Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Twilio API for WhatsApp

Overview

WhatsApp is the most popular OTT app in many parts of the world. With the WhatsApp Business API with Twilio, you can reach more than 1.5 billion WhatsApp users. You can send notifications, have two-way conversations, or build chatbots. If you're trying to reach – and better converse with – users in LATAM, EMEA, and APAC, you need to consider using WhatsApp.

The WhatsApp Business API with Twilio is now available in an early-access program, to allow developers to start building and prototyping in a sandbox. To launch apps in production, start by requesting access to enable WhatsApp on your Twilio number. WhatsApp is currently providing this access in a limited availability program, for which WhatsApp approval is required for all customers who wish to create their own profiles.

WhatsApp Opt-In Requirements

WhatsApp requires that your application implement explicit user opt-ins to deliver messages over WhatsApp. You may gather this opt-in information either via a web page or a mobile app, such as during your application's sign-up flow, in your application's account settings, via SMS, etc.

Please note that sending messages to end users without an opt-in may result in users blocking your business as well as the suspension of your WhatsApp Business account.

Using Twilio Phone Numbers with WhatsApp

On WhatsApp, users message each other using phone numbers. To send and receiveWhatsApp messages using the Twilio Programmable Messaging API, you'll need a phone number as well. The Twilio API addresses WhatsApp users and your numbers, using the following prefixed address format:

whatsapp:<E.164 formatted phone number>

(E.164 is an international telephone number format; you will see it often in the strings that represent Twilio phone numbers.)

Enabling WhatsApp with a Twilio Number

To use WhatsApp messaging in production apps, you must enable WhatsApp on your Twilio number. WhatsApp is currently opening up this access in a limited availability program. This means that WhatsApp approval is required for all customers who wish to create their own profiles.

For a step-by-step walkthrough of the process, visit our guide to Connecting your Twilio Number to your WhatsApp Business Profile. One your request has been submitted and approved, you will be able to select your Twilio numbers and apply for them to be enabled in WhatsApp.

Please note: we are currently unable to enable WhatsApp on non-Twilio numbers.

Submit your Facebook Business Manager Account

WhatsApp uses your Facebook Business Manager account to identify your business and associate your phone numbers with it.

You must get approval to enable your Twilio numbers for WhatsApp. Next, you will need to provide Twilio with your Facebook Business Manager ID. If you do not already have a Facebook Business Manager account, follow Facebook's instructions to create one.

Your Facebook Business Manager ID can be found in the "Business Info" section under Business Settings.

BM.png

Manage and Configure Your WhatsApp-enabled Twilio Numbers

You can request to configure up to 25 new numbers for WhatsApp. To manage your own templates and your WhatsApp profile, go to WhatsApp Senders page in the Console. Here, you can see the list of your WhatsApp-enabled Twilio phone numbers (senders) as well as any templates that you have submitted for approval.

WA Senders

WA Sender Page

Sending Notifications with WhatsApp

WhatsApp requires that business-initiated notifications sent by your application be templated and pre-registered, with the exception of messages sent as a reply to a user-initiated message. (See Conversational Messaging on WhatsApp for more details).

To learn more, consult our Guide to Sending WhatsApp Notifications Using Message Templates.

Conversational Messaging on WhatsApp

To have 2-way conversations with end users, you need to be able to receive messages from them. Users can send your business messages either directly or in response to a templated notification.

How to Initiate WhatsApp "24-hour Session"

A WhatsApp session begins when a user sends a message to your app. Sessions are valid for 24 hours after the most recently received message, during which you can communicate with customers using free-form messages. To send a message outside the 24-hour session window, you must use a pre-approved message template. (See our Guide to WhatsApp Message Templates).

Configuring Inbound Message Webhooks

When customers send you a WhatsApp message, Twilio sends a webhook (a request to a URL that you specify) to your application. You can configure the URL to which Twilio sends a webhook when it receives inbound messages in the Twilio Console:

Configuring Fallback URLs for your WhatsApp-enabled Senders

Optionally, you can configure a Fallback URL in the same place that you set your default webhook URL. If a fatal error occurs while making a request to your primary webhook URL, Twilio "falls back" to this secondary fallback URL.

When making the request to your fallback URL, Twilio also submits the ErrorCode and ErrorUrl parameters, indicating the error code of the failure and the URL for which the failure occurred.

whasapp-sandbox-inbound-webhook.png
whatsapp-numbers-config.png
Configuring Inbound Message Webhooks for Twilio Sandbox for WhatsApp Configuring Inbound Message webhooks for your WhatsApp enabled Twilio number

For details on the data provided in the request that Twilio makes to your application (via the webhook URL), read more about Twilio's HTTP Requests to Your a Application.

Receiving a WhatsApp Message

The webhook for inbound messages uses the same format as incoming SMS and MMS messages, with the exception that To and From addresses will be set to WhatsApp addresses (whatsapp:<your E.164 number> and whatsapp:<User's E.164 phone number>), respectively.

Incoming messages may include text or media. The Body field contains the message text, and the MediaUrl field contains a link to the media file. You can learn how to download incoming media included in a message in the Receive and Download Images on Incoming MMS Messages tutorial. Supported media include images (JPG, JPEG, PNG), audio files, and PDF files, with a size limit of 16MB per message.

Responding to Incoming Messages with TwiML

WhatsApp incoming messages are fully supported by TwiML, allowing you to seamlessly use your existing SMS app with WhatsApp. For more information, check out Documentation on How to Use TwiML.

Sending a Freeform WhatsApp Message Using the API

Within a WhatsApp session, you can send freeform messages using the Programmable Messaging API. Freeform messages may include text or media.

Web links in Freeform WhatsApp Messages

Freeform WhatsApp messages that include web links will display a web page snippet preview when received on the WhatsApp client.

        
        
        
        
        Send a freeform message within the 24-hour session

        Send an outbound freeform WhatsApp Message

        Send a freeform message within the 24-hour session
              
              
              
              
              Send a freeform media message within the 24-hour session

              Send a freeform WhatsApp message with media

              Send a freeform media message within the 24-hour session

              Monitor the Status of your WhatsApp Outbound Message

              To receive real-time status updates for outbound messages, you can choose to set a Status Callback URL. Twilio sends a request to this URL each time your message status changes to one of the following: queued, failed, sent, delivered, read.

              You can set the Status Callback URL in the Console, or when you send an individual outbound message, by including the StatusCallbackUrl parameter. You can set this in different parts of the Twilio Console depending on your messaging set-up:

              When you set the Status Callback URL, Twilio sends a POST request to that URL, including the MessageSid (the Message's Unique identifier) along with the other standard request parameters as well as MessageStatus and ErrorCode.

              The parameters Twilio sends to your callback URL include all standard request parameters, as well as some unique messaging parameters. You can see the full list of parameters in the API Reference for the Message Resource.

                    
                    
                    
                    
                    Rate this page:

                    Need some help?

                    We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.