WhatsApp Kaleyra Provider Setup

📋 What’s about

It is possible to use Kaleyra as provider to receive and send message on WhatsApp channel.
Kaleyra allows to receive inbound messages and create templates for outbound campaigns.
For more information about Kaleyra you can also explore documentation at this link https://developers.kaleyra.io/docs/whatsapp-overview

Requirements

You have to create an account on http://Kaleyra.io , by following the official guide: https://developers.kaleyra.io/docs/create-an-account-in-kcloud
You need to register a phone number on http://eu.kaleyra.io
You need to generate an API Key (follow the steps published below)

⚙️ Configuration

API Key Manager

In Developers section → API Keys you can see the created API key or you can Generate a new API Key

By clicking on 3 dots of an existed API Key → View, it is possible to see the different details, like API Domain, SID and API Key, so three required fields for the account creation

Register your phone number

You need to register your phone number, by entering in Kaleyra dashboard

And then select Channels section → WhatApp configuration → Manage

On Configurations tab, you can find on numbers section the configured numbers (or you can add a new one)

By clicking the 3 dots menu → Edit you will see this information:

Phone number
WABA ID, required for the account creation
Incoming URL where you have to insert the Receive URL copied from your WhatsApp account
Callback profile ID to enable the receipt of messages and the updates of templates status

Then from your Kaleyra profile, on dropdown list, you need to open Settings

And on Enable WhatsApp Callback URLs click on Edit details

And insert the same receive URL (in this way the URL is considered in whitelist to enable the receipt of messages):

Callback profiles

To create a callback profile, on your profile settings drop-down list, you have to select Callback profiles option

You need to add, by clicking on Add new, 2 new profiles.

First of all on Callback Profile window you have to create a profile for the receipt of messages:

a mandatory title (e.g. LOCAL_INCOMING)
As Channel API, you need to select Default
As HTTP Method, you have to insert POST
As Endpoint, you must indicate the Receive url, so the URL at which the callback information should be received
As Request body in Dynamic Variables the object published by Kaleyra:
{"message": "<message>","mime_type": "<mime_type>",
"media_url": "<media_url>", "from": "<from>",
"name": "<name>", "type": "<type>",
"created_at": "<created_at>"}
And click on Save

The callback profile to receive message is active instantly

Then you need to create the callback profile to receive updates about templates status (which needs a little more time to be active). So you can indicate:

Title (e.g. LOCAL_TEMPLATE)
select channel API: default
HTTP Method: POST
Endpoint:
https://yourmotionserver/api/whatsapp/template-messages/status/update
Dynamic variables with this static body:
{"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 and when it is approved/rejected, the update status is sent to the indicated endpoint

💡 Creation of WhatsApp Account on XCALLY

On WhatsApp Connector → Accounts you can create a new account, by inserting:

Name
Key
List of contact manager to associate contacts
Proxy or Motion domain
Type: Kaleyra provider
Base URL that you can copy from Developers section → API Keys (viewing the created one) where you can find API domain
WhatsApp Business Account ID, that you can find On Configurations tab → created number → 3 dots menu → edit → WABA ID
Account SID that you can copy from Developers section → API Keys (viewing the created one) where you can find SID
API Key that you can copy from Developers section → API Keys (viewing the created one)
Phone Number, that you can find On Configurations tab → created number → 3 dots menu → edit → Phone number

Templates creation

On Motion account

On WhatsApp Templates section, you can filter for Kaleyra Provider and if you want also for Account. You can see the list of templates with relative category and status

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

If you need to edit a Kaleyra template, you can’t modify it from Motion, but you can edit it on Kaleyra template section.
Moreover if for example on Motion you have a rejected template, you can create a new template on Motion or you can edit it on Kaleyra: in this case template could become approved after check

On Kaleyra account

On Channels → WhatsApp → Configurations → Templates it is possible to see the templates created on Motion. By clicking on 3 dots menu you can view or edit a specific template. Moreover for Kaleyra it is not possible to delete templates so you can delete them only from Motion database but they remain on Kaleyra account.

Obviously you can also add new templates, by clicking on Add template
If you create or edit template on Kaleyra, you have to insert Header Text also in Sample Header Text and content in Body field and copy it also in Sample Body, by replacing the variable with a value, otherwise the system will not accept it