DocumentationAPI Reference

Key concepts

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

The main data models that make up the messaging platform

The green boxes represent Zendesk objects that span multiple product areas, while the yellow boxes are objects that are specific to messaging. A solid line represents a direct relationship (typically representing ownership), and dotted lines are used to represent reference relationships. For readability, not all relationships are represented in the diagram above. Continue reading for more information about each object type and how they relate to other objects in the data model.

App

An app in Sunshine Conversations is mostly used as a container for other objects. Aside from the Zendesk account, it is the highest order object in the hierarchy and is created automatically for you in the background. The app contains several settings which affect the behavior of messaging for all conversations and integrations.

Relationships

  • Zendesk account: Messaging-enabled accounts will have one and only one app. For accounts without messaging, an app may not always exist.
  • Switchboard: An app has one and only one switchboard.
  • User (messaging): An app can have an unlimited number of messaging users.
  • Integration: An app can have many integrations of different types.
  • Conversation: An app can have an unlimited number conversations.

User (messaging)

An end user communicating with your business. Contains profile information such as the user's name and avatar, preferred language, externalId and verified email address (if applicable). Each user can participate in one or many conversations.

Note: Currently, the Sunshine Conversations user model is separate from a user object in Support, but they are related.

See introduction to users for more information about messaging users.

Relationships

  • User (Support): Messaging users who have had at least one conversation escalated to an agent will have an associated user object in Support which serves as the requester for all of their tickets.
  • Participant: A user's relationship to a conversation is modeled by the participant object.
  • Conversation: A user may be a participant in any number of conversations.
  • Client: A user may have many clients.
  • Device: A user may have up to 20 devices.

Conversation

A stored history of messages between your business and a user, or between multiple users. 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. The vast majority of conversations are of this type.
  • 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). Third-party channel linking is not possible in these types of conversations, however, messaging authentication can be leveraged to allow a user to resume their conversation on a different device.

Relationships

  • Ticket: Conversations that have been escalated to an agent will have one or more related tickets. While a conversation may span multiple tickets over time, there can only be one open ticket for a given conversation. A conversation may also have zero related tickets if the interaction has been entirely handled by an AI agent or bot.
  • User (messaging): A conversation typically involves a single user interacting with your business.
  • Participant: The participant object is the source of truth for which users are a member of the conversation. Typically there will only be one participant for a conversation.
  • Message: A conversation may contain up to 30,000 messages.
  • Switchboard integration: The activeSwitchboardIntegration property of a conversation indicates which switchboard integration is currently in control of the conversation.
  • Brand: When the user sends a message from an integration linked to a particular brand, a brandId property will be stored on the conversation. The brand of a conversation is used for decisions such as which bot flow should run or what agent group tickets should be assigned to.
    • The brand id is sticky on the conversation and will not be automatically updated if the user switches channels mid-conversation.
    • The brand id can be explicitly unset via the API, causing a new brand id to be reassigned on the next user message.
    • When switchboard control of a conversation is released, the brandId is automatically unset. Among other reasons, this can occur when a ticket related to the conversation is closed, or when a bot flow expires due to activity.

Participant

An entity representing the link between a messaging 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.

Relationships

  • Conversation: A participant belongs to exactly one conversation.
  • User (messaging): A participant represents exactly one user participating in a conversation. For users taking part in multiple conversations, multiple participant objects will exist (one for each user <> conversation pairing).
  • Client: A participant contains a list of client references (clientAssociations) that tracks which channel(s) the user has connected to the conversation, and in what order of preference. Used when determining where a business message should be delivered.

Message

Represents the message history of a conversation. Each conversation contains an ordered list of messages, sorted by message received time. Messages can be simple or complex, supporting a variety of interactive structures, extensions, and media formats.

Messages may have one of two author types: user, representing the end user, or business, meaning it was sent on behalf of the business. Business messages are not always attributed to a particular person in your company. Business messages may also be sent by AI agents, third-party bots, directly using the API, or produced automatically by the platform. Each message has a source property that identifies where it came from.

Relationships

  • Conversation: Each message belongs to one and only one conversation.
  • Client: For messages authored by a user, a message's source property may refer to the client that produced the message.
  • Device: For messages authored by a user, a message's source property may refer to the device that produced the message.
  • Integration: For messages authored by the business, a message's source property may refer to the integration that produced the message.

Client

A client is a connection through which an individual user can send and receive messages. Clients come in a variety of flavors, identified by their type. When routing user and business messages, clients play a key role in determining where the message needs to go.

For third-party channels, a client represents the relationship between your business and the user in an external system. For example, a messenger client has an externalId representing the user's Facebook account, and an integrationId from one of your business' Facebook pages. Given this information (user X is connected to Facebook page Y), the client object can therefore be used as both a source and a destination for messages. Clients also contain metadata about the user gathered from their profile on the channel.

For native channels, a client will have the type sdk. A user may only have one such client, which can be linked to multiple devices and encompasses several integrations. 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.

Relationships between a user and clients of different types

