Multi-Party Early Access Guide

Overview

Multi-party conversations allow multiple users to participate in a conversation with each other, with or without a business actor present to enable a full range of new use cases that were not possible on the Sunshine Conversations platform previously.

Multi-Party Overview

The multi-party conversations early access program offers a suite of conversation-centric APIs, published under a new major API version: v2. The v2 API introduces new key concepts and evolutionary changes to the v1.1 API such as multiple conversations per user and multiple users per conversation. Along with the new API suite, we are also publishing new versions of our iOS, Android and Web SDKs.

Use cases

Multi-sided conversations

Enable more sophisticated conversations between multiple parties inside and outside your organization and loop in customer support with full context to streamline resolutions.

For marketplace companies, you can now connect buyers, sellers, riders, drivers into a conversation about a specific marketplace transaction (e.g. order, booking, ride) and programmatically add the right participants at the right time to streamline customer support.

For insurance and financial services companies, you can now facilitate conversations between third parties like insurance brokers, advisors, or portfolio managers and clients and centrally own the conversation record with every customer. For healthcare and life sciences companies, you can now create multi-sided conversations between primary care doctors, specialists, nurses, insurance providers, patients, and family members to more seamlessly deliver a great healthcare experience.

Group conversations & communities

Facilitate support conversations between a group of users to drive real-time engagement and deliver more specialized customer experiences.

For travel & hospitality companies, loop entire families or groups of travelers into a single conversation with hosts, guides, transportation services, and hotel staff to streamline communications and deliver more personalized services for every group member. For software & gaming companies, you can now create topic-based conversational forums for users to exchange tips, tricks, and best practices across every product in your portfolio, with escalation to nominated super-users and customer support when needed.

Internal messaging & collaboration

Make it easy for internal teams to collaborate to manage schedules, coordinate logistics, and solve complex multi-department support issues in real-time.

For manufacturing & logistics companies, facilitate conversations between dispatched drivers in the field, shift supervisors, warehouse employees, and more to drive efficiency and streamline complex operations. For retail & hospitality companies, connect on-the-floor staff with shift supervisors, inventory managers, kitchen staff, and more to coordinate schedules, deliveries, and services across every customer touchpoint.

Conversation monitoring

Passively listen in to conversations as a third-party to power analytics, detect fraud and misuse, and enable real-time auditing, and loop in support at the right time.

For marketplace companies, monitor conversations and listen for keywords to prevent fraud, detect spam, and prevent off-band transactions before they happen. For financial services companies, own the record of the conversations between clients, financial advisors, and portfolio managers to enforce compliance, power auditing, and transfer context when customer support is needed.

Multi-conversations

Engage in multiple conversations with a single customer, separated by department, topic, or business event.

For marketplace companies, enable multiple conversations between your buyers, sellers, riders, and drivers related to business events like product listings, deliveries, and rides. For multi-departmental customer engagement teams, maintain separate conversations with a given customer based on department, topic, or individual engagement rep.

Early access program

Admission

To qualify for admission into the multi-party conversations Early Access Program, you must be a Sunshine Conversations customer with a Premium or Enterprise plan subscription and have a well-defined use case supported by this version of the v2 APIs (sample use cases above). If you satisfy these requirements, please inform your named account manager and apply for admission by describing your use case in this form.

The Sunshine Conversations product team will be reviewing form submissions on a regular basis and accepting a select set of customers on a rolling basis. Once you are admitted into the EAP, your account manager will reach out with more details about onboarding and getting started.

Access

If you are accepted into the early access program, your account will be whitelisted and the app you intend to use will need to have the multiConvoEnabled setting enabled (this can be set using the Create or Update App API).

Quality

Though this program is in early access, the v2 APIs and webhooks should be considered as production-ready and able to be used in live applications.

Versioning policy

During the early access phase, the v2 API will be managed under a more flexible versioning policy compared to the v1.1 API. Any planned breaking changes will be communicated in advance, and a grace period will be given to make any necessary changes. You’ll be notified via our EAP mailing list a minimum of 6 weeks prior to the effective date.

