Kirusa Konnect

Overview

This enables you to execute SMS campaigns (outbound or inbound) by invoking a Konnect REST API or a set of APIs. The following sections provide details on the same.

Base URI

https://konnect.kirusa.com/api/v1/Accounts/{account_id}/

Authentication and Authorization

The Konnect APIs make use of authentication as follows

The Konnect account_id value is set in the URL
The Konnect api_token is passed in the Authorization header

The account_id and api_token are available on the Account Dashboard once the user logs in to the Konnect portal ( https://konnect.kirusa.com/ ).

Outbound Messaging

Overview

Allows user to execute SMS campaigns through the Konnect platform using an API.

Features

Enterprise user can send SMS to a single recipient or a list of recipients
He will be notified of the SMS delivery status via a callback URL
Track each SMS sent on a real-time report in the Konnect portal. The reporting analytics will include:
- From and To numbers
- Time stamp of when SMS was sent, submitted and delivered
- Body of the message

Method

POST/GET

URL Structure

For POST: https://konnect.kirusa.com/api/v1/Accounts/{account_id}/Messages

For GET : https://konnect.kirusa.com/api/v1/Accounts/{account_id}/Messages?id={id}&to={to}&from={from}&body={body}&sender_mask={sender_mask}&callback_url={callback_url}&track_url={track_url}&expiry={expiry}&priority={priority}&url_to_track={url_to_track}

Request Parameters

The following table lists the parameters required for SMS API.

Field	Type	Mandatory	Description
id	String	Yes	Unique transaction id for the request
to	String	Yes	The destination phone number, multiple phone numbers should be passed as a JSON array separated by comma.
from	String	No	The sender phone number. If not specified, the default sender id is used.
direction	String	No	The direction of the message, it can be ‘inbound’, ‘outbound’ or ‘2way’. If values is not specified then ‘outbound’ is set as default.
sender_mask	String	No	The string to mask the sender.
body	String	Yes	The full text of the message
expiry	Integer	No	The message expiry in seconds. E.g. if the message is valid for 5 minutes then the value needs to be set as 300.
priority	String	No	Defines the priority of message delivery, the value can be set to ‘normal’ or ‘high’. The message with ‘high’ priority is charged at premium rate than ‘normal’ priority messages. If this parameter is not set, the default priority will be ‘normal’.
callback_url	String	No	The URL where status of message is notified, the fields passed in the response is covered in table given below. The callback notification is provided for each SMS sent.
track_url	Boolean	No	Flag to turn on tracking of URL clicks in case URL is present in the SMS content. The actual URL is changed to track the click.
url_to_track	String	No	URL that is to be tracked. This URL should be present in the actual SMS content also.
Note: Sender mask needs to be selected by the user from the Konnect user interface. The selection goes through an approval process by the Kirusa country manager. If the sender mask is not selected, then the default sender mask is used. There is a default sender mask for every Carrier.

Sample JSON request body for sending an SMS

{
  "id": "A10579090909090",
  "to": ["919886038842”,”919886038843”],
  "from": "919886000085",
  "body": "Welcome to Konnect !",
  “callback_url”: “http://myapp.com/notify”
}

Response

The sample response when the request is submitted successfully is as follows

{
  "status":"ok"
}

The sample response when the submitted request fails due to low balance is as follows

{
  "status":"error",
  “error_code”:”3003”,
  “error_reason”:”Low Balance”
}

The sample JSON response for the above request is notified asynchronously in the callback_url as follows

{
  “id”:” A10579090909090”,
  "status":"accepted",
  "ref_ids": [{“phone_number”:” 919886038842”,”ref_id”:"AC5ef8732a3c49700934481addd5ce1659”},{“phone_number”:” 919886038843”,”ref_id”:”BD6ef8732a3c49700934481addd5ce16560”}]
}

If the SMS body includes an URL, then the URL click information is notified asynchronously to the user in the callback_url as follows

{
"id" : "A10579090909090",
"ref_id" : "AC5ef8732a3c49700934481addd5ce1659",
"to" : "919886038842",
"url_access_time" : "May 9, 2019 5:33:30 PM IST"
}

Response Parameters passed in the Callback URL

Field	Type	Mandatory	Description
ref_id	String	Yes	Unique reference generated by Konnect Platform.
status	String	Yes	The status can be any of the following:- rejected, sent, failed, delivered and undelivered. In case of MO SMS it is set as received
to	String	No	The phone number to which the message was sent.
from	String	No	The phone number from which the message originated.
price	String	No	The amount billed for the message
balance	String	No	The amount remaining in the account
body	String	No	This is only applicable when the text is received from MO SMS.
error_code	String	Yes	The error code is set when the status is either failed; rejected or undelivered else it is blank.
error_reason	String	Yes	The error reason is set when the status is either failed; rejected or undelivered else it is blank.
timestamp	String	Yes	The start time of this event/status
event_timestamp	String	Yes	The end time of this event, in case of delivery it is the delivery time
url_access_time	String	No	The time at which the URL in the SMS body is clicked

The values of the status, error_code and error_reason fields are in the API documentation.

Inbound Messaging

Overview

Allows user to configure a phone number for receiving SMS on Konnect platform using an API

Features

You can use this API effectively to generate leads, build contest voting campaigns or even create polls.
For each SMS received, the enterprise will be notified via the callback URL
Body of each SMS and the timestamp at which the SMS is received in Konnect will be available as part of Konnect analytics

Create an Inbound Phone number

Method

POST/GET

URL Structure

Request Parameters

Field	Type	Mandatory	Description
id	String	Yes	Unique transaction id for the request.
phone_number	String	Yes	The phone number to be configured for receiving incoming SMS. The phone number to be configured should be purchased from the Konnect Portal.
callback_url	String	No	The URL where status of inbound phone number configuration as well as any incoming SMS text is notified.

The sample request looks as follows

{
  "id": "A10579090909090",
  "phone_number": "919886038842",
  “callback_url”: “http://myapp.com/notify”
}

Response

The sample success response looks as follows

{
  "status":"accepted",
  "ref_id": "AC5ef8732a3c49700934481addd5ce1659"
}

In case of error response looks as follows

{

  "status":"rejected",
  "ref_id": "AC5ef8732a3c49700934481addd5ce1659",
  "error_code": “3050”,
  “error_reason”:”Invalid Parameter Value”
}

Response Parameters passed in the Callback URL

Field	Type	Mandatory	Description
ref_id	String	Yes	Unique reference generated by Konnect Platform.
status	String	Yes	The status is set to either “done”, “received” or “failed”.
body	String	No	This is only applicable when the text is received from MO SMS. The status for such cases is set to “received”.
error_code	String	Yes	The error_code is set to blank when the status is set to “done”. Please refer the table below for error_code.
error_reason	String	Yes	The error reason is blank if the status is “done” or “received”
timestamp	String	Yes	The start time of this event/status
event_timestamp	String	Yes	The end time of this event, in case of delivery it is the delivery time

The values of the status, error_code and error_reason fields are in the API documentation.

Deleting an Inbound Phone number

Method

DELETE

URL Structure

https://konnect.kirusa.com/api/v1/Accounts/{account_id}/InboundPhoneNumbers/{inbound_phone_number}

Response

The response is similar to creating an inbound phone number.

Get User Balance

Overview

Allows user to request for his current account balance via an API.

Method

GET

URL Structure

https://konnect.kirusa.com/api/v1/Accounts/{accountId}/Balance

Response

The sample JSON response for the GET request is as follows:

{
 "mode":"paid",
 "account_balance":"Rs.4,801",
 "name":"Abhirup",
 "status":"ok"
}

Response Parameters

The following table lists the parameters in the response:

Field	Type	Description
mode	String	Trial account or Paid account
account_balance	String	Account balance of the user
name	String	Display name of the user

Please click here for Complete API Reference.

Send an outgoing SMS using Konnect’s REST API Copy

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Messages",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => "{\r\"id\":\"your_unique_id_for_request\",\r\"from\":\"91888200XXXX\",\r\"to\":[\"91888100XXXX\",\"91888100XXXX\"],\r\"sender_mask\":\"KONNECT\",\r\"body\":\"Your charging for Subscription is successful, you are subscribed for a period of 30 days\"\r}\r",
    CURLOPT_HTTPHEADER => array(
        "Authorization: your_api_token",
        "Content-Type: application/json"
    )
));

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

curl_close($curl);

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

Receive an SMS using Konnect’s REST API Copy

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/InboundPhoneNumbers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\r \"id\": \"your_unique_id_for_request\",\r \"phone_number\": \"91888300XXXX\",\r \"callback_url\": \"your_callback_url\"\r  }",
CURLOPT_HTTPHEADER => array(
  "Authorization: your_api_token",
  "Content-Type: application/json"
),
));

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

curl_close($curl);

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

Deleting an Inbound Phone number using Konnect’s REST API Copy


<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/InboundPhoneNumbers/91888300XXXX",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => array(
    "Authorization: your_api_token"
  ),
));

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

