icon_whatsapp_business_docs_center_33px_white_
WhatsApp Business API | Message Templates

The WhatsApp Business solution has two types of communications — Business Initiated, and User Initiated. Make use of both message types for facilitating interactions with your customers.

Message Templates

Notifications & Alerts (Business Initiated Conversation)

Companies can initiate a customer interaction with notifications like appointment reminders, shipping confirmations or delivery tracking information.

When you want to start communicating with an end user, you must set up message templates. When sending message templates, they can be personalized, translated and allow for minimal variable text through programmable variables. Every message template must be approved by WhatsApp before it can be used. Text, images, files (PDFs), videos, audios and more are available to be used in message templates. Please check more information on media message templates.

Attempting to send a non-approved message will be refused by WhatsApp, resulting in a delivery failure.

Advertising, marketing, and promotional messages are not permitted by WhatsApp, as per their Business Policy. These include offering coupon codes or free gifts, up selling, cold call messages, sending surveys or polls, as well as the inclusion of certain words or phrases that could make the template promotional. 

Support Window (User Initiated Conversation)

Each time an end user sends a message to a WhatsApp Business Account, the business has a 24 hour “support window” to reply to the end user with a message. Enterprises are free to personalize and design the communication without any approval needed. Support windows are applicable for customer service, feedback, surveys, and more.

How to Create Message Templates

WhatsApp message templates are specific message formats that businesses use to send out notifications, alerts, and customer care messages to people who have opted-in to receive them. These may include appointment reminders, shipping information, issue resolutions, payment updates, and more.

When creating a message template, you must add the following:

  • Name: A message template name can only contain lowercase alphanumeric characters and underscores ( _ ). No other characters or spaces are allowed.
  • 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.
  • Translations: All message template translations must be provided by you in the format below. The element name will be the same for all translations. When sending a message template from the WhatsApp Business API, you will specify the language you would like the message template to be displayed in by using the language field.
  • Variables: The correct format for variables is this string: {{#}}, where # represents the variable index. Note: variables must begin at {{1}}.

 Formatting

WhatsApp allows for basic formatting in message templates. To format a message or a part of a message, use the formatting symbols described in this table.

Formatting Description Symbol Example
Italic text Italicize your message with an underscore on both sides of the text _text_ Welcome to _tyntec_
Bold text Place an asterisk on both sides of the text *text* Your total is EUR *19.90*
Struck through text To strikethrough your message, place a tilde on both sides of the text ~text~ This is ~better~ best!
Monospace text / code Place three backticks on both sides of the text ```text``` ```print 'Hello World';```

Variables

When submitting a text-based message template, keep in mind that you need to contain the full body of the message. There are options to add unique parameters or variables, represented as placeholders, to personalize messages to your customers.

Message templates use numbered placeholders '{{x}}' for each variable in the message. Each variable can be replaced with text that contains letters, digits, special characters and/or spaces. Each message template needs to contain at least one parameter.

Here is an example of the full body of a message:

Hi Joey! Thanks for starting your personal training plan. We’ll send you a weekly update with your new schedule. You can log in online using your training ID 123456. Stay fit!

This message needs to be submitted with variables to personalize it for each of your customers:

Hi {{1}}! Thanks for starting your personal training plan. We’ll send you a *{{2}}* *update* with your new schedule. You can log in online using your training ID {{3}}. Stay fit!

*Note that there is also a bold element in the text which you can easily add to your message template.

Here is an example of an order confirmation:

 Hi Judy! Thanks for placing an order at FabShoes. Your order 786564, for a total of EUR 45.00, is confirmed. The expected delivery date is May 26th.

Here is how you would submit this message:

Hi {{1}}! Thanks for placing an order at FabShoes. Your order {{2}}, for a total of EUR {{3}}, is confirmed. The expected delivery is {{4}}.

Please note: the actual content of a variable can’t contain the following:

  • New lines
  • Tabulators
  • More than four consecutive spaces.

Last but not least, WhatsApp will not approve templates with floating parameters (i.e. lines with just parameters and no texts). Please surround the parameters with information so it’s clear what kind of data is inserted. In the below, we’re referring to {{3}} and {{4}} as the floating parameters.

Example:

  •  --
  • TICKET NO: {{1}}
  • PASSENGER NAME: *{{2}}*
  •  --
  • {{3}} - {{4}}
  • --

Sending a WhatsApp Message with Variables

To input actual variables into a Message Template, you'll need to send parameter values instead of sending the full message.

For the following example Message Template:

Hi {{1}}! Thanks for placing an order at FabShoes. Your order {{2}}, for a total of EUR {{3}}, is confirmed. The expected delivery is {{4}}.

You'll need to send the following example request:

curl –XPOST https://api.tyntec.com/chat-api/v2/messages\
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'apikey: API_KEY' \
-d '{
  "to": "+123234234",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": 545345345,
    "contentType": "template",
    "template": {
    "templateId" : "order_confirmation",
   "language" : {
      "policy"  : "deterministic",
      "code" : "en"
    },
    "parameters" : {
      "default" : "Ben",
      "default" : "2019-0000001",
      "default" : "600.00",
      "default" : "2019-06-01"
    }
  }
  }
}'

