VOICE API
Personalized Calls
Overview
Go4clients bases its functionality on campaigns. A campaign is a set of events (Calls, SMS, Landing pages, and many more) with the same characteristics that allows your organization to categorize your customers according to your needs and contact them evenly. Each petition to this API will add a new Call to previously created campaign. You can find the interactions that your customers have with it in the “OTP analytics” section. This API allows you to send a personalized Call at the time no matter what programming language your organization uses since Go4clients APIs use standard REST services that are easily integrated with any application. You can use this API when you need to send a personalized Call to a single destination.
To use this service you will have to create an On Demand Voice Campaign (OTP Campaign) and then add calls to it. You can also terminate this campaign to stop adding events to it.
AUTHENTICATION
All requests require API Key and API Secret authentication credentials. Your Account Administrator can modify this information under “My Profile > Settings > API” section. The security information goes in the POST Headers:
The account’s Api key username (key), a 32 character random generated string.
The account’s API password (secret). It’s a numeric random string with a random length between 10 and 15 characters.
1 | "Apisecret" : "712968662797" |
Please be advised that the header also have to include a parameter “Content-Type” with value “applica-tion/json”.
1. On Demand Voice Campaign Creation
To start sending calls to your customers you need to create a campaign previously. This campaign will help you to organize and group your calls, reports and statistics.
1.1 HTTP Methods
You need to call a POST HTTP for creating a new OTP campaign. The following URLs are used to publish the massive voice service:
HTTPS (Recommended):
HTTP (non-SSL):
1 | http://go4clients.com:3011/TelintelSms/apiotp/voice/createcampaign |
The following HTTP request will create an On Demand voice Campaign with all its details:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | POST /TelintelSms/apiotp/voice/createcampaign HTTP/1.1 Host: go4clients.com Apikey: 65d1f3bb09ec4499552eaa5607d5b3320e7 Apisecret: 38492511442666 Content-Type: application/json { "name":"OTP Demo campaign", "description":"OTP Campaign description", "voice":"DOUGLAS", "callerId":"130500000", "endDate":"2017-08-03 15:55", "repetitionKey":"1" } |
1.2. REQUEST PARAMETERS
The OTP campaign name.
The description of the OTP campaign.
The voice to convert the text to audio for the calls in this campaign. The available voices are in Annex C: Available Voices.
The Caller ID number from the campaign originates. The Caller ID number can be any number entered by the user that calls the service, and must have a max length of 15 numeric characters. e.g.: 123456789012345.
The capacity to dispatch calls for this campaign.
This key is used if you want to create an IVR with the repeat audio option. The value must be only one digit from 0 to 9.
The end date of the campaign. The date format is ‘YYYY-MM-DD HH:MM’, example: 2016-08-03 15:55.
1.3. Response Parameters
For information about the error codes of the voice api, please see the Annex A: OTP Api Response Codes Table
Long
ID of the OTP campaign created.
String
Code that identifies the response. See Annex A: OTP Api Response Codes Table
Boolean
Indicates if the service response is successful or not.
String
Brief description of the process or errors.
Unique campaign id of the campaign created.
2. Add Calls to campaign
2.1 HTTP Methods
2.1.1 Custom Calls
This HTTP service allows adding a call to an OTP campaign as well as specifying the call structure. Mainly, you must to create an OTP campaign and get its “otpCampaignId”.
HTTPS (Recommmended)
HTTP (non-SSL)
1 | http://go4clients.com:3011/TelintelSms/apiotpV2/voice/addcall |
The following HTTP request will generate a call with destination “mobileNumber“, add it to the existing campaign “otpCampaignId” and will execute the “callSteps” to your customer:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 | POST /TelintelSms/apiotpV2/voice/addcall HTTP/1.1 Host: go4clients.com Apikey: 65d5555509ec4492b2e5607d5b3320e7 Apisecret: 355555112020 Content-Type: application/json { "otpCampaignId": 142, "mobileNumber": "573002234608", "priority": "HIGH", "callSteps": [{ "type": "SAY", "text": "Hello, please press 1 to communicate with sales or 2 if you want to repeat this menu", "convertVoice": "DORIS", "sourceType": "STANDARD" }, { "type": "DETECT", "options": [{ "type": "OPTION", "dtfmCommand": "1", "optionId": "sales", "steps": [{ "type": "SAY", "text": "Welcome to the sales area", "convertVoice": "DORIS", "sourceType": "STANDARD" }, { "destination": "17868716544", "type": "DIAL" } ] }, { "type": "OPTION", "dtfmCommand": "2", "optionId": "Repeat the audio above", "steps": [{ "type": "REPEAT_AUDIO" }] } ] } ] } |
2.1.2 REQUEST PARAMETERS
The ID of the OTP campaign asociated with this call.
The destination number to send this call.
Steps tree to be executed to the customer. Please see the Annex D: Step types and how to use them Annex
The priority assigned to the call. It could be HIGH or LOW.
2.1.3 Response Parameters
For information about the error codes of the voice API, please see the Annex A: OTP Api Response Codes Table
Code that identifies the response in the Annex A: OTP Api Response Codes Table.
Indicates if the service response is successful or not.
Brief description of the process or errors.
2.2 Text2Speach calls
When creating a new campaign the API will return the campaign id. In order to create a call you need to send this information. You need to call a POST HTTP for adding a call to an existing OTP campaign. The following URLs are used to publish the massive voice service:
HTTPS (Recommmended)
HTTP (non-SSL)
1 | http://go4clients.com:3011/TelintelSms/apiotp/voice/addcall |
The following HTTP request will generate a call with destination “mobileNumber“, add it to the existing campaign “otpCampaignId” and will convert the “message” into an audio and play it to your customer.
2.2.1 REQUEST PARAMETERS
Code that identifies the response in the Annex A: OTP Api Response Codes Table.
Indicates if the service response is successful or not.
Brief description of the process or errors.
3. Campaign Termination
Additionally you can terminate an existing campaign. This action will reject any further event and will change the campaign status.
3.1 HTTP Methods
HTTPS (Recommended)
HTTP (non-SSL)
1 | http://go4clients.com:3011/TelintelSms/apiotp/voice/finishcampaign |
The following HTTP request will terminate the campaign with id “otpCampaignId“.
3.2 Request parameters
The ID of the OTP campaign that will be completed.
3.3 Response Parameters
For information about the error codes of the voice api, please see the Annex A: OTP Api Response Codes Table
Code that identifies the error in the Annex A: OTP Api Response Codes Table.
Indicates if the service response is successful or not.
Brief description of the process or errors.