WhatsApp RESTful API Overview

Overview

This document is intended for businesses wanting to develop applications that make use of Clickatell’s RESTful WhatsApp Enterprise API to send and receive messages to and from end-users on the WhatsApp channel. This document is designed for customers approved for or enabled as WhatsApp Enterprise Business to reach their end-users on this channel. It is required that you complete your application process successfully within your Clickatell Connect Platform account.

Account configuration details

The Clickatell Connect solution offers a RESTful API enabling enterprise business to deliver WhatsApp messages to any mobile user that has opted in to receive communication from the company. The following are required to provision the production-ready WhatsApp REST API:

• Registered an active Clickatell account with billing details configured
• Successfully completed a WhatsApp business approval and registration process

Provisioning of a demo API

The Clickatell platform will enable a Demo API in your account as soon as your electronic WhatsApp application was registered and vetted. This will enable you to confirm the functionality of the API and deliver messages to registered test phones prior to the completion of the final business registration with WhatsApp.

Note: The demo API will be deactivated 30 days after successful business registration.

Activation of production API

Once your application was successfully approved, a WhatsApp Business registration will be activated and two RESTful API integrations will automatically be added for your account:

• Sandbox Integration: Allows you to start testing Clickatell WhatsApp Enterprise API immediately and deliver messages to the registered test phones. The Sandbox integration will replace the temporary demo integration that was initially provisioned.
• Production Integration: Your permanent WhatsApp API integration linked to your business profile for the delivery of production traffic.

Note: the API is defined and authenticated with the unique API Key

Setting up callback details

You can configure the following callback URLs for each of the WhatsApp Enterprise API integrations. This will allow you to register the webhooks to receive callback information directly into your application.

Note: the callback URLs are configured via the Clickatell portal UI when setting up your specific WhatsApp integration preferences

Non-functional message requirements and limitations

The API has the following limitations for the different message formats supported:

Text Message Limitations

• Maximum number of messages (destinations) in a single batch call: 200
• Maximum length of a single text message: 4096 characters

Media message limitations

• Maximum number of messages (destinations) in a single batch call: 200
• Maximum size of a single media message: 1Mb
• Maximum size of whole packet: 20Mb

Re-engagement message limitations

• All re-engagement messages will be sent using a pre-approved templated message to the consumer 
• Using freeform text for this message type will result in failure to deliver

Order of callback responses

The order of a callback response may not always follow the order of submission. We do not “retain” message status responses to maintain the original order of the submission. We attempt to deliver the response for any specific message as soon as the result is available. This logic also holds when a batch is submitted, i.e. should you submit 20 messages in a single call, the response will not “wait” for all 20 results before we return the status of all 20 in a similar format. The result(s) for each message in the original batch will be returned as soon as available, independent of the original submission grouping.

Templated Messaging

All one-way, outbound transactional messages from business to consumer will be verified and approved by WhatsApp before use. All transactional messages must be sent using the appropriate preapproved template. Once approved, the business can simply indicate the template ID and the parameters in the API call. 

Please refer to the WhatsApp Enterprise API – Business Messaging Guide to learn more about template message format, registration and approval process. You can create your own template messages from within your platform account.

Message Content Encryption

Clickatell API supports content encryption for your messaging application. Please refer to the WhatsApp Enterprise API – Clickatell Encryption Guide to learn more about the process of setting up the encryption service, creating and managing encryption keys, and configuring access.

When the message is encrypted you will need to indicate this in the API by specifying the key parameter (this parameter will also be in an encrypted format). Note that the key parameter is optional, but if you do not specify the key in the API call, the content will be treated as unencrypted. You can send the content of your message either in an encrypted or in a clear format.