curl_close($curl);

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

Send an outgoing SMS using Konnect’s REST API Copy

public static void RequestToKonnect() throws JSONException {

 HttpURLConnection urlConnection;
 JSONObject json = new JSONObject();
 json.put("id", "your_unique_id_for_request");
 json.put("from", "91888200XXXX");

 JSONArray jsonArray = new JSONArray();
 jsonArray.put("91888100XXXX");
 jsonArray.put("91888100XXXX");
 json.put("to", jsonArray);

 json.put("sender_mask", "KONNECT");
 json.put("body", "Your charging for Subscription is successful, you are subscribed for a period of 30 days");
 String data = json.toString();
 String response = null;

 try {
  //Connect
  urlConnection = (HttpURLConnection)((new URL("https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Messages").openConnection()));
  urlConnection.setDoOutput(true);
  urlConnection.setRequestProperty("Content-Type", "application/json");
  urlConnection.setRequestProperty("Authorization", "your_api_token");
  urlConnection.setRequestMethod("POST");
  urlConnection.connect();

  //Write
  OutputStream outputStream = urlConnection.getOutputStream();
  BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream, "UTF-8"));
  writer.write(data);
  writer.close();
  outputStream.close();

  //Read
  BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), "UTF-8"));

  String line = null;
  StringBuilder sb = new StringBuilder();

  while ((line = bufferedReader.readLine()) != null) {
   sb.append(line);
  }

  bufferedReader.close();
  response = sb.toString();

 } catch (UnsupportedEncodingException e) {
  e.printStackTrace();
 } catch (IOException e) {
  e.printStackTrace();
 }

 System.out.println(response);

}

