As of Sept 21, 2020, Twilio and WhatsApp have implemented a new process for ISV, SI and ISV/SI end customer onboarding. This new process is reflected below.
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 this article.
At a high level, to enable your Twilio number for WhatsApp, you must complete the following steps:
- Request access to enable your Twilio numbers for WhatsApp
- Submit a WhatsApp Sender request in the Twilio console
- Approve Twilio to message on your behalf in the Facebook Business Manager console
- Submit your Facebook Business Manager account for Business Verification
- (Twilio completes your WhatsApp Sender registration)
This guide includes instructions for both direct businesses and third-party vendors. Third party vendors include independent software vendors (ISVs) and systems integrators (SIs) who are implementing WhatsApp on behalf of another company or brand. Under each step, look for the Note for third-party vendors subheading to find specific instructions.
Please make sure your business is not on the list of prohibited verticals is listed in WhatsApp's commerce policy. In addition, developers will need to verify their business through Facebook Business Manager as part of the WhatsApp onboarding process.
To connect your Twilio number with your WhatsApp Business Account, have the following information handy:
- Facebook Business Manager account ID: If you do not already have one, please follow Facebook's instructions on setting up a business manager account. WhatsApp uses the FB Business Manager account to identify your business to safeguard the WhatsApp ecosystem.
- Twilio account: You will need your Twilio Account SID, which you can find in the Twilio console. At this time, trial accounts are not eligible to create a WhatsApp Business Profile with Twilio.
Please for third-party vendors: If you are a third-party vendor, independent software vendor (ISV) or system integrator (SI), you will also need:
- Twilio Subaccount for your client: This is where your client’s account will be provisioned. It is the subaccount on your (the ISV's) account. You must submit this Account SID in the "Request Access" form, both in the main Account Sid field and in the "Assign approval to alternate Account SID" field.
In order to enable your Twilio numbers for WhatsApp, you will need to fill out Twilio's "Request Access" form with accurate and up-to-date information, including your Facebook Business Manager ID. (Please note: This is not the same as your Facebook page). The information must correspond to the company whose brand will be represented on the WhatsApp business profile. Providing incorrect information here can lead to delays in the onboarding process.
Please note: As of Sept 21, 2020, Twilio and WhatsApp have implemented a new process for ISV, SI and ISV/SI end customer onboarding.
When completing the "Request Access" form, please take note of the information below (labeled Note for ISVs) to ensure that you correctly represent your customer.
Below is additional information on some of the fields on the "Request Access" form based on frequently asked questions:
- Phone Number: The phone number where the user or business requesting access can be contacted, not your Twilio Phone Number.
- Email Address: The address where Twilio will reach out with the next steps once your account is approved for use of the Twilio API for WhatsApp in production.
- Note for ISVs: The submitted email should go to whoever is managing the onboarding process. For ISVs, it should be your email address, not your customer's email.
- Company Name, Website, HQ Country: Your company’s information. To avoid delays, this should be the same company name used in your Facebook Business Manager account, and the same name that will be displayed on the WhatsApp business profile, once you go live.
- Note for ISVs: Complete these fields with the client company’s information.
- Twilio Account SID: Your primary Twilio Account SID. To find your Account SID, log into the console click the “Home” button, and locate your Account SID on the top right on the page. If this is a Flex account, use your Flex Project Sid.
- Note for ISVs: This is the Subaccount Sid where the WhatsApp sender will be provisioned. There should be one subaccount per client. Read more about subaccounts here. If this is a Flex account, use your Flex Project Sid.
- Facebook Business Manager ID: You can find this ID by following this link, or logging into business.facebook.com > clicking “Business Settings” > "Business Info" > Look for the Business Manager ID. (More information about submitting your Facebook Business Manager ID)
- "I've completed Facebook Business Verification": Learn more about Facebook's verification process documentation.
- "I wish to provision this account with a third party vendor": Check this box if a third-party vendor (ISV or SI) is provisioning the account. If the WhatsApp Business Profile is for your own brand, you do not need to check this box.
- "Assign approval to alternate Account Sid (Optional)":
- Note for ISVs: If you are an ISV, fill this out with the Subaccount Sid that you will use to provision your client’s account. There should be one subaccount per client. Read more about subaccounts here.
- "I understand Twilio can modify my SMS/Voice URL and that approval is only for the brand submitted": Twilio may momentarily use your Twilio number’s SMS or Voice URL to register your number with WhatsApp.
After you submit the "Request Access" form, you will receive an email confirming the form submission.
Once Twilio reviews your account, you will receive an email with subject "You are now pre-approved to use Twilio APIs for WhatsApp". This message will contain the next steps for you to follow for submitting your sender Profile and WhatsApp Message Templates. If your company has missing information or falls in a vertical forbidden by WhatsApp's commerce policy, Twilio may reject your submission. Final approval is provided by WhatsApp after you submit your sender profile (next step).
You will receive a pre-approval email containing "next steps" that instruct you to submit a sender profile and Message Templates.
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.
- If you want to port your number to Twilio, please read our support article about moving an existing WhatsApp Number to Twilio.
- If you just want to register your own number without porting it to Twilio, please read our support article about activating your own number.
Log into the Twilio Console and go to the Programmable Messaging > Senders > WhatsApp Senders section. Click the "New WhatsApp Sender" button to create a new profile.
When you submit a business profile, your "Display Name" must be the business name used in the Facebook Business Manager account. If you would to use another name, it must follow WhatsApp’s Display Name rules.
Twilio will submit your Display Name to WhatsApp. This is final piece of information that WhatsApp will need to approve to register your number. You will receive automated confirmation through Zendesk that your Profile Information form has been received.
Logos are not reviewed by WhatsApp and can be updated any time by opening a support ticket. Please be aware of the following requirements when submitting a logo as part of your WhatsApp Sender profile:
- Minimum size restriction: 640x640 px
- Maximum size restriction: 5 MB
- Square aspect ratio
- PNG or JPG (JPG recommended)
- No clear (alpha) background
You may have a brand name that you wish to use as the Display Name for your WhatsApp Business Profile that differs from the name of your company. If so, there must be a clear, externally published association between your company and the brand. This association between the brand and your business needs to be displayed on your website and on the Display Name itself.
For example, if your company is Johnny Mobile and your brand is "PizzaApp", then we would recommend using the Display Name "PizzaApp by Johnny Mobile." This association must be published on your website so WhatsApp can verify it. This means that somewhere on the website, there must be a visible relationship between the two names. If you would like to keep the name "PizzaApp", this will generally require an appeal to WhatsApp and may extend the registration process.
For more info, see WhatsApp's Display Name rules.
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 Facebook Business Messenger. This email usually has the subject "WhatsApp Profile Request."
Go to the Facebook Business Manager console (the one that you submitted in Step 1) and approve Twilio to "message on behalf of." You can find this request by following this link, or navigating to business.facebook.com > Business Settings > Requests section. Once there, click the Approve button.
Please note: If you have already verified your Facebook Business Manager account previously, you will not need to complete this step again. Consult Facebook's documentation about verifying your business 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 Facebook Business Manager account if you have not already done so. In the Facebook Business Manager>> Settings console, click the Start or Continue button under in the Verification section.
(The verification button may be greyed out prior to starting the onboarding process.)
The Facebook 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 Facebook in more than 10 business days, please let the Twilio team know.
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. 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.
To start conversations with new users, or with 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 Programmable Messaging > Senders > WhatsApp Templates. Learn more about Whats App Message Templates here.
Once you connect your Twilio number and WhatsApp Business profile, you have many options.