WhatsApp Business API | Creating a Message Template

Message templates can be fairly straightforward and simple when you know how they’re structured and which elements they are composed of.

For text-only message templates, all you need is body text.
For media message templates, you can use all the elements at your disposal, including a header caption for your media, footer text, and interactive buttons.

ℹ️ Are you ready to submit your message templates for approval? Use our Message Template API or the Message Template Manager on your tyntec dashboard. Check more details in our next section: Submitting a message template.

ℹ️ Message Templates cannot be renamed or edited once submitted so you would need to submit a new Message Template every time you’d like to make changes.

How you can create your message templates:

1. Choose a Name

A message template name can only contain lowercase alphanumeric characters and underscores ( _ ). No other characters or spaces are allowed.

image_docs_message_templates_name_screenshot

2. Select a Message Template Type

Select the appropriate template type from the drop-down list. The template type must fall under one of the template type options, e.g., appointment update, issue resolution, payment update, etc.

image_docs_message_templates_different_types_screenshot

3. Choose a Language

WhatsApp supports message templates in nearly 70 languages and idiom variations, e.g., American and British English.

Since WhatsApp does not perform any translations for your business, you need to provide all message template translations.

When sending a message template from the WhatsApp Business API, you need to specify the language you would like the message template to display using the language field. That means you need to submit a Message Template for each language chosen by you. Please make sure that you do NOT mix languages in your message template!

ℹ️ Check all supported languages and respective codes.

4. Add your Content

When creating the copy that will form your template content, here are some things to keep in mind:

Message Template content should include the text and a media sample (in case you’re sending media types, too).
Text copy can be no more than 1024 characters long.
New lines, tabs, or more than four consecutive spaces will not be accepted.
You can include variables to add personalization to your message (see more on Message Template Variables below).
You can send links or URLs from your business domain. For example, if you’re sharing a product link, you should share the full URL: https://www.tyntec.com/whatsapp-business-api

5. Format your Message Template

Your Message Template content can be formatted with italic, bold, or underlined text. See the table below for a description of each formatting option.

image_docs_message_templates_styling_screenshot

6. Variables

Dynamic variables - also known as placeholders, parameters, or substitutions - allow you to pass dynamic contents to the message while requesting message templates you can specify the dynamic variable like {{1}}, {{2}}. By adding unique parameters, you can personalize information for your customers.

For example, in the template below you can replace {{1}} and {{2}] with your own value when sending a message.

You made a purchase for {{1}} using a credit card ending in {{2}}.

For "namespace": "cdb2df51_9816_c754_c5a4_64cdabdcad3e" with "element_name": "purchase_with_credit_card", the first value you list replaces the {{1}} variable in the template message and the second value you list replaces the {{2}} variable.

Some of these parameters (e.g., date_time or currency) are localizable so they are displayed appropriately based on the customer's language and locale preferences. If the device is unsuccessful in localizing a parameter, it falls back to the value that is provided as the "default" value.

When a message request is submitted with a template, you specify the variables, which are textually replaced inside the WhatsApp installation we run for a phone number.

ℹ️ Note that the actual variable content cannot contain newlines, tabulators, and more than four consecutive spaces. Also, WhatsApp will not approve templates with floating parameters, i.e. lines with just parameters and without text. Make sure that you surround the variables with context, so it’s clear what type of data is inserted in the Message Template.

ℹ️ Check the tutorial on how to send a message with variables here.

7. Add media to your message template

With tyntec, you can embed media on your message templates at no extra cost.

To add media to your message template, you will have to:

Request approval for your media message template. You will need to specify the header type/variant, body text and footer (optional) and provide a media sample.
Integrate a code to enable the content types you wish to send a media message template.

The media component will be sent directly to the user, being uploaded on your server.

We provide the following media types on message templates:

Media type	Supported format	Supported size	Caption length
Images	JPG, PNG	Up to 5MB	Up 4096 characters
Documents	Any valid MIME-type	Up to 100MB	Up 4096 characters
Videos	MP4, 3GPP	Up to 16MB	Up 4096 characters
Locations	Latitude, longitude, location name, address	n/a	n/a
Buttons: Call-to-action	2 buttons	n/a	20 characters per button
Buttons: quick-reply	3 buttons	n/a	20 characters per button

ℹ️Check all the content types and their specifications here.

Requesting approval for your media message template

Once you have selected “media message template”, you should specify the following:

Header type/variant: select the media type. Currently, images (.jpg and .png), videos, documents (PDF), location and interactive buttons (call-to-action and quick-reply) are available.
Body text: add the text that will accompany your media file. The same guidelines as text-based message templates for WhatsApp approval apply.

Footer text (optional): in case you need to add a disclaimer, signature, or anything

ℹ️ Sending media samples for your media message template approval

Using the tyntec dashboard: you have to declare what type of media you send in the header. Then, send an email to onboarding@tyntec.com to provide the media sample.

Using the Message Template API: you can submit the media sample directly on the API. – image, video, location, document, text - and add a media sample for approval.

Integrating media messages

In addition to requesting approval for your media messages, you will need to add a code to enable this feature in your integration for:

Image

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
-H 'Content-Type: application/json' \
-H 'apikey: <API KEY>' \
-d ''
 
{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",
            "components" : {
                "header" : [
                    {
                        "type": "image",
                        "image" : {
                            "url": "https://upload.wikimedia.org/wikipedia/commons/6/6c/Sample_EPC_QR_code.png"
                        }                        
                    }
                ],                
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    },
                    {
                        "type": "text",
                        "text": "Additional Variable"
                    },
                    {
                        "type": "text",
                        "text": "And a third one"
                    }
                ]
            }
        }
    }
}

Documents

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
-H 'Content-Type: application/json' \
-H 'apikey: <API KEY>' \
-d ''
{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",
            "components" : {
                "header" : [
                    {
                        "type": "document",
                        "document" : {
                            "url": "https://s1.q4cdn.com/806093406/files/doc_downloads/test.pdf"
                        }                        
                    }
                ],                
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    },
                    {
                        "type": "text",
                        "text": "2nd Parameter"
                    }
                ]
            }
        }
    }
}

Videos

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
-H 'Content-Type: application/json' \
-H 'apikey: <API KEY>' \
-d ''
{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",
            "components" : {
                "header" : [
                    {
                        "type": "video",
                        "video" : {
                            "url": "http://techslides.com/demos/sample-videos/small.mp4"
                        }                        
                    }
                ],
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    },
                    {
                        "type": "text",
                        "text": "Additional Variable"
                    }
                ]
            }
        }
    }
}

Location

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
-H 'Content-Type: application/json' \
-H 'apikey: <API KEY>' \
-d ''
{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",
            "components" : {
                "header" : [
                    {
                        "location" : {
                            "longitude" : 7.4954884,
                            "latitude" : 51.5005765,
                            "name" : "tyntec GmbH",
                            "address" : "tyntec GmbH, Semerteichstraße, Dortmund"
                        },
                        "type":"location"
                    }
                ],  
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    },
                    {
                        "type": "text",
                        "text": "Additional Variable"
                    },
                    {
                        "type": "text",
                        "text": "And a third one"
                    }
                ]
            }
        }
    }
}

Buttons: Call-to-action with dynamic URL

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
-H 'Content-Type: application/json' \
-H 'apikey: <API KEY>' \
-d ''
{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",
            "components" : {
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    },
                    {
                        "type": "text",
                        "text": "Additional Variable"
                    }
                ],
                "button" : [
                    {
                        "type" : "url",
                        "index": 1,
                        "text" : "test"
                    }
                ]
            }
        }
    }
}

Buttons: Quick-Reply

curl –XPOST https://api.tyntec.com/conversations/v3/messages\
-H 'Content-Type: application/json' \
-H 'apikey: <API KEY>' \
-d ''
{
    "from" : "{{whatsAppBusinessNumber}}",
    "to" : "{{receiverPhoneNumber}}",
    "channel" : "whatsapp",
    "content" : {
        "contentType" : "template",
        "template" : {
            "templateId" : "{{whatsAppTemplateName}}",
            "templateLanguage" : "{{whatsAppTemplateLanguage}}",
            "components" : {
                "body" : [
                    {
                        "type": "text",
                        "text": "User"
                    }
                ],
                "button" : [
                    {
                        "type" : "quick_reply",
                        "index": 0,
                        "payload" : "event-id"
                    },
                    {
                        "type" : "quick_reply",
                        "index": 1,
                        "payload" : "event-id"
                    },
                    {
                        "type" : "quick_reply",
                        "index": 2,
                        "payload" : "event-id"
                    }
                ]
            }
        }
    }
}