Key Concepts

The glossary below defines key Sunshine Conversations concepts and how they relate to each other.

ER diagram

User Account

A top level entity that identifies the owner in charge of one or many Sunshine Conversations apps. A user account either represents a single business, or it represents a software maker who manages multiple apps on behalf of many separate businesses. A separate user account may also be created as a sandbox for development and testing purposes.

Service Account

A service account represents an API user, with its own set of credentials, that only has access to a certain subset of apps. For software makers that create apps on behalf of separate customers or businesses, service accounts can be used to generate and distribute credentials that only have access to a single business’ data.


An app represents a customer or business as a whole using your software, or a department within one of those customers or businesses. An app contains a set of configured channels as well as any associated user profile and conversation data. Each app’s user and conversation data exists separately; apps never share data between each other.


An end user communicating with a business. More details can be found here.


A stored history of messages sent to and received from a user. There are two types of conversations: personal and sdkGroup.

  • A personal conversation involves a single user and one or many business actors. 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 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.


An 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. Therefore, there can be many participants associated with the same user object. An sdkGroup conversation can also have multiple participants.


A message that was sent via the Sunshine Conversations API or received from a third party integration. All messages have one of two author types: user, representing the end user, or business, meaning it was sent on behalf of the business. Messages can be simple or complex, supporting a variety of interactive structures, extensions and media formats. Messages have a source property that identifies which client they came from.


A connection through which an individual user can send and receive messages. Clients come in a variety of flavors, each identified by a different channel. Clients also contain metadata about the channel being used. For example, a Messenger client will contain a raw copy of the user’s Facebook profile information.

A user may only have one SDK client, which can be linked to multiple devices. 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.

client diagram


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.


A configuration that defines how the app connects to one of the Sunshine Conversations SDKs or to a third party messaging service. There is no limit on the number of integrations an application can be connected to (note that a maximum of 250 integrations will be rendered in the Sunshine Conversations Web Dashboard. Integrations beyond the first 250 may be queried via the public API). More details can be found here.

Custom Integration

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.