Template Messages

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.

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.

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.

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

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.

🚧

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.