Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Send WhatsApp Notification Messages with Templates



WhatsApp message templates overview

whatsapp-message-templates-overview page anchor

A WhatsApp message template is a message format that you can use over and over again to message users once they have opted-in and given your app permission to send them messages. To use a message template, you must first submit it to WhatsApp. Meta reviews and approves each message template to maintain high-quality content and avoid spam. Once WhatsApp has approved your template, you can use the message template to send notifications. For more info on WhatsApp's template approval process, please refer to this article.

Templates use placeholder values that can be replaced with dynamic content inside double curly braces ({{...}}) when the message is sent:

  • Your appointment for {{1}} is scheduled for {{2}}. Need to reschedule? Tap below to reply.
  • Example of a message sent using this template: Your appointment for your doctor's appointment is scheduled for Tuesday at 10AM. Need to reschedule? Tap below to reply.
  • Note that a single placeholder can contain multiple words.

Think of your template message as a conversation starter; the goal is to convert this initial message into a two-way conversation when the user replies. Two-way conversations are considered higher value because you are engaging with your end-user. In addition, they reduce your spend because WhatsApp does not charge for free-form outbound messages within the 24-hour session. For more information on pricing, please see our pricing page(link takes you to an external page).

Sending non-template messages within a 24-hour session

sending-non-template-messages-within-a-24-hour-session page anchor

If a WhatsApp user has sent your application a message — whether it's a reply to one of your outbound messages, or they have initiated communication themselves — your application has a 24-hour window (sometimes called a "24-hour session") to send that user messages that don't need to use a template.

When your application sends a message to a WhatsApp user outside a 24-hour session, the message must use an approved template.

Starting June 1, 2023, WhatsApp maintains separate 24-hour windows depending on the category of the template used to start the conversation. For example, if you already opened a 24-hour window using one template category, then a template of a different category would open up a second, separate 24-hour window.

Templates pre-registered for the Sandbox

templates-pre-registered-for-the-sandbox page anchor

Twilio has pre-provisioned for the following templates for use in the WhatsApp Sandbox(link takes you to an external page):

  • Your {{1}} appointment is coming up on {{2}}. Get ready!
  • Your {{1}} order of {{2}} has shipped and should be delivered on {{3}}. Details : {{4}}. Let us know if you have any questions.

For more information, read our guide to getting started with the Twilio Sandbox for WhatsApp.


WhatsApp notification categories

whatsapp-notification-categories page anchor

Your WhatsApp message templates must fall into one of the following categories. Please note that the categories "One-time password" and "Transactional" have been renamed to "Authentication" and "Utility", respectively.

  • Authentication: Authenticate users with one-time passcodes. The body text is determined by Meta cannot be changed.
  • Utility: Share important information related to a specific, agreed-upon transaction and accomplish one of the following: confirm, suspend, or change a transaction or subscription.
  • Marketing: Send promotional offers, product announcements, and more to increase awareness and engagement. Any template that has a mix of utility and marketing content will be classified by Meta as a marketing template.

As of June 1, 2023, Meta's fees for business-initiated conversations is now defined by the category of the template used to start the conversation. Any templates that do not clearly result from an explicit end-user request will likely be categorized by Meta as "Marketing". Learn more in our pricing page(link takes you to an external page). Please refer to Meta's docs(link takes you to an external page) for examples and the latest details on Meta's template categorization rules. Meta determines template categories at their sole discretion.


Creating message templates and submitting them for approval

creating-message-templates-and-submitting-them-for-approval page anchor

Customers interested in sending notifications outside of the 24-hour window need to create their own templates for these messages.

WhatsApp Templates vs. Content Templates

whatsapp-templates-vs-content-templates page anchor

Twilio currently offers two ways to manage and use templates: WhatsApp templates and Content Templates. Content Templates are message templates that can be used on any channel, including WhatsApp. They offer more flexibility, but require some additional setup before you can get started. To launch quickly, we recommend using WhatsApp Templates. This guide explains how to use WhatsApp Templates. As you are scaling your solution, we suggest considering integrating Content Templates into your workflow. Learn more about Content templates here.

Content TemplatesWhatsApp Templates
Supported channelsWhatsApp, SMS, MMS, Facebook MessengerWhatsApp
Sending messagesSending requires use of a ContentSid fieldUse the Body field to send
Messaging ServiceRequiredOptional
Rich feature supportLatest rich features support by Twilio, such as lists, media templates and dynamic buttonsStatic quick replies and CTA buttons only
API to manage templatesContent APIN/A
UI to manage templatesContent Editor In the Twilio Console, go to Messaging > Content EditorWhatsApp Templates In the Twilio Console, go to Messaging > Senders > WhatsApp Templates

