Konnect API

Resource URL

https://konnect.kirusa.com/admin/api/sms


HTTP Method

POST


Description

This API enables you to send messages via Konnect SMS service. You can provide your purchased SnapCall number as 'from' number and include the text message that will be sent. You can also add sender mask in the API request which is not mandatory.

Note: SMS delivery to international number is not allowed.


Please click here for Konnect API pricing.

Authentication

All requests to Konnect API are authenticated using your Konnect Account ID and API Token. Your Konnect Account ID and API Token can be found when you login to your Dashboard.





Request Parameters


Header Parameters
Parameter Description
Authorization Add the provided Konnect Account ID to authenticate yourself with the server.

Content-Type Konnect only accepts input of the type application/json. The HTTP body content must be passed as json with the Content-Type set as application/json.

Body Parameters
Parameter Description
cmd Keyword used to identify the API request. For SMS API identifier will be "send_sms"

api_token Add the provided Konnect API Token to authenticate yourself with the server.

to The destination phone number where sms is to be sent. The number should be prefixed with the ISD code and should not be formatted. e.g. USA : 13371234567, Ghana : 233501234567
from A SnapCall number which is used as a sender ID. SnapCall number or short codes purchased from Konnect will work here.
body The text of the message you want to send, limited to 160 characters. Segmented SMS feature is not supported.

Optional Parameters
Parameter Description
sender_mask It’s a Sender ID, which can be your brand or company name. When sending SMS using Konnect SMS APP Token, you can personalize your sender id. This means that when user receives the message it will show your company name or brand from where the SMS message has come from rather than a number. If sender mask is not set than the receiver will see your SnapCall number.

Response Parameters

Parameter Description
cmd Keyword used to identify the API request. For SMS API identifier will be "send_sms"
status Returns the status of the request. If request is successful than the value will be 'ok' otherwise error will be shown.
error_reason Error reason will be added to the response if rquest made is not successful e.g. Invalid API token

Code Snippet

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.net.HttpURLConnection;
import java.net.URL;

import org.json.JSONException;
import org.json.JSONObject;

public class CodeSnippet {

  
  public static String RequestToKonnect() throws JSONException {
       HttpURLConnection urlConnection;
       JSONObject json = new JSONObject();
       json.put("cmd","send_sms");
       json.put("api_token", "Your Konnect API Token");
       json.put("to", "13371234567");
       json.put("body", "TEXT MESSAGE");
       json.put("from", "13371234568");														
       String data = json.toString();
       String result = null;
    try {
        //Connect
        urlConnection = (HttpURLConnection) ((new URL("https://konnect.kirusa.com/admin/api/sms").
openConnection())); urlConnection.setDoOutput(true); urlConnection.setRequestProperty("Content-Type", "application/json"); urlConnection.setRequestProperty("Authorization", "Your Konnect Account ID"); 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(); result = sb.toString(); } catch (UnsupportedEncodingException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } return result; } public static void main(String args[]){ String response= RequestToKonnect(); } }
<?php

// The data to post
$postData = array(
    'cmd' => 'send_sms',
    'api_token' => 'Your Konnect API Token',
    'to' => '13371234567',
    'body' => 'TEXT MESSAGE',
    'from' => '13371234568'														
);


// Create the context for the request
$context = stream_context_create(array(
    'http' => array(
        // http://www.php.net/manual/en/context.http.php
        'method' => 'POST',
        'header' => "Authorization: {Your Konnect Account ID\r\n".
            "Content-Type: application/json\r\n",
        'content' => json_encode($postData)
    )
));

// Sending request
$response = file_get_contents('https://konnect.kirusa.com/admin/api/sms', FALSE, $context);

// Check for errors
if($response === FALSE){
    die('Error');
}

echo $response                                              ;
// decoding and  accessing indivial element
$responseDataArray = json_decode($response, true);
echo responseDataArray['status'];

?>
curl -d '{"cmd":"send_sms", "api_token":"Your Konnect API Token", "to":"13371234567","body":"TEXT MESSAGE",
"from":"13371234568"}' -H "Content-Type: application/json" -X POST https://konnect.kirusa.com/admin/api/sms

