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?

Connect your Twilio Number to your WhatsApp Business Profile

As of July 17th, 2020, WhatsApp is no longer accepting new ISVs (Independent Software Vendors) and SIs (System Integrators) as well as ISV/SI end-client engagements.

For existing ISVs, SIs, and their end clients, WhatsApp will require an additional audit. More information about the review process will be provided directly to these customers.

For new ISVs, SIs, and end clients requesting access, Twilio is still accepting applications, but the on-boarding process is paused until Q4 (Fourth quarter) 2020.

The notice applies to any third-party businesses on the WhatsApp Business API who are not end business customers. WhatsApp's definition of ISV has evolved to include any third parties who have access to customer data, including messages, obtained using the WA Business API, even if such activity is at the request of end clients.

In this guide, we walk you through connecting a WhatsApp Business profile to your Twilio phone number.

Associating your Twilio number with your Facebook Business Manager account gives you the ability to receive and send messages from your Twilio number using a WhatsApp Business profile. This means you can engage in conversational (two-way) messaging and send higher engagement notifications to your customers from your Twilio number.

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

  1. Request access to enable your Twilio numbers for WhatsApp
  2. Submit a WhatsApp sender profile request and your Message Templates in the Twilio console
  3. Approve Twilio to message on your behalf in the Facebook Business Manager console
  4. Verify your Facebook Business Manager in the Facebook Business Manager console
  5. (Twilio completes your WhatsApp Business Profile registration)

A note for third-party vendors

This guide includes instructions for both individual businesses and third-party vendors. Under each step, look for the Note for third-party vendors subheading to find specific instructions.

Overview of the registration process

Before getting started

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

Developers will need to verify their business through Facebook Business Manager as part of the process of connecting their WhatsApp Business Profile and their Twilio phone number. Please make sure your business is not on the list of prohibited verticals is listed in WhatsApp's commerce policy.

To connect your Twilio number with a WhatsApp Business account, have the following information handy:

  • Facebook Business Manager account: If you do not already have one, please read Facebook's instructions on setting up a business manager account. WhatsApp uses the Business Manager account to identify your business and associate your phone number(s) with it.
  • Facebook Business Verification: Businesses will need to verify their Facebook Business Manager account as part of the process. In some cases, this cannot be done in advance and Twilio will let you know when this step is required.
  • 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 note: Twilio is still accepting applications from third-party vendors, ISVs, and SIs, but the on-boarding process is paused until Q4 2020

If you are a third-party vendor, independent software vendor (ISV) or system integrator (SI), you will also need:

  • Your client’s Twilio Account SID: Your client needs to accept the WhatsApp terms of service in their own Twilio account by navigating to console under Programmable SMS > WhatsApp and clicking "I Accept." You must submit this Account SID in the "Request Access" form, as described below.
  • 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 "Requset Access" form under "Assign approval to alternate Account SID".

Can I move my approved WhatsApp number to Twilio?

In some cases, you can move an approved WhatsApp number to Twilio. Please read our support article about moving an existing WhatsApp Number to Twilio.

If you are able to port your WhatsApp number to Twilio, you will still need to follow the steps in the onboarding process described in this guide.

Step 1: Request access to enable your Twilio numbers for WhatsApp

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). Providing incorrect information here can lead to delays in the onboarding process.

Please note: Twilio is still accepting applications from third-party vendors, ISVs, and SIs, but the on-boarding process is paused until Q4 2020

If you are a third party vendor, ISV, or SI completing the form on behalf of your customer, you must submit one form per customer or brand that you support.

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:

  • 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 Sender Profile. For ISVs, it should be your email address, not your customer's email.
  • Company Name, Website, HQ Country: Your company’s information.
    • 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
    • Note for ISVs: This is your customer’s primary Account SID where they accepted the WhatsApp terms of service. This is not your Account SID and not your Subaccount 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 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.

Await pre-approval from Twilio

After you submit the "Request Access" form, you will receive an email confirming the form submission. Twilio will send this confirmation to the email address provided once access becomes available and you have been approved.

Twilio will notify you when your request for access to the Twilio API for WhatsApp has been approved. This message will contain the next steps for you to follow for submitting your sender Profile and WhatsApp Message Templates.

As part of this process, businesses must verify their Facebook Business Manager account. However, please note that Facebook Business Verification cannot be done ahead of time for all companies.

Only some companies which have access to certain Facebook features, such as games and apps, will be able to complete this verification step in advance.

If you are able to complete the steps outlined in Facebook's Verify Your Business documentation at this time, this guide will cover the process in a later step.

Step 2: Submit a Sender Profile and Message Templates

You will receive a pre-approval email containing "next steps" that instruct you to submit a sender profile and Message Message Templates.

Submit the Sender Profile and Message Templates for approval

Log into the Twilio Console and go to the Programmable Messaging > Senders > WhatsApp Senders section. Click the "+" button to create a new profile.

In the Twilio Console, go to Programmable Messaging, then Senders, then WhatsApp Senders to add a new WhatsApp enabled Sender (number)

When you submit a business profile, ensure that your display name follows WhatsApp’s Display Name rules. WhatsApp will reject display names that don't match the business name in Facebook Business Manager.

On this same screen, you can submit Message Templates along with your business profile. Learn more about Whats App Message Templates here.

Screenshot of "Submit Business Profile" form for WhatsApp

Using the information from your completed "Submit Profile Information" form, Twilio will submit your Twilio number and Business Profile display name to WhatsApp. You will receive automated confirmation through Zendesk that your Profile Information form has been received.

Logo requirements

Please be aware of the following requirements hwen 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

Using a brand name in your WhatsApp Business Profile

You may have a brand name that you wish to use 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 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.

Step 3: Approve Twilio to send messages on your behalf

When you receive notice that Twilio has submitted your WhatsApp Business display name and Twilio number to WhatsApp, you need to approve Twilio to send messages on behalf of that Business Profile. 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.

approve-twilio-request-800.jpg

Step 4: Verify your Facebook Business Manager account

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.

facebook_business_verification_button.jpg

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

Step 5: Twilio completes your WhatsApp Business Profile registration

After you approve Twilio to message on your behalf, Twilio will complete the registration process to connect your Twilio number and your WhatsApp Business Profile. You will receive an email confirmation that Twilio has finalized the registration of your profile.

At this point, your Business Profile 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.

        
        
        
        
        Send a freeform message within the 24-hour session

        Send an outbound freeform message with WhatsApp

        Send a freeform message within the 24-hour session

        What's next?

        Once you connect your Twilio number and WhatsApp Business profile, you have many options.

        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.