The Developer Hub

Welcome to the Developer Documentation Hub. You'll find comprehensive guides and documentation to help you start working with SMS,Voice, 2FA, VMN, SMPP and Outbound Dialing Documentation as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Start a OBD/Outbound Call

What can do with this API?

Through this API, you can initiate an outbound call to a single number, multiple numbers or already created groups. To initiate an outbound call request, the following URL format is used:


https://obd.kaleyra.com/api/v1/?api_key=A025XXXXXXXXXXXXXXXXXXXXX&method=voice.call&format=xml&numbers=88XXXXXXXX&play=123.sound

Prerequisites

  • An API Key
  • Numbers to who the call has to be initiated
  • A predefined IVR flow/ Valid sound file

API Parameters

Parameter Name
Type
Description
Expected Value

method

Mandatory

Predefined method

voice.call

api_key

Mandatory

API key generated from your account

Alphanumeric key from your account. Can be configured to validate source IP.

format

Optional

Output response format

Default text. Supports JSON, JSONP, XML and PHP.

numbers

Mandatory

Number(s) for generating OBD call. Multiple numbers separated by ",".

10 Digit phone number. Single or multiple(comma separated)

group

Optional

Contact group ID or group name from where number has to be picked. If given, overrides numbers parameter (above).

Numeric Group ID(comma separated for multiple) or Group Name (single)

play

Mandatory

Valid sound file reference OR an IVR created in given account.

Sound file ID. (Ex: 123.sound)

Format of IVR on second leg: ivr:id (Ex: ivr:1234 or 1234.ivr)

message

Optional

Message in text format (English only) to be verbalized over outbound call. Play configuration (above) takes the priority over message.

URL encoded text, English only.

retries

Optional

Number of retry to be made if caller(First Leg) doesn't answer the call. Ex Usage: "&retry=X".

Numeric value, default 0 (max 2).

campaign

Optional

Campaign name five given API call.

URL encoded text

newgroup

Optional

Option to enable separate group listing for every API call over application. Default option combines the similar API calls into single group.

Numeric value 1. Default 0.

scheduletime

Optional

Date time value when the call has to be scheduled. Minimum, 15 mins from current time is accepted (max upto 2 month)

EPOCH or datetime in YYYY-MM-DD HH:mm:SS or DD/MM/YYYY HH:MM AM format

delay

Optional

Numeric time delay (in seconds) to be introduced before initiating the current request

Numeric, max 900.

meta

Optional

JSON metadata or additional parameters

Sample JSON

custom

Optional

Custom reference ID for call

Alpha-numeric ID, Comma seperated for multiple numbers

callback

Optional

Callback URL to be triggered at the end of the call

                      
     <?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://obd.kaleyra.com/api/v1/?method=voice.call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&numbers=88XXXXXXXX&play=123.sound&format=xml",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

            	
            
            var request = require("request");

var options = { method: 'GET',
  url: 'https://obd.kaleyra.com/api/v1/',
  qs: 
   { method: 'voice.call',
     api_key: 'A025XXXXXXXXXXXXXXXXXXXXX',
     numbers: '88XXXXXXXX',
     play: '123.sound',
     format: 'xml' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
 
            	
            
            OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://obd.kaleyra.com/api/v1/?method=voice.call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&numbers=88XXXXXXXX&play=123.sound&format=xml")
  .get()
  .build();

Response response = client.newCall(request).execute();

            	
            
            var client = new RestClient("https://obd.kaleyra.com/api/v1/?method=voice.call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&numbers=88XXXXXXXX&play=123.sound&format=xml");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
            
            	
            
            require 'uri'
require 'net/http'

url = URI("https://obd.kaleyra.com/api/v1/?method=voice.call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&numbers=88XXXXXXXX&play=123.sound&format=xml")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
            
            	
            
            import requests

url = "https://obd.kaleyra.com/api/v1/"

querystring = {"method":"voice.call","api_key":"A025XXXXXXXXXXXXXXXXXXXXX","numbers":"88XXXXXXXX","play":"123.sound","format":"xml"}

response = requests.request("GET", url, params=querystring)

print(response.text)
            
            	
            
            var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://obd.kaleyra.com/api/v1/?method=voice.call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&numbers=88XXXXXXXX&play=123.sound&format=xml");

xhr.send(data);
            
            	
            
            curl --request GET \
  --url 'https://obd.kaleyra.com/api/v1/?method=voice.call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&numbers=88XXXXXXXX&play=123.sound&format=xml'
            
            	
            
            {

  "status": "200",

  "message": "OK",

}

            	
            
            <?xml version="1.0" encoding="UTF-8" ?>
<api>
    <status>200</status>
    <message>OK</message>
</api>
 
            	
            
            Array
(
[status] => 200
[message] => OK
)
            	
            
            	
            

Error Response

<?xml version="1.0" encoding="UTF-8" ?>
<api>
    <status>A404</status>
    <message>Your api account got suspended</message>
</api>

Response Data

Response
Description

status

It indicates the success or failure of your request. 200 is success, others are failure

message

It indicates the success or failure message.