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.
This guide covers the following topics:
- Templates and Sessions
- Using the WhatsApp Sandbox
- Rolling out your WhatsApp Twilio application
- Approved use cases
- Using WhatsApp in production (WhatsApp-enabled numbers)
- Opt-in and opt-out with WhatsApp
- Messaging limitations
Templates and Sessions
WhatsApp divides messages into two different types: Template messages and Session messages.
- Template messages: Outbound messages sent via Twilio that use one of the pre-approved templates. These are generally unsolicited transactional messages (delivery alerts, appointment reminders, etc.) sent to users who have opted in to receive messages from you.
- Session messages: All incoming messages, or outgoing replies to these messages within 24-hours. A messaging session starts when a user sends your application a message, and lasts for 24 hours from the most recently received message. Session messages do not need to follow a template, and can include media attachments.
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.
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.
Approved use cases
WhatsApp supports customer care, notifications, marketing/promotional and mixed use cases over Twilio.
- Customer Care is initiated with an inbound message from an end user. When the first message is received from the user, it opens a conversation, in which the business can reply back with Session messages (non-template). The conversation will remain open for 24hrs from the last message received from the user.
- Notifications use case is a uni-directional messaging service designed for the business to send alerts and informational notifications to users. Messages sent in this use case are required to use pre-approved Templates.
- Marketing/Promotional use cases are now allowed for all businesses globally.
- Mixed use case is initiated when a user replies to a notification message, thus starting a customer care use case.
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 How Much Does it Cost to Send and Receive WhatsApp Messages with Twilio.
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.
Opt-outs and WhatsApp
WhatsApp handles opt-outs natively by allowing users to "Block" a sender in the WhatsApp app. WhatsApp does not offer a way to be notified when a user has blocked your sender, or to retrieve a list of users who have blocked you. It is essential to follow the opt-in guidelines above, to minimize the chance of users blocking your sender.
In addition, you may use Advanced Opt-Out with Messaging Services to set up opt-out keyword handling (e.g. "STOP") for WhatsApp, similar to SMS. If your WhatsApp sender is in a Messaging Service with Advanced Opt-Out configured, all your keyword and response configurations will apply to your WhatsApp senders as well. You can then instruct your users to send a message with one of your configured opt-out keywords to unsubscribe.
You may choose to provide your users a convenient way to opt-out of WhatsApp messages, for example by toggling an option on your website, or by sending a specific keyword to your WhatsApp number.
Please note that if you are not using Advanced Opt-Out, Twilio's default, account-wide keyword-based opt-out handling system does not apply to WhatsApp senders on Twilio, these systems currently apply for SMS and MMS messaging only.
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.
WhatsApp also applies limits to the number of messages that can be sent to their users. For more information, see WhatsApp Rate Limiting.
- Newlines are forbidden within placeholders. More information on this Facebook limitation here
- No more than 4 consecutive spaces are allowed in message templates.