HTTP API Specification V2.3.

0
17 April 2007
 HTTP API Specification v.2.3.0

1. Content

1. Content ......................................................................................................................................... 1
2. Change history.............................................................................................................................. 3
3. Overview....................................................................................................................................... 3
4. Introduction ................................................................................................................................... 3
5. Getting started .............................................................................................................................. 4
5.1 Step 1 - register for an account ................................................................................................. 4
5.2 Step 2 - add an API sub-product (registered API connection) .................................................... 4
6. Terminology .................................................................................................................................. 5
7. Basic commands........................................................................................................................... 6
7.1 Authentication and session ID’s................................................................................................. 6
7.2 Ping .......................................................................................................................................... 8
7.3 Send a message ....................................................................................................................... 8
7.4 Query a message...................................................................................................................... 9
8. Message parameters................................................................................................................... 10
8.1 Table of parameters................................................................................................................ 10
8.2 Message parameters in detail ................................................................................................. 12
8.2.1 Destination address (to).................................................................................................. 12
8.2.2 Source address (from) .................................................................................................... 12
8.2.3 Delivery acknowledgment (deliv_ack) ............................................................................. 13
8.2.4 Callback URL (callback).................................................................................................. 13
8.2.5 Delivery time (deliv_time)................................................................................................ 14
8.2.6 Concatenation (concat)................................................................................................... 15
8.2.7 Maximum credits (max_credits) ...................................................................................... 15
8.2.8 Required features (req_feat) ........................................................................................... 17
8.2.9 Delivery queue (queue)................................................................................................... 17
8.2.10 Gateway escalation (escalate) ........................................................................................ 19
8.2.11 Mobile originated (mo) .................................................................................................... 19
8.2.12 Client message ID (climsgid) .......................................................................................... 20
8.2.13 Unicode (unicode) .......................................................................................................... 20
8.2.14 Message type (msg_type)............................................................................................... 21
8.2.15 Validity period (validity)................................................................................................... 21
9. Additional commands.................................................................................................................. 22
9.1 Delete/stop message .............................................................................................................. 22
9.2 Query balance ........................................................................................................................ 22
9.3 Coverage Query ..................................................................................................................... 22
9.4 MMS push .............................................................................................................................. 23
9.5 WAP push service indication................................................................................................... 24
9.6 Get message charge query ..................................................................................................... 24
9.7 WAP push service indication................................................................................................... 25
9.8 Token (voucher) pay ............................................................................................................... 26
10. Batch messaging .................................................................................................................... 27
10.1 Start batch .......................................................................................................................... 27
10.2 Sending messages to existing batch ................................................................................... 27
10.3 Quick send to batch ............................................................................................................ 28
10.4 End batch ........................................................................................................................... 28
11. 8-BIT messaging..................................................................................................................... 29
11.1 Converters and builders...................................................................................................... 29

Copyright  2006 Clickatell 1

 HTTP API Specification v.2.3.0

12. Message examples ................................................................................................................. 29

12.1 Simple examples ................................................................................................................ 29
12.2 Batch SMS examples.......................................................................................................... 30
12.2.1 Sending a personalised messages to multiple recipients ................................................. 30
12.2.2 Sending two personalised messages .............................................................................. 30
12.2.3 Sending multiple SMS using batches .............................................................................. 30
12.3 8-bit SMS examples............................................................................................................ 30
12.3.1 Sending a ringtone ......................................................................................................... 30
12.3.2 Sending an operator logo................................................................................................ 31
12.3.3 Removing an operator logo............................................................................................. 31
12.3.4 Sending a VCARD.......................................................................................................... 31
12.3.5 Sending a VCAL............................................................................................................. 31
13. Appendix A: Error codes ......................................................................................................... 32
14. Appendix B: Message statuses ............................................................................................... 34
15. Contact details........................................................................................................................ 35

Copyright  2006 Clickatell 2

 HTTP API Specification v.2.3.0

2. Change history

Approximately six (6) months of changes are reflected.

Version Date Section Changes to Documentation

2.3 13/04/2007 All Revised document branding

3. Overview

This document is intended for those users who wish to develop applications that make use of our SMS
gateway.

It is recommended that you have an understanding of profiles before reading this document. Information
is available at http://support.clickatell.com/guides/clickatell/routing.php.

There are a number of different ways of gaining access to the gateway:

• SMTP - enabling a server or client generated email to be delivered as an SMS.

• HTTP / HTTPS - submitting either a POST or GET to the API server.
• FTP – uploading a text file to our FTP Server.
• XML – posting to our gateway using XML over HTTP.
• COM Object – for Windows based development.
• SMPP – customers requiring a high throughput binary socket connection.

We will cover the HTTP method in this document. Additional documentation is available for the other
methods. Sample code is provided on the site.

In order to reduce testing costs, Clickatell offers a test number range. Messages sent to any number on
this prefix will only be charged 1/3 of a credit. Use the number 279991xxxxx where “xxxxx” represents
any numeric string. Message statuses will be returned.

4. Introduction

This is one of the simpler server-based forms of communication to with our gateway. It can be used
either in the form of a HTTP POST, or as an URL (GET). We recommend POST for larger data transfer,
due to the size limitations of GET. Communication to our API can be done either via HTTP on port 80 or
HTTPS on port 443. All calls to the API must be URL-encoded. The parameter names are case-
sensitive. Batch messaging is catered for in a variety of ways.

Note: It is important that the ENTIRE document is read before contacting support. Parameters are
case-sensitive. All examples shown use HTTP GET.

Copyright  2006 Clickatell 3

 HTTP API Specification v.2.3.0

5. Getting started

In order to use the Clickatell gateway you need a Clickatell account and at least one registered
connection (API sub-product instance) between your application and our gateway. Each connection
method (SMTP, HTTP, FTP, XML, COM Object, SMPP), is known as a sub-product (of our API product).
Here’s how:

5.1 Step 1 - register for an account

If you do not already have a Clickatell account, you need to register for one as per below. Otherwise
proceed to Step 2.

• Go to http://www.clickatell.com/products/sms_gateway.php, and choose the appropriate API

sub-product (connection method) you wish to use.
• Click on the registration hyperlink.
• Fill out the registration form.

After successfully submitting the form you will automatically be logged into your new account and taken
to a page where you can add your chosen API sub-product.

5.2 Step 2 - add an API sub-product (registered API connection)