Receive an SMS using Konnect’s REST API Copy

public static void RequestToKonnect() throws JSONException {

 HttpURLConnection urlConnection;
 JSONObject json = new JSONObject();
 json.put("id", "your_unique_id_for_request");
 json.put("phone_number", "91888300XXXX");
 json.put("callback_url", "your_callback_url");
 String data = json.toString();
 String response = null;

 try {
  //Connect
  urlConnection = (HttpURLConnection)((new URL("https://konnect.kirusa.com/api/v1/Accounts/your_account_id/InboundPhoneNumbers").openConnection()));
  urlConnection.setDoOutput(true);
  urlConnection.setRequestProperty("Content-Type", "application/json");
  urlConnection.setRequestProperty("Authorization", "your_api_token");
  urlConnection.setRequestMethod("POST");
  urlConnection.connect();

  //Write
  OutputStream outputStream = urlConnection.getOutputStream();
  BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream, "UTF-8"));
  writer.write(data);
  writer.close();
  outputStream.close();

  //Read
  BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), "UTF-8"));

  String line = null;
  StringBuilder sb = new StringBuilder();

  while ((line = bufferedReader.readLine()) != null) {
   sb.append(line);
  }

  bufferedReader.close();
  response = sb.toString();

 } catch (UnsupportedEncodingException e) {
  e.printStackTrace();
 } catch (IOException e) {
  e.printStackTrace();
 }

 System.out.println(response);

}

Deleting an Inbound Phone number using Konnect’s REST API Copy

HttpURLConnection urlConnection;
    
  String response = null;

  try {
   //Connect
   urlConnection = (HttpURLConnection)((new URL("https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/InboundPhoneNumbers/91888300XXXX").openConnection()));
   urlConnection.setDoOutput(true);
     
   urlConnection.setRequestProperty("Authorization", "your_api_token");
   urlConnection.setRequestMethod("DELETE");
   urlConnection.connect();

   //Read
   BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), "UTF-8"));

   String line = null;
   StringBuilder sb = new StringBuilder();

   while ((line = bufferedReader.readLine()) != null) {
    sb.append(line);
   }

   bufferedReader.close();
   response = sb.toString();

   } catch (UnsupportedEncodingException e) {
      e.printStackTrace();
   } catch (IOException e) {
      e.printStackTrace();
   }

  System.out.println(response);

Send an outgoing SMS using Konnect’s REST API Copy

curl --request POST \
  --url https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Messages \
  --header 'Authorization: your_api_token' \
  --header 'Content-Type: application/json' \
  --data '{
"id":"your_unique_id_for_request",
"from":"91888200XXXX",
"to":["91888100XXXX","91888100XXXX"],
"sender_mask":"KONNECT",
"body":"Your charging for Subscription is successful, you are subscribed for a period of 30 days"
}'

Receive an SMS using Konnect’s REST API Copy

curl --request POST \
  --url https://konnect.kirusa.com/api/v1/Accounts/your_account_id/InboundPhoneNumbers \
  --header 'Authorization: your_api_token'' \
  --header 'Content-Type: application/json' \
  --data '{
 "id": "your_unique_id_for_request",
 "phone_number": "91888300XXXX",
"callback_url": "your_callback_url"
 }'

Deleting an Inbound Phone number using Konnect’s REST API Copy


curl --location --request DELETE "https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/   
       InboundPhoneNumbers/91888300XXXX" \
     --header "Authorization: your_api_token"

Send an outgoing SMS using Konnect’s REST API Copy

import requests

url = "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Messages"

