VOICE API

Massive Voice Campaign
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 create a new campaign for your organization. You can find the interactions that your customers have with it in the “Robocall analytics” section.

The voice API helps you to create massive campaigns no matter what programming language your organization uses since Go4clients APIs use standard REST services that are easily integrated with any application.

1. HTTP Methods

To send a massive voice campaign you need to call a POST HTTP . The following URLs are used to publish the outbound calls service:

HTTPS (Recommended)

1
https://go4clients.com:8443/TelintelSms/api/voice/outcall

HTTP (non-SSL)

1
http://go4clients.com:3011/TelintelSms/api/voice/outcall

The following HTTP request will create a new campaign and send the call structure inside “callSteps” to all the numbers inside the “toList” using the caller id: “from“.

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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
POST /TelintelSms/api/voice/outcall HTTP/1.1
Host: go4clients.com
Content-Type: application/json
Apikey: 60b71c485976433999654501a93098a6
Apisecret: 1166368856664
 
{
  "from": "12345",
  "toList": [
    "573000000000"
  ],
  "callSteps": [
    {
      "type": "SAY",
      "text": "Hello, please press 1 to communicate with sales, 2 to communicate with technical support, or 3 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": "19431843765",
              "type": "DIAL"
            }
          ]
        },
        {
          "type": "OPTION",
          "dtfmCommand": "2",
          "optionId": "technical support",
          "steps": [
            {
              "type": "SAY",
              "text": "Welcome to the technical support area",
              "convertVoice": "DORIS",
              "sourceType": "STANDARD"
            },
            {
              "destination": "19431843765",
              "type": "DIAL"
            }
          ]
        },
        {
          "type": "OPTION",
          "dtfmCommand": "3",
          "optionId": "Repeat the audio above",
          "steps": [
            {
              "type": "REPEAT_AUDIO"
            }
          ]
        }
      ]
    }
  ]
}

2. Authentication

All requests require API Key and API Secret authentication credentials. Your Account Administrator can 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.

1
Apisecret : 712968662797

 Please be advised that the header also have to include a parameter “Content-Type” with value “application/json”.

3. Request Parameters

Request Parameters
from
String (Required)

Caller Id that the your customers will see when picking up the call. 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. However it’s recommended to use a valid mobile number.

toList
String (1…*) (Required)

The list of recipients for this massive campaign. Each destination number must be in international format (country code) + (mobile number) and can only contain digits Example: 573004445566 when sending to the Colombia.

callSteps
String (1…*) (Required)

It has the call structure that the recipients will interact with. Please see the  Annex D: Step types and how to use them

PHP example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
<?php
 
$url = 'https://go4clients.com:8443/TelintelSms/api/voice/outcall';
$data ='{SOME JSON...TO SIMPLIFY}';
// use key 'http' even if you send the request to https://...
$options = array(
    'http' => array(
        'header'  => "Content-type: application/json\r\n".
            "Apikey: [YOUR_API_KEY]\r\n".
            "Apisecret: [YOUR_API_SECRET]\r\n",
        'method'  => 'POST',
        'content' => $data
    ),
);
$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
var_dump($result);
 
?>

Java example (with Apache HTTPClient)

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
try{
 
    String url = “https://go4clients.com:8443/TelintelSms/api/voice/outcall";
    
    HttpClient httpClient = HttpClientBuilder.create().build();;
    HttpPost postRequest = new HttpPost(url);
            
    postRequest.addHeader("Content-type", "application/json");
    postRequest.addHeader("Apikey", "[YOUR_API_KEY]");
    postRequest.addHeader("Apisecret", "[YOUR_API_SECRET]");
            
    ObjectMapper objMap = new ObjectMapper();
 
    String json = objMap.writeValueAsString(request);
            
    HttpResponse response = httpClient.execute(postRequest);
            
Response response = objMap.readValue(response.getEntity(), Response.class);
            
}catch(Exception e){
    //Capture the possible exceptions
}finally{
    if(postRequest != null){
        postRequest.releaseConnection();
    }
}

4. Response Parameters

For information about the error codes of the voice api, please see the Annex B: Voice Api Error Table

Response Parameters
code
String

Code that identifies the error in the Voice Api Error Table

description
String

Brief description of the error.

success
Boolean

It indicates if the service response is successful or not

requestResponseDescription
String

Unique identificator for the created voice campaign