MOBI-APPS TELECOMS

Bringing fun back into people’s lives while adding value to them…

Sms Apis

Mobi-Apps SMS API
Description

This document describes the base API interfaces which can be used with Mobi-apps.
The API is currently only implemented with a JSON wrapper.
These API’s can be accessed with an HTTP client independent of language. We have provided PHP examples to demonstrate the implementation as well as raw HTTP requests in order to assist.
Some general considerations:
= Negative number in status codes indicate an error
= HTTP Keep-Alive is supported and should be used for large numbers of queries.
= Unbilled queries are limited to 10 per minute (message_status, user_get_balance, etc)
 example: The Mobi-apps Java class source is provided for your use or extension (Page 17)
 example: The Mobi-apps PHP class for easy deployment and integration (referenced in examples) (Page 22).

Class Constant Summary

api_result_authentication_failed = -8
api_result_could_not_save = -256
api_result_duplicate_record = -512
api_result_internal_error = -16
api_result_invalid_record = -128
api_result_key_created = 2
api_result_message_sent = 1
api_result_missing_parameter = -4
api_result_no_action_specified = -1
api_result_no_such_action = -2
api_result_ok = 0
api_result_out_of_credit = -64
api_result_routing_error = -32
api_result_timeout = -8192
api_result_too_many_connections = -4096
api_result_user_invalid_affiliate = -1024
api_result_user_no_hlr = -2048
batch_status_busy = 16
batch_status_error = 128
batch_status_filter = 256
batch_status_filtering = 512
batch_status_new = 1
batch_status_parsing = 2
batch_status_parsing_paused = 4
batch_status_paused = 32
batch_status_ready = 8
batch_status_submitted = 64
maximum_affliate_registrations_reached = -2048
message_status_acknowledged = 1
message_status_delivered = 4
message_status_does_not_exist = -1
message_status_failed = 32
message_status_filtered = 64
message_status_internal_failed = 8
message_status_routing_error = 16
message_status_submitted = 2

Method Summary

object address_book_contacts_get_list (string username, string password, int group_id)
object address_book_contact_add (string username, string password, int group_id, string phone_number, [string first_name = ”], [string last_name = ”])
object address_book_contact_delete (string username, string password, int contact_id)
object address_book_contact_update (string username, string password, int contact_id, [string phone_number = null], [string first_name = null], [string last_name = null])
object address_book_groups_get_list (string username, string password)
object address_book_group_add (string username, string password, string name)
object address_book_group_delete (string username, string password, int group_id)
object affiliate_get_default_pricing (string username, string password, string country_code, string currency_code)
object affiliate_list_countries (string username, string password)
object affiliate_register_user (string username, string password, string email_address, string dialling_code, string phone_number, [string user_ip_address = Null], [string user_username = Null], [string user_password = Null], [int campaign_id = Null])
object affiliate_register_user_quick (string username, string password, string email_address, string phone_number, [string ip_address = false], [integer marketing_channel_id = ‘0’])
object affiliate_set_promotion_code (string username, string password, integer user_id, string promotion_code, [integer affiliate_id = null])
object batches_list (string username, string password)
object batch_check_status (string username, string password, int batch_id)
object batch_create (string username, string password, string name, [int throughput = 0], [boolean filter = false], [string file_type = ‘csv’], [string start_time = null])
object batch_start (string username, string password, int batch_id)
object batch_stop (string username, string password, int batch_id)
object execute_multiple (string username, string password)
object get_affiliate_country_info (string username, string password, string ip_address, [boolean return_array = false], [ country_name = false])
object hlr_perform (string username, string password, string number, sring report_url)
object hlr_perform_synchronous (string username, string password, string number)
object inject_lead (string username, string password, integer batch_id, [string number = NULL], enum lead_type)
object list_actions ()
object messages_get (string username, string password, int last_id)
object messages_statistics (string username, string password, [string start_date = NULL], [string end_date = NULL], [string user_id = NULL])
object message_send (string username, string password, string to, string text, [string from = null], [int report_mask = 19], [string report_url = null], [string charset = null], [int data_coding = null], [int message_class = -1], [int auto_detect_encoding = null])
object message_status (string username, string password, string message_id)
object ping ()
object route_check_price (string username, string password, string to)
object user_authorize_application (string application_name, [string icon_url = null], [string return_url = null])
object user_get_api_key (string request_key)
object user_get_balance (string username, string password)
object user_get_info (string username, string password)
object user_get_phone_number (string username, string password)
object user_transfer_funds (string username, string password, string target_username, float amount)

Methods

address_book_contacts_get_list
Gets a list of contacts for a particular group
 example: Generic HTTP Address book usage examples (Page 30)
 example: PHP API Address book usage examples (Page 32)
object address_book_contacts_get_list (string username, string password, int group_id)
 string username
 string password
 int group_id: The ID of the group
address_book_contact_add
Add a contact to a group
 example: Generic HTTP Address book usage examples (Page 33)
 example: PHP API Address book usage examples (Page 35)
object address_book_contact_add (string username, string password, int group_id, string phone_number, [string first_name = ”], [string last_name = ”])
 string username
 string password
 int group_id: The group ID to add the record to
 string phone_number: Phone number of the user
 string first_name: First name of the user (optional)
 string last_name: Last name of the user (optional)
address_book_contact_delete
Delete a contact
 example: Generic HTTP Address book usage examples (Page 36)
 example: PHP API Address book usage examples (Page 38)
object address_book_contact_delete (string username, string password, int contact_id)
 string username
 string password
 int contact_id: The contact ID
address_book_contact_update
Update an existing contact
 example: Generic HTTP Address book usage examples (Page 39)
 example: PHP API Address book usage examples (Page 41)
object address_book_contact_update (string username, string password, int contact_id, [string phone_number = null], [string first_name = null], [string last_name = null])
 string username
 string password
 int contact_id: The contact ID
 string phone_number: The new first name
 string first_name: The new last name
 string last_name: The new phone number
address_book_groups_get_list
Retrieves a list of address book groups
Example output : {“status”:0,”message”:”OK”,”details”:[{“id”:”1″,”name”:”My Friends”}]}
 example: Generic HTTP Address book usage examples (Page 42)
 example: PHP API Address book usage examples (Page 44)
object address_book_groups_get_list (string username, string password)
 string username
 string password
address_book_group_add
Adds a new address book group
 example: Generic HTTP Address book usage examples (Page 42)
 example: PHP API Address book usage examples (Page 44)
object address_book_group_add (string username, string password, string name)
 string username
 string password
 string name: The name of the group
address_book_group_delete
Deletes an address book group
 example: Generic HTTP Address book usage examples (Page 42)
 example: PHP API Address book usage examples (Page 44)
object address_book_group_delete (string username, string password, int group_id)
 string username
 string password
 int group_id: The ID of the group
affiliate_get_default_pricing
Returns the default pricing for new registrations
object affiliate_get_default_pricing (string username, string password, string country_code, string currency_code)
 string username
 string password
 string country_code: The 3 digit ISO country code to check
 string currency_code: The 3 digit currency code preferred
affiliate_list_countries
Returns the list of countries used by this system
object affiliate_list_countries (string username, string password)
 string username
 string password
affiliate_register_user
This action allows affiliate users to create new users, please contact support@mobi-apps.co.za if you are interested in becoming an affiliate.
Please note that this method returns its own status codes, an English error message will be returned to you, it is at your own discretion to translate these strings.
Example output: {“status”:0,”message”:”OK”,”details”:{“user_id”:”67″,”username”:”testdd”,”password”:”10jm06″,”message”:”User created successfully.”}}
 example: Generic HTTP API Affiliate Program Example (Page 42)
 example: PHP API Affiliate Program Example (Page 44)
object affiliate_register_user (string username, string password, string email_address, string dialling_code, string phone_number, [string user_ip_address = Null], [string user_username = Null], [string user_password = Null], [int campaign_id = Null])
 string username: Your Username
 string password: Your Password or token
 string email_address: New user email address
 string dialling_code: Registrant Number prefix
 string phone_number: New user phone_number (in format: country prefix-number ie: 798000000)
 string user_ip_address: New Users Ip address
 string user_username: New User Username (optional)
 string user_password: New User Password (optional)
 int campaign_id: Campaign Id (optional)