By entering into this program, you acknowledge that breaking changes will happen and you must be able to incorporate them into your integration before the effective date. Our aim is to introduce changes in a way that allows for a seamless upgrade at any time during the grace period, whenever possible. For example:

  • For changes to API request payloads (e.g. renamed or moved fields, new required parameters, etc.), both the old and new payloads will be accepted until the effective date
  • For changes to response or webhook payloads, where the breaking change is a field that has been moved or renamed, both fields will be sent until the effective date
  • If an API endpoint is being renamed or removed, the previous version will continue to work until the effective date

Below you can find a list of upcoming and completed breaking changes:

Status Posted Date Effective Date Description
ITC 2020-08-13 2020-09-28 The user:merge webhook payload will have surviving, discarded and discardedConversationId discontinued and mergedUsers and mergedConversations objects introduced.
ITC 2020-08-13 2020-09-28 API errors will now return an errors array rather than a single error object
ITC 2020-08-13 2020-09-28 The user exposed through webhooks (where applicable) will now have the givenName, surname, email and avatarUrl (new property being introduced) properties exposed under a profile object rather than at the object's root
ITC 2020-08-13 2020-09-28 Custom Integration Keys will have the name property replaced by displayName
ITC 2020-08-13 2020-09-28 Custom Integrations will have the webhook object replaced by a webhooks array
ITC 2020-08-13 2020-09-28 Messages will have the name property replaced by displayName and role by type in the author object. The type will have business replace appMaker as allowed value.
ITC 2020-08-13 2020-09-28 The Conversations property appMakerLastRead will be replaced by businessLastRead
ITC 2020-08-13 2020-09-28 PUT method will no longer be available for modifying resources, but PATCH should be used instead (behaviour remains unchanged / already compatible with the new method)
ITC 2020-08-13 2020-09-28 Offset pagination will no longer be supported in favor of cursor pagination replacing it for resources listing (where available). The v2 apps API already supports cursor pagination.
ITC 2020-08-13 2020-09-28 Individual webhooks will be attributed a new id, unique from the custom integration id, which will be used for their management going forward. Updating a webhook can no longer be achieved with the integrations API PUT /integrations/:id. Instead, webhooks can be updated using this new id and the webhooks API PUT /integrations/:id/webhooks/:id. Additonally, this new id will be used as the id field of the webhook payloads for the new API version starting on the effective date of this change (the change will not affect the previous version of the API)
TBI 2020-08-13 2020-09-28 Conversations and Integrations will no longer accept an empty string for the displayName or description (Conversations only) properties
TBI 2020-08-13 2020-09-28 Shorthand syntax will only be parsed in text type messages
TBI 2020-08-13 2020-09-28 A more specific invalidFile error will replace the generic badRequest for bad media (when applicable)

Status descriptions:

  • TBI: To be implemented. The new behaviour is not yet available;
  • ITC: Implemented / Temporarily compatible. The new behaviour is implemented and the previous one is also available until the effective date;
  • COM: Completed. The new behaviour is implemented and the previous one has been deprecated / removed;

Introduction to v2 API

Multi-party conversations introduces a 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 a 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.

