NOTE: Examine your automation program closely for problems. You are just as responsible for Best SMS Gateway commands initiated by an automation program as if you had performed the action manually.
http://bestsmsgateway.com/api_v1
via HTTP POST or GET method and the response will be returned in a JSON format.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.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; ?>
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"}
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
|
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; ?>
{ "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} }
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. |
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 |
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; ?>
{"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"}
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 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
|
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; ?>
{"total":"10"}Below is a sample response to a failed process, a JSON Object
{"error":"no record found.","error_code":"10"}
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 |
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; ?>
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."}
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 |
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; ?>
{ "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"} ] }
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 |
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; ?>
{"contact_groups":{"My Customers":"2","default":"4"}}
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 |
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; ?>
{"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"}
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 |