There are 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.

• 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

• 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

• 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

• 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

• 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

• Click on Create

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

On Synch the SINCH side you need to:

• Configure a Conversation API Project, creating:

  • Project

  • App on Sinch SINCH

  • Api Key / Key Secret

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

• Create Webhook App in Sinch conversation 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, environment accessible via HTTPS, you should have already have a Whatsapp Account with old SinchWhatsapp API.

• To avoid service interruptions, we suggest you create a new Whatsapp Account Sinch 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

• In this account, you need to insert parameters related to Sinch SINCH Conversation API Project (Sinch SINCH Project ID, Sinch 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 Sinch the SINCH side

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