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