Best Practices for WhatsApp API Message Templates and Session Messages

Best Practices for WhatsApp API Message Templates and Session Messages

Best Practices for WhatsApp API Message Templates and Session Messages

Mar 18, 2021

Published by

Published by

MessageBird

MessageBird

Category:

Category:

WhatsApp

WhatsApp

Ready to see Bird
in action?

Ready to see Bird
in action?

Best Practices for WhatsApp API Message Templates and Session Messages

Best Practices for WhatsApp API Message Templates and Session Messages

WhatsApp Message Templates allow you to actively communicate and build engaging experiences with your customers. You can send templated support messages, notifications, account updates, alerts, and two-factor authentication codes.

If it’s your first time using the WhatsApp API, then be aware that WhatsApp enforces stronger rules and restrictions than other messaging channels. We’ve put together guidelines and best practices to help ensure approval of your template messages — from getting started to sending out WhatsApp Message Templates:

  • Message Templates versus Session Messages

  • Message formats allowed to be used on WhatsApp API

  • Rules to start sending WhatsApp Message Templates

  • Best practices to prevent your messages from being rejected

  • Start sending WhatsApp Message Templates with MessageBird


Message Templates vs Session Messages with WhatsApp API

The WhatsApp API allows you to interact with your customers in two ways: 

  • Session Messages: These are responses from your business to a customer, when a customer initiates a conversation with your business on WhatsApp.

  • Message templates: These are templated outbound messages you send to customers, that require customer opt-in.

Customer Care Window

The biggest difference between message types is what WhatsApp calls the Customer Care Window. The Customer Care Window is a 24-hour timeframe that allows you to communicate with your customers and respond to their queries — it starts when your customer sends their first message.


Session Messages

Session Messages include media attachments (images, videos, GIFs, etc.) and help you provide better and faster customer support.

You don’t need to get these messages pre-approved as long as you follow WhatsApp Business Policy and WhatsApp Commerce Policy.

MessageBird’s WhatsApp API allows the following formats for Session Messages:

  • Text messages (supports formatting such as bold, italic, strikethrough & code)

  • Text messages with URL (can enable preview URLs & all URLs are clickable)

  • Send/receive media messages (audio, document, image, sticker & video)

  • Send/receive location

  • Buttons (coming soon!)


Template Messages

You can only send Template Messages to users who have opted-in to receive from you. These templated messages are typically used for transactional notifications like purchase confirmations, delivery alerts, etc.

Since Template Messages are sent to users outside of the 24-hour customer care window, they are required to be highly structured and paid for (rates vary by country).

Here is an example of a WhatsApp Template Message:


In their documentation, WhatsApp explains that you are not allowed to send promotional materials through template messages. However, WhatsApp has recently started beta testing non-transactional notifications in Indonesia and Mexico. These new notifications templates include promotional and marketing messages. 

Talk to our sales team if you want to be part of the beta program.

What formats are allowed on Message Templates?

The most recent WhatsApp API update allows you to send the following content types: text, message templates, images, documents and audio. 

WhatsApp defines the different variations as:

  1. Text Messages

  2. Media Messages

  3. Message Templates

  4. Other Message Types


Regardless of the content type, you have to get your messages pre-approved before going live — and don’t be surprised if your first message(s) get rejected by WhatsApp. Our MessageBird team has developed the following guidelines and best practices to help prevent your WhatsApp Message Templates from rejection.

10 rules to prevent your WhatsApp Message Templates from being rejected

Following these best practices will help you ensure speedy approval of your templates by WhatsApp so you can start sending messages.

1. WhatsApp Message Templates categories

Make sure that your messages fall into one of the following categories:

  • Account Update: Give customers updates about changes to their accounts.

  • Alert Update: Send notifications on order updates or delivery services.

  • Appointment Update: Send appointment reminders and confirmations.

  • Auto-Reply: Send automatic messages during your Holidays or outside of work hours.

  • Issue Resolution: Respond to questions, issues or information customers need from you.

  • Payment Update: Confirm that payments were successfully processed.

  • Personal Finance Update: Update customers on personal finance queries.

  • Reservation Update: Keep customers up to date with their reservations. 

  • Shipping Update: Send shipping updates on new purchases or orders.

  • Ticket Update: Confirm and send ticketing update status.

  • Transportation Update: Update customers on transportation related tickets.


2. Grammatical Errors and Language Selection

Misspelling and grammatical errors can automatically flag your messages as spam or untrustworthy. Make sure to check — and double check — the spelling of your messages before you submit them.

Your Message Template must also match the language you’ve selected. If you are sending a message in Bahasa, but you’ve selected English as the message language, your message will be automatically rejected. Here is a list of supported languages by WhatsApp.


3. Formatting Rules

These are the formatting guidelines to follow when writing your Message Templates:

  1. Naming of template: The name of your message template can only contain lowercase alphanumeric and underscores (e.g. account_update_1) Make your message template name clear. 

  2. Size of template: The message has a limitation of 1024 characters and can not include new lines, tabs or more than 4 consecutive characters.

  3. Must be text-based: letters, digits, special characters, emojis, and WhatsApp specific formats.

