WhatsApp Tech Provider Program Integration Guide

You will need to register as a Meta Developer if you haven't created a Meta app before. See Meta's Register as a Meta Developer documentation for more information.

It's recommended to start with a new Meta app (even if you already have another Meta app). If you already have another Meta app, there is little benefit to reusing it unless you have already completed the WhatsApp Tech Provider process for another BSP or with Meta directly.

1. Visit Meta's App Creation Page to create a new app.
2. Under App details, enter the app name and a contact email for Meta to reach out if necessary.

3. Under Use cases, choose Other.
4. Under Type, select Business.
5. Under Details, validate that the app name and app contact email are correct, and select your company's Business portfolio.
6. Click on Create app to continue.

1. On the Dashboard page within your Meta app, find the WhatsApp card and click on Set Up.

2. Under the Scale your Business section, there is a Become a Tech Provider card. Click Start Onboarding. Please note that by doing so, you will be accepting Meta's Tech Provider Terms and any other associated terms from Meta.

3. Even though you are working with Twilio, on the next screen, please select Independent Tech Provider, as Twilio doesn't publish its Meta app ID externally.

1. Navigate to the App settings > Basic page using the navigation on the left side of the page.

2. Here, you should add the following information:

   • Your App Icon, which can be the same as your company's logo. This will be visible to your customers when onboarding to WhatsApp.

     • Don't use any Meta logos or trademarks on the icon (e.g., "WA", "WhatsApp").

   • A URL to your company's privacy policy. This will also be available to your customers when onboarding to WhatsApp.

   • A category that best represents your app or business.

3. Now, scroll down and click on the Add Platform button. Here, you will need to specify the platform you're using (e.g., a website or app). Under the platform you choose, you do not need to add testing instructions and can ignore that section.

1. On the App Review > Permissions and Features page, find the whatsapp_business_management permission.

2. Click on either Request advanced access or Edit App Review request, depending on what is displayed.

3. In the modal that is displayed, answer Yes to "Are you creating an integration to enable multiple business clients to manage their own Facebook data? (e.g., a SaaS platform or a chatbot for multiple business clients)"

4. You will then be taken to the App Review > Requests page. Scroll down to the bottom of the Request for App Review page. There you will find the Data Handling questions section. Click on the arrow to answer the data handling questions.

Meta will require you to:

• Indicate if you have a data controller located in the European Economic Area (EEA) or the United Kingdom (UK) that will be responsible for all data Meta shares with you.

• For each data processor, provide the company name, purpose of data access, and countries where data will be obtained. A data processor is a company that will have access to users' personal data obtained from Meta.

• Share which processes you have in place to adhere to requests from public authorities for the personal data of users.

  For more information, see Meta's Data Handling Questions FAQs documentation

Neither Twilio nor Meta can provide guidance on completing this section for your organization. Please consult legal, policy, and data handling experts within your organization for guidance on how to answer these questions.

5. Once completed, click Submit on the modal.

Next, review your app settings, and fill in any missing information.

The final step prior to submitting for app approval is providing your "app verification details".

1. Click on Provide verification details on the same App Review > Requests page.

2. You do not need to submit instructions. Instead, in the box where it asks for instructions, you may copy and paste the text below:

   Copy code block

   We are applying to become a WhatsApp Tech Provider. We will be submitting videos for the whatsapp_business_management permission. We will be working with Twilio who already has whatsapp_business_messaging permission and won't be sending messages with the Meta API.

3. Click Save on the modal.

Meta has two different permissions for WhatsApp Tech Provider which should have automatically been added to your app:

• whatsapp_business_messaging - Since you will be using Twilio's APIs to send and receive WhatsApp messages—rather than Meta's—you do not need this permission.

• whatsapp_business_management - This allows your app and business to manage the WhatsApp Business Accounts (WABAs) created and owned by your customers within Meta's WhatsApp Manager UI.

1. Next to How will your app use the advanced access whatsapp_business_messaging permission?, click on the trash can icon to remove the whatsapp_business_messaging permission from your app review request.

2. Click the card asking How will your app use the advanced access whatsapp_business_management permission? to fill in details about your application.

