HTTP API: Send message

SMS messages are sent by making HTTPS calls to the API.
This command allows you to send one or more SMS messages making HTTPS calls directly to the API. To send multiple messages to your database of mobile numbers, you can call this command in a loop.
Getting started is quick and easy – all you need to do is copy and paste the URL directly in your web browser to send a message!
The server will respond with a unique identifier for each message (referred to as an API message ID). This API Message ID can be used to track and monitor the status of your message.
For high volume messaging, we encourage the use of persistent HTTPS connections (keep-alive). Multiple concurrent HTTPS connections may also be used for additional performance.

Some basic facts about this API

  • You can send a message to a single handset in one single HTTPS request.
  • You can specify a message status call back method and destination in your integration configuration.
  • Allow two-way messaging with the ability to set message the reply call back method and destination in your integration configuration.
  • Supports sending of UTF8 character set messages.

Send your first message

  1. The first thing you’ll need is your HTTP API key generated when you configured the integration settings. This key is the authentication token used to call and unlock your specific integration service.
  2. Format the mobile number that you want to send to in international format.
    - The mobile number needs to start with the country code.
    - It must contain no spaces or other non-numeric characters.
    - If the mobile number starts with zero, remove the zero before typing the rest of the number.
  3. Decide on the SMS message text that you want to send.
  4. Next, add the details into the example that is generated in the code library of your integration.

Command

You can copy and paste the URL below into your web browser. Simply add your API key, mobile number, and text placeholders.

https://platform.clickatell.com/messages/http/send?apiKey=xxxxxxxxxxxxxxxx==&to=xxxxxxxxxxx&content=Test+message+text

Note – If you set Accept header to "application/json" you will get response as JSON.

Security

For additional security:

  • We support only HTTPS for all HTTP API requests.
  • You can enable IP lock down on your API connection. This is configured in the specific integration settings.

Authenticating 

Authenticate your requests using the unique API key generated when you save your integration configuration. You may refresh this key as desired from the integration settings window in the Platform portal.

See below URL example:

https://platform.clickatell.com/messages/http/send?apiKey=xxxxxxxxxxxxxxxx==&to=xxxxxxxxxxx&content=Test+message+text&from=xxxxxxxxxxx

Copy this string and paste it into the URL address bar of your browser to send a message.  Simply add your API key, mobile numbers, and text placeholders.

  1. You should see the response in your browser with an API Message ID.

Here's an example of an API Message ID: f7012c1edff2509a19ce1667c7f52b18 (this is a message tracking ID from the API integration which you can use later).

2. If you receive an error such as Invalid or missing Integration API Key, you may need to double check the parameters that were specified in the URL.

Code samples

Javascript:

var xhr = new XMLHttpRequest(https://platform.clickatell.com/messages/http/send?apiKey=AmwrItKBTSyRDz7xAI2p3A==&to=27999123456&content=Test+message+text", true);
xhr.onreadystatechange = function(){
    if (xhr.readyState == 4 && xhr.status == 200) {
        console.log('success');
    }
};
xhr.send(); 

API responses:

Example response - Single number submission

Successful API response:


<SendMessagesResponse>
<Messages>
<Message>
<ApiMessageId>f7012c1edff2509a19ce1667c7f52b18</ApiMessageId>
<Accepted>true</Accepted>
<To>27999123456</To>
</Message>
</Messages>
</SendMessagesResponse>

Error response for invalid key:


<SendMessagesResponse>
<Messages/>
<Accepted>false</Accepted>
<Error>Invalid or missing Integration API Key. - </Error>
</SendMessagesResponse>