Key concepts and terms

Key concepts and terms for the Sinch Conversation API

Project

The project entity belongs to a Sinch account, acts as a container and is the root entity from the Conversation API's point-of-view. All Conversation API resources are grouped under a project.

App

The app entity, which is created and configured through the Sinch Customer Dashboard, is tied to the API user and comes with a set of channel credentials for each underlying connected channel. The app has a list of conversations between itself and different contacts which share the same project.

For more information on how to manage apps, see the App section of the API reference.

An app has the following configurable properties:

Processing modes

The processing mode, which is set at the App level, changes whether or not messages are associated with Contacts and Conversations. For more information, see Processing Mode.

Retention policy

Each App has a retention policy that specifies how long messages, sent to or from the App, are stored. The retention policy can be changed via the API by updating the corresponding app, or via the Customer Dashboard by editing the corresponding app. A retention policy is defined by the following properties:

Retention policy types

• MESSAGE_EXPIRE_POLICY - this option will remove all messages, sent or received by the app , older than the TTL days specified in the policy.
• CONVERSATION_EXPIRE_POLICY - this option only takes the last message in a conversation into consideration when deciding if a conversation should be removed or not. The entire conversation will be removed if the last message is older than the TTL days specified in the policy. The entire conversation will be kept otherwise.
• PERSIST_RETENTION_POLICY - this option persists all messages, and conversations until they're explicitly deleted. Note that this option will be subject to additional charges in the future.

Contacts

Contacts have a separate retention policy which applies at the project level and is applied to all Apps which reside within that project. The contact retention policy is configured through the dashboard.

Changes from the default retention policy require legal justification. If the change is made via the dashboard, Sinch will collect the justification. If the change is made programmatically, then the obligation is upon the client to notify Sinch of the legal justification and provide it to your account manager.

This is for your own administration, and it’s your responsibility to set legally compliant retention times. Sinch doesn't perform a legal review of your internal processes and personal data processing.

Channel credential

A channel credential is the authentication means used to authenticate against an underlying connected channel. A channel credential is tied to one app.

The order of the channel credentials registered for an app is significant. It defines the channel priority order on app level when defining which channels to send first.

The app channel priority is overridden by contact channel priority order and by message specific channel priority order. A channel credential has the following configurable properties:

Channel Integration State

A channel credential might need time to be processed. Some channels will report integration state PENDING while the process is ongoing. However, after a few seconds, or a minute at most you should see ACTIVE or FAILED.

Please observe that the following list of states is reported by the API. If you're managing a channel setup on the Customer Dashboard the states might have a slightly different name.

Message retry

The message retry mechanism allows you to handle errors gracefully by automatically retrying messages which failed during processing. Messages are retried only on temporary errors, ensuring that only transient issues trigger the retry mechanism. Permanent errors, which are unlikely to be resolved by retrying, are not subject to the automatic retry process. Messages are retried using exponential backoff with a randomized jitter. This helps prevent overwhelming the server during periods of high load.

Message retry configuration

The retry duration is configurable to meet the specific needs of your application. The system guarantees at least one retry attempt, and the retry mechanism performs a final retry attempt after the configured retry duration.

Message fallback

The message fallback mechanism allows message delivery attempts to fallback to another channel, based on channel priority, when more than one channel identity is specified in the message recipient field.

Message fallback criteria

The message fallback mechanism is triggered when any one of the following circumstances are met:

• A permanent error occurs
• The message retry duration expires
• No positive Delivery Report is received during the pre-configured time (note that this condition requires additional configuration)

Message Fallback Callback

When the fallback mechanism is triggered, customers are promptly notified through a Delivery Report with the SWITCH_ON_CHANNEL status. This callback including the failed channel identity and the reason for the fallback invocation.

Delivery Report base message fallback

Delivery Report based fallback will initiate a fallback attempt when no positive Delivery Report(that is, a Delivery Report with a status ofDELIVERED or READ) is received. This helps address uncertainty regarding the success of the message delivery.

A fallback attempt will be made using the next channel in the channel priority list.

Important Considerations The Delivery Report based fallback mechanism is an internal Conversation Api feature designed to enhance message delivery reliability. Messages already sent to channel are not cancelled. Therefore, using this feature could cause:

