Introduction to the v2 API

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.

New key concepts

Multi-Party Key Concepts

Updated platform key concepts

Participant

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.

SDK client

Clients of type android, ios and 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.

Device

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 ios, android and web in the v1 API will be automatically translated into devices in the v2 API.

Custom integration

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.

Default conversation

The first 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.

New platform capabilities

Multiple users per conversation

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 personal.

  • A personal conversation 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.
  • An sdkGroup conversation 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 (ios, android, and 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.

Multiple conversations per user

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).

Multiple instances of a channel

You can now connect multiple instances of a channel to a single Sunshine Conversations app. For example:

  • In a marketplace use case, configure two iOS SDK instances, one for customers and one for sellers in order to support separate push notification credentials for each.
  • Connect two or more WhatsApp business numbers to the same app, for example one for Europe and one for America.

See the updated integration API for more details.

New SDK versions

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.

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.

Participants

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.

Additional changes

In addition to the changes listed above, the SDKs should now be initialized using the integration’s integrationId rather than an appId.

The new versions also include modifications to SDKs’ current APIs. You can view the references below:

Webhooks are now integrations

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.

Custom Integration

Read more about how to manage Custom Integrations in the reference documentation.

Redesigned webhook payloads

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.

New message object structure

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 author, source, and content. This change applies both when sending messages and when retrieving them via the various GET APIs and webhook payloads.

Updated user merge logic

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.