3. In the first box, explain how your business utilizes the WhatsApp Business Platform.

4. Next, you will need to create a screen recording creating a WhatsApp template with either the Twilio Console using the Content Template Builder or within Meta's WhatsApp Manager. If you use the Twilio Console, you can use the account where you onboarded your own company's brand using WhatsApp Self Sign-up. Omit audio, as Meta's reviewers won't listen to it.

5. Return to your browser window with app review and upload the screen recording.

6. Check the box, and click Save.

7. Finally, click Submit for Review.

Let Twilio know that you have submitted your App to Meta. Twilio is here to help you along the way, and we want to know how it's going!

Once Meta has reviewed your App, you will receive an email and Alert in your Meta App Dashboard. Go to Alerts > Inbox and review the submission results.

Once your Meta app is approved, you will need to complete Meta's Access Verification to verify that your business is a Tech Provider. You can do this in your App Dashboard by navigating to App Settings > Basic. There you should see an option to complete Access Verification. Fill out the required information, and submit. Meta typically takes 5 business days to review this, but if it's taking longer than expected, please inform Twilio to escalate it on your behalf.

Congratulations on getting all of the Meta approvals completed!

In order to continue, Meta requires a Partner Solution, which lets Meta know that you are working with Twilio and gives Twilio permission to access your customers' WABAs.

1. If you haven't already, you will need to copy your Meta app ID shown at the top of your App Dashboard and send this to Twilio's channels onboarding team using the support ticket created when you requested access to the Tech Provider Program.

2. Wait 1–2 business days for the channels onboarding team to send you the Partner Solution request. Once sent, you will be notified via the support ticket. You will also receive an email from Meta directly.

1. In the left navigation within the Meta app, select Products > WhatsApp > Partner Solutions. Click Accept to confirm Twilio's request.
2. Let Twilio's channels onboarding team know that you accepted the request.
3. Save the Partner Solution ID as you will need it in Part 3 when adding the Embedded Signup code to your website.

For compliance and legal reasons, Meta needs to track all businesses with access to a WABA. As a result, Twilio needs to update all WABAs created for customers you have already onboarded to WhatsApp to include the Partner Solution that you just accepted. This will require each of your customers to accept this request; however, please note that the process is slightly different depending on how you initially onboarded your customers to WhatsApp with Twilio.

If you had previously used the Guided Onboarding process to onboard your customers to WhatsApp, Twilio created a WABA that is currently owned by Twilio's Meta business portfolio.

This means that only Twilio can currently view your customer's WABA within Meta's website. In order to add the Partner Solution to your customer's WABA, Twilio will request to transfer the WABA's ownership over to your customer. Once they accept the request, both you and your customer will have access to view their WABA within Meta's website.

After accepting Twilio's Partner Solution request in your Meta app dashboard, Twilio will notify you via the same support ticket about initiating the "ownership transfer" for existing Guided Onboarding customers. If they don't notify you, please request that they allow your customers to access their WABAs created with Guided Onboarding and add the Partner Solution.

Once Twilio confirms they have made this request for your customers, please notify them to accept it within their Meta business portfolios by following the steps below. Specifically for customers that onboarded to WhatsApp via Guided Onboarding, neither Twilio nor Meta will send an email to them notifying them to accept this request.

1. In their Meta business portfolio, navigate to Settings > Requests > Other requests.
2. There, they should see a message that "Twilio, Inc requested to transfer the [name of the customer's WABA] WhatsApp account to your business portfolio."
3. They will need to click Review and accept the ownership of the WABA in the screens that follow.

If you had previously used Twilio's WhatsApp Self Sign-up process to onboard your customers to WhatsApp, Twilio will need to add the Partner Solution to your customers' WABAs. Once your customer accepts this request or it is accepted by Meta automatically (see below), their WABA will be available to view within your Meta business portfolio on Meta's website.

Once you accept Twilio's Partner Solution request in your Meta app dashboard, using the same support ticket created after submitting the Tech Provider request form, notify Twilio that you had previously onboarded customers using WhatsApp Self Sign-up and need to add your Partner Solution to their WABAs. Twilio will not prompt you to update any WABAs onboarded via WhatsApp Self Sign-up.

