HTTP Interface Specification
Connection Details
| |
Non SSL |
SSL Connections |
| Hostname |
sms.world-text.com |
sms.world-text.com |
| Port |
1081 |
1082 |
Method Summary
| Authentication Methods |
| Method |
Description |
| delauthkey |
Deletes an allocated authorisation key |
| getauthkey |
Retrieves an authorisation key for further transactions |
| Delivery & Query Methods |
| Method |
Description |
| querysms |
Query the delivery status of a message |
| sendtxt |
Sends a text message to a mobile device or UK land line |
| submitsm |
Not yet impletemented |
| 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 |
| groupremove |
Remove and 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 |
Authorisation key (see getauthkey) |
| msgid |
HEX string |
32 |
Message ID |
| multipart |
1 digit number |
1 |
Max number of SMS parts (default 1) |
| 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.
Authentication Key
For every call to the interface an authentication key (key) is passed. This key is obtained by an initial call to getauthkey and when the sessions is finished it is removed by a call to delauthkey, or the key will expire after 10 minutes of inactivity. This method is the most secure option and for bulk use a quicker means of authentication.
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 that once every 120 seconds |
delauthkey
| Description |
Deletes an allocated session authorisation key |
| Required Args |
key |
| Return Value |
OK on success |
getauthkey
| Description |
Allocates and retrieves a session authentication key that is valid for one session. The key expires after a prefinded period, it is also removed on application restarts and should be deleted when finished with. |
| Required Args |
user, pass |
| Return Value |
HEX string value |
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 |
OK or FAIL |
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 |