Current SDKs and v1 APIs will continue to work as they do today, 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 (appMakers). 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 (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.

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 in parallel (of any type). 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

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. Note that the SDKs do not yet include a conversation list UI, but it can be built based on the SDK API.

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 preview the release notes of each SDK below. The new version of each SDK will be made available through-out March 2020

Webhooks are now integrations

As mentioned in the new key concepts section above, webhooks have been replaced by the new concept of Custom Integrations.

v1.1 v2
Multi-Party Webhooks Multi-Party Custom Integration
GET /v1.1/apps/{{appId}}/webhooks GET /v2/apps/{{appId}}/integrations
{
  "webhooks": [
    {
      "_id": "5cd97e921f7a2900105ff022",
      "version": "v1.1",
      "target": "https://example.org"
      "secret": "secret",
      "triggers": ["message:appUser"],
      "includeFullAppUser": true,
      "includeClient": false
    }
  ]
}



{
  "integrations": [
    {
      "id": "5cd97e921f7a2900105ff022",
      "type": "custom",
      "webhooks": [
        {
          "id": "5f3be401e6d4ea000db49886"
          "version": "v2",
          "target": "https://example.org"
          "secret": "secret",
          "triggers": ["conversation:message"],
          "includeFullUser": true,
          "includeFullSource": false
        }
      ]
    }
  ]
}

Read more about how to manage Custom integrations in the reference doc.

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

Multi-threading support in Mailgun integration

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.

Implementation guide

Some assembly required

There are a few important functions that your software will need to implement in order to offer a complete end-to-end experience for multi-party conversations:

  • Conversation creation

    • The SDKs do not have the ability to create new conversations for a given user, this function must be performed by your backend in response to some existing business process on your side.
  • Participant matching

    • The Sunshine Conversations platform does not facilitate searching or matching of users, nor does it provide a means for users to discover each other and begin a conversation. The logic that determines who should be a member of each conversation (and when they are added and removed) must be handled by your software.
  • In-app conversation discovery

    • The multi-convo SDKs do not provide a conversation list UI or a means for a user to self-select which conversation should be displayed. Your mobile app or website must leverage its existing navigation flows to show the correct conversation at the right moment, or implement a custom conversation picker interface based on the data exposed by the SDK.

Additional functionality (optional)

With a multi-party implementation in place, additional use cases can be considered, such as:

  • Escalation

    • If a conversation between two or more users requires escalation to a higher business unit (customer service or technical support, for example), your application should provide a way for users to trigger these escalation flows when necessary.
  • Content moderation

    • Webhook events for multi-party conversations can be subscribed to in order to perform any type of monitoring or moderation of the conversations happening between your users. If your business needs to enforce or audit a code of conduct, you can listen to webhook events to implement these functions.
  • Conversation enrichment

    • The business has the ability to “barge in” to any existing conversation at will. This can be used to provide value-added services like enriching the conversation with business-specific information related to the ongoing content of the conversation. For example, when a user mentions a product in your catalog, the business may choose to send a rich message with more information about the product.

Limitations of the early access program

Multi-party conversations

  • Multi-party conversations (type: "sdkGroup") are only possible with Sunshine Conversations’ native SDK channels (iOS, Android, and Web). There is no third-party channel linking possible in this type of conversation. Channel linking is only available on conversations of type personal.
  • A multi-party conversation may only have a maximum of 10 participants at a time.
  • The Sunshine Conversations platform does not provide role-based access or permissions models for conversation participants. At the moment, all users have the same level of permissions in terms of which conversations they can be added to, and what types of actions they can perform in those conversations. Note however that conversation membership is managed entirely by the integrator on the server-side; a user does not have the ability to join conversations themselves and they can be removed from conversations at any time.
  • Payment request buttons using the Stripe Connect integration are not supported in multi-party conversations. Buttons of this type will be rejected at the API level.

Multiple conversations per user

  • Conversation history is not separated across different SDK integrations. This means that if a user in your system can fulfill multiple roles (ex: a user is both a buyer and a seller in your marketplace), they will see the same set of conversations in both instances. If this situation is possible in your use case, consider creating separate users representing each role in order to ensure proper segmentation of the data.

Multiple instances of a channel

  • The Sunshine Conversations platform does not automatically track a user across multiple integrations at the moment. This means that if the same end-user messages WhatsApp integrations X and Y, for example, that user will be represented as two separate users (even though the ID on WhatsApp is the same).
  • There will be no automatic reconciliation of duplicate users created as a result of the above once tracking a user across channel instances is launched as a feature of the platform. The merge user API may be used to manually consolidate redundant users on demand, if required.
  • When offering a user to connect another channel from Web messenger, it’s only possible to offer linking to a single, specific channel integration of each type (for example, even if you connected 2 Facebook pages, only one can be offered for linking). By default, the first created instance of each type will be offered, but this can be customized using the Web Messenger integration API (see integrationOrder).
  • Each Sunshine Conversations app can be connected to an unlimited number of channel integrations. Moreover, the “Overview” page of the Sunshine Conversations web dashboard displays a maximum of 250 integrations. Integrations beyond the first 250 may be queried via the public API.
  • Legacy webhook paths for the WeChat and LINE channels will no longer be able to accept messages as soon as a second instance of either of those channels is added. v2-compatible webhook path examples can be found here for WeChat and LINE. Integrations created after March 2018 should already be using the new path structure.