Key concepts and terms
Key concepts and terms for the Sinch Conversation API
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.
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.
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:
|Display name||The name visible in the Customer Dashboard.|
|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.|
|Processing Mode||The processing mode changes whether or not messages are associated with Contacts and Conversations. For more information, see Processing Mode|
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||
|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 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.
|Retention Policy Types||
|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.|
While you can update the retention policy from the customer dashboard, other contact-related management tasks can be completed programmatically.
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.
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||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
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.
|State on API||State on Sinch Customer Dashboard||Meaning|
||Your channel integration with given credentials is active, available to use.|
||Your channel credentials are being process to integrate the channel. Please wait a few seconds, a minute at most, try refreshing the Sinch Dashboard.|
||Your channel integration failed, a description is provided about the cause of the failure.|
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.
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:
|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.
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:
|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|
|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.
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
- Apple Messages for Business
A channel recipient identity has the following configurable properties:
|Channel||The channel that this identity is used on|
|Channel recipient identity||The actual identity, example an international phone number, email address or alphanumeric string.|
|App id||The Conversation API's app ID if this is app-scoped channel identity. For project-scope identity this field is empty.|
A collection entity that groups several conversation messages. It's tied to one specific app and one specific contact.
An individual message, part of a specific conversation.
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.