Key Concepts and Terms for the WhatsApp Business Platform with Twilio

WhatsApp regulates when and how you can send messages to your end users. When an end user sends your business a WhatsApp message, that message 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. Create and submit templates for WhatsApp approval using Content Templates. When you create a template, you'll get a unique Content SID, which you use in your application code to send messages outside of the customer service window.

From July 1, 2025, Utility template messages don't incur any Meta fees if you send them during a customer service window. Authentication and Marketing template messages continue to incur fees during the customer service window. For more information on how the customer service window affects WhatsApp pricing, see Twilio's WhatsApp pricing FAQ.

In some cases, you need to use a message template to send WhatsApp messages. The following table summarizes when a message template is required, whether it needs WhatsApp approval, and example message types for each scenario:

Message template examples:

• "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."

Note: The double-bracketed numbers are placeholders for your custom values. In your code, provide these values as key-value pairs. For example, if you use the Appointment Reminders template, {"1":"2025/7/15","2":"3:00p.m."} will show "Your appointment is coming up on 2025/7/15 at 3:00p.m.".

To create message templates and submit them for approval, use the Content Template Builder or Content API. For more information, see Send WhatsApp notification messages with templates and Message template approval and statuses.

The Twilio Sandbox for WhatsApp comes with pre-approved templates for testing purposes. For more information, see Test WhatsApp messaging with the Sandbox.

WhatsApp requires you to classify message templates into one of three categories that determine pricing and approval requirements:

• Authentication: Authenticate users with one-time passcodes. Meta determines the body text, and you can't change it.
• Utility: Share important information related to a specific, agreed-upon transaction by confirming, suspending, or changing a transaction or subscription.
• Marketing: Send promotional offers, product announcements, and more to increase awareness and engagement. Meta classifies any template with a mix of utility and marketing content as a marketing template.

Meta bases its message fees on template categories and determines categories at its sole discretion. Any templates that don't result from an explicit end user request will likely be categorized as "Marketing".

Learn more about Meta's template categorization and WhatsApp pricing.

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.