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.

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

Template messages can contain the following specifications:

  • Header made up of either text, image, document, video (optional settings)

  • Body - mandatory - (up to 1024 characters, plain text with placeholders which represents variables)

  • Footer - optional - (up to 60 characters, text only)

  • Optional Buttons: (For Utility and Marketing templates)

    • Quick Replies - predefine 3 buttons with text up to 20 characters each
    • Call-to-Action - prefine a Call Phone Number button or a static or dynamic website
  • Mandatory Buttons (For Authentication templates)

    • Autofill
    • Copy Code

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 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": "ord20200610111234",
                        "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": "Maybe",
                        "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


What’s Next