12 April 2017

HTTP API: Send message

12 April 2017
clock
4 minutes

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>

 

Featured Insight Circle post

Reclaiming Billions in the Digital Economy: James Ronca

Related blogs posts

Reclaiming Billions in the Digital Economy: James Ronca
The 2020s: Decade of Dynamic Payments
Life will never be the same

About Clickatell

Todays’ consumers spend more time on chat like text, Instagram, Facebook Messenger, and WhatsApp than apps, and they expect a high degree of convenience in the way brands serve them. Clickatell makes it possible for brands and consumers to engage and transact via mobile chat and digital channels with industry-leading communications commerce platforms and solutions. With offices in San Francisco, Toronto, Cape Town, and Lagos, Clickatell serves more than 15,000 global brands, ranging from Fortune 500 organizations to well-known consumer brands and small businesses in over 220 countries worldwide.

Read more about Clickatell

Related blogs posts

Reclaiming Billions in the Digital Economy: James Ronca
The 2020s: Decade of Dynamic Payments
Life will never be the same

This website uses cookies to allow us to see how the site is used. The cookies cannot identify you. If you continue to use this site we will assume that you are happy with this. If you want to use the site without cookies or would like to know more, you can do that here.