NAV
JSON cURL PHP Java Javascript

Introduction

This page will help you get started with CITCALL API.

This document will provide instructions on how to integrate CITCALL services by using CITCALL HTTP application programming interface (HTTP API). Use HTTP API for making miscall and sending SMS messages. CITCALL's API is based on REST standards, enabling you to use your browser for accessing URLs. Use any HTTP client in any programming language to interact with our API.

Authorization

The majority of requests to CITCALL’s API require authentication. That can be done in two steps:

  1. IP Whitelist

    You can register your IP(s) at our Dashboard on option menu.

  2. API key authorization

    This is the most secure authorization type and the one with the most flexibility.

    API keys can be generated by calling the dedicated API method. Furthermore, API keys can have a limited scope and cover only some API methods. Lastly, they can be revoked at any time. This range of possibilities makes API keys well suited for separating the API access rights across multiple applications or use cases. Finally, the loss of an API key is easily manageable.

    You can find out more about API key creation and management at our Dashboard on API menu.

    In this case, the credentials included in the Authorization header should be a Base64 encoded username and password combination. More formally, basic authentication header can be constructed in two steps:

    • Username and password are concatenated using the colon (:) as a separator username:apikey.
    • The resulting string is encoded using the RFC2045-MIME variant of Base64.
  3. Example:

    Username: "Aladdin"
    Apikey: "9af4d8381781baccb0f915e554f8798d"

    Concatenated string: "Aladdin:9af4d8381781baccb0f915e554f8798d"

    Base64 encoded string: "QWxhZGRpbjo5YWY0ZDgzODE3ODFiYWNjYjBmOTE1ZTU1NGY4Nzk4ZA=="

    Authorization header: "QWxhZGRpbjo5YWY0ZDgzODE3ODFiYWNjYjBmOTE1ZTU1NGY4Nzk4ZA=="

API reference

Misscall


{
	"msisdn": "6281234567890",
	"gateway": 0
}

				
curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: VVNFUk5BTUU6QVBJS0VZ' \
 -d '{
 	"msisdn":"6281234567890",
 	"gateway":"0"
 }' https://gateway.citcall.com/v3/call

				
<?php
$userid = 'USERNAME';
$apikey = 'APIKEY';
$auth = base64_encode($userid . ':' . $apikey);

$base_url = 'https://gateway.citcall.com';
$version = '/v3';
$action = '/call';

$url = $base_url . $version . $action ;
$data = array(
	'msisdn' => '6281234567890',
	'gateway' => 0
);

$content = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($ch,CURLOPT_POSTFIELDS,$content);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HTTPHEADER,array(
	'Content-Type: application/json',
	'Authorization: '. $auth,
	'Content-Length: '.strlen($content))
);
$response  = curl_exec($ch);
$err  = curl_error($ch);

curl_close($ch);

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

				
HttpResponse<String> response =  Unirest.post("https://gateway.citcall.com/v3/call")
.header("content-type","application/json")
.header("Authorization","VVNFUk5BTUU6QVBJS0VZ")
.body("{\"msisdn\":\"6281234567890\",\"gateway\":\"0\"}")
.asString();

				
var data = JSON.stringify({
  "msisdn": "6281234567890",
  "gateway": "0"
});

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

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

xhr.open("POST", "https://gateway.citcall.com/v3/call");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "VVNFUk5BTUU6QVBJS0VZ");

xhr.send(data);

				

The above command returns JSON structured like this:


{
	"rc": "00",
	"trxid": "20170709083044690027711524",
	"msisdn": "+6281234567890",
	"via": "voice",
	"token": "622130401234",
	"dial_code": "200",
	"dial_status": "OK",
	"call_status": "ANSWERED",
	"result": "Success"
}

				

You can use our API to provide miscall to the MSISDN

HTTP Request

POST https://gateway.citcall.com/v3/call

Request structure

To provide miscall using the Citcall API you need to submit a JSON object to the url defined above. The JSON object takes the following properties:

Parameter Type Description Required
msisdn string End-User mobile number Required
gateway int Gateway number Required

Gateway description:

Gateway Description VIA Route to
0 Gateway number 0 Call Telephony Gateway 0
1 Gateway number 1 Call Telephony Gateway 1
2 Gateway number 2 Call Telephony Gateway 2
3 Gateway number 3 Call Telephony Gateway 3
4 Gateway number 4 Call Telephony Gateway 4
5 SMS SMS SMS Gateway

Request Body

Below is a more detailed description of the parameters in the SMS request body (JSON object submitted to the API)

Response

The response returns the following:

SMS


{
	"senderid": "citcall",
	"msisdn": "6281234567890",
	"text": "Hello World!"
}

				
curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: VVNFUk5BTUU6QVBJS0VZ' \
 -d '{
 	"senderid":"citcall",
 	"msisdn":"6281234567890",
 	"text":"Hello World!"
 }' https://gateway.citcall.com/v3/sms

				
