Introduction

SparkTG is a Cloud Telephony service provider. Cloud Telephony is an on-demand service to provide the robust telephony features, reliably to organisations providing products and services.

Network Access:

Capabilities are available over the network and accessed through standard mechanisms. Consumers should be able to login from anywhere and control their service.

Resource Pooling:

The telecom resources are pooled to serve multiple consumers using a multi-tenant model, with different physical and virtual resources dynamically assigned and reassigned according to consumer demand. This reduces consumer’s cost of developing in-house telephony service and they pay only for the resource they use.

Elasticity:

Telephony Ports can be rapidly and elastically provisioned, in some cases automatically, to quickly scale out and rapidly released to quickly scale in.

Measured Service:

Cloud system automatically control and optimize resource use by leveraging a metering capability at some level of abstraction appropriate to the type of service (e.g., number of inbound calls, number of outbound calls, and number of spam calls). Resource usage can be monitored, controlled, and reported providing transparency for both the provider and consumer of the utilized service. With these objectives in perspective, Spark TG is introducing APIs for most of its services for customer to easily test and integrate them with their applications (web or desktop or mobile).

Assumptions

This document is intended for the developers and requires basic knowledge of Spark TG Cloud Telephony platform. Spark TG will need to provision API service in advance for each customer before they can use it in their applications.

Supplying Basic Auth Headers:

We have REST based API’s in which we use basic authentication. You have to send basic auth headers yourself. To do this you have to pass a string of the form username:password.

Make Call

curl -X POST -d "number=999XXXX999" -u "username:password" https://telephonycloud.co.in/api/v1/calls
Parameter Name Type Sample Comments Mandatory
number String 999XXXX999 Number of customer to whom the call is to made Yes
service-id Integer 123 Id of the service No
app-id String 999999 Required only for special/customized API, given by SparkTG in such case No
agent-sip String 1012318 Required if want to make call to a specific agent via SIP, requires admin credentials No
agent-number String 999XXXX999 Required if want to make call to a specific agent via number of the agent, requires admin credentials No
Response : {"id":"9999xxx9-xx99-9999-99xx-x999xxx999x"}

Agent Detail

curl -u "username:password" https://telephonycloud.co.in/api/v1/agents
No parameters required : If provided credentials of user which have admin rights then all the agents of that service

will be shared else only the agent of whom credentials will be passed in API

Response : [{"id":3243,"number":"9999XXXXX9","number1":"","name":"ABC","status":0,"sip":"101504","time":1522918018275,

"active":true,"country_code":"91","svc_id":15,"user_id":3638,"call_txn_id":"9999999-999x-9999-9999-xx00999xxx,xxxxx99xx-9xxx-99xx-9x99-9999x9x9999,0000xxxx-99xx-99xx-9999-9999083a7xxxx","bind_count":0}]

Agent Login Logout

curl -X PATCH -u "username:password" https://telephonycloud.co.in/api/v1/agents?status=0
Parameter Name Type Sample Comments Mandatory
status Integer 0 Status number resembles which type of status is desired. See table Status below Yes
break Integer 0 Break id resembles that which type of break is taken against the status. See table Break below No
agent-number String 999XXXX999 Number of the agent of which status to be updated, useful in case of admin credentials, can change status of agent via agent’s number No
Response : {"break":-1,"status":0}

Status Table

Status code
Status
0 Login
2 Logout

Break Table

Break code
Break
0 Login
1 Lunch Break
2 Tea Break
3 Rest Room Break
4 Huddle
5 Training
6 Nature Break
7 Logout

Change Number

curl -X PATCH -u "username:password" https://telephonycloud.co.in/api/v1/agents?number=999XXXX999
Parameter Name Type Sample Comments Mandatory
number String 999XXXX999 Desired updated number for agent Yes
agent-number String 999XXXX999 Number of the agent of which status to be updated, useful in case of admin credentials, can change status of agent via agent’s number No
Response : {"number":"9999XXXXX9"}

Available Agent

curl -u "username:password" https://telephonycloud.co.in/api/v1/agents-free
Based on the provided credentials, available/free agents will be provided of the assigned service id.
Response : {"name":"ABC","id":3243}

Send Signal

curl -X POST -u "username:password" https://telephonycloud.co.in/api/v1/calls/{call-txn-id}
Parameter Name Type Sample Comments Mandatory
signal String hangup To hangup a call, set value as hangup Yes
Response : true

Send SMS

curl -X POST -u "username:password" https://telephonycloud.co.in/api/v1/send-sms
Parameter Name Type Sample Comments Mandatory
number String 999XXXX999 Number on which SMS is to be sent Yes
message String Hi, This is test message Desired message Yes
service-id Integer 123 Id of the service Yes
country-code String 91 Country Code of the number on which SMS is to be sent No
call-txn-id String 99xx99xx-9999-99x9-9x9x-99xx9999x9x9 Call Txn Id of the call, if there any No
tries Integer 2 How many times a SMS should be tried on a number No
Response : xxx999xxx-9999-9999-99xx-9999x999x9xxx99

Send OTP

curl -u "username:password" https://telephonycloud.co.in/api/v1/otp?number=999XXXX999
Parameter Name Type Sample Comments Mandatory
number String 999XXXX999 Number on which OTP is to be sent Yes
keyword String Click2Call Represents for which purpose the OTP is sent, default value : Click2Call No
service-id Integer 123 Id of the service No
Response : 8330

Validate OTP

curl -X POST -d "number=999XXXX999" -u "username:password" https://telephonycloud.co.in/api/v1/otp?otp=9999
Parameter Name Type Sample Comments Mandatory
number String 999XXXX999 Number on which OTP was sent / to be validated Yes
otp String 9999 OTP which is to be validated Yes
Response : true

Click2Call

curl -X POST -d "number=999XXXX999" -d "service-id=123" -u "username:password" https://telephonycloud.co.in/api/v1/click2call?otp=9999
Parameter Name Type Sample Comments Mandatory
number String 999XXXX999 Number on which call is to be made Yes
otp String 9999 OTP which was sent on the number Yes
service-id Integer 123 Id of the service Yes
country-code String 91 Country code of the number, on which click2call is made No
Response : {"isError":false,"callTxnId":"99999999-9999-9x99-x9x9-x9x9x9"}

Webhook

Name
Type
Sample
Comments
callid String 999x9999-x999-9x99-x999-x9x99x9999xx call transaction id
call-duration String 30 call duration in seconds
agent-number String 999XXXX999 agent number
customer-number String 999XXXX999 customer number
end-time String 2016-06- 27 15:23:28 end time of call
start-time String 2016-06- 27 15:23:58 start time of call
recording-url String http://telephonycloud.co.in/recordings/123/160327/999x9999-x999- 9x99-x999-x9x99x9999x9.wav url of call recording(if call was answered)
call-type String outgoing incoming/outgoing
virtual-number String 999XXXX999 called number
disposition String answered Disposition of the call answered / missed