WhatsApp also allows you to format selected text inside your messages with Bold, Italics, Strikethrough or Monospace:


4. Variables for your Message Templates

The Message Template 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. 

For our example, {{1}} is the name or the customer, {{2}} is how frequently the company is sending to the customer, {{3}} is the training ID of that specific client.

Here is how it would need to submitted for approval in our Sandbox:

"Hi {{1}}! Thanks for starting your personal training plan. We'll send you a {{2}} update with your new schedule. You can log-in online using your training ID {{3}}. Stay fit!"

Here is how an Account Registration message would look like:

"Hi Anna! Thanks for starting your personal training plan. We'll send you a weekly update with your new schedule. You can log-in online using your training ID 1234. Stay fit!"

For additional help writing your WhatsApp messages, check out this guide.

5. Using URLs for your messages

WhatsApp recommends sending links or URLs from your business domain. For example, if you are sharing a product link, you should share the full URL: https://www.messagebird.com/en/solutions/whatsapp-api 

We don’t recommend using Short Links or third party URL shortener such as Bitly: https://bit.ly/3t8RDEj

6. 24-hour rule

Understand how the 24-hour Customer Care Window works and follow the rules of engagement. You can chat with a person for up to 24 hours after a customer first initiates a chat with you. Outside of the Customer Care Window, you should only send messages via approved Message Templates. Sending other types of messages can lead to your account being flagged or blocked.

7. The Opt-in rule

You must receive explicit opt-in from the end user before you can start sending WhatsApp Template messages. Opt-in can not be assumed and has to be approved by the end-user. The opt-in must 

  • Clearly state that the person is opting in to receive messages from you over WhatsApp

  • Clearly state your business’ name

Be specific in your message and use clear language. Example:

“To receive (e-invoices and delivery notifications) to (+31 XXX XXX) from MessageBird, please reply yes”

Violating this rule can lead to your account/number being blocked. If you are still unsure, read our WhatsApp guidelines for customer opt-in.

8. Don’t collect customer data or try to run promotions

WhatsApp is slowly rolling out new promotion and marketing message templates starting in Indonesia and Mexico; however, if you are sending messages outside of those regions we recommend avoiding upselling, coupon codes, cold-call messages or sending links with polls to collect customer data otherwise your account could be flagged or blocked. 

9. Chat automation with escalation paths

You can use chatbots and chat automation to respond within the Customer Care Window, but you are required to set up clear and direct escalation paths to human agents.

These escalation paths include:

  • In Chat Human Agent transfer

  • Phone number

  • Email

  • Web support (on the business website)

  • In-store visits (ex: visit retail store, bank branch)

  • Support form

10. Improve the quality of your messages from low to medium within 7 days

WhatsApp tracks the quality of your messages as low (red), medium (medium) or high (green)


If you are not able to improve the quality rating of your messages from low to medium within a 7-day period, WhatsApp will disable your templates and prevent you from sending new messages or even reject other ones. 

Examples of messages rejected

There are a number of reasons as to why messages can be rejected. We wanted to share some examples of messages that were rejected so that you don’t make the same mistake:

  • Promotional coupon: Hi {{1}}. Thank you for buying your shoes. Get 5% on your next purchase with this coupon code {{2}}. Here is your boarding pass, with seat assignment and gate information. If you would like to save 5% on your in-flight dinner, order your meal through our app.

  • Wrong formats: Hi {{1}} | Order Information: {{2}}

  • Mix of languages: Hi {{1}}! This is Shoe Co, Gracias por comprar tus zapatos.

  • Sensitive information: Hi! Please share your full banking account number to process your quests

  • Surveys: Hi, we're interested in knowing how you feel about certain food groups. Do you mind participating in a survey?

  • Cold calls: Is not a good time to talk? Thank you for your interest. Can we speak now?

For additional examples, please refer to our guide “Why has the message template been rejected?”.

Ready to start using WhatsApp?

MessageBird’s WhatsApp Business API connects you to your customers on the world’s most popular messaging app via our powerful APIs, tools like Flow Builder and Inbox,, or native integrations like Zendesk. Our customers use WhatsApp for customer support, sending alerts and notifications, and even two-factor authentication.


MessageBird’s WhatsApp Business API offers:

  • Easy integration: Send and receive WhatsApp messages without having to host, manage or take care of software updates.

  • End-to-end WhatsApp encryption: All your information is secure.

  • Rich messaging: CTA and quick-reply buttons, share and receive images, locations, files, audio, and inbound videos.

  • 24/7 support: Our offices around the world provide unparalleled support in every time zone, 24 hours a day, 7 days a week.

Join today and start sending WhatsApp Message Templates for your business!

Your new standard in Marketing, Payments & Sales. It's Bird

The right message -> to the right person -> at the right time.

Your new standard in Marketing, Payments & Sales. It's Bird

The right message -> to the right person -> at the right time.