SMS API Documentation
Use the World Text custom APIs - HTTP REST, SMPP and SMTP to add SMS functionality to your applications and services.
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 fieldsReturn 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:
|
| 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:
|
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:
|
| 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 |