/
Instant - Outbound Campaigns

Instant - Outbound Campaigns

XCALLY Section

WhatsApp –> WhatsApp Templates
WhatsApp –> WhatsApp Campaigns

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.

  • Meta Templates must be created through the XCALLY interface

  • Kaleyra Templates can be managed in Kaleyra or XCALLY, depending on where the template originated

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 before use 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.

image-20240410-092809.png

 

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.

Find out more about message guidelines and Common Rejection reasons, at this link.

 

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

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.

  • 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

Create a WhatsApp Campaign

You can create a new WhatsApp Campaign, by clicking on WhatsApp → WhatsApp Campaign → + Add Campaign

image-20241015-102949.png

 

  • Insert campaign Name

  • Select Provider (Meta or Kaleyra)

  • Choose Account (Meta/Kaleyra type)

  • Select WhatsApp Templates (only approved templates are shown). The eye icon shows a template preview

  • Insert sending Interval

  • Indicate Response Timeout (expressed in days, minimum 1): specifies the time window during which a customer’s reply is considered valid and associated with the campaign. After this period, any response is treated as a separate interaction

  • Hopper history duplicate check: defines the number of past days (1-7) to check for duplicate contact duplicates in the hopper history. If left blank, duplicate checking is skipped.

  • Include customers with active interactions: allows you to send the campaign even to contacts currently in an active conversation with an agent.
    ⚠️ Option disabled by default, to avoid confusing the customer during ongoing chats.
    Use this option when needed—for instance, in mass notifications, such as a service number change.

  • Close interaction on quick reply response: when enabled, the system automatically closes the interaction if the customer replies using a quick reply button

  • Start date: set the exact start time for the campaign. If left blank, the campaign will start immediately upon saving

  • Click on Add WhatsApp Campaign

To determine the cost of sending conversations based on the selected template category, please refer to the official Meta pricing documentation, where you can download the pricing file corresponding to your local currency.
Consider that Meta charges per conversation, not per message. A conversation is defined as the exchange of messages in the 24-hour time window, tarting from the first message sent

After creating a campaign, it will appear in the campaign list with a corresponding status.
For example, the status will display RUNNING once the campaign has started.

image-20240410-163816.png

 

In this section, all created campaigns are displayed by default. You can filter campaigns by account to view only those associated with a specific WhatsApp provider or configuration.

By clicking the three-dot menu (⋮) next to a campaign, the following options are available:

  • Edit WhatsApp Campaign

  • Add List

  • Stop WhatsApp Campaign

  • Start WhatsApp Retry Campaign

  • Delete WhatsApp Campaign

To send a campaign, you must add a contact list. Lists must be previously created in Contact Manager → Lists.
Phone numbers must be formatted with the international prefix, without the "+" sign (e.g., 393402211333).
Lists can be added in two ways:

  • From the three-dot menu (⋮) next to the campaign → Add List

  • While editing the campaign → click the green "Add List" button

The campaign will send messages to numbers in the Phone Contact field.

Starting from version 3.50.0, if only the phone or mobile field is filled, the system will automatically copy the number to the other field.
✅ It is strongly recommended to insert the same number in both the phone and mobile fields to ensure proper delivery.

When adding contacts:

  • If the Account List (Master List) already contains a contact with the same phone number, and this contact is also present in the campaign list (whatsapp_hopper), any custom fields or variable values will be synchronized across both lists.

  • This ensures data consistency when using variables in WhatsApp templates.

 

For Meta Accounts, non-existing numbers pass directly in hopper history tab with reason Message Undeliverable. This can occur in the following cases:

  • recipient's number is not associated with a WhatsApp account

  • recipient has not accepted the latest Terms of Service and Privacy Policy

  • recipient is using an outdated version of WhatsApp

For Kaleyra Accounts, non-deliverable numbers pass directly in hopper history tab with reason ‘To’ number invalid or WhatsApp account does not exist

If the campaign attempts to send a message to a phone number with fewer than 5 digits, the contact remains in the hopper with the error
Contact with invalid phone number: {{phone_number}}. The phone number should have at least 5 digits.
📌 Phone numbers must contain at least 5 digits to be considered valid for campaign delivery.

 

By clicking Edit on a WhatsApp campaign, you can access detailed configuration and performance data:

image-20241015-103217.png

 

  • Settings displays general information about the campaign, such as name, provider, template used, and configuration options.

image-20241015-103310.png

 

  • Hopper provides a real-time overview of contact statuses within the campaign:

    • total number of contacts in the campaign

    • fresh, so contacts that have not yet been messaged

    • retry, contacts that previously failed and are eligible for another attempt

    • pending, contacts who have received the message and are awaiting response

    • closed, contacts who completed the interaction (e.g., by responding to the message)

  • Pending tab: contacts in pending status after sending the template message waiting for a response. A contact remains in Pending status until they reply or the campaign ends.

  • Contacts History shows the outcome of the campaign for each contact, including responses received and status per contact

  • At the top of the campaign editor, a blue action bar contains two key icons:

    • Green icon – Add List: attach a new list of contacts to the campaign.

    • Red icon – Reset List: resets all contacts in the hopper to Fresh status, allowing the campaign to resend messages to previously handled contacts.
      ⚠️ Use with caution: all previously contacted recipients will receive the campaign again

 

For contacts that failed to receive the message, you can initiate a retry:

  • Open the campaign menu (⋮ three dots)

  • Select Start WhatsApp Retry Campaign

image-20240503-071516.png

You may perform multiple retries, as long as they fall within the campaign's configured duration window.

Only temporary failures (e.g., network issues) will be retried. Permanent failures (e.g., non-existent WhatsApp accounts) will be skipped.
Errors that allow retry are due to, for example:

  • temporary network problem

  • invalid template (temporary invalidity decided by Meta)

  • temporary authentication error

  • “Contact has an open interaction with another campaign” option (when the other campaign will be closed, you will be able to retry sending desired template).

A running campaign can be stopped by clicking on the 3 dots in the campaign → Stop WhatsApp Campaign

Campaign interactions

When a campaign is launched, the system first checks whether the contact is already involved in an active campaign interaction.
If an open interaction exists, the contact remains in Pending status until the previous interaction is closed. This prevents overlapping conversations and ensures consistent tracking.

To view active or completed interactions navigate to: WhatsApp Accounts → ⋮ (three dots menu) → Go to Interactions

Here you can monitor the status of each conversation:

  • Open – The contact has not replied yet.

  • Closed – The contact has sent an answer, and the interaction has been processed

 

Scenario

You configure a campaign asking:

"How would you like to be contacted?"
with quick reply buttons: Phone call | WhatsApp message | Email

  • If the customer answers within the configured Response Timeout, the system:

    • Records the selected option

    • Closes the campaign interaction → Status: Closed

    • Opens a 24-hour Customer Service Window → Status: Open (for agent follow-up). Agent can manage the conversation (by reading the sent template message and relative customer’s answer

If the customer does not respond, no further messages can be sent.
The system displays: No messages can be sent since we are waiting for the customer's response.

  • If the customer responds after the Response Timeout expiration, the campaign interaction is:

    • Closed, as it is no longer valid for the campaign