If you are not already logged into your account, then you must do so at
http://www.clickatell.com/login.php

• Select “Manage my products” from the top menu.

• Select the API connection type you wish from the drop down menu in the “My Connections”
page.
• Select “add sub-product” from the main page (it will default to this page if you have not yet
added a sub-product).
• Complete the form.

After successfully submitting the form, your authentication details will be displayed, including the sub-
product instant’s own unique API ID (api_id). These authentication details are required when connecting
to the Clickatell gateway to send a message.

Note: For more information on managing your API connections within your Clickatell account see our
API guide at http://support.clickatell.com/guides/clickatell/api_guide.php..

Copyright  2006 Clickatell 4

 HTTP API Specification v.2.3.0

6. Terminology

• Mobile originated (MO): A message sent (originating) from a mobile handset to an application
via Clickatell.
• Mobile terminated (MT): A message sent from an application to (terminating on) a mobile
handset via Clickatell.
• Premium rated message (MO): A mobile user is charged a premium for the message that they
send to a particular number.
• Premium rated message (MT): A mobile user is charged a premium for a message that they
receive from a particular number.
• Revenue share: This refers to the portion of the increased cost associated with a premium
rated message, which is passed on to the content provider.
• Content provider: This is the Clickatell client offering service(s) based on a premium rated
SMS system.
• Customer: A registered Clickatell customer utilising the Clickatell API for message delivery and
receipt.
• Sender ID: The “from” address that appears on the user’s handset. Also known as the
originating number, MSISDN or originator ID.
• Destination address: This is the number to which the mobile user sent the message.
• Source address: The number of the handset to which the message must be delivered.
• Shortcode: A short number which is common across all the operators for a specific region.
• Subscriber: The handset that will be paying for the premium rate MT service.
Upstream gateway: A network operator, third party or our own short message service centre (SMSC)

Copyright  2006 Clickatell 5

 HTTP API Specification v.2.3.0

7. Basic commands

In order to send a message, the system will firstly need to authenticate you as a valid user. The
preferred method of authentication is using the auth command. Whilst it involves an additional step, it is
far more secure in that you only have to pass login details once, to obtain a session ID. If you do not use
auth to obtain a session ID, you will have to pass your account details with every command.

All other commands are then made up of three segments: authentication, the basic message
components (message content and recipients) and the additional message parameters. In the examples
below, we will include the authentication and basic message components. The additional message
parameters will be included only where they are relevant.

Basic Command Structure:

URL Call Authentication Message Parameters

http://api.clickatell.com/http/sendmsg?session_id=xxxx&to=xxxx&text=xxxx
or
http://api.clickatell.com/http/sendmsg?api_id=xxxx&user=xxxx&password=xxxx&to=xxxx&text=xxxx

7.1 Authentication and session ID’s

In order to deliver a message, the system needs to authenticate the request as coming from a valid
source. We use a number of parameters to achieve this:

§ api_id: This is issued upon addition of an HTTP sub-product to your account. A single account
may have multiple API IDs associated with it.
§ user: This is the username of your account.
§ password: The current password you have set on your account.

Additionally we can force an IP lockdown, allowing only requests sent from IP addresses that you have
specified. This can be set under the API product preferences within your account. Please ensure that
after testing, you remove all unnecessary IP addresses in your preferences to tighten up on security.

You can have multiple sessions open, however the session ID will expire after fifteen minutes of
inactivity. You will then have to re-authenticate to receive a new session ID. Alternatively, you can ping
every 10 minutes or so to ensure that the current session ID is kept live.

Command:

Un-secure: http://api.clickatell.com/http/auth?api_id=xxxx&user=xxxx&password=xxxx
Secure: https://api.clickatell.com/http/auth?api_id=xxxx&user=xxxx&password=xxxx

Response:
OK: Session ID
or
ERR: Error number

Copyright  2006 Clickatell 6

 HTTP API Specification v.2.3.0

This session ID must be used with all future commands to the API, unless you authenticate each time
within the command itself.

Copyright  2006 Clickatell 7

 HTTP API Specification v.2.3.0

7.2 Ping
This command prevents the session ID from expiring in periods of inactivity. The session ID is set to
expire after 15 minutes of inactivity. You may have multiple concurrent sessions using the same session
ID.

Command:
http://api.clickatell.com/http/ping?session_id=xxx

Response:
OK:
or
ERR: Error number

7.3 Send a message

To facilitate sending an SMS with a single command, we have included the ability to post api_id, user
and password variables in sendmsg. This is only required if you do not authenticate yourself using the
authentication command (auth). Using a session ID is preferred to authenticating each time.

One can send to multiple destination addresses by delimiting the addresses with commas. The basic
parameters required are to (the handset number to which the message is being sent) and text (the
content of the message). A maximum of 100 comma separated destination addresses per sendmsg, or
quicksend command, are possible, if you are calling the command via a GET, or alternatively, 300
destination addresses if you are submitting via a POST.

In the examples displayed in this document we will only refer to these basic parameters. Other
parameters may be used to enable different features. These are discussed in the following section.

Each message returns a unique identifier in the form of an API message ID. This can be used to track
and monitor any given message. The API message ID (apiMsgid) is returned after each post.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxxx&to=xxxx&text=xxxx
or
http://api.clickatell.com/http/sendmsg?api_id=xxxx&user=xxxx&password=xxxx&to=xxxx&text=xxxx

Response Single Message:

ID: apimsgid
Response Multiple Messages:
ID: apimsgid To: xxxxxx
ID: apimsgid To: xxxxxx

Or

Response Single Message:

ERR: Error number
Response Multiple Messages:
ERR: Error number To: xxxxxx
ERR: Error number To: xxxxxx

Copyright  2006 Clickatell 8

 HTTP API Specification v.2.3.0

7.4 Query a message

This command returns the status of a message. You can query the status with either the apimsgid or
climsgid. The API Message ID (apimsgid) is the message ID returned by the Gateway when a
message has been successfully submitted. If you specified your own unique client message ID
(climsgid) on submission, you may query the message status using this value. You may also
authenticate with api_id, user and password.

See Appendix B for status codes.

Command:
http://api.clickatell.com/http/querymsg?session_id=xxx&apimsgid=XXXXX
or
http://api.clickatell.com/http/querymsg?user=xxxx&password=xxxx&api_id=xxxx& apimsgid=XXXXX

Response:
ID: xxxx Status: xxxx
or
ERR: Error number

