Template Messages

Most of the content were retrieved or adapted from Facebook Official Documentation

In this section, you will get acquainted with the Template Messages. Before we dive deeper as to how we can send a template message, it is important to understand the basics of a Template Message.

Why and What

In order to start conversing with your end user, you would need to either start with a Business-initiated Conversation or a User-initiated Conversation. A Business initiated Conversation is one of the three categories:

  • Marketing
  • Utility
  • Authentication

These conversations can be started by sending a template message. But what are template messages?

  • WhatsApp templates are messages that are pre-approved template messages and can be used if the Business wishes to initiate a conversation with its customers (Business Initiated conversation- BI).
  • Templates are used to prevent spam and they should be created following WhatsApp guidelines.
  • When sending template messages, businesses only need to provide template names and parameters, which serve for personalization purposes.

The currently available templates categories are named the same way - Utility, Marketing and Authentication Templates.

Unifonic Conversations API

Before we begin, this is the API end point: https://apis.unifonic.com/v1/messages

You will also require a publicId and secret key to be used as Headers.

Utility templates

Utility templates relate to a specific, agreed-upon transaction and accomplish one of the following: Confirm, suspend, or change a transaction or subscription.

Any template that has a mix of utility and marketing content will be classified as a marketing template.

DefinitionExamples
Confirm or suspend an existing transaction"Your order #0021 is confirmed"
"Thank you for your reservation! See you next week"
"Your payment was received! We hope you enjoy the concert!"
"Your consultation is complete, and your prescription is attached below"
"Thank you for visiting the doctor, here is your treatment plan"
"Your order has been canceled; your refund will be processed in 7-10 days"
Change or update a transaction"You have successfully checked in! Here’s your boarding pass for your flight"
"Your order has shipped! It will be delivered on Friday"
"Reminder: Your appointment is at 1pm on Tuesday"
"Your password was changed"
"Your profile was updated"
Account, billing, or payment notification"Here is the monthly statement you requested"
"Your payment failed, click here to retry"
"Your payment was accepted” / "Your payment failed"
Reminder: your payment is due on Tuesday"
"Here is your low-balance warning for account ending in -XXXX"
"Your pre-paid balance is low; click here to top up"

Note: Examples are illustrative only, templates containing similar content or content including this example text may be categorized differently based on their exact content.

Authentication Templates

Authentication templates enable businesses to authenticate users with one-time passcodes (usually 4-8 digit alphanumeric codes), potentially at multiple steps in the login process (e.g., account verification, account recovery, integrity challenges).

Authentication templates are our most restricted. Businesses must use WhatsApp’s preset authentication message templates, which includes optional add-ons like security disclaimers and expiry warnings. In addition, authentication templates must configure a one-time password button (copy code or one-tap).

URLs, media, and emojis are not allowed for authentication template content or parameters. Additional length restrictions of 15 characters also apply to parameters.

DefinitionExamples
Provide an authentication code to the user"{{1}} is your verification code."
"{{1}} is your verification code. For your security, do not share this code."
"{{1}} is your verification code. This code expires in 15 minutes."

Marketing Templates

Marketing templates are our most flexible – they do not relate to a specific, agreed-upon transaction and instead may relate to the business and/or its products/services. These templates may include promotions or offers; welcoming / closing messages; updates, invitations or recommendations; or requests to respond or complete a new transaction.

Any template that has a mix of utility and marketing content will be classified as a marketing template.

DefinitionExamples
Promotions or offers"If you buy 2 or more coffees, you’ll get $5 off!"
"Thanks for your order! Use code SAVE20 for 20% off your next order!
"Your pre-paid balance is low; click here to top up! Get a 10% bonus with code EXTRA10"
"Hey members join us tonight for this event"
Welcoming or closing messages"This is Vinny’s Bakery and we are now on WhatsApp!"
"Hello, welcome to our profile on WhatsApp!"
"I'm sorry for the delay, my name is XX, how can I help you?"
"Thank you, have a good day"
"Thank you for visiting our store, we really appreciate your visit."
"A question for you - how much time are you spending doing your hair?"
Updates, invitations, newsletters, or recommendations"Our store has moved. Come and check us out!"
"We will be closed next Monday for the holiday"
"Good news! The product you saved is back in stock."
"Join us for our upcoming holiday gala!"
"Here are this month’s coupons – happy shopping!"
"We think you will love this – check out our new ice cream flavor"
Requests to respond or complete a new transaction"Thank you for your order. We’d love your feedback. Please click here."
"Forgot something? We kept your items, click to check out"
"Your application is waiting for you. Click here to complete"
"You missed your recent appointment, tap here to rebook."

