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 Click-to-Call

Through Click-to-Call, you can connect two users on the call. Let's say the customer can request for a phone call from the company's executive and Solutions Infini triggers a bridge call connecting the executive and the customer. You can also bridge the call between the customer and IVR.

You can choose who the call first connects to and add that number in the "From" field. The next connecting call is initiated to the "To" number once the "From" answers the call.

Once you use Click-to-Call API, we'll connect the call between the agent and the customer through a bridge number.

Prerequisites

  • An active API Key
  • An Active DID number
  • Caller and Receiver Number

API for initiating Click-to-Call

To initiate a click to call request, the following URL format is used:


https://api-voice.kaleyra.com/v1/?api_key=A025XXXXXXXXXXXXXXXXXXXXX&method=dial.click2call&format=xml&caller=88XXXXXXXX&receiver=99XXXXXXXX

API Parameters

Parameter Name
Type
Description
Expected Value

method

Mandatory

Predefined method

dial.click2call

api_key

Mandatory

API key generated from your account

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

format

Optional

Output response format

Default text.
Supports JSON and XML.

caller

Mandatory

First leg of the call. Multiple numbers separated by “–“can be given. Call is triggered to all the numbers, when 1 person receives other calls get disconnected

10 Digit
mobile number. Single or multiple (hyphen separated)

receiver

Mandatory

Second leg of the call. Multiple number separated by ^ can be given. Call is triggered to all the numbers, when 1 person receives other calls get disconnected

10 Digit mobile number.
Single or multiple (^ separated) or IVR. Format of IVR on second leg: ivr:id (Ex: ivr:1234)

retry

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

callback

Optional

URL that needs to be triggered at first leg answer & at the end of the call, supported with replaceable variables. Ex Usage:
"&callback=http%3A%2F%2Fcallback%
2F%3Fcaller%3D{caller}"

URLencoded API URL

delay

Optional

Time delay from the API is triggered and call is initiated. Ex Usage: "&delay=X".

Time in seconds, default 0.

return

Optional

Flag to indicate if Call ID need to be returned on API response. ID is an alphanumeric value with max length 50.
Ex Usage: "&return=X".

Numeric value 1.
Default 0.

caller_id

Optional

Phone number to be used as caller ID, can be any number assigned to given account.

10 Digit number. Default first active number assigned to the account

meta

Optional

JSON metadata or additional parameters

Sample JSON

custom

Optional

Custom reference ID for call

Alpha-numeric ID

Find below the noted Example Responses for each situation:

          <?php
                       $curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api-voice.kaleyra.com/v1/?method=dial.click2call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&caller=88XXXXXXXX&receiver=99XXXXXXXX&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);
            
            	
            
            var request = require("request");
var options = { method: 'GET',
 url: 'http://api-voice.kaleyra.com/v1/',
  qs: 
   { method: 'dial.click2call',
     api_key: 'A025XXXXXXXXXXXXXXXXXXXXX',
     caller: '88XXXXXXXX',
     receiver: '99XXXXXXXX',
     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://api-voice.kaleyra.com/v1/?method=dial.click2call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&caller=88XXXXXXXX&receiver=99XXXXXXXX&format=xml")
  .get()
  .build();
Response response = client.newCall(request).execute();
            
            	
            
            var client = new RestClient("https://api-voice.kaleyra.com/v1/?method=dial.click2call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&caller=88XXXXXXXX&receiver=99XXXXXXXX&format=xml");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);
            
            	
            
            require 'uri'
require 'net/http'
url = URI("https://api-voice.kaleyra.com/v1/?method=dial.click2call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&caller=88XXXXXXXX&receiver=99XXXXXXXX&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://api-voice.kaleyra.com/v1/"
querystring = {"method":"dial.click2call","api_key":"A025XXXXXXXXXXXXXXXXXXXXX","caller":"88XXXXXXXX","receiver":"99XXXXXXXX","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://api-voice.kaleyra.com/v1/?method=dial.click2call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&caller=88XXXXXXXX&receiver=99XXXXXXXX&format=xml");

xhr.send(data);
            
            	
            
            curl --request GET \
  --url 'https://api-voice.kaleyra.com/v1/?method=dial.click2call&api_key=A025XXXXXXXXXXXXXXXXXXXXX&caller=88XXXXXXXX&receiver=99XXXXXXXX&format=xml'
            
            	
            
            {
  "status":"200",
  "message":"OK",
  "data":{
    "id":"c2c_5a7d85903dd7xxxx"
  }
}
            
            	
            
            <?xml version="1.0" encoding="UTF-8" ?>
<api>
 	<status>200</status> 
 	<message>OK</message> 
    <data> 
        <id> c2c_57XXXXXXXXXXXX</id> 
    </data> 
</api>
 
            	
            

Success Response (with ID return)

{
  "status":"200",
  "message":"OK",
  "data":{
    "id":"c2c_5a7d85903dd7xxxx"
  }
}
<?xml version="1.0" encoding="UTF-8" ?> 
<api> 
 	<status>200</status> 
 	<message>OK</message> 
    <data> 
        <id>c2c_57XXXXXXXXXXXX</id> 
    </data> 
</api>

Example Error Response

{
  "status":"E423",
  "message":"Receiver value not provided"
}
<?xml version="1.0" encoding="UTF-8" ?>
<api>
    <status>A404</status>
    <message>Your api account got suspended</message>
</api>

Response Data

Status
Message

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

It indicates the success or failure message.

Callback & Replaceable Variables

Callback is a functionality to get notified through an API call when a call is answered and completed. One needs to follow below steps to achieve valid callback.

1.Define sample callback API with sample values.


https://callback-dot-
com/callback/?from=9988xxxx&to=9877xxxx&duration=10&status=ANSWER
  1. Carefully find and replace values with respective variables. Note that all the replaced values shall be in URL encoded format only

https://callback-dot-
com/callback/?from={caller}&to={receiver}&duration={duration}&status={status1}
  1. Append callback value with Click2Call API.

&callback=http%3A%2F%2Fcallback-dot-
com%2Fcallback%2F%3Ffrom%3D%7Bcaller%7D%26to%3D%7Breceiver%7D%26duration%3D%7Bduration%7D%26status%3D%7Bstatus1%7D

List of variables supported over callback API

The following are the variables that are supported over a callback API.

Parameter
Description

{caller}

Caller (first leg) number

{receiver}

Receiver (second leg) number

{starttime}

Call start time EPOCH format

{endtime}

Call end time EPOCH format

{duration}

Call duration in seconds for caller (first leg)

{billsec}

Call duration in seconds for receiver (second leg)

{status}

Consolidate status for C2C outcome

{status1}

Call status for caller (first leg)

{status2}

Call status for receiver (second leg)

{recordpath}

Recording file URL

{callerid}

Caller ID used to dial

Expected Call Status values

The following table states the expected status values of the API:

{Status}
{Status1}
{Status2}

ANSWER

ANSWER

ANSWER

FAILED_LEG1

BUSY

BUSY

CANCEL

CANCEL

CANCEL

FAILED_LEG2

CONGESTION

CONGESTION

CONGESTION_LEG2

NOANSWER

NOANSWER

NOANSWER_LEG1

FAILED

FAILED

BUSY_LEG2

NOANSWER_LEG2

CONGESTION_LEG1

BUSY_LEG1