payload = "{\r\"id\":\"your_unique_id_for_request\",\r\"from\":\"91888200XXXX\",\r\"to\":[\"91888100XXXX\",\"91888100XXXX\"],\r\"sender_mask\":\"KONNECT\",\r\"body\":\"Your charging for Subscription is successful, you are subscribed for a period of 30 days\"\r}\r"
headers = {
    'Content-Type': "application/json",
    'Authorization': "your_api_token"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Receive an SMS using Konnect’s REST API Copy

import requests

url = "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/InboundPhoneNumbers"

payload = "{\r \"id\": \"your_unique_id_for_request\",\r \"phone_number\": \"91888300XXXX\",\r \"callback_url\": \"your_callback_url\"\r  }"
headers = {
    'Content-Type': "application/json",
    'Authorization': "your_api_token"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Deleting an Inbound Phone number using Konnect’s REST API Copy


import requests

url = 'https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/InboundPhoneNumbers/91888300XXXX'

payload = {}
headers = {
    'Authorization': 'your_api_token'
    }

response = requests.request('DELETE', url, headers = headers, data = payload, allow_redirects=False, timeout=undefined, allow_redirects=false)

print(response.text)

Please click here for Complete API Reference.

One Time password can be sent to validate an user’s identity by his mobile number. The Outbound messaging API can be used for this purpose.

All transactional summaries eg., latest bank account balance, last five bank transactions etc. can be sent via SMS by using the Outbound Messaging API.

You can send out offers and opportunities, and easily communicate with your target audience by using the Messaging API.

You can use the Outbound SMS API to send out information to a specific set of people for eg., to parents of school bus in a particular route regarding change in the driver’s contact number, church goers regarding changes in church timings etc..

The Outbound Messaging API can be effectively used to promote related products to a target audience.

You can send warm and refreshing greetings (eg., Happy Birthday, Happy Easter, Happy New Year) to your target audience by using the SMS API.

By using the Inbound APIs, you can configure a short code or a long number to accept voting commands and run contests. Eg., to vote for participant 1 send WIN 1, to vote for participant 2 send WIN2 and so on.

Relevant and personalized offers can be made on receiving SMS inputs from an user for eg., if he is interested in Nike shoes, he can send an SMS ‘OPT NIKE’ to 2510. This input will be processed by the Inbound Messaging system and notification sent to the enterprise upon which the Outbound Messaging API can be used to send the end user attractive deals from Nike.

By using the Inbound APIs, polls and surveys can be easily configured on specific short codes or long numbers.

On receiving relevant keywords on a number from the end user, you can trigger subscription to a specific service.

Get feedback from the customer and act on them to continuously improve. All these can be achieved by configuring inbound numbers.

You can configure a number to generate interested leads for a product or a service by using the Konnect API.

Overview

This enables you to execute outbound voice campaigns (OBD) and Interactive Voice Response (IVR) campaigns through the Konnect platform by invoking a REST API.

Base URI

https://konnect.kirusa.com/api/v1/Accounts/{account_id}/

Authentication and Authorization

The Konnect APIs make use of authentication as follows

The Konnect account_id value is set in the URL
The Konnect api_token is passed in the Authorization header

The account_id and api_token are available on the Account Dashboard once the user logs in to the Konnect portal ( https://konnect.kirusa.com/ ).

Outbound Calls / Inbound (IVR) Calls

Overview

Allows user to execute OBD/Interactive or inbound voice campaigns through the Konnect platform using an API

Features

Outbound Calls

Enterprise user can send outbound calls to a single recipient or a list of recipients
He will be notified of the OBD status via a callback URL eg., whether the OBD was answered, not answered, no reply, busy and rejected etc..
Track each OBD sent on a real-time report in the Konnect portal. The reporting analytics will include:
- From and To numbers
- Time stamp of when OBD was initiated and when the call got answered
- Call duration
- Status of the call
Campaign can be configured along with an IVR number. This is a part of the API parameters and is available here (refer to Section OBD/Inbound Calls in the document). The end user can dial in to the IVR number to listen to the audio content that he would have missed listening to when he had received the OBD call. Enterprise user can send the dial-in (IVR) number info via an SMS to the end user by using the Outbound Messaging API. This type of OBD is referred in the API documentation as ‘Premium OBD’.

Inbound (IVR) Calls

Enterprise user can configure an IVR (Interactive Voice Response) campaign by calling the Calls API
The same API that is used for 'Outbound Calls' should be used for Inbound campaigns as well, only the request parameters change. Details are available here (refer to Section OBD/Inbound Calls in the document)
The inbound number to be configured first needs to be purchased from the number management page in the Konnect portal (https://konnect.kirusa.com/)
Track each inbound call on a real-time report in the Konnect portal. The reporting analytics will include:
- From and To numbers
- Start and End time of the call
- Call duration
Enterprise user will be notified of the call details (start time, end time and duration) via the callback URL configured in the API

Method

POST/GET

URL Structure

For POST: https://konnect.kirusa.com/api/v1/Accounts/{account_id}/Calls

For GET : https://konnect.kirusa.com/api/v1/Accounts/{account_id}/Calls?id={id}&caller_id={caller_id}&media_url={media_url}&callback_url={callback_url}&direction={direction}&doc_url={doc_url}&alt_doc_url={alt_doc_url}&ivr_number={ivr_number}&recipient={recipient}

Request Parameters

Field

Type

Mandatory

Description

String

Yes

Unique transaction id for the request.

ref_id

String

This reference id (preconfigured voice callflow id) is used for executing the preconfigured voice callflow. The reference id is returned in the response of callflow creation API. This can be re-used for subsequent campaigns with the same call flow, but with different/same set of recipients.

recipient

String

The destination phone numbers, each phone numbers must be separated by “,” delimiter.
This parameter is mandatory if the direction is ‘outbound’ or ‘2way’, for ‘inbound’ campaigns it is not required

direction

String

The value can be ‘inbound’, ‘outbound’ or ‘2way’. If no value is specified then default string is ‘outbound’. E.g. for premium OBD the value is set to ‘2way’.

expiry

String

[ Not currently supported ]
The expiry in seconds, it is applicable for outbound Calls, e.g. if the message is valid for 5 minutes then the value needs to be the value needs to be set as 300.

priority

String

[ Not currently supported ]
Defines the priority of outbound Calls delivery, the value can be set to ‘normal’ or ‘high’. The message with ‘high’ priority is charged at premium rate than ‘normal’ priority messages. If this parameter is not set, the default priority will be ‘normal’.

media_url

String

The URL for the media to be played in outbound call. The media file format needs to be in A-law, 64 kbps, mono.Please note that if ref_id is passed, the media_url should be null. This parameter is ignored if the doc_url is specified.

caller_id

String

The phone number of the OBD initiator/sender. If not specified the default caller_id is used.

ivr_number

String

The dial-in phone number used when the call_type is defined as ‘premium’ or direction is defined as ‘inbound’.

Premium OBD: If this number is not specified then the caller_id is configured as dial-in number for premium OBD.

Inbound Calls: This parameter is mandatory for calls with direction ‘inbound’

callback_url

String

The URL to be notified for the status of OBD/Inbound call. The callback notification is provided for each call.

doc_url

String

The fully qualified URL containing KML instructions for the call. Konnect invokes this URL when the call gets connected. The response details are covered in the section 5 Kirusa Markup Language. This parameter is ignored if the ref_id is specified.
The call_id, campaign_id, phone_number,key_pressed and call_status parameters are passed in the query string while invoking the doc_url:-
The description of the parameters are as follows:-

Parameter	Value
call_id	The unique id for the current call.
campaign_id	The id of the campaign.
phone_number	The mobile number of the caller.
key_pressed	The DTMF key pressed by the user
call_status	A string representing the status of the call. The status can be one of the following:- ‘continue’, ‘end’ or ‘error’.

alt_doc_url

String

The fully qualified URL containing KML instructions, an alternative to the doc_url. This URL gets invoked if there is an error in accessing the doc_url.

The sample request for configuring an OBD campaign looks as follows

{
  "id": "A10579090909090",
  "recipient": ["919886038842",”9198860347”],
  "caller_id": "919886000085",
  "media_url": "http://somewebsite.com/audio.wav",
  “callback_url”, “http://myapp.com/notify”
}

The sample request for configuring an IVR campaign looks as follows

{
 "id": "A10579090909091",
 "media_url": "http://somewebsite.com/audio.wav",
 "callback_url": "http://myapp.com/notify",
 "ivr_number":"919977000043",
 "direction":"inbound"
}

The sample request for configuring a 2-way campaign looks as follows

// If caller_id is not a 2-way number
{
"id":"A10579090909092",
"caller_id":"919886000085", 
"ivr_number":"919977000042", 
"recipient":["919886038842",”919886038848”],
"media_url": "http://somewebsite.com/audio.wav",
"callback_url": "http://myapp.com/notify",
"direction":"2way"
}

// If caller_id is a 2-way number
{
"id":"A10579090909092",
"caller_id":"919886000085", 
"ivr_number":"919886000085", 
"recipient":["919886038842",”919886038848”],
"media_url": "http://somewebsite.com/audio.wav",
"callback_url": "http://myapp.com/notify",
"direction":"2way"
}

Response

Outbound Calls

The sample response when the request is submitted successfully is as follows:-

{
  "status":"ok"
}

The sample response when the submitted request fails due to low balance is as follows:-

{
  "status":"error",
  “error_code”:”3003”,
  “error_reason”:”Low Balance”
}

The asynchronous response of the above request command is sent via callback_url, containing status and ref_ids as follows:-

{
  “id”:” A10579090909090”,
  "status":"accepted",
  "ref _ids": [{“phone_number”: “919886038842”,”ref_id”:”AC5ef8732a3c49700934481addd5ce1659"},{“phone_number”: “9198860347”,”ref_id”,”BD6ef8732a3c49700934481addd5ce1660”}]
}

Note: In case the request is rejected then the status is set as rejected and the error_code and error_reason contains the details for error.

Inbound (IVR) Calls

The sample response when the request is submitted successfully is as follows:-

{
  "status":"ok"
}

Response Parameters passed in the Callback URL

The callback_url for the OBD or IVR call contains the following fields:-
Please note that for an OBD call, this is invoked for each phone number every time there is a change in the status of call(Accepted, Queued, Sent, Delivered).
For an inbound (IVR) call, this is invoked at the end of each call.

Field	Type	Mandatory	Description
ref_id	String	Yes	Unique reference generated by Konnect Platform.
recipient	String	Yes	The phone number of the recipient.
caller_id	String	No	The phone number of the OBD initiator.
status	String	Yes	The list of status is mentioned in the API documentation.
price	String	Yes	The amount billed for the OBD
balance	String	Yes	The remaining balance in the account
error_code	String	Yes	The list of error code is mentioned in the API documentation.
error_reason	String	Yes	The list of error reason is mentioned in the API documentation.
call_start_time	String	No	The start time of an OBD/IVR Call. The time format is in MMM D, YYYY H:M:S AM/PM time zone of the user e.g. Nov 22, 2018 6:07:12 PM IST.
call_end_time	String	No	The end time of an OBD/IVR Call. The time format is in MMM D, YYYY H:M:S AM/PM time zone of the user.
call_connect_time	String	No	The time when the call was picked up. The time format is in MMM D, YYYY H:M:S AM/PM time zone of the user.
media_duration	String	No	The length of the audio listened in seconds.
key_pressed	String	No	The DTMF key pressed by the user in the IVR. If user presses multiple keys then each key is delimited with “,” (comma).
media_url	String	No	If the user had recorded any audio in the callflow then the audio is sent to the user

The values of the status, error_code and error_reason fields are in the API documentation.

Deleting an Inbound Phone number

Method

DELETE

URL Structure

https://konnect.kirusa.com/api/v1/Accounts/{account_id}/InboundPhoneNumbers/{inbound_phone_number}

Response

The response is similar to 'Inbound Messaging - Deleting an inbound phone number'.

SnapCall

Konnect API for configuring a SnapCall (FlashCall) campaign is under implementation and will be available soon.
It is, however, already available from the user interface portal (Go to ‘Campaigns’ section after log-in, click on ‘New Campaign’ and choose ‘SnapCall’)

SnapCall uses the power and simplicity of a phone call to make inbound communication intuitive and easy for the target segment.
It is the one of the best mediums for generating leads and interest among the probable customers.

This is how a typical SnapCall works:

A mobile user places a call to the SnapCall number (Service number)
The call via the mobile network lands on the Kirusa Konnect platform
The call is disconnected after mobile user hears a ring or after a prompt is played (depends on the campaign configuration)
The Webhook (or Callback) URL is an additional configuration in SnapCall which will be used by Konnect platform to notify your web server for every incoming SnapCall that is received on the configured SnapCall number.
Once the notification is received by your server, you can decide whether to send an SMS or OBD to the end user number or take any other action desired by you. SMS or OBD can be sent by using the Konnect APIs.
Details about how to use the Webhook (Callback URL) and the API request and response format details are available here.

OTP via Outbound Call

This API enables you to send a plain-text OTP (One Time Password) to the Konnect platform. Konnect will initiate an OBD call for you that will play the OTP to the user, once he answers the call. Details of the API usage are available here.

Please click here for Complete API Reference.

Configure an outbound calling campaign using Konnect’s REST API Copy

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\n\"id\":\"your_unique_id_for_request\",\n\"caller_id\":\"91922100XXXX\",\n\"recipient\":[\"91888122XXXX,91888122XXXX\"],\n\"media_url\":\"your_media_url\",\n\"direction\":\"outbound\"\n}",
CURLOPT_HTTPHEADER => array(
  "Authorization: your_api_token",
  "Content-Type: application/json"
),
));

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

curl_close($curl);

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

Configure an OBD campaign and an IVR number that plays the OBD content when dialled in: Copy

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\n\"id\":\"your_unique_id_for_request\",\n\"caller_id\":\"91922100XXXX\",\n\"ivr_number\":\"91997700XXXX\",\n\"recipient\":[\"91888122XXXX,91888122XXXX\"],\n\"doc_url\":\"your_kml_url\",\n\"direction\":\"2way\"\n}",
CURLOPT_HTTPHEADER => array(
  "Authorization: your_api_token",
  "Content-Type: application/json"
),
));

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

curl_close($curl);

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

Configure an IVR campaign using Konnect’s REST API Copy

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
CURLOPT_URL => "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\n\"id\":\"your_unique_id_for_request\",\n\"ivr_number\":\"91922100XXXX\",\n\"media_url\":\"your_media_url\",\n\"direction\":\"inbound\"\n}",
CURLOPT_HTTPHEADER => array(
  "Authorization: your_api_token",
  "Content-Type: application/json"
),
));

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

