/
WhatsApp Templates

WhatsApp Templates

On this page

Overview

You can use the WhatsApp channel to send outbound campaigns or single outbound messages using pre-approved templates.
These templates must be approved by Meta or Kaleyra, depending on your provider.

Once a message is sent using a template, it opens a 24-hour customer service window during which agents can freely exchange messages with the user.
This window starts the moment the first WhatsApp template is delivered → Explore Meta’s messaging limits.

Requirements

  • To send outbound campaigns or to allow agents to send single outbound messages (through templates), you need to use Meta or Kaleyra as providers

  • To use Kaleyra as provider you need to register an account at Kaleyra Login and configure an account on XCALLY following the relative wiki

  • To use Meta as provider, you need to register a Facebook Developers account on Meta for Developers (to create a WhatsApp Business App).
    Then you have to configure an account on XCALLY following the relative wiki

  • Moreover on your Facebook Developers account, you can access messaging insights at WhatsApp Manager > Overview Dashboard > Insights tab to check your messaging limits (explore here official Meta documentation)

WhatsApp Templates

Templates are structured messages (with optional variables) required for outbound campaigns or single messages.

By clicking on the WhatsApp Templates section, you have to select the created Meta/Kaleyra Provider and Account to view all created templates.

image-20240415-075316.png

Templates must be approved by the provider to be used for campaigns.

Create a template

To create a new WhatsApp template (up to 250 allowed), access to WhatsApp Templates section and click on Add +:

image-20240410-084659.png

  • Template name: name must be unique
    Starting from version 3.53.0, duplicate names trigger a warning:

    image-20250625-073533.png

  • Provider: Meta or Kaleyra

  • Account: associated account configured in XCALLY

  • Category:

Scenario
If campaign sends a marketing template and customer answers, then campaign send a utility template, this last one “replaces” 24h window that was open so it’s not possible to write to customer until he/she replies to utility template, because category has changed

  • Template language

You can explore supported languages for templates on Meta official link

 

  • Enable this option to mark the template as a Recontact Template, which can be selected later in the Advanced settings of an existing account.
    Recontact Templates are used to reach out to customers after the 24-hour Customer Service Window has expired. This is in accordance with Meta's policy that limits outbound communication once a conversation window is closed.
    Meta manages WhatsApp conversations as 24-hour windows, starting from the moment the first template message is delivered.
    Scenario
    - 11:00 AM – Agent sends a WhatsApp message using an approved template
    - 12:00 PM – Customer replies
    - A 24-hour customer service window opens, starting from 11:00 AM (when the agent has sent the first template). During this window, the agent can freely exchange messages with the customer.
    - Once the 24-hour window ends, no additional messages can be sent, unless a Recontact Template is used (already approved by Meta/Kaleyra before use).
    A Recontact Template allows the agent to resume contact after the window closes, with a pre-approved message, like e.g: “Hello {{NAME}}, the chat window has expired, please reply to this message if you still need support”.

  • Available to agents: option to allow agents to send specific templates to individual contacts. Find out more on the relative documentation

  • Calling Permission Request: option to ask customers if you can call them on WhatsApp, available from version 3.66.0 and using Meta as provider.

Important: WhatsApp calling is not yet available. The Calling Permission Request option is preparatory work to support WhatsApp Calls in future releases. While Calling Permission Request templates can already be created and synchronized, the actual calling functionality will be introduced in a later version.

image-20260618-094913.png
image-20240410-092809.png

Meta Template Limits

Character and Emoji Limits: If you exceed the maximum number of characters allowed in the message body or include more than 10 emojis, the interface displays a red counter below the text field. If the template is submitted anyway through the API or external systems, it is automatically rejected during validation with the status Rejected, indicating a formatting error as the reason.

  • Marketing Templates: The message body is limited to 550 characters (including variables such as {{1}}, {{2}}, etc.) and a maximum of 10 emojis.

  • Utility and Authentication Templates: The message body is limited to 512 characters.

Please note that Meta may change these values

  • Content (max 1024 characters): enter the message body here. You can include one or more variables.

Only plain text is allowed in this field

To insert a variable (e.g., {{1}}), the surrounding sentence must contain at least 3 words. If not, the system will display:
"This template has too many variable parameters for the message length. Please reduce them or extend the message length”.

Variables must be added sequentially (e.g., {{1}}, {{2}}…), or an error will be shown.

 

 

You can enable additional sections: Header, Footer, and Buttons.

image-20240410-093844.png
image-20240410-093928.png

Header

Types supported:

  • Text (Max 60 characters)

  • Media (Upload required with drag&drop option):

    • Image: JPG, JPEG, PNG only | Max 5MB

    • Video: 3GP, MP4 only | Max 16MB

    • Document: PDF only | Max 16MB

image-20240410-094151.png

If you select text it’s also possible to include a variable, both with Meta and Kaleyra providers.

image-20240410-094506.png

Footer

Text only (Max 60 characters)

You can enable one of the following button types (mixing not allowed):

