Sunshine Conversations is introducing a new suite of conversation-centric APIs that are published under a new API version (v2). The v2 API extends the platform to add new concepts and updates some of the existing ones.
Updated platform key concepts
A new Sunshine Conversations entity representing the link between a user and a conversation. Tracks which conversations a user is part of, and which of the user’s clients are attached to the conversation.
A user may participate in many conversations, and therefore there can be many participants associated with the same user object. A multi-party conversation can also have multiple participants.
Clients of type
web are now unified under a single client type called
sdk. This client represents the fact that a given user has been seen on at least one native messaging SDK. When a message is sent to a conversation for which the user has an SDK client subscribed, a push notification will be sent to all eligible devices at the same time, regardless of platform.
Clients of type
sdk can have multiple devices associated with them, allowing to track push notification tokens and information such as what operating system is used on a per-device basis. Clients of type
web in the v1 API will be automatically translated into devices in the v2 API.
The concept of webhooks as a top-level object has been replaced by a new integration type:
custom. Custom integrations represent a complete business system interacting with Sunshine Conversations in both directions. A custom integration consists of a webhook and, optionally, a set of API keys used to interact with the public API with scope
integration. Webhooks created via the v1 API will be automatically translated into custom integrations in the v2 API.
personal conversation that has been created for a user. Exists purely for backwards compatibility with existing v1 API concepts.
SDKs version prior to iOS SDK 9.0.0, Android 8.0.0 and Web SDK 5.0.0 and v1 APIs will continue to work, but will only interact with the default conversation for a given user.
A new conversation type of
sdkGroup has been introduced in order to support multi-party conversations. All existing conversations on the Sunshine Conversations platform are of type
personalconversation involves a single user and one or many business actors (formerly known as appMaker). The user is able to move freely between all channel types using any of the existing channel transfer flows.
sdkGroupconversation allows many users to communicate with each other, with or without a business actor (formerly known as appMaker) being present. Conversations of this type are limited to SDK integrations only (
web). Identified users can move freely between devices using the SDK login API, but there is no third-party channel linking supported for this conversation type.
The previous limitation of a single conversation per user has been lifted, and a user can now take part in multiple conversations (of any type) in parallel. The new conversation-centric API allows to target messages and activities per conversation instead of per user, and webhook payloads will include the
id of the conversation for which the event occurred (as well as the user that performed the action, if applicable).
You can now connect multiple instances of a channel to a single Sunshine Conversations app. For example:
See the updated integration API for more details.
The complete family of the Sunshine Conversations SDKs (iOS, Android & Web) are gaining support for the platform capabilities listed above.
The client side API of SDKs has been upgraded to expose the new concepts introduced by multi-party conversations.
The SDKs now include a conversation list UI, allowing users to navigate between their conversations. Using the SDK API you can read, update and list multiple conversations for a user. The SDKs trigger real-time events when the current user is added or removed from conversations as well as conversation-scoped events for typing and read indicators.
The list of participants for each conversation is accessible using the SDK API. The SDKs trigger real-time events when a participant is added or removed from a conversation the current user is part of.
In addition to the changes listed above, the SDKs should now be initialized using the integration’s
integrationId rather than an
The new versions also include modifications to SDKs’ current APIs. You can view the references below:
As mentioned in the new key concepts section, webhooks have been replaced by the new concept of Custom Integrations that consists of a webhook and, optionally, a set of API keys used to interact with the public API.
Read more about how to manage Custom Integrations in the reference documentation.
The v2 API introduces a new schema for webhook payloads which supports batching of events in a single webhook call. While most webhook calls will include a single event, you should now iterate over the events and ensure that your system processes them all.
The structure of a message object has been modified to more clearly delineate the different aspects of the message. The previous message structure has been re-organized and composed into multiple top-level objects including
content. This change applies both when sending messages and when retrieving them via the various GET APIs and webhook payloads.
When users are merged as a result of a login event, channel linking, or other, the merge process now accounts for the fact that a user may have multiple conversations.
For users with a verified email address, the mailgun integration will now create separate conversations when a user starts a new email thread from the same address. Previously, a new email thread would have updated the subject of the existing conversation and merged the two threads together.