Skip to contentSkip to navigationSkip to topbar
On this page

Guided Onboarding


(warning)

Guided Onboarding support ending December 31, 2024.

Meta will no longer support the Guided Onboarding process for registering WhatsApp Senders after December 31, 2024.

ISVs should adopt the WhatsApp Tech Provider Program in order to continue to register WhatsApp Senders for their client businesses and remain compliant with Meta.

For Direct Customers who wish to upgrade their accounts to WhatsApp Self Sign-up, Twilio will release this functionality later this year.

In this guide, we walk you through getting your Twilio phone number approved to be used with WhatsApp. This gives you the ability to receive and send messages from your Twilio number through the WhatsApp. If you want to use a non-Twilio number, please refer to Can I register my own phone number for WhatsApp on Twilio?(link takes you to an external page)

At a high level, to enable your Twilio number for WhatsApp, you must complete the following steps:

  1. Submit a WhatsApp Sender request in the Twilio Console
  2. Approve Twilio to message on your behalf in the Meta Business Manager console
  3. Submit your Meta Business Manager account for Business Verification
  4. (Twilio completes your WhatsApp Sender registration)

A note for ISVs

a-note-for-isvs page anchor

This guide includes instructions for both direct businesses and third-party vendors. Third party vendors include independent software vendors (ISVs) who are implementing WhatsApp on behalf of another company or brand. Under each step, look for the Note for ISVs subheading to find specific instructions.


Overview of the registration process

overview-of-the-registration-process page anchor

Before getting started

before-getting-started page anchor

Before getting started, please make sure your business meets the eligibility criteria for the WhatsApp Business Platform.

Can I use my own number?

can-i-use-my-own-number page anchor

If you want to use your number, and that number has never been registered with the WhatsApp Business API, then it can be used to register with Twilio. You will still need to follow the steps described in this guide.

Note for ISVs

When onboarding a new End Client, you will need to have the following information handy:

  • Client's Meta Business Manager ID - Your client will need to have created a Meta Business Manager prior to you submitting this form
  • Client's Legal Business Name
  • Client's Contact Email Address - This should be whoever will be filling out the form to accept the End Client terms

Step 1: Submit a Sender Profile and Message Templates

step-1-submit-a-sender-profile-and-message-templates page anchor

Submit the WhatsApp Sender

submit-the-whatsapp-sender page anchor

Navigate to the Messaging > Senders > WhatsApp Senders(link takes you to an external page) section in the Twilio Console. Click the WhatsApp Sender submission button to create a new sender profile. If you already have a WhatsApp sender, click "Create new Sender".

whatsapp-senders.

ISVs Only - Client Information

If this is the first WhatsApp Sender for a new End Client, you will need to enter in your Client's information. This replaces the request access form.

GuidedOnboardingEndClient.

Select a phone number

GuidedOnboardingSelectPhoneNumber.

Fill out your WhatsApp Sender Profile information

GuidedOnboardingProfile.

Twilio will then submit your Display Name to WhatsApp. You will receive automated confirmation through Zendesk that your Profile Information form has been received.

Logos are not reviewed by WhatsApp and can be set by submitting a link to an image as part of your WhatsApp Sender Profile. Please be aware of the following requirements when submitting a logo:

  • Minimum size restriction: 640x640 pixels
  • Maximum size restriction: 5 MB
  • Square aspect ratio
  • PNG or JPG (JPG recommended)
  • No clear (alpha) background

You can update your logo after your sender profile is approved by navigating to the WhatsApp Senders page(link takes you to an external page) and clicking on the sender.

The logo must only represent a brand that you own and operate. Operating a sender with another brand's logo is considered impersonation and is against WhatsApp's terms of service.


Step 2: Approve Twilio to send messages on your behalf

step-2-approve-twilio-to-send-messages-on-your-behalf page anchor

For the first WhatsApp Sender in an Account, when you receive notice that Twilio has submitted your Display Name and number to WhatsApp, you will need to approve Twilio to send messages on your behalf. You will receive an email to "Approve Twilio to message on behalf of" in your Meta Business Messenger. This email usually has the subject "WhatsApp Profile Request."

