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.

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

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