Sample Request

{
    "cmd": "send_sms",
    "api_token":"Your Konnect API Token",
    "to":"13371234567",
    "body": "7878 is your OTP.",
    "from": "13371234568"
}

Sample Response

{
    "cmd": "send_sms",
    "status": "ok"                              
}


Resource URL

https://konnect.kirusa.com/admin/api/obd


HTTP Method

POST


Description

This API allows you to make outbound call to a phone number from your purchased OBD / 2-Way Voice number, for otp verification. You must provide One-Time password in request body.

Note: OBD delivery to international number is not allowed.


Please click here for Konnect API pricing.

Authentication

All requests to Konnect API are authenticated using your Konnect Account ID and API Token. Your Konnect Account ID and API Token can be found when you login to your Dashboard.





Request Parameters


Header Parameters
Parameter Description
Authorization Add the provided Konnect Account ID to authenticate yourself with the server.

Content-Type Konnect only accepts input of the type application/json. The HTTP body content must be passed as json with the Content-Type set as application/json.
Body Parameters
Parameter Description
cmd Keyword used to identify the API request. For OTP by OBD API identifier will be "send_otp_by_obd"

api_token Add the provided Konnect API Token to authenticate yourself with the server.

to The phone number to which the outbound call is to be made. The number should be prefixed with the ISD code and should not be formatted. e.g. USA : 13371234567, Ghana : 233501234567
caller_id An OBD / 2-Way Voice number which is used as a caller ID. An OBD / 2-Way Voice number purchased from Konnect will work here.
callback_url The URL to be notified for the status of OBD call. The callback notification is provided for each call.
otp One-Time password which will be played in outbound call to destination phone number. e.g. 7878

Response Parameters

Parameter Description
cmd Keyword used to identify the API request. For SMS API identifier will be "send_otp_by_obd"
status Returns the status of the request. If request is successful than the value will be 'ok' otherwise error will be shown.
error_reason Error reason will be added to the response if rquest made is not successful e.g. Invalid API token

Code Snippet

import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.UnsupportedEncodingException;
import java.net.HttpURLConnection;
import java.net.URL;

import org.json.JSONException;
import org.json.JSONObject;

public class CodeSnippet {

  
  public static String RequestToKonnect() throws JSONException {
       HttpURLConnection urlConnection;
       JSONObject json = new JSONObject();
       json.put("cmd","send_otp_by_obd");
       json.put("api_token", "Your Konnect API Token");
       json.put("to", "13371234567");
       json.put("otp", "7878");
       json.put("caller_id", "13371234568");														
       String data = json.toString();
       String result = null;
    try {
        //Connect
        urlConnection = (HttpURLConnection) ((new URL("https://konnect.kirusa.com/admin/api/obd").
openConnection())); urlConnection.setDoOutput(true); urlConnection.setRequestProperty("Content-Type", "application/json"); urlConnection.setRequestProperty("Authorization", "Your Konnect Account ID"); 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(); result = sb.toString(); } catch (UnsupportedEncodingException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } return result; } public static void main(String args[]){ String response= RequestToKonnect(); } }
<?php

// The data to post
$postData = array(
    'cmd' => 'send_otp_by_obd',
    'api_token' => 'Your Konnect API Token',
    'to' => '13371234567',
    'otp' => '7878', 
    'caller_id' => '13371234568',
);


// Create the context for the request
$context = stream_context_create(array(
    'http' => array(
        // http://www.php.net/manual/en/context.http.php
        'method' => 'POST',
        'header' => "Authorization: {Your Konnect Account ID\r\n".
            "Content-Type: application/json\r\n",
        'content' => json_encode($postData)
    )
));

// Sending request
$response = file_get_contents('https://konnect.kirusa.com/admin/api/obd', FALSE, $context);

// Check for errors
if($response === FALSE){
    die('Error');
}