curl_close($curl);

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

Deleting an Inbound Phone number using Konnect’s REST API Copy

<?php
              
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/InboundPhoneNumbers/91888300XXXX",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => false,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_HTTPHEADER => array(
    "Authorization: your_api_token"
  ),
));

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

curl_close($curl);

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

Configure an outbound calling campaign using Konnect’s REST API Copy

public static void RequestToKonnect() throws JSONException {

 HttpURLConnection urlConnection;
 JSONObject json = new JSONObject();
 json.put("id", "your_unique_id_for_request");
 json.put("caller_id", "91922100XXXX");

 JSONArray jsonArray = new JSONArray();
 jsonArray.put("91888122XXXX");
 jsonArray.put("91888122XXXX");
 json.put("recipient", jsonArray);

 json.put("media_url", "your_media_url");
 json.put("direction", "outbound");
 String data = json.toString();
 String response = null;

 try {
  //Connect
  urlConnection = (HttpURLConnection)((new URL("https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls").openConnection()));
  urlConnection.setDoOutput(true);
  urlConnection.setRequestProperty("Content-Type", "application/json");
  urlConnection.setRequestProperty("Authorization", "your_api_token");
  urlConnection.setRequestMethod("POST");
  urlConnection.connect();

  //Write
  OutputStream outputStream = urlConnection.getOutputStream();
  BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream, "UTF-8"));
  writer.write(data);
  writer.close();
  outputStream.close();

  //Read
  BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), "UTF-8"));

  String line = null;
  StringBuilder sb = new StringBuilder();

  while ((line = bufferedReader.readLine()) != null) {
   sb.append(line);
  }

  bufferedReader.close();
  response = sb.toString();

 } catch (UnsupportedEncodingException e) {
  e.printStackTrace();
 } catch (IOException e) {
  e.printStackTrace();
 }

 System.out.println(response);

}

