Skip to main content

WhatsApp Template Message

Send WhatsApp template messages with Messente's Omnichannel API.


Introduction

WhatsApp template message use pre-approved message templates, that can be used to initiate conversations with users. The templates can be created through our template management API or using Meta's WhatsApp Business Account dashboard, and in both cases, they must be approved by Meta before they can be used.

The templates can include text, images, buttons, header/footer, and other interactive elements. They are designed to be re-usable and can be sent to users without prior interaction, as long as the template has been approved by Meta. Template messages are typically used for sending notifications, alerts, or other generic business-related messages. For more interactive flows, you can use service messages in order to be able to reply to users without pre-approved templates.

Template messages are the only way to initiate a conversation with a user. Once the recipient responds to your template message, a 24-hour window is started. Within this window, you can send any type of message to the user without needing to use a template. The type of messages, that don't require templates are called service messages. This can be especially useful for interactive flows, and back-and-forth conversation with your customers. After the 24-hour window expires, you are again required to use a template message to initiate a new conversation.

Service Window extension

The 24-hour service window is extended by any user-initiated message. This means that if the user replies to your template message, the service window is extended for another 24 hours. You can continue sending service messages within this window without needing to use a template.

Template Categories

There are 3 categories of template messages you can send:

  • marketing - these are used for sending promotional content, such as offers, discounts, or other marketing-related messages.
  • utility - these are used for sending important information, such as account updates, transaction notifications, order status, or other business-related messages with the aim to improve your customers' experience.
  • authentication - these are used for sending one-time passwords (OTPs), verification codes, or other authentication-related messages.

Different categories have different rules, restrictions and set of usable components, so it's important to choose the right category for your purpose. For example, only authentication messages can include OTPs, but can't include media content, while marketing and utility messages can include images, videos and documents.

Template Structure

Message templates consist of a name, category, language, and components. The name is a unique identifier for the template, and the category defines the type of message it is. The language must be specified and reflects the language, in which the template is written. The components are the actual content of the message, which can include text, images, buttons and more.

When creating a template, you can specify the components that you want to include in the message. Each component has its own set of properties, such as text, media URL, or button actions.

There are many types of components and they can contain parameters, which are placeholders for dynamic content. When sending a template message, you can use these parameters to replace the placeholders with actual values, allowing you to customize the message for each recipient. For example, you can use parameters to include the recipient's name, order number, or other relevant information. For more information about the components and their properties, you can refer to Meta's template component documentation. Our template messages are structured in a way, that allows you to include the components and parameters you need for a template.

Template Message Examples

The WhatsApp ecosystem is quite complex, and there are many different types of template messages you can send. To help you get started, we have provided some examples for the most common types, using our public libraries as well as raw HTTP requests (cURL). You can use these examples as a starting point for your own template messages, and customize them to fit your needs.

Hello world

After you've set up your WhatsApp Business Account and connected it to Messente, you can send a simple "Hello world" message to test the integration. It is a very basic template message, and it's already pre-approved by Meta, so you can use it right away. The template is called "hello_world".

# pip install messente-api

from pprint import pprint
from messente_api import (
OmnimessageApi,
Omnimessage,
Configuration,
ApiClient,
WhatsApp,
WhatsAppTemplate,
WhatsAppLanguage,
OmnimessageMessagesInner,
)
from messente_api.rest import ApiException


configuration = Configuration()
configuration.username = "YOUR_MESSENTE_API_USERNAME"
configuration.password = "YOUR_MESSENTE_API_PASSWORD"

api_instance = OmnimessageApi(ApiClient(configuration))

wa_template = WhatsAppTemplate(
name="hello_world",
language=WhatsAppLanguage(code="en_US"),
)
whatsapp = WhatsApp(sender="<sender name>", template=wa_template)
whatsapp_inner = OmnimessageMessagesInner(whatsapp)

omnimessage = Omnimessage(messages=[whatsapp_inner], to="<recipient_phone_number>")

try:
response = api_instance.send_omnimessage(omnimessage)
print(
"Successfully sent Omnimessage with id: %s that consists of the following messages:"
% response.omnimessage_id
)
for message in response.messages:
pprint(message)
except ApiException as exception:
print("Exception when sending an omnimessage: %s\n" % exception)

Media-based template with coupon code

This example shows how to send a template message with an image and a coupon code. The template consists of 5 components:

  • a header with an image,
  • a body with text and a parameter for the coupon code,
  • a footer with text,
  • 2 buttons that open a link and allow the user to copy the coupon code quickly.

The media is included in the header component and can be one of:

  • image
  • document
  • video
  • location
# pip install messente-api

from pprint import pprint
from messente_api import (
OmnimessageApi,
Omnimessage,
Configuration,
ApiClient,
OmnimessageMessagesInner,
WhatsApp,
WhatsAppTemplate,
WhatsAppLanguage,
WhatsAppParameter,
WhatsAppComponent,
)
from messente_api.rest import ApiException


