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 Twilio API for WhatsApp, you can reach more than 1.5 billion WhatsApp users with one REST API, which is part of Twilio’s Programmable Messaging platform. 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. Learn More about WhatsApp.

Twilio API for WhatsApp 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; for example, during your sign-up flow, in account settings, via SMS, etc. Note that sending users messages without an opt-in may result in users blocking your business and suspension of your Whatsapp business account.

Twilio Sandbox for WhatsApp

With Twilio Sandbox for WhatsApp, you can prototype with WhatsApp immediately, without waiting for your Twilio number to be approved for WhatsApp.

Because Twilio Sandbox is pre-provisioned with a Twilio phone number that is shared across all sandbox users, you can pick from a list of sandbox numbers to use when you activate the sandbox via the WhatsApp console.

Sandbox

Joining a Twilio Sandbox

To send or receive WhatsApp messages to a user from the sandbox, you must first have the user join the sandbox.

Send “join <your sandbox keyword>” to your sandbox number in WhatsApp to join your sandbox and we'll reply with a confirmation that you’ve joined. Your sandbox keyword can be found in the console.

Once users join, they will only receive messages from your specific sandbox. To disconnect from the sandbox, they can reply to the message from WhatsApp with `stop`. You can switch to a different sandbox by messaging `join <other sandbox keyword>`.

This limitation does not exist on your own Twilio number that you enable for WhatsApp.

Twilio Sandbox Limitations

  • You can only message users who have joined your sandbox. Messaging other users will fail.
  • Twilio Sandbox supports functional testing, but not load testing of profile traffic.
  • Sandbox numbers are restricted to 1 message every 3 seconds.
  • Sandbox numbers are branded as Twilio numbers.
  • You can only use pre-registered templates with the sandbox for outbound messages sent outside a WhatsApp session. Click here for more information.

There is no limit to the number of messages you can send via Twilio Sandbox, nor any limit on how long you can use the sandbox. Sandbox messages are billed as usual, per pricing for Twilio API for WhatsApp.

Using 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:<e164 formatted phone number>

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, in which WhatsApp approval is required for all customers who wish to create their own profiles.

To provision your own numbers, visit the WhatsApp Console and submit a request for approval from WhatsApp. Once approved, you will be able to select your Twilio numbers and apply for them to be enabled in WhatsApp.

Currently, we are unable to enable WhatsApp on non-Twilio numbers. Support for this use case is coming soon and we will update these docs once available.

Submit your Facebook Business Manager Account

The Business Manager account is used by WhatsApp to identify your business and associate your phone numbers with it. Once approved to enable your Twilio numbers for WhatsApp, you will need to provide Twilio with your Facebook Business Manager ID. If you do not already have a Facebook Business Manager account, follow the instructions here to create one.

Your 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.

WA Senders

WA Sender Page

WhatsApp Verified Accounts

Types of WhatsApp Business Accounts

There are 2 types of WhatsApp Business Accounts. Note that very few businesses will be designated an Official Business Account. Being verified on Facebook or Instagram will not help your business to become an Official Business Account.

Name Description
Business Account Any account that uses the WhatsApp Business API is by default a Business Account.
Official Business Account

WhatsApp has verified that an authentic brand owns this account.

An Official Business Account is marked by a green checkmark badge in its profile and next to the header in the chat thread. The name of the business is visible even if users haven't added the business to their address books.

How Your Business Appears to Users

Depending on whether you have a WhatsApp Business Account or Official Business Account, users will see different things. However, if users already saved the business number in their address book, the name from the address book will be displayed, although the phone number will still be visible in the Contacts view. Please be prepared for users who may try to call this number and plan for how to handle such calls.

How Business Accounts Appear to Users

If your account is a Business Account, the Verified Name only will be shown, in smaller text, in the Contacts view; all other views will show the phone number. You can help customers learn more about your company by filling out your business info, including your business website, address, and hours.

WA Business Account

Official Business Account

If the WhatsApp Account is an Official Business Account, the Verified Name will be visible in the chat list, chat screens, chat groups, and contacts view instead of the phone number. There will be a green checkmark beside the displayed name in the contacts view.

WA Official Business Account

Benefits of Official Business Accounts

WhatsApp Official Business Accounts offer customers the following benefits:

  • A Verified Account badge, shown in the conversation header to ensure users recognize the business as a WhatsApp Verified Business.
  • Named Conversations, where incoming notification show the business name rather than a phone number, resulting in higher engagement and conversion rates because a business name is more easily recognized than a phone number.
  • Designation that the business is a known sender on a user device. Known senders benefit from:
    • Suppression of the automatic SPAM report/block suggestion on the conversation screen.
    • Clickable embedded links