How to create a template for approval

WhatsApp message templates are specific message formats that businesses use to send out notifications or customer care messages to people that have opted in to notifications. Messages can include appointment reminders, shipping information, issue resolution or payment updates.

Before sending a message template, you need to create one. Businesses can submit the templates through their Unifonic Account or directly on the Meta Platform.

  1. Log in to your Unifonic account and navigate to the Channels>Whatsapp.
  2. Click the channel edit button of any Whatsapp Business Account and you should see the Templates tab

Click CREATE NEW TEMPLATE to submit a new template for approval.

Fill in the template details as mentioned above in the "WhatsApp Template" section depending upon its text template or media template. Do note that template name has to be in english alphanumeric characters only.

Template messages can contain the following specifications:

Header

Headers can be made up by text, or media such as Image, Video, Document and Location. The inclusion of header for your templates is optional.

👍

Location Header

Businesses can share their business address or an event location in the header. This would appear as a clickable map so that your recipients can navigate themselves to your location!

Body

The Body text is a mandatory field. This body is the main message which you're driving across in your template. And this is your chance to illustrate what you really wish to convey.

In this body free text box, you're allowed to specify up to 1024 characters. These characters can be:

  • plain text
  • placeholders which represents variables (you can later specify these variables {{1}} in your API request)

Footer

A footer message is optional. And it is usually used to convey some small details or disclaimer.

You are allowed up to 60 characters, text only.

Buttons

Buttons are optional in most cases. While in other cases, such as catalog and authentication template messages, buttons are mandatory and very often are added by default in the background.

Buttons for Utility and Marketing templates:

There are two button types for Utility and common Marketing templates:

  • Call to Action: specify a static or dynamic website and/or a Call Phone Number Button
  • Quick Reply: specify up to 3 options to choose from, up to 20 characters

Buttons for Authentication templates:

There are 2 types of buttons available for Authentication Templates. And they are:

  • Copy Code: Copy the OTP into your clipboard
  • Autofill: Autofilled into the application which is triggering the Authentication message

For more information on what an Authentication Template comprise, please read this Meta Documentation - Authentication Templates.

After a template is approved by Meta, you will now be able to send them to your end users.

How to edit a template

Customers can easily edit a template by going to the Unifonic Console. Simply click on the edit button of each template which you want to edit.

🚧

Templates can only be successfully editted once every 24 hours

  • Only templates with an APPROVED, REJECTED, or PAUSED status can be edited.
  • You can only edit a template's components.
  • Approved template can be edited up to 10 times in a 30 day window, or 1 time in a 24 hour window.
  • Rejected or paused templates can be edited an unlimited number of times.

How to send a template message

In order to get started with sending a template message, you will need an API key made up of Public and Secret Key. Follow this guide in order to retrieve your API keys. Also, make sure you're aware of what your approved template name and language is.

📘

Mandatory

Template Name, Language and API Keys are necessary before you can send out a template message

Text-Based Message Templates

To send a text-based message template, make a POST call to /messages. Make sure that the content.type is template

{
    "recipient": {
        "contact": "+966XXXXX",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "sandbox_account_update",
        "language": {"code": "en"},
        "components": [
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Name"
                    }
                ]
            }
        ]
    }
}

As your template might have more than 1 variable. You can add more parameters in the array table that are date/time/currency etc.

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "sandbox_account_update",
        "language": {"code": "en"},
        "components": [
        	{
        		"type": "body",
        		"parameters": [
            		{
						"type": "text",
						"text": "order-no-123"
					},
					{
						"type": "datetime",
							"datetime": {
							"value": "2020-04-10T08:54:09+00:00",
							"text": "May 1st, 2019 8:45pm"
						}
					},
					{
						"type": "currency",
						"currency": {
							"code": "USD",
							"value": 10990.23,
							"text": "$10990.23"
						}
					}
            	]
        	}
        ]
    }
}

