Send WhatsApp Notification Messages with Templates

WhatsApp message templates overview

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. WhatsApp reviews and approves each message template, typically in 48 hours or less, to maintain high-quality content and avoid spam. Once WhatsApp has approved your template, you can use the message template to send notifications.

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

• Your login code for {{1}} is {{2}}.
• Example of a message sent using this template: Your login code for Twilio is 12345.

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 outbound messages within the 24-hour session. For more information on pricing, please see our pricing page.

Sending non-template messages within a 24-hour session

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.

Templates pre-registered for the Sandbox

Twilio has pre-provisioned for the following templates for use in the WhatsApp Sandbox:

• Your {{1}} code is {{2}}
• Your {{1}} appointment is coming up on {{2}}
• Your {{1}} order of {{2}} has shipped and should be delivered on {{3}}. Details : {{4}}

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

WhatsApp notification categories

Your WhatsApp message templates must fall into one of the following categories. Templates that do not align clearly with these template types are more likely to be rejected by WhatsApp in the template approval process described below.

• Marketing: Send promotional offers, product announcements, and more to increase awareness and engagement.
• One-time passwords: Send codes that allow your customers to securely access their accounts.
• Transactional: Send account updates, order updates, alerts, and more to share important information.

As of September 2022, the following categories are deprecated and will only show for previously submitted templates:

• Account Update
• Alert Update
• Appointment Update
• Auto-Reply
• Issue Resolution
• Payment Update
• Personal Finance Update
• Reservation Update
• Shipping Update
• Ticket Update
• Transportation Update

Creating message templates and submitting them for approval

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

Set up WhatsApp message templates in your Twilio account

To create a template, go to Twilio Console > Messaging > Senders > WhatsApp Templates. Click on Submit a 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: Select the one that best fits your use case.
• 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.

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