Set up WhatsApp message templates in your Twilio account

set-up-whatsapp-message-templates-in-your-twilio-account page anchor

To create a WhatsApp template, go to Twilio Console > Messaging > Senders > WhatsApp Templates(link takes you to an external page). Click on Submit a message template:

New Message Template.

Note: If you are not creating a template for the first time, you will see the New message template button. Click it to create additional templates.

On the next screen, you will be able to fill out information to submit to WhatsApp. WhatsApp's team uses the information you submit to approve or reject your template submission.

  • Template name: Must be a unique name and can only contain lowercase alphanumeric characters and underscores. Tip Use a name that helps WhatsApp's reviewer understand the purpose of your message, for example "order_delivery" rather than "template_1"
  • Template category: You must select the category that matches WhatsApp's definition. See Meta's docs(link takes you to an external page) for definitions and examples. Authentication templates have special constraints. ( See below. )
  • Message language: Select from the languages provided by WhatsApp.
  • Message body: The text of the message that you want to send. Please note WhatsApp does not allow multiple sequential line breaks.
  • Buttons: You can choose either Quick reply or Call to action buttons. Each button needs to contain text of no more than 20 characters (emojis, newlines, and underscores are not allowed). Placeholders are not supported in button text.

    • Choose "Quick replies" to predefine button responses that users can easily tap to respond. WhatsApp allows a max of 3 quick reply buttons.
    • Choose "Call to action" to generate buttons that trigger a phone call or open a website when tapped. You can add a max of 2 CTA buttons. Note : The 2 CTA buttons need to be unique; 1 button can trigger a phone call and 1 button can open a website. They cannot both trigger the same action.
wa-templates-save.

After you fill out the message template, click Save template for WhatsApp approval.

If your template includes placeholders (e.g. "Hello {{1}}! We've received your request regarding {{2}}."), a modal will appear for you to add sample content for each placeholder. Enter in sample text for each placeholder and then click Save and submit to submit your template to WhatsApp.

WhatsApp Placeholder Sample Submission.

Note: Once you submit a template, it cannot be edited through the Twilio console.

Please refer to the WhatsApp documentation to learn more about message template formatting and supported languages(link takes you to an external page).

Authentication Templates

authentication-templates page anchor

When creating a template with the category of Authentication (i.e. Authentication Templates) using WhatsApp Templates, certain restrictions apply to comply with WhatsApp's policies:

  1. The body text of the template is set by WhatsApp for every language and is not editable.
  2. A "Copy Code" button is required which users can use to copy the one time passcode. The button label is editable per language.

Content Templates provide additional flexibility when creating Authentication Templates. See more here.

Twilio supports multiple translations per template. If you need the same template in different languages, click Add template translation on an individual template's view in the console. Translations have a higher chance of approval if submitted together.

Note: WhatsApp Templates does not support editing or deleting individual translations within a template. If you need to delete individual translations, please use the Content Templates instead.

Removing WhatsApp message templates

removing-whatsapp-message-templates page anchor

To delete a message template, click on the template name on the WhatsApp Message Templates page and then click Delete at the bottom on the page.

Per WhatsApp guidelines, you may not reuse the name of a deleted template for 30 days after deletion.

(information)

Info

WhatsApp now supports up to 6000 template translations in total, across all templates, per account. Previous limits of 250 and 1500 templates no longer apply.

Submitting templates for approval to WhatsApp

submitting-templates-for-approval-to-whatsapp page anchor

Most templates submitted to WhatsApp for approval are reviewed within minutes. To learn more about WhatsApp's approval process, and for additional tips and tricks, please refer to this article.


Send a WhatsApp message using a template

send-a-whatsapp-message-using-a-template page anchor

Twilio supports sending messages with WhatsApp message templates without requiring a change in how you use the Twilio Programmable Messaging API.

To send a templated message, include the full body of the message in the API call. Twilio will send the message as a templated message if it matches one of the approved templates. If the body does not match a pre-registered template, the message will be sent as a freeform message. This means it may not deliver if it is outside a 24-hour session.

For example, if your approved template is:


_10
Hi {{1}}! Thanks for placing an order with us. We'll let you know once your order has been processed and delivered. Your order number is {{2}}. Thanks

