WhatsApp Message Templates

The following guide covers the many aspects of creating WhatsApp Message Templates for use with Sunshine Conversations.

Message Template Category

When submitting a message template, it is required to choose a category. This makes it easier for WhatsApp to review and approve a template by providing context for how the message template will be used. The category values are described here.

Message Template Name

When creating a message template, it is mandatory to give it a name. It is advised that the name reflect the template’s content. This name must have no more than 512 characters and may only contain lowercase letters, numbers, and underscores.

e.g.

  • account_balance_update_2020 ✅
  • account balance update ❌
  • Account_Balance_Update ❌
  • Account_Balance&Update ❌

Message Template Language

When creating a new message template, you must choose a language code. The language codes are described here.

A message template can be created in as many languages as desired. However, when translating the template into multiple languages, please be sure to use the exact same message template name.

When submitting a message template to WhatsApp for approval, or when sending a message template to a customer, please be sure to use WhatsApp’s language code (e.g. en_US).

Message Template Components

When creating a message template, you must select which components that you would like to include. It is important to note that you cannot add a new component to an existing template. You must create a new template — with a new template name — if you wish to incorporate a new component into a template.

The header is optional.

The header can only be one of: text, image, or document.

Text

A text header has a limit of 60 characters including parameters.

In the example: Hello {{1}}, this is an update for your account {{2}}. This header contains 44 characters not including parameters. This means that both parameters combined can only be 16 characters long when sending this template. If you try to add more characters, the message will fail.

Therefore:

  • Hello Johnathan, this is an update for your account 8472693. ✅
  • Hello Johnathan Smith, this is an update for your account 0018472693. ❌

Image

When creating a message template with an image header, you do not specify the actual image that will be used; you only specify that an image will be used in the message template’s header. The image only needs to be specified when sending the template. The image must also be less than 25MB.

Document

When creating a message template with a document in the header, you do not specify that actual document that will be used; you only specify that a document will be used in the message template’s header. The document only needs to be specified when sending the template. The document must also be less than 25MB.

Body

The body is mandatory.

The body of a message template should only contain text, parameters, emojis and formatting (bold, italic, strikethrough and monospace). There is no limit to the number of parameters allowed in the body but when sending the message template, the total number of characters may not exceed 1024. If using parameters in the body, they may contain many characters as long as the total body length does not exceed the aforementioned 1024 characters.

The footer is optional.

When creating a message template, you may include a footer at the end of the message. A footer may only contain text. No parameters, emojis, or formatting is allowed. A footer has a limit of 60 characters.

Buttons

Buttons are optional.

There are two different kinds of buttons that may be added to a message template: call to action and quick reply.

If you wish to send a call to action, you may not send a quick reply in the same template and vice versa.

Call to Action

A call to action button can allow the customer to call a specific phone number or go to a specific URL.

If using a phone number call to action, the button text (max. 25 characters), and phone number are required fields for template creation.

If using a URL call to action, the button text (max. 25 characters) and URL are required fields for template creation. However, when using a URL, it is possible to add a parameter at the end to customize the URL. To add a parameter to the URL, simply add {{1}} to the end.

Once set, call to actions can not be changed. Additionally, a single message template can have a maximum of 1 phone and 1 URL call to action button each.

Here’s an example of each type:

Quick Reply

A quick reply button can allow the customer to easily respond to a message template with up to 3 predefined answers.

For quick reply buttons, all that is required is the button text (max. 25 characters).

When sending a message template with quick replies, you will be asked to specify a payload. The payload is separate from the button text.

Deleting Message Templates

Currently, it is not possible to edit a message template once it has been submitted and approved. Therefore, if you wish to correct/update anything about an approved message template, you must first delete the template and then recreate it. Recreation of a template with the same name is only possible 30 days after its deletion. When deleting a template, all languages with that template’s name will be deleted as well. Please be sure that you don’t accidentally delete a template unless you wish to delete all of its translations.

Once a template is deleted, it should continue working for roughly 30 days. This is because WhatsApp leaves a grace period to make sure that any messages that have been sent — but not yet delivered — don’t fail. However, this also means that once a message template is deleted, that template name cannot be re-used for 30 days.

Exceptionally, if the message template happens to be rejected, the 30 day rule does not apply and the message template name will become free immediately after deleting the message template.

Message Template Content

Message templates were designed to allow WhatsApp to control the type of content that is sent to its users. As such, they have many restrictions around the types of content that are allow on the platform. Abusing the platform or ignoring WhatApp’s rules may lead to a phone number — or even your WhatsApp Business Account — becoming banned from the platform. Please exercise caution!

To avoid wasting time on rejected templates, here is a comprehensive list of reasons for which a message template may get rejected. It is important to note that, while it is unlikely, an approved message template may be revised and later rejected if WhatsApp decides that it no longer follows the guidelines.

Reasons for Rejection

Trying to cleverly circumvent these rules is not advisable as this will result in rejected templates. You can find more information here in WhatsApp’s message template guide.

To be sure that your templates get approved, please avoid these types of templates:

The message template contains content that violates WhatsApp’s Business Policy

To avoid this,

  • Do not request sensitive identifiers from users. This includes asking people to share full credit card numbers, financial account numbers, National Identification numbers, or other similar information either as plain text or in the form of attachments that contain this information.
  • Do not send a survey or poll to collect data from users. You may only send a survey to collect information about an experience the customer had with your business (and even these templates are often rejected).
  • Do not send games, contests, tests, quizzes, or anything that involves skill, competition or luck.
  • Do not send messages that are non-transactional. This means that you should only send messages from which you expect a reply.

The message template is considered promotional

To avoid this:

  • Do not send advertising, marketing, or promotional messages. This includes offering coupon codes and/or free gifts, upselling a product or service, and cold call messages such as “Is now a good time to talk?”, “Thank you for your interest, can we speak now?”, “I tried contacting you but you weren’t available. When are you free?”, etc.

The message template contains potentially abusive or threatening content

To avoid this:

  • Do not send messages that threaten customers with a legal course of action
  • Do not send messages that threaten to add customers to a WhatsApp group with their friends and family to shame them if they don’t pay back their loans.

The message template is incomplete

To avoid this:

  • Do not submit templates with floating parameters. This means, do not submit lines with just parameters and no text. Be sure to surround the parameters with information so it’s clear as to the intent and what will be inserted into these parameters. If the content of a parameter is too ambiguous, the template will be rejected.

The message template is formatted incorrectly

To avoid this:

  • Do not submit message templates with spelling or grammar errors. If Facebook approves a message template with spelling or grammatical errors, you will not be able to edit or correct them. (If you are stuck with an approved message template that contains errors, your only option is to delete the message template and submit a new one.)
  • Make sure to use parameters correctly: the syntax {{1}} must be respected and the parameter numbers must be sequential. ​

Create a new message template

Follow this guide to create a new WhatsApp Message Template using the Sunshine Conversations dashboard.