Configuring Sinch Conversation API

When using Sinch Conversation API as a messaging service, you should configure all webhooks with a secret to enable digital signature verification in Sinch Contact Pro. Configure the same webhook secret in Sinch Contact Pro to use this secret to verify the digital signature.

In Sinch Conversation API, webhooks are configured per app, and each webhook has its own secret. In the System Configurator (SC) application, only a single webhook secret can be configured per messaging service and it applies to all apps within that messaging service. But if your project extends over multiple messaging services, one webhook secret per service is needed. For example, if you have apps in different regions but the project is the same, you need to configure two messaging services.

Note:
  • When you create your app in Sinch Build, select Conversation mode as the processing mode.
  • If you are setting up a SMS channel, inform Sinch of the phone number you want to use for outbound SMS messages. Currently, you cannot configure this number yourself.

Prerequisites

You have created and configured your project and apps API in Sinch Build (https://dashboard.sinch.com/login). For instructions, see https://developers.sinch.com/docs/conversation. Note that while the integration with Sinch Conversation API is built in, it's an additional service billed separately from Sinch Contact Pro.

Procedure

  1. Go to System Management > Messaging Services.

  2. Choose Add New and sinchconversation.

  3. In the Basics block, enter:

    • name for your service
    • service connection of format https://[landscape either eu or us].conversation.api.sinch.com/v1/projects/[project ID]/messages:send

  4. In the Authentication block, define authentication for outbound messaging (consisting of key ID and app ID) and inbound messaging (webhook).

    Note:
    Create a separate entry for both outbound and inbound messaging.
    1. For outbound messaging, enter
      • authentication ID: Format is [Key ID]@[App ID]

        You get the Key ID from Settings > Access Keys.

        app ID is in Conversation API > Apps.

      • password: Use the secret in Settings > Access keys > Access key list.

    2. For inbound messaging, enter

      • authentication ID: webhook
      • password: Use the secret token in Conversation API > Apps > [the app] > Webhook > Secret token
      • triggers:
        • MESSAGE_INBOUND is mandatory. Without it, your system won't receive any messages.
        • MESSAGE_DELIVERY is required for showing:
          • delivery status notifications to agents in Communication Panel
          • delivery errors
          • quoted messages to agents in Communication Panel
        • EVENT_INBOUND is for Sinch Chat to enable customers to end chat.

      The target URL depends on your region and is one of the following:

      Data center region URL
      Europe https://login-eu-c1.cc.sinch.com/[tenantname]/sms/sinchconversation/all
      North America https://login-na-w2.cc.sinch.com/[tenantname]/sms/sinchconversation/all
      Africa [https://login-af-s1.cc.sinch.com/[[tenantname]/sms/sinchconversation/all]
      Australia [https://login-au-s2.cc.sinch.com/[[tenantname]/sms/sinchconversation/all]

      If you don't know your region, you can get it from the Communication Panel URL. Or you can contact Sinch using the request type Inquiry in the support portal.

  5. Save your new messaging service.
  6. Go to Queue Management > Queues and create a chat queue.

    The queue address in the Numbers/Addresses block is of format [app ID]@[subchannel].sinchconversation.com, for example:

    • WhatsApp: 01E4556565565ERKYO@whatsapp.sinchconversation.com
    • Sinch Chat: 01EB17K24DRDHH07FVSSG00WEN@nativechannel.sinchconversation.com
    • Facebook: 01F49FCDPK4V1F1WJCE8DM1MBH@facebook.sinchconversation.com
    • Viber Bot: 01F44FCDPK2V6F1WJCE5DM1MBH@viber-bot.sinchconversation.com
    • Instagram: 01F39FCDPK7V8F1WJCE8DM1MBH@instagram.sinchconversation.com
    • Viber: 01F29FCDPK2V6F1WJCE8DM1MBH@viber.sinchconversation.com
    • Telegram: 01F39FCDPK2V5F1WJCE8DM1MBH@telegram.sinchconversation.com
    • Line: 01F85FCDPK2V8F1WJCE8DM1MBH@line.sinchconversation.com
    • Google RCS: 01F82FCDPK2V8F1WJCE8DM1MBH@rcs.sinchconversation.com
    • SMS: 01ER4ABSP36WG80BMAR2CN1XEY@sms.sinchconversation.com
    Make sure to capitalize the letters in the app ID when you enter it. Sinch Conversation API generates app IDs in capital letters and the System Configurator must use the same format in the queue address and messaging service configuration.

    For US numbers you also need to enter the SMS sender ID.