Once Twilio makes this request to Meta to add the Partner Solution to your customer's WABA, Meta will email your customer directly to accept this request. They can accept this request by following the steps below, or Meta will automatically accept it after 90 days if your customer takes no action.

1. In their Meta business portfolio, navigate to Settings > Requests > Other requests.
2. There, they should see a message that "Twilio, Inc has requested to allow their partner access to [name of the customer's WABA] WhatsApp Business Account."
3. They will need to click Review and accept the access request of the WABA in the screens that follow.

You can still use the existing processes to onboard WhatsApp Senders for existing customers. However, in order to onboard new customers to WhatsApp, you will need to complete Part 3.

It's almost time to code, but first we need to do additional technical setup within your Meta app.

First, familiarize yourself with the onboarding flow that your customers will follow:

1. Your customers will choose the phone number that they wish to use on WhatsApp (unless you assign numbers automatically). The WhatsApp Tech Provider Program supports both Twilio phone numbers and non-Twilio phone numbers (i.e. bringing your own phone number, or BYON) on WhatsApp, but it's up to you on what you expose to your customers. Note: this needs to happen before the Embedded Signup popup window, so that you can get the full phone number required by the Senders API, as Meta doesn't return the full phone number.

2. Your customers will click the "Login with Facebook" button within your UI and the Embedded Signup popup window will launch.

3. In the popup window, they will follow Meta's Embedded Signup flow and complete the following:

• Create or select a Meta Business Portfolio
• Create a WhatsApp Business Account ("WABA") or select the existing one if onboarding an additional number
• If not using a Twilio SMS number that you have purchased, they will need to verify ownership of the phone number with Meta by entering their phone number again and verifying it using a one-time password (OTP) that Meta will send via either SMS or voice call.

4. Once your customer completes the flow within the Embedded Signup window, it will close and you will need to register their WhatsApp Sender using the Twilio Senders API and the subaccount credentials that you have assigned to this customer.

We will start by completing the integration with Meta's Embedded Signup feature by adding a "Login with Facebook" button into your front-end. Then, we'll move to the backend where we will need to take the information returned when your customers complete the front-end flow and call the Senders API to register the phone number by creating a WhatsApp Sender in your Twilio subaccount that's assigned to your customer.

In order to set up your Embedded Signup integration, Meta requires you to first create what they call a "login configuration". This is where you will use the whatsapp_business_management permission that you requested during Meta app review. This allows your customers to log in to their Facebook account and select or create their Meta business portfolio and WABA and then share it with your app and business.

1. Go to the Facebook Login for Business > Configurations page using the left-hand navigation and click on Create Configuration.

2. In this section, assign a name to your configuration—for example, you can call this "Embedded Signup Integration". This name will not be visible to your customers. After you've entered a name, select Next.

3. In the login variation section, select the WhatsApp Embedded Signup option and click Next.

4. Choose Access Token: This section refers to your Meta Graph API access token. Since you are working with Twilio and will not be calling Meta's Graph API directly, you don't need to worry about this page. Simply select the recommended 60 days option and click Next.

5. Under the Assets section, make sure the WhatsApp accounts option is selected.

6. Verify the whatsapp_business_management permission has been added before you finalize the configuration. Since you are working with Twilio's APIs, you don't need to add other permissions, so don't add other permissions to reduce potential for errors later on during the integration.

7. Click Create and save the Configuration ID that Meta provides. You will need this when adding the JavaScript code for Embedded Signup to your website.

In order for Embedded Signup to function correctly, we will need to make some updates to your Facebook Login for Business settings.

1. On the left-hand navigation menu, go to Facebook Login for Business > Settings.

2. Enable the following toggles if they're not already enabled:

   • Client OAuth login
   • Web OAuth login
   • Enforce HTTPS
   • Embedded Browser OAuth Login
   • Use Strict Mode for redirect URIs
   • Login with the JavaScript SDK

3. Add your website's domain(s) into both Valid OAuth Redirect URIs and Allowed Domains for the JavaScript SDK. These URIs need to be served using HTTPS and can only be static, and not dynamic URLs that use a wildcard.