in the Body parameter of the message resource, you would write the following, replacing the {{1}} placeholder with the end-user's information:


_10
Body=“Hi Joe! Thanks for placing an order with us. We'll let you know once your order has been processed and delivered. Your order number is O12235234. Thanks”

Twilio also supports sending template messages by referencing the template ID. This is available through Twilio's omnichannel Content Templates (Beta).

Send a WhatsApp message using a message template

send-a-whatsapp-message-using-a-message-template page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.messages
_14
.create({
_14
from: 'whatsapp:+15005550006',
_14
body: `Hi, Joe! Thanks for placing an order with us. We'll let you know once your order has been processed and delivered. Your order number is O12235234. Thanks`,
_14
to: 'whatsapp:+14155238886'
_14
})
_14
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "Hi, Joe! Thanks for placing an order with us. We'll let you know once your order has been processed and delivered. Your order number is O12235234. Thanks",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "whatsapp:+15005550006",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "whatsapp:+14155238886",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}

Encountering Error Code 63016

encountering-error-code-63016 page anchor

Twilio's Error 63016 indicates that you are making an attempt to send a freeform message when there's no conversation set with that user. This may happen if your text does not exactly match the text from the approved template. Please make sure that you use a diff tool to check for any differences between the approved template and the content being sent, including extra spaces or newlines. If you need to change the template to match your needs, please submit a new template. If you are seeing a different error code and you believe it is related to templates, please open a support ticket, and we will help you understand why this is happening.

Including new lines and escape characters in your templates

including-new-lines-and-escape-characters-in-your-templates page anchor

If you are rendering new lines or other escaped characters, you will need to encode the linebreaks properly based on the language you are using. The Twilio Console may show line breaks and other escaped characters in their raw form, such as \n. However, if your message body shown on Twilio has "\n" visible in the body contents, you need to check your code to ensure you pass an actual line break character to Twilio.

For example, here's a message template with line breaks:


_10
Hello! This is a notification message from [Your Company].\nWe wanted to inform you about an important update:\n[Message Content].\nThank you!

If you are using cURL, you will need to use the following syntax, $'Body=Hello \n world!' with single quotes ($'...') to send newlines. Here is a full example:


_10
curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
_10
--data-urlencode 'To=whatsapp:+15005550006' \
_10
--data-urlencode 'From=whatsapp:+14155238886' \
_10
--data-urlencode $'Body=Hi, there.\nWelcome to ALVIN instant servicing.\n\nKindly provide your reference number to proceed' \
_10
-u ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token


Initiate the 24-hour window with a generic template

initiate-the-24-hour-window-with-a-generic-template page anchor

As a developer, you may want to send different types of notifications and messages to your users. However, it's difficult and inefficient to go through the template approval process described above for every type of message that you wish to send to your end-users.

For example, let's say you want to send out a time-sensitive message to all of your end-users, such as "Today, we are having a company-wide announcement at 11am." It is unlikely that WhatsApp will approve this template, which makes it challenging to build a real notification flow.

To work around this problem, you can create a generic template that asks your end-users to respond. An example of generic notification template that you can submit for approval is:

"Hello {{1}}, we have a new update regarding your account. Please respond to this message to receive it. Have a nice day!"

Once an end-user replies to this templated message, it initiates the 24-hour session, during which your business can send free-form messages.


Monitoring Live Templates

monitoring-live-templates page anchor

Once you start using your templates, it's important to monitor them for excessive negative user feedback.

Paused & Disabled Templates

paused--disabled-templates page anchor

If end users are repeatedly giving blocking or reporting spam in association with a message template, WhatsApp will pause the template for a period of time to protect the quality rating of senders that have used the template. Pausing durations are as follows:

  • 1st Instance: Paused for 3 hours
  • 2nd Instance: Paused for 6 hours
  • 3rd Instance: Disabled

When a template is paused a third time it will instead be permanently disabled. Messages sent using paused or disabled templates will fail. Paused and disabled message templates that are attempted to be sent do not count against the daily messaging limit.

Getting Alerts for Paused, Disabled and Rejected Templates

getting-alerts-for-paused-disabled-and-rejected-templates page anchor

Twilio can send a notification using Twilio Alerts when a template status changes to "paused", "disabled" or "rejected". To get notified, create an alert for error 63041 (paused), 63042 (disabled) and/or 63040 (rejected).


Ready to create your own WhatsApp templates? Head over to the Twilio Console(link takes you to an external page) to get started.


Rate this page: