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:

Parameters
Apikey
String (Required)

The account’s Api key username (key), a 32 character random generated string.

1
"Apikey": "5bf54d157a214f748eede4e4131b874d"
Apisecret
String (Required)

The account’s API password (secret). It’s a numeric random string with a random length between 10 and 15 characters.

Example
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):

1
https://go4clients.com/TelintelSms/apiotp/voice/createcampaign

HTTP (non-SSL):

Java
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

Request Parameters
name
String (Required)

The OTP campaign name.

description
String

The description of the OTP campaign.

voice
String (1…*) (Required)

The voice to convert the text to audio for the calls in this campaign. The available voices are in Annex C: Available Voices.

callerId
String (Required)

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.

campaignCapacity
Integer (Required)

The capacity to dispatch calls for this campaign.

repetitionKey
Integer

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.

endDate
String

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

1
2
3
4
5
6
7
{
    "code": "OTP-SUC-001",
    "description": "The OTP campaign was saved sucessfully",
    "success": true,
    "otpCampaignId": 535,
    "uniqueCampaignID": "da0e6b0e-1054-4eec-8309-655444163297"
}
Request Parameters
otpCampaignId

Long
ID of the OTP campaign created.

code

String
Code that identifies the response. See Annex A: OTP Api Response Codes Table

success

Boolean
Indicates if the service response is successful or not.

description

String
Brief description of the process or errors.

uniqueCampaignID

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)

1
https://go4clients.com/TelintelSms/apiotpV2/voice/addcall

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

Request Parameters
otpCampaignId
Long (Required)

The ID of the OTP campaign asociated with this call.

mobileNumber
String (Required)

The destination number to send this call.

callSteps
JSON (Required)

Steps tree to be executed to the customer. Please see the Annex D: Step types and how to use them Annex

priority
JSON (Required)

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

Response Parameters
code
String

Code that identifies the response in the Annex A: OTP Api Response Codes Table.

success
Boolean

Indicates if the service response is successful or not.

description
String

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)

1
https://go4clients.com/TelintelSms/apiotp/voice/addcall

HTTP (non-SSL)

Java
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.

1
2
3
4
5
6
7
8
9
10
11
POST /TelintelSms/apiotp/voice/addcall HTTP/1.1
Host: go4clients.com
Apikey: 65d1f3bb09ec4492b2e5607d5b3320e7
Apisecret: 384925112020
Content-Type: application/json
 
{
    "otpCampaignId":100,
    "mobileNumber":"57300000000",
    "message":"Welcome to the Go4Clients on demand voice API."
}

2.2.1 REQUEST PARAMETERS

Response Parameters
otpCampaignId
Long

Code that identifies the response in the Annex A: OTP Api Response Codes Table.

mobileNumber
Boolean

Indicates if the service response is successful or not.

message
String

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)

1
https://go4clients.com/TelintelSms/apiotp/voice/finishcampaign

HTTP (non-SSL)

Java
1
http://go4clients.com:3011/TelintelSms/apiotp/voice/finishcampaign

The following HTTP request will terminate the campaign with id “otpCampaignId“.

1
2
3
4
5
6
7
8
9
POST /TelintelSms/apiotp/voice/finishcampaign HTTP/1.1
Host: go4clients.com
Apikey: fc382d6990464dGBGF958d767dc0b61666b7
Apisecret: 608169195823
Content-Type: application/json
 
{
    "otpCampaignId":6
}

3.2 Request parameters

Response Parameters
otpCampaignId
Long (Required)

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

Response Parameters
code
Long

Code that identifies the error in the Annex A: OTP Api Response Codes Table.

success
Boolean

Indicates if the service response is successful or not.

description
String

Brief description of the process or errors.