How to Get Verified?

To get verified, follow the steps below. Note that approval is not guaranteed and is subject to the WhatsApp compliance team’s approval.

  • Verify your Facebook Business Account. Check your business information under Business Verification Status at https://business.facebook.com/settings/info. If the account shows “Unverified,” follow the link to get verified. To learn more about the verification process, click here.
  • Once the account is verified, open a support ticket with Twilio. Request to apply to a WhatsApp Official Business Account and provide the following information: A screenshot showing your verified account status, the business website address, the Facebook page URL, and the business name in languages other than English (if any). We will use this information to open a ticket with WhatsApp to verify the account.

It typically takes up to 3 weeks to complete an account verification review.

Sending Notifications

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 users, you need to be able to receive messages from them. Users can send you message either directly or in response to a templated notification. (See Discovery section below).

The 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).

Discovery

Customers can initiate a conversation with you on WhatsApp via URL deep links. If users installed WhatsApp on their devices, clicking the deep link will open a conversation with you inside of the app.

Deep link format : whatsapp://send?phone=<e164 number>&text=Hello!

Deep links can be embedded in web or mobile apps, advertised on the web, or placed wherever you want. They are an effective way to start conversations without needing to use templates.

Configuring Inbound Message Webhooks

When customers send you a WhatsApp message, Twilio sends a webhook to your application. You can configure the URL to which Twilio sends a webhook when it receives inbound messages on either the Sandbox page and the WhatsApp enabled numbers page.

Optionally, you can configure a Fallback URL on the same page. If a fatal error occurs while executing your primary webhook, Twilio will "fall back" to this secondary URL. When making the request to your fallback URL, Twilio will submit 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

Receiving a WhatsApp Message

The webhook for inbound messages uses the same format as incoming 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. Message text is included in the Body field and media will be included in the MediaUrl field. 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.

For details on the data provided in the callback, find out how to handle Twilio HTTP Requests to Your a Application in the overview.

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

              Formatting in WhatsApp Messages

              WhatsApp allows text, emojis, and some formatting in messages. To format all or part of a message, use these formatting symbols:

              Formatting Symbol Example
              Bold Asterisk (**) Your total is *$10.50*.
              Italic Underscore (_) Welcome to _WhatsApp_!
              Strike-through Tilde (~) This is ~better~ best!
              Code / Pre-formatted Three backticks (```) ```print 'Hello World';```
                    
                    
                    
                    
                    Use symbols to format your WhatsApp messaage

                    Send a formatted WhatsApp message

                    Use symbols to format your WhatsApp messaage

                    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" to which will webhook 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 outbound message, by including the StatusCallbackUrl parameter. (Click here for sandbox and here for your WhatsApp numbers.)

                    If you set the Status Callback URL, Twilio will POST the MessageSid 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.

                          
                          
                          
                          

                          Location Messages with WhatsApp

                          Sending outbound location messages over WhatsApp is similar to sending a text-based message, with the addition of the PersistentAction parameter in your Twilio API requests, with must include the following information:

                          • Body={name}
                          • PersistentAction=geo:{latitude},{longitude} OR
                          • PersistentAction=geo:{latitude},{longitude}|{label}
                          Name Type Required Description
                          name String Yes (for outbound messages)

                          The name of the location being sent.(Location must exist in Google maps for the hyperlink to work on Mac/Windows WhatsApp client)

                          latitude Number Yes
                          Latitude of the location being sent
                          longitude Number Yes Longitude of the location being sent
                          label String No Optional free-form text to display under the location name

                          WhatsApp Message Templates do not support location messaging at this time. Location messages are only supported within session messages, within the 24-hour session window of receiving an inbound message from a customer over WhatsApp. If the session has expired, you must wait for a new inbound message to trigger a new session before sending customers a location message.

                          You can also receive inbound location messages with the Twilio API for WhatsApp. Locations will not show up in the Twilio Console at this time. However, your web application will receive the location data in the POST request that Twilio sends.

                          Below is a sample payload containing location information. Please note that the Body={name} parameter is not required for inbound messages.

                          Latitude=37.7879277&Longitude=-122.3937508&Address=375+Beale+St%2C+San+Francisco%2C+CA+94105&SmsMessageSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&NumMedia=0&SmsSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&Label=Twilio+Inc&Body=&To=whatsapp%3A%2B14155238886&NumSegments=1&MessageSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&AccountSid=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&From=whatsapp%3A%2B12345678900&ApiVersion=2010-04-01
                          
                                
                                
                                
                                
                                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.