Conversation API callbacks

This page covers registering webhooks and listening to callbacks from the Sinch Conversation API.

Testing your solution

Certain webhook test services, like https://webhook.site/, Beeceptor, and https://collect2.com/, can be used when trialing a Conversation API solution.

However, these services should only be used for testing purposes. Using the Conversation API can generate high volumes of callback traffic (including multiple delivery states per message, MO reply messages, and more), which can easily exceed the TPS limits of certain webhook services. These high volumes can result in queuing, latency, and rejections of callbacks, which can negatively impact the performance of your Conversation API solution. Additionally, sensitive information may be included in the callback, including message content and contact information.

Ensure that you use a scalable and secure callback/webhook processor after your initial testing is complete.

Webhook Management

The Conversation API delivers contact messages, delivery receipts for app messages and various notifications through callbacks.

API clients can create fine-grained subscriptions for up-to 5 endpoints (webhooks) per conversation API app through the Sinch Portal or by using the /webhooks management endpoint.

Each webhook represents a subscription for events defined by a list of triggers. The events are delivered by the Conversation API to the webhook target URL. The callbacks are signed with the webhook secret if such is provided. The signature can be used to verify the authenticity and integrity of the callbacks.

Webhook Triggers

Each webhook can subscribe to one or more of the following triggers:

• MESSAGE_INBOUND - subscribe to inbound messages from end users on the underlying channels.
• EVENT_INBOUND - subscribe to inbound events (for example, composing events) from end users on the underlying channels.
• MESSAGE_DELIVERY - subscribe to delivery receipts for app messages sent on Conversation API channels.
• MESSAGE_SUBMIT - subscribe to message submission notifications for app messages sent on Conversation API channels.
• EVENT_DELIVERY - subscribe to delivery receipts for events sent on Conversation API channels.
• CONVERSATION_START - subscribe to the conversation start events.
• CONVERSATION_STOP - subscribe to conversation stop events.
• CONVERSATION_DELETE - subscribe to conversation deleted events.
• CONTACT_CREATE - subscribe to contact create events.
• CONTACT_DELETE - subscribe to contact delete events.
• CONTACT_MERGE - subscribe to contact merge events.
• CONTACT_UPDATE - subscribe to contact update events.
• CAPABILITY - this trigger is used to receive the results of asynchronous capability checks .
• OPT_IN - subscribe to opt-in events .
• OPT_OUT - subscribe to opt-out events .
• CONTACT_IDENTITIES_DUPLICATION - subscribe to notifications about contact identity duplications found during message or event processing.
• CHANNEL_EVENT - subscribe to channel event notifications.
• RECORD_NOTIFICATION - subscribe to record notifications.
• UNSUPPORTED - subscribe to receive channel callbacks that are not natively supported by the Conversation API .
• UNSPECIFIED_TRIGGER : using this value will cause errors.

Smart Conversations Triggers

In addition to the standard webhooks, you may also configure your solution to subscribe to the SMART_CONVERSATION or MESSAGE_INBOUND_SMART_CONVERSATION_REDACTION webhooks. These triggers allows you to subscribe to payloads that:

• Provide machine learning analyses of inbound messages from end users on the underlying channels (in the case of the SMART_CONVERSATION webhook)
• Deliver redacted versions of inbound messages (in the case of the MESSAGE_INBOUND_SMART_CONVERSATION_REDACTION webhook)

Smart Conversation trigger

The SMART_CONVERSATION webhook delivers the results of the machine learning analyses. For information on the structure of the callback, see Smart Conversations callbacks.

Message Inbound Smart Conversation Redaction trigger

The MESSAGE_INBOUND_SMART_CONVERSATION_REDACTION webhook delivers messages as the MESSAGE_INBOUND webhook does, but the content of the message has been analyzed and masked (or blocked, in some cases) based on the results of the analysis. For information on the structure of the callback, see Message Inbound Smart Conversation Redaction callback

Creating webhooks using the API

The snippet below demonstrates how to create a webhook using the management API. The webhook registers a POST capable endpoint with URL {{WEBHOOK_URL}} to receive inbound messages and delivery receipts for app with ID {{APP_ID}} and project with ID {{PROJECT_ID}}.

curl -X POST \
'https://eu.conversation.api.sinch.com/v1/projects/{{PROJECT_ID}}/webhooks' \
-H 'Content-Type: application/json' --header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-d '{
 "app_id": "{{APP_ID}}",
 "target": "{{WEBHOOK_URL}}",
 "target_type": "HTTP",
 "triggers": ["MESSAGE_DELIVERY", "MESSAGE_INBOUND"]
}'

Validating Callbacks

Conversation API callbacks triggered by a registered webhook, with a secret set, will contain the following headers:

The receiver of signed callbacks should execute the code found in the following example, after replacing the commented values in the example with their values:

var crypto = require('crypto')

var secret = 'foo_secret1234' // secret used when creating a webhook; replace with your own value