Note: Clickatell can also post message status updates to your application via means of a Callback URL.
This is the recommended method to obtain message status updates as your application is not required
to continually poll the Clickatell gateway. Detailed information can be found in the “Callback URL”
section under “Message parameters”.

Message statuses reports can be viewed online within your Clickatell Central account. These reports can
also be exported in CSV or Excel format.

Copyright  2006 Clickatell 9

 HTTP API Specification v.2.3.0

8. Message parameters

8.1 Table of parameters

There are a variety of messaging and SMS features supported by the gateway, which can be activated
by including a number of additional parameters. These parameters include those in the table below.
Parameters are case-sensitive.

Parameter Default Restricted

Name Short description
name value values
API product ID api_id The value for this mandatory
parameter can be found or
created by logging in online and
going to Product Control.
Username user The username you specified.
Password password Your account password.
Session ID session_id The session ID from the auth
command. Not applicable to the
FTP or SMTP APIs.
Destination to The number of the handset to No ‘00’ prefix or
address which the message must be leading “+”
delivered. The number should be symbol should
in international number format. be used.
Text text The text content of the message.

Source address from The source/sender address that gateway A valid

the message will appear to come assigned international
from. number format number
between 1 and
16 characters
long, or an 11
character
alphanumeric
string.
Delivery deliv_ack Where possible, this will return a 0 0 – Upstream
acknowledgement delivery acknowledgement for any gateway
message, upon delivery of the 1 - Handset
message to the mobile handset or acknowledgeme
upstream gateway. Also see nt.
required features parameter.
Enable callback callback Enables you to receive message 0 0,1,2,3
delivery statuses via an HTTP Read detailed
callback which is posted to a URL description of
of yours using the GET method. parameter.
This is done every time a
message status is updated.

Copyright  2006 Clickatell 10

 HTTP API Specification v.2.3.0

Parameter Default Restricted

Name Short description
name value values
Delivery time deliv_time Delays delivery of SMS to mobile The upper limit is
device in minutes relative to the 7 days, or 10080
time at which the SMS was minutes.
received by our gateway. This
should be greater than 10 minutes
for best effect. Smaller time
frames may be delivered too
soon.
Concatenation concat Enables you to send messages 1 1,2,3
longer than a standard message.
Maximum credits max_credits Overrides the maximum charge As per 0.8,1,1.5,2,2.5,3
specified online in “profiles”. It profiles
works within the bounds of the
profiles. In other words a profile
must exist for the maximum credit
that you set.
Required features req_feat Some parameters and features Read detailed
are not set as “required” by description of
default, and may be dropped if the parameter.
least-cost route does not support
them. This parameter allows you
to ensure that the features set
when an SMS is sent are
supported by the gateway used.
This could increase the cost per
message if a more expensive
gateway is used.
Delivery queue queue Delivers the message through one 3 1, 2,3
of three queues assigned to each 1 is highest
client account. Messages in the priority.
highest priority queue will be
delivered first.
Gateway escalate Prompts an escalation to an 0 0 - off
escalation alternative delivery gateway, 1 - Escalate
should the message be delayed immediately to
for a set length of time. an alternative
route if
messages are
queued on the
least-cost route.
Mobile originated mo We route via a pre-defined carrier 0 0 – Off. We use
to enable the ability for a reply to our normal
be received back. This is only routing rules.
applicable to clients that have 1 – Enable
subscribed to a two-way Reply.
messaging service.
Client message ID cliMsgId Client message ID defined by user Up to 32
for message tracking. alphanumeric
characters. No

Copyright  2006 Clickatell 11

 HTTP API Specification v.2.3.0

Parameter Default Restricted

Name Short description
name value values
spaces.
Unicode message Unicode Two digit language code. Convert 0 0 – No Unicode
your text to Unicode [UCS-2 1 – Send as
encoding]. See Unicode.
http://www.Unicode.org/.

Message type msg_type Optional parameter which must be SMS_TE

set to send specially formatted XT
messages; e.g. logos and
ringtones.
User data header udh Allows you to set your own Set UDH data
message types. Do not use if you manually.
set the message type parameter.
Data data The data content of a message, if
the UDH component is set
manually.
Validity period See The validity period in minutes 1440 Set value in X
detailed relative to the time at which the minutes minutes from 1 –
information SMS was received by our (24 1440 minutes.
on message gateway. The message will not be hours)
parameter delivered if it is still queued on our
gateway after this time period.

8.2 Message parameters in detail

8.2.1 Destination address (to)

SMS messages need to be sent in the standard international format, with country code followed by
number. No leading zero to the number and no special characters such as "+" or spaces must be used.
For example, a number in the UK being 07901231234 should be changed to 447901231234.

If have you set the preferred dial prefix preference within your client account after logging in on-line, any
mobile numbers starting with zero will have the zero stripped and replaced with your default prefix. If the
mobile number does not have a zero, the default prefix will not be changed.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx

8.2.2 Source address (from)

The source address (from), also known as the sender ID, can be either a valid international format
number between 1 and 16 characters long, or an 11 character alphanumeric string. Note that characters
such as spaces, punctuation, Unicode and other special characters may not always be supported to all
destinations and could interfere with your delivery.

We suggest that you refrain from using such characters on the source address. If this is set, then
delivery acknowledgements may be unavailable. The use of an alphanumeric source address with 8-bit

Copyright  2006 Clickatell 12

 HTTP API Specification v.2.3.0

messaging may cause message failure. This service is not guaranteed across all mobile networks and
may interfere with delivery to certain handsets.
Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&from=xxxx

Note: To ensure that this feature is supported when delivering your message, the required features
(req_feat) parameter for this feature must be set.

8.2.3 Delivery acknowledgment (deliv_ack)

In order to determine whether an SMS has been received by a handset or not, we offer delivery
acknowledgement. The ability to receive reliable delivery acknowledgements varies between mobile
networks.

Values to set are:

Value Status
0 Off - default status, no delivery to handset reported. However
delivery to the upstream gateway will be reported.
1 Handset acknowledgment - handset has received SMS (delivery
acknowledgment).

To ensure that this feature is supported when delivering your message, the required features (req_feat)
parameter for this feature must be set. This ensures that an upstream gateway that supports this feature
is used to deliver the message. This gateway may be more expensive.

Handset acknowledgements are not guaranteed by all of our upstream gateways. Please test to a
specific mobile network first, before assuming that you will receive handset acknowledgments for
messages that are delivered.