affiliate_register_user_quick
This action allows affiliate users to create new users, please contact support@sancustelecom.sms-console.com if you are interested in becoming an affiliate.
An English error message will be returned to you, it is at your own discretion to translate these strings.
When a user is created the new username will be returned and an auto generated password will be sent to them via SMS.
Example output: {“status”:0,”message”:”OK”,”details”: “george”}
object affiliate_register_user_quick (string username, string password, string email_address, string phone_number, [string ip_address = false], [integer marketing_channel_id = ‘0’])
 string username: Your Username
 string password: Your Password or token
 string email_address: New user email address
 string phone_number: New user phone_number (in format: country prefix-number ie: 798000000)
 string ip_address: New Users Ip address
 integer marketing_channel_id: Marketing channel ID (optional)

batches_list
Retrieves a list of the user batches.
Example output: {“status”:0,”message”:”OK”,”details”:[{“id”:”11″,”name”:”test”,”status”:32,”deletable”:false},{“id”:”12″,”name”:”Relationships”,”status”:32,”deletable”:false}]}
object batches_list (string username, string password)
 string username
 string password
batch_check_status
Checks the status of a batch
 example: HTTP trace for checking a batch status
 example: Perform batch functions using PHP API
object batch_check_status (string username, string password, int batch_id)
 string username
 string password
 int batch_id: batch_id as returned from batches_list (or other batch API’s)
batch_create
Creates a new batch, returns batch ID if successful
This action supports zip compression of files, these must be base64 encoded zip files.
 example: HTTP trace for creating a batch using a zip file
 example: Create a batch using a zip file using PHP
 example: HTTP trace for creating a batch
 example: Perform batch functions using PHP API
object batch_create (string username, string password, string name, [int throughput = 0], [boolean filter = false], [string file_type = ‘csv’], [string start_time = null])
 string username
 string password
 string name: A description / name for this batch
 int throughput: Throughput to deliver this batch at (per second)
 boolean filter: Filter this batch against the global blocklist
 string file_type: File type of the upload ( csv, xls or zip accepted )
 string start_time: If the batch must be auto-started at a given time, it must be specified here: eg: 2012-03-04 08:00:00

batch_start
Starts the given batch
 example: HTTP trace for starting a batch
 example: Perform batch functions using PHP API
object batch_start (string username, string password, int batch_id)
 string username
 string password
 int batch_id: batch_id as returned from batches_list (or other batch API’s)
batch_stop
Stops/pauses the given batch
object batch_stop (string username, string password, int batch_id)
 string username
 string password
 int batch_id: batch_id as returned from batches_list (or other batch API’s)
execute_multiple
This action allows you to execute multiple actions within the API with a single request.
The payload (with all actions) must be sent in a POST request with a variable named ‘data’ containing a JSON encoded array of actions to execute.
An array of results sent in the same order they were received will be returned.
 example: Perform execute_multiple using PHP API
 example: JSON HTTP trace example
object execute_multiple (string username, string password)
 string username
 string password
get_affiliate_country_info
Public method that returns affiliate country information. Primarily used for detecting number prefixes.
 example: Generic HTTP API Affiliate Program Example
 example: PHP API Affiliate Program Example
object get_affiliate_country_info (string username, string password, string ip_address, [boolean return_array = false], [ country_name = false])
 string username
 string password
 string ip_address: Ip Address to get country information for.
 boolean return_array: No need to change this.
 country_name
hlr_perform
This performs an HLR request and gives you the result via an HTTP callback
This is the recommended method for large volumes of HLR requests
Ouput contains keys: details (request ID)
object hlr_perform (string username, string password, string number, sring report_url)
 string username
 string password
 string number
 sring report_url: This is the URL you want to be called with the resulting information.
hlr_perform_synchronous
This performs an HLR request and gives you the result immediately.
This method is only recommended for small volumes and you will be limited to a maximum of 5 simultaneous requests using this method.
Example output contains keys: number_status, mcc, mnc, country_code, network_name
object hlr_perform_synchronous (string username, string password, string number)
 string username
 string password
 string number
inject_lead
This is for using our free leads service to inject leads.
Although this system filters out duplicate leads, best practise would be to manually filter the leads yourself as we only filter on a per batch basis.
Example output: {“status”:0,”message”:”OK”,”details”:”Lead Created”}
object inject_lead (string username, string password, integer batch_id, [string number = NULL], enum lead_type)
 string username
 string password
 integer batch_id
 string number
 enum lead_type: – options (1-Opt In,2-Opt Out)

list_actions
This method provides all a list of all methods currently available in the API and their parameters
object list_actions ()
messages_get
This function returns all inbound (MO) messages for the user which have an ID larger than ‘last_id’.
Best practice is to use this function starting with last_id = 0, then as messages are received, to store last_id as the highest message ID you receive back from the API request. Results are limited to 50 at a time.
Example ID {“status”:0,”message”:”OK”,”details”:[{“id”:”11″,”created”:”2011-04-09 19:25:09″,”from”:”27832659217″,”to”:”20000″,”data”:”Test MO Generated”,”charset”:”UTF-8″},{“id”:”10″,”created”:”2011-04-09 19:24:02″,”from”:”27832659217″,”to”:”20000″,”data”:”Test MO Generated”,”charset”:”UTF-8″}]}
object messages_get (string username, string password, int last_id)
 string username
 string password
 int last_id
messages_statistics
Statistics for the user account. These are a summarized value and should only be user to provide a broad overview of statistics.
Example output: {“status”:0,”message”:”OK”,”details”:{“sent”:231709,”dlr_received”:162,”received”:5,”dlr_requested”:200}}
object messages_statistics (string username, string password, [string start_date = NULL], [string end_date = NULL], [string user_id = NULL])
 string username
 string password
 string user_id: the sub user id that these statistics are for
 string start_date: start point of the statistics
 string end_date: end point of the statistics
message_send
Send an SMS message
In the return result, if successful the details key will contain the message ID.
Example output : {“status”:1,”message”:”Sent”,”details”:”8beda1a8-5c12-489f-0107-123000000003″}
 example: Sending an SMS using the Java API (Page 45)
 example: Sending an SMS using the PHP/HTTP API (Page 46)
 example: Sending an SMS via JSON HTTP GET (Page 46)
object message_send (string username, string password, string to, string text, [string from = null], [int report_mask = 19], [string report_url = null], [string charset = null], [int data_coding = null], [int message_class = -1], [int auto_detect_encoding = null])
 string username
 string password
 string to
 string text: The body of your message
 string from
 int report_mask: Delivery report request bitmask (see delivery_report_mask_* variables)
 string report_url: URL to call when delivery status changes
 string charset: Character set to use (defaults to UTF-8)
 int data_coding: Data coding (see data_coding_*)
 int message_class: Message class
 int auto_detect_encoding: Auto detect the encoding and send appropriately (useful for sending arabic, hindi, unicode etc messages) 1 = on, 0 = off, defaults off.
message_status
Checks the status of a message
This function can only be used 10 times per minute (to prevent bad implementation :)) if you require status for each message you send please use the report_url and report_mask variables when sending your messages with message_send().
Example ouput: {“status”:0,”message”:”OK”,”details”:{“status”:1,”cost”:0.20000,”parts”:1}}
 example: Checking message status with the Java API (Page 44)
object message_status (string username, string password, string message_id)
 string username
 string password
 string message_id
ping
Function to ensure communication
object ping ()
route_check_price
This action allows you to check the price you can expect to pay for a message to the destination in ‘to’
Output will contain the cost in the the details key.
 example: A generic HTTP request illustrating the use and response of route_check_price (Page 47)
object route_check_price (string username, string password, string to)
 string username: Your username
 string password: Your password or API key
 string to: The number you wish to test
user_authorize_application
This action allows a third party application to get an authentication key in order to make use of a user’s account.
The benefits of using this method is know that the application doesn’t have to worry about registration of the user account, it simply redirects the user to a web based location (which is provided) for authentication, once done, if the user allowed it, the application can access the API functions using the new API token.
WARNING: Request key’s generated here can only be guaranteed to be valid for 1 hour, so you *MUST* call user_get_api_key() after the process has been completed.
The output details key contains ‘authorize_url’ where the user should be sent to and ‘request_key’ which is the key to be used for API key creation once complete.
 example: A generic HTTP request illustrating the use and response of user_get_api_key()
 example: A PHP based example on how to generate a usable API Key based on a successful authorization
 example: A PHP based example on how to generate an API Key request token and redirect the user
object user_authorize_application (string application_name, [string icon_url = null], [string return_url = null])
 string application_name: The name of the application to be authorized (for the user to see)
 string icon_url: The URL where an icon can be found for this application (optional)
 string return_url: The URL where the user must be returned to once complete, if left out the window will be allowed to be closed (optional)
