Send SMS using XML
The XML API supports utf-8 encoded XML. Requests should be made using HTTP POST with a Content-Type of text/xml. For performance reasons the maximum request size is 500 messages.
https://api.clockworksms.com/xml/send.aspx
Request Parameters
| Parameter | Type | Default | Required |
|---|---|---|---|
| Key | String | Yes | |
| To | MSISDN | Yes | |
| From | MSISDN or Alphatag | User configurable | No |
| Content | String | Yes | |
| MsgType | String | TEXT | No |
| Concat | Integer | 1 | No |
| ClientID | String | No | |
| ExpiryTime | Integer (minutes) | No | |
| DlrType | Integer | User configurable | No |
| DlrUrl | String | User configurable | Sometimes |
| DlrContent | String | User configurable | Sometimes |
| AbsExpiry | DateTime | No | |
| UniqueId | Integer | User configurable | No |
| InvalidCharAction | Integer | User configurable | No |
| Truncate | Integer | User configurable | No |
Description of Request Parameters
Key
Your API key, available from your API account.
To
A phone number in international number format without a leading ‘+’ or international dialling prefix such as ‘00’, e.g. 441234567890.
From
A maximum of 11 characters or 12 digits, we recommend you only use letters and numbers as some handsets don’t correctly handle punctuation. If not specified, your account default will be used. If you’re sending with a text from address and your message isn’t delivered try again but change to sending from a telephone number - some international networks place restrictions on the from addresses they’ll accept. Due to US telecomunications rules you’re unable to set the from address when sending to the USA - the text will always come from 43704.
Content
The content of the message in UTF-8 encoded text. It must be passed as a hexadecimal encoded string when using the UDH MsgType. This parameter cannot be blank. For a single TEXT SMS this should be 160 GSM characters or less, this is equal to 140 bytes.
MsgType
Message type, the default is TEXT.
TEXT
Standard SMS message. Any character from the GSM character set can be used, all Characters should be submitted to the API encoded in UTF-8. A single SMS can contain 160 standard GSM characters, using concatenation a 2 part message can send 306 characters and 3 parts can send 459 characters. The extended GSM characters take up two characters of space within a message.
UCS2
Unicode SMS message. Any Unicode characters from the UCS-2 character set can be sent through the API; these should be submitted encoded in UTF-8. Refer to http://www.unicode.org/ for further information on Unicode and UCS-2. A single UCS-2 message can contain 70 characters, using concatenation 2 parts can contain 134 characters and 3 parts can contain 201 characters.
Concat
The maximum number of parts for concatenated messages. Defaults to 1 part, maximum 3. This parameter only affects TEXT message types. Each part is billed as an individual message. When set to 1 the platform will only allow 1 SMS to be sent. When set to 2, it allows either one or two SMS to be sent. When set to 3, the platform allows 1,2 or 3 SMS to be sent depending on the size of the content.
ClientID
A unique Message ID specified by the connecting application, for example your database record ID. Maximum length: 50 characters.
ExpiryTime
Number of minutes. It should be an integer, and corresponds to the number of minutes before the message expires. The minimum is 10 and the maximum is 10080 (7 days). Please note the set expiry time may not be honoured by some mobile networks.
DlrType
Delivery Receipt Type Valid values are:
| DlrType | Description | Content Type |
|---|---|---|
| 0 | No Delivery Receipt | |
| 1 | HTTP GET | |
| 2 | HTTP POST | application/x-www-form-urlencoded |
| 3 | HTTP POST | text/xml |
| 4 | Bulk XML | text/xml |
DlrUrl
The URL that delivery receipts should be forwarded to. This is required if DlrType is non-zero
DlrContent
The content to be sent to the delivery receipt url. This is required when DlrType is non-zero. Various parameters can be merged in to the content.
AbsExpiry
The Absolute Expiry time for the message. An absolute time should be specified in UTC (Coordinated Universal Time) in the following format yyyyMMddHHmm. For example 201710201530 represents 3:30pm on 20th October 2017 (UTC).
If both an absolute and relative expiry time are given the absolute expiry time will be used. If the supplied expiry time is in the wrong format or in the past an error will be returned by the SMS API. Please note the set expiry time may not be honoured by some mobile networks.
UniqueId
Possible Values:
| UniqueId | Description |
|---|---|
| 0 | Unique ID checks disabled |
| 1 | Unique ID checks Enabled |
If Unique ID checks are enabled, the ClientID specified by the connecting application must be unique within the last 12 hours. This is to prevent the connecting application from falsely sending duplicate messages to a phone.
InvalidCharAction
Possible Values:
| InvalidCharAction | Description |
|---|---|
| 1 | Return an error |
| 2 | Remove the invalid characters |
| 3 | Replace invalid characters where possible, remove the rest |
What to do with any invalid characters in the message content. If this parameter is not specified your account default will be used. The replace option will replace a small number of common invalid characters, such as the smart quotes used by Microsoft Office with a similar match.
Truncate
Possible Values:
| Truncate | Description |
|---|---|
| 0 | Return an error if content is too long |
| 1 | Remove the extra text |
When enabled, the API trims the message content to the maximum length if it’s too long. If this is not set your account default will be used. Truncate only works with standard text messages (MsgType=TEXT).
Response Parameters
| Parameter | Type |
|---|---|
| To | MSISDN |
| MessageID | String |
| ClientID | String |
| ErrNo | String |
| ErrDesc | String |
Description of Response Parameters
To
Phone number message was sent to
MessageID
Unique ID assigned to this message by Clockwork. Every successful message will have a message ID, you will need this ID to match up delivery receipts.
ClientID
Your Client ID, passed back for your reference only. This field is only supplied if the Client ID was specified in the request.
ErrNo
The API Error Code. This parameter will only be populated if an error occurred sending the message.
ErrDesc
A text description of the API error code.
Examples
Send Hello World to 441234567890
Request
1
2
3
4
5
6
7
8
<?xml version="1.0" encoding="UTF-8"?>
<Message>
<Key>key</Key>
<SMS>
<To>441234567890</To>
<Content>Hello World</Content>
</SMS>
</Message>
Response
1
2
3
4
5
6
7
<?xml version="1.0" encoding="utf-8"?>
<Message_Resp>
<SMS_Resp>
<To>441234567890</To>
<MessageID>AB_123456</MessageID>
</SMS_Resp>
</Message_Resp>
Send to multiple recipients
This send is to one valid and one invalid mobile number.
Request
1
2
3
4
5
6
7
8
9
10
11
12
<?xml version="1.0" encoding="UTF-8"?>
<Message>
<Key>key</Key>
<SMS>
<To>441234567890</To>
<Content>Hello World</Content>
</SMS>
<SMS>
<To>44123456abcd</To>
<Content>Hello World</Content>
</SMS>
</Message>
Response
1
2
3
4
5
6
7
8
9
10
11
12
<?xml version="1.0" encoding="utf-8"?>
<Message_Resp>
<SMS_Resp>
<To>441234567890</To>
<MessageID>AB_123456</MessageID>
</SMS_Resp>
<SMS_Resp>
<To>44123456abcd</To>
<ErrNo>10</ErrNo>
<ErrDesc>Invalid 'To' Parameter</ErrDesc>
</SMS_Resp>
</Message_Resp>
General Errors
If the entire request fails you get a single error message, this example has an invalid API key.
Request
1
2
3
4
5
6
7
8
9
10
11
12
<?xml version="1.0" encoding="UTF-8"?>
<Message>
<Key>key</Key>
<SMS>
<To>441234567890</To>
<Content>Hello World</Content>
</SMS>
<SMS>
<To>441234567891</To>
<Content>Hello World</Content>
</SMS>
</Message>
Response
1
2
3
4
5
<?xml version="1.0" encoding="utf-8"?>
<Message_Resp>
<ErrNo>58</ErrNo>
<ErrDesc>Invalid API Key</ErrDesc>
</Message_Resp>