Configure an OBD campaign and an IVR number that plays the OBD content when dialled in: Copy

public static void RequestToKonnect() throws JSONException {


 HttpURLConnection urlConnection;
 JSONObject json = new JSONObject();
 json.put("id", "your_unique_id_for_request");
 json.put("caller_id", "91922100XXXX");
 json.put("ivr_number", "91997700XXXX");

 JSONArray jsonArray = new JSONArray();
 jsonArray.put("91888122XXXX");
 jsonArray.put("91888122XXXX");
 json.put("recipient", jsonArray);

 json.put("doc_url", "your_kml_url");
 json.put("direction", "2way");
 String data = json.toString();
 String response = null;

 try {
  //Connect
  urlConnection = (HttpURLConnection)((new URL("https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls").openConnection()));
  urlConnection.setDoOutput(true);
  urlConnection.setRequestProperty("Content-Type", "application/json");
  urlConnection.setRequestProperty("Authorization", "your_api_token");
  urlConnection.setRequestMethod("POST");
  urlConnection.connect();

  //Write
  OutputStream outputStream = urlConnection.getOutputStream();
  BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream, "UTF-8"));
  writer.write(data);
  writer.close();
  outputStream.close();

  //Read
  BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), "UTF-8"));

  String line = null;
  StringBuilder sb = new StringBuilder();

  while ((line = bufferedReader.readLine()) != null) {
   sb.append(line);
  }

  bufferedReader.close();
  response = sb.toString();

 } catch (UnsupportedEncodingException e) {
  e.printStackTrace();
 } catch (IOException e) {
  e.printStackTrace();
 }

 System.out.println(response);

}