user_get_api_key
Once the user_authorize_application() action is completed and the user has returned to your application, you must call user_get_api_key() to create a permanent API key.
Details key contains ‘username’ and ‘key’ which can be used as username and password combinations in subsequent requests.
 example: A generic HTTP request illustrating the use and response of user_get_api_key()
 example: A PHP based example on how to generate a usable API Key based on a successful authorization
 example: A PHP based example on how to generate an API Key request token and redirect the user
object user_get_api_key (string request_key)
 string request_key: The original request key returned from user_authorize_application()
user_get_balance
Gets the user balance
 example: Checking user balance using the Java API
object user_get_balance (string username, string password)
 string username
 string password
user_get_info
Gets the user details
object user_get_info (string username, string password)
 string username
 string password
user_get_phone_number
This function returns the verified phone number for the given user
Example output {“status”:0,”message”:”OK”,”details”:”0832659217″}
object user_get_phone_number (string username, string password)
 string username
 string password
user_transfer_funds
Transfer credit from one account to another
Example output {“status”:0,”message”:”OK”,”details”:3338.50000}
object user_transfer_funds (string username, string password, string target_username, float amount)
 string username
 string password
 string target_username: The username to move funds to (this must be a sub-user of your account)
 float amount: The amount to transfer
Class Constants

api_result_authentication_failed = -8
Authentication failure
api_result_could_not_save = -256
Could not save
api_result_duplicate_record = -512
Duplicate record found (when adding)
api_result_internal_error = -16
Internal error
api_result_invalid_record = -128
Invalid record
api_result_key_created = 2
API Request Key created
api_result_message_sent = 1
Message sent/queued
api_result_missing_parameter = -4
There was a required parameter missing from the request (see ‘details’ key in result for more information)
api_result_no_action_specified = -1
No action was specified in the request
api_result_no_such_action = -2
There was no matching action found
api_result_ok = 0
Generic OK
api_result_out_of_credit = -64
Out of credit
api_result_routing_error = -32
Routing error
api_result_timeout = -8192
User has exceeded the maximum number of simultaneous requests to the API
api_result_too_many_connections = -4096
User has exceeded the maximum number of simultaneous requests to the API
api_result_user_invalid_affiliate = -1024
User is not part of any affiliate program
api_result_user_no_hlr = -2048
User does not have HLR enabled on his account
batch_status_busy = 16
Batch is busy being processed
batch_status_error = 128
There was an error processing the batch
batch_status_filter = 256
The batch is waiting to be filtered.
Set the batch to this status if you wish for it to be filtered.
batch_status_filtering = 512
Batch is busy being filtered
batch_status_new = 1
Batch is waiting to be processed
batch_status_parsing = 2
Batch is busy being parsed
batch_status_parsing_paused = 4
Parsing of the batch has been paused
batch_status_paused = 32
Batch has been parsed and is currently paused
batch_status_ready = 8
Batch is waiting to be processed (no action required)
batch_status_submitted = 64
Batch has been submitted
maximum_affliate_registrations_reached = -2048
User has reached maximum registrations during specified period.
message_status_acknowledged = 1
Message acknowledged
message_status_delivered = 4
Message has been delivered
message_status_does_not_exist = -1
Message does not exist
message_status_failed = 32
Message failed
message_status_filtered = 64
Filtered (blocked or previously failed)
message_status_internal_failed = 8
Message failed (internal error)
message_status_routing_error = 16
Routing error
message_status_submitted = 2
Message has been sent to the networks

The Mobi-Apps Java class source is provided for your use or extension
1. package com. sancustelecom.sms-console;
2.
3. import java.io.BufferedReader;
4. import java.io.IOException;
5. import java.io.InputStream;
6. import java.io.InputStreamReader;
7. import java.net.ConnectException;
8. import java.net.HttpURLConnection;
9. import java.net.URL;
10. import java.net.URLEncoder;
11. import java.text.SimpleDateFormat;
12. import java.util.Calendar;
13. import java.util.HashMap;
14. import java.util.Iterator;
15. import java.util.Set;
16.
17. import org.json.JSONObject;
18.
19.
20. public class Api {
21.
22. private String apiUrl = “http://api.sancustelecom.sms-console.com/json”;
23. private String username;
24. private String password;
25.
26. private String encodingScheme = “UTF-8”;
27.
28. private boolean debug = false;
29.
30. /**
31. * Instantiates a new instance of the API
32. *
33. * @param username Your Mobi-Apps username
34. * @param password Your Mobi-Apps password
35. */
36.
37. public Api(String username, String password) {
38. this.username = username;
39. this.password = password;
40. }
41.
42. /**
43. * Set’s the debugging state
44. *
45. * (if on it will print lines to the console, default: off)
46. *
47. * @param state
48. */
49.
50. public void setDebugging(boolean state) {
51. this.debug = state;
52. }
53.
54. private static java.util.HashMap createParams(String action) {
55. HashMap map = new HashMap();
56. map.put(“action”, action);
57. return map;
58. }
59.
60. private static void addParameter(java.util.Map map, String key, String value) {
61. if(value != null) {
62. map.put(key, value);
63. }
64. }
65.
66. private static void addParameter(java.util.Map map, String key, Integer value) {
67. if(value != null) {
68. map.put(key, String.valueOf(value));
69. }
70. }
71.
72.
73. private static String convertStreamToString(InputStream is) {
74. /*
75. * To convert the InputStream to String we use the
76. * BufferedReader.readLine() method. We iterate until the BufferedReader
77. * return null which means there’s no more data to read. Each line will
78. * appended to a StringBuilder and returned as String.
79. */
80. BufferedReader reader = new BufferedReader(new InputStreamReader(is));
81. StringBuilder sb = new StringBuilder();
82.
83. String line = null;
84. try {
85. while ((line = reader.readLine()) != null) {
86. sb.append(line + “\n”);
87. }
88. } catch (IOException e) {
89. e.printStackTrace();
90. } finally {
91. try {
92. is.close();
93. } catch (IOException e) {
94. e.printStackTrace();
95. }
96. }
97. return sb.toString();
98. }
99.
100. private JSONObject call(java.util.Map map) {
101. String workingUrl = apiUrl;
102. String key = null;
103. String val = null;
104. try {
105. workingUrl += “?username=”+URLEncoder.encode(username, encodingScheme);
106. workingUrl += “&password=”+URLEncoder.encode(password, encodingScheme);
107.
108. Set keys = map.keySet();
109. Iterator i = keys.iterator();
110.
111.
112. while(i.hasNext()) {
113. key = (String) i.next();
114. val = map.get(key);
115. if(val != null) {
116. workingUrl += “&”+URLEncoder.encode(key, encodingScheme) + “=” +URLEncoder.encode(val, encodingScheme);
117. }
118. }
119.
120. debug(“URL to be called “+workingUrl);
121.
122. URL url = new URL(workingUrl);
123. HttpURLConnection urlConnection = (HttpURLConnection)url.openConnection();
124.
125.
126. String result = convertStreamToString(urlConnection.getInputStream());
127.
128. if(result != null) {
129. if(result.length() > 0) {
130. /* Something */
131. JSONObject json = new JSONObject(result);
132. return json;
133. }
134. }
135. } catch(ConnectException e) {
136. debug(“Connection error “+ e.getMessage());
137. } catch(Exception e) {
138. e.printStackTrace();
139. }
140.
141. return null;
142. }
143.
144. private boolean validateResult(JSONObject json) {
145. if(json != null) {
146. try {
147. int status = json.getInt(“status”);
148.
149. if(status >= 0) {
150. /* OK! */
151. return true;
152. }
153. debug(“result was “+json.toString());
154. } catch(Exception e) {
155. e.printStackTrace();
156. }
157. }
158.
159. return false;
160. }
161.
162. private void debug(String data) {
163. if(this.debug) {
164. Calendar cal = Calendar.getInstance();
165. SimpleDateFormat sdf = new SimpleDateFormat(“yyyy-MM-dd HH:mm:ss”);
166. String str = “[” + sdf.format(cal.getTime()) + “] “+data;
167. System.out.println(str);
168. }
169. }
170.
171. /**
172. * Send’s a message via sancustelecom.sms-console.com/
173. *
174. * @param to The destination of the message
175. * @param text The text of the message
176. * @param from The source of the message (where the user will see it came from)
177. * @param report_mask Delivery report mask (See API documentation)
178. * @param report_url Delivery report URL (See API documentation)
179. * @param charset Character set encoding (default: UTF-8)
180. * @param data_coding Data coding (See API documentation)
181. * @return
182. */
183. public String message_send(String to, String text, String from, Integer report_mask, String report_url, String charset, Integer data_coding) {
184. HashMap map = new HashMap();
185. addParameter(map, “action”, “message_send”);
186. addParameter(map, “to”, to);
187. addParameter(map, “text”, text);
188. addParameter(map, “from”, from);
189. addParameter(map, “report_mask”, report_mask);
190. addParameter(map, “report_url”, report_url);
191. addParameter(map, “charset”, charset);
192. addParameter(map, “data_coding”, data_coding);
193.
194. JSONObject result = call(map);
195.
196. if(validateResult(result)) {
197. /* Return the message ID */
198. try {
199. return result.getString(“details”);
200. } catch(Exception e) {
201. e.printStackTrace();
202. }
203. }
204.
205. return null;
206. }
207.
208. /**
209. * Check your balance
210. *
211. * @return The balance
212. */
213. public Double user_get_balance() {
214. HashMap map = createParams(“user_get_balance”);
215. JSONObject result = call(map);
216. if(validateResult(result)) {
217. try {
218. return Double.valueOf(result.getDouble(“details”));
219. } catch(Exception e) {
220. e.printStackTrace();
221. }
222. }
223. return null;
224. }
225.
226. /**
227. * Check the status of a message
228. * @param message_id The message ID you wish to check
229. * @return A JSONObject containing keys status, cost and parts see ApiExample.java
230. */
231. public JSONObject message_status(String message_id) {
232. HashMap map = createParams(“message_status”);
233. addParameter(map, “message_id”, message_id);
234. JSONObject result = call(map);
235. if (validateResult(result)) {
236. try {
237. return result.getJSONObject(“details”);
238. } catch (Exception e) {
239. e.printStackTrace();
240. }
241. }
242. return null;
243. }
244.
245.
246.
247.
248.
249.
250.
251. }

