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 Max Price enables dynamic, auction-based pricing for MARKETING category message templates. Instead of paying a fixed rate per country or message, you submit a bid_amount. Meta then determines a clearing price for each delivery attempt. The clearing price is always less than or equal to your bid.

Max Price removes the marketing frequency caps that normally limit how often you can contact a specific WhatsApp user. By raising or lowering your bid_amount, you can:

• Reach a larger portion of your target audience.
• Observe how different bids affect delivery rates.
• Control overall campaign spend by analyzing delivery-versus-cost trade-offs.

Include a bid_amount when you create a new MARKETING template. The value represents the maximum amount you are willing to pay per 1,000 message deliveries. Express the value in the smallest unit of the WABA currency (for example, cents for USD).

You can edit the bid_amount without resubmitting the template for Meta approval.

Note: Twilio currently supports bid changes only on the content template itself.

Dynamic billing requires the currency on your Twilio account to match the currency on the WhatsApp Business Account (WABA).

Set the bid_amount parameter in your content template.

bid_amount is the maximum price per 1,000 deliveries, expressed in the smallest unit of your WhatsApp Business Account (WABA) currency (for example, cents, centavos, or pence).

Calculation shortcut
Multiply the target per-message rate by 100,000:

• Formula: bid_amount = target per-message rate × 100,000
• Example: A target rate of US $0.05 per message yields 0.05 × 100,000 = 5,000.

Use the following table to map common fixed rates to bid_amount values while keeping the deliverability characteristics of Max Price.

The bid_amount figures are derived from Meta's fixed marketing rates published in July 2026. Adjust the values upward or downward to match your reach and budget goals.

All values are shown in USD cents per 1,000 deliveries.

Because auction pricing varies by user, you can estimate campaign spend with Meta's Reach Estimation tool through Twilio's MessageCostEstimate API.

Provide:

• Target country
• Look-back window (1, 7, 14, or 28 days)
• Desired bid_amount

The API returns estimates for 1,000 targeted users:

• Deliveries (lower and upper bounds): projected messages delivered.
• Cost (lower and upper bounds): projected spend for those deliveries.

Evaluating these ranges helps you find a bid that balances reach and cost before you launch a campaign.

Pricing is fully dynamic. Meta calculates a real-time per-user clearing price based on market conditions and your bid_amount. You are charged this clearing price, which will always be less than or equal to your maximum bid.

No. Currency settings on existing Twilio accounts and WABAs are permanent. To move to a supported currency (for example, from JPY to USD), you must create a new Twilio account and provision a new WABA in the target currency.

Automatic WABA currency upgrades for non-USD Twilio accounts begin in mid-October 2026. During this update, your WhatsApp Business Account (WABA) currency will automatically transition to match the currency of your Twilio account. For USD Twilio accounts, Max Price becomes an optional feature in mid-October 2026.

• Price stability: Invoices are issued in your local account currency, which removes foreign-exchange fluctuations.
• Flexible messaging: Enables Max Price dynamic bidding while still supporting fixed-rate messaging through the Marketing Messages API.

To use Marketing Messages API features such as Max Price and fixed-rate messaging, you must accept Meta's Marketing Messages API Terms of Service (ToS). Until you accept the ToS, you can continue to send marketing template messages at fixed rates through Cloud API.

Accept the ToS

1. Log in to Meta Business Manager with an account that has full control over your business portfolio.
2. Open WhatsApp Manager > Overview.
3. In the Alerts section, select Accept terms to start the Marketing Messages API (MM Lite) onboarding process.
4. Follow the on-screen instructions to complete the agreement.

Note: You can also accept the MM API ToS when you onboard a new sender in ESU v4.

If you wish to opt out of the automatic currency upgrade, you must do so by September 30, 2026.

• When to consider opting out: Only opt out if you explicitly do not want local currency billing for your WABA.
• Twilio Recommendation: Twilio strongly recommends accepting this upgrade to prepare for upcoming Meta platform requirements. Upgrading enables Max Price access while allowing you to continue using fixed rates on either the Cloud API or MM API, all while benefiting from local currency stability.

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 continue to message users by phone number, your workflow is unchanged. Authentication messages also still require phone numbers. If you receive only a BSUID from a user, you can request them to share their phone number if you prefer to message users with a phone number. You can do so using the Request Contact Info button.

In addition to receiving BSUID in inbound webhooks, you are also able to message a user via their BSUID (for example To=whatsapp:US.1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R9S0T ).

If you use Twilio Event Streams, make sure that you have upgraded to the latest version so that BSUID data appears.

Depending on how you handle inbound and outbound messages, BSUID data appears in the following fields:

Note: Twilio updates the delivered and read statuses for both webhooks and Event Streams. When available, pricing callbacks include the same status information.

Meta assigns parent BSUIDs to portfolios that it manages directly. If your business is not Meta-managed or you do not meet Meta's eligibility requirements, skip this section.

If you need a parent BSUID, contact Twilio Support and include Parent BSUID Request in the subject line.

To qualify for a parent BSUID, you must meet all of the following requirements. Meta may change these requirements at any time and might impose additional criteria.

• Each portfolio is business-verified.
• Each portfolio has a messaging limit of at least 100,000 messages in a 24-hour period.
• All portfolios are in good standing with no active policy violations.
• You link at least two business portfolios.

