VOICE API

Operations over voice campaigns

As the campaign creator, you have total control of its execution through operations like start, stop or cancel. All this is possible submitting PUT requests to the following URLs:

Start campaign

1
PUT https://go4clients.com/TelintelSms/api/voice/campaigns/{uniqueCampaignId}/start

Note: if the campaign with the detailed unique id doesn’t exists, a error with the code VOICE-ERR-43 will arrive, indicating that the campaign must have “FAILED” or “PAUSED” status to execute the start operation.

Stop campaign

1
PUT https://go4clients.com/TelintelSms/api/voice/campaigns/{uniqueCampaignId}/stop

Cancel campaign

1
PUT https://go4clients.com/TelintelSms/api/voice/campaigns/{uniqueCampaignId}/cancel

Use example (using start operation, for the others is the same):

1
2
curl -ik -X PUT -H "Apikey: 70ea87b330fe4b82a9aee902fac05d23" -H "Apisecret: 8908028582"
https://go4clients.com/TelintelSms/api/voice/campaigns/e8dca66b-95cf-4c2b-aef7-80ec14532dd9/stop

Get campaign information

Where the uniqueCampaignId path parameter is the returned string when the campaign was created. This parameter can be used to get information about the campaign through the Campaign Info service; you can call it through the following GET service:

1
GET https://go4clients.com/TelintelSms/api/voice/campaigninfo?uniqueCampaignID={uniqueCampaignId}&start={start}&limit={limit}

Request example:

1
2
curl -ik -X GET -H "Apikey: 70ea87b330fe4b82a9aee902fac05d23" -H "Apisecret: 8908028582"
https://go4clients.com/TelintelSms/api/voice/campaigninfo?uniqueCampaignID=e8dca66b-95cf-4c2b-aef7-80ec14532dd9&start=0&limit=2

The parameters start and limit are used as paging parameters. i.e.

Start: 0 and Limit: 500 It will return the first 500 rows.

Start: 500 and Limit: 500 It will return rows from 500 to 1000.

Start: 1000 and Limit: 500 It will return rows from 1000 to 1500.

By default, start will be 0 and limit will be 500. The Campaign Info service returns a JSON with the following structure:

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
{
  "code": "VOICE-SUC-07",
  "description": "The campaign was found sucessfully",
  "success": true,
  "campaignName": "Test Campaign",
  "campaignCost": "500.95",
  "campaignConfig": {
    "callerId": "123456",
    "minTime": "08:00",
    "maxTime": "22:00",
    "dialCounts": "3",
    "timeBetweenCalls": "30",
    "nextDayContinue": true,
    "voice": "PEDRO",
    "personalizedText": "Test words for campaign",
    "capacity": 500
  },
  "callDetails": [
    {
      "mobileNumber": "1234567890",
      "name": "John",
      "lastName": "Doe",
      "duration": 60,
      "status": "SUCCESS_FINISHED"
    },
    {
      "mobileNumber": "112233445566",
      "name": "Jannine",
      "lastName": "Doe",
      "duration": 35,
      "status": "CALL_FAILED"
    }
  ]
}

You can found the detailed structure of the JSON in the following table:

Structure of the JSON
code
String

Code that identifies the error in the Voice Api Error Table.

description
String

Brief description of the error.

success
Boolean

Indicates if the service response is successful or not.

campaignName
String

Name assigned to the campaign.

campaignCost
Double

Calculated cost of the campaign.

campaignConfig
Object

All the configuration info of the campaign, like call and time parametrization.

List of objects
String

Details of each call in the campaign.

Voice campaign configuration object structure

Voice campaign configuration object structure
callerId
String

The number that appears as the caller in the mobile destinations.

minTime
String

Low time limit where the campaign launches calls to the destinations, in 24 hours format e.g. 08:00.

maxTime
String

Max time limit where the campaign launches calls to the destinations, in 24 hours format e.g. 22:00.

dialCounts
Integer

NRetries to a call destination, where it fails.

timeBetweenDials
Integer

Time in minutes where each retry for a specific call destination is executed.

nextDayContinue
Boolean

Define if the campaign continue with its execution in the next day, or it must finalize and omit all the remaining calls.

voice
Boolean

All the audios in the campaign will be played with the selected voice. In some cases (e.g. the API created campaigns) this voice is setted as UNKNOWN.

personalizedText
String

Set a text and the campaign will only plays its content.

capacity
String

Max concurrent calls in execution for the campaign.

Call Detail object structure

Request Parameters
mobileNumber
String

Mobile destination of the call.

name
String

First name of the destination person.

lastName
String

Last name of the destination person.

duration
Integer

Duration of the call. It could be zero if the call hasn’t be executed.

status
Integer

Status of the call, it consider the following values:

  • PROGRAMMED
  • IN_PROGRESS
  • NO_ANSWER
  • FINISHED
  • SUCCESS_FINISHED
  • NO_ENOUGH_BALANCE
  • CALL_FAILED
  • NO_RATES_FOUND