The Mobi-Apps PHP class for easy deployment and integration (referenced in examples).
1. = 5)) {
24. $this->debug(“Version OK “.implode(“.”, $ver));
25. if(!function_exists(‘json_decode’) || !function_exists(‘json_encode’)) {
26. $this->debug(“You need the json_encode and json_decode functions to use this Class, JSON is available in PHP 5.2.0 and up for alternatives please see http://json.org”);
27. $this->debug(“Your PHP version is “.implode(“.”, $ver).” “.__FILE__);
28. die();
29. }
30. } else {
31. $this->debug(“You need at least PHP 5 to use this Class “.__FILE__);
32. die();
33. }
34. }
35.
36. function debug($str, $nl = true) {
37. if($this->debug) {
38. echo $str;
39. if($nl) {
40. echo “\n”;
41. }
42. }
43. }
44.
45. function call_api($url) {
46. if(function_exists(‘curl_init’)) {
47. if($this->curl === FALSE) {
48. $this->curl = curl_init();
49. } else {
50. curl_close($this->curl);
51. $this->curl = curl_init();
52. }
53. curl_setopt($this->curl, CURLOPT_HEADER, 1);
54. curl_setopt($this->curl, CURLOPT_URL, $url);
55. curl_setopt($this->curl, CURLOPT_RETURNTRANSFER, 1);
56. curl_setopt($this->curl, CURLINFO_HEADER_OUT, true);
57. curl_setopt($this->curl, CURLOPT_HTTPHEADER, array(“Connection: keep-alive”));
58.
59. $result = curl_exec($this->curl);
60.
61. $size = curl_getinfo($this->curl, CURLINFO_HEADER_SIZE);
62. $request_headers = curl_getinfo($this->curl, CURLINFO_HEADER_OUT);
63. $response_headers = substr($result, 0, $size);
64. $result = substr($result, $size);
65.
66. $this->debug(“— HTTP Request trace — “);
67. $this->debug($request_headers, false);
68. $this->debug($response_headers, false);
69. $this->debug($result);
70.
71.
72.
73. if($result !== FALSE) {
74. return json_decode($result, true);
75. }
76. return false;
77. } else {
78. $this->debug(“You need cURL to use this API Library”);
79. }
80.
81. return FALSE;
82. }
83.
84. function call_api_action($method, $params, $authenticate = true) {
85. if($this->performActionsImmediately) {
86. $url = $this->url.”?action=”.urlencode($method->getName());
87. if($authenticate) {
88. if(!is_null($this->password) && !is_null($this->username)) {
89. $url .= “&username=”.urlencode($this->username);
90. $url .= “&password=”.urlencode($this->password);
91. } else {
92. $this->debug(“You need to specify your username and password using setUsername() and setPassword()”);
93. return FALSE;
94. }
95. }
96. $parameters = $method->getParameters();
97. for($i=0;$igetName()).”=”.urlencode($params[$i]);
100. }
101. }
102.
103. return $this->call_api($url);
104. } else {
105. if(is_null($this->username) || is_null($this->password)) {
106. $this->debug(“You need to specify your username and password using setUsername() and setPassword() to perform bulk actions”);
107. return FALSE;
108. }
109. $action = array(
110. ‘command’ => $method->getName(),
111. ‘params’ => array()
112. );
113.
114. $parameters = $method->getParameters();
115. for($i=0;$igetName()] = $params[$i];
117. }
118.
119. $this->queuedActions[] = $action;
120.
121. return TRUE;
122. }
123. }
124.
125. function execute_multiple() {
126. if(function_exists(‘curl_init’)) {
127. if($this->curl === FALSE) {
128. $this->curl = curl_init();
129. } else {
130. curl_close($this->curl);
131. $this->curl = curl_init();
132. }
133.
134. $url = $this->url . “?action=execute_multiple”;
135. $url .= “&username=”.urlencode($this->username);
136. $url .= “&password=”.urlencode($this->password);
137.
138. curl_setopt($this->curl, CURLOPT_HEADER, 1);
139. curl_setopt($this->curl, CURLOPT_URL, $url);
140. curl_setopt($this->curl, CURLOPT_RETURNTRANSFER, 1);
141. curl_setopt($this->curl, CURLINFO_HEADER_OUT, true);
142. curl_setopt($this->curl, CURLOPT_POST, 1);
143. curl_setopt($this->curl, CURLOPT_POSTFIELDS, “data=”.urlencode(json_encode($this->queuedActions)));
144. curl_setopt($this->curl, CURLOPT_HTTPHEADER, array(“Connection: keep-alive”));
145.
146. $result = curl_exec($this->curl);
147.
148. $size = curl_getinfo($this->curl, CURLINFO_HEADER_SIZE);
149. $request_headers = curl_getinfo($this->curl, CURLINFO_HEADER_OUT);
150. $response_headers = substr($result, 0, $size);
151. $result = substr($result, $size);
152.
153. $this->debug(“— HTTP Request trace — “);
154. $this->debug($request_headers,false);
155. $this->debug(“\n”);
156. $this->debug($response_headers, false);
157. $this->debug($result);
158.
159.
160. if($result !== FALSE) {
161. return json_decode($result, true);
162. }
163. return false;
164. } else {
165. $this->debug(“You need cURL to use this API Library”);
166. }
167. return FALSE;
168. }
169.
170. function setUsername($username) {
171. $this->username = $username;
172. }
173.
174. function setPassword($password) {
175. $this->password = $password;
176. }
177.
178. function performActionsImmediately($state) {
179. $this->performActionsImmediately = $state;
180. }
181.
182. function message_send($to, $text, $from = null, $report_mask = 19, $report_url = null, $charset = null, $data_coding = null, $message_class = -1, $auto_detect_encoding = null) {
183. $args = func_get_args();
184. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
185. }
186.
187. function message_status($message_id) {
188. $args = func_get_args();
189. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
190. }
191.
192. function user_get_balance() {
193. $args = func_get_args();
194. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
195. }
196.
197. function batches_list() {
198. $args = func_get_args();
199. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
200. }
201.
202. function batch_start($batch_id) {
203. $args = func_get_args();
204. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
205. }
206.
207. function batch_stop($batch_id) {
208. $args = func_get_args();
209. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
210. }
211.
212. function batch_check_status($batch_id) {
213. $args = func_get_args();
214. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
215. }
216.
217. function address_book_groups_get_list() {
218. $args = func_get_args();
219. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
220. }
221.
222. function address_book_group_add($name) {
223. $args = func_get_args();
224. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
225. }
226.
227. function address_book_group_delete($group_id) {
228. $args = func_get_args();
229. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
230. }
231.
232. function address_book_contacts_get_list($group_id) {
233. $args = func_get_args();
234. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
235. }
236.
237. function address_book_contact_add($group_id, $phone_number, $first_name = null, $last_name = null) {
238. $args = func_get_args();
239. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
240. }
241.
242. function address_book_contact_delete($contact_id) {
243. $args = func_get_args();
244. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
245. }
246.
247. function address_book_contact_update($contact_id, $phone_number = null, $first_name = null, $last_name = null) {
248. $args = func_get_args();
249. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
250. }
251.
252. function user_authorize_application($application_name, $icon_url = null, $return_url = null) {
253. $args = func_get_args();
254. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args, false);
255. }
256.
257. function user_get_api_key($request_key) {
258. $args = func_get_args();
259. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args, false);
260. }
261.
262. function route_check_price($to) {
263. $args = func_get_args();
264. return $this->call_api_action(new ReflectionMethod(__CLASS__, __FUNCTION__), $args);
265. }
266.
267. function batch_create($name, $file, $throughput = 0, $filter = false, $file_type = ‘csv’, $start_time = null) {
268. /* This function has special requirements in terms of streaming raw data, hence it calls the API directly */
269. if(function_exists(‘curl_init’)) {
270. if($this->curl === FALSE) {
271. $this->curl = curl_init();
272. } else {
273. curl_close($this->curl);
274. $this->curl = curl_init();
275. }
276.
277.
278. if(!file_exists($file)) {
279. $this->debug(“File {$file} does not exist”);
280. return FALSE;
281. }
282.
283. if($file_type != ‘zip’) {
284. $data = “data=”.urlencode(file_get_contents($file));
285. } else {
286. $data = “data=”.urlencode(base64_encode(file_get_contents($file)));
287. }
288.
289. $url = $this->url . “?action=batch_create”;
290. $url .= “&username=”.urlencode($this->username);
291. $url .= “&password=”.urlencode($this->password);
292. $url .= “&name=”.urlencode($name);
293. $url .= “&file_type=”.urlencode($file_type);
294. $url .= “&filter=”.($filter ? ‘true’ : ‘false’);
295. $url .= “&throughput=”.$throughput;
296.
297. if(!is_null($start_time)) {
298. $url .= “&start_time=”.urlencode($start_time);
299. }
300.
301. curl_setopt($this->curl, CURLOPT_HEADER, 1);
302. curl_setopt($this->curl, CURLOPT_URL, $url);
303. curl_setopt($this->curl, CURLOPT_RETURNTRANSFER, 1);
304. curl_setopt($this->curl, CURLINFO_HEADER_OUT, true);
305. curl_setopt($this->curl, CURLOPT_HTTPHEADER, array(“Connection: keep-alive”));
306. curl_setopt($this->curl, CURLOPT_POST, 1);
307. curl_setopt($this->curl, CURLOPT_POSTFIELDS, $data);
308.
309. $result = curl_exec($this->curl);
310.
311. $size = curl_getinfo($this->curl, CURLINFO_HEADER_SIZE);
312. $request_headers = curl_getinfo($this->curl, CURLINFO_HEADER_OUT);
313. $response_headers = substr($result, 0, $size);
314. $result = substr($result, $size);
315.
316. $this->debug(“— HTTP Request trace — “);
317. $this->debug($request_headers, false);
318. $this->debug($response_headers, false);
319. $this->debug($result);
320.
321.
322.
323. if($result !== FALSE) {
324. return json_decode($result, true);
325. }
326. return false;
327. } else {
328. $this->debug(“You need cURL to use this API Library”);
329. }
330. return false;
331.
332. }
333.
334. function ok($result) {
335. if(is_array($result)) {
336. if(array_key_exists(‘status’, $result)) {
337. if($result[‘status’] >= 0) {
338. return TRUE;
339. }
340. $this->error = $result[‘message’];
341. }
342. } else {
343. if($result === TRUE) {
344. $this->error = “Command queued”;
345. return TRUE;
346. }
347. $this->error = “Error communicating with API”;
348. }
349. return FALSE;
350. }
351.
352. function getError() {
353. return $this->error;
354. }
355. }

