SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Rules and Best Practices for WhatsApp Messaging on Twilio

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

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

Every new WhatsApp-enabled Sender is initialized as being allowed 1000 business-initiated conversations with unique customers in a rolling 24-hour period. Due to these rate limits, Twilio recommends customers intending to initiate more than 1000 conversations with unique customers to gradually roll out their WhatsApp launch over the course of a week. In this context, a customer is a unique WhatsApp end user phone number. 

For more information, please see WhatsApp Rate Limiting.

Approved use cases

WhatsApp supports the following use cases:

  • Customer Care (Known as service conversations): 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 (non-template) messages. The conversation will remain open for 24hrs from the last message received from the user.
  • Utility: Confirm or suspend an existing transaction, change or update a transaction, account, billing, or payment notification
  • Authentication: Send codes that allow your customers to securely access their accounts.
  • Marketing/Promotional: Send promotional offers, product announcements, and more to increase awareness and engagement.

Using WhatsApp in production (WhatsApp-enabled numbers)

Notice: Every WhatsApp Business Account comes with a handful of sample templates (named as 'sample_shipping_confirmation' etc.). These should not be used for production traffic as they contain a footer that will display on the recipient device as "This message is from an unverified business." If the content of any of these templates matches a production template you'd like to submit, the sample template would need to be removed first. Alternatively you can submit a modified version the template that is tailored to your own business.

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.

Messaging limitations

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.

However, WhatsApp does have character limits for any template messages. WhatsApp template messages cannot contain more than 1,024 characters.

WhatsApp also applies limits to the number of messages that can be sent to their users. For more information, see WhatsApp Rate Limiting.

Template limitations 

  • Newlines are forbidden within placeholders. More information on this Facebook limitation here
  • No more than 4 consecutive spaces are allowed in message templates.

Related topics

Have more questions? Submit a request
We can’t wait to see what you build.
Powered by Zendesk