echo $response;
// decoding and  accessing indivial element
$responseDataArray = json_decode($response, true);
echo responseDataArray['status'];

?>
curl -d '{"cmd":"send_otp_by_obd", "api_token":"Your Konnect API Token", "to":"13371234567", "otp":"7878",
"caller_id": "13371234568"}' -H "Content-Type: application/json" -X POST https://konnect.kirusa.com/admin/api/obd

Sample Request

{
    "cmd": "send_otp_by_obd",
    "api_token":"Your Konnect API Token",
    "to":"13371234567",
    "caller_id":"13371234568",
    "otp": "7878"   
}

Sample Response

{
    "cmd": "send_otp_by_obd",
    "status": "ok"                           
}


Webhook is a user-defined HTTP callback

Konnect platform uses Webhook to let your web server know when events happen, such as getting an incoming SnapCall on your configured SnapCall number.

How it works?



Konnect makes an HTTP request (POST) to the URL you configured for the webhook. Webhook can be configured while attaching a number for your campaign(See image below). In response, webhook can request for SMS delivery to the caller. One SMS per SnapCall is allowed. Additional SMS to the caller is chargeable as per SMS pricing.

Note: SMS delivery to international number is not allowed.




Webhook Request Parameters


When Konnect platform makes an HTTP request to your web server, it will include the following contextual information related to the SnapCall event that triggered the Webhook callback to your backend.

Parameter Description
event Type of event that triggered the webhook callback. e.g. snapcall
api_token Your Konnect API Token to authenticate yourself with the server.
id Unique request ID for the request
from Number from which the call is made. The number is prefixed with the ISD code and is not formatted. e.g. USA : 13371234567, Ghana : 233501234567
to SnapCall number on which call is made.
at Epoch time at which SnapCall was made.

Sample Request:
{
    "event": "snapcall",
    "api_token": "Your Konnect API Token",
    "id": 11628,
    "from": "13371234567",
    "to": "13371234568",
    "at": 1509355661140
}

Response

Send SMS:
Webhook response body should include the following JSON string, to deliver an SMS to the caller:
{
    "cmd": "send_sms",
    "sms_text": "Thank you for showing interest in our product. Our executive will contact you within 24 hours."
}
In case, no SMS to be delivered, then return empty JSON string (e.g. {}).

SMS Status Request:
SMS status request will be made on your provided Webhook URL
{
    "event": "send_sms_status",
    "api_token": "Your Konnect API Token",
    "id": 11628,
    "status": "ok"
}
Field "id" is the same Request ID for which you sent an SMS request.

The callback URL is used to let your web server know the status of the OBD call initiated from Konnect platform for OBD Campaigns; or status of the SMS (as per delivery receipt report from the carrier) for SMS Campaigns. You will be notified of the delivery status of each OBD call/SMS sent as per the campaign configured.

Callback Request Parameters


When Konnect platform makes an HTTP request to your web server, it will include the following contextual information related to the OBD/SMS event that triggered the callback to your backend.

Parameter Description
to_number Phone number to which the OBD call was initiated / SMS was sent
campaign OBD/SMS campaign name for which the callback was configured.
schedule OBD/SMS schedule name for which the callback was configured.
schedule_time OBD/SMS schedule time when the schedule was run.
status Status of the OBD call or SMS sent
description Description of the status.
event_timestamp Time of event occurrence


Sample OBD Request:

{
    "to_number": "13371234567",
    "campaign": "OBD Campaign",
    "schedule": "Schedule 1",
    "schedule_time": "Aug 27, 2018 5:44:01 PM EDT",
    "status": "Answered",
    "event_timestamp": "Aug 27, 2018 5:45:00 PM EDT"
}


Sample SMS Request:

{
    "to_number": "13371234567",
    "campaign": "Bulk SMS Campaign",
    "schedule": "Schedule 1",
    "schedule_time": "Aug 17, 2018 12:35:34 PM EDT",
    "status": "DELIVERED",
    "description": "The message was successfully delivered",
    "event_timestamp": "Aug 17, 2018 12:36:00 PM EDT"
}