Skip to contentSkip to navigationSkip to topbar
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 create and submit it to WhatsApp using the Content Template Builder or Content API. 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 Content Template to send notifications. For more info on WhatsApp's template approval process, refer to this article.

Templates use placeholder values that can be replaced with dynamic content using Content Variables 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 10 AM. 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 nor Utility template messages within the 24-hour customer service window. For more information on pricing, see our pricing page(link takes you to an external page).

Sending free-form messages within a 24-hour customer service window

sending-free-form-messages-within-a-24-hour-customer-service-window 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 customer service window to send that user messages that don't need to use a template. This customer service window lasts for 24 hours after the last inbound message you receive from a user.

When your application sends a message to a WhatsApp user outside this window, the message must use an approved template.

Templates pre-provisioned for the Sandbox

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

Twilio has pre-provisioned Content Templates using each of WhatsApp's template categories for testing in the WhatsApp Sandbox(link takes you to an external page). The Sandbox guides you through using Content Templates and Content Variables and provides sample code snippets using Twilio SDKs.

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


WhatsApp template categories

whatsapp-template-categories page anchor

Your WhatsApp message templates must fall into one of the following categories.

  • Authentication: Authenticate users with one-time passcodes. The body text is determined by Meta and 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.

Meta bases their message fees on template categories. 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) and refer to our best practices(link takes you to an external page) for guidance on creating WhatsApp templates. 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

To send notifications outside of the customer service window, you need to create your own templates for these messages.

Content Templates are omnichannel templates and offer access to WhatsApp templates. Content Templates are message templates that can be used on any channel, including WhatsApp. They offer flexibility and help ensure your implementation remains compatible with future updates at Twilio. For more detailed information about Content Templates and how to use them with WhatsApp, refer to this page.

FeatureWhat is supported in Content Templates
Supported channelsWhatsApp, SMS, MMS, Facebook Messenger
Sending messagesSend messages with a ContentSid field
Messaging ServiceRequired
Rich feature supportLatest rich features supported by Twilio, such as catalog, carousels, media templates, and dynamic buttons
API to manage templatesContent API
UI to manage templatesContent Editor in the Twilio Console, go to Messaging > Content Editor

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:

  1. Go to Twilio Console > Messaging > Content Template Builder(link takes you to an external page).

  2. Click on Create new.

    Content Template Builder interface with a highlighted Messaging menu and a prompt to create your first content template.
    (information)

    Info

    If you are creating a template for the first time, you will see the Create your first content template button. Click it to create templates.

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

    For more information, refer to this page on creating Content Templates.

    • Template name: The name 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. WhatsApp doesn't allow multiple sequential line breaks.
    • Buttons and other rich features: There are a variety of button types and other rich features that can be added into a content template. To see a full list of supported template types, see our content type overview here.
  4. After you fill out the message template, click Save and submit for WhatsApp approval.

Configure call to action with button for Visit website, including body and URL fields, and option for WhatsApp approval.

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

Add sample data to variables for message templates and button URLs with fields for input and saving options.

Note: Once you submit a template, it currently cannot be edited.

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.

To learn more about Authentication Templates, see more here.

WhatsApp currently evaluates each template language translation on an individual basis. Content Templates offer searching and filtering tools to help manage your templates.

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.
  • Click Delete at the bottom of the page.
  • Alternatively, click on the 3-dot menu on the right-hand side of the template and select Delete.

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 information, refer to this article.


Send a WhatsApp message using a template

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

Twilio supports sending Content Templates using the ContentSid and ContentVariables parameters.

To send a templated message, include the ContentSid parameter in the call with the HX content SID of the template you would like to send. If your template includes variables, set them using the ContentVariables parameter. Twilio will send the message as a templated message if it matches one of the approved templates. For more information, refer to this page on sending Content Templates.

For example, if your approved template is:

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 ContentVariables parameter of the message resource, provide the end user's information as follows:

ContentVariables={ "1": "Joe", "2": "O12235234" }
Send a WhatsApp message using a message templateLink to code sample: Send a WhatsApp message using a message template
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async function createMessage() {
11
const message = await client.messages.create({
12
contentSid: "HXXXXXXXXX",
13
contentVariables: JSON.stringify({ 1: "Name" }),
14
from: "whatsapp:+15005550006",
15
messagingServiceSid: "MGXXXXXXXX",
16
to: "whatsapp:+18551234567",
17
});
18
19
console.log(message.body);
20
}
21
22
createMessage();

Response

Note: This shows the raw API response from Twilio. Responses from SDKs (Java, Python, etc.) may look a little different.
1
{
2
"account_sid": "ACXXXXXXXXX",
3
"api_version": "2010-04-01",
4
"body": "Hello! 👍",
5
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
"direction": "outbound-api",
9
"error_code": null,
10
"error_message": null,
11
"from": "whatsapp:+15005550006",
12
"num_media": "0",
13
"num_segments": "1",
14
"price": null,
15
"price_unit": null,
16
"messaging_service_sid": "MGXXXXXXXX",
17
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
"status": "queued",
19
"subresource_uris": {
20
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
},
22
"to": "whatsapp:+18551234567",
23
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.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 message when there's no customer service window open with that user. This may happen if your template was rejected later by WhatsApp. If you need to change the template to match your needs, submit a new template. If you are seeing a different error code and you believe it is related to templates, 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, encode the line breaks 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.


Initiate the customer service window with a generic template

initiate-the-customer-service-window-with-a-generic-template page anchor

You may want to send different types of notifications and messages to your users. However, it is difficult and inefficient to go through the template approval process for every type of message you wish to send to your end users.

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

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

"Hello {{1}}, we have a new update regarding your account. 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 customer service window, during which your business can send free-form messages.


Monitoring live templates

monitoring-live-templates page anchor

Once you start using your templates, monitor them for excessive negative user feedback.

Paused and disabled templates

paused-and-disabled-templates page anchor

If end users repeatedly block or report 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:

  • First instance: Paused for 3 hours
  • Second instance: Paused for 6 hours
  • Third instance: Disabled

When a template is paused a third time, it will 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). We also offer alarms for approved templates with code 63046.


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