4. Make sure to click Save changes.

One final step before you begin coding. When your Meta app's App Mode is set to Development, as it is by default, then only users that have been added to your Meta app can access it. Otherwise, an error will be shown. Before moving into Production, you will need to update your App Mode to be set to Live (at the top of the App Dashboard).

To add additional developers and testers to your Meta app:

1. Using the left-hand navigation, go to App roles > Roles
2. It is recommended to edit app roles within the Business settings. Click on Edit roles in Business Manager.
3. In the new tab that is opened, click Assign people and add your coworkers that will need to be able to test your Embedded Signup integration.

Alright, now it's finally time to code!

1. Add the snippet below after the opening <body> tag on the page you intend to add the "Login with Facebook" button. Make sure you replace the value with your App ID.

   Copy code block

   1
   <script>
   2
     window.fbAsyncInit = function() {
   3
       FB.init({
   4
         appId: 'APP_ID', // Replace with your Meta app ID
   5
         autoLogAppEvents: true,
   6
         xfbml: true,
   7
         version: 'v21.0' // Latest version when this doc was published
   8
        })
   9
     };
   10
   </script>
   11
   <script async defer crossorigin="anonymous" src="https://connect.facebook.net/en_US/sdk.js"></script>

2. Add the following HTML to where you want to surface the "Login with Facebook" button. Styles are included to match Meta's style guide.

   Copy code block

   1
   <button onclick="launchEmbeddedSignup()" style="background-color: #1877f2; border: 0; border-radius: 4px; color: #fff; cursor: pointer; font-family: Helvetica, Arial, sans-serif; font-size: 16px; font-weight: bold; height: 40px; padding: 0 24px;">
   2
   Login with Facebook
   3
   </button>

3. The button above will trigger the launchEmbeddedSignup function as defined below, which will open the Embedded Signup popup window.

   Make sure to replace the placeholder values with your Configuration ID and Partner Solution ID.

   Copy code block

   1
   // Handle WhatsApp Embedded Signup
   2
   function launchEmbeddedSignup() {
   3
     // Launch Facebook login
   4
     FB.login(
   5
       function (response) {
   6
         // Since you are using Twilio's APIs, you do not need to do anything with the response here.
   7
       },
   8
       {
   9
         config_id: "KEEP_IN_QUOTES_BUT_REPLACE_WITH_YOUR_CONFIG_ID",
   10
         auth_type: "rerequest", // Avoids 'user is already logged' in errors if users click the button again before refreshing the page
   11
         response_type: "code",
   12
         override_default_response_type: true,
   13
         extras: {
   14
           sessionInfoVersion: 3, // Required to get WABA ID
   15
           setup: {
   16
             solutionID: "KEEP_IN_QUOTES_BUT_REPLACE_WITH_YOUR_SOLUTION_ID" // This is the Partner Solution ID
   17
           }
   18
         }
   19
       }
   20
     );
   21
   }

4. Now, when your customers close the Embedded Signup window, we need to add a listener to the page to capture the session information that Meta will return.

   Copy code block

   1
   // Define session handler
   2
   const embeddedSignupInfoListener = (event) => {
   3
     if (!event.origin.endsWith('facebook.com')) return;
   4
     try {
   5
           const data = JSON.parse(event.data);
   6
           if (data.type === 'WA_EMBEDDED_SIGNUP') {
   7
             
   8
             // if user finishes the Embedded Signup flow
   9
             if (data.event === 'FINISH' || data.event === 'FINISH_ONLY_WABA') {
   10
               const {phone_number_id, waba_id} = data.data;
   11
               console.log('Phone number ID ', phone_number_id, ' WhatsApp business account ID ', waba_id);
   12
         
   13
             // if user cancels the Embedded Signup flow
   14
             } else if (data.event === 'CANCEL') {
   15
               const {current_step} = data.data;
   16
               console.warn('Cancel at ', current_step);
   17
   
   18
             // if user reports an error during the Embedded Signup flow
   19
             } else if (data.event === 'ERROR') {
   20
               const {error_message} = data.data;
   21
               console.error('error ', error_message);
   22
             }
   23
           }
   24
         } catch {
   25
           console.log('Non JSON Responses', event.data);
   26
         }
   27
   };
   28
   
   29
   
   30
   // Listen for Embedded Signup events
   31
   window.addEventListener('message', embeddedSignupInfoListener);
   32
   
   33
   
   34
   // When the user navigates away from the page, remove the event listener
   35
   window.addEventListener('beforeunload', () => 
   36
     window.removeEventListener('message', embeddedSignupInfoListener)
   37
   );

