Basic commands

This section outlines the available WhatsApp Enterprise API functions to send and receive messages successfully.

The base URL for all API call strings is: https://platform.clickatell.com

You can send the following message types via the REST API:

1. Text message – plain text, rich text and URL support
2. Templated messages (also known as Highly Structured Messages [HSM])
3. Media Messages

Note: Businesses cannot initiate non-template messages to the end-users unless it is within the Customer Care window. Please review the latest Business Messaging Guide for more details on the various conversation types before implementing the below API calls.

Send Message API

Plain text

This command allows you to send one or more WhatsApp messages. The server will respond with a unique identifier for each message. The Clickatell platform then asynchronously targets the callback URL with status updates.

Request headers:

JSON Request

Response

Rich formatted text

Clickatell supports the following text formatting options when sending messages from business to end-user.

URL preview formatted text

This flag allows you to enable an URL preview of the first URL in your message on the recipient handset. WhatsApp by default recognizes an URL and makes it clickable within the application.

Please ensure the URL begins with http:// or https:// in the message content body.

Request headers:

JSON Request

Response

Template messaging

For the delivery of outbound transactional messages or re-engagement messages, a templated message format is required. This message is defined as a Highly Structured Message (HSM) message type. All the same text formatting will apply to templated messages as well.

Please ensure the template reference is preapproved for your business before use.

When sending a template message, you need to specify the template reference and associated parameter values of your template within the HSM array. Please note that the parameters in your template are in a sequential order beginning at {{1}}. Template parameters cannot have new-line/tab characters or more than four consecutive spaces or will be rejected by the WhatsApp client.

Sample template message: Hello {{1}}. This is a demo welcome message from {{2}}
Sample template reference: welcome_notification_demo

Request headers:

JSON Request

Response

The following message will be received on the phone:

 

Media messages

This command allows you to send messages containing images, documents or audio files to your consumer. Sending video in messages is not supported. Clickatell supports media sending by byte streams where the message content will be set to the base64-encoded file content value and the content-type correctly set to describe the data contained in the message body. If set incorrectly, the message API may not be able to process the content appropriately and the delivery may fail. If left blank, the message will be considered as text message type by default and processed accordingly. 

The caption parameter is optional and can be used to reference or name the media content being sent.

Request headers:

JSON Request

Response

 

Some of the popular supported media file types and their associated content-types for reference:

 

Encrypted message content

This command allows you to send encrypted message content using the Send Message API. The encryptionKey parameter will indicate to the API that the message content being transmitted is encrypted. The encryptionKey must be the base64 encoded ciphertext blob with which the message content was encrypted.

Message content encryption will be supported for text messages, templated messages and all supported media file types.

Encrypted text message example

Request headers:

JSON Request

Encrypted template message example

For templated messages, you can encrypt the values of the parameters within the API call as below. The remaining structure of the message must be left unencrypted to facilitate structure validation on API acceptance.

JSON Request

Encrypted media message example

Encrypted media messages require an additional parameter, sha265Hash. This is a hash of the file content that is being submitted before it is encrypted. The hash is used to verify that the media was decrypted successfully, before submission to WhatsApp Enterprise API. The hash value itself is sent unencrypted.

Request headers:

JSON Request

Response

 

General Callback API note:

Forward Compatibility

While the basic callback parameters will remain constant:

{  "integrationId":"string",   "integrationName":"string",  "messageId": "string" }

 

there are frequent additions to channels including new features and message types, Clickatell will be adding these to the callbacks as they become available. Customers are required to implement callback processing in such a way that additional parameters in the JSON structure do not break callback processing in the customer system.

Message status callback API

Clickatell will asynchronously send a callback to your application on the status update per message when received from WhatsApp. The callbacks may arrive out of order, but a timestamp is included with each callback for your reference.

Status callback example

Below is a standard callback sample when the message has been read by recipient:

POST Request

Message status descriptions

The following message statuses are generated after the Clickatell platform has accepted the message for delivery.

Receive message callback API

Clickatell will asynchronously send a callback to your application with the details of any messages that were received from the WhatsApp channel (incoming messages sent from the end user’s mobile phone to your business account). Note that the message in the callbacks is independent of the original sequence of messages sent. The callback will return the incoming messages as received with a timestamp generated by the WhatsApp client for your reference. The timestamp will indicate when the message was processed by WhatsApp.

Receive message callback example

Below is a standard callback sample that is generated when an incoming message has been received by the platform:

POST Request

Reply message callback example

End-users can respond to a specific message in WhatsApp. For the business to understand the context of a message reply, we include the relatedMessageId field. It will only appear for message replies and will contain the unique messageId related to the message the reply was to. No other fields are changed.

POST Request

Media message callback example

When a media message is received from the end-user, the platform will convert the media object into a base64 encoded string as the message content. The media message callback will also contain additional information like content-type and caption that identifies the media object type.

POST Request

Location message callback example

End-users can share their current location with the business from within the WhatsApp application. The business will receive the location information as shown below:

POST Request

Callbacks with encrypted content

If the content of a received message is encrypted, the callback will contain the encryptionKey parameter to be used for decrypting the message content. Media message callbacks will also have the sha256Hash parameter to be used to validate that decryption was done correctly in the customer system. Callbacks for the following message types support content encryption: plain text, template and media.

Sample encrypted text message callback information as shown below:

POST Request

Sample encrypted media message callback information as shown below:

POST Request

Sample encrypted location message callback information as shown below:

POST Request

Setting a username and password on callback (optional)

It is possible to predefine a username and password for your message callbacks. This value will then be included as parameters in the body to allow for system authentication.