Generic HTTP Address book usage examples
1. — HTTP Request trace for address_book_groups_get_list —
2. GET /json?action=address_book_groups_get_list&username=demouser&password=demouser HTTP/1.1
3. Host: sancustelecom.sms-console.com/
4. Accept: */*
5. Connection: keep-alive
6.
7. HTTP/1.1 200 OK
8. Date: Tue, 18 Jan 2011 12:50:51 GMT
9. Server: Apache
10. Content-Length: 70
11. Keep-Alive: timeout=15, max=100
12. Connection: Keep-Alive
13. Content-Type: text/html; charset=UTF-8
14.
15. {“status”:0,”message”:”OK”,”details”:[{“id”:”1″,”name”:”My Friends”}]}
16.
17. — HTTP Request trace for address_book_group_add —
18. GET /json?action=address_book_group_add&username=demouser&password=demouser&name=Api+demo+group HTTP/1.1
19. Host: sancustelecom.sms-console.com/
20. Accept: */*
21. Connection: keep-alive
22.
23. HTTP/1.1 200 OK
24. Date: Tue, 18 Jan 2011 12:50:52 GMT
25. Server: Apache
26. Content-Length: 41
27. Keep-Alive: timeout=15, max=100
28. Connection: Keep-Alive
29. Content-Type: text/html; charset=UTF-8
30.
31. {“status”:0,”message”:”OK”,”details”:”7″}
32.
33. — HTTP Request trace for address_book_contact_add —
34. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234567 HTTP/1.1
35. Host: sancustelecom.sms-console.com/
36. Accept: */*
37. Connection: keep-alive
38.
39. HTTP/1.1 200 OK
40. Date: Tue, 18 Jan 2011 12:50:52 GMT
41. Server: Apache
42. Content-Length: 42
43. Keep-Alive: timeout=15, max=100
44. Connection: Keep-Alive
45. Content-Type: text/html; charset=UTF-8
46.
47. {“status”:0,”message”:”OK”,”details”:”16″}
48.
49. — HTTP Request trace for address_book_contact_add —
50. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234568&first_name=Donald HTTP/1.1
51. Host: sancustelecom.sms-console.com/
52. Accept: */*
53. Connection: keep-alive
54.
55. HTTP/1.1 200 OK
56. Date: Tue, 18 Jan 2011 12:50:52 GMT
57. Server: Apache
58. Content-Length: 42
59. Keep-Alive: timeout=15, max=100
60. Connection: Keep-Alive
61. Content-Type: text/html; charset=UTF-8
62.
63. {“status”:0,”message”:”OK”,”details”:”17″}
64.
65. — HTTP Request trace for address_book_contact_update —
66. GET /json?action=address_book_contact_update&username=demouser&password=demouser&contact_id=17&last_name=Jackson HTTP/1.1
67. Host: sancustelecom.sms-console.com/
68. Accept: */*
69. Connection: keep-alive
70.
71. HTTP/1.1 200 OK
72. Date: Tue, 18 Jan 2011 12:50:53 GMT
73. Server: Apache
74. Content-Length: 27
75. Keep-Alive: timeout=15, max=100
76. Connection: Keep-Alive
77. Content-Type: text/html; charset=UTF-8
78.
79. {“status”:0,”message”:”OK”}
80.
81. — HTTP Request trace for address_book_group_delete —
82. GET /json?action=address_book_group_delete&username=demouser&password=demouser&group_id=7 HTTP/1.1
83. Host: sancustelecom.sms-console.com/
84. Accept: */*
85. Connection: keep-alive
86.
87. HTTP/1.1 200 OK
88. Date: Tue, 18 Jan 2011 12:50:53 GMT
89. Server: Apache
90. Content-Length: 27
91. Keep-Alive: timeout=15, max=100
92. Connection: Keep-Alive
93. Content-Type: text/html; charset=UTF-8
94.
95. {“status”:0,”message”:”OK”}

