WhatsApp (Twilio)

The WhatsApp channel allows chatbots and agents to chat with customers via the WhatsApp Business API through Twilio.

Once you add a WhatsApp channel, click anywhere on the channel row to configure it.

🚧

Requirement

The WhatsApp channel must be enabled before you test it. To enable the channel, click the STATUS toggle.

Before starting

Before starting, you must setup a Twilio account with WhatsApp Business API.

Settings

Under the SETTINGS tab, you have the following options:

  • Enable - make the channel live to the public
  • Name - edit the channel name within the AICX platform
  • Language - set the default language for customers using this channel
  • Testing mode - make chatbot edits live only after when the chatbot is deployed
  • Channel ID and Secret - required for the deploy script
  • Delete - remove the channel

❗️

Important

Once a WhatsApp channel is deleted, you will need to update the WhatsApp channel webhook information on your Twilio Console.

Twilio setup

Complete the following steps to set up a WhatsApp Business API on your Twilio account:

  1. Create an account on Twilio
  2. Purchase a mobile number from Twilio
  3. Request access to enable your Twilio numbers for WhatsApp
  4. Submit a WhatsApp Sender request in the Twilio console
  5. Approve Twilio to message on your behalf in the Facebook Business Manager console
  6. Submit your Facebook Business Manager account for Business Verification
  7. Twilio completes your WhatsApp Sender registration
  8. Set up template message for chatbot Trigger message

📘

Note

A mobile number already in use with the WhatsApp Business API cannot be migrated. You have to choose a different mobile number. You can use a mobile number that is already registered in the Android, iPhone, or Business application versions of WhatsApp. To register this mobile number on WhatsApp Business API, follow these steps.

📘

Note

If you have an existing mobile number for setting up a WhatsApp Business API, please refer to Twilio's transfer service steps to port this number to Twilio.

Please note that there might be extra charges for porting an existing mobile number. Currently, there are limited countries available for the porting service.

1. Create an account on Twilio

  • Sign up for Twilio account. If you signed up for a free account, please upgrade to a paid account.

2. Purchase a mobile number from Twilio

  • Once you login to the Twilio console, go to Develop > Phone Numbers > Buy a number to search for the mobile numbers available for your required countries.

🚧

Requirement

The mobile number must have SMS capabilities. Please contact Twilio if you need assistance.

3. Request access to enable your Twilio numbers for WhatsApp

  • To enable your Twilio numbers for WhatsApp, fill out Twilio's request access form
  • The information must correspond to the company whose brand will be represented on the WhatsApp business profile
  • Providing incorrect information here can lead to delays in the onboarding process
  • After you submit the form, you will receive an email confirming the form submission
  • Once Twilio reviews your account, you will receive a pre-approval email with subject You are now pre-approved to use Twilio APIs for WhatsApp
  • This email will contain the next steps for you to follow for submitting your sender profile and WhatsApp message templates.
  • If your company has missing information or falls into an industry forbidden by WhatsApp's commerce policy, Twilio may reject your submission
  • Final approval is provided by WhatsApp after you submit your sender profile

4. Submit a WhatsApp Sender request in the Twilio console

  • Follow the instructions on submitting a sender profile and message templates in your pre-approval email.
  • Log in to the Twilio Console and go to Develop > Messaging > Senders > WhatsApp Senders and click the "New WhatsApp Sender" button to create a profile

📘

Note

When you submit a business profile, your Display Name must be the business name used in the Facebook Business Manager Account. If you prefer to use another name, follow WhatsApp’s Display Name rules.

  • Twilio will submit your Display Name to WhatsApp, which is the final requirement for WhatsApp to approve before registering your mobile numbers
  • Logos are not reviewed by WhatsApp and can be set by submitting a link to an image as part of your WhatsApp Sender Profile
  • Logos must comply with the following requirements:
    i. Minimum size restriction of 640x640 px
    ii. Maximum size restriction of 5 MB
    iii. Square aspect ratio
    iv. PNG or JPG (JPG recommended)
    v. No clear (alpha) background
  • You can update your logo after your sender profile is approved by navigating to the WhatsApp Senders page and clicking on the sender
  • You may have a brand name that you wish to use as the Display Name for your WhatsApp Business Profile that differs from the name of your company; if so:
  • There must be a clear, externally published association between your company and the brand
  • This association between the brand and your business needs to be displayed on your website and on the Display Name per WhatsApp's Display Name rules.