Relationships

  • User (messaging): A client must belong to one user.
  • Integration: For social messaging clients (that is, all clients except those of type sdk), a client will be related to a specific integration of the same type. If the same user is connected to multiple integrations, for example if your business has multiple WhatsApp phone numbers for different regions, a user will have separate clients for each integration.
  • Participant: A client is connected to a conversation through the participant object.
    • The sdk client for a user can be connected to multiple conversations simultaneously.
    • For social messaging clients in particular, a client may only be connected to one participant at a time.
    • If a client is linked to a conversation that gets deleted, the client will remain under the ownership of the user, but will be connected to zero conversations. The next time the user reaches out from that client, a new conversation will be automatically created.
  • Device: The sdk client for a user may have up to 20 connected devices.
  • Message: A client can produce many messages, referenced in the message's source property.

Device

Clients of type sdk can have multiple devices associated with them, representing the user's presence on various physical devices or browsers. The device contains information such as push notification tokens, the user's operating system version, or current page URL.

For authenticated users, the user can have up to 20 connected devices. If a user logs out on a particular device, their device object will still be stored for future use. However, push notifications will be suppressed on that device until the user logs in again.

Relationships

  • User (messaging): A device must belong to one user.
  • Client: Each device belongs to the user's one and only sdk client.
  • Integration: A device is related to a specific integration of type ios, android, unity or web. If a user is logged into several different integrations on the same device, for example if you have a single mobile app that is shared by multiple of your business' brands, a user will have separate devices for each integration.
    • For integrations of type ios, android or web, the device's type will match the type of the integration
    • For unity integrations, the device may have different type values based on the platform of each physical device.
  • Message: A device can produce many messages, referenced in the message's source property.

Integration

A configuration that defines the connection between an app and one of the messaging SDKs, third party messaging channels, bot platforms, or other systems. There are many different types of integrations, generally falling within one of the following categories:

  • Messaging channels (for example, web, whatsapp, viber, twilio, etc.)
  • Zendesk services (for example, Agent Workspace, AI Agents, QA, etc.)
  • OAuth integrations (for example, third-party bot partners)
  • Custom integrations (webhook-based integrations built by your developers)

Relationships

  • Client: For messaging channel integrations, a client will reference the integration that was used to create it.
  • Device: For messaging SDKs and Web Widget integrations, a device will reference the integration that was used to create it.
  • Switchboard integration: Integrations can be related to switchboard integrations in one of two ways:
    • For Zendesk services, OAuth integrations and custom integrations: A switchboard integration may be created to represent that integration in the switchboard. If an integration is not connected to the switchboard, it can not be put in control of a conversation.
    • For messaging channel integrations: A defaultResponderId can be set on the channel which references the id of a specific switchboard integration. When a per-channel responder is configured, this overrides the global default responder of the switchboard, allowing for different responders per channel.
  • Brand: For messaging channel integrations, an integration can be assigned to a particular brand. The brand assignment of the integration will determine the brandId of conversations that the integration generates.

Switchboard

The switchboard is a container for a set of switchboard integrations, which each handle part of a user's journey as their conversation progresses. The switchboard establishes an escalation flow that each conversation in your account will follow.

For example, your switchboard may be configured to assign all conversations to an AI Agent by default, and escalate to Agent Workspace if a human needs to be involved. In this example, your switchboard would have two switchboard integrations representing your AI agent and Agent Workspace, respectively. The switchboard's defaultSwitchboardIntegrationId would point to your AI agent as the first responder for all newly created conversations.

See the switchboard guide page for more details.

Relationships

  • App: A switchboard belongs to one app.
  • Switchboard integration: A switchboard may have up to 10 connected switchboard integrations.

Switchboard integration

A switchboard integration represents a business system which can be placed in explicit control of a conversation. Examples of business systems would be an agent help desk like the Zendesk Agent Workspace, or an automated responder like an AI Agent or third-party bot. When a switchboard integration is in control of a conversation, it will receive all messages sent by the user, and is expected to be the one to reply. If and when escalation to a different system is required, the switchboard integration is expected to pass control away. Control of a conversation can also be released, resetting the conversation back to a neutral state.

The switchboard integration object exists distinctly from the integration object because not every integration should be part of the switchboard. A system like Zendesk QA is only intended to be a "passive listener" on conversations - collecting data in the background, but not ever being put in control of a conversation. These types of integrations can and should exist outside of the switchboard.

A switchboard integration contains configuration such as:

  • Whether the integration should receive webhooks when not in control of a conversation (deliverStandbyEvents).
  • Which other switchboard integration should be assigned as in control in the case of an escalation (for example, your AI Agent might escalate conversations to Agent Workspace).

Relationships

  • Switchboard: A switchboard integration belongs to one switchboard.
  • Integration: A switchboard integration represents a specific business system integration (Zendesk service, OAuth integration or custom integration) in the switchboard.
  • Conversation: Control of a conversation can be assigned to a particular switchboard integration via the activeSwitchboardIntegration property. The active switchboard integration for a particular conversation is expected to respond to the user's messages, or pass control away if and when escalation to a different system is required. Control of a conversation can also be released, unsetting the conversation's activeSwitchboardIntegration.
  • Switchboard integration: Switchboard integrations may refer to other switchboard integrations via the nextSwitchboardIntegrationId property. If control of a conversation is passed using the next keyword, the next system to be placed in control will be resolved based on this configuration.