Setting up a custom connection with Aggregators supporting WhatsApp Business API Integration

Since WhatsApp opened up its WhatsApp Business API to companies, some aggregators i.e Twilio, Nexmo, Clickatell to name a few have added that integration so that their customers can use the integration in their products. 

In this article, we'll look at the steps of how to set up some of the Aggregators FrontlineSMS recommends to our clients. This will enable them to use the power of SMS to reach out to their users through the WhatsApp platform.

Clickatell WhatsApp Business API integration

Part 1: Setup instructions on Clickatell Portal

1. Log into the Clickatell portal (The steps below assume that you have already registered and been approved for WhatsApp integration)
2. Navigate to menu on the left and click on WhatsApp menu item. Once a dropdown sub-menu appears, select the sub-menu item Configure WhatsApp
3. The WhatsApp integration page will open. This shows you the integrations that you have registered. Click on the integration that you want to use.
4. A page with several tabs will be open, the default tab being the Integration details view. Note down the API Key displayed on that view which we'll use in the custom connection we will set up on Cloud.
5. On the Integration settings tab, we will add a Callback URL later, on once we have our custom connection setup on Cloud. This will be put under the Receive Message Callback URL section of that view.
6. On the Business profile tab, you'll find the phone number that you registered to be used in this integration.
7. On the Test phones tab view, you can add some test phone which you can use during activity testing (as recipients) before launching for a client

Part 2: Set up instructions on the FrontlineSMS Cloud

1. Open the Configure your Connections page on Cloud and click on Connect to a mobile network.
2. Once the sidebar opens, select the custom aggregator option. This will open up a  Create a new Custom Connection section on the sidebar containing details that will need to be field to set up the integration with Clickatell WhatsApp Business API.
3. Fill the fields on that form fields as shown below:

Name: <NAME_OF_YOU_CONNECTION>

Endpoint Url:  https://platform.clickatell.com/wa/messages

HTTP Method: POST

Content Type: JSON

Request Headers: 
    Authorization: <API key copied from Part 1 step 5 above>
    Accept: application/json

Single Messaging Payload: 
${groovy.json.JsonOutput.toJson([messages: [[to:"${destination}", content: "${text}"]]]).toString()}

Mark a message as sent if the condition below evaluates as True: 
${responseCode == 200 || responseCode != 401 }

Receiving Settings:
    Message Expression: ${parseJSON(requestText).content} 
    Sender Number expression: ${"+"+parseJSON(requestText).from}

4. Once you fill the details above click save and once the page reloads, your connection will be created. An example is shown below.
5. Copy the Callback URL (It's under the connection name) and add it to the Integration settings tab view as shown below then make sure to save your settings

Twilio WhatsApp Business API integration

Part 1: Set up instructions on the FrontlineSMS Cloud

1. Open the Configure your Connections page on Cloud and click Connect to a mobile network.
2. Once the sidebar opens, select the custom aggregator option. This will open up a  Create a new Custom Connection section on the sidebar containing details that will need to be field to set up the integration with Twilio WhatsApp Business API.
3. Fill the fields on that form fields as shown below:

Name: <NAME_OF_YOU_CONNECTION>

Endpoint Url:  https://api.twilio.com/2010-04-01/Accounts/AC98141d5a325008312b90b8f3af548a56/Messages.json

HTTP Method: POST

Content Type: URLENC

Request Headers: 
    Authorization: <BASIC_AUTH_OF_YOUR_TWILIO_CREDENTIALS>
    Content-Type: application/x-www-form-urlencoded

Single Messaging Payload Specify parameters to be sent as part of outbound messages requests:
    To: whatsapp:${destination}
    FROM : whatsapp:+14155238886
    Body: ${text} 

Mark a message as sent if the condition below evaluates as True: 
${responseCode >= 200 && responseCode < 300 && responseCode != 203}

Receiving Settings:
    Message Expression: ${params.Body}
    Sender Number expression: ${params.From - "whatsapp:"}

4.  Once you fill the details above click save and once the page reloads, your connection will be created. An example is shown below. Note down the Callback URL (below the connection name). We will use it to set back our callback settings on the Twilio Console

Part 1: Set up instructions on the Twilio Console

Currently we only have access to the Sandbox test integration but part of the steps below will also apply to the actual integration. Note that these notes will be updated once the approval is finalized

1. Ensure you have a registered the number in use i.e office number for the WhatsApp Twilio integration (In the sandbox environiment they will have already provided you with a test number)
2. Using the Callback URL copied from the last part add it to your Twilio WhatsApp integration as a POST request as shown below (UI on the actual configuration may differ)

3.  For testing purposes, you can add participants in the scenario where you want to test an activity before going to production under the Sandbox Participants