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. Authorization Methods

    The majority of requests to CITCALL’s API require authentication. That can be done by setting the Authorization HTTP header. The Authorization header must include a type and the credentials themselves.

    Authorization: <type> <credentials>

    Type Format Notes
    Apikey Citcall Generated Apikey Recommended
    Basic Base64 encoded userid and password combination Not recommended because the password is included in every request.
    API key authorization

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

    Example:

    Authorization header: "Apikey {YOUR_APIKEY}"

    Basic authorization

    Basic authorization type can be used in situations when the API key is not available. For example, API methods for generating API keys should be authenticated with the Basic type.

    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.
    • Encoded string is added as credentials after the "Basic" type.
  3. Example:

    Userid: "citcall"
    Password: "citcall"

    Concatenated string: "citcall:citcall"

    Base64 encoded string: "Y2l0Y2FsbDpjaXRjYWxs"

    Authorization header: "Basic Y2l0Y2FsbDpjaXRjYWxs"

API reference

Asynchronous Misscall


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

				
curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Apikey {YOUR_APIKEY}' \
 -d '{
 	"msisdn":"6281234567890",
 	"gateway":"0"
 }' http://104.199.196.122/gateway/v3/asynccall

				
<?php
$apikey = '{YOUR_APIKEY}';

$base_url = 'http://104.199.196.122/gateway';
$version = '/v3';
$action = '/asynccall';

$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: Apikey '. $apikey,
	'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("http://104.199.196.122/gateway/v3/asynccall")
.header("content-type","application/json")
.header("Authorization","Apikey {YOUR_APIKEY}")
.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", "http://104.199.196.122/gateway/v3/asynccall");
xhr.setRequestHeader("content-type", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "Apikey {YOUR_APIKEY}");

xhr.send(data);

				

The above command returns JSON structured like this:


{
	"rc": 0,
	"trxid": "20170709083044690027711524",
	"msisdn": "+6281234567890",
	"token": "622130401234",
	"gateway": 0
}

				

You can use our API to provide miscall to the MSISDN

HTTP Request

POST http://104.199.196.122/gateway/v3/asynccall

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
retry int Retry Sequence (0,1,2,3,4) Required
callback_url uri Webhook URL where delivery status for the result will be posted (Overwrites your default account callback URL). no

Retry description:

Retry 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

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


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

				
curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Apikey {YOUR_APIKEY}' \
 -d '{ 	
 	"msisdn":"6281234567890",
	"senderid":"citcall",
 	"text":"Hello World!"
 }' http://104.199.196.122/gateway/v3/sms

				
<?php
$apikey = '{YOUR_APIKEY}';

$base_url = 'http://104.199.196.122/gateway';
$version = '/v3';
$action = '/sms';