Configure an IVR campaign using Konnect’s REST API Copy

public static void RequestToKonnect() throws JSONException {

 HttpURLConnection urlConnection;
 JSONObject json = new JSONObject();
 json.put("id", "your_unique_id_for_request");
 json.put("ivr_number", "91922100XXXX");
 json.put("media_url", "your_media_url");
 json.put("direction", "inbound");
 String data = json.toString();
 String response = null;

 try {
  //Connect
  urlConnection = (HttpURLConnection)((new URL("https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls").openConnection()));
  urlConnection.setDoOutput(true);
  urlConnection.setRequestProperty("Content-Type", "application/json");
  urlConnection.setRequestProperty("Authorization", "your_api_token");
  urlConnection.setRequestMethod("POST");
  urlConnection.connect();

  //Write
  OutputStream outputStream = urlConnection.getOutputStream();
  BufferedWriter writer = new BufferedWriter(new OutputStreamWriter(outputStream, "UTF-8"));
  writer.write(data);
  writer.close();
  outputStream.close();

  //Read
  BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), "UTF-8"));

  String line = null;
  StringBuilder sb = new StringBuilder();

  while ((line = bufferedReader.readLine()) != null) {
   sb.append(line);
  }

  bufferedReader.close();
  response = sb.toString();

 } catch (UnsupportedEncodingException e) {
  e.printStackTrace();
 } catch (IOException e) {
  e.printStackTrace();
 }

 System.out.println(response);

}

Deleting an Inbound Phone number using Konnect’s REST API Copy