If your template includes placeholders (e.g. "Your login code for {{1}} is {{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.

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.

Template translations

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 does not support editing or deleting individual translations within a template. If you need to resubmit a translation, you must submit it as another new template.

Removing WhatsApp message templates

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.

Message template approval criteria

Your template text should make it clear to the end-user why they received your message. You can remind them of the reason why they originally granted you permission to send the messages. For example: “Hi {{1}}, thanks for your order {{2}} placed on {{3}}. Your order has shipped. You can get a tracking update any time by replying TRACK.”

WhatsApp does not allow template placeholders to be placed at the beginning or the end of the message. Doing so will result in automatic rejection of the template. To work around this restriction, you may add additional words or punctiation before/after the variable.

Common Rejection Reasons

WhatsApp most commonly rejects templates for the following reasons, so be sure to avoid the following:

• Variables are placed in the beginning or end of the message.
• Variables are placed next to each other, such as “{{1}} {{2}}”.
• Variables have mismatched curly braces, or use words instead of numbers. The correct format is {{1}}, not {{one}}.
• Variable parameters are not sequential. For example, {{1}}, {{2}}, {{4}}, {{5}} are defined but {{3}} does not exist.
• Call-to-action button URL contains a direct link to WhatsApp, such as "https://wa.me/14154443344", which Meta no longer allows.
• Template is a duplicate of an existing template. WhatsApp rejects templates submitted with the same wording with a different name. Please note that this check does not apply to OTP templates.
• Template contains content violating the WhatsApp Commerce Policy or the WhatsApps Business Policy. Do not request sensitive identifiers from users, such as payment card numbers, financial account numbers, or National Identification numbers. Requesting partial identifiers (ex: last 4 digits of their Social Security number) is OK.
• Template appears to encourage gaming or gambling. Including words such as "raffle" or "win a prize" almost guarantees template rejection by WhatsApp.
• Template is overly vague, such as “Hi, {{1}}, thanks”. This type of template could be abused to spam users. You need to surround the parameters with information so that it’s clear what type of information will be inserted.
• You are using the wrong language. For example, a template in English is submitted with Portuguese language selected.
• Grammatical or spelling mistakes. Even minor spelling or grammatical mistakes are likely to be rejected by WhatsApp.

Additional Tips for Creating Templates

WhatsApp's template approval requirements does not mean that your use case is not supported. Below are some tips to work with WhatsApp's rules and scale your use case:

• If you are not sure how to phrase your template, take an iterative approach. Submit a template, get it approved by WhatsApp, and tweak it based on results (feedback or Read rates, available in Twilio Insights). You can always submit a new version of the template and delete the old version.
• If you need to write a template to re-open the 24-hour window, we suggest starting with some mention of the previous thread. Example: “I’m sorry that I wasn’t able to respond to your concerns yesterday but I’m happy to assist you now. If you’d like to continue this discussion, please reply with YES”.
• Consider using a friendly tone when sending messages over WhatsApp. Selective use of specific emojis are shown to increase engagement with end users.

Including links in your templates

You may send URLs in a template, e.g., “Thanks for registering with My Business. To continue click on https://app.example.com”.

If you have an Official WhatsApp Business Account, recipients will see a link preview in the message.

If you have another type of WhatsApp Business Account, recipients will not see a link preview if they have not added the business to their contact list. Recipients can add your Business Account as a contact by clicking the Add as a Contact button in the WhatsApp interface. As soon as they do this, the link previews will retroactively appear, and all future links will also display previews.

Template Statuses

Templates can have the following statuses:

• Pending: Indicates that the template is still under review by WhatsApp. Review can take up to 24 hours.
• Approved: The template was approved by WhatsApp and can be used to notify customers.
• Rejected: The template has been rejected by WhatsApp during the review process.
• Paused: The template has been paused by WhatsApp due to recurring negative feedback from end users, typically resulting from "block" and "report spam" actions associated with the template. Message templates with this status cannot be sent to end users.
• Disabled: The template has been disabled by WhatsApp due to recurring negative feedback from end users or for violating one or more of WhatsApp's policies. Message templates with this status cannot be sent to end users.

Approval Period

Typically, templates are approved by WhatsApp within 24 hours. Starting October 2022, WhatsApp has been approving most templates within minutes. Twilio checks for template statuses every 15 minutes. If your template are remaining in "pending" state for more than 48 hours, please open a support ticket with Twilio and include the name of the template that you created.

Paused Templates

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

Paused message templates that are attempted to be sent do not count against the daily messaging limit.

Getting Alerts for Paused, Disabled and Rejected Templates

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

Revising rejected message templates

If your message template was rejected, you will see a rejection reason code in the Twilio Console specifying why WhatsApp rejected it. You may submit a new template with a different template name to replace the rejected template at any time. WhatsApp will not let you use the same template name for 30 days.

These are the rejection reasons that WhatsApp has disclosed to date:

• TAG_CONTENT_MISMATCH: The language and/or template category selected don’t match the template content.
• INVALID_FORMAT: Placeholders or other elements that were formatted incorrectly.

If you are having a difficulties getting your template approved, it often helps to provide additional detail in your template to make its use evident to WhatsApp. For example, you may add “You asked us to let you know about [Topic]”. If you feel your templates are being rejected by mistake and resubmissions continue to be rejected, please open a support ticket explaining the issue in detail. Twilio can request that WhatsApp reconsider the rejected template.

Marketing and promotional templates

As of September 19, 2021, WhatsApp has enabled marketing templates globally. This includes templates that WhatsApp deems to comprise promotional or marketing content. Businesses registered in any country are now allowed to send promotional or marketing templates. There is no additional requirement.

Note: WhatsApp will continue to conduct a review to ensure your templates are not violating any policies. For more information, see the WhatsApp Message Template Guidelines.

Send a WhatsApp message using a template

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:

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}}

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

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”

Twilio also supports sending template messages by referencing the template ID. This is available through Twilio's Content API (Pilot). To request access, please follow this link.

Encountering Error Code 63016

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

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.

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:

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

Initiate the 24-hour window with a generic template

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.

Examples of approved and rejected message templates

Approved message templates

• 👋 Welcome {{1}}. What company do you work for?
• Your {{1}} appointment is coming up on {{2}}. Have a nice day
• Your {{1}} appointment is coming up on {{2}}. Reply with {{3}} or {{4}}. Thank you
• Dear {{1}}: Unfortunately your pending booking did not go through.
No charges were made to your bank account.
You can try to rebook the hotel again.
We sincerely apologize for the inconvenience.

Rejected message templates

The following templates don’t provide sufficient detail on how they will be used:

• Reminder: {{1}}
• {{1}} was added
• {{1}}, {{2}}!

The following templates are considered spam, as they do not make it clear to the user why they are receiving this message:

• I am Jenn, the virtual assistant.
• Hi, are you available?
• We will put our platform up and running soon, I would like to get to know you better by asking 5 questions.
• Do not worry, I will not share your answers with anyone.

What’s next?

Ready to create your own WhatsApp templates? Head over to the Twilio Console to get started.