ENTERPRISE BULK SMS. SMSHUB HTTP API Specification V3.0 Released 9 th August 2013

Transcription

1 ENTERPRISE BULK SMS SMSHUB HTTP API Specification V3.0 Released 9 th August

2 1.0 INTRODUCTION This document is meant to provide help and illustrations to users who wish to delivery SMS using Our SMS Gateway via the HTTP Protocol. Sending messages via the HTTP API is one of the best and the quickest ways to deliver SMS messages. This document gives a detailed explanation of using the gateway through HTTP API. All requests are to be made via API CALLS 2.1 MESSAGING The following table gives the list of parameters required for sending message through The X-Wireless Bulk SMS Gateway using HTTP API. S/N PARAMETER NAME PARAMETER VALUE PARAMETER DESCRIPTION 1 method compose Sets API for Composing new SMS 2 username {username} Your username 3 password {password} your password 4 sender {sender_id} Sender ID (only 6character) 5 to {recipient} Destination Mobile Number 6 message {message} Message to be sent 7 INDIAN (optional) 1 (true) or 0 (false) For INDIAN Routing. This defaults to 0 8 reqid (optional) 1 (true) or 0 (false) Request Message ID 9 format (optional) text (serialized), json, API output format. This defaults to xml json 10 sendondate (optional) YY-MM-DD HH:MM:SS Message scheduler 11 source (optional) numberlist, group Tells the API where to get the list of recipients. This defaults to numberlist 12 groupid {groupid} Group ID. This should be specified when the value of source is group 2

3 Sending to Single Recipient To send a message to a single recipient, you are to supply a mobile number to the to parameter, i.e. to= Example: XX>&password=<your_password>&sender=<mysenderid>&to=<myrecipient>&messa ge=hello+test+message&reqid=1&format={json text} Sending to Multiple Recipients (Bulk Messaging) To send a message to multiple recipients, you are to supply multiple mobile numbers separated with a coma (,), i.e. to= , , Example: r_password>&sender=<mysenderid>&to= , , &message=Hello+Test+Mess age&reqid=1&format={json text}

4 JSON OUTPUT {"error":1,"status":" error message here "} {"error":0,"status":"message Sent Successfully"} Success (reqid=1): {"error":0,"status":"message Sent Successfully","data":{"msg_id":" bf b ","SenderId":"Christian","linecount":"1","billcredit":"1.50","message":"Testing","sen dondate":" :00:00","seq_id":{"1":{"valid":"true","billcredit":"1.50","id_provider":"9","providerkey":"MTN Nigeria","regionKey":0,"originalnumber":" ","validnumber":" ","mn pid":"46","dlr_seq":1}}}} XML OUTPUT <error>1</error> <status> error message here </status> <error>0</error> <status>message Sent Successfully</status> Success (reqid=1): <error>0</error> <status>message Sent Successfully</status> <data> <msg_id> bf9-4318cce </msg_id> <SenderId>Christian</SenderId> <linecount>1</linecount> <billcredit>1.50</billcredit> <message>testing</message> <sendondate> :01:00</sendondate> <seq> 4

5 </seq> </data> <seq_id> <valid>true</valid> <billcredit>1.50</billcredit> <id_provider>9</id_provider> <providerkey>mtn Nigeria</providerkey> <regionkey>0</regionkey> <originalnumber> </originalnumber> <validnumber> </validnumber> <mnpid>46</mnpid> <dlr_seq>1</dlr_seq> </seq_id> TEXT OUTPUT a:2:{s:5:"error";i:1;s:6:"status";s:25:" error message here ";} a:2:{s:5:"error";i:0;s:6:"status";s:25:"message Sent Successfully";} Success (reqid=1): a:3:{s:5:"error";i:0;s:6:"status";s:25:"message Sent Successfully";s:4:"data";a:7:{s:6:"msg_id";s:47:" bf9-4360cb fa ";s:8:"SenderId";s:9:"Christian";s:9:"linecount";s:1:"1";s:10:"billcredit";s:4:"1. 50";s:7:"message";s:7:"Testing";s:10:"sendondate";s:19:" :08:00";s:6:"seq_id";a:1:{i:1;a:9:{s:5:"valid";s:4:"true";s:10:"billcredit";s:4:"1.50";s:11: "id_provider";s:1:"9";s:11:"providerkey";s:11:"mtn Nigeria";s:9:"regionKey";i:0;s:14:"originalnumber";s:10:" ";s:11:"validnumbe r";s:14:" ";s:5:"mnpid";s:2:"46";s:7:"dlr_seq";i:1;}}}} 5

6 2.2 SHOW ROUTES The following table gives the list of parameters required for getting all route types enabled for an account via Our Gateway using the HTTP API. S/N PARAMETER NAME PARAMETER VALUE PARAMETER DESCRIPTION 1 method show_route Sets API for displaying list or Route Types 2 username {username} Your Username 3 password {password} Your Password 4 format (optional) text (serialized), json, API output format. This defaults to xml json Example: ndex.php?method=show_route&username=<dddd>&pass word=<your_password>&format={json text} JSON OUTPUT {"error":1,"status":" error message here "} {"error":0,"status":"query Successful!","data":{"id":"3","name":"Alpha SS7"}} XML OUTPUT <error>1</error> <status> error message here </status> <error>0</error> 6