GSM handsets that are off will only be reported once a user has switched their phone back on. If the
validity period is exceeded, the Clickatell gateway will return a message status of 7, “Error with
message”.

A delivery acknowledgment can be monitored via the callback URL or online reports.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&deliv_ack=1

8.2.4 Callback URL (callback)

Final or intermediary statuses are passed back by the API depending on the callback value set in the
original post. This is done by means of an HTTP GET. The callback URL is set in the preferences
section of the particular API product within your client account, after logging in online. The URL must
begin with either http:// (un-secure) or https:// (secure).

The variables returned are apiMsgId, cliMsgId, api_id, to, timestamp, from, status and charge.

Values to set with delivery acknowledgment (deliv_ack) set to 0 (no delivery to phone reported) are:

Copyright  2006 Clickatell 13

 HTTP API Specification v.2.3.0

Callback
Message status types returned Message status code returned
value
0 No message status returned.
1 Returns only intermediate statuses. 002, 011
2 Returns only final statuses of a message. 003, 005, 006, 007, 008, 009, 010, 012
3 Returns both intermediate and final statuses of a All except 001
message.

Values to set with delivery acknowledgment (deliv_ack) set to 1 (handset acknowledgment) are:

Callback
Message status types returned Message status code returned
value
0 No message status returned.
1 Returns only intermediate statuses. 002, 003, 011
2 Returns only final statuses of a message. 004, 005, 006, 007, 008, 009, 010, 012
3 Returns both intermediate and final statuses of a All except 001
message.

Sample callback to your callback URL:

http://www.yoururl.com/script.asp?api_id=12345&apiMsgId=96905854f5045354a1b36134acf81&cliMsgI
d=123456&status=003&timestamp=1055155528&to=2782123456&from=Sender&charge=2.5

Delivery acknowledgment (deliv_ack) and callback explained:

Example 1:

With deliv_ack=1 (acknowledgment of delivery to handset), you will receive a callback of messages
reaching the SMSC (003), if you requested intermediate statuses, and a callback of messages reaching
handsets (004), if you requested final statuses.

Example 2:

With deliv_ack = 0 (default), you will only receive a callback of messages reaching the SMSC (003), if
you have set callback = 2.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&callback=3
or secure
https://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&callback=3

8.2.5 Delivery time (deliv_time)

The delivery of a SMS message may be delayed by setting an amount of time in minutes relative to the
time at which it was received by our gateway. We will store the message until the required time frame
has elapsed. The maximum delay time is 10080 minutes or 7 days.

Copyright  2006 Clickatell 14

 HTTP API Specification v.2.3.0

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&deliv_time=120

Response:
ID: xxxxx
or
ERR: Error Number

When sending batches of messages, the delivery time should be set in the startbatch command. This
will ensure that all messages are delivered X minutes after being posted to the Gateway.

8.2.6 Concatenation (concat)

If this value is set to 1, 2 or 3 the message will span across 1, 2 or 3 SMS messages where applicable.
One text SMS will be sent for every 160 characters or 140 bytes. If a message is concatenated, it
reduces the number of characters contained in each message by 7. With 8-bit concatenated messages,
each SMS can support up to 160 bytes including the UDH headers.

Please be aware that a single Unicode SMS can only contain a maximum of 70 characters. 8-Bit
messages will be split over multiple messages, where necessary, irrespective of whether the flag for
concatenated messages has been set. If a Unicode message is concatenated, it reduces the number of
characters contained in each message part by 3.

Values set are:

Value Status
1 Default - No concatenation: only 1 message.
2 Concatenate a maximum of 2 messages.
3 Concatenate a maximum of 3 messages.
N Concatenate a maximum of N messages.
(Delivery is dependant on mobile and gateway. A maximum of 3 is
recommended).

Command: http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&concat=2

8.2.7 Maximum credits (max_credits)

This parameter overrides the maximum charge associated with message delivery, as set by the profiles
selected within your client account after logging in online. This parameter can be used to limit the cost of
a message to a particular value and is bound by the maximum credit value specified in your profiles.

A valid API message ID can still be returned for messages that are not delivered as a result of the
maximum credits value set. These messages will have a status of routing error (009).

The credit value in this parameter can be set to any amount of credits. The current maximum charge is 3
credits. Please see http://www.clickatell.com/pricing/basic_coverage.php to view relative destination
costs.

To set your delivery profile, go to “AccountàRouting Profiles” from within your online account.

Copyright  2006 Clickatell 15

 HTTP API Specification v.2.3.0

Copyright  2006 Clickatell 16

 HTTP API Specification v.2.3.0

8.2.8 Required features (req_feat)

This parameter specifies the features that must be present in order for message delivery to occur. If all
features are not present, the message will not be delivered. This prevents SMS messages arriving at a
destination via the least-cost gateway, without certain features. This would, for instance, prevent the
dropping of an alphanumeric sender ID.

This means is that we will not route messages through a gateway that cannot support the required
features you have set. For certain message types, we always set the required feature bitmask where
relevant. These are FEAT_8BIT, FEAT_UDH, FEAT_UCS2 and FEAT_CONCAT.

This parameter is set using a combined decimal number to refer to the additional required features.

E.g.: 32 + 512 = 544 – Numeric sender ID and Flash SMS both required.
The value you would set to ensure that Flash and numeric sender ID are both supported, would
therefore be 544.
To ensure that delivery acknowledgment and alphanumeric IDs are supported you would use the value
8240 (16 + 32 + 8192).

Hex value Decimal Feature Description

0x0001 1 FEAT_TEXT Text – set by default.
0x0002 2 FEAT_8BIT 8-bit messaging – set by default.
0x0004 4 FEAT_UDH UDH (Binary) - set by default.
0x0008 8 FEAT_UCS2 UCS2 / Unicode – set by default.
0x0010 16 FEAT_ALPHA Alpha source address (from parameter).
0x0020 32 FEAT_NUMER Numeric source address (from parameter).
0x0200 512 FEAT_FLASH Flash messaging.
0x2000 8192 FEAT_DELIVACK Delivery acknowledgments.
0x4000 16384 FEAT_CONCAT Concatenation – set by default.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&req_feat=####

8.2.9 Delivery queue (queue)

