Key Concepts and Terms for the WhatsApp Business Platform with Twilio

WhatsApp regulates when and how you can send messages with your end users. When an end user sends your business a WhatsApp message, it starts a customer service window (also known as a 24-hour window) during which you can send free-form messages to the user. This customer service window lasts for 24 hours after the last inbound message you receive from a user.

Outside of a customer service window, you may only send a message using an approved template. Templates are created and sent for approval to WhatsApp using Content Templates. Once you've created a template, you will get a unique Content SID, which must be used in your application code to send messages outside of the customer service window. For more information, read below and reference our guide to using templated messages for WhatsApp notifications.

From July 1, 2025, Utility template messages do not incur any Meta fees if they are sent during a customer service window. Authentication and Marketing template messages will continue to incur fees during the customer service window. See Twilio's WhatsApp pricing FAQ to understand more about how the customer service window affects WhatsApp pricing.

Outside of the customer service window, your business can only send messages following pre-approved templates to your end users. Some examples of these templated messages are:

• "Your appointment for {{1}} is {{2}}. Need to reschedule? Tap below to reply."
• "Your {{1}} delivery is on the way. It should arrive {{2}}. If you have any questions, reach out."

In the above examples, {{1}} and {{2}} are the message-specific information for a given end user.

When you get started with the WhatsApp Business Platform with Twilio, you can submit templates for approval by WhatsApp. Learn how to send messages with WhatsApp templates.

A WhatsApp Business Account (WABA) is required to register a WhatsApp Sender and send and receive messages on WhatsApp using Twilio. All WhatsApp Senders and Templates must belong to a WABA.

There is a one-to-one relationship between a Twilio account, subaccount, or project and a WABA. In other words, you may only have one WABA in a Twilio account or subaccount, and each WABA should only be connected to a single Twilio account, subaccount, or project. This means that if you have multiple accounts, subaccounts, or projects, then you will need to have multiple WABAs.

WhatsApp does not limit how many WABAs a business can have.

In order to have a WhatsApp Business Account (WABA), your business must have a Meta Business Portfolio. A Meta Business Portfolio allows organizations to organize and manage all of their business assets (e.g., Facebook pages, Instagram accounts, and WhatsApp Business accounts) together. It is a separate concept from the WhatsApp Business Account (WABA).

Consult Meta's instructions for creating a Meta Business Portfolio account. You may also do this when registering your first WhatsApp Sender using WhatsApp Self Sign-up.

Meta uses your Meta Portfolio to verify your business's identity through a process called "Business Verification."

The Twilio Sandbox for WhatsApp is a tool created by Twilio for you to prototype and test sending and receiving WhatsApp messages before you are fully set up with a WABA and Twilio WhatsApp sender number. You can read more in our in-depth guide to getting started with the Twilio Sandbox for WhatsApp or our step-by-step Quickstart to WhatsApp.

WhatsApp supports usernames for individual users. A username masks the user's phone number and lets the user interact with businesses through a Business-scoped User ID (BSUID). Twilio exposes this identifier in the Messaging API as ExternalUserId.

Meta automatically generates a BSUID for each combination of business portfolio (formerly called Business Manager) and user. If the user changes their phone number, Meta regenerates the BSUID. A BSUID can contain up to 128 alphanumeric characters, excluding the country code. All message webhooks include the BSUID, whether or not the user has turned on usernames.

Twilio maps the BSUID to the ExternalUserId field in the Messaging API. When relevant, Twilio also appends the BSUID to the existing to and from parameters.

Example ExternalUserId values:

1
whatsapp:CC.1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T
2
whatsapp:CC.BSUID

In these examples, CC represents the two-letter country code, such as US for the United States or BR for Brazil.

The to and from parameters behave as follows:

• If a phone number is present, the to or from field contains only the phone number, and ExternalUserId contains the BSUID.
• If no phone number is present, Twilio populates the to, from, and ExternalUserId fields with the BSUID.

Note: Phone numbers are in E.164 format (for example, whatsapp:+18005550100).

Limitations on BSUIDs:

• All message types are supported except one-tap, zero-tap, and copy-code authentication templates, which require a phone number.
• A BSUID is valid only for the portfolio that generated it. If you operate multiple portfolios, a request that includes a BSUID from another portfolio fails.

If you message users with a phone number, the workflow continues to operate exactly as it does today. Authentication messages also continue to require phone numbers.

A business can assign one username to each WhatsApp phone number. A phone number can have only one username, and no two phone numbers—consumer or business—can share the same username.

Business usernames must meet the following requirements:

• Contain only English letters (a–z), digits (0–9), periods (.), or underscores (_).
• Be 3–35 characters long.
• Include at least one letter.
• Not start or end with a period and not contain two consecutive periods.
• Not start with www.
• Not end with a domain suffix (for example, .com, .org).
• Be case-insensitive (myID and myid are equivalent) but treat . and _ as distinct (my.id and my_id are different).

WhatsApp displays sender names in the chat window in the following priority order (highest to lowest):

1. Saved contact name
2. Verified business name or Official Business Account (OBA) name
3. Username
4. Phone number

Meta plans an initial rollout in June 2026, followed by a global rollout in August 2026. Make sure your integration is updated by early June 2026.

This list is subject to change by Meta.

Update your systems to store the new BSUID. Twilio returns the BSUID in the to and from parameters and in the ExternalUserId field.

Some WhatsApp messages might not include the user's phone number. If you receive only a BSUID, you still need a way to identify and communicate with that user. Store the BSUID with any existing identifiers so that you can map conversations correctly across your CRM, profile, or other data stores.

If you already have a phone number for a user, you can continue to use it. Treat the BSUID as an additional identifier for future interactions or for linking conversation history when a phone number isn't provided.

Onboarding and registration continue to use phone numbers. Usernames only affect the sender name displayed in WhatsApp, and they don't change onboarding or sender registration.

Meta plans to release a contact book feature that automatically stores WhatsApp user contact information (phone number and BSUID) when you exchange a message or call with that user.

After a contact is stored, the platform includes the user's phone number and BSUID in all webhook payloads and API responses, even if the user has enabled the WhatsApp usernames feature.

Meta retains contact book data until you either:

• Turn the feature off.
• Deactivate your Meta account.

Starting March 16, 2026, you can turn the contact book on or off in Meta Business Suite > Business settings > Business info. When you turn the feature off, Meta:

• Stops storing new user information.
• Deletes all previously stored user information.

If you turn the feature back on later, storage resumes, but deleted data isn't restored.

• Contact books are scoped to business portfolios. If you use linked portfolios, each portfolio stores contact information independently. The data isn't shared or synchronized across portfolios.

For more information, see Meta's documentation.

For information from Meta, see the Business-Scoped User IDs documentation. For Twilio-specific updates, monitor this page.