Media-Based Message Templates

To send a media-based message template, make a POST call to /messages. Make sure that the content.type is template and add the media file in the header.

Adding an image to the header:

{
        "contact": "+966XXXXX",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "sandbox_ticket_update",
        "language": {"code": "en"},
        "components": [
            {
                "type": "header",
                "parameters": [
                    {
                        "type": "image",
                        "url": "https://XXXX"
                    }
                ]
            },
            {
                "type": "body",
                "parameters": [
                    {
                        "type": "text",
                        "text": "Spider Man"
                    },
                    {
                        "type": "text",
                        "text": "1 Jan"
                    },
                    {
                        "type": "text",
                        "text": "ABC Cinema"
                    }
                ]
            }
        ]
    }
}

Adding an video to the header:

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "sandbox_ticket_update",
        "components": [
        	{
        		"type": "header",
        		"parameters": [
					{
						"type": "video",
						"url": "{{urlVideoMp4}}"
					}
				]
			},
        	{
        		"type": "body",
        		"parameters": [
            		{
						"type": "text",
						"text": "order-no-123"
					},
					{
						"type": "datetime",
							"datetime": {
							"value": "2020-04-10T08:54:09+00:00",
							"text": "May 1st, 2019 8:45pm"
						}
					},
					{
						"type": "currency",
						"currency": {
							"code": "USD",
							"value": 10990.23,
							"text": "$10990.23"
						}
					}
            	]
        	}
        ]
    }
}

Adding an document to the header:

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "sandbox_reservation_update",
        "language": {"code": "ar"},
        "components": [
        	{
        		"type": "header",
        		"parameters": [
					{
						"type": "file",
						"url": "https://www.w3223233.org/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
                        "fileName": "fileName.pdf",
                        "text": "testing"
					}
				]
			},
        	{
        		"type": "body",
        		"parameters": [
            		{
						"type": "text",
						"text": "هنا"
					}
            	]
        	}
        ]
    }
}

Interactive Message Templates

To send a interactive message template, make a POST call to /messages. Make sure that the content.type is template and add the options in the payload.

Call-to-Action:

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "dev_order_trk_btns",
        "language": {"code": "en"},
        "components": [
        	{
        		"type": "body",
        		"parameters": [
					{
						"type": "text",
						"text": "#20200610-111234"
					}
				]
			},
        	{
        		"type": "options",
        		"parameters": [
            		{
						"value": "https://inserturl.com", //in case dynamic url was defined in template
						"subType": "url", 
						"index": 1
					}
            	]
        	}
        ]
    }
}

Quick Replies:

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "dev_event_quk_rply",
        "language": {"code": "en"},
        "components": [
        	{
        		"type": "body",
        		"parameters": [
					{
						"type": "text",
						"text": "The Great Concert"
					}
				]
			},
        	{
        		"type": "options",
        		"parameters": [
            		{
						"value": "Yes",
						"subType": "quickReply", 
						"index": 0
					},
					{
						"value": "No",
						"subType": "quickReply", 
						"index": 1
					},
					{
						"value": "Don't know",
            "subType":"quickReply",
						"index": 2
					}
            	]
        	}
        ]
    }
}

Authentication Template Messages With One-Time Password Buttons

{
    "recipient": {
        "contact": "{{phoneNumber}}",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "onetimepassword",
        "language": {"code": "en"},
        "components": [
        	{
        		"type": "body",
        		"parameters": [
					{
						"type": "text",
						"text": "123456"
					}
				]
			},
        	{
        		"type": "options",
        		"parameters": [
            		{
						"value": "123456",
						"subType": "url", 
						"index": 0
					}
            	]
        	}
        ]
    }
}

📘

What is the status of my template message

Simply subscribe to the Message Delivery Status Webhook by following this guide

Carousel Template Messages