It’s not possible to mix buttons typology, e.g. you can’t insert Yes / No / contact us button and if you choose call to action you can’t insert 2 phone numbers, but only 1 phone and 1 link

image-20240410-095334.png

Example of WhatsApp Template with call to action buttons:

Call-to-Action Buttons

  • Call Phone Number: define button text and phone number (with international prefix) to start a call directly

  • Visit Website: define button text and a full URL (shortened links and variables in the base URL are not supported by Meta to avoid spam; variables are permitted only in query string).

When using call-to-action buttons, the contact remains in Pending status until the Response Timeout is reached

Dynamic URLs in CTA buttons

FROM VERSION 3.67.0

In templates creation, it’s possible to handle dynamic URLs in CTA buttons.

Template creation on Motion

  1. Create a Meta Template in XCALLY

  2. Enable the “Button” option, by selecting “Call To Action”

  3. Enable Visit the Website and add a website URL

  4. You can view the section where you need to map and configure the Dynamic URL

  5. Adding {{1}} at the end of the URL will make the URL dynamic

    image-20260729-155128.png

Template creation on Meta with import on XCALLY

  1. Create a Template on Meta with Type Marketing

  2. Add button type “Call to Action”

  3. Add the URL and an Example of URL

  4. Save and Import on XCALLY

  5. You can view the new section where you need to map and configure the Dynamic Url

Consider that Meta supports a single dynamic variable, called {{1}}. You must insert it at the end of the URL and there cannot be any other characters after the variable.

The feature will also be available via API. Once a template with a dynamic variable has been imported from Meta, you need to map the variable in XCALLY via the GUI.

 

image-20240410-101734.png

Example of WhatsApp Template with quick reply buttons:

Quick Reply Buttons

  • It’s possible to create a choice with max 3 buttons, each with max 25 characters of text.

  • When a user taps a quick reply, their selected option is sent back as a message.

When using quick reply buttons, the contacts remain in pending status until they don’t answer.
Instead they can consider closed if they choose an option.
Explore here the possible scenarios.

  • Click on Add WhatsApp Message Template

Using List Messages via API

To configure list messages via API, refer to the Meta API Documentation to send interactive messages.
List Messages allow a structured menu of up to 10 options for better user interaction. They offer a simpler and more consistent way for users to make a selection when interacting with a business.
To allow the creation of this type of templates, on whatsapp_messages table, the following columns are present

  • type: ‘button' | 'button_reply' | 'list' | 'list_reply' | 'location' | 'media' | 'template' | 'text'

  • errorMessage: it contains any error message triggered when sending a message

New templates are submitted to Meta or Kaleyra and typically reviewed within 24 hours.

While in Pending, templates cannot be used.

image-20240410-154526.png

You can track template status also in:

  • Kaleyra: Channels → WhatsApp → Configurations → Templates

  • Meta: Business Manager → WhatsApp Manager → Message Templates, where you can see Active Templates and templates in the control

Templates have a quality status: customers can report business accounts as spam or undesired contact.
Meta monitors template performance based on user feedback. Repeated reports of spam may lower quality, eventually leading to the template being paused (no longer usable).
As long as the template is active (even if low quality) it’s possible to send it, after that, it will be put on pause (so not possible to send it). Find out here guidelines about quality rating and template pausing.

FROM VERSION 3.53.0

The WhatsApp Templates can be filtered by Not deleted | All | Deleted

image-20250625-073832.png

For Deleted templates, only Show Details and Preview template actions are available (editing is not allowed).

image-20250625-074043.png

 

After template creation, you can see the list of created templates with relative category and status:

image-20240410-154718.png

The created template has to comply with certain standards (that you can explore at this link), for example:

  • if it is configured as utility category, text can not contain question marks (because considered as marketing category)

  • a variable inserted in a empty row is not accepted

If you click on the Preview template, a modal will appear with the preview:

image-20240410-083636.png

Moreover you can edit a WhatsApp message template, by clicking on Edit template mapping

image-20240410-155621.png

 

You can see:

  • template name

  • selected category

  • Recontact Template option (switch on/off)

  • Available to agents option (switch on/off)

  • Header content

  • Content

  • Template preview

image-20240410-155700.png

 

If variables are used, map them to fields from the customer database (e.g., {{1}} = First Name).
The system populates automatically the list of variables used in the text template. So you can choose which field of the customer's database to insert within the variable.

image-20240410-155741.png

Variables must be mapped before launching a campaign with the specific template. You can map variable after template approval

Import of WhatsApp templates already created on Meta

FROM VERSION 3.64.0

You can import WhatsApp templates, already created and available on Meta, instead of recreating them manually.
By clicking on Sync templates button, the supported template types (Marketing and Utility without attachment) can be imported, while unsupported ones are skipped.

image-20260408-075953.png

The system inform the user about imported and skipped templates with a popup.

image-20260402-095910.png

From version 3.66.0 Calling Permission Request templates created on Meta are imported in XCALLY. Please note that the actual calling functionality is not available yet in XCALLY and it will be introduced in a later version.

Explore how to create a WhatsApp Campaign