5. It's okay to leave that console.log statement for now; we'll come back to it.

It's a good time now to test the Embedded Signup flow.

To make sure your Partner Solution (solutionID) is working correctly, you should notice that when you go through Embedded Signup, it displays that your company is working with Twilio to enable your customers on WhatsApp during the pop-up window flow. This is required by Meta's legal team and can't be removed.

Using the default Embedded Signup configuration, when the Embedded Signup window opens, your customers will do the following:

1. Create or select their Meta Business Portfolio
2. Create their WhatsApp Business Account (WABA)
3. Enter a phone number and their WhatsApp Display Name
4. Verify phone number ownership by entering a one-time passcode (OTP) sent via SMS or a voice call

However, if you've purchased Twilio SMS-capable phone numbers for your customers to use with WhatsApp, it's against Twilio policy to display OTPs within your account. As a result, Twilio's Senders API will handle steps 3 and 4 automatically when you make the API call to create the WhatsApp Sender, and you need to turn off those steps within Embedded Signup.

If you are using a combination of Twilio SMS-capable phone numbers, as well as Twilio voice-only numbers or non-Twilio numbers (i.e., BYON), then you will need to configure Embedded Signup conditionally based on the type of phone number the client business chooses.

To configure Embedded Signup to not prompt your customers to provide a phone number and skip those steps, update where you make your FB.login call to include featureType: 'only_waba_sharing' like so:

Meta has a feature that allows you to add in details about the customer's business if you have already collected that information. This can speed up the onboarding process for your customers.

Customers can still edit the data that you prefill, if necessary.

Review Meta's documentation and make sure you thoroughly test any changes. Also, remember that the Embedded Signup feature is provided by Meta and not Twilio, and our support teams may not always be able to assist when troubleshooting the Embedded Signup integration.

Finally, note how Meta only returns the phone_number_id when the user completes the Embedded Signup flow:

1
const embeddedSignupInfoListener = (event) => {
2
  if (!event.origin.endsWith('facebook.com')) return;
3
  try {
4
        const data = JSON.parse(event.data);
5
        if (data.type === 'WA_EMBEDDED_SIGNUP') {
6
          
7
          // if user finishes the Embedded Signup flow
8
          if (data.event === 'FINISH' || data.event === 'FINISH_ONLY_WABA') {
9
            const {phone_number_id, waba_id} = data.data;
10
            console.log('Phone number ID ', phone_number_id, ' WhatsApp business account ID ', waba_id);
11
      
12
          // if user cancels the Embedded Signup flow
13
          } else if (data.event === 'CANCEL') {
14
            const {current_step} = data.data;
15
            console.warn('Cancel at ', current_step);
16

17
          // if user reports an error during the Embedded Signup flow
18
          } else if (data.event === 'ERROR') {
19
            const {error_message} = data.data;
20
            console.error('error ', error_message);
21
          }
22
        }
23
      } catch {
24
        console.log('Non JSON Responses', event.data);
25
      }
26
};

The Twilio Senders API requires a phone number in E.164 format. As a result, if you are allowing your customers to choose the phone number—no matter the type—they wish to register on WhatsApp, you will need to collect it from your customers outside of the Embedded Signup flow. This can be done prior to launching the Embedded Signup flow or after, as long as it is collected before making the call to the Twilio Senders API.

Once you have the WABA ID from the embeddedSignupInfoListener function and the phone number in E.164 format, pass these parameters to your backend to register the WhatsApp Sender.

• Create a subaccount for each new business using the Accounts API docs. Each subaccount will be mapped to a WABA.
• Use the Twilio Senders API to connect new WABAs to new subaccounts and register phone numbers with WhatsApp.

