How to migrate a first generation WhatsApp API integration to One API (detailed)

This page provides detailed steps to migrate a legacy WhatsApp API integration to Clickatell’s One API.

The migration process can be summarized in the two steps shown below. Navigate to the relevant section for more information on each step.

Step 1:	Set up a One API integration in the user portal (via Classic View)
Step 2:	Update the authentication token and integration ID on the new One API integration

 

Read more:

• Summary Guide
• Compare the first generation WhatsApp API with the new One API
• Rollback from the One API integration to the first generation WhatsApp integration
• Allowed media types & sizes (business-to-handset)

 

Step 1: Set up a One API integration in the user portal

 

Note: this setup of the new One API integration must take place via the Classic View of the user portal as indicated by the screens below. See here to switch to the Classic View from within the new portal.

 

1. Log into the Clickatell Portal.

2. Click Launchpad on the left-hand navigation menu.

3. In the One API section, click Create One API Integration.

 

4. In the Details section:

• Add a name and description for your One API integration.
  • Note: This can be any meaningful value and does not relate in any way to the name and descriptions of the legacy WhatsApp integration you are migrating to One API.
• Select the Integration Type, i.e. whether this integration must be in the production or sandbox (test) environment.

 

5. In the Channel section:

• Use the toggle to switch the WhatsApp channel to “on”.
• From the drop-down, select the business WhatsApp number that you want to migrate to this One API integration.

 

6. In the Settings section:

• Use the toggle to switch Reply Callbacks to “on”.
• Specify how you want callbacks to be returned to your system (i.e. messages sent from the handset user to your business):
  • Enter your callback URL where it asks you to Enter target address
    • Note: This must be an HTTPS endpoint and must contain a valid SSL certificate. Clickatell does SSL certificate validation when making the HTTPS connection to your system.
  • For basic authentication on callbacks, populate the username and password in the Credentials for basic http authentication section (optional)
• Under Inbound Media, select how you would like to receive inbound media messages:
  • Inline: Inline processing of media content reduces integration complexity and is the preferred strategy when a client aims to send mostly smaller files or when the minority of messages sent are media files. However, when there is a requirement to send larger media files (specifically videos) or higher volumes of media messages, the increased data loads and costs become a disadvantage. The media file data gets populated inline in the callback JSON payload as a base64 encoded string. 
  • Pass by reference: The client first uploads the media content to a secure hosted online storage facility and then includes the specific media file reference and validation token in the actual API call. The callback payload to the customer’s system only contains a reference to the file on the Clickatell system. 

 

 

• Use the toggle to switch Status Notifications to “on” to set up inbound status update notifications.
• Specify where callbacks with status updates about an outbound message (i.e. sent by the business to a handset user) must be returned:
  • Enter your callback URL where it asks you to Enter target address
    • Note: This must be an HTTPS endpoint.
  • For basic authentication on callbacks, populate the username and password in the Credentials for basic http authentication section (optional)

 

 

7. Click the Generate API

• Note: The legacy WhatsApp integration settings will be ignored and overwritten by the settings of this One API.

 

 

8. The Edit API Integration page opens, displaying the newly generated API key and Integration ID.

• These are the keys you need to use to set up your inbound callback receiver/s and outbound message sending.

 

 

Step 2: Update authentication token and integration ID on new One API integration

 

HTTP request security header

‘Authorization: Your-Api-Key‘

The HTTP authentication header remains unchanged as ‘Authorization‘.

When setting up the new One API integration ID (Step 1), a new authentication token will be generated by the Clickatell system.

Update the authentication token and integration ID on your system to the new One API integration ID and authentication token to successfully connect and send messages via your new One API integration.

 

HTTP request endpoints

 

Type	Legacy WhatsApp API	One API
Message sending	POST https://platform.clickatell.com/wa/messages	POST https://platform.clickatell.com/v1/message
Media upload	Not Supported	POST https://platform.clickatell.com/v1/media
Media download	Not Supported	GET https://platform.clickatell.com/v1/media