ON THIS PAGE:

Table of Contents

minLevel	1
maxLevel	3
outline	false
type	list
printable	false

Image Removed

You can connect Whatsapp with Motion in two official different ways: Twilio and SINCH via Conversation API, (doing a migration from Whatsapp API to Conversation API, if you already use Whatsapp Connector)

SINCH account

Image Added

Note

By the end of September 2023 v1 SINCH version will be deprecated as indicate in the official SINCH portal:^{[...]“Support for the standalone WhatsApp API will end on September 30, 2023. New customers must use, and existing customers must migrate to, the WhatsApp channel of the Conversation API. Any migration must be completed prior to September 30, 2023}..^{[...] “}
_{(for more information}https://developers.sinch.com/docs/whatsapp/migration-guide/overview/₎

To continue using SINCH provider you must upgrade Motion to v 3.22.0 and use SINCH v2.

SINCH account

Image Removed

There are two important sections on SINCH:

Whatsapp (“old section” for Whatsapp API)
Conversation API → new section to configure SINCH v2

On Whatsapp section you can access to Senders, so telephone numbers approved by Meta which can receive and send new interactions. Configure senders is essential for getting Whatsapp working.

Senders can have associated Message Templates, so predefined messages approved by Meta that can be used to start new interactions with customers.

Info
In current implementation, templates are not supported in Conversation API, only incoming chats from Whatsapp where agents reply are supported

How to configure a Whatsapp Channel on Conversation API

You need to create a Project: company or partner’s customer
Configure app which can be considered like an aggregator of service channels. App can have 1 channel of each type, but 1 telephone number allows only the creation of 1 app.
On SINCH we support only Instagram and Whatsapp
two available regions, USA and EU, depending on customer's number: insert EU if it is an European number or USA if it is an American number

Info
If you have doubts about region, you can ask to SINCH support

Clicking on the created app, you can edit it from configuration section, by modifying the name (not recommended action)
Processing Mode: Conversation mode

Note
It is essential to select this mode to allow Motion to reply to customer messages (without it, client id is not sent with the message, so messages arrive from SINCH to Motion as "Fire and forget" (so only as notification).

On Set up channels you can setup app connections
As reference guide to create another channel, you can use Instagram via conversation API.
Officially, we support only Whatsapp and Instagram via Conversation API

Whatsapp setup can only be done with SINCH.

You need to ask to your account manager to associate phone number to this app, sending an email to your account manager.
If you already have contacts with Whatsapp API, you can speak with the same account manager, otherwise you can request contact from Overview section → Get Started

In your email for account manager, you have to send your:

SINCH App ID: you can copy it from Conversation API→ Apps
SINCH Project ID: you can copy it from Conversation API→ Overview

How Admin can configure SINCH on Motion

Create a Webhook

First of all you need to insert Motion URL in Apps section → Webhooks
To create a new webhook you can click on Add Webhook

target type: HTTP
target url: composed by https://{MOTION_URL}/api/whatsapp/accounts/{WHATSAPP_CONNECTOR_ID}/notify
If not sure, there is a cortesy URL ready to be copy pasted in Whatsapp Connector → Whatsapp Accounts → Settings → Receive URL
secret token for security to prevent a third element from sending messages
triggers: you must add all available triggers

Info
OAuth2 authentication is not supported, authentication is via secret token

Click on Create

Create a new Whatsapp Account

On Motion, as Admin you can create a new Whatsapp Account from WhatsApp Connector section.

Name
Key
Choose a List
Proxy or Motion Domain: public ID (important also for attachments that will be downloaded from here)
Type = Sinch V2
Base URL = EU Production or US Production which must be equal to region inserted in app
SINCH Project ID to copy from Conversation API → Overview
SINCH App ID to copy from Conversation API → Overview
SINCH Key ID to create in Settings → Access Keys → New Key

Note
When you create a New Key, you will view a visible Key ID and a Key Secret which will disappear, so you need to copy it immediately to insert it on Motion. These two keys are associated to project

SINCH Key Secret value from Settings → Access Keys
SINCH webhook optional added security token: secret token created before
Phone: phone number inserted in SINCH with prefix ( Conversation API → Apps)
Optional description

And click ADD

Then you need to add agents or queue to the created Whatsapp Account to manage interactions.

Editing the account, you can see on Settings → General → Receive URL your url including tokens.

To change settings you can edit them in Advanced section:

Use Whatsapp Connector with SINCH for Agents

For Agents, the feature is available on Whatsapp Connector section, from which they have to select accounts.
In fact agents need to enable the new created account connected to SINCH V2 to receive new interaction from this account

How to migrate from Whatsapp API to Conversation API

If you want to migrate using SINCH V2, it means that you have already a Whatsapp API with a configured sender and approved templates

On SINCH side you need to:

Configure a Conversation API Project, creating:
- Project
- App on SINCH
- Api Key / Key Secret

(These parameters are essential to configure the new Whatsapp Connector Account on Motion side)

Create Webhook App in SINCH Conversation API → Apps → Webhooks and in target url you can insert: https://{MOTION_URL}/api/whatsapp/accounts/{WHATSAPP_CONNECTOR_ID}/notify

On Motion side, you should have already a Whatsapp Account with Whatsapp API.

To avoid service interruptions, we suggest you create a new Whatsapp Account SINCH V2. Be careful that once the migration will take place, messages arrive on the new account (For reports it’s important to consider it, because you will find interaction only on this new account). So you need to create a new onewith the same:
- settings: list, notification template, transfer options, routing parameters, dispositions, canned answer
- action flow
- associated queue and agents. It’s very important to add permissions to agents to allow the receiving of interactions

Info
Useful Tip: you can create a queue, by associating both the old and the new account, so you are sure that all interactions will arrive in the queue and when the switch will be complete, there will be continuity on the queue

In this account you need to insert parameters related to SINCH Conversation API Project (SINCH Project ID, SINCH App ID, API Key, Key Secret) created before
Moreover you need to copy Motion Url, Whatsapp Connector ID account and secret token to configure Webhook App on SINCH side

Then you must ask to your account manager to switch from Whatsapp API to SINCH V2 (to associate sender phone number to the new App project) sending by email:

SINCH App ID: you can copy it from Conversation API→ Apps
SINCH Project ID: you can copy it from Conversation API→ Overview

When account manager confirms migration finalisation, messages will pass via Conversation API

Note
Remember that after migration interactions will be available only on SINCH V2 Account (and not more on old one). Moreover old interactions will not continue on the new account, even if the phone number will be the same. Check that you have correctly added agents and action flow for the successful reception of interactions

Troubleshooting

Whatsapp messages don't arrive to SINCH	SINCH messages don't arrive to Motion	Motion doesn't open interaction	Whatsapp attachment doesn't arrive to SINCH
Verify if number is blocked by META and check SINCH Analytics	Check https, webhook url, webhook events, webhook secret, check if motion account ID is correct, set motion to debug and check logs	Check admin open interactions, assigned agents and assigned queue	Not all attachments are available for whatsapp business, check motion debug logs

Attachments is not saved to motion	Motion can't send messages to Whatsapp	Motion attachment refused by Whatsapp	Motion can't send messages to SINCH
Check Motion disk space, check Whatsapp account proxy url and proxy token settings	Check SINCH analytics failed messages, check Motion debug logs	Some attachment types can't be sent on Whatsapp. A link will be used if possible, if not use another channel like email	Check Whatsapp account SINCH settings

Supported attachment

Some messages are managed as link while others as native whatsapp messages (e.g. jpg or video).
For more information explore this page: https://developers.sinch.com/docs/conversation/message-types/media-message/#whatsapp

✔️⚠️CSV → shown as link

❌DOC → Error CHANNEL_FAILURE

❌GIF → Error CHANNEL_FAILURE (GIF not allowed because not supported by Meta)

✔️JPG → shown as media with preview

✔️MP3 → shown as audio with preview

✔️MP4 → shown as video with preview

✔️⚠️PDF → shown as link

✔️PNG → shown as media with preview

❌WAV → Error BAD_REQUEST

✔️DLL → shown as link

❌EXE → Error BAD_REQUEST

If there are issues sending attachment, a system message appears

Supported messages

Messages are supported only on Service mode (Business Mode, Utility and Authentication are work in progress).

Messages are supported only on Conversation Mode (not dispatch mode)

If there are issues by customer side to send attachments and SINCH doesn’t recognise the message and it doesn’t send it, on Motion a general message error appears

You can explore here errors shown to the agent when a send message fails https://developers.sinch.com/docs/conversation/callbacks/#error-codes, including:
CHANNEL_FAILURE → you can contact XCALLY Support
MEDIA_TYPE_UNSUPPORTED --> file type not supported by Whatsapp. Remember that Whatsapp Business has some file types non allowed compared to traditional Whatsapp (e.g. not supported DOC, DOCX)
MEDIA_TOO_LARGE → you can check on this guide to know SINCH and Whatsapp limits
https://developers.sinch.com/docs/conversation/channel-support/whatsapp/message-support/
Attached weight > Motion limits > SINCH limits > Whatsapp limits
When you see this error, you are exceeding your SINCH or Whatsapp limit
MEDIA_NOT_REACHABLE → possible reasons: file deleted or renamed on the server, file deleted by interaction.
It cannot be caused by non-public url but you can check however that https token proxy is correct
BAD_REQUEST → you can contact XCALLY Support
MESSAGE_SPLIT_REQUIRED → too long text
ATTACHMENT_REJECTED → Error by Whatsapp Meta Side, attachment not allowed

Messages don’t arrive from Whatsapp to Motion

If messages don’t arrive from Whatsapp to Motion, you can check what happens on
SINCH → Conversation API → Analytics

In case of issues (e.g. message from Motion don’t arrive on Whatsapp), you can:
set Motion in debug mode
check logs and send them to us

Account blocked by Meta

It’s possible that Whatsapp Business is blocked without warning by Meta (e.g. if an unauthorised template was used or a user blocked you)

In this case you can check this guide of Facebook Policy and then contact your account manager.

Possible errors on Meta site which can hint about issues with Meta policies:

RECIPIENT_NOT_OPTED_IN,
OUTSIDE_ALLOWED_SENDING_WINDOW
DELIVERY_REJECTED_DUE_TO_POLICY
NO_PERMISSION
NO_PROFILE_AVAILABLE
INACTIVE_CREDENTIAL

Other possible errors: (you can explore details at the page https://developers.sinch.com/docs/conversation/callbacks/#error-codes )

Network errors, try again later:

RATE_LIMITED
DELIVERY_TIMED_OUT
MESSAGE_EXPIRED
CHANNEL_REJECT

SINCH configuration errors:

RECIPIENT_NOT_REACHABLE
CHANNEL_BAD_CONFIGURATION
CHANNEL_CONFIGURATION_MISSING
NO_CHANNELS_LEFT
TEMPLATE_NOT_FOUND
TEMPLATE_INSUFFICIENT_PARAMETERS
TEMPLATE_NON_EXISTING_LANGUAGE_OR_VERSION
UNKNOWN_APP
NO_CHANNEL_IDENTITY_FOR_CONTACT

XCALLY code errors, contact support:

RECIPIENT_INVALID_CHANNEL_IDENTITY
CHANNEL_FAILURE
CONTACT_NOT_FOUND
BAD_REQUEST
UNSUPPORTED_OPERATION
UNKNOWN
INTERNAL_ERROR

Versions Compared

Old Version 18

New Version 19

Key

SINCH account

SINCH account

How to configure a Whatsapp Channel on Conversation API