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 Portal, 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.

Webhooks, which the app is attached to, defines the destination for various events coming from the Conversation API. An app has the following configurable properties:

Field Description
Display name The name visible in the Sinch Portal.
Conversation metadata report Specifies the amount of conversationmetadata that's returned as part of each callback.
Retention Policy The retention policy specifies how long messages, sent to or from an app, are stored by the Conversation API.

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 Sinch Portal by editing the corresponding app. A retention policy is defined by the following properties:

Field Description
Retention Policy Types MESSAGE_EXPIRE_POLICY - This is the default policy. This option will remove all messages, sent or received by the app, that are older than the TTL days specified in the policy.
TTL days The days before a message or conversation is eligible for deletion. The allowed values are 1,3650 and the default value is 180 days.

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 Contect retention policy is configured through the dashboard.

Field Description
Retention Policy Types CONTACT_EXPIRE_POLICY - This is the default policy. This option will remove all contacts and associated conversations and messages, sent or received by the app, that are older than the TTL days specified in the policy.
TTL days The days before a message or conversation is eligible for deletion. The allowed values are 1,3650 and the default value is Persist.

Together with the retention policy, contacts can also be managed through the CRUD function described here.

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:

Field Description
Channel Which channel these credentials are used with.
Credential Specifies the type and values for the credentials used for a channel.
Callback Secret Optional. A secret for certain channels where Conversation API can validate callbacks coming from the channels.

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 Sinch Portal the states might have a slightly different name.

State on API State on Sinch Portal Meaning
ACTIVE ACTIVE Your channel integration with given credentials is active, available to use.
PENDING ACTIVATING CHANNEL Your channel credentials are being process to integrate the channel. Please wait a few seconds, a minute at most, try refreshing the Sinch Dashboard.
FAILING FAILED Your channel integration failed, a description is provided about the cause of the failure.
Warning

Please observe that FAILING state can happen after ACTIVE state in certain cases:

You integrated Facebook Messenger or Instagram with a Facebook Page, and without removing the integration on the Sinch Dashboard you revoked the permission you granted to Sinch to manage your page. In this case your Messenger/Instagram credentials become invalid as per Facebook's point of view, and you need to grant these permissions again. The FAILING state will provide a description to you about this problem as well.

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:

Field Description
Target The target URL where events should be sent to
Target type Type of the target URL. Currently only DISMISS and HTTP are supported values. DISMISS indicates the events won't be sent
Secret Optional secret to be used to sign the content of Conversation API callbacks. Can be used to verify the integrity of the callbacks. See Validating Callbacks for details.
Triggers A set of triggers that this webhook is listening to. Example triggers include MESSAGEDELIVERY for message delivery receipts and MESSAGEINBOUND for inbound contact messages

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. A contact has the following configurable properties:

Field Description
Channel identities List of channel identities specifying how the contact is identified on underlying channels
Channel priority Specifies the channel priority order used when sending messages to this contact. This can be overridden by message specific channel priority order.
Display name Optional display name used in chat windows and other UIs
Email Optional Email of the contact
External id Optional identifier of the contact in external systems
Metadata Optional metadata associated with the contact.

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.

Some channels use app-scoped channel identity. Currently, Facebook Messenger and Viber Bot are using app-scoped channel identities, which means contacts will have different channel identities for different apps.

For Facebook Messenger this means that the contact channel identity is associated with the app linked to the Facebook page for which this PSID is issued. A channel recipient identity has the following configurable properties:

Field Description
Channel The channel that this identity is used on
Channel recipient identity The actual identity, example an international phone number or email address.
App id The Conversation API's app ID if this is app-scoped channel identity.

Conversation

A collection entity that groups several conversation messages. It's tied to one specific app and one specific contact.

Conversation message

An individual message, part of a specific conversation.

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.