Setting this parameter will assign the message to one of three queues assigned to each user account.
This sets the priority of a message sent to us, relative to other messages sent from the same user
account. Messages in queue number 1, will always be delivered before messages in queue number 2
and 3, while messages in the 3rd queue, will have the lowest priority (relative to queues 1 and 2).

This is useful when delivering, for example, a single high priority message while you have a large batch
going through that same account. The large batch will be queued through queue number 3 (default), and
urgent alerts (sent through queue 1), will be delivered ahead of those messages in the batch (queue 3),
regardless of when they are actually sent to us.

Values set are:

Copyright  2006 Clickatell 17

 HTTP API Specification v.2.3.0

Value Status
1 Use first / primary user queue (highest priority).
2 Use second user queue.
3 Use third user queue (lowest priority) - Default status.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&queue=2

Copyright  2006 Clickatell 18

 HTTP API Specification v.2.3.0

8.2.10 Gateway escalation (escalate)

By default, the message router will select the lowest cost route (matching features and reliability) that is
available for a given destination.

This parameter ensures that, should a message be delayed due to gateway congestion or some other
reason on the initial gateway selected by our router, then alternative routes that match the required
features will be sought. This is done by moving through the available gateways in order of increasing
cost, up to the maximum charge set by the user either using the parameter that defines the maximum
credits or based on the profiles selected.

When urgent and high priority messages are sent, they should be posted with escalate set to 1 (on),
combined with a high maximum credit value to ensure that the greatest number of gateways are
available.

Values set are:

Value Status
0 Off – Default value.
1 On - If the least-cost route has messages queued then escalate
immediately to an alternative route.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&escalate=1

8.2.11 Mobile originated (mo)

This parameter is only used when a message is sent to a handset and a reply is expected.

PLEASE NOTE: This parameter is only valid for clients that have signed up and paid for our two-
way messaging service. An alternative to our least-cost gateway may be used, which could result
in a higher cost per message. Please email Clickatell support for pricing or view online.

When sending a normal MT message to a handset and you expect a reply to your registered MO
number, please set the mo parameter to “1”.

Values to set are:

Value Status
0 Off - Default status. Clickatell uses the normal routing feature.
1 Enables reply ability. Clickatell routes via a pre-defined carrier to enable the
ability to reply.

It is important that the user specifies the correct from parameter together with this parameter. If no from
parameter is specified, we will use a default originator number as set by Clickatell. You will NOT receive
these replies.

Copyright  2006 Clickatell 19

 HTTP API Specification v.2.3.0

If you specify the originator (the purchased mo number), then we will route the message such that it can
be replied to by the recipient. This reply will be sent to you.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&mo=#

8.2.12 Client message ID (climsgid)

This parameter is set by the user to enable internal message tracking. It allows the user to set their own
tracking ID for each message. Once set for a given message, this may be used in place of the Clickatell
issued API message ID (apimsgid) for querying message.

A client message ID (climsgid) may be any combination of alphanumeric characters excluding spaces. A
maximum of 32 characters may be used.

Client message IDs may be used with the querymsg command.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&climsgid=xxxx

8.2.13 Unicode (unicode)

If this value is set to 1, the text field must contain two-byte UTF-16 Unicode. Each SMS can handle a
maximum of 70 characters. Each Unicode character must be hex-encoded. More information is available
at http://www.Unicode.org/.

Note: When using the batch send facility for delivering Unicode messages, it is not possible to substitute
variables into the message content. This is only possible with Germanic characters.

Values set are:

Value Status
0 Off - default status.
1 On - delivers the text as two-byte Unicode.

We provide a converter to convert text to Unicode within your client account online. Go to “Converters”
from within your account online.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&unicode=1
Eg.: ΩΨΘ becomes: ….&text=03A903A80398&unicode=1

Copyright  2006 Clickatell 20

 HTTP API Specification v.2.3.0

8.2.14 Message type (msg_type)

A wide variety of messages can be sent through our gateway. We have pre-defined a number of SMS
message-types in the API, so that you do not have to set the UDH (user data header) manually. You
may optionally set the UDH rather than using one of the message types set below. Message types are
case sensitive.

For non-Nokia message types (EMS, etc.), please generate your own UDH and data according to the
manufacturers specifications of the message type you wish to send.

This parameter need not be included if the SMS is a standard text message.

Values set are:

Value Description
SMS_TEXT This is the default message type. It is optional to specify this
parameter.
SMS_FLASH To send an SMS that displays immediately upon arrival at the
phone.
SMS_NOKIA_OLOGO Send an operator logo to a Nokia handset.
SMS_NOKIA_GLOGO Send a group logo to a Nokia handset.
SMS_NOKIA_PICTURE Send a picture message to certain Nokia handsets.
SMS_NOKIA_RINGTONE Send a ringtone to a Nokia handset.
SMS_NOKIA_RTTL Send an RTTTL format ringtone to Nokia handsets.
SMS_NOKIA_CLEAN Remove operator logo from a Nokia handset.
SMS_NOKIA_VCARD Send a business card to a Nokia handset.
SMS_NOKIA_VCAL Send an event calendar to a Nokia handset.

Command:
Please see the messaging examples at the end of this document.

8.2.15 Validity period (validity)

A message may be given a time frame for which it is valid. After this period the message will expire. This
parameter takes an amount of time in minutes relative to the time at it which it was received by our
gateway. If the message is queued on our gateway for a period exceeding the validity period set then a
routing error of 115 will be returned. The default validity period is 1440 minutes (24 hours).

Note: The validity period is not passed on to the upstream gateway.

Command:
http://api.clickatell.com/http/sendmsg?session_id=xxx&to=xxxx&text=xxxx&validity=120

Copyright  2006 Clickatell 21

 HTTP API Specification v.2.3.0

9. Additional commands

9.1 Delete/stop message

This enables you to stop the delivery of a particular message. This command can only stop messages
which maybe queued within our router, and not messages which have already been delivered to a
SMSC. This command is therefore only really useful for messages with deferred delivery times.

Command:
http://api.clickatell.com/http/delmsg?session_id=xxx&apimsgid=XXXXX
or
http://api.clickatell.com/http/delmsg?session_id=xxx&climsgid=XXXXX

Response:
ID: xxxx Status: xxxx
or
ERR: Error number

9.2 Query balance

This will return the number of credits available on this particular account. The account balance is
returned as a floating point value.

Command:
http://api.clickatell.com/http/getbalance?session_id=xxx

Response:
Credit: xxxx.x
or
ERR: Error number