configuration = Configuration()
configuration.username = "YOUR_MESSENTE_API_USERNAME"
configuration.password = "YOUR_MESSENTE_API_PASSWORD"

api_instance = OmnimessageApi(ApiClient(configuration))

header_component = WhatsAppComponent(
type="header",
parameters=[
WhatsAppParameter(
type="image",
image={"link": "<MEDIA_URL>"} # URL link to the header image or other media resource
)
]
)

body_component = WhatsAppComponent(
type="body",
parameters=[
WhatsAppParameter(
type="text",
text="<COUPON_CODE>" # The coupon code to be displayed
)
]
)

footer_component = WhatsAppComponent(
type="footer",
parameters=[
WhatsAppParameter(
type="text",
text="<FOOTER_TEXT>"
)
]
)

button_component = WhatsAppComponent(
type="button",
sub_type="copy_code",
index=1,
parameters=[
WhatsAppParameter(
type="coupon_code",
coupon_code="<COUPON_CODE>" # The coupon code to be copied when the button is clicked
)
]
)

whatsapp_template = WhatsAppTemplate(
name="<TEMPLATE_NAME>",
language=WhatsAppLanguage(code="<LANGUAGE_CODE>"),
components=[header_component, body_component, footer_component, button_component]
)

whatsapp_message = WhatsApp(
channel="whatsapp",
sender="<SENDER_NAME>",
template=whatsapp_template
)

whatsapp_inner = OmnimessageMessagesInner(whatsapp_message)

omnimessage = Omnimessage(
to="<RECIPIENT_PHONE_NUMBER>",
messages=[whatsapp_inner]
)

try:
response = api_instance.send_omnimessage(omnimessage)
print(
"Successfully sent Omnimessage with id: %s that consists of the following messages:"
% response.omnimessage_id
)
for message in response.messages:
pprint(message)
except ApiException as exception:
print("Exception when sending an omnimessage: %s\n" % exception)

Resulting Message

Media-based template with coupon code

Text-based template with Quick Reply buttons

This example shows how to send a template message with a text-based header and 2 quick reply buttons for user responses. The template consists of 4 components:

  • a header with text (this can be skipped in the request, since there are no parameters),
  • a body with text and a parameter for the user's name,
  • 2 buttons that allow the user to quickly respond to the message using pre-defined replies. The buttons in this case are yes and no replies. You can specify a PAYLOAD for each button, which is additional data that will be sent back to you when the user clicks the button. This can be useful for tracking user responses or triggering specific actions in your application. If you don't need the payload, you can skip adding the button components altogether, as long as they are present in the template approved by Meta.
# pip install messente-api

from pprint import pprint
from messente_api import (
OmnimessageApi,
Omnimessage,
Configuration,
ApiClient,
OmnimessageMessagesInner,
WhatsApp,
WhatsAppTemplate,
WhatsAppLanguage,
WhatsAppParameter,
WhatsAppComponent,
)
from messente_api.rest import ApiException


configuration = Configuration()
configuration.username = "YOUR_MESSENTE_API_USERNAME"
configuration.password = "YOUR_MESSENTE_API_PASSWORD"

api_instance = OmnimessageApi(ApiClient(configuration))

body_component = WhatsAppComponent(
type="body",
parameters=[
WhatsAppParameter(
type="text",
text="<PARAMETER_TEXT (e.g. a name or ID)>"
)
]
)

yes_button_component = WhatsAppComponent(
type="button",
sub_type="quick_reply",
index=0,
parameters=[
WhatsAppParameter(
type="payload",
payload="<PAYLOAD>"
)
]
)

no_button_component = WhatsAppComponent(
type="button",
sub_type="quick_reply",
index=1,
parameters=[
WhatsAppParameter(
type="payload",
payload="<PAYLOAD>"
)
]
)

whatsapp_template = WhatsAppTemplate(
name="<YOUR_TEMPLATE_NAME>",
language=WhatsAppLanguage(code="<LANGUAGE_CODE>"),
components=[body_component, yes_button_component, no_button_component]
)

whatsapp_message = WhatsApp(
channel="whatsapp",
sender="<SENDER_NAME>",
template=whatsapp_template
)

whatsapp_inner = OmnimessageMessagesInner(whatsapp_message)

omnimessage = Omnimessage(
to="<RECIPIENT_PHONE_NUMBER>",
messages=[whatsapp_inner]
)

try:
response = api_instance.send_omnimessage(omnimessage)
print(
"Successfully sent Omnimessage with id: %s that consists of the following messages:"
% response.omnimessage_id
)
for message in response.messages:
pprint(message)
except ApiException as exception:
print("Exception when sending an omnimessage: %s\n" % exception)

Resulting Message

Text-based template with Quick Reply buttons