SMS API Documentation
Use the World Text custom APIs - HTTP REST, SMPP and SMTP to add SMS functionality to your applications and services.
HTTP REST API Introduction
The World Text REST API is able to query a selection of resources, make groups, and and remove numbers from groups, and send SMS text messages.
You can call any part of the API from within a browser, which is very helpful during development and testing.
Base URL
GET
https://sms.world-text.com/v2.0/
For your privacy and security, the https call is preferred and recommended, but you are free to call the API over open http if you wish.
All calls to the World Text REST API require authorisation using the account ID and the secret API key which can be change and viewed on the World Text account page, on the API tab.
Submission Speed
Clients should submit to the HTTP REST API at no more than 10 messages per second, accounts submitting faster than this will be either throttled or suspended. If your application requires a faster submission speed, please contact us to request this.
HTTP Method - IMPORTANT
The HTTP method is part of the command. For example adding a group entry and deleting a group entry are distinguished only by the HTTP method - PUT or DELETE.
Depending on what you are actually asking of the resource you are calling, the HTTP method will change. OPTION is not used, but GET, PUT and DELETE are used as appropriate.
GET queries a resource
PUT creates or updates a resource (Including send)
DELETE removes a resource
From a Browser - Use Method Overloading
Given that some clients and languages are restricted in what HTTP methods are available, we've provided a way for you to still be able to use these.
You can make a GET call and append the actual method as a parameter. For instance if you want to make a call to DELETE, you'd append "&method=DELETE" to the end of the call.
https://sms.world-text.com/v2.0/group/contents?id=AccountID&key=APIKey&grpid=GroupID&method=DELETE
This has an added advantage that it allows developers to test calls in a browser, and instantly see results or errors.
Method parameter (DELETE, PUT, GET) must be in capitals, or it will fail.
Simulating Calls
Any part of the API can be operated in simulated mode by apending &sim to any call. You can create groups, query, delete, but any sending of SMS text messages will
be processed, but not sent. You'll get a simulated response with message ID and a receipt is generated.
This, of course, allows you to test your app or site without incurring charges until you are ready to send live test data. Please be aware that currently only numbers formatted for the UK (i.e. 44XXXX...) will succeed, please contact us to have additional destinations added to the simulator.
You can run simulated against any resource, but of course it only really makes sense against sms/send and group/send.
Delivery Receipts via Callback
HTTP Callback URL
This callback URL is called when a message reaches Final State (which is when a message reaches it's end of life), whether that is rejection, delivery, expiry, or undeliverable.
Whilst you will typically receive receipts coming back within a few seconds of the message being sent it is entirely possible for the time to be in the order of a couple of days when it's expiring due to non-delivery.
Set your delivery receipt callback URL via the 'Configuration' tab on your account dashboard here.
Please do not attempt to use deprecated API functions to query the delivery status.Callback POST Parameters
Default Parameters
| Parameter | Description |
|---|---|
msgid
|
The World Text Message ID. |
error
|
The error number (if any) associated with this message. |
state
|
The final message state of this message can be one of:
|
date
|
The date and time in yymmddhhmm format that the message reached it's final state. |
Optional Parameters
| Parameter | Description |
|---|---|
clientref
|
A string which is only returned if the clientref optional parameter was set in the call to send. Please note clientref parameter is used with a group send, every message in the group will have the same clientref parameter returned in the delivery receipt. |
e212
|
A numeric value of 5 or 6 digits with indicates which network the destination number belongs to. This is what's known as the E.212 code or MCC/MNC (Mobile Country Code / Mobile Network Code, for reference you can see these values on our coverage page. This information will only be returned when the message reaches it's final state. Please note, this functionality is not available for all destinations / networks, in the event the information is not available the content returned for MCC/MNC will be '000000'. The e212 optional parameter functionality for delivery receipts must be requested to be enabled on your account, please contact us to request this. |
http://yourdomain.com?msgid=MessageID&error=ErrorCode&state=MessgaeState&date=DateAndTime
HTTP Server Responses
The World Text REST API can return a selection of HTTP response codes depending on the success or otherwise of your API call. Typically you're going to get a return of 200 or 201 indicating success.
JSON or XML
By Default each API call returns a JSON encoded response. This can be changed to XML by appending "&xml" to each API call.
Possible GET Responses
| Code | Description |
|---|---|
200 OK |
The request was processed successfully |
307 Temporary redirect |
Please use the alternative server provided in the response for the duration of your session. This is primarily used for load balancing |
400 Bad request |
Bad arguments typically |
401 Unauthorised |
Incorrect authorisation info |
404 Not Found |
Not found |
405 Method Not allowed |
Method not allowed |
429 Too Many requests |
Slow down! |
500 Server Error |
Internal error, go away. :) |
503 Service Unavailable |
Service unavailable |
Possible PUT Responses
| Code | Description |
|---|---|
200 OK |
The request was processed successfully. We updated the resource |
201 Created |
We created the resource |
307 Temporary redirect |
Please use the alternative server provided in the response for the duration of your session. This is primarily used for load balancing |
400 Bad request |
Bad arguments typically |
401 Unauthorised |
Incorrect authorisation info |
403 Forbidden |
Prepay PAYG account is out of credit |
404 Not Found |
Not found |
405 Method Not allowed |
Method not allowed |
429 Too Many requests |
Slow down! |
500 Server Error |
Internal error, go away. :) |
503 Service Unavailable |
Service unavailable |
Possible DELETE Responses
| Code | Description |
|---|---|
200 OK |
The request was processed successfully. We deleted the resource |
307 Temporary redirect |
Please use the alternative server provided in the response for the duration of your session. This is primarily used for load balancing |
400 Bad request |
Bad arguments typically |
401 Unauthorised |
Incorrect authorisation info |
404 Not Found |
Not found |
405 Method Not allowed |
Method not allowed |
429 Too Many requests |
Slow down! |
500 Server Error |
Internal error, go away. :) |
503 Service Unavailable |
Service unavailable |
Possible Error Codes
As well as the HTTP return code, we populate a JSON response containing a status of "1", and an error and description field.
The majority of error cases should be detectable from the HTTP response.
| Error | Desc |
|---|---|
1000 |
Authorisation Failure |
1100 |
Insufficient funds remaining |
1024 |
Insufficient credit on pre-pay account |
1025 |
Account is disabled / not activated |
1026 |
Destination number is blacklisted, and cannot be sent to |
1027 |
Destination country is invalid or not allowed on your account |
1200 |
Incorrect arguments specified |
1201 |
Unknown Command |
1202 |
Bad Request |
1204 |
Not Implemeneted |
1300 |
Specified group name already exists |
1301 |
Specified group is empty |
1302 |
Specified group ID does not exist |
1303 |
Specified group name length is invalid |
1400 |
No information for the MSISDN was available |
1900 |
Unknown Error |
HTTP REST Interface with PHP Example
// Basic function used to call World-Text.com this should be enhanced to
// do failover testing between the main servers for invoiced clients.
function sendSMS($accid, $apikey, $dstaddr, $txt, $srcaddr = "SMSAlert") {
// Using host sms1 for this script, this will only work for all clients
$host = "sms1.world-text.com";
// Build the URL we are going to post our request to
$data = urlencode($txt);
$srcaddr = urlencode($srcaddr);
$url = "http://$host/sms/send";
$body = "id=$accid&key=$apikey&srcaddr=$srcaddr&dstaddr=$dstaddr&txt=$data";
// Initialise CURL
$ch = curl_init();
// set the target url
curl_setopt($ch, CURLOPT_URL, $url);
// tell curl we are posting this URL
curl_setopt($ch, CURLOPT_POST, 1);
// Add the arguments to the body of the call
curl_setopt($ch, CURLOPT_POSTFIELDS, "$body");
// Return the data rather than printing
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Make the call and grab the results
$result = curl_exec($ch);
// All done so close up
curl_close($ch);
return $result;
}
// Account ID, this can be found on the main logged in page at World-Text.com
$accid = 0123;
// This is your API Key, this key can be modified on the World-Text website
$apikey = "1234567ab8c9d0e1";
// Call the sendSMS function with the required parameters
$result = sendSMS($accid, $apikey, "447890123456", "Hello this is a PHP SMS Test from World-Text using the HTTP Interface", "SMSAlert");
// Print the result out
echo $result;
HTTP Admin Functions
Admin functions are used to query credits available and ping our SMSC.
Credits on Account
For Prepay customers returns the number of credits available to you currently on your account.
For Account customers returns the number of credits used this accounting period (as a negative balance).
Resource URI
GET
https://sms.world-text.com/v2.0/admin/credits
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
https://sms.world-text.com/v2.0/admin/credits?id=AccountID&key=APIKey
Responses
Success Example JSON
{
"status":"0",
"credits":"2950"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<credits>2950</credits>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Ping SMSC
Ping the World Text SMSC to check alive state.
Resource URI
GET
https://sms.world-text.com/v2.0/admin/ping
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
https://sms.world-text.com/v2.0/admin/ping?id=AccountID&key=APIKey
Responses
Success Example JSON
{
"status":"0"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
HTTP Inbound SMS Description
Using the HTTP API MO SMS are passed to a URL of your choice. The URL can be unique per each inbound number or per keyword. The system automatically passes all messages to the specified URL using the ‘HTTP GET’ request.
Encoding
By default Inbound (MO) SMS passed to your URL are encoded as GSM. For SMS that may have Unicode / UCS-2 content, please see and use the HTTP Binary method for inbound SMS.
If our platform receives an SMS identified as having Unicode / UCS-2 content, then the message will automatically be passed to you in binary format.
SSL (HTTPS)
SSL (HTTPS) is supported, and can be enabled by simply specifying 'HTTPS' in your URL when creating your Auto Responder rule.
Retry Profile
Should your server fail to give a success resposne (status 200) promptly, inbound SMS will enter an account specific queue and attempt to return SMS to your server a further two times, at 60 second intervals before giving up. Clients can download details of all inbound messages for the preceeding 6 months via the reporting page.
At special request the retry profile can be changed, on a per Auto Responder rule basis.
Inbound HTTP Format
The following parameters are used when returning inbound SMS to your URL via the Auto Responder.
Values
| Parameter | Description |
|---|---|
mobile
|
Source address of sender. |
destaddr
|
Destination number of inbound SMS, i.e. to which number or short code the inbound SMS was sent to. |
keyword
|
Using keyword based rule:Keyword based Auto Responder rules will return the keyword (first word of message) in the 'keyword' parameter, and the remainder of the message in the 'message' parameter. Using #Hashtag based rule:Hastag based Auto Responder rules will return the Hashtag (format '#yourHashtag') irrespective of where in the message it appears, in the 'keyword' parameter, and the full message in the 'message' parameter which will include the #Hashtag. Note: Hashtags can only be used on dedicated numbers. Using Keyword + #Hashtag rules togetherA message may have a combination of a single keyword and multiple #Hashtag based rules within the message. The keyword Auto Responder rule will be run first, and then each #Hashtag rule as they appear in a message. Each Keyword and #Hashtag rule will be a separate call made to your URL. Note: Hashtags can only be used on dedicated numbers. Using catch all rule:Catch all based Auto Responder rules will return the first word of the message in the 'keyword' parameter, which of course can be ignored unless you have a purpose for this. The full message including the first word of the message is returned in the 'message' parameter. |
message
|
Message content. |
timestamp
|
The date and time the inbound SMS was received in the format: yyyy-mm-dd hh:mm:ss |
password
|
If you have specified a password in your Auto Responder rule, this will be returned in this field. |
Using keyword based rule:
http://your.url/?mobile=Number&destaddr=Number&keyword=KEYWORD&message=MESSAGE×tamp=yyyy-mm-dd hh:mm:ss&password=PASSWORD
Using catch all rule:
http://your.url/?mobile=Number&destaddr=Number&keyword=FirstWordOfMessage&message=MESSAGE×tamp=yyyy-mm-dd hh:mm:ss&password=PASSWORD
Inbound HTTP Format Binary
The following parameters are used when returning binary encoded inbound SMS to your URL via the Auto Responder.
Values
| Parameter | Description |
|---|---|
mobile
|
Source address of sender. |
destaddr
|
Destination number of inbound SMS, i.e. to which number or short code the inbound SMS was sent to. |
len
|
Length of message – numeric value. |
dcs
|
Data Coding Scheme - values:
|
esm
|
Default value is 0. If a response of 64 is returned this probably means it is a multi-part message. |
data
|
Data content of message. |
timestamp
|
The date and time the inbound SMS was received in the format: yyyy-mm-dd hh:mm:ss |
password
|
If you have specified a password in your Auto Responder rule, this will be returned in this field. |
http://your.url/?mobile=NUMBER&destaddr=NUMBER&len=LENGTH&dcs=DataCoding&esm=ESM&data=DataContent×tamp=yyyy-mm-dd hh:mm:ss&password=PASSWORD
Inbound URL
The URL that inbound (MO) SMS are passed to is set when configuring your Auto Responder rules.
HTTP HLR Lookup Description
Performs an HLR (Home Location Register) lookup of a mobile number to query it's validity and state. HLR lookups can be used for routing, number verification and security purposes.
Please note, in order to use this service your account must first be migrated to an HLR lookup account and be enabled, to do this please contact us.
Resource URI
GET
https://sms.world-text.com/v2.0/hlr/lookup
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
msisdn
|
Mobile phone number in E.164 international format without the leading '+'. For example '447989123456'. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's perform a lookup of the UK mobile number 07989 123456
https://sms.world-text.com/v2.0/hlr/lookup?id=AccountID&key=APIKey&msisdn=447989123456
Responses
Success Example JSON
{
"status":"0",
"msisdn":"447989123456",
"state":"OK",
"imsi":"234101231231230"
"location":"44"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<msisdn>447989123456</msisdn>
<state>OK</state>
<imsi>234101231231230</imsi>
<location>44</imsi>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Fields Returned
| Field | Description |
|---|---|
STATUS
|
Successful/unsuccessful submission of request. |
MSISDN
|
Number submitted to lookup. |
STATE
|
Response returned by HLR lookup. |
IMSI
|
Numeric IMSI number where available, MCC MNC as a minimum will be returned. |
LOCATION
|
The current location of the handset, defined by country code. |
Possible Values of State Field
| Result | Description |
|---|---|
ABSENT_SUBSCRIBER
|
The subscriber is absent. |
BLOCKED
|
Request is blocked. |
CALL_BARRED
|
The service is restricted by the destination network. |
DATA_MISSING
|
The data was missing. |
FAIL
|
Generic failure result. |
HLR_ABORT
|
The HLR (or some other entity) aborted the request. No response to the request was received. |
HLR_CANCEL
|
No response for the HLR request was received. |
HLR_REJECT
|
The HLR request was rejected. |
HLR_TIMEOUT
|
No response for the HLR request was received. |
NOT_SUPPORTED
|
Short message facility is not supported. |
OK
|
The request was successful. |
THROTTLED
|
Maximum ongoing requests exceeded. |
SYSTEM_FAILURE
|
A system failure occurred in the HLR. |
UNKNOWN
|
An unexpected response was received. |
UNKNOWN_SUBSCRIBER
|
The subscriber is unknown. |
HTTP MNP Lookup Description
Performs an MNP (Mobile Number Portability) lookup of a mobile number to query it's validity, network and ported from network (if applicable). Where this information is not permitted in a country, prefix based information is returned based on databases from operators worldwide, which can still provide accurate home network information.
Please note, in order to use this service your account must first be migrated to an MNP lookup account and be enabled, to do this please contact us.
Resource URI
GET
https://sms.world-text.com/v2.0/hlr/mnp
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
msisdn
|
Mobile phone number in E.164 international format without the leading '+'. For example '447989123456'. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's perform a lookup of the UK mobile number 07989 123456
https://sms.world-text.com/v2.0/hlr/mnp?id=AccountID&key=APIKey&msisdn=447989123456
Responses
Success Example JSON
{
"status":"0",
"msisdn":"447989123456",
"state":"OK",
"imsi":"23410"
}
or
{
"status":"0",
"msisdn":"447989123456",
"state":"OK",
"imsi":"23410"
"location":"44"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<msisdn>447989123456</msisdn>
<state>OK</state>
<imsi>23410</imsi>
</result>
or
<result>
<status>0</status>
<msisdn>447989123456</msisdn>
<state>OK</state>
<imsi>23410</imsi>
<location>44</imsi>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Fields Returned
| Field | Description |
|---|---|
STATUS
|
Successful/unsuccessful submission of request. |
MSISDN
|
Number submitted to lookup. |
STATE
|
Response returned by HLR lookup. |
IMSI
|
Numeric IMSI number where available, MCC MNC as a minimum will be returned. |
Possible Values of State Field
| Result | Description |
|---|---|
ABSENT_SUBSCRIBER
|
The subscriber is absent. |
BLOCKED
|
Request is blocked. |
CALL_BARRED
|
The service is restricted by the destination network. |
DATA_MISSING
|
The data was missing. |
FAIL
|
Generic failure result. |
HLR_ABORT
|
The HLR (or some other entity) aborted the request. No response to the request was received. |
HLR_CANCEL
|
No response for the HLR request was received. |
HLR_REJECT
|
The HLR request was rejected. |
HLR_TIMEOUT
|
No response for the HLR request was received. |
NOT_SUPPORTED
|
Short message facility is not supported. |
OK
|
The request was successful. |
THROTTLED
|
Maximum ongoing requests exceeded. |
SYSTEM_FAILURE
|
A system failure occurred in the HLR. |
UNKNOWN
|
An unexpected response was received. |
UNKNOWN_SUBSCRIBER
|
The subscriber is unknown. |
HTTP SMS Functions
Using these functions you may check costs, send and query for individual numbers.
Cost To Send SMS
Returns the number of credits a single message would cost to send to this destination.
If for any reason the system is unable to infer accurately the cost it will return the default cost of 20 credits.
Resource URI
GET
https://sms.world-text.com/v2.0/sms/cost
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
dstaddr
|
Destination phone number in E.164 international format without the leading '+'. For example '447989123456'. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's check the cost of sending a text message to the UK mobile number 07989 123456
https://sms.world-text.com/v2.0/sms/cost?id=AccountID&key=APIKey&dstaddr=447989123456
Responses
Success Example JSON
{
"status":"0",
"credits":"10"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<credits>10</credits>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Send SMS
Standard SMS
Sends an SMS Text message to a single destination. The message is supplied as normal URL encoded text after the parameter txt.
With text mode sends, the default encoding is GSM. You can specify other non-GSM character set content by setting the optinal 'enc' parameter to UnicodeBigUnmarked.
Binary SMS
For sending binary data (frequently machine to machine (M2M) data), you need to replace the txt parameter with data. You must follow data with a hex encoded string representing your data.
You also need to supply a dcs parameter which is the data coding scheme.
The data coding scheme is as per the SMPP specification.
In the case of binary data, this should be set to 2 (Octet unspecified (8-bit binary)).
Resource URI
PUT
https://sms.world-text.com/v2.0/sms/send
PUT Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
dstaddr
|
Destination phone number in E.164 international format without the leading '+'. For example '447989123456'. |
txt
|
The SMS Text message(s) to be sent. If you exceed the standard length of an SMS message (140 bytes) we will ignore any excess unless the multipart optional
parameter is specified. For the actual number of characters you can send, please see How long is an SMS Text Message Really? |
Optional Parameters
| Parameter | Description |
|---|---|
clientref
|
Client Reference: This is a custom variable that can be populated with any value up to a maximum size of 32 characters. This field is returned when the message reaches a final state if delivery receipts are being accepted by HTTP. |
data
|
Replaces the text parameter. Specifies the data to be sent, which is a hex encoded binary stream. |
dcs
|
Data Coding Scheme. Should be set to 2 (Octet unspecified (8-bit binary)). As per the SMPP specification. |
delay
|
Delay: On sending a single SMS /send/sms you can specify the parameter delay that is a number in seconds to delay the submission of a message to the mobile networks. Maximum delay is 60 seconds. However we recommend clients handle delays until full scheduled SMS function which is in development is available, as delayed messages will not survive an SMSC restart. |
enc
|
For use with non-GSM character set content. Must be set to UnicodeBigUnmarked, otherwise the text is treated as being the default GSM encoding. |
expiry
|
Numeric value specified in seconds. Specifies the message validity period, if a message is not delivered during this time it will expire in the operators SMSC. The default is 48 hours, this does not need to be set. Not all operators support message validity period and this should not be set to more than 7 days (604800). |
multipart
|
The maximum number of messages to be sent, to a maximum of 9. If the text contains more characters than can be sent in {multipart} messages, any excess characters are silently lost. If not specified and your message exceeds 160 characters (GSM encoded), the default is 1 message. |
sendid
|
A reference of your own to make it easier to generate reports and statistics for your SMS. Maximum size of 32 characters |
sim
|
Simulated: No message is sent, but the message is accepted, processed and a result returned. This is a cost-free way of developing your app without needing to waste lots of sent messages. The simulator currently is configured for UK numbers, however additional country's can be added upon request. |
srcaddr
|
Source address: Can be one of your allocated source addresses or stored numbers, or string as specified in your World Text account. If none is specified, the
account default is used.
Numeric source addresses (most commonly - mobile numbers) can be a maximum of 16 numbers long, and contain only numeric characters, no letters or special characters allowed. Alphanumeric source addresses (numbers & letters) can be a maximum of 11 characters and can contain the following characters: A-Z, a-z and 0-9. No special characters allowed. Short Code source addresses are usually a 5 or 6 digit number (e.g. 84101), which are made up of numeric characters only, no letters or special characters allowed. To request additional source addresses and view existing, please login to your account. |
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Standard SMS
Let's send "hello world" as a text message to the UK mobile number 07989 123456
https://sms.world-text.com/v2.0/sms/send?id=AccountID&key=APIKey&srcaddr=SMSAlert&dstaddr=447989123456&txt=hello%20world
Binary SMS
Sending a stream of binary data (actually the string "Hello World" encoded in hex) as a text message to the UK mobile number 07989 123456
In this case encoding is set to Octet unspecified (8-bit binary).
https://sms.world-text.com/v2.0/sms/send?id=AccountID&key=APIKey&srcaddr=SMSAlert&dstaddr=447989123456&data=48656C6C6f20576F726C64&dcs=2
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=PUT to the call. This overloads the browser's default http GET and treats it as a PUT.
PUT must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/sms/send?id=AccountID&key=APIKey&srcaddr=SMSAlert&dstaddr=447989123456&txt=hello%20world&method=PUT
Responses
Success Example JSON
{
"status": "0",
"message": [
{
"state": "0",
"dstaddr": "447989123456",
"msgid": "31CD0DAB",
"credits": "0"
}
]
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<message>
<msgid>31CD21F7</msgid>
<state>0</state>
<credits>0</credits>
<dstaddr>447989123456</dstaddr>
</message>
<status>0</status>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
SMS Query
Query SMS Status
When a message reaches Final State (which is when a message reaches it's end of life), whether that is rejection, delivery, expiry, or undeliverable this status is returned to you automatically. Please see Delivery Receipts via Callback for further information.
Please contact us to setup a URL for delivery receipts to be passed to.
HTTP SMS To Group Functions
Using these functions you may check costs, edit and send to groups.
Cost To Send SMS
Returns the number of credits a single text message would cost to send to every number in the group. This is only applicable for groups with messages to recipients all in the same country.
If for any reason the system is unable to infer accurately (unlikely) the cost of a particular number, that will be included in total at the default cost of 20 credits.
Resource URI
GET
https://sms.world-text.com/v2.0/group/cost
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The ID of the group to be checked. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's check the cost of sending a text message to the group ID 1234
https://sms.world-text.com/v2.0/group/cost?id=AccountID&key=APIKey&grpid=1234
Responses
Success Example JSON
{
"status": "0",
"credits": "510",
"entries": "51"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<credits>510</credits>
<entries>51</entries>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Create a Group
Creates a group to allow sending of a text message to all numbers in the group at once.
Resource URI
PUT
https://sms.world-text.com/v2.0/group/create
PUT Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
name
|
The name you want to assign to the group you're creating, without any spaces. |
pin
|
Usually 0000, but a PIN code is required to create a group. This can be used to allow remote despatch. |
srcaddr
|
Source address or phone number in E.164 international format without the leading '+'. For example '447989123456'. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's create a group, and call it Yoda. We'll not be using the PIN code so that can be set to 0000. Source address we'll set to SMSAlert.
https://sms.world-text.com/v2.0/group/create?id=AccountID&key=APIKey&name=Yoda&srcaddr=SMSAlert&pin=0000
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=PUT to the call. This overloads the browser's default http GET and treats it as a PUT.
PUT must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/group/create?id=AccountID&key=APIKey&name=Yoda&srcaddr=SMSAlert&pin=0000&method=PUT
Responses
Success Example JSON
{
"status": "0",
"groupid": "2024"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<groupid>2024</groupid>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Destroy (Remove) a Group
Removes a pre-existing group.
Resource URI
DELETE
https://sms.world-text.com/v2.0/group/destroy
DELETE Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The ID of a previously created group. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's destroy a group with the ID 1234.
https://sms.world-text.com/v2.0/group/destroy?id=AccountID&key=APIKey&grpid=1234
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=DELETE to the call. This overloads the browser's default http GET and treats it as a DELETE.
DELETE must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/group/destroy?id=AccountID&key=APIKey&grpid=1234&method=DELETE
Responses
Success Example JSON
{
"status": "0"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Get Group Details
Returns all the name and number pairs in the given group.
Resource URI
GET
https://sms.world-text.com/v2.0/group/details
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The ID of a previously created group. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's get the details of a group with the ID 1234.
https://sms.world-text.com/v2.0/group/details?id=AccountID&key=APIKey&grpid=1234
Responses
Success Example JSON
{
"status": "0",
"entry": [
{
"name": "Harry",
"number": "447989001133"
},
{
"name": "Fred",
"number": "447989112233"
},
{
"name": "Boris",
"number": "447989112244"
}
]
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<entry>
<name>Harry</name>
<number>447989001133</number>
</entry>
<entry>
<name>Fred</name>
<number>447989112233</number>
</entry>
<entry>
<name>Boris</name>
<number>447989112244</number>
</entry>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Delete Group Contents
Deletes ALL the names and numbers in the specified group.
Resource URI
DELETE
https://sms.world-text.com/v2.0/group/contents
DELETE Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The ID of a previously created group. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's delete all entries of a group with the ID 1234.
https://sms.world-text.com/v2.0/group/contents?id=AccountID&key=APIKey&grpid=1234
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=DELETE to the call. This overloads the browser's default http GET and treats it as a DELETE.
DELETE must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/group/contents?id=AccountID&key=APIKey&grpid=1234&method=DELETE
Responses
Success Example JSON
{
"status": "0"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Delete Single Entry from a Group
Deletes a single entry from a group.
Resource URI
DELETE
https://sms.world-text.com/v2.0/group/entry
DELETE Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The ID of a previously created group. |
dstaddr
|
The Destination address (Number) to be removed. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's delete an entries with the UK number 07989 123456 in a group with the ID 1234.
https://sms.world-text.com/v2.0/group/entries?id=AccountID&key=APIKey&grpid=1234&dstaddr=447989123456
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=DELETE to the call. This overloads the browser's default http GET and treats it as a DELETE.
DELETE must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/group/entries?id=AccountID&key=APIKey&grpid=1234&dstaddr=447989123456&method=DELETE
Responses
Success Example JSON
{
"status": "0"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Add Entries to a Group
Adds a list of name/number pairs to a group.
The list must be in the format number:name,number2:name2 etc.
Numbers must be unique within the group, names need not be.
Resource URI
PUT
https://sms.world-text.com/v2.0/group/entries
PUT Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The group to add entries to. |
members
|
A list of names and numbers to be added. The list must be in the following format Number:Name,Number:Name etc. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's add a couple of entries to the group 1234
https://sms.world-text.com/v2.0/group/entries?id=AccountID&key=APIKey&grpid=1234&members=447989112233:Fred,447989112244:Boris
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=PUT to the call. This overloads the browser's default http GET and treats it as a PUT.
PUT must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/group/entries?id=AccountID&key=APIKey&grpid=1234&members=447989112233:Fred,447989112244:Boris&method=PUT
Responses
Success Example JSON
{
"status": "0",
"added": "2"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<added>2</added>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Add Single Entry to a Group
Adds a single name/number pair to a group.
Number must be unique within the group.
Resource URI
PUT
https://sms.world-text.com/v2.0/group/entry
PUT Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The group to add entries to. |
dstaddr
|
The Destination address (Number) to be added. |
name
|
The entry name. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Let's add an entry of the UK number 07989 110000 which belongs to Harry to the group 1234
https://sms.world-text.com/v2.0/group/entry?id=AccountID&key=APIKey&grpid=1234&dstaddr=447989110000&name=Harry
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=PUT to the call. This overloads the browser's default http GET and treats it as a PUT.
PUT must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/group/entry?id=AccountID&key=APIKey&grpid=1234&dstaddr=447989110000&name=Harry&method=PUT
Responses
Success Example JSON
{
"status": "0",
"added": "2"
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<added>2</added>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Get Group List
List all groups currently stored on this account.
Resource URI
GET
https://sms.world-text.com/v2.0/group/list
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
https://sms.world-text.com/v2.0/group/list?id=AccountID&key=APIKey
Responses
Success Example JSON
{
"status": "0",
"group": [
{
"id": "2024",
"name": "yoda"
}
]
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<group>
<id>2024</id>
<name>yoda</name>
</group>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Get Numbers in a Group
Returns all the numbers in a particular group.
Resource URI
GET
https://sms.world-text.com/v2.0/group/numbers
GET Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
The ID of the group to be checked. |
Optional Parameters
| Parameter | Description |
|---|---|
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
https://sms.world-text.com/v2.0/group/numbers?id=AccountID&key=APIKey&grpid=1234
Responses
Success Example JSON
{
"status": "0",
"entry": [
{
"number": "447989112244"
},
{
"number": "447989112233"
}
]
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
<result>
<status>0</status>
<entry>
<number>447989112244</number>
</entry>
<entry>
<number>447989112233</number>
</entry>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
Send SMS To Group
Standard SMS
Sends an SMS Text message to a group. The message is supplied as normal URL encoded text after the parameter txt.
With text mode sends, the default encoding is GSM. You can specify other non-GSM character set content by setting the optinal 'enc' parameter to UnicodeBigUnmarked.
Binary SMS
For sending binary data (frequently machine to machine (M2M) data), you need to replace the txt parameter with data. You must follow data with a hex encoded string representing your data.
You also need to supply a dcs parameter which is the data coding scheme.
The data coding scheme is as per the SMPP specification.
In the case of binary data, this should be set to 2 (Octet unspecified (8-bit binary)).
Resource URI
PUT
https://sms.world-text.com/v2.0/group/send
PUT Parameters
Required Parameters
| Parameter | Description |
|---|---|
id
|
Account ID from your World Text account page. |
key
|
Hex authorisation key (Generated for you, and accessible from your World-Text account page on the API tab). |
grpid
|
Destination phone number in E.164 international format without the leading '+'. For example '447989123456'. |
txt
|
The SMS Text message(s) to be sent. If you exceed the standard length of an SMS message (140 bytes) we will ignore any excess unless the multipart optional
parameter is specified. For the actual number of characters you can send, please see How long is an SMS Text Message Really? |
Optional Parameters
| Parameter | Description |
|---|---|
clientref
|
Client Reference: This is a custom variable that can be populated with any value up to a maximum size of 32 characters. This field is returned when the message reaches a final state if delivery receipts are being accepted by HTTP. |
data
|
Replaces the text parameter. Specifies the data to be sent, which is a hex encoded binary stream. |
dcs
|
Data Coding Scheme. Should be set to 2 (Octet unspecified (8-bit binary)). As per the SMPP specification. |
enc
|
For use with non-GSM character set content. Must be set to UnicodeBigUnmarked, otherwise the text is treated as being the default GSM encoding. |
multipart
|
The maximum number of messages to be sent, to a maximum of 9. If the text contains more characters than can be sent in {multipart} messages, any excess characters are silently lost. If not specified and your message exceeds 160 characters (GSM encoded), the default is 1 message. |
rdelay
|
Repeat delay: Used in conjunction with the parameter 'repeats', this is the delay between the repeated group message send. A maximum of 180 seconds may be specified. |
repeats
|
Repeat amount: Used in conjunction with the parameter 'rdelay', this is the number of times a group message send is repeated. A maximum of 10 repeats may be specified. |
sendid
|
A reference of your own to make it easier to generate reports and statistics for your group SMS. Maximum size of 32 characters |
sim
|
Simulated: No message is sent, but the message is accepted, processed and a result returned. This is a cost-free way of developing your app without needing to waste lots of sent messages. The simulator currently is configured for UK numbers, however additional country's can be added upon request. |
srcaddr
|
Source address: Can be one of your allocated source addresses or stored numbers, or string as specified in your World Text account. If none is specified, the
account default is used.
Numeric source addresses (most commonly - mobile numbers) can be a maximum of 16 numbers long, and contain only numeric characters, no letters or special characters allowed. Alphanumeric source addresses (numbers & letters) can be a maximum of 11 characters and can contain the following characters: A-Z, a-z and 0-9. No special characters allowed. Short Code source addresses are usually a 5 or 6 digit number (e.g. 84101), which are made up of numeric characters only, no letters or special characters allowed. To request additional source addresses and view existing, please login to your account. |
subs
|
Substitute: By defining this parameter and including a substitute tags in your message body, the relevant text will be inserted automatically for you. Tags in txt content: {{time}} = will insert the current GMT time at point of message submission in the format HH:mm:ss. {{date}} = will insert the current date based on the UK at the point of message submission in the format yyyy/mm/dd. |
templates
|
Templates: A pre-defined template message is inserted as the message body, overriding any text specified in the txt parameter. New feature, definition for parameter to follow. |
xml
|
Specifies that results are returned in xml format rather than the default JSON. |
Standard SMS
Let's send "hello world" as a text message to the group ID 1234
https://sms.world-text.com/v2.0/group/send?id=AccountID&key=APIKey&srcaddr=SMSAlert&grpid=1234&txt=hello%20world
Binary SMS
Sending a stream of binary data (actually the string "Hello World" encoded in hex) as a text message to the group ID 1234
In this case encoding is set to Octet unspecified (8-bit binary).
https://sms.world-text.com/v2.0/group/send?id=AccountID&key=APIKey&srcaddr=SMSAlert&grpid=1234&data=48656C6C6f20576F726C64&dcs=2
Testing in a Browser? Use Method Overloading
To test in a browser, append &method=PUT to the call. This overloads the browser's default http GET and treats it as a PUT.
PUT must be in capitals, or it will fail.
https://sms.world-text.com/v2.0/group/send?id=AccountID&key=APIKey&srcaddr=SMSAlert&grpid=1234&txt=hello%20world&method=PUT
Responses
Success Example JSON
This will list a response for each destination number in a group
{
"status": "0",
"message": [
{
"state": "0",
"dstaddr": "447989123456",
"msgid": "31CD0DAB",
"credits": "0"
}
]
}
Failure Example JSON
{
"status":"1",
"error":"1000",
"desc":"Authorisation Failure"
}
For a full list of Possible Error Codes please see here.
Success Example XML
This will list a response for each destination number in a group
<result>
<message>
<msgid>31CD21F7</msgid>
<state>0</state>
<credits>0</credits>
<dstaddr>447989123456</dstaddr>
</message>
<status>0</status>
</result>
Failure Example XML
<result>
<status>1</status>
<error>1000</error>
<desc>Authorisation Failure</desc>
</result>
For a full list of Possible Error Codes please see here.
HTTP REST Interface With PHP Example to Group
// Basic function used to call World-Text.com this should be enhanced to
// do failover testing between the main servers for invoiced clients.
function sendGroup( $user, $pass, $grpid, $txt, $srcaddr = "SMSAlert" )
{
// Using host sms1 for this script, this will only work for all clients
$host = "sms1.world-text.com";
// Build the URL we are going to post our request to
$data = urlencode( $txt );
$srcaddr = urlencode( $srcaddr );
$url = "http://$host/sendgroup";
$body = "user=$user&pass=$pass&grpid=$grpid&txt=$data&srcaddr=$srcaddr";
// Initialise CURL
$ch = curl_init();
// set the target url
curl_setopt($ch, CURLOPT_URL,$url);
// tell curl we are posting this URL
curl_setopt($ch, CURLOPT_POST, 1);
// Add the arguments to the body of the call
curl_setopt($ch, CURLOPT_POSTFIELDS,"$body");
// Return the data rather than printing
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
// Make the call and grab the results
$result = curl_exec( $ch );
// All done so close up
curl_close( $ch );
return $result;
}
// User name that you use to log into World-Text.com
$user = "USERNAME";
// This is your password that you use to log onto the World-Text website
$pass = "SECRET";
// Call the sendSMS function with the required parameters
$result = sendGroup( $user, $pass, "$grpid", "Hello this is a PHP SMS Test from World-Text using the HTTP Interface", "SMSAlert" );
// Print the result out
echo $result;