HttpURLConnection urlConnection;
    
  String response = null;

  try {
   //Connect
   urlConnection = (HttpURLConnection)((new URL("https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/InboundPhoneNumbers/91888300XXXX").openConnection()));
   urlConnection.setDoOutput(true);
     
   urlConnection.setRequestProperty("Authorization", "your_api_token");
   urlConnection.setRequestMethod("DELETE");
   urlConnection.connect();

   //Read
   BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream(), "UTF-8"));

   String line = null;
   StringBuilder sb = new StringBuilder();

   while ((line = bufferedReader.readLine()) != null) {
    sb.append(line);
   }

   bufferedReader.close();
   response = sb.toString();

  } catch (UnsupportedEncodingException e) {
    e.printStackTrace();
  } catch (IOException e) {
    e.printStackTrace();
  }

System.out.println(response);

Configure an outbound calling campaign using Konnect’s REST API Copy

curl --request POST \
  --url https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls \
  --header 'Authorization: your_api_token' \
  --header 'Content-Type: application/json' \
  --data '{
"id":"your_unique_id_for_request",
"caller_id":"91922100XXXX",
"recipient":["91888122XXXX","91888122XXXX"],
"media_url":"your_media_url",
"direction":"outbound"
}'

Configure an OBD campaign and an IVR number that plays the OBD content when dialled in: Copy

curl --request POST \
  --url https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls \
  --header 'Authorization: your_api_token' \
  --header 'Content-Type: application/json' \
  --data '{
"Id":"your_unique_id_for_request",
"caller_id":"91922100XXXX",
"ivr_number":"91997700XXXX",
"recipient":["91888122XXXX","91888122XXXX"],
"doc_url":"your_kml_url",
"direction":"2way"
}'

Configure an IVR campaign using Konnect’s REST API Copy

curl --request POST \
  --url https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls \
  --header 'Authorization: your_api_token' \
  --header 'Content-Type: application/json' \
  --data '{
"id":"your_unique_id_for_request",
"ivr_number":"91922100XXXX",
"media_url":"your_media_url",
"direction":"inbound"
}'

Deleting an Inbound Phone number using Konnect’s REST API Copy

                   
curl --location --request DELETE "https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/   
       InboundPhoneNumbers/91888300XXXX" \
     --header "Authorization: your_api_token"

Configure an outbound calling campaign using Konnect’s REST API Copy

import requests

url = "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls"

payload = "{\n\"id\":\"your_unique_id_for_request\",\n\"caller_id\":\"91922100XXXX\",\n\"recipient\":[\"91888122XXXX,91888122XXXX\"],\n\"media_url\":\"your_media_url\",\n\"direction\":\"outbound\"\n}"
headers = {
    'Content-Type': "application/json",
    'Authorization': "your_api_token"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Configure an OBD campaign and an IVR number that plays the OBD content when dialled in: Copy

import requests

url = "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls"

payload = "{\n\"id\":\"your_unique_id_for_request\",\n\"caller_id\":\"91922100XXXX\",\n\"ivr_number\":\"91997700XXXX\",\n\"recipient\":[\"91888122XXXX,91888122XXXX\"],\n\"doc_url\":\"your_kml_url\",\n\"direction\":\"2way\"\n}"
headers = {
    'Content-Type': "application/json",
    'Authorization': "your_api_token"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Configure an IVR campaign using Konnect’s REST API Copy

import requests

url = "https://konnect.kirusa.com/api/v1/Accounts/your_account_id/Calls"

payload = "{\n\"id\":\"your_unique_id_for_request\",\n\"ivr_number\":\"91922100XXXX\",\n\"media_url\":\"your_media_url\",\n\"direction\":\"inbound\"\n}"
headers = {
    'Content-Type': "application/json",
    'Authorization': "your_api_token"
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

Deleting an Inbound Phone number using Konnect’s REST API Copy

import requests

url = 'https://konnect.kirusa.com/admin/api/v1/Accounts/your_account_id/InboundPhoneNumbers/91888300XXXX'

payload = {}
headers = {
     'Authorization': 'your_api_token'
    }

response = requests.request('DELETE', url, headers = headers, data = payload, allow_redirects=False, timeout=undefined, allow_redirects=false)

print(response.text)

Please click here for Complete API Reference.

Reminders via outbound calls can be set up for users whose insurance premium fall (for eg.) within the 10th of each month. The Outbound Calls API can be used to achieve this.

One Time password can be sent to validate an user’s identity by his mobile number. The Outbound Calls API can be used for this purpose.

Outbound campaigns can be configured by using the Calls API to persuade people to buy a product, pay for a service, donate to a cause or otherwise include them in some social circle.

The API can be used to trigger an outbound call to a specific user to provide updates on his upcoming travel, trip details while he is travelling, pick-up and drop details etc..

Example of such type of campaign can be to spread awareness amongst the public on government vaccination schedules, Virus outbreak warnings and others. The API can be used to create such a campaign.

Outbound calls playing the desired audio content can be initiated for users who have subscribed to or interested in some category of audio/voice based services. The Outbound Calls API can be used to achieve this.