7 <status>query Successful!</status> <data> <route> <id>3</id> <name>alpha SS7</name> </route> </data> TEXT OUTPUT a:2:{s:5:"error";i:1;s:6:"status";s:30:" error message here ";} a:3:{s:5:"error";i:0;s:6:"status";s:17:"query Successful!";s:4:"data";a:2:{i:3;s:9:"Alpha SS7";i:16;s:10:"Naija Plus";}} 2.3 CHECK ACCOUNT BALANCE The following table gives the list of parameters required for retrieving account balance via Our Gateway using the HTTP API. S/N PARAMETER NAME PARAMETER VALUE PARAMETER DESCRIPTION 1 method credit_check Sets API for displaying balance 2 username {username} Your Username 3 password {password} Your Password 4 format (optional) text (serialized), json, API output format. This defaults to xml json Example: ndex.php?method=credit_check&username=<dddd>&pass word=<your_password>&format={json text} 7

8 JSON OUTPUT {"error":1,"status":" error message here "} {"error":0,"status":"query Successful!","credits":{"3":{"routtype":"Alpha SS7","credit":86.94,"validity":"13141"}}} SAMPLE XML OUTPUT <error>1</error> <status> error message here </status> <error>0</error> <status>query Successful!</status> <data> <credit> <routeid>16</routeid> <routtype>naija Plus</routtype> <credit>3764</credit> <validity>254</validity> </credit> </data> TEXT OUTPUT a:2:{s:5:"error";i:1;s:6:"status";s:30:" error message here ";} a:3:{s:5:"error";i:0;s:6:"status";s:17:"query Successful!";s:4:"data";a:1:{i:16;a:3:{s:8:"routtype";s:10:"Naija Plus";s:6:"credit";d:3764;s:8:"validity";s:3:"254";}}}

9 2.4 SHOW DELIVERY REPORT The following table gives the list of parameters required for retrieving delivery reports via Our Gateway using the HTTP API. S/N PARAMETER NAME PARAMETER VALUE PARAMETER DESCRIPTION 1 method show_dlr Sets API for displaying balance 2 username {username} Your Username 3 password {password} Your Password 4 format (optional) text (serialized), json, API output format. This defaults to xml json 5 msg_id {msg_id) Message ID Example: ndex.php?method=show_dlr&username=<ddd>&password =<your_password>&msg_id=<message+id>&seq_id=<1,2> &limit=<0,10>&format={json text} JSON OUTPUT {"error":1,"status":" error message here "} {"error":0,"status":"query Successful!","data":{"msg_id":" bf9-4318cce ","sender":"Christian","linecount":"1","billcredit":"1.50","refundcredit":"0.00 ","sendondate":" :01:00","seq_id":{"1":{"sender":"Christian","validnumber":" ","linecou nt":"1","billcredit":"1.50","refundcredit":"0.00","sendondate":" :01:00","status":"Successfully Delivered","statusdate":" :01:41"}}}} 11

10 XML OUTPUT <error>1</error> <status> error message here </status> <error>0</error> <status>query Successful!</status> <data> <msg_id> bf9-4318cce </msg_id> <sender>christian</sender> <linecount>1</linecount> <billcredit>1.50</billcredit> <refundcredit>0.00</refundcredit> <sendondate> :01:00</sendondate> <seq> <seq_id> <sender>christian</sender> <validnumber> </validnumber> <linecount>1</linecount> <billcredit>1.50</billcredit> <refundcredit>0.00</refundcredit> <sendondate> :01:00</sendondate> <status>successfully Delivered</status> <statusdate> :01:41</statusdate> </seq_id> </seq> </data> 12

11 TEXT OUTPUT a:2:{s:5:"error";i:1;s:6:"status";s:30:" error message here ";} a:3:{s:5:"error";i:0;s:6:"status";s:17:"query Successful!";s:4:"data";a:7:{s:6:"msg_id";s:47:" bf9-4318cce ";s:6:"sender";s:9:"Christian";s:9:"linecount";s:1:"1";s:10:"billcredit";s:4:"1.5 0";s:12:"refundcredit";s:4:"0.00";s:10:"sendondate";s:19:" :01:00";s:6:"seq_id";a:1:{i:1;a:8:{s:6:"sender";s:9:"Christian";s:11:"validnumber";s:13: " ";s:9:"linecount";s:1:"1";s:10:"billcredit";s:4:"1.50";s:12:"refundcredit"; s:4:"0.00";s:10:"sendondate";s:19:" :01:00";s:6:"status";s:22:"Successfully Delivered";s:10:"statusdate";s:19:" :01:41";}}}} For More Details Kindly Mail us at or call :