Twilio Flex WhatsApp Integration Checklist

Twilio Flex WhatsApp Integration Checklist

With billions of users around the world and its lack of reliance on cellular networks, WhatsApp can be an important customer engagement channel for companies using Twilio Flex. But integrating Twilio Flex and WhatsApp might seem like a daunting task due to the amount of effort required to stand up the desired experience.

In this blog post, I will provide a quickstart checklist that walks through standard implementation steps between Twilio Flex and WhatsApp. Completing this checklist will help you build a scalable WhatsApp integration that effectively reaches your audience.  

Prerequisites

• Single or multiple Twilio accounts depending on the environment strategy (we provide some guidance around account setup below)
• Identity Provider and Single Sign-On
• Meta Business Manager ID (formerly known as Facebook Business Manager ID)

Configuration Process

The following steps are not the only configuration options available, but they do cover most of the necessary implementation steps to have a successful inbound and outbound Twilio Flex contact center with WhatsApp.  

Step 1: Twilio Account Setup

The very first step in the Twilio Flex and WhatsApp integration is to configure your Twilio accounts.

When creating a Twilio account, there are several items to keep in mind:

• Ensure the account is a Twilio Flex account (note that it is possible to create a non-Flex Twilio account).
• Confirm billing on the account is done in the proper currency. By default, billing is done in US dollars, but depending on your country you might like to change that.
• Confirm the accounts are associated with the appropriate corporate consolidated billing entity. In other words, if your company has consolidated billing implemented with Twilio, new accounts have to be added to the existing entity.
• Add administrator access to the appropriate resources working on the project.

Step 2: Single Sign-On (SSO) for Twilio Flex

Each company has a different Identity Provider and a dedicated process to add a new Single Sign-On application. Please find the SSO guidance for Twilio Flex here.

Due to the various procedural delays, we recommend you start on the SSO project right after Twilio accounts have been properly configured. Completed SSO is not required for the rest of the steps in this blog post – however, we suggest you do it sooner rather than later.

Step 3: Request Access to WhatsApp

Once the Twilio accounts have been successfully configured, it is time to request Access to WhatsApp by submitting this form. This process enables Twilio accounts to access the WhatsApp Business API. Requesting a WhatsApp Business Account (WABA) for your development or staging environment is not a mandatory step, however, it will allow for more robust testing and an easier development process.

Once the “Request Access” form has been submitted, an email confirmation will be sent. Since the approval process can take up to a week, we recommend you start this process right after you set up your Twilio accounts.

Step 4: Purchase a Twilio phone number

While the WhatsApp access approval is in progress, the next step is to purchase a Twilio phone number. You will use this phone number for inbound and outbound WhatsApp messaging within a Twilio account. Repeat this process for every Twilio account.

Every country has its own regulatory compliance requirements. It is possible that a regulatory bundle needs to be submitted to Twilio before a phone number can be assigned to the desired Twilio account. Twilio offers a guide on how to submit a regulatory compliance bundle for approval.

Optional Step 5: WhatsApp Sandbox

This step is entirely optional for development/staging environments and is not needed for the production Twilio account.

WhatsApp sandbox with Twilio Flex can be enabled in the following way:

• For Flex 1.x: Flex 1.x uses the Programmable Chat API for 2-way WhatsApp communication. Follow this guide to have it enabled for your sandbox account.
• For Flex 2.x: Since Flex 2.x uses the Conversations API by default, enabling 2-way WhatsApp communication within Flex requires a bit more work and is documented here.

Step 6: Routing

With Twilio, there are many options when it comes to routing a task to an agent. The following documentation provides guidance on how to do various routing uses cases and provides definitions on Twilio components:

• Routing documentation 
• Tutorial & exercise on routing

This is not a definitive list of potential routing options within Twilio. Instead, it is a starting point to get WhatsApp messages (tasks) routed to Twilio Flex agents (workers).

Step 7: WhatsApp Sender

Once a Twilio account has been granted access to WhatsApp Business API via the approval process and a Twilio phone number has been successfully purchased, it is time to create a WhatsApp sender. The WhatsApp sender is the WhatsApp profile that is going to be sending and receiving WhatsApp messages.

This process will walk through:

• The creation of a dedicated WhatsApp sender.
• Linking of WhatsApp business account with the Twilio account.
• Creation of a WhatsApp Business Profile.
• Verification of the WhatsApp business phone number.
• Registration of the Twilio phone number with the newly created WhatsApp sender.

If you are not able to get the WhatsApp activation code via SMS, try using the voice method with this Twimlet.

Optional Step 8: WhatsApp Official Business Account

Once the WhatsApp business account has been approved, the next step is to request an Official Business Account.

Requesting an Official Business Account for WhatsApp is not a mandatory step, however, having an Official Business Account comes with additional benefits and features. 

Since the approval for WhatsApp Official Business Account is done at the sole and full discretion of WhatsApp, we recommend you start with the production Twilio account first, then decide if it makes sense to convert development/staging accounts into an Official Business Account as well.

Step 9: WhatsApp Templates

In order to send outbound messages with WhatsApp, Meta (WhatsApp's owner) requires the use of pre-approved templates. Without approved templates, outbound WhatsApp messages from Twilio will fail. This is a WhatsApp requirement, not a Twilio requirement.

WhatsApp templates will have to be individually requested and will be approved individually by WhatsApp as well. Make sure to properly test the desired outbound behavior before moving to production.

Step 10: Reporting - Flex Insights

Once the Twilio accounts have been properly configured and consolidated billing has been completed (if applicable), Twilio Flex Insights can be enabled.

Twilio Flex Insights provides details into conversations between agents and customers. Out-of-the-box and custom data views enable drill down from top-level KPIs to individual conversation segments. Information on how to build custom views inside of Flex Insights is available in the developer documentation.

Step 11: Local Development Environment

The following documentation will enable a local workstation to support Twilio Flex plugin development. Since the Twilio CLI allows you to manage your Twilio resources from your terminal or command prompt, this vastly simplifies the Twilio Flex Plugin development process:

• Start with the Twilio CLI tool
• Install the Twilio Flex plugin CLI
• Finally the CLI autocomplete
• Exposing local applications to the public internet can be done via the ngrok solution 

Step 12: Inbound WhatsApp Routing and Mapping

In order to route incoming WhatsApp messages to a Twilio Flex agent, you need to create a mapping between the Twilio/WhatsApp phone number and Twilio Flex.

• Flex 2.x uses the Conversation API for its WhatsApp messaging needs and requires a WhatsApp Conversation address to be created within the Twilio console.
• Flex 1.x uses Programmable Chat and Proxy to route incoming WhatsApp messages to Twilio Flex. It is necessary to create proper mapping between the Proxy service and incoming Twilio phone number following this guide. The process is very similar to the WhatsApp sandbox enablement.  

A common requirement is to have all of the messaging between the agents and customers be a part of the same conversation thread. This is not available out-of-the-box and custom code is needed to achieve this functionality.

Twilio’s Professional Services has made a custom plugin that enables this functionality for Flex 2.x by parking an interaction. The way this plugin works is by manually removing the agent from a conversation (using Conversations API) and assigning a Studio webhook to the conversations object. In case a customer replies back, the Studio webhook will route the customer’s WhatsApp message back through the designated Studio flow.

Step 13: Outbound WhatsApp Messaging

Once the WhatsApp templates have been approved by WhatsApp, they can be used to initiate an outbound WhatsApp message to customers. However, out-of-the-box messaging in Twilio Flex does not have an option to send outbound WhatsApp messages using the WhatsApp template.

This means a custom Twilio Flex plugin needs to be developed. This plugin provides some examples on how to send an outbound message using Conversation based messaging in Flex 2.0.

Step 14: Twilio Flex Plugin Deployment

Twilio's CLI has the capability of deploying your Flex solution (plugins and functions) to both accounts. This document provides guidance on how to do it.

Twilio Flex plugins can be deployed from a local development workstation or can be added to the existing CI/CD pipeline.

Conclusion

Congratulations, you have successfully created an inbound and outbound WhatsApp contact center with Twilio Flex, but this is just a beginning! The next step is to take all the building blocks you’ve gathered and start customizing the experience according to your business needs.

If your team would like assistance with any aspect of your solution, Twilio Professional Services is here to help. Reach out to learn more about our offerings.

I can’t wait to see what you build!

Matija Vrzan is a Senior Solutions Architect at Twilio’s NAMER Professional Services Team, changing the world one contact center at a time. He can be reached at mvrzan [at] twilio.com.