9.3 Coverage Query

This command enables users to check our coverage of a network or number, without sending a
message to that number. Authentication is required for this API call. This call should NOT be used
before sending each message.

Command:
http://api.clickatell.com/utils/routeCoverage.php?session_id=xxxx&msisdn=xxxx
or
http://api.clickatell.com/utils/routeCoverage.php?api_id=xxx&user=xxx&password=xxxx&msisdn=xxxx

Where msisdn is the number you wish to route to.

Response:
OK: This prefix is currently supported. Messages sent to this prefix will be routed. Charge: 1
or

Copyright  2006 Clickatell 22

 HTTP API Specification v.2.3.0

ERR: This prefix is not currently supported. Messages sent to this prefix will fail. Please contact support
for assistance.

9.4 MMS push

When an MMS message is sent to a phone, the mobile device receives an MMS notification message
via SMS. When this MMS notification message is received by the mobile device, the mobile device
automatically initiates a WAP gateway connection to download the content of the MMS message, from a
URL specified in the SMS notification message. This command enables users to send an MMS
notification message. Authentication is required for this API call.

MMS documentation (WAP-209-MMSEncapsulation-20020105-a.pdf, Version 05-Jan-2002) can be

found at http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html.

Default
Parameter Description Example Restricted value Required
value
mms_subject Subject My+message yes
mms_class Class 80 80 (Personal) yes
81 (Advertisement)
82 (Informational)
83 (Auto)
mms_expire How long before the 3000 Time in seconds yes
MMS expires
mms_from From text John yes
mms_url URL with the MMS http://www.mywebsite.co yes
content. The URL m/example.mms
must be URL
encoded.
Command:
http://api.clickatell.com/mms/ind_push.php?user=xxxx&api_id=xxxx&password=xxxx&to=xxxx&from=xxx
x&mms_subject=xxxx&mms_class=xx&mms_expire=xxxx&mms_from=xxxx&mms_url=http://xxxx.xx/xx.
mms

Response:
ID: xxxx To: xxxx
or
ERR: Error number

Copyright  2006 Clickatell 23

 HTTP API Specification v.2.3.0

9.5 WAP push service indication

WAP Push Service Indication (SI) is a WAP address embedded within the header of a specially
formatted SMS. This is displayed as an alert message to the user, and gives the user the option of
connecting directly to a particular URL via the handsets WAP browser (if supported). This command
enables you send a WAP Push Service Indication.

WAP documentation (WAP-167-ServiceInd-20010731-a.pdf, Version 31-July-2001) can be found at

http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html.

Parameter Description Example Default value Restricted Required

values
si_id Unique ID for each message No
si_url The URL that is used to access http://www.65mydom Yes
the service or content. The URL ain?picture=6566
must be URL encoded.
si_text Notification text. Provides a Here is your picture. No
means to specify additional
information.
si_created A date in UTC (Coordinated 2006-01- No
Universal Time) format. Used to 01T19:30:41Z
specify the date and time
associated with the creation or
last modification of the content
indicated by the URL, which
may differ from the date and
time when the SI was created.
si_expires Expiry date in UTC format. This 2006-12- No
allows you to specify a time 12T19:30:40Z
after which the SI will
automatically be deleted from
the handset. If not specified it
will never expire.
si_action A string specifying the action to signal-none, No
be taken when the SI is signal-low,
received. signal-
medium,
signal-high,
delete.

Command:
http://api.clickatell.com/mms/si_push?api_id=xxxx&user=xxxx&password=xxxx&to=xxxx&si_id=xxxx&si_
url=xxxx&si_created=xxxx&si_expires=xxxx&si_action=xxxx&si_text=xxxx

Response:
ID: xxxx To: xxxx
or
ERR: Error number

9.6 Get message charge query

Copyright  2006 Clickatell 24

 HTTP API Specification v.2.3.0

This command enables the user to query both the status and charge of a delivered message in a single
API call. Authentication is required for this API call. Clickatell can also post the message charge to your
application via means of a Callback URL (this is the preferred method). Detailed information can be
found in the “Callback URL” section under “Message parameters”.

9.7 WAP push service indication

WAP Push Service Indication (SI) is a WAP address embedded within the header of a specially
formatted SMS. This is displayed as an alert message to the user, and gives the user the option of
connecting directly to a particular URL via the handsets WAP browser (if supported). This command
enables you send a WAP Push Service Indication.

WAP documentation (WAP-167-ServiceInd-20010731-a.pdf, Version 31-July-2001) can be found at

http://www.openmobilealliance.org/tech/affiliates/wap/wapindex.html.

Default Restricted
Parameter Description Example Required
value values
si_id Unique ID for each No
message
si_url The URL that is used to http://www.65mydomain? Yes
access the service or picture=6566
content. The URL must
be URL encoded.
si_text Notification text. Here is your picture. No
Provides a means to
specify additional
information.
si_created A date in UTC 2006-01-01T19:30:41Z No
(Coordinated Universal
Time) format. Used to
specify the date and
time associated with the
creation or last
modification of the
content indicated by the
URL, which may differ
from the date and time
when the SI was
created.
si_expires Expiry date in UTC 2006-12-12T19:30:40Z No
format. This allows you
to specify a time after
which the SI will
automatically be
deleted from the
handset. If not specified
it will never expire.
si_action A string specifying the signal-none, No
action to be taken when signal-low,
the SI is received. signal-
medium,

Copyright  2006 Clickatell 25

 HTTP API Specification v.2.3.0

signal-high,
delete.
Command:
http://api.clickatell.com/http/getmsgcharge?session_id=xxxx&apimsgid=xxxxx
or
http://api.clickatell.com/http/getmsgcharge?api_id=xxxx&user=xxxx&password=xxxx&apimsgid=xxxxx

Response:
apiMsgId: xxxx charge: xxx status: xxx
or
ERR: Error number

9.8 Token (voucher) pay

This command allows you to spend a voucher that has been generated, within your client account, after
logging in online. This is very useful for topping up sub-users accounts with credits. You would generate
a session ID for the sub-user account, into which you wish to add the credits. You may also use the
standard login details. The voucher number is currently a 16 digit numeric value.

Command:
http://api.clickatell.com/http/token_pay?session_id=xxx&token=xxxxxxxxxxxxxxxxxxxx
or
http://api.clickatell.com/http/token_pay?api_id=xxx&user=xxx&password=xxxx&token=xxxxx