//actual raw message; replace with your own value
var rawBody = '{"app_id":"","accepted_time":"2021-10-18T17:49:13.813615Z","project_id":"e2df3a34-a71b-4448-9db5-a8d2baad28e4","contact_create_notification":{"contact":{"id":"01FJA8B466Y0R2GNXD78MD9SM1","channel_identities":[{"channel":"SMS","identity":"48123456789","app_id":""}],"display_name":"New Test Contact","email":"new.contact@email.com","external_id":"","metadata":"","language":"EN_US"}},"message_metadata":""}'

var nonce = '01FJA8B4A7BM43YGWSG9GBV067' //x-sinch-webhook-signature-nonce; replace with your own value
var timestamp= 1634579353 //x-sinch-webhook-signature-timestamp; replace with your own value

var signedData = rawBody + '.' + nonce + '.' + timestamp
var signature = crypto.createHmac('sha256', secret).update(signedData).digest('base64')

console.log("calculated-signature     : " + signature)
console.log("x-sinch-webhook-signature: 6bpJoRmFoXVjfJIVglMoJzYXxnoxRujzR4k2GOXewOE=")

import base64
import hashlib, hmac

secret = 'foo_secret1234' #secret used when creating a webhook; replace with your own value

#actual raw message; replace with your own value
body = '{"app_id":"","accepted_time":"2021-10-18T17:49:13.813615Z","project_id":"e2df3a34-a71b-4448-9db5-a8d2baad28e4","contact_create_notification":{"contact":{"id":"01FJA8B466Y0R2GNXD78MD9SM1","channel_identities":[{"channel":"SMS","identity":"48123456789","app_id":""}],"display_name":"New Test Contact","email":"new.contact@email.com","external_id":"","metadata":"","language":"EN_US"}},"message_metadata":""}'

nonce = '01FJA8B4A7BM43YGWSG9GBV067' #x-sinch-webhook-signature-nonce; replace with your own value
timestamp= 1634579353 #x-sinch-webhook-signature-timestamp; replace with your own value

signed_data = body + '.' + nonce + '.' + str(timestamp)

digest = hmac.new(secret.encode('utf-8'), signed_data.encode('utf-8'), hashlib.sha256).digest()

print('calculated signature     : ' + base64.b64encode(digest).decode())
print('x-sinch-webhook-signature: 6bpJoRmFoXVjfJIVglMoJzYXxnoxRujzR4k2GOXewOE=')

Callback Format

Each callback dispatched by Conversation API has a JSON payload with the following top-level properties:

Each specific callback type adds additional properties to the payload which are described in detail in the section below.

Inbound Message

This callback delivers contact (end-user) messages to the API clients. The message details are given in a top level message field (or message_redaction in case of redacted messages). It's a JSON object with the following properties:

Metadata assigned to the conversation, if any, is provided in the top level message_metadata string field.

For example, a string representation of the metadata_json field value of a Create conversation request, or the value assigned to the conversation_metadata field in a Send message request. The last value provided in any of those fields is returned, replacing any previous value, if present.

Example of Inbound Message Callback

{
  "app_id": "01EB37HMH1M6SV18ABNS3G135H",
  "accepted_time": "2020-11-16T08:17:44.993024Z",
  "event_time": "2020-11-16T08:17:42.814Z",
  "project_id": "c36f3d3d-1523-4edd-ae42-11995557ff61",
  "message": {
    "id": "01EQ8235TD19N21XQTH12B145D",
    "direction": "TO_APP",
    "contact_message": {
      "text_message": {
        "text": "Hi!"
      }
    },
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "2742085512340733",
      "app_id": "01EB37HMH1M6SV18ABNS3G135H"
    },
    "conversation_id": "01EQ8172WMDB8008EFT4M30481",
    "contact_id": "01EQ4174TGGY5B1VPTPGHW19R0",
    "metadata": "",
    "accept_time": "2020-11-16T08:17:43.915829Z",
    "sender_id": "12039414555",
    "processing_mode": "CONVERSATION",
    "injected": false
  },
  "message_metadata": "{\"arbitrary\": \"json object stringify as metadata\" }",
  "correlation_id": "correlation-id-1"
}

Redacted Messages

Inbound messages can also be delivered using the MESSAGE_INBOUND_SMART_CONVERSATION_REDACTION webhook trigger, where the content of the message goes through an A.I. analysis and is redacted if required. It is possible to use this trigger instead of the MESSAGE_INBOUND, which will deliver a payload with a message_redaction field instead of a message, allowing you to easily differentiate the callbacks:

{ "message": { "contact_message": "..." } }

{ "message_redaction": { "contact_message": "..." } }

For information on the structure of the callback, see Message Inbound Smart Conversation Redaction callback

Contact Message

The table below shows the properties of the contact_message field in inbound message callbacks:

It also contains one of the following properties depending on the type of message: text_message, media_message, location_message, choice_response_message, media_card_message, fallback_message, product_response_message, channel_specific_message.

All of these properties are JSON objects described in the sections below.

Text Message

Media Message

For channels with a "Share Contact" feature, you will receive the MO as a media_message containing a URL where you can collect a vCard formatted file as a standard media_message. Standard retention will apply.

Location Message