$url = $base_url . $version . $action;
$data = array(
	'msisdn' => '6281234567890',
	'senderid' => 'citcall',
	'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: Apikey '. $apikey,
	'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("http://104.199.196.122/gateway/v3/sms")
.header("content-type","application/json")
.header("Authorization","Apikey {YOUR_APIKEY}")
.body("{\"msisdn\":\"6281234567890\",\"senderid\":\"citcall\",\"text\":\"Hello World!\"}")
.asString();

				
var data = JSON.stringify({
  "msisdn": "6281234567890",
  "senderid": "citcall",
  "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", "http://104.199.196.122/gateway/v3/sms");
xhr.setRequestHeader("content-type"", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "Apikey {YOUR_APIKEY}");

xhr.send(data);

				

The above command returns JSON structured like this:


{
	"rc": 0,
	"info": "Ok",
	"sms_count": 1,	
	"senderid": "citcall",
	"msisdn": "6281234567890",
	"text": "Hello World!",
	"trxid": "20170530152922",
	"currency": "IDR",
	"price": "450"
}

				

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

HTTP Request

POST http://104.199.196.122/gateway/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
msisdn string Destination phone number Required
senderid string Your Registered Senderid Required
text string SMS body (ie: text of the message) Required
callback_url uri Webhook URL where delivery status for the result will be posted (Overwrites your default account callback URL). no

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 OTP


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

				
curl -X POST \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \
 -H 'Authorization: Apikey {YOUR_APIKEY}' \
 -d '{ 	
 	"msisdn":"6281234567890",
	"senderid":"citcall",
 	"text":"Hello World!"
 }' http://104.199.196.122/gateway/v3/smsotp

				
<?php
$apikey = '{YOUR_APIKEY}';

$base_url = 'http://104.199.196.122/gateway';
$version = '/v3';
$action = '/smsotp';

$url = $base_url . $version . $action;
$data = array(
	'msisdn' => '6281234567890',
	'senderid' => 'citcall',
	'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: Apikey '. $apikey,
	'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("http://104.199.196.122/gateway/v3/smsotp")
.header("content-type","application/json")
.header("Authorization","Apikey {YOUR_APIKEY}")
.body("{\"msisdn\":\"6281234567890\",\"senderid\":\"citcall\",\"text\":\"Hello World!\"}")
.asString();

				
var data = JSON.stringify({
  "msisdn": "6281234567890",
  "senderid": "citcall",
  "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", "http://104.199.196.122/gateway/v3/smsotp");
xhr.setRequestHeader("content-type"", "application/json");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("Authorization", "Apikey {YOUR_APIKEY}");

xhr.send(data);

				

The above command returns JSON structured like this:


{
	"rc": 0,
	"info": "Ok",
	"sms_count": 1,	
	"senderid": "citcall",
	"msisdn": "6281234567890",
	"text": "Hello World!",
	"trxid": "20170530152922",
	"currency": "IDR",
	"price": "450"
}

				

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

HTTP Request

POST http://104.199.196.122/gateway/v3/smsotp

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:

Callback

Callback or Delivery Report (DR) are webhooks for delivery statuses: POST requests sent by the Citcall platform either in JSON format to the callback URL configured for your account.

Whenever a request has a new delivery status associated with the delivery stage it is in, Citcall sends out a POST request with the new status to the callback URL.

You can configure your default callback URL for your account at our Dashboard on API menu.

You can also overwrite the default callback URL on by specifying a different callback_url value in your API requests.

Asynchronous Miscall Callback

Parameters of Asynchronous Miscall Callback:

Code Description
rc Response Code. (see appendix)
trxid Unique message ID automatically generated by Citcall.
msisdn End-User mobile number.
via Route used to end-user.
token Number received by the end user
dial_code Dial code. (see appendix)
dial_status Dial Status. (see appendix)
call_status Call Status. (see appendix)
price Price billed by CITCALL for the Transaction
result Result.

SMS Callback

Parameters of SMS Callback:

Code Description
trxid Unique message ID automatically generated by Citcall.
result The status of the message
description Description of the result.
reportedDate Time stamp of reported message. (yyyy-mm-dd hh:mm:ss)
currency Billing currency for price.
price Price billed by CITCALL for the Transaction

SMS OTP Callback

Parameters of SMS OTP Callback:

Code Description
trxid Unique message ID automatically generated by Citcall.
result The status of the message
description Description of the result.
reportedDate Time stamp of reported message. (yyyy-mm-dd hh:mm:ss)
currency Billing currency for price.
price Price billed by CITCALL for the Transaction

Response Code

Response Code Description
0Success or Procesed.
6unknown error / failed
7Invailid Gateway
14insuficient amount
34Service temporary unavialable
42invalid msisdn
43invalid sms content
44senderid closed
66Maintanance in progress
76Wrong Password
77userid not found
78Data not found!
79Invalid token
80Expired token
81maximum try reached!
88missing parameter
96apikey not found or non active
97invalid json format
98Authorazation failed
99wrong method

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.

android auto-verify

You can check our GIthub repository to see our sample android auto-verify. click here to see our android auto-verify repository.

android permission guide

You can check our android permission guide. click here to see our.