Twilio WhatsApp API and Flex in Minutes

November 12, 2020
Written by
Reviewed by

Flex Messaging with WhatsApp

With the recent announcement of Twilio API for WhatsApp and ongoing excitement around Twilio Flex, I thought it might be fun to bring WhatsApp into the contact center space. With just a few minutes of setup, customers can reach your business through an entirely different channel. Let’s take a look at how the hottest new things at Twilio work seamlessly together!


If you'd like to follow along and bring WhatsApp into Flex, you’ll need:

Let’s get started!


These instructions apply to Flex Legacy Messaging. To use WhatsApp with Flex Conversations, refer to Manage Conversations WhatsApp Addresses.

Start with Flex

If you’ve already set up your Flex instance, you can skip ahead to the next step.
If you’re new to Flex, create a new Flex account. Follow the prompts to kick off the Flex setup. During this process, several Twilio services will be created for you.
Launch the Flex UI in your browser, and you should see something like this:

Flex UI by default

Construct a Message Handler URL

The format of your Messaging Handler URL should be:

Replace ACxx with your Account SID (found in your account dashboard) and KSxx with your Flex Proxy Service SID (found in the Services page). This will be your Message Handler URL.

Set up your WhatsApp Sandbox

Navigate to the WhatsApp Sandbox. (If you haven’t already set up your sandbox, do so now!) Head over to the Sandbox Configuration section and paste the Message Handler URL into the "When A Message Comes In" text field. Save your sandbox settings.

WhatsApp Sandbox webhook setup

Gather Some Account Details

Still on the WhatsApp Sandbox, save your WhatsApp Number for later.


Navigate to Studio, and find the Messaging Flow for Flex. Save the Flow SID, starting with FWxx.

Messaging flow SID location

Within Programmable Chat, grab your Chat Service Instance SID, starting with ISxx.

Chat service SID

Lastly, grab your Auth Token so that we can make an API request to Twilio. The Auth Token is a hidden value found on your Flex account Dashboard.

Flex WhatsApp account dashboard

Finally, start a command shell session and run the following curl request:

curl -X POST "" \
--data-urlencode "ChannelType=whatsapp" \
--data-urlencode "Enabled=true" \
--data-urlencode "JanitorEnabled=true" \
--data-urlencode "IntegrationType=studio" \
--data-urlencode "ContactIdentity=whatsapp:+13115552368" \
--data-urlencode "FriendlyName=Flex WhatsApp FlexFlow" \
--data-urlencode "Integration.FlowSid=FWxxxxxx" \
--data-urlencode "ChatServiceSid=ISxxxxxx" \
-u ACxxxxxx:yourAuthToken

Replace the values above with your:

  • WhatsApp number (in the ContactIdentity) in this format: whatsapp:[+][country code][subscriber number including area code] (Ensure that the number after whatsapp: is in E.164 format and that it is set to the exact same number that you registered with WhatsApp. This may be different from your PSTN number)
  • Studio Flow SID (in Integration.FlowSid)
  • Chat Service Instance SID
  • Account SID
  • Auth Token

Example Flex Flows API Response

  "integration": {
    "retry_count": 3,
    "flow_sid": "FWda89b731a3cce381b3c37c69e0cd1013"
  "janitor_enabled": false,
  "integration_type": "studio",
  "date_updated": "2020-11-10T23:20:30Z",
  "enabled": true,
  "friendly_name": "Flex WhatsApp FlexFlow",
  "contact_identity": "whatsapp:+14155238886",
  "account_sid": "ACxx",
  "channel_type": "whatsapp",
  "url": "",
  "sid": "FOb939520aee88d161ae0f750db8ead4b9",
  "date_created": "2020-11-10T23:20:30Z",
  "long_lived": false,
  "chat_service_sid": "IS75c3668972364ff28a4d7ad06f0e6073"

You can handle your messages with more than just Studio. Learn more from our documentation on Messaging in Flex. For more details on Flex Flow properties, see the API reference page.

Start chatting

You’re ready to flex those WhatsApp muscles! Mark yourself as available in the Flex UI, send a WhatsApp message to the sandbox number, and watch it come in as a new Task in Flex!

WhatsApp in Flex screenshot

Accept the task, and get chatting! Your contact center can now receive inbound WhatsApp chats and respond to them just like SMS, Twilio Chat, or Facebook Messenger messages.

Keep Flexing those muscles

Now that you’ve added this quick channel integration to Flex, try adding another messaging channel. You can also make Flex your own by styling the UI to reflect your brand or creating custom components to extend what you can do with Twilio Flex.

Ready to do more with the Twilio API for WhatsApp? Try our emoji translation app, or our npm search bot, or create your own unique WhatsApp hack!

We can’t wait to see what you build! helps social impact builders use digital technology and financial resources to scale their reach and impact. Get started today at no cost. Sign up here for your Impact Access Program product credits. Eligibility criteria applies.