SMS Gateway API for developers

SMS Gateway Developers' API

1.0 Introduction
- 1.1 Automation Details
2.0 SMS Automation
3.0 Contacts Manager/Automation
4.0 Disclaimer

1.0 Introduction

This document describes how to programmatically interact with bestsmsgateway.com (You must have registered, and created a sub-account that you'll use for accessing this API ).

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 bestsmsgateway.com 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://bestsmsgateway.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

This section describes how you can automatically send SMS, fetch SMS information, stop / delete SMS / get total units spent or get the balance and other information of the sub-account.

2.1 Sending SMS

The following parameters can be sent, through HTTP GET or POST request to the URL: http://bestsmsgateway.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,+2348094309000,4478128372838 will be converted to, 2348086689567,2348094309000,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":"John","lastname":"Doe","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' in a contact when sending message, the value of the extra_data you supplied will be availabe 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
NOTE: All duplicate numbers will be automatically removed for you and SMS will be sent to unique recipients only.

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 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://bestsmsgateway.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
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

Plain HTTP
PHP

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 'fetch_sms' request will be a JSON Object, containing the paging information, and an Array SMS objects,
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 is 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 is 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 is 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://bestsmsgateway.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

Plain HTTP
PHP

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 'account_info' request will be a JSON Object, containing the sub-account's full information,
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://bestsmsgateway.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
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.

Plain HTTP
PHP

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 'stop_sms' request will be a JSON Object, containing the total number of messages successfully stopped or deleted (as the case may be).
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"}

3.0 Contacts Manager/Automation

This section describes how you can automatically use CGSMS's contacts management system to store or backup your contacts, fetch/retrieve your contacts, or even delete contacts

3.1 Save Contacts/Phone Numbers

The following parameters can be sent, through HTTP GET or POST request to the URL: http://bestsmsgateway.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":"John","lastname":"Doe","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

Plain HTTP
PHP

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 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://bestsmsgateway.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.

Plain HTTP
PHP

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 'fetch_contacts' request will be a JSON Object, containing the paging information, and an Array contact objects,
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://bestsmsgateway.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

Plain HTTP
PHP

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 'get_contact_groups' request will be a JSON Object, containing 'contact_groups', an object having each contact_group names and their sizes (amount of contact),

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://bestsmsgateway.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).

Plain HTTP
PHP

http://bestsmsgateway.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://bestsmsgateway.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;
?>

The response to a successful 'delete_contacts' request will be a JSON Object, containing the total number of deleted contacts.
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 Disclaimer

The Author [Tormuto Info. Tech.] accepts no responsibility for damages to persons, property or data incurred through the use or misuse of these API and scripts. To the maximum extent permitted by law, in no event shall the Author [Tormuto Info. Tech.] be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use or inability to use this API, even if the Author has been advised of the possibility of such damages.
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

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered

A PHP Error was encountered