API Documentation

SMS Platform API’s

Directed to HTTP url:

When the option DIRECTED TO HTTP URL is selected , we will send the following fields to the URL defined in the keyword management:

keyword=xxx

mobilenumber=1xxxxxxxxxx

shortmessage=xxxxxxx

network=operator id

datetime=yyMMddHHmmss

shortcode=short code

For instance, if we have the keyword “george” and its’ forward http url is http://customer.com/receiver,

after receiving your sample message from number 11804677488 at 2007-09-15 01:01:01, we will forward the following data to the URL:

keyword=george

mobilenumber=11804677488

shortmessage=george 37 pizza 12345

network=xxxxx

datetime=070915010101

shortcode=41513

Here is sample code for a Java servlet:

public class HTTPReceiver

extends HttpServlet {

Object lock1 = new Object(), lock2 = new Object(), lock3 = new Object();

//Process the HTTP Post request

response) throws

ServletException, IOException {

doGet(request, response);

}

//Process the HTTP Get request

public synchronized void doGet(HttpServletRequest request,

HttpServletResponse response) throws

ServletException, IOException {

// get all forwarded data

String keyword=request.getParameter(“keyword”);

String mobilenumber=request.getParameter(“mobilenumber”);

String shortmessage=request.getParameter(“shortmessage”)

String network=request.getParameter(“network”)

String datetime=request.getParameter(“datetime”)

String shortcode=request.getParameter(“shortcode”)

// TODO whatever you like to do

}

}

The principle is same with other languages.

“sms.gateway”:

In order to send sms message via http interface, the user needs to submit 4 parameters to http url: http://yourWLdomainhere.com/sms.gateway, e.g. http://client.yourdomain.com/sms.gateway

The 4 parameters in insecure way: username and password are both in plain text

1. username

2. password

3. shortmessage

4. destnumber

for example:

http://yourWLdomainhere.com/sms.gateway?username=xxx&password=xxx&shortmessage=xxx
&destnumber=12345678901

The 4 parameters in the secure way: cid and password are encrypted text

1. cid

2. password

3. shortmessage

4. destnumber

for example:

http://yourWLdomainhere.com/sms.gateway?
cid=77de68daecd823babbb58edb1c8e14&password=ee11cbb19052e40b07a
&shortmessage=xxx&destnumber=12345678901

Cid and encrypted password is located in the Account Info.

Send a message to an existing group

http://yourWLdomainhere.com/sms.gateway?
cid=77de68daecd823babbb58edb1c8e14&password=ee11cbb19052e40b07a
&shortmessage=xxx&destgroup=mygroup

============================================================================
Customer Management API: 

The basic usage of customer management api is as follow:

1. add new account:

The client can submit the following variables to link:

http://domain/customermanagement

op=A

cid=*

password=*

username=*

firstname=*

lastname=*

company=*

paypal_email=*

keyword_num=

credits=

low_credits=
new_password=
email=

use_twitter=

twitter_account=

twitter_password=

use_auto_monthly_credits=

auto_monthly_credits=

next_reset_date=

sales_id=<sales_id of=”” new=”” account=””>

for example:

http://yourWLdomainhere/customermanagement?
cid=356a192b7913b28d46e6395428ab&password=f8296700920b5be9177f90a80&op=A
&username=newuser@123.com&keyword_num=10&firstname=John&lastname=Smitch

2. update info for an user

The client can submit the following variables to link:

http://domain/customermanagement

op=U

cid=*

password=*

username=*

new_password=

company=

keyword_num=

add_keywords=

low_credits=

credits=

add_credits=

paypal_email=

email=

use_facebook=

twitter_account=

twitter_password=

use_twitter=

fb_api_key=

fb_app_secret=

use_auto_monthly_credits=

auto_monthly_credits=

next_reset_date=

for example:

http://yourWLdomainhere/customermanagement?
cid=356a192b7913b28d46e6395428ab&password=f8296700920b5be9177f90a80&op=U
&username=newuser@123.com&keyword_num=200

http://yourWLdomainhere/customermanagement?
cid=356a192b7913b28d46e6395428ab&password=f8296700920b5be9177f90a80&op=U
&username=newuser@123.com&add_credits=100

http://selfstudy/customermanagement?
cid=356a192b7913b28d46e6395428ab&password=f8296700920b5be9177f90a80&op=U
&username=newuser@123.com&use_auto_monthly_credits=n&auto_monthly_credits=100
&next_reset_date=201009301200

3. disable an user

The client can submit the following variables to link:

http://domain/customermanagement

op=D

cid=*

password=*

username=*

4. get password of an user

The client can submit the following variables to link:

http://domain/customermanagement

op=V

cid=*

password=*

username=*

for example:

http://yourWLdomainhere/customermanagement?
cid=356a192b7913b28d46e6395428ab&password=f8296700920b5be9177f90a80&op=V
&username=newuser@123.com

“00
” will be returned upon succeed
The customer management API return codes and explanations are as follow:

If the operation succeeds:

00 Succeed.

If the operation fails:

01

02 Username does not exist.

03 Failed to add new account.

04 Admin has insufficient number of keyword to finish the operation.

Note: Client can either submit the data in GET or POST method. Those

fields end with “*” mark are mandatory.
==================================================================