• Multiple Channel Deliveries: Because of the fallback mechanism, the same message may be delivered to multiple channels to ensure successful delivery.
• Billing Implications: Customers should be aware that when fallbacks occur, and messages are delivered through alternative channels, billing may apply for each of those channels. This is also true for late positive Delivery Reports that come from the base channel. It is important to consider the potential impact on billing when utilizing the fallback mechanism.

Delivery Report based message fallback configuration

The configuration options related to Delivery Report based fallback are available in the settings of your Conversation API app. By default, feature is disabled.

Delivery Report based fallback callback

When this type of fallback is triggered, customers are notified in the same way as they would be for standard fallback invocation. A Delivery Report with a status of SWITCH_ON_CHANNEL will be sent. The switch reason will contain error code DELIVERY_REPORT_TIME_OUT.

Example callback:

{
  "app_id": "01GRTRXMACYWHBKGTYE6A9BXXV",
  "accepted_time": "2023-12-12T15:00:00.000Z",
  "event_time": "2024-01-12T15:10:00.000Z",
  "project_id": "a03a7084-1e24-4ed5-978e-d7cdfbb3ceaa",
  "message_delivery_report": {
    "message_id": "01HMXZPTJ5W42FB9WWQ277M7XN",
    "conversation_id": "01GHH9A492KWBGZYB79RP1YNQ4",
    "status": "SWITCHING_CHANNEL",
    "channel_identity": {
      "channel": "VIBER",
      "identity": "bDhER5CvbuGo3/aaabbbcc==",
      "app_id": "01GRTRXMACYWHBKGTYE6A9BXXV"
    },
    "contact_id": "01GD31H6166RCTS8RNNN85QGPJ",
    "reason": {
      "code": "DELIVERY_REPORT_TIME_OUT",
      "description": "Delivery Report based fallback invoked. No positive DR received during configured time. Trying channel TELEGRAM next",
      "sub_code": "UNSPECIFIED_SUB_CODE"
    },
    "metadata": "",
    "processing_mode": "CONVERSATION"
  },
  "message_metadata": "",
  "correlation_id": ""
}

Webhook

A webhook is a POST capable URL destination for receiving callbacks from the Conversation API. Beside URL, each webhook includes a set of triggers which dictates which events are to be sent to the webhook. A webhook has the following configurable properties:

Conversation API Callbacks provides more information about managing webhooks and the format of the callbacks.

Contact

The contact entity is a collection entity that groups together underlying connected channel recipient identities. It's tied to a specific project and is therefore considered public to all apps sharing the same project.

For more specific information on how contacts are managed by the Conversation API, see the Conversation API contact management page. For information on how to manage contacts, see the Contact section of the API reference.

A contact has the following configurable properties:

Channel recipient identity

A channel recipient identity is an identifier for the contact for a specific channel. example an international phone number is used as identifier for SMS and RCS while a PSID (Page-Scoped ID) is used as the identifier for Facebook Messenger.

In the Conversation API, there are two scopes for channel identity:

• Project-scoped channel identities are considered to be unique when they have different channel and identity value pairs within the same project. Channel identities with the same identity type (for example, a phone number in the case of the SMS and WhatsApp channels) are not considered to be equivalent for different channels .
• App-scoped channel identities are considered to be unique when they specify different channels, identity values, and/or app ID. This means that contacts will have different channel identities when different app IDs are used to send requests .

Currently, following channels are using app-scoped channel identities:

• Facebook Messenger
• Viber Bot
• Instagram
• Apple Messages for Business
• LINE
• WeChat

A channel recipient identity has the following configurable properties:

Conversation

A collection entity that groups several conversation messages. It's tied to one specific app and one specific contact. For more information on how to manage conversations, see the Conversation section of the API reference.

Conversation message

An individual message, part of a specific conversation. For more information on how to send, retrieve, and manage messages, see the Messages section of the API reference.

Metadata

There are currently three entities which can hold metadata: message, conversation and contact.

The metadata is an opaque field for the Conversation API and can be used by the API clients to retrieve a context when receiving a callback from the API. Metadata fields are currently restricted to 1024 characters.

Message processing error types

There are two processing error types:

• Permanent erros
• Temporary errors

Permanent errors

Permanent errors are those that typically result from client-side issues or incorrect requests. These errors are unlikely to be resolved by retrying the same request. For example:

• Bad channel configuration

Temporary errors

Temporary errors are those that may be resolved by retrying the same request after a certain period of time. For example:

• Lack of channel availability
• Network issues during connection phase