Response:
OK: 605 - If the payment was successful
or
ERR: 606, Invalid Voucher
ERR: 607, Expired Voucher

Copyright  2006 Clickatell 26

 HTTP API Specification v.2.3.0

10. Batch messaging

This facility enables one to do high volume delivery and server-side message merging. It offers the end-
user the ability to define all elements common to a batch, and then send only the parameters that
change on a message by message basis.

One initially defines a batch using the startbatch command, which will return a unique batch ID. You then
use either senditem or quicksend with the batch ID, depending on whether the message needs to be
personalised. See SMS examples below.

Hi #field1#, your doctor’s appointment is at #field2# tomorrow, could become:

Hi Fred, your doctor’s appointment is at 10:30 tomorrow.
Hi Jane, your doctor’s appointment is at 14:00 tomorrow.

10.1 Start batch

Once you have issued this command, you will be returned a batch ID that is to be used when sending
multiple batch items. Included functionality also allows for message merging where you can substitute
fields that you have defined in your template. The field names are called field1 though to fieldN.

This command can take all the parameters of sendmsg, with the addition of a template, and the
exception of both the destination address and the text fields. The template parameter must be URL
encoded. It must be used before either the senditem or quicksend command.

Command:
http://api.clickatell.com/http_batch/startbatch?session_id=xxx&...............&template=Hi #field1#, your
balance is #field2#.&from=Sender&deliv_ack=1

Response:
ID: batch id
or
ERR: Error number

10.2 Sending messages to existing batch

Note: The fields 1-N that you defined in the startbatch command are used to optionally personalise the
message.

Command:
http://api.clickatell.com/http_batch/senditem?session_id=xxx&batch_id=xxx&to=123456789&field1=Joe&
field2=$150........

Response:
ID: apimsgid
or
ERR: Error number

Copyright  2006 Clickatell 27

 HTTP API Specification v.2.3.0

10.3 Quick send to batch

Where one has the requirement to send the same message to multiple recipients, you can use the
quicksend command. This command offers low overhead and maximum throughput. It is essentially a
reference to a predefined template and a string of destination addresses.

Command:
http://api.clickatell.com/http_batch/quicksend?session_id=xxx&batch_id=xxx&to=123456789,234567890
,345678901,etc

Response:
ID: apimsgid To: xxxxx

or
ERR: Error number To: xxxxxx

Note: A response is returned for each destination address on a new line. The newline character (\n) is
used to create the line break.

10.4 End batch

This command ends a batch and is not required (following a batch send). Batches will expire
automatically after 24 hours.

Command:
http://api.clickatell.com/http_batch/endbatch?session_id=xxx&batch_id=xxx

Response:
OK
or
ERR: Error number

Copyright  2006 Clickatell 28

 HTTP API Specification v.2.3.0

11. 8-BIT messaging

Through the HTTP interface, one is also able to send 8-bit messages. These are most often used for
ringtones and logos, but one can also send vCards, vCalendar appointments and EMS messages. When
sending 8-bit messages, you need to set the user data header (UDH) of the SMS as well as sending the
data. To simplify the process, we have provided a number of pre-defined message types.

If you are comfortable with the creation of your own UDH, we also enable you to set it directly using the
udh parameter.

11.1 Converters and builders

To facilitate easy creation of ringtone, logo and vCard PDUs (protocol description units) for delivery via
SMS, we offer various converters for your use. These are only available from within your client account
after logging in online and not from us directly. The ringtones must be in midi format or RTTL (if you use
the RTTL converter), and the logos must be a 1-bit BMP. The PDU that they generate must be included
as the text variable. More documentation on Nokia Smart Messaging can be found on the Nokia
developer forum - http://forum.nokia.com/. We currently provide converters for Nokia phones only.
Please contact other phone manufacturers directly for their binary messaging formats. You can send
these formats using the udh and text parameters.

The vCard builder enables you to build a valid vCard PDU. Please remember that the more information
you include in the vCard, the more SMS it will concatenate over to send the vCard.

Notes:
• If a ringtone or logo is concatenated over multiple SMSs, you will be charged accordingly.
This is irrespective of the concat parameter value.
• The ringtone name field is compulsory in the converter. Failing to set this will result in a
silent ringtone.
• If you convert an RTTTL to a hex string using the online converter, then you must use the
msg_type SMS_NOKIA_RINGTONE and not SMS_NOKIA_RTTL.

12. Message examples

Here are some example URLs that demonstrate how to use the API. All values in these examples should
be replaced by your own values.

12.1 Simple examples

sendmsg command including authentication and Sender ID:
http://api.clickatell.com/http/sendmsg?api_id=1&user=demo&password=demo&to=1234567890123&text
=initial+test+message&from=ME

Initial authentication:
http://api.clickatell.com/http/auth?api_id=1&user=demo&password=demo

All further commands will use a session ID generated using auth command above:

Copyright  2006 Clickatell 29

 HTTP API Specification v.2.3.0

sendmsg command:
http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&from=ME&text=initial+test+message

Flash SMS:
http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&from=ME&msg_type=SMS_FLASH&text=flash+test+message

sendmsg with delivery acknowledgment and callback request:

http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&from=ME&callback=3&deliv_ack=1&text=callback+and+deliveryack

Account balance:
http://api.clickatell.com/http/getbalance?session_id=e74dee1bbed22ee3a39f9aeab606ccf9

Query message status:

http://api.clickatell.com/http/querymsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&apimsgid=48
89e40291643afeb5a7c4cce7811abb

Monitoring the connection:

http://api.clickatell.com/http/ping?session_id=e74dee1bbed22ee3a39f9aeab606ccf9

12.2 Batch SMS examples

12.2.1 Sending a personalised messages to multiple recipients

http://api.clickatell.com/http_batch/startbatch?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&templ
ate=Hi+%23field1%23+this+is+a+personalised+message

12.2.2 Sending two personalised messages

http://api.clickatell.com/http_batch/senditem?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&batch_i
d=f677d2fbb858a79aad0556dc71dd4383&to=1234567890&field1=David
http://api.clickatell.com/http_batch/senditem?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&batch_i
d=f677d2fbb858a79aad0556dc71dd4383&to=2345678901&field1=John

12.2.3 Sending multiple SMS using batches

