Working with WhatsApp Message Templates

When initiating a conversation with a customer, you must use a Message Template. Message Templates must be approved by WhatsApp and can be submitted via the WhatsApp Template Manager on the MessageBird Dashboard. Note that you can only create a Message Template if you have an active channel. It is not possible to submit your own Message Template when testing using our Sandbox.

In this article, we will discuss the following:

What do I need to create a Template Message?

  • A name: The name of the Template Message has to be formatted in small letters only, and spaces need to be replaced with an underscore. The name should be as descriptive as possible. For example: shipping_alert_1

  • A body (1024 character limit)

  • Variable(s)/placeholder(s): The Template Message uses numbered placeholders '{{x}}' for each variable in the message. Each variable can be replaced with text that contains letters, digits, special characters, or spaces.

When submitting the Template Message for approval, you should keep in mind that it needs to contain the full body of the message, with the option to add unique parameters represented as placeholders. At least one parameter is required and the template should not contain any spelling mistakes.

What types of messages are supported as Template Messages?

Supported Categories

Not supported

  • Transactional: Send account updates, order updates, alerts, and more to share important information.

  • Marketing: Promotional offers, product announcements, and more to increase awareness and engagement. (always important to get explicit Opt-in from the customer first)

  • One-time passwords (OTP)

  • Recurring content

  • Customer re-engagement

  • Businesses asking customers to review their app

  • Businesses sending reminders or alerts that a customer may have indicated an interest in seeing (not related to a purchase or event)

  • Product or marketing/brand surveys

What does a Media Template look like?

WhatsApp media templates have a 3-part structure:

  • The header (optional)

  • The body (required)

  • Buttons (optional)

The Header

The Header is optional and can be an image,a document or video.


When using an image, keep the following in mind:

  • The maximum size is 20 MB

  • The following types of images are supported: jpg, jpeg, png, gif


When using a video, keep the following in mind:

  • The maximum size is 16 MB

  • The following types of video are supported: mp4 (Only H.264 video codec and AAC audio codec is supported. Only videos with a single audio stream are supported.)


When using a document, keep the following in mind:

  • The maximum size is 20 MB

  • A document header is only possible in .pdf format

The Body

The Body is required and supports only text and emojis. Keep the following in mind:

  1. Please include parameter placeholders (e.g. {{1}}, {{2}}, etc. At least one {{1}}), as required. Make sure it contains no tabs, or more than 4 consecutive spaces.

  2. The body can contain a maximum of 1028 characters

  3. All standard emojis are supported

  4. For formatting, please refer to the below:

    1. Bold: Place an asterisk on either side (*bold*)

    2. Italicise: Place an underscore on either side (_italic_)

    3. Strikethrough: Place a tilde on either side (~strikethrough~)

    4. Monospace: Place three backticks on either side (```monospace```)


Buttons are optional and can be Call to Actions and/or Quick Replies

Call To Action button options

    1. Call phone number

      For this type of button, you require:

      1. Button text (This is the text that will show on the button to call a number, e.g. "Call now". Up to 20 characters)

      2. Phone number

    2. Visit website

      For this type of button you require:

      1. This is the text that will show on the button to the url link e.g. "Visit our website!". Up to 20 characters

      2. Public website url

    3. Call phone number & visit website

      For this type of button, please check under 'Call phone number' & 'Visit website' above for the requirements.

Quick Replies

Quick replies allow you to suggest answers for your customer. You can create up to 3 buttons with a maximum of 20 characters each

How can I submit a Template Message?

Only if you have WhatsApp access, you can submit a Template Message from your Dashboard via the WhatsApp Template Manager. If you do not have WhatsApp access yet, sign up to get started.

  1. Head to the WhatsApp Template Manager in the WhatsApp Section on the left side of your Message Dashboard.

  2. Click on Create template, a pop-up will open.

  3. Fill out all the information

    • Name: in small letters only and spaces need to be replaced with an underscore

    • Category: should describe the purpose of the message

    • Language: the language of the template

    • Content: is the full body of the message, with the option to add unique parameters represented as placeholders.

      • Make sure to include at least one variable, like {{1}}

  4. Double-check all the information and, once you're ready, click on Submit for approval.

Keep in mind that once submitted for approval, a message template cannot be edited.

Best Practices

When submitting your Template Message, you should keep the following things in mind:

  1. Your template should include at least one parameter “{{x}}”

  2. Your template should not contain any spelling mistakes

  3. Your template should be formatted correctly, including parameters, as described above.

  4. Your template should have a clear title name, for example instead of using a name like "template_014," use "bus_ticket_details"

  5. Your template cannot be edited once it has been submitted

  6. Your template cannot contain any shortened URLs (like

  7. Your 'body' section should be within the 1024 character limit

Last updated