If your request has been successful, the response will be similar to this:

{
  "messageId": "77185196-664a-43ec-b14a-fe97036c697f",
  "acceptedAt": "2019-05-17T09:45:00Z"
}

Media Message Templates

With WhatsApp, you can expand text-based message templates with images, documents (such as PDFs), location, video and interactive buttons that can be sent as a company-initiated message. These are “media message templates”.

How to create media message templates

Creating your media message template follows the same principle of text-based message templates. You can add your media message templates via the Message Template API or in your account at my.tyntec.com. Check this Message Template Manager overview for more information.

When adding your add media types to your message templates via your tyntec account, all you have to do is declare what type of media you send in the header – image, location, pdf, text. The media component will be sent directly to the user, being uploaded on your server. WhatsApp reviews only the text component in your message templates.

When adding the media message template in the setup form, you will need to select the “message template type” (“standard message template” or “media message template”). Once you have selected “media message template”, new fields will pop up:

  • Header type/variant: select the media type. Currently, images (.jpeg and .png), documents (PDF), videos, location and interactive buttons 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 that should accompany the message by default.

As an alternative to the Message Template Manager on your tyntec account, you can also use our self-service API to submit new media message templates. Check how to proceed here.

Once submitted, tyntec will keep you posted on the approval process. In case you submit via the Message Template API, you get a response in 15 minutes latest.

Media Messages Integration

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

Image

curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
  "to": "+123214234234",
  "channels": ["whatsapp"],
  "whatsapp": {
    "from" : "+4923147790813",
    "template": {
      "templateId": "qr_code",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
 
        {
          "type": "header",
          "parameters" : [
            {
              "type": "media",
              "media": {
                "type": "image",
                "url": "https://upload.wikimedia.org/wikipedia/commons/6/6c/Sample_EPC_QR_code.png"
              }
            }
          ]
 
        },
        {
          "type" : "body",
          "parameters": [
            {
              "type": "text",
              "text": "Peter"
            },
            {
              "type": "text",
              "text": "tyntec post box"
            }
          ]
 
        }
        ]},
    "contentType": "template"
  }
}'

Documents (PDF)

curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'apikey: <API KEY>' \
  -d '{
  "to": "+123214234234",
  "channels": ["whatsapp"],
  "whatsapp": {
    "from" : "+4923147790813",
    "template": {
      "templateId": "checkin_voucher",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
 
        {
          "type": "header",
          "parameters" : [
            {
              "type": "media",
              "media": {
                "type": "document",
                "url": "https://s1.q4cdn.com/806093406/files/doc_downloads/test.pdf",
                "filename" : "Voucher"
              }
            }
          ]
 
        },
        {
          "type" : "body",
          "parameters": [
            {
              "type": "text",
              "text": "Peter"
            },
            {
              "type": "text",
              "text": "tyntec demo motel"
            }
          ]
 
        }
        ]},
    "contentType": "template"
  }
}'
 
With the response
 
{
    "messageId": "b19f2243-0fb8-41d7-be10-1cd7914b6e43"
}

Location

curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'apikey: <apikey>' \
   -H "apikey: $API_KEY"  \
  -d '{
  "to": "12341414124124",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "4923147790717",
    "template": {
      "templateId": "pickup_point",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "location",
              "location": {
                "latitude": 51.5005765,
                "longitude": 7.4954884
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Peter"
            },
            {
              "type": "text",
              "text": "2020/05/01"
            },
            {
              "type": "text",
              "text": "11am"
            }
          ]
        }
      ]
    },
    "contentType": "template"
  }
}'

Quick Reply (Interactive Buttons)

curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'apikey: <apikey>' \
   -H "apikey: $API_KEY"  \
  -d '{
  "to": "12341414124124",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "4923147790717",
    "template": {
      "templateId": "event_rating",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [        
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Peter"
            },
            {
              "type": "text",
              "text": "WhatsApp Demo"
            },
          ]
        },
        {"type" : "button",
           "subType" : "quick_reply",
           "index": 0,
           "parameters" : [{"type":"payload", "payload": "event-id-1233"}]        
        },
        {"type" : "button",
           "subType" : "quick_reply",
           "index": 1,
           "parameters" : [{"type":"payload", "payload": "event-id-1233"}]        
        },
        {"type" : "button",
           "subType" : "quick_reply",
           "index": 2,
           "parameters" : [{"type":"payload", "payload": "event-id-1233"}]        
        }
      ]
    },
    "contentType": "template"
  }
}'

Videos

curl -X POST \
  https://api.tyntec.com/chat-api/v2/messages \
  -H 'Content-Type: application/json' \
  -H 'apikey: <apikey>' \
   -H "apikey: $API_KEY"  \
  -d '{
  "to": "12341414124124",
  "channels": [
    "whatsapp"
  ],
  "whatsapp": {
    "from": "4923147790717",
    "template": {
      "templateId": "instructions",
      "language": {
        "policy": "deterministic",
        "code": "en"
      },
      "components": [
        {
          "type": "header",
          "parameters": [
            {
              "type": "media",
              "media": {
                "url": "http://techslides.com/demos/sample-videos/small.mp4",
                "type": "video"
              }
            }
          ]
        },
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "Peter"
            }
          ]
        }
      ]
    },
    "contentType": "template"
  }
}'

Pricing

There’s no additional cost for submitting and sending media message templates. Your current tyntec monthly fee and your message fees (for tyntec and WhatsApp) cover the media message templates.

Other Tips to Get Your Message Templates Approved

  • Make your template name clear and concise. Instead of using a name like "template_014," use:
    • "bus_ticket_details"
    • Remember that someone outside of your business will be reviewing your templates
  • Providing more clarity gives reviewers more context around how the template will be used
  • Templates that contain potentially abusive or threatening content will be rejected, such as:
    • Templates that threaten customers with a legal course of action
    • Templates that threaten to add customers to a WhatsApp group with their friends and family to shame them if they don’t pay back their loans

Service Window

As you already know, when a customer replies to one of your messages, a 24-hour “customer service window” opens, and during that time, communication with that customer is not ruled by message templates. You can exchange messages with that customer without needing to use WhatsApp-approved message templates.

Service Support After 24 Hours

There may be cases, especially when you’re using WhatsApp for customer service, that you need more than 24 hours to process an inquiry or answer a question. When this happens, you might need to send a message template to re-engage the affected customer, prompting him or her to answer it, thereby activating the “support window” again.

To handle a situation like this, you might consider creating template messages like this one:

“We have updates regarding your ticket {{1}}. Please respond back if you’d like to continue support.”
“I'm sorry that I wasn't able to respond to your concerns yesterday, but I’m happy to assist you now. If you’d like to continue this discussion, please reply with ‘yes’”
“I was able to do some follow-up based on our previous conversation, and I’ve found the answer to your question about our refund policy. If you’d like to continue our conversation, please say ‘yes’”

How to Disable Chat Function

For companies that want to use WhatsApp for notifications only, and therefore not expanding to customer service, it’s possible to disable the Chat function. Disabling this function means dropping the incoming messages, which can be done by:

  • Not providing a webhook (our system will drop messages/notifications in case nothing is configured) or
  • Providing the webhook but drop the messages on the receiving side.

Please be aware that tyntec doesn’t store incoming messages for future retrieval, so in case there is no webhook defined, the messages can't be queried from our systems