http://api.clickatell.com/http_batch/quicksend?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&batch
_id=f677d2fbb858a79aad0556dc71dd4383&to=1234567890,2345678901,3456789012,4567890123,567
8901234

12.3 8-bit SMS examples

Note: You cannot set an alphanumeric Sender ID (from parameter) when sending 8-bit messages.

12.3.1 Sending a ringtone

Sending a ringtone using the msg_type parameter:

http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&msg_type=SMS_NOKIA_RINGTONE&text=024A3A5585E195B198040042D9049741A69761781B6
176156174288B525D85E0A26C24C49A617628930BB125E055856049865885D200

Copyright  2006 Clickatell 30

 HTTP API Specification v.2.3.0

Sending same ringtone with the udh parameter:

http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&udh=06050415810000&data=024A3A5585E195B198040042D9049741A69761781B617615617428
8B525D85E0A26C24C49A617628930BB125E055856049865885D200

12.3.2 Sending an operator logo

http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&msg_type=SMS_NOKIA_OLOGO&text=00480e010FC0000000000000003FF000000000000000
70380F9B006000001B601818DB006000C01BCF0C3058006000C01BDF8C301B3E66F9EF9BDF8C30
1B626C8CD8DBDF8C301B60787CDFDBCF0C305B6078CCD81B601818DB626C8CD8DB70380F9B3
E66FCEF9B3FF0000000000000000FC000000000000000000000000000000000

12.3.3 Removing an operator logo

http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&msg_type=SMS_NOKIA_CLEAN&text=00

12.3.4 Sending a VCARD

http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&msg_type=SMS_NOKIA_VCARD&text=BEGIN%3AVCARD%0D%0AVERSION%3A2.1%0D%0AN
%3ABloggs%3BJoe%0D%0ATEL%3BPREF%3A%2B1234567890%0D%0AEND%3AVCARD%0D%0A

12.3.5 Sending a VCAL

http://api.clickatell.com/http/sendmsg?session_id=e74dee1bbed22ee3a39f9aeab606ccf9&to=12345678
90&msg_type=SMS_NOKIA_VCAL&text=BEGIN%3AVCALENDAR%0D%0AVERSION%3A1.0%0D%0
ABEGIN%3AVTODO%0D%0ACATEGORIES%3AMISCELLANEOUS%0D%0ASUMMARY%3AMeet+bu
yers+at+Mario’s%0D%0ADTSTART%3A20030301T133000%0D%0AEND%3AVTODO%0D%0AEND%
3AVCALENDAR%0D%0A

Copyright  2006 Clickatell 31

 HTTP API Specification v.2.3.0

13. Appendix A: Error codes

The following list of error messages are generated by our gateway. There will be no message charge if
these errors are generated when sending a message.

Number Description Detail

001 Authentication failed

002 Unknown username or

password
003 Session ID expired

004 Account frozen

005 Missing session ID

007 IP Lockdown violation You have locked down the API instance to a specific IP
address and then sent from an IP address different to the one
you set.
101 Invalid or missing parameters

102 Invalid user data header

103 Unknown API message ID

104 Unknown client message ID

105 Invalid destination address

106 Invalid source address

107 Empty message

108 Invalid or missing API ID

109 Missing message ID This can be either a client message ID or API message ID. For
example when using the del_msg command.
110 Error with email message

111 Invalid protocol

112 Invalid message type

113 Maximum message parts The text message component of the message is greater than
exceeded the permitted 160 characters (70 Unicode characters). Select
concat equal to 1,2,3-N to overcome this by splitting the
message across multiple messages.
114 Cannot route message This implies that the gateway is not currently routing messages
to this network prefix. Please email [email protected] with

Copyright  2006 Clickatell 32

 HTTP API Specification v.2.3.0

the mobile number in question.

115 Message expired

116 Invalid Unicode data

120 Invalid delivery time

201 Invalid batch ID

202 No batch template

301 No credit left

302 Max allowed credit

Copyright  2006 Clickatell 33

 HTTP API Specification v.2.3.0

14. Appendix B: Message statuses

Number Hex Description Detail

001 0x001 Message unknown The message ID is incorrect or reporting is
delayed.
002 0x002 Message queued The message could not be delivered and has
been queued for attempted redelivery.
003 0x003 Delivered to gateway Delivered to the upstream gateway or network
(delivered to the recipient).
004 0x004 Received by recipient Confirmation of receipt on the handset of the
recipient.
005 0x005 Error with message There was an error with the message, probably
caused by the content of the message itself.
006 0x006 User cancelled message The message was terminated by an internal
delivery mechanism.
007 0x007 Error delivering message An error occurred delivering the message to the
handset.
008 0x008 OK Message received by gateway.

009 0x009 Routing error The routing gateway or network has had an error
routing the message.
010 0x00A Message expired Message has expired before we were able to
deliver it to the upstream gateway. No charge
applies.
011 0x00B Message queued for later Message has been queued at the gateway for
delivery delivery at a later time (delayed delivery).
012 0x00C Out of credit The message cannot be delivered due to a lack of
funds in your account. Please re-purchase credits.

Number Hex Description Detail

001 0x001 Message unknown The message ID is incorrect or reporting is
delayed.
002 0x002 Message queued The message could not be delivered and has
been queued for attempted redelivery.
003 0x003 Delivered to gateway Delivered to the upstream gateway or
network (delivered to the recipient).
004 0x004 Received by recipient Confirmation of receipt on the handset of the
recipient.
005 0x005 Error with message There was an error with the message,
probably caused by the content of the

Copyright  2006 Clickatell 34

 HTTP API Specification v.2.3.0

message itself.

006 0x006 User cancelled message The message was terminated by an internal
delivery mechanism.
007 0x007 Error delivering message An error occurred delivering the message to
the handset.
008 0x008 OK Message received by gateway.

009 0x009 Routing error The routing gateway or network has had an
error routing the message.
010 0x00A Message expired Message has expired before we were able to
deliver it to the upstream gateway. No charge
applies.
011 0x00B Message queued for later Message has been queued at the gateway for
delivery delivery at a later time (delayed delivery).
012 0x00C Out of credit The message cannot be delivered due to a
lack of funds in your account. Please re-
purchase credits.

15. Contact details

Phone: +27 21 910 7700

Fax: +27 21 910 7701
Website: www.clickatell.com
Help URL: http://support.clickatell.com/index.php
Support: [email protected]
Sales: [email protected]

--- 0 ---

Copyright  2006 Clickatell 35