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?

Key Concepts and Terms for the WhatsApp Business API with Twilio

When you use the WhatsApp Business API with Twilio, you connect with userson the world’s most popular messaging app, all with the power of the Twilio APIs.

WhatsApp is a highly-regulated channel, and getting started requires documentation and approval from Facebook. This document covers the common key concepts and terms that you will encounter when you use the WhatsApp Business API with Twilio.

The "24-hour window" or "24-hour session"

WhatsApp regulates when and how you can send messages with your end users. When an end user sends your business a WhatsApp message, it kicks off a 24-hour WhatsApp "session" or "window" during which you can send free-form (non-templated) messages to the user. A WhatsApp session lasts for 24 hours after the last inbound message you receive from a user.

Outside of a WhatsApp session, you may only send a message following a pre-approved template to the user. Any message that doesn't match a pre-approved template is considered a free-form message. For more information, please read below and reference our guide to using templated messages for WhatsApp notifications.

WhatsApp Notification Templates

Outside of the 24-hour WhatsApp session, your business can only send messages following pre-approved templates to your end users. Some of examples of these templated messages are:

  • "Your login code for {{1}} is {{2}}."
  • "Your {{1}} delivery is on the way. It should arrive {{2}}."

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 API with Twilio, you can submit templates for approval by WhatsApp. Please reference our guide to the approval process as well as how to send messages with WhatsApp notification templates.

In addition, the Twilio Sandbox for WhatsApp has three pre-approved templates that you can use to try out this functionality before your Twilio number has been approved to send WhatsApp messages.

WhatsApp Business Account (WABA)

A WhatsApp Business Account (WABA) is an account for your business to send and receive messages through the WhatsApp Business API. When you want to connect with your end users over WhatsApp using Twilio, we will create and manage a WABA on your behalf. This process is documented in the Connect your Twilio Number to your WhatsApp Business Profile guide.

Each Twilio account, subaccount, or project can only be associated with one WABA. However, WhatsApp imposes no limit as to how many WABAs a business can have.

Facebook Business Manager (FB BM)

In order to have a WhatsApp Business Account (WABA), your business must have a Facebook Business Manager (FB BM) account. Facebook Business Manager is a tool through which you organize and manage your business within the Facebook ecosystem. It is a separate concept from the WhatsApp Business Account (WABA)

Please consult Facebook’s instructions for creating a Business Manager account.

Facebook uses your FB BM to verify your business' identity through a process called "Business Verification."

Twilio needs your Facebook Business Manager ID for setting up a WABA on behalf of your business for sending and receiving WhatsApp messages.

Twilio Account, Account SID, Subaccount SID, and Project SID

In order to use the WhatsApp Business API with Twilio, you will need to sign up for a Twilio Account, which has a unique 34-digit identifier, called a "String Identifier" or "SID." (For more on SIDs, read our glossary page What is a String Identifier?)

Under your Twilio Account, you can purchase and configure your WhatsApp Senders, prototype using the Twilio Sandbox for WhatsApp, and submit

WhatsApp message templates for approval.

If you are an Independent Software Vendor (ISV) or third party operating on behalf of another business, you will likely use a Twilio Subaccount SID instead. If you are setting up with Twilio Flex, you will use a Flex project SID instead.

Twilio Sandbox for WhatsApp

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.

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.