PHP API Address book usage examples
1. setUsername(“demouser”);
7. $api->setPassword(“demouser”);
8.
9. $groups = $api->address_book_groups_get_list();
10.
11. if($api->ok($groups)) {
12. foreach($groups[‘details’] as $group) {
13. echo “Group {$group[‘name’]} has ID {$group[‘id’]}\n”;
14. }
15. }
16.
17. /* Let’s add a new group */
18.
19. $result = $api->address_book_group_add(“Api demo group”);
20.
21. if($api->ok($result)) {
22. echo “Group added! ID = {$result[‘details’]}\n”;
23.
24. /* Now let’s add some contacts to our group */
25.
26. $contact1 = $api->address_book_contact_add($result[‘details’], “441234567”); /* Remember to specify the group ID, first name and last name are optional parameters */
27. $contact2 = $api->address_book_contact_add($result[‘details’], “441234568”, “Donald”);
28.
29. if($api->ok($contact1) && $api->ok($contact2)) {
30. echo “Both contacts added successfully, IDs {$contact1[‘details’]} and {$contact2[‘details’]}\n”;
31.
32. /* Let’s set the surname for contact2 */
33.
34. $api->address_book_contact_update($contact2[‘details’], null, null, “Jackson”); /* Specify null to not change */
35. }
36.
37. /* Let’s list all the contacts now */
38.
39. $contacts = $api->address_book_contacts_get_list($result[‘details’]);
40.
41. /* Let’s delete this group now */
42.
43. $api->address_book_group_delete($result[‘details’]);
44. }
45.
46.
47. ?>
Generic HTTP Address book usage examples
1. — HTTP Request trace for address_book_groups_get_list —
2. GET /json?action=address_book_groups_get_list&username=demouser&password=demouser HTTP/1.1
3. Host: sancustelecom.sms-console.com
4. Accept: */*
5. Connection: keep-alive
6.
7. HTTP/1.1 200 OK
8. Date: Tue, 18 Jan 2011 12:50:51 GMT
9. Server: Apache
10. Content-Length: 70
11. Keep-Alive: timeout=15, max=100
12. Connection: Keep-Alive
13. Content-Type: text/html; charset=UTF-8
14.
15. {“status”:0,”message”:”OK”,”details”:[{“id”:”1″,”name”:”My Friends”}]}
16.
17. — HTTP Request trace for address_book_group_add —
18. GET /json?action=address_book_group_add&username=demouser&password=demouser&name=Api+demo+group HTTP/1.1
19. Host: sancustelecom.sms-console.com
20. Accept: */*
21. Connection: keep-alive
22.
23. HTTP/1.1 200 OK
24. Date: Tue, 18 Jan 2011 12:50:52 GMT
25. Server: Apache
26. Content-Length: 41
27. Keep-Alive: timeout=15, max=100
28. Connection: Keep-Alive
29. Content-Type: text/html; charset=UTF-8
30.
31. {“status”:0,”message”:”OK”,”details”:”7″}
32.
33. — HTTP Request trace for address_book_contact_add —
34. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234567 HTTP/1.1
35. Host: sancustelecom.sms-console.com
36. Accept: */*
37. Connection: keep-alive
38.
39. HTTP/1.1 200 OK
40. Date: Tue, 18 Jan 2011 12:50:52 GMT
41. Server: Apache
42. Content-Length: 42
43. Keep-Alive: timeout=15, max=100
44. Connection: Keep-Alive
45. Content-Type: text/html; charset=UTF-8
46.
47. {“status”:0,”message”:”OK”,”details”:”16″}
48.
49. — HTTP Request trace for address_book_contact_add —
50. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234568&first_name=Donald HTTP/1.1
51. Host: sancustelecom.sms-console.com
52. Accept: */*
53. Connection: keep-alive
54.
55. HTTP/1.1 200 OK
56. Date: Tue, 18 Jan 2011 12:50:52 GMT
57. Server: Apache
58. Content-Length: 42
59. Keep-Alive: timeout=15, max=100
60. Connection: Keep-Alive
61. Content-Type: text/html; charset=UTF-8
62.
63. {“status”:0,”message”:”OK”,”details”:”17″}
64.
65. — HTTP Request trace for address_book_contact_update —
66. GET /json?action=address_book_contact_update&username=demouser&password=demouser&contact_id=17&last_name=Jackson HTTP/1.1
67. Host: sancustelecom.sms-console.com
68. Accept: */*
69. Connection: keep-alive
70.
71. HTTP/1.1 200 OK
72. Date: Tue, 18 Jan 2011 12:50:53 GMT
73. Server: Apache
74. Content-Length: 27
75. Keep-Alive: timeout=15, max=100
76. Connection: Keep-Alive
77. Content-Type: text/html; charset=UTF-8
78.
79. {“status”:0,”message”:”OK”}
80.
81. — HTTP Request trace for address_book_group_delete —
82. GET /json?action=address_book_group_delete&username=demouser&password=demouser&group_id=7 HTTP/1.1
83. Host: sancustelecom.sms-console.com
84. Accept: */*
85. Connection: keep-alive
86.
87. HTTP/1.1 200 OK
88. Date: Tue, 18 Jan 2011 12:50:53 GMT
89. Server: Apache
90. Content-Length: 27
91. Keep-Alive: timeout=15, max=100
92. Connection: Keep-Alive
93. Content-Type: text/html; charset=UTF-8
94.
95. {“status”:0,”message”:”OK”}

PHP API Address book usage examples
1. setUsername(“demouser”);
7. $api->setPassword(“demouser”);
8.
9. $groups = $api->address_book_groups_get_list();
10.
11. if($api->ok($groups)) {
12. foreach($groups[‘details’] as $group) {
13. echo “Group {$group[‘name’]} has ID {$group[‘id’]}\n”;
14. }
15. }
16.
17. /* Let’s add a new group */
18.
19. $result = $api->address_book_group_add(“Api demo group”);
20.
21. if($api->ok($result)) {
22. echo “Group added! ID = {$result[‘details’]}\n”;
23.
24. /* Now let’s add some contacts to our group */
25.
26. $contact1 = $api->address_book_contact_add($result[‘details’], “441234567”); /* Remember to specify the group ID, first name and last name are optional parameters */
27. $contact2 = $api->address_book_contact_add($result[‘details’], “441234568”, “Donald”);
28.
29. if($api->ok($contact1) && $api->ok($contact2)) {
30. echo “Both contacts added successfully, IDs {$contact1[‘details’]} and {$contact2[‘details’]}\n”;
31.
32. /* Let’s set the surname for contact2 */
33.
34. $api->address_book_contact_update($contact2[‘details’], null, null, “Jackson”); /* Specify null to not change */
35. }
36.
37. /* Let’s list all the contacts now */
38.
39. $contacts = $api->address_book_contacts_get_list($result[‘details’]);
40.
41. /* Let’s delete this group now */
42.
43. $api->address_book_group_delete($result[‘details’]);
44. }
45.
46.
47. ?>
Generic HTTP Address book usage examples
1. — HTTP Request trace for address_book_groups_get_list —
2. GET /json?action=address_book_groups_get_list&username=demouser&password=demouser HTTP/1.1
3. Host: sancustelecom.sms-console.com
4. Accept: */*
5. Connection: keep-alive
6.
7. HTTP/1.1 200 OK
8. Date: Tue, 18 Jan 2011 12:50:51 GMT
9. Server: Apache
10. Content-Length: 70
11. Keep-Alive: timeout=15, max=100
12. Connection: Keep-Alive
13. Content-Type: text/html; charset=UTF-8
14.
15. {“status”:0,”message”:”OK”,”details”:[{“id”:”1″,”name”:”My Friends”}]}
16.
17. — HTTP Request trace for address_book_group_add —
18. GET /json?action=address_book_group_add&username=demouser&password=demouser&name=Api+demo+group HTTP/1.1
19. Host: sancustelecom.sms-console.com
20. Accept: */*
21. Connection: keep-alive
22.
23. HTTP/1.1 200 OK
24. Date: Tue, 18 Jan 2011 12:50:52 GMT
25. Server: Apache
26. Content-Length: 41
27. Keep-Alive: timeout=15, max=100
28. Connection: Keep-Alive
29. Content-Type: text/html; charset=UTF-8
30.
31. {“status”:0,”message”:”OK”,”details”:”7″}
32.
33. — HTTP Request trace for address_book_contact_add —
34. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234567 HTTP/1.1
35. Host: sancustelecom.sms-console.com
36. Accept: */*
37. Connection: keep-alive
38.
39. HTTP/1.1 200 OK
40. Date: Tue, 18 Jan 2011 12:50:52 GMT
41. Server: Apache
42. Content-Length: 42
43. Keep-Alive: timeout=15, max=100
44. Connection: Keep-Alive
45. Content-Type: text/html; charset=UTF-8
46.
47. {“status”:0,”message”:”OK”,”details”:”16″}
48.
49. — HTTP Request trace for address_book_contact_add —
50. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234568&first_name=Donald HTTP/1.1
51. Host: sancustelecom.sms-console.com
52. Accept: */*
53. Connection: keep-alive
54.
55. HTTP/1.1 200 OK
56. Date: Tue, 18 Jan 2011 12:50:52 GMT
57. Server: Apache
58. Content-Length: 42
59. Keep-Alive: timeout=15, max=100
60. Connection: Keep-Alive
61. Content-Type: text/html; charset=UTF-8
62.
63. {“status”:0,”message”:”OK”,”details”:”17″}
64.
65. — HTTP Request trace for address_book_contact_update —
66. GET /json?action=address_book_contact_update&username=demouser&password=demouser&contact_id=17&last_name=Jackson HTTP/1.1
67. Host: sancustelecom.sms-console.com
68. Accept: */*
69. Connection: keep-alive
70.
71. HTTP/1.1 200 OK
72. Date: Tue, 18 Jan 2011 12:50:53 GMT
73. Server: Apache
74. Content-Length: 27
75. Keep-Alive: timeout=15, max=100
76. Connection: Keep-Alive
77. Content-Type: text/html; charset=UTF-8
78.
79. {“status”:0,”message”:”OK”}
80.
81. — HTTP Request trace for address_book_group_delete —
82. GET /json?action=address_book_group_delete&username=demouser&password=demouser&group_id=7 HTTP/1.1
83. Host: sancustelecom.sms-console.com
84. Accept: */*
85. Connection: keep-alive
86.
87. HTTP/1.1 200 OK
88. Date: Tue, 18 Jan 2011 12:50:53 GMT
89. Server: Apache
90. Content-Length: 27
91. Keep-Alive: timeout=15, max=100
92. Connection: Keep-Alive
93. Content-Type: text/html; charset=UTF-8
94.
95. {“status”:0,”message”:”OK”}