Keyword Management API:
The basic usage of keyword management API is as follows:

1. add new keyword:

The client can submit the following variables in get or post method to link:

http://domain/keywordmanagement

op=A *

cid=*

password=*

username=

keyword=*

type=<1|2|5|6|7|11|12|13|1024|1025|1026|1027|1028|1029>* // keyword function type

remove_opt_out=<y|n>* //Remove opt-out instructions from reply message

short_message=*

use_already_in_group_reply=<y|n>

top_keyword= // The top keyword should be given if

creating a sub keyword

forward_email=

forward_number=

forward_url=

// encoded – http%3A%2F%2F

forward_group=

coupon_code=

for example:

http://yourWLdomainhere/keywordmanagement?
cid=356a192b7913b28d46e6395428ab&password=f8296700920b5be9177f90a80&op=A
&type=2&remove_opt_out=y&keyword=test_keyword&short_message=testing+message

2. update keyword

The client can submit the following variables to link:

http://domain/keywordmanagement

op=U *

cid=*

password=*

username=

keyword=*

top_keyword= // The top keyword should be given if

creating a sub keyword

short_message=

coupon_code=

for example:

http://yourWLdomainhere/keywordmanagement?
cid=356a192b7913b28d46e6395428ab&password=f8296700920b5be9177f90a80&op=U
&keyword=test_keyword&short_message=new+testing+message

Note:

The fields mark with * are obligatory.

Return code and explanation

If the operation succeeds:

00 The keyword was added successfully.

If the operation fails:

01
The keyword function type list:

Type Description

1 Forward as email (iso-8859-1)

2 Reply message will be sent

5 Customer will be added to group

12 Customer will be added to group & email will be forwarded

6 Customer will be removed from a group

7 The message will be forwarded to group members

11 The message will be forwarded as sms & Customer will be added to group

13 The message will be forwarded as sms and email & Customer will be added to group

1024 Directed to HTTP URL

1025 Direct to HTTP URL and add to group

1026 Direct to HTTP URL and forward as email

1027 Direct to HTTP URL, forward as email and add to group

1028 Direct to HTTP URL, forward as SMS and add to group

1029 Direct to HTTP URL, forward as email&SMS and add to group

==============================================================

Carrier Lookup API 

URI: https://www.carrierlookupservice.com/service
SSL: Required
HTTP Method: POST

Required POST Parameters:

Parameter	Notes	Example
format	JSON is the only currently supported return object type	format=json
key	API key associated with your account	key=1234567abcdefg.12345
min	Phone number, numbers only	min=15555555555

JSON Response Object:

Field	Notes	Sample
error	If there is an issue with your account and/or request, a message will appear in the error field, otherwise it will be omitted	“error”:”Credits Depleted”
result	Result of the lookup – either the carrier name, or Boolean false if not found in carrier database (i.e. not mobile).	“result”:false “result”:”Sprint PCS Wireless”
creditsRemain	Remaining credits associated with account. An email is sent to the registered account when credits are depleted.	“creditsRemain”:”49″
min	Number submitted to lookup database (reformatted, if required)	“min”:”15555555555″
carrierId	Carrier ID number	“carrierId”:”5″
ip	Detected IP address of caller	“ip”:”192.168.0.1″

Sample Responses:

{“creditsRemain”:”49″,”ip”:”192.168.0.1″,”min”:”15555555555″,”carrierId”:”5″,”result”:”Sprint PCS Wireless”}

{“error”:”Account Error”}

{“error”:”Credits Depleted”}

{“error”:”Incorrect Parameters – please refer to documentation and POST the correct parameters”}

{“error”:”SSL Required”}

==============================================================

Carrier Codes

These are the AMM Codes

AMM Carrier ID	AMM Carrier Name
274	Alaska Communications Systems
359	Allied Wireless
7	Alltel (now own Western Wireless & Midwest Wireless)
1	AT&T
249	Bluegrass Cellular
129	Boost Mobile CDMA
128	Boost Mobile iDEN
233	Cellcom
357	Cellular Once of Montana Same asMTPCS Cellular One)
284	Cellular One of NE PA (Cellular One of NE Penn)
210	Cellular South
53	Centennial
286	Chat Mobility (Hawkeye)
125	Cincinnati Bell
356	Cox Wireless
203	Cricket (Leap Wireless)
235	East Kentucky Network
269	ECIT (Cellular One of East Illinois)
358	Element Mobile
140	Enid/Pioneer Cellular
298	Epic Touch
303	GCI Communications
264	Golden State
311	Illinois Valley Cellular
313	Inland Cellular
214	iWiereless
	Metro PCS (Q1 or Q2 – finalizing agreement with Metro)
218	Midwest Wireless (now part of Alltel)
324	Nex-Tech Wireless
6	Nextel Communications
327	Northwest Missouri Cellular (Hawkeye)
131	NTELOS
329	Panhandle Wireless
331	Plateau Wireless
332	Pocket Wireless
355	Revol Wireless
5	Sprint PCS Wireless
342	Thumb Cellular
2	T-Mobile
142	TMP/Simmetry
225	Union Telephone
345	United Wireless
36	US Cellular
4	Verizon Wireless
281	Viaero Wireless
205	Virgin Mobile USA
232	West Central Wireless