Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now


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


The Twilio API for WhatsApp enables you to reach over 1.5 billion users on WhatsApp using a simple REST API, all in Twilio’s Programmable Messaging platform. You can send notifications, have two-way conversations or build chatbots. WhatsApp is the most popular OTT app in many parts of the world. 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 early access, which allows developers to start building and prototyping in a sandbox. In order to launch apps in production, you can request access to enable WhatsApp on your Twilio number. WhatsApp is currently opening up this access in a Limited Availability program, where 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 via a web page or mobile app (for example during your signup flow, in account settings, via SMS, etc.) Sending users messages without an opt-in may result in users blocking your business and suspension of your Whatsapp business account.

Using Phone Numbers with WhatsApp

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

whatsapp:<e164 formatted phone number>

Twilio Sandbox for WhatsApp

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

It 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 here.


Joining a Sandbox

In order to send or receive WhatsApp messages to a user from the Sandbox, you must first have them 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 they 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`, or 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.

Sandbox Limitations

  • You can only message users who have joined your sandbox. Messaging other users will fail
  • Sandbox supports functional testing. Load testing profile traffic is not supported
  • The 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. See more here.

There is no limit to the number of messages you can send via the 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.

Enabling WhatsApp with a Twilio Number

In order to use WhatsApp messaging in production apps, you need to enable WhatsApp on your Twilio number. WhatsApp is currently opening up this access in a Limited Availability program, where WhatsApp approval is required for all customers who wish to create their own profiles.

In order 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 WhatsApp enabled.

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

Facebook Business Manager account

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 instructions here to create one.

The Business Manager account is used by WhatsApp to associate your phone numbers with your business and to identify your business.

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


Managing and configuring your WhatsApp enabled Twilio numbers

You can request up to 5 new numbers to be configured for WhatsApp, manage your own templates and your WhatsApp profile on WhatsApp Senders page in Console.

WA Senders

WA Sender Page

WhatsApp Verified Accounts

Types of WhatsApp Business Accounts

There are two types of WhatsApp Business Accounts:

名前 概要
Business Account Any account that is using 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 has 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 the user hasn't added the business to their address book.

Note: Very few businesses will be an Official Business Account. Being verified on Facebook or Instagram will not help your business be an Official Business Account.

How Your Business Appears to Users

Depending on your WhatsApp Account type, users will see different things. However, if a user has already saved the business number in their address book, the name from the address book will always be displayed. The phone number will still be visible in the contacts view. Please be prepared for users who may try to call this number and have a plan for how to handle these incoming calls.

Business Account

If it is a Business Account, the Verified Name will only 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 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 Account

WhatsApp Official Business Account offers customers the following benefits:

  • Verified Account badge - will show at the conversation header, making sure users recognize the business as Verified Business.
  • Named Conversations - incoming notifications will show the business name, rather than a phone number, leading to higher engagement and conversion rate, as the business is easily recognized, compared to messages sent from a phone number.
  • Mark the business as a known sender on a user device. Known senders benefit from:
    • Suppress the automatic suggestion for SPAM report/block showing in the conversation screen.
    • Enable embedded links from known senders are clickable.

How to get Verified?

To get verified, the business should go through the following steps. Note that approval is not guaranteed, and is subject to WhatsApp compliance team’s approval.

  1. Get the Facebook Business Account verified. Check your business information at https://business.facebook.com/settings/info, under Business Verification Status. If the account is showing “Unverified”, it will also show a link to get verified. Follow the process, and verify your account. More information about the verification process can be found here.
  2. Once the account is verified, open a support ticket with Twilio, requesting to apply to a WhatsApp Official Business Account with the following information: Screenshot showing your verified account status, the Business Website Address, the Facebook Page URL, and business name in languages other than English (if any). We will use this information to open a ticket with WhatsApp to get the account verified.

It typically takes up to 2 weeks to get an account verification review completed.


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 the Conversational Messaging on WhatsApp section for more details).

WhatsApp Message Template Format

A WhatsApp Message Template contains the full body of the message, with the parameters represented as placeholders using the format below.

For example, the message:

Hi Joe Barone! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is O12235234

can be templatized as:

Hi {{1}}! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is {{2}}

The template uses numbered placeholders `{{x}}` for each variable in the message. Each variable can be replaced with text that contains letters, digits, special characters, or spaces. Newlines (`\n`) are not permitted in the variable values.

A WhatsApp Message template can only contain text, emojis or WhatsApp-specific formatting. Media is not supported by WhatsApp template messages.

Templates pre-registered for the Sandbox

If you are developing with the sandbox, you can only use the following templates that we have pre-provisioned for you:

  • Your {{1}} code is {{2}}
  • Your {{1}} appointment is coming up on {{2}}
  • Your {{1}} order of {{2}} has shipped and should be delivered on {{3}}. Details : {{4}}

Registering your own templates

You can register and manage your templates in the Console once your Twilio number is enabled for WhatsApp.

Send a WhatsApp message using a template

Twilio supports sending WhatsApp templated messages without requiring a change in how you use the Twilio Programmable Messaging API.

In order to send a templated message, you include the full body of the message in the API call. Twilio will send the message as a templated message if it matches one of the approved templates. If the Body does not match a pre-registered template, the message will be sent as a freeform message, which may not deliver if it is outside a WhatsApp session (see below).

For the example above, you would send:

Body=“Hi Joe! Thanks for placing an order with us. We’ll let you know once your order has been processed and delivered. Your order number is O12235234”


        Conversational Messaging on WhatsApp

        To have a 2 way conversation with a user, you need to receive messages from them. Users can send you a message in response to a templated notification or directly (see Discovery section below).

        WhatsApp Session

        A WhatsApp session begins with a user initiated message to your app. Sessions are valid for 24 hours after the most recently received message, during which time you can communicate with them using free form messages. In order to send a message outside the 24 hour Session window, you must use a pre-approved template (see Sending Notifications section above).


        You can have customers initiate a conversation with you on WhatsApp via URL schemes, embedded in web / mobile apps. If the user has WhatsApp IOS, Android or desktop installed, clicking the deep link will open a conversation with you inside the app.

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

        Configuring inbound message webhooks

        When customers send you a WhatsApp message, Twilio sends a web hook to your application. You can configure the URL that Twilio sends a web hook to for inbound messages on the sandbox page and the WhatsApp enabled numbers page.

        Optionally, on the same page, you can configure a Fallback URL that Twilio sends a web hook to, in the event of a fatal error while executing your primary webhook. When making the request to your Fallback URL Twilio will submit the ErrorCode and ErrorUrl parameters, indicating the error code of the failure and what URL the failure occurred on.

        Configuring Inbound Message webhook 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, with a size limit of 5MB per message.

        For details on the data provided in the callback, find out how to handle Twilio HTTP Requests to your 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 the 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-link in freeform WhatsApp message

        Freeform WhatsApp messages that include web-link will be received showing a web page snippet preview when received on WhatsApp client.

        Sending a freeform WhatsApp message with Media attachment

        To send a freeform WhatsApp message with media attachment, include MediaUrl parameter in your message. Supported media include images (JPG, JPEG, PNG), audio files and PDF. One media attachment is supported per message, with a size limit of 5MB.

        Building Whatsapp Bots

        You can build Whatsapp AI-powered chatbots that respond to users in an automated way. With Twilio Autopilot, you can design, build and train bot-driven conversations to automate appointment scheduling, lead qualification, do surveys or any other data collection, question-answering, or intent-based routing use case.

        Learn how to build Whatsapp chatbots

        Monitor the status of your WhatsApp outbound message

        In order to receive real time status updates for outbound messages, you can choose to set a Status Callback URL that Twilio will web hook to 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 (here for sandbox and here for your WhatsApp numbers), or when you send an outbound message and include the StatusCallbackUrl parameter.

        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 its standard request parameters and some unique messaging parameters. You can see the full list in the API Reference for the Message resource.

        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
        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';```
        Rate this page:


        誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。