PHP API Address book usage examples
1. setUsername(“demouser”);
7. $api->setPassword(“demouser”);
8.
9. $groups = $api->address_book_groups_get_list();
10.
11. if($api->ok($groups)) {
12. foreach($groups[‘details’] as $group) {
13. echo “Group {$group[‘name’]} has ID {$group[‘id’]}\n”;
14. }
15. }
16.
17. /* Let’s add a new group */
18.
19. $result = $api->address_book_group_add(“Api demo group”);
20.
21. if($api->ok($result)) {
22. echo “Group added! ID = {$result[‘details’]}\n”;
23.
24. /* Now let’s add some contacts to our group */
25.
26. $contact1 = $api->address_book_contact_add($result[‘details’], “441234567”); /* Remember to specify the group ID, first name and last name are optional parameters */
27. $contact2 = $api->address_book_contact_add($result[‘details’], “441234568”, “Donald”);
28.
29. if($api->ok($contact1) && $api->ok($contact2)) {
30. echo “Both contacts added successfully, IDs {$contact1[‘details’]} and {$contact2[‘details’]}\n”;
31.
32. /* Let’s set the surname for contact2 */
33.
34. $api->address_book_contact_update($contact2[‘details’], null, null, “Jackson”); /* Specify null to not change */
35. }
36.
37. /* Let’s list all the contacts now */
38.
39. $contacts = $api->address_book_contacts_get_list($result[‘details’]);
40.
41. /* Let’s delete this group now */
42.
43. $api->address_book_group_delete($result[‘details’]);
44. }
45.
46.
47. ?>
Generic HTTP Address book usage examples
1. — HTTP Request trace for address_book_groups_get_list —
2. GET /json?action=address_book_groups_get_list&username=demouser&password=demouser HTTP/1.1
3. Host: sancustelecom.sms-console.com
4. Accept: */*
5. Connection: keep-alive
6.
7. HTTP/1.1 200 OK
8. Date: Tue, 18 Jan 2011 12:50:51 GMT
9. Server: Apache
10. Content-Length: 70
11. Keep-Alive: timeout=15, max=100
12. Connection: Keep-Alive
13. Content-Type: text/html; charset=UTF-8
14.
15. {“status”:0,”message”:”OK”,”details”:[{“id”:”1″,”name”:”My Friends”}]}
16.
17. — HTTP Request trace for address_book_group_add —
18. GET /json?action=address_book_group_add&username=demouser&password=demouser&name=Api+demo+group HTTP/1.1
19. Host: sancustelecom.sms-console.com
20. Accept: */*
21. Connection: keep-alive
22.
23. HTTP/1.1 200 OK
24. Date: Tue, 18 Jan 2011 12:50:52 GMT
25. Server: Apache
26. Content-Length: 41
27. Keep-Alive: timeout=15, max=100
28. Connection: Keep-Alive
29. Content-Type: text/html; charset=UTF-8
30.
31. {“status”:0,”message”:”OK”,”details”:”7″}
32.
33. — HTTP Request trace for address_book_contact_add —
34. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234567 HTTP/1.1
35. Host: sancustelecom.sms-console.com
36. Accept: */*
37. Connection: keep-alive
38.
39. HTTP/1.1 200 OK
40. Date: Tue, 18 Jan 2011 12:50:52 GMT
41. Server: Apache
42. Content-Length: 42
43. Keep-Alive: timeout=15, max=100
44. Connection: Keep-Alive
45. Content-Type: text/html; charset=UTF-8
46.
47. {“status”:0,”message”:”OK”,”details”:”16″}
48.
49. — HTTP Request trace for address_book_contact_add —
50. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234568&first_name=Donald HTTP/1.1
51. Host: sancustelecom.sms-console.com
52. Accept: */*
53. Connection: keep-alive
54.
55. HTTP/1.1 200 OK
56. Date: Tue, 18 Jan 2011 12:50:52 GMT
57. Server: Apache
58. Content-Length: 42
59. Keep-Alive: timeout=15, max=100
60. Connection: Keep-Alive
61. Content-Type: text/html; charset=UTF-8
62.
63. {“status”:0,”message”:”OK”,”details”:”17″}
64.
65. — HTTP Request trace for address_book_contact_update —
66. GET /json?action=address_book_contact_update&username=demouser&password=demouser&contact_id=17&last_name=Jackson HTTP/1.1
67. Host: sancustelecom.sms-console.com
68. Accept: */*
69. Connection: keep-alive
70.
71. HTTP/1.1 200 OK
72. Date: Tue, 18 Jan 2011 12:50:53 GMT
73. Server: Apache
74. Content-Length: 27
75. Keep-Alive: timeout=15, max=100
76. Connection: Keep-Alive
77. Content-Type: text/html; charset=UTF-8
78.
79. {“status”:0,”message”:”OK”}
80.
81. — HTTP Request trace for address_book_group_delete —
82. GET /json?action=address_book_group_delete&username=demouser&password=demouser&group_id=7 HTTP/1.1
83. Host: sancustelecom.sms-console.com
84. Accept: */*
85. Connection: keep-alive
86.
87. HTTP/1.1 200 OK
88. Date: Tue, 18 Jan 2011 12:50:53 GMT
89. Server: Apache
90. Content-Length: 27
91. Keep-Alive: timeout=15, max=100
92. Connection: Keep-Alive
93. Content-Type: text/html; charset=UTF-8
94.
95. {“status”:0,”message”:”OK”}