{
    "recipient": {
        "contact": "+971563493085",
        "channel": "whatsapp"
    },
    "content": {
        "type": "template",
        "name": "dubai_craft_beer_week",
        "language": {"code": "en"},
        "components": [        	
        	{
        		"type": "carousel",
        		"cards": [
            		{
                        "cardIndex": 0,
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "url": "https://animalfactguide.com/wp-content/uploads/2022/03/koala_iStock-140396797-scaled.jpg"
                                    }
                                ]
                            },
                            {
                                "type": "options",
                                "parameters": [
                                    {
                                        "value": "button1 card1",
                                        "subType": "quickReply",
                                        "index": 0
                                    }
                                ]
                            }
                        ]
					},
                    {
                        "cardIndex": 1,
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "url": "https://animalfactguide.com/wp-content/uploads/2022/03/koala_iStock-140396797-scaled.jpg"
                                    }
                                ]
                            },
                            {
                                "type": "options",
                                "parameters": [
                                    {
                                        "value": "button1 card2",
                                        "subType": "quickReply",
                                        "index": 0
                                    }
                                ]
                            }
                        ]
					},
                    {
                        "cardIndex": 2,
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "url": "https://animalfactguide.com/wp-content/uploads/2022/03/koala_iStock-140396797-scaled.jpg"
                                    }
                                ]
                            },
                            {
                                "type": "options",
                                "parameters": [
                                    {
                                        "value": "button1 card3",
                                        "subType": "quickReply",
                                        "index": 0
                                    }
                                ]
                            }
                        ]
					},
                    {
                        "cardIndex": 3,
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "url": "https://animalfactguide.com/wp-content/uploads/2022/03/koala_iStock-140396797-scaled.jpg"
                                    }
                                ]
                            },
                            {
                                "type": "options",
                                "parameters": [
                                    {
                                        "value": "button1 card4",
                                        "subType": "quickReply",
                                        "index": 0
                                    }
                                ]
                            }
                        ]
					},
                    {
                        "cardIndex": 4,
                        "components": [
                            {
                                "type": "header",
                                "parameters": [
                                    {
                                        "type": "image",
                                        "url": "https://animalfactguide.com/wp-content/uploads/2022/03/koala_iStock-140396797-scaled.jpg"
                                    }
                                ]
                            },
                            {
                                "type": "options",
                                "parameters": [
                                    {
                                        "value": "button1 card5",
                                        "subType": "quickReply",
                                        "index": 0
                                    }
                                ]
                            }
                        ]
					}
            	]
        	}
        ]
    }
}


Template Quality

Now that you have your template ready, and has sent out template messages. You start to notice that your template seems to have a quality rating, just like your Whatsapp Phone Number. Indeed, Templates do have quality ratings. There are no hard rules as to why a template is rated these way, but the generic rule of thumb to quality ratings is that they are affected by how well received your messages are.

Template Quality RatingsDefinitions
Active - Quality pendingThe message template has yet to receive quality feedback from customers. Message templates with this status can be sent to customers. You can only view the quality rating via the Unifonic Console.
Active - High QualityThe template has received little to no negative customer feedback. Message templates with this status can be sent to customers. You can only view the quality rating via the Unifonic Console.
Active - Medium QualityThe template has received negative feedback from multiple customers but may soon become paused or disabled. Message templates with this status can be sent to customers. You can only view the quality rating via the Unifonic Console.
Active - Low QualityThe template has received negative feedback from multiple customers. Message templates with this status can be sent to customers but are in danger of being paused or disabled soon, so we recommend that you address the issues that customers are reporting. You can only view the quality rating via the Unifonic Console.
PausedThe template has been paused due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers. If a message template reaches the lowest quality rating (a status of Active - Low quality), it will automatically be paused for a period of time to protect the quality rating of phone numbers 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

You can view this template status via the Unifonic Console and subscribe to receive a webhook notification for this status change.
DisabledThe template has been disabled due to recurring negative feedback from customers. Message templates with this status cannot be sent to customers.

You can view this template status via the Unifonic Console and subscribe to receive a webhook notification for this status change.
RejectedThe message template has been rejected by Meta. Please edit or submit a new template request.

You can view this template status via the Unifonic Console and subscribe to receive a webhook notification for this status change.

🚧

Typically, we have seen that customers who do not do opt-ins for their WhatsApp subscribers end up having very poor template quality ratings at the end of a campaign.


What’s Next