Versions Compared

Old Version 2

changes.mady.by.user XCALLY Knowledge

Saved on

compared with

New Version Current

changes.mady.by.user Product Knowledge

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
ON THIS PAGE:

On this page

Table of Contents
minLevel1
maxLevel
3info
2
outlinefalse
stylenone
typelist
printablefalse
Image Removed

We currently have several systems to connect Whatsapp with Motion. This can be useful so if a channel does not work, it’s possible to apply a work around on another system.

Now you can connect Whatsapp with Motion in two official different ways: Twilio and Sinch via conversation API, doing a Switch from Whatsapp API to Conversation API

Note

Consider that to use WhatsApp, on XCALLY side you need to enable the connector, while for interactions management you need to consult the official documentation of the selected provider to check prices: find out Sinch documentation at this link

📋 What’s about

Image Added
Image Removed
Note

By the end of September 2023 v1 Sinch SINCH version will be deprecated as indicate in the official Sinch 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 SINCH provider you must upgrade Motion to v 3.22.0 and use Sinch SINCH v2.

Switch from Whatsapp API to Conversation API

There are 2 two important sections on SinchSINCH:

  • 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

Only incoming chats from Whatsapp where agents reply are supported

How to associate a sender and configure a Whatsapp Channel on Conversation API

Image Removed
you

in Conversation API implementation (not message templates for outbound)

⚙️ Configuration

Image Added

  • 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.
    If e.g. you need a chat for reservations and a chat for information you have to configure 2 apps, but if you need Telegram and Whatsapp Channels you can use the same app

Info

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 SINCH support

  • Clicking on the created app, you can edit it from configuration section, by modifying the name but is (not recommended to do thataction)

  • 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 SINCH to Motion as "Fire and forget" (so only as notification).

Image Removed

  • On Set up channels you can configure 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 SinchSINCH.

You need to ask to your account manager to associate the 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 the Overview section → Get Started

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

  • Sinch SINCH App ID: you can copy it from Conversation API→ Apps (Sender identity is the ID approved by Meta)Sinch

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

If you

How to configure Sinch on Motion

(blue star) Requirements

Image Removed
Panel
bgColor
#FFEBE6
#EAE6FF
☑️

  • The Motion instance must

be

  • have a public address accessible via HTTPS

☑️

  • . For security reasons we strongly recommend to use a Reverse Proxy → find out more

  • Motion instance must have valid certificate

url di motion inserito in app in webhooks
ADD WEBHOOK tipo hhtp
url nell'url composto da nome nominio

  • License with Whatsapp Channel enabled


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

Image Added
3 che è id dell'account wa connector / notify
secret token per sicurezza per impedire che 3° si metta a mandare msg
triggers = mettere tt
non supportata OAuth2
autenticazione tramite secret token
create

account whatsapp in motion
admin
nuovo account
name
ip pubblico importante per allegati che verranno scaricati da qui
type synch v2
eu stessa region dell'app
SINCH project ID copiare da synch
key e secret da creare in settings access key new key dare nome confirm
mostrato key id e key secret key id rimane visibile, secret scompare da copiare subito da copiare in motion
associati a project queste 2 key
token da webhook
phone messo in synch con prefisso

aggiungere coda o agenti
url comprensivo di proxy token
per modificare impostazioni in advanced

template prossimamente mostrati come template

Agente
funzionalità è su WA connector
si sceglie account abilitare
nuova chat +
se cliente nuovo solo tramite templates
msg che arriva e si apre interazione

cliente può creare synch v2
fasi per migrazione: si fa configurazione app su synch conversation api poi si chiede con synch di cambiare n° sender o creare sender nuovo associando sender ad app project
numero migrato su nuova
avere prima di chiedere prodotto
prima di passaggio avere project su coversation api
app su conversation apri
webhook
api key
lato motion bisogno di motion con https account configurato lato admin con synch v2 e relative code
richiesta a synch di associare da wa api a conversation api

MIGRAZIONE
mda quando account manger conferma migrazione msg passano tramite conversation API
da account 1 si passa a 2
trovano interazioni su account 2
per evitare interruzioni serizio da fare account 2
una volta avvenuta migrazione msg arrivano su nuovo account
non interruzioni servizio!!
ricordati agenti aggiunti a coda WA devi metterli anche di qua!!
stesse action flow e stessi permessi agli agenti e stesse code

wa API
OTTIENI UN SENDER
APPROVAZIONE TEMPLATE

SINCH CONVERSATION PROJECT--> configura project / app / api key in setting / copia key value
con questi parametri configura WA connector

da synch vecchio usa stessa lista contatti / parametri instradamento / notification template / transfer setting / disposition / canned answer / actions routing / agenti / code
PRo tip: fai una coda con i due account associati alla coda così sei sicuro che interazioni arrivano in coda e quando fatto switch vedi continuità sulla stessa coda
attenzione che ci saranno nuove interazioni su nuovo account, non continuano quelle vecchie anche se stesso n° per problema tecnico di conversation api
dopo aver importare tutto com'era nel vecchio
indirizzo https pubblico motion
id account - wa connector - secret del webhook
coinfugrare webhook - app conversation api sinch

in sinch conversation api --> apps --> webhooks
in target url mettere codice id

chiediamo poi a sinch . email richiesta ad account manager di sinch - meta di cambiare da WA API a sinch
fornire APP ID e project ID

dopo ok msg arrivano su nuovo account

problemi comuni:
msg errore wa riceviamo in ritardo e non è legato a msg
xm-683
parte allegati: alcuni msg gestiti come link altri come msg nativo di wa (jpg o png)
supportati solo modalità service: cliente chiama, motion risponde
template modalità nusiness, utilitiy e autetnthcial work in progress

se ci sono problemi con invio allegato compare msg di sistema
se problemi da parte del cliente a invio su motion compare message error
problemi legati al fatto che utente manda allegato, sinch non riconosce msg e non invia (errore generico)
troubleshooting problemi comuni
media not reachable = alcuni file non supportati
controlalre https token proxy
gif non allowed non supportate da meta
non arrivano msg da wa a motion --> analytics su sinch e si vede cosa succede in failed message
controllare che wa account fatto bene in parti sinchsettings
in advanced
mettere motion in modalità debug
controllare log e inviarci in caso di problemi

msg da motion non arrivano su wa -->
mettere motion in modalità debug
controllare log e inviarci in caso di problemi

controllare sent messages su analytics
controllare api key in settings(nel caso se ne può creare una nuova)

potresti essere stato bloccato da meta (limnk fb policy)
wa business può bloccare senza preavviso, scritta guida e contattare account manager
(es. template non consentito o utente ti ha bloccato)
se tutte configurazioni apposto controllare qst

  • {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.

Image Added

  • 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.

Image Added

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:

Image Added

👥 Use Whatsapp Connector with SINCH for Agents

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

Image Added

⚙️ 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

Image Added

On the SINCH side you need to:

(These parameters are essential to configure the new Whatsapp Connector Account on the 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 the Motion side, you should have already a Whatsapp Account with Whatsapp API.

  • (warning) 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

    • (info) 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 the Webhook App on the 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

(tick) 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

Image Added

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 the customer side to sending attachments and SINCH doesn’t recognise the message and it doesn’t send it, on Motion a general message error appears

Image Added

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

Image Added

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