PHP API Address book usage examples
1. setUsername(“demouser”);
7. $api->setPassword(“demouser”);
8.
9. $groups = $api->address_book_groups_get_list();
10.
11. if($api->ok($groups)) {
12. foreach($groups[‘details’] as $group) {
13. echo “Group {$group[‘name’]} has ID {$group[‘id’]}\n”;
14. }
15. }
16.
17. /* Let’s add a new group */
18.
19. $result = $api->address_book_group_add(“Api demo group”);
20.
21. if($api->ok($result)) {
22. echo “Group added! ID = {$result[‘details’]}\n”;
23.
24. /* Now let’s add some contacts to our group */
25.
26. $contact1 = $api->address_book_contact_add($result[‘details’], “441234567”); /* Remember to specify the group ID, first name and last name are optional parameters */
27. $contact2 = $api->address_book_contact_add($result[‘details’], “441234568”, “Donald”);
28.
29. if($api->ok($contact1) && $api->ok($contact2)) {
30. echo “Both contacts added successfully, IDs {$contact1[‘details’]} and {$contact2[‘details’]}\n”;
31.
32. /* Let’s set the surname for contact2 */
33.
34. $api->address_book_contact_update($contact2[‘details’], null, null, “Jackson”); /* Specify null to not change */
35. }
36.
37. /* Let’s list all the contacts now */
38.
39. $contacts = $api->address_book_contacts_get_list($result[‘details’]);
40.
41. /* Let’s delete this group now */
42.
43. $api->address_book_group_delete($result[‘details’]);
44. }
45.
46.
47. ?>
Generic HTTP Address book usage examples
1. — HTTP Request trace for address_book_groups_get_list —
2. GET /json?action=address_book_groups_get_list&username=demouser&password=demouser HTTP/1.1
3. Host: sancustelecom.sms-console.com
4. Accept: */*
5. Connection: keep-alive
6.
7. HTTP/1.1 200 OK
8. Date: Tue, 18 Jan 2011 12:50:51 GMT
9. Server: Apache
10. Content-Length: 70
11. Keep-Alive: timeout=15, max=100
12. Connection: Keep-Alive
13. Content-Type: text/html; charset=UTF-8
14.
15. {“status”:0,”message”:”OK”,”details”:[{“id”:”1″,”name”:”My Friends”}]}
16.
17. — HTTP Request trace for address_book_group_add —
18. GET /json?action=address_book_group_add&username=demouser&password=demouser&name=Api+demo+group HTTP/1.1
19. Host: sancustelecom.sms-console.com
20. Accept: */*
21. Connection: keep-alive
22.
23. HTTP/1.1 200 OK
24. Date: Tue, 18 Jan 2011 12:50:52 GMT
25. Server: Apache
26. Content-Length: 41
27. Keep-Alive: timeout=15, max=100
28. Connection: Keep-Alive
29. Content-Type: text/html; charset=UTF-8
30.
31. {“status”:0,”message”:”OK”,”details”:”7″}
32.
33. — HTTP Request trace for address_book_contact_add —
34. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234567 HTTP/1.1
35. Host: sancustelecom.sms-console.com
36. Accept: */*
37. Connection: keep-alive
38.
39. HTTP/1.1 200 OK
40. Date: Tue, 18 Jan 2011 12:50:52 GMT
41. Server: Apache
42. Content-Length: 42
43. Keep-Alive: timeout=15, max=100
44. Connection: Keep-Alive
45. Content-Type: text/html; charset=UTF-8
46.
47. {“status”:0,”message”:”OK”,”details”:”16″}
48.
49. — HTTP Request trace for address_book_contact_add —
50. GET /json?action=address_book_contact_add&username=demouser&password=demouser&group_id=7&phone_number=441234568&first_name=Donald HTTP/1.1
51. Host: sancustelecom.sms-console.com
52. Accept: */*
53. Connection: keep-alive
54.
55. HTTP/1.1 200 OK
56. Date: Tue, 18 Jan 2011 12:50:52 GMT
57. Server: Apache
58. Content-Length: 42
59. Keep-Alive: timeout=15, max=100
60. Connection: Keep-Alive
61. Content-Type: text/html; charset=UTF-8
62.
63. {“status”:0,”message”:”OK”,”details”:”17″}
64.
65. — HTTP Request trace for address_book_contact_update —
66. GET /json?action=address_book_contact_update&username=demouser&password=demouser&contact_id=17&last_name=Jackson HTTP/1.1
67. Host: sancustelecom.sms-console.com
68. Accept: */*
69. Connection: keep-alive
70.
71. HTTP/1.1 200 OK
72. Date: Tue, 18 Jan 2011 12:50:53 GMT
73. Server: Apache
74. Content-Length: 27
75. Keep-Alive: timeout=15, max=100
76. Connection: Keep-Alive
77. Content-Type: text/html; charset=UTF-8
78.
79. {“status”:0,”message”:”OK”}
80.
81. — HTTP Request trace for address_book_group_delete —
82. GET /json?action=address_book_group_delete&username=demouser&password=demouser&group_id=7 HTTP/1.1
83. Host: sancustelecom.sms-console.com
84. Accept: */*
85. Connection: keep-alive
86.
87. HTTP/1.1 200 OK
88. Date: Tue, 18 Jan 2011 12:50:53 GMT
89. Server: Apache
90. Content-Length: 27
91. Keep-Alive: timeout=15, max=100
92. Connection: Keep-Alive
93. Content-Type: text/html; charset=UTF-8
94.
95. {“status”:0,”message”:”OK”}

PHP API Address book usage examples
1. setUsername(“demouser”);
7. $api->setPassword(“demouser”);
8.
9. $groups = $api->address_book_groups_get_list();
10.
11. if($api->ok($groups)) {
12. foreach($groups[‘details’] as $group) {
13. echo “Group {$group[‘name’]} has ID {$group[‘id’]}\n”;
14. }
15. }
16.
17. /* Let’s add a new group */
18.
19. $result = $api->address_book_group_add(“Api demo group”);
20.
21. if($api->ok($result)) {
22. echo “Group added! ID = {$result[‘details’]}\n”;
23.
24. /* Now let’s add some contacts to our group */
25.
26. $contact1 = $api->address_book_contact_add($result[‘details’], “441234567”); /* Remember to specify the group ID, first name and last name are optional parameters */
27. $contact2 = $api->address_book_contact_add($result[‘details’], “441234568”, “Donald”);
28.
29. if($api->ok($contact1) && $api->ok($contact2)) {
30. echo “Both contacts added successfully, IDs {$contact1[‘details’]} and {$contact2[‘details’]}\n”;
31.
32. /* Let’s set the surname for contact2 */
33.
34. $api->address_book_contact_update($contact2[‘details’], null, null, “Jackson”); /* Specify null to not change */
35. }
36.
37. /* Let’s list all the contacts now */
38.
39. $contacts = $api->address_book_contacts_get_list($result[‘details’]);
40.
41. /* Let’s delete this group now */
42.
43. $api->address_book_group_delete($result[‘details’]);
44. }
45.
46.
47. ?>
Checking user balance using the Java API
1. package com. sancustelecom.sms-console;
2.
3. import org.json.JSONObject;
4.
5. public class ApiExample {
6.
7. /**
8. * @param args
9. */
10. public static void main(String[] args) {
11. Api api = new Api(“demouser”, “demouser”);
12. api.setDebugging(false);
13.
14. String message_id = api.message_send(“0832659217”, “Hi there, I just sent a message!”, “0214224825”, null, null, null, null); /* Not all arguments are required */
15. if(message_id != null) {
16. System.out.println(“It worked! Your message was sent!”);
17.
18. /* Now we can do some other checks */
19.
20. Double balance = api.user_get_balance();
21. if(balance != null) {
22. System.out.println(“Great! My balance is “+balance.toString());
23. }
24.
25. JSONObject status = api.message_status(message_id);
26. if(status != null) {
27. try {
28. System.out.println(“Message cost was “+String.valueOf(status.getDouble(“cost”)));
29. System.out.println(“Message status is now “+String.valueOf(status.getInt(“status”)));
30. System.out.println(“Message had “+String.valueOf(status.getInt(“parts”)) + ” parts”);
31.
32. } catch(Exception e) {
33. System.out.println(“JSON Error”);
34. e.printStackTrace();
35. }
36. }
37. } else {
38. System.out.println(“Could not send message :(“);
39. }
40.
41. }
42.
43. }

Sending an SMS using the PHP/HTTP API
1. setUsername(“demouser”);
7. $api->setPassword(“demouser”);
8.
9. $result = $api->message_send(“27111234567”, “Hello”, “27111236846”);
10.
11. if($api->ok($result)) {
12. echo “Message sent! ID was {$result[‘details’]}\n”;
13. } else {
14. /* There was an error */
15. echo $api->getError();
16. }
17.
18. ?>

Sending an SMS via JSON HTTP GET
1. GET /json?action=message_send&username=demouser&password=demouser&to=27111234567&text=Hello&from=27832659217 HTTP/1.1
2. Host: sancustelecom.sms-console.com
3. Accept: */*
4. Connection: keep-alive
5.
6. HTTP/1.1 200 OK
7. Date: Thu, 30 Dec 2010 20:12:02 GMT
8. Server: Apache
9. Content-Length: 78
10. Keep-Alive: timeout=15, max=100
11. Connection: Keep-Alive
12. Content-Type: text/html; charset=UTF-8
13.
14. {“status”:1,”message”:”Sent”,”details”:”6487a012-516e-4105-0103-123000000003″}

A generic HTTP request illustrating the use and response of route_check_price
1. — HTTP Request trace —
2. GET /json?action=route_check_price&username=demo&password=demo&to=27111234567 HTTP/1.1
3. Host: sancustelecom.sms-console.com
4. Accept: */*
5. Connection: keep-alive
6.
7. HTTP/1.1 200 OK
8. Date: Wed, 09 Mar 2011 18:35:56 GMT
9. Server: Apache
10. Content-Length: 85
11. Keep-Alive: timeout=15, max=100
12. Connection: Keep-Alive
13. Content-Type: text/html; charset=UTF-8
14.
15. {“status”:0,”message”:”OK”,”details”:{“cost”:0.2,”status”:64,”reason”:”64: Routed OK”}}