A regular BSUID applies to a single business portfolio. Any phone number in that portfolio can use the BSUID, but the identifier does not work with phone numbers in other portfolios. If you operate multiple portfolios, you cannot use a regular BSUID to identify the same user across all of them.

To remove this limitation, Meta provides parent BSUIDs for businesses with linked portfolios:

• A parent BSUID works across all linked portfolios.
• You can identify and message the same user from any business phone number in those portfolios.
• To confirm whether you can link portfolios, contact your Meta point of contact.
  If your account is not Meta-managed, you do not have a Meta representative, or you do not meet the eligibility requirements listed above, this feature does not apply to you.

When portfolios are linked, parent BSUIDs appear in webhooks in the ParentExternalUserId field.
The format matches a regular BSUID but inserts ENT between the country code and the identifier, for example:

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

You can use a parent BSUID anywhere you use a regular BSUID.
Existing portfolio-scoped BSUIDs continue to work.

When a parent BSUID is present, Twilio uses it instead of a regular BSUID. If a parent BSUID is enabled for your portfolio, it appears in the to and from fields when no phone number is present.

Note: Contact books remain portfolio-scoped. If you link portfolios, add each user's phone number and BSUID to the contact book in every portfolio. Twilio and Meta do not sync contact data between portfolios.

Twilio is releasing this capability in phases:

To test:

1. After you start receiving inbound webhooks that contain ExternalUserId, update your inbound message handler to read this field.
2. When Meta enables outbound BSUID messaging for a country, pass the ExternalUserId value everywhere your integration currently expects a phone number. Until the rollout reaches your target region, continue supplying the phone number.
3. Verify that messages are delivered and that user identification functions as expected.

If you don't have users in the initial rollout countries, you can still test the feature with simulated data. For outbound testing, use the ExternalUserId as the To address when sending a message. To simulate an inbound event with a BSUID, take a real inbound webhook payload and replace the From value with the ExternalUserId.

Meta plans to roll out outbound BSUID messaging in phases. End-users in the United States might not deploy this messaging until GA expeceted in September. To test before then, use a phone number from a country included in the initial rollout period.

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

You can request a business username in WhatsApp Manager or Meta Business Suite. For detailed instructions, see the WhatsApp FAQ article Request a business username.

Meta is using a phased approach to achieve a global rollout by September 2026. To keep your integration compatible, update it as described in this guide.

In late June 2026, Meta told users worldwide that they could request a username. The request flow is available globally, but the feature is active only in the countries listed in the initial rollout (see the table below). Meta plans to activate the feature worldwide in September 2026. These dates are estimates and may change.

Rollout will occur in waves with groups of countries. Rollouts are ramped up within each group. Dates will be published when Meta finalizes timing.

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 has a 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 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.

You can access a user's WhatsApp username in addition to their BSUID. The fields below are for both webhooks and event streams. It contains the display name that the user configured in WhatsApp.

This value is informational only. It does not influence message routing or delivery. You can store the value in your internal systems (for example, databases or CRMs).

Depending on how you process inbound and outbound messages, the username data appears in the following fields:

Use the REQUEST_CONTACT_INFO action type with the twilio/call-to-action template to ask a user for their phone number when the conversation thread contains only their BSUID.

For details, see Content Types and twilio/call-to-action.

Flex and Conversations (classic) use a different approach to end-user identity than Programmable Messaging. There is no From field and no ExternalUserId field in the Conversations webhook model. Instead, end-user identity is carried by MessagingBinding.Address (on conversation and participant events) and Author (on message events).

The shape of these fields depends on your contact book configuration and your history with that end user. When a phone number-BSUID pairing exists, meaning you've had prior contact with that user, you receive the phone number: whatsapp:+15551234567. When no pairing exists, you receive the BSUID: whatsapp:US.ABC123XYZ. Both values arrive in the same fields.

Your integration receives messages regardless of contact book state. Participant identity has always been carried by these two fields. What changes is the type of possible values those fields contain. Any integration that stores, routes, or displays the value from MessagingBinding.Address or Author must treat identifier shape as variable. Code that assumes a phone number will be present, such as regex matching, E.164 parsing, phone-keyed lookups, or display formatting, will fail silently on BSUID values rather than visibly error.

The behavior of Studio depends on how you trigger the flow.

Programmable messaging triggers: Studio supports BSUID-identified users. When a user has a WhatsApp username and no prior contact with your business, the From field may carry a BSUID value (for example, whatsapp:US.ABC123XYZ) instead of a phone number. The BSUID is also available in the ExternalUserId webhook field. Studio maintains session continuity correctly in both cases.

If your flow reads From or ExternalUserId for downstream logic—such as customer lookup or display—update it to handle both phone number and BSUID formats.

Conversations triggers: Studio copies the Conversations webhook payload directly into the flow's execution context. This path doesn't include an ExternalUserId field. Identity is carried by MessagingBinding.Address and Author, the same fields used throughout Conversations. In Studio, these appear as {{trigger.conversation.MessagingBinding.Address}} and {{trigger.conversation.Author}}. Session continuity is unaffected, since Conversations uses a stable ConversationSid regardless of changes to either field.

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