WhatsApp messages are subject to certain rules and restrictions that do not apply to standard Twilio Programmable SMS and MMS messages. For best results, it’s important to understand the concepts of “templates” and “sessions,” and design your messaging flow to follow WhatsApp’s rules.
Templates and Sessions
All messages sent from your WhatsApp number (or from the Twilio Sandbox) must follow a pre-approved template, unless the end user has messaged you first. After a user sends you a message, you have a 24-hour session to send session messages to that user. Session messages do not need to follow a template, and can include media attachments. The 24-hour session restarts each time that user sends you a new incoming message.
Using the WhatsApp Sandbox
When using the Sandbox, you have a few pre-approved message templates to choose from. To view the list of templates, and additional setup details, please see Getting Started with Twilio for WhatsApp (Beta).
Before you can send any messages to a WhatsApp user from your Sandbox, that user must first send a message to the Sandbox number with your unique join keyword. The join keyword for your Sandbox is displayed on the Twilio Sandbox page in Console.
Rolling Out your WhatsApp Twilio Application
Approved WhatsApp users are initially limited to 1,000 unique message recipients a day. Due to this rate limiting implementation, Twilio recommends customers intending to message with more than 1,000 unique users gradually roll out their WhatsApp launch over the course of a week. For more information, please see WhatsApp Rate Limiting.
Using WhatsApp in Production (WhatsApp-Enabled Numbers)
If your use case is approved by WhatsApp for use in production, you will be able use your own Twilio phone numbers, and submit your own message templates to WhatsApp for approval. WhatsApp production rules mirror those of the Twilio Sandbox; outbound messages must match your approved templates unless within a user-initiated session. Again, a session lasts 24 hours after the last incoming message you get from a specific user.
To be notified as WhatsApp further opens up approvals for using your own Twilio numbers and templates, sign up for updates here: Request to enable your Twilio numbers for WhatsApp.
To view pricing information for using WhatsApp, see our WhatsApp Pricing page. For a detailed explanation, please see New Pricing for the Twilio API for WhatsApp (Twilio Blog).
Opt-in and Opt-out with WhatsApp
Similar to SMS, you must receive explicit opt-in from end users before sending them a WhatsApp message. WhatsApp requires the opt-in to be active, which means that it can not be assumed: the end user must knowingly sign up to receive messages from your business. We recommend keeping a record of customer opt-ins.
If you are using the Twilio Sandbox to build and test, Twilio takes care of this for you by only allowing you to send messages to users who have joined your Sandbox.
When using WhatsApp in production, the following opt-in rules apply:
- Get an active opt-in from the user: Opt-in for your messages must be triggered by a user action. Examples include entering a phone number, or checking a box to indicate consent.
- Provide clear opt-in messaging: Users must be made aware of the type(s) of messaging they are signing up for.
Twilio and WhatsApp will monitor accounts for signs that these opt-in rules are being violated, and will ask you to demonstrate proof of opt-in if we see signs that users are being messaged without consent.
Twilio's platform has a 1,600 GSM character limit for a single API request. For more details, please see What is the Maximum Length for Messages Sent with Twilio Programmable Messaging.