<?php
$userid = 'USERNAME';
$apikey = 'APIKEY';
$auth = base64_encode($userid . ':' . $apikey);

$base_url = 'https://gateway.citcall.com';
$version = '/v3';
$action = '/sms';

$url = $base_url . $version . $action ;
$data = array(
	'senderid' => 'citcall',
	'msisdn' => '6281234567890',
	'text' => 'Hello World!'
);

$content = json_encode($data);
$ch = curl_init($url);
curl_setopt($ch,CURLOPT_CUSTOMREQUEST,'POST');
curl_setopt($ch,CURLOPT_POSTFIELDS,$content);
curl_setopt($ch,CURLOPT_RETURNTRANSFER,true);
curl_setopt($ch,CURLOPT_HTTPHEADER,array(
	'Content-Type: application/json',
	'Authorization: '. $auth,
	'Content-Length: '.strlen($content))
);
$response  = curl_exec($ch);
$err  = curl_error($ch);

curl_close($ch);

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

				
HttpResponse<String> response =  Unirest.post("https://gateway.citcall.com/v3/sms")
.header("content-type","application/json")
.header("Authorization","VVNFUk5BTUU6QVBJS0VZ")
.body("{\"senderid\":\"citcall\",\"msisdn\":\"6281234567890\",\"text\":\"Hello World!\"}")
.asString();

				
var data = JSON.stringify({
  "senderid": "citcall",
  "msisdn": "6281234567890",
  "text": "Hello World!"
});

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

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

xhr.open("POST", "https://gateway.citcall.com/v3/sms");
xhr.setRequestHeader("content-type"", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "VVNFUk5BTUU6QVBJS0VZ");

xhr.send(data);

				

The above command returns JSON structured like this:


{
	"rc": "00",
	"info": "Ok",
	"messages": [
	  {
	    "to": "6281234567890",
	    "result": "ok",
	    "smsCount": 1
	  }
	],
	"senderid": "citcall",
	"msisdn": "6281234567890",
	"text": "Hello World!",
	"trxid": "20170530152922"
}

				

You can use our API to send single SMS requests or batch SMS requests to deliver your text messages to any country or operator in the World using your Citcall account.

HTTP Request

POST https://gateway.citcall.com/v3/sms

Request structure

To send a single SMS using the Citcall SMS API you need to submit a JSON object to the url defined above. The JSON object takes the following properties:

Parameter Type Description Required
senderid string Your Registered Senderid Required
msisdn string Receipient number, multiple delimiter with “,” Required
text string SMS body (ie: text of the message) Required

Request Body

Below is a more detailed description of the parameters in the SMS request body (JSON object submitted to the API)

Response

The response returns the following:

Appendix

Table of dial code

We consider dial status 180,183 & 2xx to be succeed result (misscall delivered).

1XXProvisional
100Trying
180Ringing
181Call is being forwarded
182Queued
183Session in progres
199Early Dialogue Terminated
2XXSuccessfull
200OK
201Accepted
204No Notification
3XXRedirection
300Multiple Choice
301Moved Permanently
302Moved Temporarily
305Use Proxy
380Alternative Service
4XXClient Failure
400Bad Request
401Unauthorized
402Payment Required
403Forbiden
404Not Found
405Method Not Allowed
406Not Acceptable
407Proxy Authentication Required
408Request Timeout
409Conflict
410Gone
411Length Required
412Conditional Request Failed
413Request Entity Too Large
414Request-URI Too Long
415Unsupported Media Type
416Unsupported URI Scheme
417Unknown Resource-Priority
420Bad Extension
421Extension Required
422Session Interval To Small
423Interval Too Brief
424Bad Location Information
428Use Indentity Header
429Provide Refferer Indentity
430Flow Failed
433Anonymity Disallowed
436Bad Indentity-Info
437Unsupported Certificate
438Invalid Indentity Header
439First Hop Lacks Outbound Support
470Consent Needed
480Temporarily Unavailable
481Call/Transaction Does Not Exits
482Loop Detected
483Too Many Hoops
484Address Incomplete
485Ambiguous
486Busy Here
487Request Terminated
488Not Acceptable Here
489Bad Event
491Request Pending
493Undecipherable
494Security Agreement Required
5XXServer Failure
500Server Internal Error
501Not Implemented
502Bad Gateway
503Service Unavailable
504Server Time-out
505Version Not Supported
513Message Too Large
580Precondition Failure
6XXGlobal Failure
600Busy Everywhere
603Decline
604Does Not Exits Anywhere
606Not Acceptable

UI/UX Guideline

You can check our UI/UX guideline for more refference. click here to see our UI/UX guideline.

Code Repository

You can check our GIthub repository to see our sample code. click here to see our repository.