DEPRECATED: Reference only

Direct Connection Details

For clients that connect to ports other than the HTTP/S ports (80/443) the preferred method of connection is directly to the HTTP/S service using the hostname and port numbers below, for clients that can only connect out on standard ports please see Proxy Connection Details:

  Non SSL SSL Connections
Hostname
sms.world-text.com
sms.world-text.com
Port
80
443

Example call from a browser address bar:
http://sms.world-text.com:1081/ping

Proxy Connection Details

For clients that can only connect out on the HTTP/S ports then all calls should be made via the WorldText website proxying API for the HTTP service.

  Non SSL SSL Connections
Hostname
www.world-text.com
www.world-text.com
Port
80
443
URL Prefix
/proxyapi
/proxyapi

Example call from a browser address bar:
https://www.world-text.com/proxyapi/ping

Method Summary

Delivery & Query Methods
Method Description
querysms Query the delivery status of a message
sendsms Sends a text message to a mobile device or UK land line
wappush Delivers a basic WAP Push message to a mobile device

Group Management Methods
Method Description
groupadd Add a new number to an existing group
groupcreate Create a new group list, this is a list of numbers that messages can be sent to in one call
groupdel Deletes a number from an existing group
groupdelall Deletes all numbers from an existing group
groupget Retrieves all the numbers from an existing group
groupgetdetails Retrieves all the numbers and names from an existing group
groupremove Remove an exisiting group list
sendgroup Dispatches a message to a predefined group

Miscellaneous Methods
Method Description
credits Retrieves the amount of credit available on the specified account
ping Test interface availability & keep session key alive


Parameter Description

Please note that items in italics are in beta test and may be withdrawn or modified at any time.

Name Type Max Size Description
accid 4-6 digit number 6 Account ID
AUTH key or user/pass n/a See Authentication section
callback URL n/a Message Status callback HTTP URL
data HEX string unlimited Encoded message content
dstaddr number list 25 numbers Destination Address List (recipients)
grpid 1-6 digit number 6 Group list ID
key HEX string 32 API key
msgid HEX string 32 Message ID
multipart 1 digit number 1 Max number of SMS parts (default 1)
name string 20 A user defined name
none none none No argument is required for this call
pass string 50 Account Password
srcaddr string or number 16 Source Address (sender)
txt ISO 8859 string unlimited Plain text string to be sent
url URL n/a Uniform Resource Locator
user string 50 Account Username

List Parameters

Parameters that are specified as being a list can consist of one or more values seperated by a comma sybmol (,). An example would be the dstaddr field, following is an example of specifying values for these fields

Return Values

Every line returned as a result from the HTTP interface is prefixed by the values shown in the table below.

SUCCESS
the request was either fully or partially successful
FAIL
the request failed

Following the above strings will be the method return values, for certain interface calls there may be more than one result line returned.

Authentication

Most calls to the HTTP/S interface require that authentication parameters are sent along with the request, this can be handle one of two ways:

Username & Password

For every call to the interface requires that the username and password fields (user & pass) are provided. This method is simple however is less secure on non SSL connections.

API Key

For every call to the interface an API key (key) is passed.

Method Detail

Please note that items in italics are in beta test and may be withdrawn or modified at any time.

credits

Description Retrieves the amount of credit available on the specified account
Required Args AUTH
Return Value credits remaining on the account, e.g:

SUCCESS 999

Policy Do not check more than once every 120 seconds

groupadd

Description Delete an entry from a group
Required Args AUTH, grpid, dstaddr, name
Return Value SUCCESS or FAIL

groupcreate

Description Create a new group list, this is a list of numbers that messages can be sent to in one call
Required Args AUTH, name, srcaddr, pin
Return Value SUCCESS [group ID] or FAIL

groupdel

Description Delete an entry from a group
Required Args AUTH, grpid, dstaddr
Return Value SUCCESS or FAIL

groupdelall

Description Deletes all entries from a group
Required Args AUTH, grpid
Return Value SUCCESS <entries deleted> or FAIL

groupget

Description Retrieves all the numbers in a group
Required Args AUTH, grpid
Return Value Numbers on consecutive lines or FAIL

groupgetdetails

Description Retrieves all the numbers and names in a group
Required Args AUTH, grpid
Return Value Numbers and names on consecutive lines or FAIL, e.g.: "0700000000","Alan B Smith"

groupremove

Description Description Deletes and entire group
Required Args AUTH, grpid
Return Value SUCCESS or FAIL

querysms

Description Query the delivery status of a message
Required Args AUTH, msgid
Return Value Message status value
Policy Initial check for delivery at a minimum of 15 seconds after submission. All further checks should be double the previous time frame, in the case the next check would be at 30 seconds, then 60 seconds etc.

ping

Description Test interface availability & optionally key session key alive
Required Args none
Optional Args key
Return Value SUCCESS or FAIL

sendgroup

Description Sends a text message to a group
Required Args AUTH, grpid, txt
Optional Args srcaddr, multipart, test
Return Value Number of messages dispatched

sendsms

Description Sends a text message to a mobile device or UK land line
Required Args AUTH, dstaddr, txt
Optional Args srcaddr, multipart, callback
Return Value Multiline response of a message id followed by the credits remaining (if applicable) on the account, there will be one line for each message dispatched eg:

SUCCESS 123 999
SUCCESS 124 989

submitsm

Description Not yet impletemented

wappush

Description Delivers a basic WAP Push message to a mobile device
Required Args AUTH, dstaddr, txt, url
Optional Args srcaddr
Return Value Multiline response of a message id followed by the credits remaining (if applicable) on the account, there will be one line for each message dispatched eg:

SUCCESS 123 999
SUCCESS 124 989

Restrictions url and txt parameter limited to 154 characters combined

Failure Codes

If a request does not result in success then the response will be FAIL code where code is one of the following failure codes.

Failure Code Description Application Action
ARGUMENTS The wrong number of arguments were supplied. Refer to the specification. Do not retry
AUTHORISATION The credentials used to authenticate the account were specified incorrectly. Do not retry
BLACKLISTED The MSISDN is blacklisted, do not retry, Do not retry
CREDIT Not enough credit remaining on the account. Do not retry
DESTINATION MSISDN specified was not long enough or in the correct format. Do not retry
DISABLED Account being used is disabled or suspended, contact support. Do not retry
EXCEPTION An application exception occured, contact support. Do not retry
INTERNAL An internal routing error occurred, please retry your message. Retry immeadiately
INVALIDARGS The arguments failed to meet the method requirements. Do not retry
KEYEXPIRED The key has expired or does not exist. Complete authentication
MESSAGEID Invalid or blank messages ID, contact support. Do not retry
SOURCEADDR An unallocated source address was specified. Do not retry
SUBMITRESP Incorrect SMPP response received, please retry your message. Retry immeadiately
TIMEOUT SMPP Response not received in time, retry your message. Retry immeadiately
THROTTLED To much traffic is being submitted through this interface. Retry after 20 seconds
UNKNOWNCMD Command is unknown Do not retry
VERSION Incorrect interface version specified Do not retry

 

Message Status Callback

Optionally an HTTP URL can be specified that is called once when a message status changes, the normal status change is to a final state such as DELIVRD which indicates that the message has been delivered. The call is to a standard HTTP POST to a URL and should be specified in full, e.g. "http://myserver.com/smsstatus.php".

Callback Parameters


Parameter Description
error Error status of the message (see Error Codes in Documentation)
msgid Message ID that was returned when the submission was made
state State of the message, DELIVRD, EXPIRED, UNDELIV, ACCEPTD, REJECTD