When your customer onboards to WhatsApp for the first time, they will create a new WABA as part of the Embedded Signup flow. Each WABA needs to be connected to separate Twilio subaccounts.

Once your customer already has a WABA using your Embedded Signup integration, they should reuse the same WABA when onboarding additional WhatsApp Senders (e.g., phone numbers).

If you're not already familiar with Twilio subaccounts, you can learn more in the Accounts API docs.

1. Create a subaccount using the example below if you don't already have a subaccount for this customer. Make sure to replace the FriendlyName with your customer's company name. Use your main Twilio account (e.g., parent account) credentials to make this request.

   Create a subaccount

   Copy code block

   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 createAccount() {
   11
     const account = await client.api.v2010.accounts.create({
   12
       friendlyName: "Owl, Inc.",
   13
     });
   14
   
   15
     console.log(account.authToken);
   16
   }
   17
   
   18
   createAccount();

   Output

   Copy output

   1
   {
   2
     "auth_token": "auth_token",
   3
     "date_created": "Thu, 30 Jul 2015 20:00:00 +0000",
   4
     "date_updated": "Thu, 30 Jul 2015 20:00:00 +0000",
   5
     "friendly_name": "Owl, Inc.",
   6
     "owner_account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   7
     "sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
   8
     "status": "active",
   9
     "subresource_uris": {
   10
       "available_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AvailablePhoneNumbers.json",
   11
       "calls": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls.json",
   12
       "conferences": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Conferences.json",
   13
       "incoming_phone_numbers": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/IncomingPhoneNumbers.json",
   14
       "notifications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications.json",
   15
       "outgoing_caller_ids": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/OutgoingCallerIds.json",
   16
       "recordings": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Recordings.json",
   17
       "transcriptions": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Transcriptions.json",
   18
       "addresses": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Addresses.json",
   19
       "signing_keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SigningKeys.json",
   20
       "connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ConnectApps.json",
   21
       "sip": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SIP.json",
   22
       "authorized_connect_apps": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AuthorizedConnectApps.json",
   23
       "usage": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Usage.json",
   24
       "keys": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Keys.json",
   25
       "applications": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Applications.json",
   26
       "short_codes": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/SMS/ShortCodes.json",
   27
       "queues": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Queues.json",
   28
       "messages": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages.json",
   29
       "balance": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Balance.json"
   30
     },
   31
     "type": "Full",
   32
     "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
   33
   }

2. The newly created subaccount's AccountSid and AuthToken will be returned in the response. Save this in your database to use for this customer. You will also use these credentials in the next step when calling the Twilio Senders API to register your customer's phone numbers on WhatsApp.

