/
Instant - Kaleyra Provider Setup

Instant - Kaleyra Provider Setup

On this page

On this page

Overview

FROM VERSION 3.34.0

Kaleyra can be integrated as a WhatsApp provider to send and receive messages through the WhatsApp channel. It supports both inbound messages and outbound campaigns via templates.
For detailed Kaleyra documentation, refer to the official guide: https://developers.kaleyra.io/docs/whatsapp-overview

Requirements

Configuration

API Key Manager

  • Navigate to Developers > API Keys in the Kaleyra dashboard.

  • You can:

    • View an existing API Key by clicking the three-dot menu > View, or

    • Generate a new API Key

image (7)-20240502-130059.jpg

By clicking on 3 dots of an existed API Key → View, make note of the following required fields details: API Domain, SID and API Key. These are necessary for integrating Kaleyra with your WhatsApp account.

image (8)-20240502-130341.jpg

 

Register your phone number

To register a phone number:

  1. Log in to the Kaleyra dashboard.

image-20240502-122312.png

  1. Navigate to Channels > WhatsApp Configuration > Manage.

image-20240502-122419.png

  1. Under the Configurations tab, find your registered number or add a new one.

image-20240502-122607.jpg

  1. Click the three-dot menu > Edit to access the following details:

image (1)-20240502-122758.jpg

  • Phone number

  • WABA ID, required for the account setup

  • Incoming URL – paste here your Receive URL copied from your WhatsApp account

  • Callback profile ID – required to receive message and template status updates

  1. To whitelist the Receive URL:

  • Go to your Kaleyra profile dropdown list → Settings

image (4)-20240502-125232.jpg

  • Click Edit Details under Enable WhatsApp Callback URLs

image-20240502-125310.png

  • Add the same Receive URL to the whitelist (so the URL is enabled the receipt of messages):

image (6)-20240502-125704.jpg

 

Callback profiles

To enable message delivery and template status updates, configure two callback profiles:

a. Incoming Messages Callback

  1. Go to your profile dropdown → Callback Profiles

  2. Click Add New

  3. Configure the following profile for the receipt of messages:

image (11)-20240502-131548.jpg

 

  • a mandatory title: insert e.g. LOCAL_INCOMING

  • Channel API: select Default

  • HTTP Method: insert POST

  • Endpoint: indicate the Receive URL, so the URL at which the callback information should be received

  • Request Body (Dynamic Variables): insert this object published by Kaleyra:

    { "message": "<message>","mime_type": "<mime_type>", "media_url": "<media_url>", "from": "<from>", "name": "<name>", "type": "<type>", "created_at": "<created_at>" }

  • Click on Save
    This callback profile becomes active immediately

 

image (12)-20240502-140855.jpg

 

b. Template Status Updates Callback

This profile may take some time to become active.

  1. Add a second callback profile to receive updates about templates status with:

    • Title: insert e.g. LOCAL_TEMPLATE

    • Channel API: select Default

    • HTTP Method: insert POST

    • Endpoint:
      https://yourmotionserver/api/whatsapp/template-messages/status/update

  • Request Body (Dynamic Variables):

    { "id": "<id>", "time": "<time>","event": "<event>", "message_template_id": "<message_template_id>", "message_template_name": "<message_template_name>", "message_template_language": "<message_template_language>", "reason": "<reason>","callback_profile_id":  "<callback_profile_id>", "company_id": "<company_id>" }

So when a new template is created, it remains in pending status. When it is approved/rejected, the update status is sent to the indicated endpoint.

Creation of WhatsApp Account on XCALLY

To create a new WhatsApp account in XCALLY:

  1. Go to WhatsApp Channel > Accounts

  2. Click Add Account and provide the following:

image (13)-20240502-144329.jpg

  • Name: custom name for the account

  • Key: unique identifier

  • List of contact manager to associate contacts

  • Proxy or Motion domain

  • Type: Kaleyra

  • Base URL: from API Keys > View > API Domain

  • WhatsApp Business Account ID: From Configurations tab > Created number > Edit > WABA ID

  • Account SID: from API Keys > View > SID

  • API Key: from API Keys > View > API Key

  • Phone Number: from Configurations > Created number > Edit > Phone Number


Templates creation

On Motion account

  • Go to WhatsApp Templates section

  • Filter by Provider: Kaleyra and optionally by Account

  • View templates with their category and status

image-20240502-153654.png

You can create a new template, by following the relative documentation at this link

Templates cannot be edited in Motion for Kaleyra, but you can edit it on Kaleyra template section.

If a template is rejected, you can create a new one in Motion or you can edit it directly on Kaleyra. In this case template approval is subject to Kaleyra review process.

 

On Kaleyra account

  • Navigate to Channels > WhatsApp > Configurations > Templates

  • Use the three-dot menu to view or Edit a template

Deletion is not supported via Kaleyra UI – deleted templates remain visible. So you can delete them only from Motion database but they remain on Kaleyra account.

image-20240502-142731.png

You can edit all parameters, except name and template category

image-20240502-142803.png

Obviously you can also add new templates, by clicking on Add template
When creating or editing a template, provide:

  • Header Text also in Sample Header Text

  • Body Content also in Sample Body Content (replace variables with static values. Templates without sample fields filled will be rejected by the system).

image-20240503-092316.png
image-20240503-092029.png