5. Approve Twilio to message on your behalf in the Facebook Business Manager console

  • After you are notified that Twilio submitted your Display Name and mobile number to WhatsApp, you must authorize Twilio to send messages on your behalf
  • You will receive an email to approve Twilio, usually with the subject line WhatsApp Profile Request
  • Go to the Facebook Business Manager console and approve Twilio to message on behalf of your WhatsApp account
  • You can find this request by link, or navigating to business.facebook.com > Business Settings > Requests
  • Click the Approve button

6. Submit your Facebook Business Manager Account for Business Verification

  • After you approve Twilio to send messages on your behalf, you can verify your Facebook Business Manager account if you have not already done so
  • In the Facebook Business Manager Account > Settings console, click the Start or Continue button under the Verification section.

📘

Note

The Facebook Business Verification process can take anywhere from 5 to 20 business days, depending on your region and company type. If you have not heard back from Facebook in more than 10 business days, please let the Twilio team know.

7. Twilio completes your WhatsApp Sender registration

  • After you approve Twilio to message on your behalf, Twilio will complete the registration process to register your WhatsApp sender
  • You will receive an email confirmation that Twilio has finalized the registration of your profile
  • At this point, your Sender is ready to receive messages from customers
  • You can test this by sending a WhatsApp message to your Twilio number and checking the Message Logs section in the Twilio Console
  • Once you receive a message, you can reply within 24 hours with free-form messages
  • Learn more about conversational messaging with WhatsApp

8. Set up template message for chatbot Trigger message

  • To start chats with new customer or with existing customer who have not sent a message for more than 24 hours, you are required to use a message template.
  • To submit a message template, go to Develop > Messaging > Senders > WhatsApp Templates

Configuration

To configure your WhatsApp channel:

  1. Get the following info from your Twilio console: Account SID, Auth token, WhatsApp enabled number
  2. Paste the required info into the WhatsApp CONFIGURATION tab in the Proto AICX platform
  3. Enable the Webhook URL on your Twilio console

1. Getting required info from your Twilio console

  • Account SID - go to your Twilio console, click on the Account tab, then click General settings from the menu, then copy your Account SID under the Properties section

  • Auth token - go to your Twilio console, find the Auth token on the General Settings, and copy your Auth token

📘

Note

If you have multiple Auth tokens, use the Primary Token.

  • WhatsApp enabled number - go to the Twilio console, navigate to Develop > Phone Numbers > Manage > Active Numbers and copy mobile phone numbers

2. Paste the required info into the WhatsApp CONFIGURATION tab in the Proto AICX platform

  • Under the CONFIGURATION tab, paste the Account SID, Auth token, and WhatsApp enabled number from your Twilio console

🚧

Requirement

The mobile numbers must contains the + sign and the country code. Example: +60123456789.

3. Enable webhook URL on your Twilio console

  • Under the WhatsApp WEBHOOK tab in the Proto AICX platform, copy the Webhook URL

  • In your Twilio console navigate to Develop > Messaging > Senders > WhatsApp senders and then click on *Edit Sender

  • Paste the Webhook URL into these fields:
    i. Webhook URL for incoming messages
    ii. Fallback URL for incoming messages
    iii. Status Callback URL

Twilio Sandbox for WhatsApp

While you wait for your WhatsApp Business Profile to be connected with your Twilio phone number, you can setup the Twilio sandbox to test out the functionality of the WhatsApp Business API with Twilio.

The Twilio Sandbox for WhatsApp is a pre-configured environment available through the Twilio Console in which you can test sending messages to your chatbot in Proto's platform.

The Sandbox is pre-provisioned with a Twilio phone number (+1-415-523-8886) that is shared across all sandbox users. However, other users who share the same sandbox number won't receive your messages, only the ones who have opted in to your sandbox.

To send or receive WhatsApp messages to an end user from the Sandbox, you must first have any user join the Sandbox.

  1. Send the message "join " to your Sandbox number in WhatsApp to join your sandbox. Your Sandbox keyword is a unique string; you can find it in the Twilio Console. When Twilio receives the join message, we will reply with a confirmation to that user that they have joined the Sandbox.
  2. Add the Twilio sandbox phone number in your chatbot WhatsApp channel configuration page
  3. You can now start testing your chatbot in the WhatsApp sandbox.
  4. To disconnect from the Sandbox, you can reply to the message from WhatsApp with the word "stop". You can switch to a different Sandbox by messaging "join ".

📘

Note

Please note that the Sandbox expires three (3) days after joining. After this time, you should re-join to continue testing.

You cannot use custom WhatsApp notification templates with the Twilio Sandbox. Instead, the Twilio Sandbox for WhatsApp comes with three pre-configured templates for testing purposes. Please refer to the documentation on Twilio to test the template messages on your WhatsApp sandbox.


What’s Next