This guide explains how to use the Twilio Senders API to register a phone number on the WhatsApp Business Platform (Twilio calls this a WhatsApp Sender) to begin sending and receiving messages on WhatsApp using the Twilio APIs.
(information)
Info
If your use case does not require registering several WhatsApp Senders, then Twilio highly recommends using WhatsApp Self Sign-up in the Twilio Console to register your WhatsApp Senders rather than via the Senders API.
(warning)
Public Beta
The Twilio Senders API is currently available as a Public Beta product. This means that some features (including Twilio SDK support) for configuring your WhatsApp Sender via the REST API are not yet implemented, and others may be changed without notice before the product is declared Generally Available. Managing your WhatsApp Senders through the Twilio Console is Generally Available.
The resources for sending and receiving Messages with a WhatsApp Sender are Generally Available.
Meta requires all phone numbers registered on WhatsApp to have their ownership verified as a part of the registration process before they can send and receive messages. This is done by sending a verification code via either SMS or an automated voice call. If using a Twilio Phone Number with SMS capability, then Twilio will do this automatically as a part of the registration process outline below.
Before you get started
Note that
Meta limits the number of WhatsApp Senders you may have in a single
WhatsApp Business Account (WABA), and as a result,
Twilio account or subaccount
. (Twilio only supports a single WABA per unique ASID.) As a result, onboard numbers one by one, waiting until each one successfully returns an
ONLINE
status before moving to the next one.
If you are not using the WhatsApp Tech Provider Program to onboard customers as an ISV,
you must first register a number using WhatsApp Self Sign-up
in the Twilio Console.
Delete any numbers already registered on WhatsApp
though either the business app or consumer app. Learn how to
delete your WhatsApp account
.
If using a Twilio Voice or non-Twilio phone number (BYON), make sure it is not associated with an IVR system (interactive voice response) or any computer-operated phone system that prohibits receiving an verification code via SMS or voice call.
Choose a display name carefully, as it must strictly follow Meta's display name guidelines
.
(warning)
Display name changes are manual
There is no API to change the display name (i.e. profile.name property in the Senders API). Meta reviews display name asynchronously after the WhatsApp Sender is registered. Before registering WhatsApp Senders in bulk, verify the display name is not rejected by Meta with a single WhatsApp Sender before continuing. If the display name is rejected by WhatsApp, the phone number's messaging limit will drop to 250 business-initiated messages per 24-hour period and may risk disconnection by WhatsApp. Resolving this requires submitting a support ticket to Twilio.
Quick start guide using cURL
1. Choose a phone number
You may purchase a Twilio number using our Phone Number APIs, or bring your own non-Twilio phone number (BYON). We recommend using a Twilio Phone Number that has SMS capabilities, as then Twilio will do the verification step automatically for you.
If using a Twilio Voice-only phone number, you will need to configure it to make sure you can receive the verification code, before moving on to the next step.
How can I configure a Twilio Voice-only phone number to receive the verification code?
In the
Twilio Console
, navigate to the
Active Numbers configuration
page and look for the Twilio number that you are attempting to register with WhatsApp.
Click on the phone number and scroll down to the
Voice & Fax
section to configure the number.
In the
Configure with
dropdown, select the
Webhook, TwiML Bin, Function, Studio Flow, Proxy Service
option.
Change the Webhook URL and use the
Voicemail Twimlet
following this convention:
http://twimlets.com/voicemail?Email=[your email address]
. For example, your twimlet can look like this:
http://twimlets.com/voicemail?Email=support@example.com
.
Click the
Save
button.
Now, any incoming calls will be transcribed and sent to your email.
Once you receive the verification code, you may reset the Webhook URL to what it was previously.
2. Create the WhatsApp Sender and trigger the verification code
Run the following cURL command, substituting the following required information:
your phone number (in e.164 format) within the sender_id field
For AR (+54) and MX (+52) numbers, WhatsApp requires the format "+549" and "+521", respectively.
your WhatsApp Sender's display name (
profile.name
)
Twilio Account SID
Twilio Auth Token
You may optionally include the following additional information:
additional profile details that will be displayed publicly to end-users
webhooks that Twilio will use to send inbound messages (
webhooks.callbackUrl
and
webhooks.fallbackUrl
) and outbound message status updates (
webhooks.statusCallbackUrl
)
This will create your WhatsApp sender in Twilio's system, add it to the WABA connected to your Twilio account, and trigger the verification code from Meta.
Make a note of the WhatsApp Sender's SID (starting with an XE), as you will need it in the next step.
This step is not required for Twilio SMS-capable phone numbers. You may skip it.
Once you receive the verification code, you must update your WhatsApp Sender with it by making the following cURL command substituing the code you received.
If you are not using a Twilio SMS-capable phone number, you may need to verify your Sender before it will show as ONLINE. When the API call is made to create a WhatsApp Sender, Meta will send an OTP by either SMS (default) or a Voice call. A WhatsApp Sender will then be in PENDING_VERIFICATION until you update the Sender with the OTP you received.
In order to verify that the WhatsApp Sender was successfully registered, you will need to make the following request to fetch the WhatsApp Sender. In the response, check the status to make sure that it shows as ONLINE. If it still notes that it is PENDING_VERIFICATION then you will need to return to Step 2 in order to request another verification code.
(information)
Info
Note that a WhatsApp Sender may briefly show as OFFLINE when registering. If that happens, please wait a few minutes and fetch the WhatsApp Sender again. If it is still showing as OFFLINE then open a support ticket.
Once the WhatsApp Sender shows as ONLINE you may begin sending and receiving messages on WhatsApp using the Twilio APIs. Congrats!
What's Next?
Now that you have a WhatsApp Sender registered, here are some other must reads when building your WhatsApp integration using Twilio.