Coordinates

Choice Response Message

The choice response message represents a contact response to a choice message.

Media Card Message

Contact Message containing media and caption.

Fallback Message

Fallback message, appears when original contact message can't be handled.

Reply To

The Reply To field contains a reference to the message that the corresponding contact message is responding to. This field is only set if the responding contact message was sent within 3 days of the original message. This feature is only supported on the following channels: WhatsApp, Telegram, Messenger, Instagram, and Viber BM.

Product Response Message

Product Item

Channel Specific Message

Contact Message containing a message of a channel-specific message type (not supported by OMNI types) from a specific channel.

Interactive Nfm Reply

This object represents the message content of a nfm_reply message type.

Nfm Reply

Channel Identity

The table below shows the properties of the channel_identity field in Conversation API callbacks:

App-scoped Channel Identities

Currently, Facebook Messenger, Viber Bot, Instagram, Apple Messages for Business, LINE and WeChat channels are using app-scoped channel identities which means contacts will have different channel identities for different apps. For example, Facebook Messenger uses PSIDs (Page-Scoped IDs) as channel identities. The app_id is pointing to the app linked to the Facebook page for which this PSID is issued.

Inbound Event

This callback delivers channel events such as composing to the API clients. The message details are given in a top level event field. It's a JSON object with the following properties:

Example of Inbound Event Callback

Below is an example of an inbound event callback. This is a standard example in which the contact_event object is populated:

{
  "app_id": "01EB37HMH1M6SV18ABNS3G135H",
  "accepted_time": "2020-11-16T08:17:44.993024Z",
  "event_time": "2020-11-16T08:17:42.814Z",
  "project_id": "c36f3d3d-1523-4edd-ae42-11995557ff61",
  "event": {
    "id": "01GJMQ28NDF6FP0REWQ70N2W3E",
    "direction": "TO_APP",
    "contact_event": {
      "composing_event": {}
    },
    "channel_identity": {
      "channel": "RCS",
      "identity": "123456789",
      "app_id": ""
    },
    "contact_id": "01EQ4174TGGY5B1VPTPGHW19R0",
    "conversation_id": "01GJMQ3782FWM7TKAZKQZAEF56",
    "accept_time": "2020-11-16T08:17:43.915829Z",
    "processing_mode": "CONVERSATION"
  }
}

Below is an alternative example of the inbound event callback with the contact_message_event object populated:

{
  "app_id": "01EB37HMH1M6SV18ABNS3G135H",
  "accepted_time": "2020-11-16T08:17:44.993024Z",
  "event_time": "2020-11-16T08:17:42.814Z",
  "project_id": "c36f3d3d-1523-4edd-ae42-11995557ff61",
  "event": {
    "id": "01GJMQ28NDF6FP0REWQ70N2W3E",
    "direction": "TO_APP",
    "contact_message_event": {
      "payment_status_update_event": {
        "reference_id": "testing-payment-sep1",
        "payment_status": "PAYMENT_STATUS_UNKNOWN",
        "payment_transaction_status": "PAYMENT_STATUS_TRANSACTION_SUCCESS",
        "payment_transaction_id": "payment-transaction-id1"
      }
    },
    "channel_identity": {
      "channel": "RCS",
      "identity": "123456789",
      "app_id": ""
    },
    "contact_id": "01EQ4174TGGY5B1VPTPGHW19R0",
    "conversation_id": "01GJMQ3782FWM7TKAZKQZAEF56",
    "accept_time": "2020-11-16T08:17:43.915829Z",
    "processing_mode": "CONVERSATION"
  }
}

Contact Event

The table below shows the properties of the contact_event field in inbound event callbacks:

Contact Message Event

The table below shows the properties of the contact_message_event field contained within inbound event callbacks:

Payment Status Update Event

The table below shows the properties of the payment_status_update_event field that is contained within the contact_message_event object:

The payment_status field can have the following values:

• PAYMENT_STATUS_UNKNOWN - The status value was not set. Treat it as null or not present field
• PAYMENT_STATUS_NEW - The user has sent an MT payment message, but the recipient didn’t start a payment yet
• PAYMENT_STATUS_PENDING - The recipient has started the payment process
• PAYMENT_STATUS_CAPTURED - The payment was captured
• PAYMENT_STATUS_CANCELED - The payment was canceled by the recipient and no retry is possible
• PAYMENT_STATUS_FAILED - The payment attempt failed, but the recipient can retry

The payment_transaction_status field can have the following values:

• PAYMENT_STATUS_TRANSACTION_UNKNOWN - The transaction status value was not set. Treat it as null or not present field
• PAYMENT_STATUS_TRANSACTION_PENDING - The transaction started
• PAYMENT_STATUS_TRANSACTION_FAILED - The transaction failed
• PAYMENT_STATUS_TRANSACTION_SUCCESS - The transaction completed successfully.
• PAYMENT_STATUS_TRANSACTION_CANCELED - The transaction has been cancelled (by either the recipient or the user/business).

Shortlink Activated Event

The table below shows the properties of the shortlink_activated_event field that is contained within the contact_message_event object:

Reaction event

The table below shows the properties of the reaction_event field that is contained within the contact_message_event object:

The action field can have the following values:

• REACTION_ACTION_UNKNOWN - Unrecognized type of action
• REACTION_ACTION_REACT - User placed some emoji reaction
• REACTION_ACTION_UNREACT - User removed previously placed emoji reaction

Message Delivery Receipt

This callback notifies the API clients about status changes of already sent app message. The delivery receipt details are given in a top level message_delivery_report field. It's a JSON object with the following properties:

Additional metadata, if any, is provided in the top level message_metadata string field. This is specific to the underlying channel used. Refer to the individual channels' documentation for more information. For example, SMS delivery receipts.

Example of Message Delivery Receipt

The example below shows a receipt for successfully enqueued message with ID 01EQBC1A3BEK731GY4YXEN0C2R on MESSENGER channel:

{
  "app_id": "01EB37HMH1M6SV18BSNS3G135H",
  "accepted_time": "2020-11-17T15:09:11.659Z",
  "event_time": "2020-11-17T15:09:13.267185Z",
  "project_id": "c36f3d3d-1513-2edd-ae42-11995557ff61",
  "message_delivery_report": {
    "message_id": "01EQBC1A3BEK731GY4YXEN0C2R",
    "conversation_id": "01EPYATA64TMNZ1FV02JKF12JF",
    "status": "QUEUED_ON_CHANNEL",
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "2734085512340733",
      "app_id": "01EB27HMH1M6SV18ASNS3G135H"
    },
    "contact_id": "01EXA07N79THJ20WSN6AS30TMW",
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

When the sending of the message failed the receipt includes a reason object describing the error:

{
  "app_id": "01EB37HMH1M6SV18BSNS3G135H",
  "accepted_time": "2020-11-17T16:01:06.374Z",
  "event_time": "2020-11-17T16:01:07Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "message_delivery_report": {
    "message_id": "01EQBF0BT63J7S1FEKJZ0Z08VD",
    "conversation_id": "01EQBCFQR3EGE60P42H6H1117J",
    "status": "FAILED",
    "channel_identity": {
      "channel": "WHATSAPP",
      "identity": "12345678910",
      "app_id": ""
    },
    "contact_id": "01EXA07N79THJ20WSN6AS30TMW",
    "reason": {
      "code": "OUTSIDE_ALLOWED_SENDING_WINDOW",
      "description": "The underlying channel reported: Message failed to send because more than 24 hours have passed since the customer last replied to this number",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": ""
  },
  "message_metadata": ""
}

Delivery Status

The field status is included in delivery receipt callbacks and shows the status of the message or event delivery. The status field can have the following values:

• QUEUED_ON_CHANNEL
• DELIVERED
• READ
• FAILED
• SWITCHING_CHANNEL

Each message and event sent by the API clients to contacts go through the following states:

1. A message has the QUEUED_ON_CHANNEL status once it is successfully dispatched to an underlying channel.
2. A delivery receipt is sent from the underlying channel detailing the delivery status on the channel. Depending on the channel response and the processing state of the message, the message is transitioned to one of following states:
   • DELIVERED - the channel delivery receipt indicates the message has reached the end user. Some channels can subsequently send new delivery receipts with a READ status.
   • READ - the channel delivery receipt indicates the message was seen or read by the end user. This is a terminal state. There are no more state changes after the message reaches the READ state. Some channels will omit sending a delivery receipt with a DELIVERED state when the message is seen immediately by the user. In such cases, the DELIVERED status is implicit.
   • FAILED - the channel delivery receipt indicates the message delivery failed and there are no more channels to try according to the channel priority defined in the send request. This is a terminal state. There are no more state changes after the message reaches the FAILED state.
   • SWITCHING_CHANNEL - the channel delivery receipt indicates that message delivery failed. However, there are more channels through which the Conversation API can try to send the message according to the channel priority defined in the send request.

Reason

The reason field in FAILED or SWITCHING_CHANNEL delivery receipt callbacks provides information for the reason of the failure.

The table below shows the properties of the reason field:

Error Codes

Conversation API provides a set of common reason codes which can be used to automate the error handling by the API clients. The codes are as follow:

• RATE_LIMITED - the message or event wasn't sent due to rate limiting.
• RECIPIENT_INVALID_CHANNEL_IDENTITY - the channel recipient identity was malformed.
• RECIPIENT_NOT_REACHABLE - it wasn't possible to reach the contact, or channel recipient identity, on the channel.

  Note:

  When using the WhatsApp channel, you may receive this error code if you send a marketing template message to a recipient, and the recipient is part of the current WhatsApp marketing message experiment.

• RECIPIENT_NOT_OPTED_IN - the contact, or channel recipient identity, hasn't opted in on the channel.
• OUTSIDE_ALLOWED_SENDING_WINDOW - the allowed sending window has expired. See the channel support documentation for more information about how the sending window works for the different channels.
• CHANNEL_FAILURE - the channel failed to accept the message. The Conversation API performs multiple retries in case of transient errors.
• CHANNEL_BAD_CONFIGURATION - the channel configuration of the app is wrong. The bad configuration caused the channel to reject the message.
• CHANNEL_CONFIGURATION_MISSING - the referenced app has no configuration for the channel. This may be considered an internal error .
• MEDIA_TYPE_UNSUPPORTED - indicates that the sent message had an unsupported media type.
• MEDIA_TOO_LARGE - some of the referenced media files are too large. See the channel support documentation to find out the limitations on file size that the different channels impose.
• MEDIA_NOT_REACHABLE - the provided media link wasn't accessible from the Conversation API or from the underlying channels. Please make sure that the media file is accessible.
• NO_CHANNELS_LEFT - no channels to try to send the message to. This error will occur if all applicable channels have been attempted. This may be considered an internal error .
• TEMPLATE_NOT_FOUND - the referenced template wasn't found. This may be considered an internal error .
• TEMPLATE_INSUFFICIENT_PARAMETERS - not all parameters defined in the template were provided when sending a template message.
• TEMPLATE_NON_EXISTING_LANGUAGE_OR_VERSION - the selected language, or version, of the referenced template didn't exist. Please check the available versions and languages of the template.
• DELIVERY_TIMED_OUT - the message or event delivery failed due to a channel-imposed timeout.
• DELIVERY_REJECTED_DUE_TO_POLICY - the message or event was rejected by the channel due to a policy. Some channels have specific policies that must be met to send a message. See the channel support documentation for more information about when this error will be triggered.
• CONTACT_NOT_FOUND - the provided Contact ID didn't exist. This can be considered an internal error .
• BAD_REQUEST - Conversation API validates send requests in two different stages. The first stage is right before the message is enqueued. If this first validation fails the API responds with 400 Bad Request and the request is discarded immediately. The second validation kicks in during message processing and it normally contains channel specific validation rules. Failures during second request validation are delivered as callbacks to MESSAGE_DELIVERY (EVENT_DELIVERY) webhooks with ReasonCode BAD_REQUEST .
• UNKNOWN_APP - missing app. This error may occur when the app is removed during message processing. This can be considered an internal error .
• NO_CHANNEL_IDENTITY_FOR_CONTACT - the contact has no channel identities for the resolved channel priorities. This can be considered an internal error .
• NO_PERMISSION - Check the configuration of the underlying channel (Facebook Messenger or Instagram) to ensure that it has the correct permissions set to be able to access the profile or the page.
• NO_PROFILE_AVAILABLE - Facebook Messenger profile information cannot be retrieved for accounts created using a phone number.
• UNSUPPORTED_OPERATION - Generic failure and/or unsupported operation. This can be considered an internal error . Contact Support.
• INACTIVE_CREDENTIAL - The channel specified has not yet completed provisioning or provisioning has failed. Note that a channel is not usable on a Conversation API app until it enters an "active" state. This can be considered an internal error .
• MESSAGE_EXPIRED - The TTL has expired for this message. This can be considered an internal error .
• MESSAGE_SPLIT_REQUIRED - The message exceeds the length limit, or other dimensional constraint(s), of the channel. The message must be split into multiple, smaller segments. This can be considered an internal error .
• DELIVERY_REPORT_TIME_OUT - This error occurs when a positive delivery report for a message is not received within the specified time. Review the Delivery Report Based Fallback .
• CHANNEL_REJECT - generic error for channel permanently rejecting a message.
• UNKNOWN - returned if no other code can be used to describe the encountered error.
• INTERNAL_ERROR - an internal error occurred. Please save the entire callback if you want to report an error.

Internal errors

Some of the above errors can be categorized as "internal errors". These include:

• CHANNEL_CONFIGURATION_MISSING
• NO_CHANNELS_LEFT
• TEMPLATE_NOT_FOUND
• CONTACT_NOT_FOUND
• UNKNOWN_APP
• NO_CHANNEL_IDENTITY_FOR_CONTACT
• UNSUPPORTED_OPERATION
• INACTIVE_CREDENTIAL
• MESSAGE_EXPIRED
• MESSAGE_SPLIT_REQUIRED

These errors occur before the message is queued on a particular channel. If you encounter these errors, note that the QUEUED_ON_CHANNEL status will not be generated for the corresponding message. Other, non-internal errors occur before and after the message reaches the QUEUED_ON_CHANNEL status.

Error Sub-Codes

The sub_code field is a more detailed classification of the main error. These sub-codes can differ between channels, and may be supplied by the channel itself.

Below are sub-codes that can correspond to errors associated with messages sent on any channel:

• UNSPECIFIED_SUB_CODE - used if no other sub code can be used to describe the encountered error.
• ATTACHMENT_REJECTED - occurs when the message attachment has been rejected by the channel due to a policy. Some channels have specific policies that must be met to receive an attachment.

Message Submit Notification

This callback provides a notification to the API clients that the corresponding app message was submitted to a channel. This notification is created before any confirmation from Delivery Receipts. The message submission details are given in a top level message_submit_notification field. It's a JSON object with the following properties:

Additional metadata, if any, is provided in the top level message_metadata string field. This is specific to the underlying channel used. Refer to the individual channels' documentation for more information. For example, SMS delivery receipts.

Example of Message Submit Notification

The example below shows a notification for a submitted message with ID 01EQBC1A3BEK731GY4YXEN0C2R on the MESSENGER channel:

{
   "app_id":"01EB37HMH1M6SV18BSNS3G135H",
   "accepted_time": "2020-11-17T15:09:11.659Z",
   "event_time": "2020-11-17T15:09:13.267185Z",
   "project_id":"c36f3d3d-1513-2edd-ae42-11995557ff61",
   "message_submit_notification":{
      "message_id":"01EQBC1A3BEK731GY4YXEN0C2R",
      "conversation_id":"01EPYATA64TMNZ1FV02JKF12JF",
      "channel_identity":{
         "channel":"MESSENGER",
         "identity":"2734085512340733",
         "app_id":"01EB27HMH1M6SV18ASNS3G135H"
      },
      "contact_id":"01EXA07N79THJ20WSN6AS30TMW",
      "submitted_message":{
         "text_message":{
            "text":"Hello from Conversation API!"
         }
      },
      "metadata":"",
      "processing_mode":"CONVERSATION"
   },
   "message_metadata":""
}

Event Delivery Receipt

This callback notifies the API clients about status changes of already sent app events. The delivery receipt details are given in a top level event_delivery_report field. It's a JSON object with the following properties:

Example of Event Delivery Callback

{
  "app_id": "01EB37HMH1M6SV18BSNS3G135H",
  "accepted_time": "2020-11-17T15:09:11.659Z",
  "event_time": "2020-11-17T15:09:13.267185Z",
  "project_id": "c36f3d3d-1513-2edd-ae42-11995557ff61",
  "event_delivery_report": {
    "event_id": "01EQBC1A3BEK731GY4YXEN0C2R",
    "status": "QUEUED_ON_CHANNEL",
    "channel_identity": {
      "channel": "MESSENGER",
      "identity": "2734085512340733",
      "app_id": "01EB27HMH1M6SV18ASNS3G135H"
    },
    "contact_id": "01EXA07N79THJ20WSN6AS30TMW",
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}

Conversation Start

This callback is sent when a new conversation between the subscribed app and a contact is started. The conversation details are given in a top level conversation_start_notification field. It's a JSON object with the following properties:

Example of Conversation Start Callback

{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "project_id": "c36f3d3d-1523-4edd-ae42-11995557ff61",
  "conversation_start_notification": {
    "conversation": {
      "id": "01EQ4174WMDB8008EFT4M30481",
      "app_id": "01EB37HMH1M6SF18ASNS3G135H",
      "contact_id": "01BQ8174TGGY5B1VPTPGHW19R0",
      "active_channel": "MESSENGER",
      "active": true,
      "metadata": ""
    }
  }
}

Conversation Stop

This callback is sent when a conversation between the subscribed app and a contact is stopped. The conversation details are given in a top level conversation_stop_notification field. It's a JSON object with the following properties:

Example of Conversation Stop Callback

{
  "app_id": "01EB37HMH1M6SV17ASNS3G135H",
  "project_id": "c36f3d3d-1523-4edd-ae42-11995557ff61",
  "conversation_stop_notification": {
    "conversation": {
      "id": "01EPYATZ64TMNZ1FV02JKD12JF",
      "app_id": "01EB37HMH1M6SV17ASNS3G135H",
      "contact_id": "01EKA07N79THJ20WAN6AS30TMW",
      "last_received": "2020-11-17T15:09:12Z",
      "active_channel": "MESSENGER",
      "active": false,
      "metadata": ""
    }
  }
}

Contact Create

This callback is sent when a new contact is created. The contact details are given in a top level contact_create_notification field. It's a JSON object with the following properties:

Example of Contact Create Callback

{
  "app_id": "",
  "accepted_time": "2020-11-17T15:36:28.155494Z",
  "project_id": "c36f3a3d-1513-4edd-ae42-11995557ff61",
  "contact_create_notification": {
    "contact": {
      "id": "01EQBDK8771J6A1FV8MQPE1XAR",
      "channel_identities": [
        {
          "channel": "VIBER",
          "identity": "9KC0p+pi4zPGFO99ACDxdQ==",
          "app_id": "01EB37KMH1M6SV18ASNS3G135H"
        }
      ],
      "channel_priority": ["VIBER"],
      "display_name": "Unknown",
      "email": "",
      "external_id": "",
      "metadata": "",
      "language": "UNSPECIFIED"
    }
  }
}

Contact Delete

This callback is sent when a contact is deleted. The contact details are given in a top level contact_delete_notification field. It's a JSON object with the following properties:

Example of Contact Delete Callback

{
  "app_id": "",
  "accepted_time": "2020-11-17T15:44:33.517073Z",
  "project_id": "c36f3a3d-1513-4edd-ae42-11995557ff61",
  "contact_delete_notification": {
    "contact": {
      "id": "01EQBDK8771J6A1FV8MQPE1XAR",
      "channel_identities": [
        {
          "channel": "VIBER",
          "identity": "9KC0p+pi4zPGFO99ACDxdQ==",
          "app_id": "01EB37HMH1M6SV13ASNS3G135H"
        }
      ],
      "channel_priority": ["VIBER"],
      "display_name": "Unknown",
      "email": "",
      "external_id": "",
      "metadata": "",
      "language": "UNSPECIFIED"
    }
  }
}

Contact Update

This callback is sent when a contact is updated. The full updated contact details are given in a top level contact_update_notification field. It's a JSON object with the following properties:

Example of Contact Update Callback

{
  "app_id": "",
  "accepted_time": "2020-11-17T15:44:33.517073Z",
  "project_id": "c36f3a3d-1513-4edd-ae42-11995557ff61",
  "contact_update_notification": {
    "contact": {
      "id": "01EQBDK8771J6A1FV8MQPE1XAR",
      "channel_identities": [
        {
          "channel": "VIBER",
          "identity": "9KC0p+pi4zPGFO99ACDxdQ==",
          "app_id": "01EB37HMH1M6SV13ASNS3G135H"
        }
      ],
      "channel_priority": ["VIBER"],
      "display_name": "Unknown",
      "email": "",
      "external_id": "",
      "metadata": "",
      "language": "UNSPECIFIED"
    }
  }
}

Contact Merge

This callback is sent when two contacts are merged. The details of the resulting merged and deleted contacts are given in a top level contact_merge_notification field.

It's a JSON object with the following properties:

Example of Contact Merge Callback

{
  "app_id": "",
  "accepted_time": "2020-11-17T15:53:03.457706Z",
  "project_id": "c36f3a3d-1513-4edd-ae42-11995557ff61",
  "contact_merge_notification": {
    "preserved_contact": {
      "id": "01EQBECE7Z4XP21359SBKS1526",
      "channel_identities": [
        {
          "channel": "VIBER",
          "identity": "9KC0p+pi4zPGFO99ACDxdQ==",
          "app_id": "01EB37KMH1M6SV18ASNS3G135H"
        }
      ],
      "channel_priority": ["VIBER"],
      "display_name": "Unknown",
      "email": "",
      "external_id": "",
      "metadata": "",
      "language": "UNSPECIFIED"
    },
    "deleted_contact": {
      "id": "01EQBEH7MNEZQC0881A4WS17K3",
      "channel_identities": [
        {
          "channel": "VIBER",
          "identity": "9KC0p+pi4zaGFO99ACDxdQ==",
          "app_id": "01EB37KMH1M6SV18ASNS3G135H"
        }
      ],
      "channel_priority": ["VIBER"],
      "display_name": "Unknown",
      "email": "",
      "external_id": "",
      "metadata": "",
      "language": "UNSPECIFIED"
    }
  }
}

Contact Identities Duplication Notification

This callback is sent when duplicates of channel identities are found between multiple contacts in the contact database during message and event processing.

When a duplicate is identified, you must use the contact endpoint to resolve the issue. This notification points to the contacts which should be deleted, updated, or merged to resolve the duplication issue.

It's a JSON object with the following properties:

For more information on contact duplication, see our documentation on Conversation API contact management.

Example of Contact Identities Duplication Notification

{
  "app_id": "01EB37KMH2M6SV18ASNS3G135H",
  "accepted_time": "2022-09-29T09:16:22.544813845Z",
  "event_time": "2022-09-29T09:16:22.544813845Z",
  "project_id": "c36f3a3d-1513-4edd-ae42-11995557ff61",
  "duplicated_contact_identities_notification": {
    "duplicated_identities": [
      {
        "channel": "channel",
        "contact_ids": [
          "01EKA07N79THJ20ZSN6AS30TMW",
          "01EKA07N79THJ20ZSN6AS30TTT"
        ]
      }
    ]
  },
  "message_metadata": ""
}

Capability Check

This callback is used to deliver the results of the asynchronous capability checks. The outcome of the capability check is given in a top level capability_notification field.

It's a JSON object with the following properties:

The possible values for capability_status are explained below:

• CAPABILITY_UNKNOWN : the channel capability for the contact is unknown because the underlying channel has not made this information available.
• CAPABILITY_FULL : the specified contact supports all the features of the channel.
• CAPABILITY_PARTIAL : the specified contact supports a subset of the channel features.
• NO_CAPABILITY : the specified contact supports none of the channel features.

Example of Capability Check Callback

{
  "app_id": "01EB37KMH2M6SV18ASNS3G135H",
  "accepted_time": "2020-11-17T16:05:51.724083Z",
  "project_id": "",
  "capability_notification": {
    "contact_id": "01EKA07N79THJ20ZSN6AS30TMW",
    "identity": "12345678910",
    "channel": "WHATSAPP",
    "capability_status": "CAPABILITY_FULL",
    "request_id": "01EQBF91XWP9PW1J8EWRYZ1GK2"
  }
}

Opt-in

This callback is used to deliver opt-in notifications from the channels.

The opt-in details are given in a top level opt_in_notification field with the following properties:

The possible values for status are explained below:

• OPT_IN_STATUS_UNSPECIFIED : the underlying channel doesn't support Opt-in.
• OPT_IN_SUCCEEDED : the Opt-in registration succeeded.
• OPT_IN_FAILED : the Opt-in registration failed, see reason in error_details field.

Example of Opt-in Callback

{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2021-06-08T07:54:03.165316Z",
  "event_time": "2021-06-08T07:54:02.112Z",
  "project_id": "",
  "opt_in_notification": {
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "channel": "VIBERBM",
    "identity": "123456789",
    "status": "OPT_IN_SUCCEEDED",
    "request_id": "01F7N9TEH11X7B15XQ6VBR04G7",
    "processing_mode": "CONVERSATION"
  }
}

Opt-out

This callback is used to deliver opt-out notifications from the channels.

The opt-out details are given in a top level opt_out_notification field with the following properties:

The possible values for status are explained below:

• OPT_OUT_STATUS_UNSPECIFIED : the underlying channel doesn't support Opt-out.
• OPT_OUT_SUCCEEDED : the Opt-out registration succeeded.
• OPT_OUT_FAILED : the Opt-out registration failed, see reason in error_details

Example of Opt-out Callback

{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2021-06-08T07:54:03.165316Z",
  "event_time": "2021-06-08T07:54:02.112Z",
  "project_id": "",
  "opt_out_notification": {
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "channel": "VIBERBM",
    "identity": "123456789",
    "status": "OPT_OUT_SUCCEEDED",
    "request_id": "01F7N9TEH11X7B15XQ6VBR04G7",
    "processing_mode": "CONVERSATION"
  }
}

Channel Event

This callback is used to deliver notifications regarding channel-specific information and updates. For example, if your are using the WhatsApp channel of the Conversation API, and your quality rating has been changed to GREEN, a POST would be made to the CHANNEL_EVENT webhook.

The event details are given in a top level channel_event field with the following properties (note that the channel_event field is under the channel_event_notification field):

Example of Channel Event Callback

{
  "channel": "WHATSAPP",
  "event_type": "WHATS_APP_QUALITY_RATING_CHANGED",
  "additional_data": {
    "quality_rating": "GREEN"
  }
}

Unsupported Callback

Some of the callbacks received from the underlying channels might be specific to a single channel or may not have a proper mapping in Conversation API yet. In such cases the callbacks are forwarded as is all the way to the API clients subscribed to the UNSUPPORTED webhook trigger.

The source of the unsupported callback is given in a top level unsupported_callback field. It's a JSON object with the following properties:

Example of Unsupported Callback

Example of an unsupported callback without the contact_id, conversation_id, or channel_identity fields:

{
  "app_id": "01EB37HMF1M6SV18ASNS3G135H",
  "accepted_time": "2020-11-17T15:17:05.723864Z",
  "event_time": "2020-11-17T15:17:05.683253Z",
  "project_id": "c36f3a3d-1513-4edd-ae42-11995557ff61",
  "unsupported_callback": {
    "channel": "MESSENGER",
    "payload": "{\"object\":\"page\",\"entry\":[{\"id\":\"107710160841844\",\"time\":1605626225304,\"messaging\":[{\"sender\":{\"id\":\"107710160841844\"},\"recipient\":{\"id\":\"2744085512340733\"},\"timestamp\":1605626225228,\"message\":{\"mid\":\"m_CE0r2yTXOPe1DG_cepCqA9eapH28NipZLg3HuKNf-MA_Edr55tBwvLiTzhrvjZJWQioE4J4gpETQZBTREc7Hdg\",\"is_echo\":true,\"text\":\"Text message from Sinch Conversation API.\",\"app_id\":477442439539985}}]}]}",
    "id": "01FMAVK07YN3SP1B43FP9D1C0S",
    "contact_id": "",
    "conversation_id": "",
    "processing_mode": "CONVERSATION"
  }
}

Example of an unsupported callback with the contact_id, conversation_id, and channel_identity fields:

{
  "app_id": "01EB37HMF1M6SV18ASNS3G135H",
  "accepted_time": "2021-11-12T19:53:54.728511Z",
  "event_time": "2021-11-12T19:53:54.542308Z",
  "project_id": "c36f3a3d-1513-4edd-ae42-11995557ff61",
  "unsupported_callback": {
    "channel": "APPLEBC",
    "payload": "{\"interactiveData\": ... }",
    "id": "01FMAVDCKE8TNN021VN7XQ1VG2",
    "contact_id": "01FMAVAPAQTEGDJSFJJWANRX38",
    "conversation_id": "01FMAVAQBTR4C1HJZS05PVTXZ8",
    "channel_identity": {
      "channel": "APPLEBC",
      "identity": "urn:mbid:AQAAX12RO5I+XVVAhq2b0S22ohAOSfSB+aZkybPFk6iOaMdgrXXstADziEHz/f/x8cA=",
      "app_id": "01EB37HMF1M6SV18ASNS3G135H"
    },
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": ""
}