1. Use the WABA ID and phone number passed from your frontend and, with the subaccount's Account SID and Auth Token, call the Twilio Senders API with the following fields:

   • sender_id: provide the phone number that you are registering in E.164 format.
   • waba_id: provide the WABA ID if this is the first number for the customer. This will connect it to the subaccount. Note that once a WABA ID has been mapped to a subaccount, it will stay connected unless all WhatsApp Senders have been deleted from the account. You don't need to provide it when registering additional Senders in the same subaccount.
   • callback_url, callback_method, fallback_url, fallback_method, and status_callback_url: these webhooks are used for inbound messages and message statuses (not for the Sender's status). Note that status callbacks only support HTTP POST.
   • profile.name is only required when using a Twilio SMS-capable number; otherwise, Twilio will use the one provided by your customer during the Embedded Signup flow and ignore this field. Even when testing, the display name must comply with Meta's WhatsApp display name guidelines.
   • Other fields are optional.
   Copy code block

   1
   ## Create Sender
   2
   curl -X "POST" "https://messaging.twilio.com/v2/Channels/Senders" \
   3
     -H "Content-Type: application/json; charset=utf-8" \
   4
     -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
   5
     -d $'{
   6
     "sender_id": "whatsapp:+15017122661",
   7
     "configuration": {
   8
       "waba_id": "12345678912345"
   9
     },
   10
     "profile": {
   11
       "address": "101 Spear Street, San Francisco, CA",
   12
       "emails": [
   13
         "support@twilio.com"
   14
       ],
   15
       "vertical": "Other",
   16
       "logo_url": "https://www.twilio.com/logo.png",
   17
       "description": "We\'re excited to see what you build!",
   18
       "about": "Hello! We are Twilio.",
   19
       "name": "Twilio",
   20
       "websites": [
   21
         "https://twilio.com",
   22
         "https://help.twilio.com"
   23
       ]
   24
     },
   25
     "webhook": {
   26
       "callback_method": "POST",
   27
       "callback_url": "https://demo.twilio.com/welcome/sms/reply/"
   28
     }
   29
   }'

   Output

   Copy output

   1
   {
   2
       "status": "CREATING",
   3
       "sender_id": "whatsapp:+15017122661",
   4
       "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   5
       "configuration": {
   6
         "waba_id": "12345678912345"
   7
       },
   8
       "profile": {
   9
         "about": "Hello! This is Twilio's official account.",
   10
         "name": "Twilio",
   11
         "vertical": "Other",
   12
         "websites": [
   13
           {
   14
             "website": "https://twilio.com",
   15
             "label": "Website"
   16
           },
   17
           {
   18
             "website": "https://help.twilio.com",
   19
             "label": "Website"
   20
           }
   21
         ],
   22
         "address": "101 Spear Street, San Francisco, CA",
   23
         "logo_url": "https://www.twilio.com/logo.png",
   24
         "emails": [
   25
           {
   26
             "email": "support@twilio.com",
   27
             "label": "Email"
   28
           }
   29
         ],
   30
         "description": "We're excited to see what you build!"
   31
       },
   32
       "webhook": {
   33
         "callback_method": "POST",
   34
         "callback_url": "https://demo.twilio.com/welcome/sms/reply/"
   35
       },
   36
       "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   37
       "properties": null
   38
     }

2. The Senders API registers WhatsApp Senders asynchronously. When you make the POST call above to create the WhatsApp Sender, the Sender's SID will be returned. WhatsApp Sender SIDs will start with XE.

3. To check if the WhatsApp Sender has been successfully registered and is online, make a request to fetch the WhatsApp Sender's current status:

   Copy code block

   1
   ## Fetch Sender
   2
   curl -X "GET" "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
   3
        -H "Content-Type: application/json; charset=utf-8" \
   4
        -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN"

   Output

   Copy output

   1
   {
   2
     "status": "ONLINE",
   3
     "sender_id": "whatsapp:+15017122661",
   4
     "sid": "XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   5
     "configuration": {
   6
       "waba_id": "12345678912345"
   7
     },
   8
     "profile": {
   9
       "about": "Hello! This is Twilio's official account.",
   10
       "name": "Twilio",
   11
       "vertical": "Other",
   12
       "websites": [
   13
         {
   14
           "website": "https://twilio.com",
   15
           "label": "Website"
   16
         },
   17
         {
   18
           "website": "https://help.twilio.com",
   19
           "label": "Website"
   20
         }
   21
       ],
   22
       "address": "101 Spear Street, San Francisco, CA",
   23
       "logo_url": "https://www.twilio.com/logo.png",
   24
       "emails": [
   25
         {
   26
           "email": "support@twilio.com",
   27
           "label": "Email"
   28
         }
   29
       ],
   30
       "description": "We're excited to see what you build!"
   31
     },
   32
     "webhook": {
   33
       "callback_method": "POST",
   34
       "callback_url": "https://demo.twilio.com/welcome/sms/reply/"
   35
     },
   36
     "url": "https://messaging.twilio.com/v2/Channels/Senders/XEXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
   37
     "properties": {
   38
       "messaging_limit": "1K Customers/24hr",
   39
       "quality_rating": "HIGH"
   40
     }
   41
   }

4. When the Sender's Status shows as ONLINE, you can then use Twilio's APIs to send and receive messages.

It's time to move into production and onboard your first customer! Make sure that you set your App Mode to Live in your Meta App Dashboard and that your production URLs have been added to your Meta app in your app's Facebook Login for Business settings section.

Congrats! Don't forget to let the Twilio WhatsApp onboarding team know you successfully completed the flow, so they can close out your ticket.