Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Send WhatsApp Notification Messages with Templates

WhatsApp Message Templates Overview

A WhatsApp message template is a message format that can be used over and over again to message users once they have opted-in and given your app permission to send them messages, and once WhatsApp has approved the template. Template messages are used to help maintain high-quality content and avoid spam in the ecosystem.

Template messages use placeholder values that can be replaced with dynamic content 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.”

Sending Non-Template Messages Within a 24-hour Session

If a WhatsApp user has sent your application a message - whether it is a reply to one of your outbound messages, or they have initiated communication themselves - your application has a 24-hour window to send that user messages that don't use a template (sometimes called a "24-hour session"). For 24 hours after the last message sent to your application by a WhatsApp user, your application can reply or send outbound messages to that user without using 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 e 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}}

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 on your Twilio Account

To create a template, go to Twilio Console > Programmable SMS > WhatsApp > Senders. Click on any phone number listed under Senders, and then scroll down to add templates.

Add new WhatsApp Message Template

After you fill out the message template, click “Create,” and the template will be sent to WhatsApp for approval. All templates must be approved by WhatsApp before you can use them for messaging users. (See tips and guidelines in the next section.)

Please refer to the WhatsApp documentation to learn more about message template formatting and supported languages.

Write clear, specific Message Templates

WhatsApp supports up to 250 templates per account. We recommend starting with a handful to get started faster.

First, please note that the following is not allowed on WhatsApp’s Business API:

  • Marketing or promotional content
  • Subscription messages (for example, a newsletter or blog post alerts).
  • Images or graphics files (at this time)

For a full list of forbidden use cases and services, please see WhatsApp’s Commerce Policy.

Here are some guidelines for increasing the odds of getting your templates approved:

  • Templates must have a specific purpose and be clear, concise, and well-written. For example: “{{1}} {{2}}” would be rejected because it is not clear how it would be used or what the message content would be.
  • Templates should be as short as possible to convey the necessary information.
  • Templates must not have any grammatical or spelling mistakes. Templates that include major spelling or grammatical mistakes will certainly be rejected. Templates with minor punctuation or grammatical inconsistencies may be approved, depending on the language.
  • Templates should be tagged with an appropriate message type and language tags.
  • We suggest getting feedback from others to ensure that the template text is clear.

You may send URLs in a template, e.g., “Thanks for registering with <SITE>. To continue click on

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.

Your template text should make it clear to the 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.”

The Approval Period

Typically, templates are approved by WhatsApp within three to five business days. If you are experiencing long delays, please open a support ticket with Twilio and include the “name” of the template that you created.

Revise rejected Message Templates

If your message template was rejected, first check the guidelines above. You may revise your template and submit a new one to replace the rejected template at any time. If you feel your template was 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.

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:

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”

        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 deviates from the approved template. You can use a diff tool to check for any differences between the approved template and the content being sent (i.e. extra spaces).

        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.

        Examples of Approved and Rejected Message Templates

        Examples of Approved Message Templates

        • Welcome {{1}}. What company do you work for?
        • Your {{1}} appointment is coming up on {{2}}.
        • Your {{1}} appointment is coming up on {{2}}. Reply with {{3}} or {{4}}
        • 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.

        Examples of Rejected Message Templates

        The following templates are too general:

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

        These message templates are not concise:

        • Hey, I'm, your new reminders bot in WhatsApp and here's what I can do:
          • Create a task by messaging me directly - You can message me 24/7 with things you want me to remind you and I'll add them to your list. If I'll find the due date, I'll add it automatically.
          • Create a task by forwarding a message - just like creating a task, you can forward me a message and I'll turn it into a task as well.
          • Get Reminders - When your tasks are due, I'll send you a reminder here in WhatsApp.
          • To see your list of tasks, make edits and get more done, please download the app -
        • Hi {{1}}! Not sure how to activate your Prepaid Card? It is quick and easy! Get your new Prepaid Card in your pocket and start to enjoy all the advantages! Access at {{2}}.
          • Revision: Hi {{1}}! Our records show that your new Prepaid Card is delivered. Reply “ACTIVATE” to activate your card now.

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

        • I am Jenn, the virtual assistant.
        • 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.

        The following template was revised to be more conversational and approved:

        • Rejected: What is the name of the city where you want to buy the property?
        • Approved: {{1}}, thank you for your interest. In which city do you intend to buy the property?

        These message templates contain promotional content:

        • Thank you for your booking. Now refer your friends and earn credits. Ask your friends to book with code {{1}}.
        • Ready! Thank you for your purchase of {{1}}. You can find your receipt at {{3}}. Download the App and get a $10 credit {{4}}.

        The following text from a message template fails to comply with the opt-in requirement:

        • “...trying to touch base with you over text as I couldn't connect with you either by phone or email...”

        What's Next?

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

        Rate this page:

        Need some help?

        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.