Instant - SINCH V2 Provider Setup

To use WhatsApp within XCALLY, you need to enable the WhatsApp Connector in XCALLY.
Refer to the official documentation of your selected provider (e.g., Sinch) for pricing and interaction management details: find out Sinch documentation at this link.

Open

Deprecation Notice
As of September 30, 2023, SINCH has deprecated v1 of the standalone WhatsApp API:
^{“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} explore Sinch documentation₎

To USE SINCH as provider you must upgrade Motion to v 3.22.0 or later and use SINCH v2, based on the Conversation API.

Key Sections in SINCH Console

• Whatsapp – for accounts using the deprecated API.

• Conversation API – for setting up SINCH v2 (required going forward).

In the WhatsApp section, configure Senders, so phone numbers approved by Meta that can send/receive messages. Configure senders is essential for getting Whatsapp working.

✅ Only incoming messages (where agents reply) are supported in the SINCH v2 implementation.
❌ Message templates (for outbound) are not supported.

Open

1. Create a Project – Typically represents your company or customer.

2. Configure an App – Acts as an aggregator of service channels.
   Each app can only include one channel per type, and each phone number can be associated with only one app.

On SINCH we support only Instagram and Whatsapp

Two available regions, depending on customer's number:

• Use EU for European phone numbers.

• Use USA for American numbers.

If unsure about region selection, consult SINCH support.

Open

Click the created app to configure it:

• You can modify the name (not recommended action)

• Processing Mode: Must be set to Conversation Mode

It is essential to select this mode to allow Motion to reply to customer messages (otherwise, client id is not sent with the message, so messages arrive from SINCH to Motion as "Fire and forget" (so only as one-way notifications).

• On Set up channels you can setup app connections
  As reference guide to create another channel, you can use Instagram via conversation API.

Open

 

Phone Number Assignment - Whatsapp setup can only be done with SINCH.

You must request your SINCH account manager to associate the phone number with your Conversation API app, sending an email.

If you already have an account manager for WhatsApp API, you can speak with the same person.
If instead you don't have an account manager, you can request support via the Overview → Get Started section in the SINCH console.

Include in the email:

• SINCH App ID (copy it from Conversation API → Apps)

• SINCH Project ID (copy it from: Conversation API → Overview)

In Conversation API → Apps → Webhooks, add a new webhook:

Open

• Target type: HTTP

• Target url: composed by https://{MOTION_URL}/api/whatsapp/accounts/{WHATSAPP_CONNECTOR_ID}/notify
  You can find a pre-formatted URL in WhatsApp → WhatsApp Accounts → Settings → Receive URL

• Secret token: optional for added security

• Triggers: enable all available triggers

Authentication: Only via secret token (OAuth2 is not supported)

• Click on Create

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

Open

 

• Name

• Key

• Choose a List

• Proxy or Motion Domain: public ID (also attachments will be downloaded from here)

• Type = Sinch V2

• Base URL = EU or US Production (match region set in SINCH)

• SINCH Project ID to copy from Conversation API → Overview

• SINCH App ID to copy from Conversation API → Overview

• SINCH Key ID and Key Secret

Create under Settings → Access Keys → New Key
The Key Secret is shown only once—copy it immediately.
These two keys are associated to project

• 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

For Sinch V2 accounts created before version 3.46.0, agent notifications will not show the phone number by default. To include the phone number, update the notification template as follows:

Account: {{account.name}} {{#queue}}Queue: {{queue.name}} {{/queue}}From : {{contact.mobile}}

From v3.46.0 onward, the phone number will appear automatically in the agent’s notification—no template update required.

 

Open

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:

Open

 

Agents must enable the SINCH V2 WhatsApp Account to receive interactions.

Open

If you used a Whatsapp API with a configured sender, you need to migrate using SINCH V2.

Open

Send migration request by email to your SINCH account manager (to associate sender phone number to the new App project) with:

• SINCH App ID (copy it from Conversation API→ Apps)

• SINCH Project ID (copy it from Conversation API→ Overview)

Once confirmed, all messages will be routed through the new SINCH V2 account via Conversation API.

Some messages are managed as link while others as native WhatsApp messages (e.g. jpg or video).
For more information explore this page: Media Message | Conversation API | Sinch

✔️⚠️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

Open

Messages are supported only on Service mode (Business Mode, Utility and Authentication not yet supported).

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

If the customer encounters issues when sending attachments and SINCH fails to recognize or forward the message, Motion will display a generic error message.

Open

When a message fails to send, agents may encounter specific error messages. You can refer to the full list of error codes in the Sinch documentation. Below are some of the most common errors and how to address them:

CHANNEL_FAILURE: A generic error occurred at the channel level → Contact XCALLY Support for assistance.

MEDIA_TYPE_UNSUPPORTED: file type is not supported by WhatsApp. Consider that WhatsApp Business supports fewer file types than the standard WhatsApp application (e.g., .DOC, .DOCX are not supported) → Ensure that the attachment format is allowed by WhatsApp

MEDIA_TOO_LARGE : the attached file exceeds size limitations → Refer to the Guide about SINCH and Whatsapp limits

Attached weight > Motion limits > SINCH limits > Whatsapp limits → If you see this error, your file likely exceeds the Sinch or WhatsApp size limit.

MEDIA_NOT_REACHABLE: The attachment could not be retrieved. Possible causes include:

• The file has been deleted or renamed on the server.

• The file was removed after the interaction.

• While this error is not caused by a non-public URL, ensure that the HTTPS token proxy is correctly configured

BAD_REQUEST : the request is malformed or invalid → Contact XCALLY Support for further investigation.

MESSAGE_SPLIT_REQUIRED : the text message is too long → Reduce the message length and try again.

ATTACHMENT_REJECTED : the attachment was rejected by WhatsApp (Meta) → This may occur if the file type or content is not permitted by WhatsApp.

In case of messages not arriving from WhatsApp to Motion, you can check on SINCH → Conversation API → Analytics

Open

If you encounter issues such as messages sent from Motion not arriving on WhatsApp, you can follow these steps to investigate:

1. Enable Debug Mode in Motion
   This allows more detailed logging for diagnostics.

2. Check the Logs
   Review the debug logs for any errors or anomalies.

3. Send the Logs to Support
   Share the logs with our support team for further analysis.

In some cases, your WhatsApp Business account may be blocked by Meta without prior notice. Common reasons include:

• Use of unauthorized message templates

• A high number of users blocking your account

In this case Review Meta’s Business Policy Guidelines on this guide of Facebook Policy and then contact your Meta account manager.

Below, some common error codes that may hint at policy-related problems:

• RECIPIENT_NOT_OPTED_IN,

• OUTSIDE_ALLOWED_SENDING_WINDOW

• DELIVERY_REJECTED_DUE_TO_POLICY

• NO_PERMISSION

• NO_PROFILE_AVAILABLE

• INACTIVE_CREDENTIAL