Go to the Facebook Business Manager console and approve Twilio to "message on behalf of." You can find this request by following this link(link takes you to an external page), or navigating to business.facebook.com(link takes you to an external page) > Business Settings > Requests section. Once there, click the Approve button.

Meta Business Manager Console page for approving Twilio to send messages on your behalf.

Step 3: Verify your Meta Business Manager account

step-3-verify-your-meta-business-manager-account page anchor

If you have already verified your Meta Business Manager account previously, you will not need to complete this step again. Consult Meta's documentation about verifying your business(link takes you to an external page) for more information.

As soon as you receive the ability to "Approve" Twilio to send messages on your behalf, you will be able to verify your Meta Business Manager account if you have not already done so. In the Meta Business Manager>> Settings console(link takes you to an external page), click the Start or Continue button under in the Verification section.

Meta business manager account verification in the Twilio Console.

(The verification button may be greyed out prior to starting the onboarding process.)

You may be required to upload supporting documents to verify your business. See Meta's guide on uploading official documents to verify your business(link takes you to an external page) for more information.

The Meta Business Verification process can take anywhere from 5 to 20 business days, depending on your region and company type. If you have not heard back from Meta in more than 10 business days, please let the Twilio team know.


Step 4: Twilio completes your WhatsApp Sender registration

step-4-twilio-completes-your-whatsapp-sender-registration page anchor

After you approve Twilio to message on your behalf, Twilio will complete the registration process to register your WhatsApp sender. You will receive an email confirmation that Twilio has finalized the registration of your profile.

At this point, your Sender is ready to receive messages from customers in production. You can test this by sending a WhatsApp message to your Twilio number and checking the Message Logs section in the Twilio Console(link takes you to an external page). Once you receive a message, you can reply within 24 hours with free-form messages. You can read more about Conversational messaging with WhatsApp here.


Step 5: Submit Message Templates

step-5-submit-message-templates page anchor

To start conversations with new users, or with existing users who have not sent you a message for more than 24 hours, you are required to use a message template. To submit a message template, navigate to Messaging > Senders > WhatsApp Templates(link takes you to an external page).
Learn more about WhatsApp Message Templates here.

Send an outbound freeform message with WhatsAppLink to code sample: Send an outbound freeform message with WhatsApp
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createMessage() {
11
const message = await client.messages.create({
12
body: "Hello there!",
13
from: "whatsapp:+14155238886",
14
to: "whatsapp:+15005550006",
15
});
16
17
console.log(message.body);
18
}
19
20
createMessage();

Output

1
{
2
"account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
"api_version": "2010-04-01",
4
"body": "Hello there!",
5
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
"direction": "outbound-api",
9
"error_code": null,
10
"error_message": null,
11
"from": "whatsapp:+14155238886",
12
"num_media": "0",
13
"num_segments": "1",
14
"price": null,
15
"price_unit": null,
16
"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
"status": "queued",
19
"subresource_uris": {
20
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
},
22
"tags": {
23
"campaign_name": "Spring Sale 2022",
24
"message_type": "cart_abandoned"
25
},
26
"to": "whatsapp:+15005550006",
27
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

Once your Twilio number is connected to WhatsApp, you have many options.


Why does Twilio need to modify my Voice URLs?

why-does-twilio-need-to-modify-my-voice-urls page anchor

In order to register a phone number with WhatsApp, WhatsApp sends a pin code to the phone number to verify ownership. In situations where the phone number cannot receive SMS messages, Twilio may need to receive the pin code from an automated voice call from WhatsApp. This can happen when a Twilio phone number is not SMS-capable, or when WhatsApp is having trouble delivering SMS pin codes to the phone number. To receive a pin code via voice, Twilio may temporarily disable the phone number's webhook URL used for incoming calls. This process typically takes 5-15 minutes, and Twilio will revert the change to the previous URL. However, during this time, all calls to the number will be routed away from your system so that our team can intercept the pin code from WhatsApp.

If your WhatsApp sender ever goes offline after it is initially registered, the pin code verification process will need to be completed again.

If you would like us to coordinate with you when registering or re-registering a number on WhatsApp, please let us know by opening a support ticket.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.