SMS Gateway Developers' API
Table of Contents
- 1.0 Introduction
- 2.0 SMS Automation
- 3.0 Contacts Manager/Automation
- 4.0 Campaigns (Receiving & Processing SMS)
- Disclaimer
1.0 Introduction
Typical credentials as follows:
sub_account: 001_0
sub_account_pass: MyMainPa$$
Interaction of this sort might be useful to those desiring to automate SMS sending, fetch the information about sent messages, or pull SMS log into a third party program.
This document is intended to be utilized by technical personnel with programming knowledge; specifically with a working knowledge of HTML forms and JSON.
NOTE: Examine your automation program closely for problems. You are just as responsible for CGSMS commands initiated by an automation program as if you had performed the action manually.
1.1 Automation Details
In the following sections, you will find the parameters for using the API and some sample codes.All API request must be sent to
http://cheapglobalsms.com/api_v1
via HTTP POST or GET method and the response will be returned in a JSON format.NOTE: If for any request, the
error
key is present in the JSON response, then the process was NOT successful, and the value of error
key is the description of what went wrong.2.0 SMS Automation
2.1 Sending SMS
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be send_sms |
send_sms |
message | The message to be sent. | Hello, there will be a meeting today by 12 noon. |
recipients |
The recipient's phone numbers. Multiple numbers can be separated by comma (,).
Any mobile numbers starting with zero will have the zero stripped and replaced with the sub-account's default dial code. If the mobile number does not start with a zero, the default dial code will not be applied. E.G if the sub-account's default dial code is '+234', 08086689567,+2348094309926,4478128372838 will be converted to, 2348086689567,2348094309926,4478128372838 |
+2348094309926 |
Optional Fields | ||
type | 0 means normal sms, while 1 means flash-message. If this was not supplied, the message will be assumed to be normal SMS. |
0 |
unicode | 0 means non-unicode sms, while 1 means that the message contains some special characters (e.g chinese, korean,...) that must be preserved (hence the character encoding of the HTTP request is also UTF-8) Please note that when a message is in unicode format, the character limits of the messages reduces to 72 characters per page. |
0 |
route | 0 means standard route, 1 means financial route, 2 means corporate route TIPS: TIPS: While using CORPORATE ROUTE helps your budget (economizing by sending through standard channel if the destination has already been found to be unrestrictive). FINANCIAL ROUTE doesn't do such fallback (typically used for OTP/Transactional messages). | 0 |
sender_id | What will appear to the recipient as the sender of the SMS. 3 to 11 characters (or 3 to 14 digits if numeric). If this was not supplied, the sub-account's default sender_id will be used. |
President |
default_dial_code | The number that will replace the leading-zero on the recipient's phone number. If this was not supplied, the sub-account's default_dial_code will be used. |
234 |
send_at | The message will be on queue, to be sent on the specified date. If this was not supplied, or if the value is a past date, the message will be sent immediately. |
2016-04-22 13:45
or
2016-04-22
or 13:45 |
timezone_offset | The timezone to be used for send_at. If this was not supplied, the sub-account's timezone_offset will be used. |
+1 |
contact_groups | Includes all numbers from the supplied contact groups of the sub-account with the recipients | default,My Customers |
ignore_groups | Excludes all numbers that appears in supplied contact groups of the sub-account from the recipients | My Customers,My Customers2 |
contacts |
A JSON Array of contacts, E.G: [{"phone":"+2348093216754","firstname":"Pearl"},{"phone":"08086689567","firstname":"Ibukun","lastname":"Oladipo","group_name":"Client","extra_data":"USER001"},{"phone":"+2348094309926","override_message":"Hello, bro. Please be around before 11:00am","override_date_time":"2016-04-22 09:30"}] ** 'phone' is the only compulsory field in a contact, when sending contacts in JSON format.
** If you include 'override_message' in a contact when sending message, it is the override_message that will be sent to that contact instead of the original message.
** If you include 'override_date_time' in a contact, message will rather be sent to the contact at the supplied override_date_time.
** If you include 'extra_data' (maxmum of 60 characters) in a contact when sending message, the value of the extra_data you supplied will be available in the record of the message when you later fetch_sms.
|
|
save_as | If this is supplied, the recipient phone number(s), will be saved under the group-name; specified as the value of this field, otherwise the numbers will not be saved to contacts | default |
callback_url |
If a url-encoded, valid url is specified, the delivery report will be sent as an encoded string of JSON Array, in an HTTP POST request to this supplied URL; under a POST key 'result'. (typically $_POST['result'] in php)
Sample format of the JSON string posted to the callback_url: [ { "sms_id":"137072", "batch_id":"1_1_1462391634", "units":1, "pages":1, "status":2, "status_msg":"DELIVERED", "info":"Message delivered to handset", "extra_data":"" },... ] |
http%3A%2F%2Fcheapglobalsms.com%2Fprocess_sms_callback |
NOTE: All duplicate numbers will be automatically removed for you and SMS will be sent to unique recipients only. |
Sample codes for sending SMS
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=send_sms&sender_id=President&message=Hello%2C+there+will+be+a+meeting+today+by+12+noon.&recipients=08086689567,2348094309926
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0Rd', 'action'=>'send_sms', 'sender_id'=>'President', 'recipients'=>'08086689567,2348094309926', 'message'=>"Hello, there will be a meeting today by 12 noon." ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { $msg="SMS sent to ".$json['total']." recipient(s)."; $sms_batch_id=$json['batch_id']; } } echo $msg; ?>
send_sms
request will be a JSON Object, containing the batch_id, and the total number of recipient numbers that are successfully parsed.
{"batch_id":"1_1_1437039374","total":"2"}Below is a sample JSON response to a failed process:
{"error":"insufficient credit","error_code":"1"}
2.2 Fetch SMS information
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be fetch_sms |
fetch_sms |
Filters (Optional Fields)
Only those SMS that matches the specified criteria will be returned.
| ||
perpage |
To fetch large records, it's essential to paginate. If supplied, maximum is 300 while minimum is 1. |
100 |
p | This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. | 1 |
batch_id | The batch_id returned from a send_sms action. |
1_1_1437039374 |
sms_ids | If the sms_id of the message(s) were already known in advanced, they can be used for filtering. | 572,228 |
stage | This can be pending, sent or failed. | sent |
status |
The specific (numerical) status of the SMS. Possible statuses and their meanings are -4 = UNDELIVERABLE, -3 = EXPIRED, -2 = REJECTED, -1 = FAILED, 0 = PENDING, 1 = ACCEPTED, 2 = DELIVERED The stage and status key can not be used together (stage key will be ignored) |
2 |
type | 0 means normal sms, while 1 means flash-message. | 0 |
recipient | The recipient number, to which the SMS had been sent, e.g 08094309926 or 2348094309926 or +2348094309926 | 2348094309926 |
sender_id | 3 to 11 characters (or 3 to 14 digits if numeric) | President |
search_term | If supplied, the records that contains either the recipient, sender_id or message body that 'roughly' matches the supplied value will be returned | President 2348094309926 |
start_date | The minimum: time sent, or scheduled time, of the messages to be returned. |
2016-04-22 13:45
or
2016-04-22
|
end_date | The maximum: time sent, or scheduled time, of the messages to be returned. |
28-04-2016 13:45
or
28-04-2016
|
Sample Codes for fetching SMS records
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_sms&batch_id=1_1_1437039374
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0Rd', 'action'=>'fetch_sms', 'batch_id'=>'1_1_1437039374', //'stage'=>'sent' ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { //you can now do whatever with the records //(e.g check the recipient, fetch the next page or display a message) $msg=$json['total']." SMS records, page ".$json['p']." of ".$json['totalpages']; $msg.= "<br/> <ol>"; foreach($json['records'] as $sms) { $msg.= "<li>To: ".$sms['recipient']."<br/> ".$sms['message']."</li>"; } $msg.= "</ol>"; } } echo $msg; ?>
Below is a sample successful process's response.
{ "total":19,"totalpages":1,"p":1,"perpage":100,"timezone_offset":"1", "records":[ {"sms_id":"68", "sender":"ibukun", "recipient":"2022451175", "message":"checking wrong number", "sub_account_id":"1", "user_id":"1", "time_scheduled":"1448224505", "batch_id":"1_1_1448224505", "status":"-2", "type":"0", "units":"1", "reference":"", "time_submitted":"1448224505", "time_sent":"1448224505", "units_confirmed":"0", "locked":"1", "info":"Network is forbidden", "firstname":"Gotv", "lastname":"NUMBER", "group_name":"default", "status_msg":"REJECTED", "submitted_at":"2015-11-22 20:35", "scheduled_to":"2015-11-22 20:35", "sent_at":"2015-11-22 20:35", "extra_data":"" }, {"sms_id":"67","sender":"ibukun","recipient":"2348094309926","message":"hello; how're you doing","sub_account_id":"1","user_id":"1","time_scheduled":"1448223878","batch_id":"1_1_1448223878","status":"2","type":"0","units":"2","reference":"","time_submitted":"1448223878","time_sent":"1448223878","units_confirmed":"1","locked":"0","info":"Message delivered to handset","firstname":null,"lastname":null,"group_name":null,"status_msg":"DELIVERED","submitted_at":"2015-11-22 20:24","scheduled_to":"2015-11-22 20:24","sent_at":"2015-11-22 20:24","extra_data":""}, ... ,"filter":{"sub_account_id":"1","batch_id":"","sms_id":"","sms_ids":"","type":"","recipient":"","search_term":"","sender_id":"","stage":"","start_date":"","end_date":"","p":"","perpage":100,"offset":0} }
For a successfully submitted SMS, the 'status' (in the JSON Object) has following meanings
Code | Status | Details |
---|---|---|
-4 | UNDELIVERABLE | The message was undeliverable |
-3 | EXPIRED | Message validity period has expired. (e.g phone off or not in coverage area) |
-2 | REJECTED | The message was rejected. The message was undeliverable. |
-1 | FAILED | An issue occured while attempting to send the SMS. |
0 | PENDING | This message is on queue, to be sent. |
1 | SENT | The message was accepted by the Network server. Awaiting delivery status. |
2 | DELIVERED | Message was delivered to destination. |
2.3 Get SMS balance and sub-account information
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be account_info |
account_info |
Sample Codes for getting SMS balance
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=account_info
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0R', 'action'=>'account_info' ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { $msg="Balance: ".$json['balance']; } } echo $msg; ?>
Below is a sample successful process's response.
{"sub_account_id":"1","sub_account":"mysub1","user_id":"1","balance":"1209","notification_email":"example@gmail.com","default_dial_code":"234","timezone_offset":"1","default_sender_id":"tormuto"}Below is a sample response to a failed process, a JSON Object
{"error":"Incorrect sub_account name or password","error_code":"4"}
2.4 Stop SMS, Delete SMS or Get Total SMS Units Spent
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
NOTE: Only the SMS that are still on schedule can be stopped.
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key can be either stop_sms , delete_sms or get_total_units |
stop_sms |
Optional Filters
IMPORTANT: When deleting or stopping SMS, you must specify some kind of filter(s), otherwise your entire sms records will be premanently deleted/stopped | ||
batch_id |
Typically a batch_id returned from a send_sms action.An attempt will be made to stop all SMS in this batch. |
1_1_1437039374 |
sms_ids | Typically one or more sms_id from the SMS objects array returned from a fetch_sms action. |
572,228 |
stage | This can be pending, sent or failed. | sent |
status |
The specific (numerical) status of the SMS. Possible statuses and their meanings are -4 = UNDELIVERABLE, -3 = EXPIRED, -2 = REJECTED, -1 = FAILED, 0 = PENDING, 1 = ACCEPTED, 2 = DELIVERED The stage and status key can not be used together (stage key will be ignored) |
2 |
type | 0 means normal sms, while 1 means flash-message. | 0 |
recipient | The recipient number, to which the SMS had been sent, e.g 08094309926 or 2348094309926 or +2348094309926 | 2348094309926 |
sender_id | 3 to 11 characters (or 3 to 14 digits if numeric) | President |
start_date | The minimum: time sent, or scheduled time, of the messages to be returned. |
2016-04-22 13:45
or
2016-04-22
|
end_date | The maximum: time sent, or scheduled time, of the messages to be returned. |
28-04-2016 13:45
or
28-04-2016
|
Sample Codes for stopping SMS from sending.
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=stop_sms&batch_id=1_1_1437039374
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0R', 'action'=>'stop_sms', 'batch_id'=>'1_1_1437039374' ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { $msg=$json['total']." messages stopped"; } } echo $msg; ?>
Below is a sample successful process's response.
{"total":"10"}Below is a sample response to a failed process, a JSON Object
{"error":"no record found.","error_code":"10"}
2.5 Get SMS delivery statistics
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be get_delivery_stat |
get_delivery_stat |
batch_id | The batch id for consideration | 1_1_1462391634 |
Sample Codes for getting SMS delivery statistics
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=get_delivery_stat&batch_id=1_1_1462391634
<?php $batch_id='1_1_1462391634'; $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0R', 'action'=>'get_delivery_stat', 'batch_id'=>$batch_id ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { //you can perform any operation on the available data now print_r($json); } } echo $msg; ?>
Below is a sample successful process's response.
{"UNDELIVERABLE":{"sms_count":0,"sms_units":0},"EXPIRED":{"sms_count":0,"sms_units":0},"REJECTED":{"sms_count":0,"sms_units":0},"FAILED":{"sms_count":0,"sms_units":0},"PENDING":{"sms_count":13,"sms_units":4},"ACCEPTED":{"sms_count":0,"sms_units":0},"DELIVERED":{"sms_count":0,"sms_units":0},"total":{"sms_count":13,"sms_units":4}}Below is a sample response to a failed process, a JSON Object
{"error":"No record found","error_code":11}
3.0 Contacts Manager/Automation
3.1 Save Contacts/Phone Numbers
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be save_contacts |
save_contacts |
Optional/Elective Fields
At least one of 'phone_numbers' or 'contacts' must be supplied.
|
||
phone_numbers |
A string of phone numbers (multiple numbers can be separated by comma)
E.G: 08086689567,+2348094309926,4478128372838 Any mobile numbers starting with zero will have the zero stripped and replaced with the sub-account's default dial code.
|
+2348094309926 |
contacts |
A JSON Array of contacts, E.G: [{"phone":"08086689567","firstname":"Ibukun","lastname":"Oladipo","group_name":"Client"},{"phone":"+2348094309926","firstname":"Pearl"}] 'phone' is the only compulsory field, when sending contacts in JSON format.
|
|
group_name | All the supplied numbers/contacts will be saved under this group_name, except those contacts in JSON Array, that also has a group_name defined. If group_name was not supplied via any means, the contacts will automatically be added under 'default' group_name. |
My Customers |
Sample codes for saving contacts
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=save_contacts&group_name=My+Customers&contacts=08086689567,2348094309926
<?php $contacts=array( 0=>array('phone'=>'08086689567','firstname'=>'Ibukun','lastname'=>'Oladipo','group_name'=>'Client'), 1=>array('phone'=>'+2348094309926','firstname'=>'Pearl'), ); $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0Rd', 'action'=>'save_contacts', 'contacts'=>json_encode($contacts), 'group_name'=>'My Customers', ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { $msg=$json['total']." contact(s) has been saved."; } } echo $msg; ?>
save_contacts
request will be a JSON Object, containing the batch_id, and the total number of recipient numbers that are successfully parsed.
{"total":"2"}Below is a sample JSON response to a failed process:
{"error_code":4,"error":"Incorrect sub_account name or password."}
3.2 Fetch Contacts
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be fetch_contacts |
fetch_contacts |
Filters (Optional Fields)
Only those contacts that matches the specified criteria will be returned.
| ||
group_name | Return only those contacts in this group | My Customers |
search_term | This can be any of phone number, firstname, lastname to find, e.g: 08094309926 or ibukun or 08094309926 ibukun | 2348094309926 |
contact_ids | If the specific contact_id(s) to be fetch were already known, it can be used for filtering. | 5,7 |
perpage |
To fetch large records, it's essential to paginate. If supplied, maximum value is 300 while minimum is 1. |
100 |
p | This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. | 1 |
Sample Codes for fetching contacts.
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_contacts&group_name=My+Customers
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0Rd', 'action'=>'fetch_contacts', 'group_name'=>'My Customers', 'search_term'=>'ibukun' ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { //you can now do whatever with the contact records returned //(e.g check list the contacts, or even fetch the next page by running the same request with p=1) $msg=$json['total']." Contacts in total, page ".$json['p']." of ".$json['totalpages']; $msg.= "<br/> <ol>"; foreach($json['contacts'] as $contact) { $msg.= "<li>+".$contact['phone']."<br/> ".$contact['firstname']." ".$contact['lastname']." (".$contact['group_name'].")</li>"; } $msg.= "</ol>"; } } echo $msg; ?>
Below is a sample successful process's response.
{ "filter":{"user_id":"1","sub_account_id":"1","perpage":10,"group_name":"My Customers","search_term":null,"offset":0}, "total":2,"p":1,"totalpages":1, "records":[{"contact_id":"20","user_id":"1","sub_account_id":"1","phone":"2348086689567","firstname":"","lastname":"","group_name":"My Customers","time":"1445721399"}, {"contact_id":"21","user_id":"1","sub_account_id":"1","phone":"2348094309926","firstname":"","lastname":"","group_name":"My Customers","time":"1445721399"} ] }
3.3 Get Contact Groups
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be get_contact_groups |
get_contact_groups |
Sample Codes for getting sub-account's contact groups
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=get_contact_groups
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0R', 'action'=>'get_contact_groups' ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { $msg="Balance: ".$json['balance']; } } echo $msg; ?>
Below is a sample successful process's response.
{"contact_groups":{"My Customers":"2","default":"4"}}
3.4 Delete Contacts
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be delete_contacts |
delete_contacts |
Filters (Optional Fields)
ALL those contacts that matches the specified criteria will be deleted.
| ||
group_name | Return only those contacts in this group | My Customers |
search_term | This can be any of phone number, firstname, lastname to find, e.g: 08094309926 or ibukun or 08094309926 ibukun | 2348094309926 |
contact_ids | Typically one or more contact_id, from the array of contact objects returned from a fetch_contacts action. |
5,7 |
Sample Codes for deleting contact(s).
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=delete_contacts&contact_ids=5%2C7
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0R', 'action'=>'delete_contacts', 'contact_ids'=>'5,7' ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { $msg="Total deleted contacts: ".$json['total']; } } echo $msg; ?>
Below is a sample successful process's response.
{"total":"4"}Below is a sample response to a failed process, a JSON Object
{"error":"No contact_ids supplied to be deleted","error_code":"7"}
4.0 Campaigns (Receiving & Processing SMS)
4.1 Callback Data
The following parameters will be sent, through HTTP POST request to the callback_url that you specifyHTTP POST KEY | Description | Example Value |
---|---|---|
sender | The phone number that sent the SMS (without the leading +) | 2348093216754 |
recipient | Your phone number (that has been configured here), to which the SMS has been sent | 2348030000000 or 23451007 |
campaign_id | ID of the campaign that captured/intercept this message for you | 121 |
message | The full content of the message sent | STOP SERVICE1 James Richard |
pages | Number of SMS pages covered by this message | 1 |
keyword | The keyword that you specified while setting up the campaign | STOP |
sub_keyword | The keyword that you specified while setting up the campaign | SERVICE1 |
clean_message | The remaining part of the message, after the keyword and sub_keyword (if available) | James Richard |
4.2 Fetching or Deleting Inbox Message
The following parameters can be sent, through HTTP GET or POST request to the URL:http://cheapglobalsms.com/api_v1
Input Field Name | Description | Example Value |
---|---|---|
sub_account | A sub_account name that you have created. | 001_mysub1 |
sub_account_pass | Sub account password | pa55w0Rd |
action | The value for this key must be fetch_inbox or delete_inbox |
fetch_inbox |
Filters (Optional Fields)
When fetching messages, only those messages that matches the specified criteria will be returned.
IMPORTANT: When deleting or stopping SMS, you must specify some kind of filter(s), otherwise your entire sms records will be premanently deleted/stopped
| ||
perpage |
To fetch large records, it's essential to paginate. If supplied, maximum is 300 while minimum is 1. |
100 |
p | This is only useful when paginating. It indicates the current page (e.g 1st page) of the record to be fetched. | 1 |
campaign_id | The campaign_id that captured the messages. | 1411 |
message_ids | If the message_id of the message(s) were already known in advanced, they can be used for filtering. | 572,228 |
keyword | This keywords that captured the messages | STOP |
recipient | The number you configured, to which the message was sent, e.g 08094309926 or 2348094309926 or +2348094309926 | 2348094309926 |
sender | The number that sends in the message | 2348094309923 |
search_term | If supplied, the records that contains either the recipient, sender or message body that 'roughly' matches the supplied value will be returned | STOP SERVICE1 |
start_date | The minimum time-received of the messages to be returned. |
2016-04-22 13:45
or
2016-04-22
|
end_date | The maximum time received of the messages to be returned. |
28-04-2016 13:45
or
28-04-2016
|
Sample Codes for fetching inbox messages
http://cheapglobalsms.com/api_v1?sub_account=001_mysub1&sub_account_pass=pa55w0Rd&action=fetch_inbox&campaign_id=1411
<?php $post_data=array( 'sub_account'=>'001_mysub1', 'sub_account_pass'=>'pa55w0Rd', 'action'=>'fetch_inbox', 'batch_id'=>'1411', ); $api_url='http://cheapglobalsms.com/api_v1'; $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $api_url); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); $response = curl_exec($ch); $response_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); if($response_code != 200)$response=curl_error($ch); curl_close($ch); if($response_code != 200)$msg="HTTP ERROR $response_code: $response"; else { $json=@json_decode($response,true); if($json===null)$msg="INVALID RESPONSE: $response"; elseif(!empty($json['error']))$msg=$json['error']; else { //you can now do whatever with the records //(e.g check the sender, fetch the next page or display a message) $msg=$json['total']." messages, page ".$json['p']." of ".$json['totalpages']; $msg.= "<br/> <ol>"; foreach($json['records'] as $message) { $msg.= "<li>From: ".$sms['sender']."<br/> ".$sms['message']."</li>"; } $msg.= "</ol>"; } } echo $msg; ?>
Below is a sample successful process's response.
{ "total":19,"totalpages":1,"p":1,"perpage":100,"timezone_offset":"1", "records":[ {"sms_id":"68", "sender":"ibukun", "recipient":"2022451175", "message":"checking wrong number", "sub_account_id":"1", "user_id":"1", "time_scheduled":"1448224505", "batch_id":"1_1_1448224505", "status":"-2", "type":"0", "units":"1", "reference":"", "time_submitted":"1448224505", "time_sent":"1448224505", "units_confirmed":"0", "locked":"1", "info":"Network is forbidden", "firstname":"Gotv", "lastname":"NUMBER", "group_name":"default", "status_msg":"REJECTED", "submitted_at":"2015-11-22 20:35", "scheduled_to":"2015-11-22 20:35", "sent_at":"2015-11-22 20:35", "extra_data":"" }, {"sms_id":"67","sender":"ibukun","recipient":"2348094309926","message":"hello; how're you doing","sub_account_id":"1","user_id":"1","time_scheduled":"1448223878","batch_id":"1_1_1448223878","status":"2","type":"0","units":"2","reference":"","time_submitted":"1448223878","time_sent":"1448223878","units_confirmed":"1","locked":"0","info":"Message delivered to handset","firstname":null,"lastname":null,"group_name":null,"status_msg":"DELIVERED","submitted_at":"2015-11-22 20:24","scheduled_to":"2015-11-22 20:24","sent_at":"2015-11-22 20:24","extra_data":""}, ... ,"filter":{"sub_account_id":"1","batch_id":"","sms_id":"","sms_ids":"","type":"","recipient":"","search_term":"","sender":"","stage":"","start_date":"","end_date":"","p":"","perpage":100,"offset":0} }
Disclaimer
This product is supplied as-is, with no warranties express or implied. Use this documentation at your own risk.
Error Codes and Descriptions
Error Code | Description |
---|---|
1 | sub_account not supplied |
2 | sub_account_pass not supplied |
3 | action not supplied |
4 | Incorrect sub_account name or password |
5 | The sub-account is currently disabled |
6 | Invalid action |
7 | missing request parameter |
8 | incorrect request parameter |
9 | confusing request parameters |
10 | no record found |
11 | operation failed |