Conversations API
Overview
The Snaps Conversations API enables two or more applications to control which application is currently interacting with a user, send messages to a user, and monitor all conversational events across Web, SMS, Google Business Messaging, Apple Business Chat, FB Messenger, Twitter, Viber and native iOS/Android channels.
High Level Diagram of the Snaps Conversations API
The Snaps Conversations API follows a JSON-RPC HTTP style interface. However, our underlying platform API leverages a graph oriented hypermedia JSON-REST style interface. If your implementation requires a deeper or more abstract integration, please reach out to your solutions architect to discuss access and documentation for the Snaps Platform REST API.
Core Concepts
It will be helpful for you to understand the core concepts at play in the Snaps Conversations API before interacting with it's procedure calls.
Channels
A channel represents a distinct endpoint where conversations with end users occur. It is important to understand that a channel has a channel type, such as SMS. However, applications may run on multiple channels of the same or varying types:
-
Suppose you have an application supporting a SMS experience in both the US and UK. This application may run on two SMS type channels, having two distinct phone numbers for each channel endpoint.
-
Suppose you have an application supporting an experience on FB Messenger and an enterprise web site. This application will run on two channels with different types and endpoints.
Check out the channels documentation to learn more.
Applications
Application can support many channels. Applications can be represented as either a primary channel receiver or a secondary channel receiver. The primary channel receiver application for the purposes of our documentation is the Snaps AI, also referred to as the bot or bot application in many parts of our documentation.
Primary Application
On some channels such as Apple Business Chat and Google Business Messaging the bot application may run as a secondary application with a human customer service application receiving initial conversational control.
Secondary channel receiver applications can be integrated into the conversational experience for a number of use cases, such as live agent customer service handoff, publishing data to a consumer data platform or integrating an enterprise rewards system to credit loyalty points.
Our documentation is focused on the customer service handoff use case, but your Solutions Architect can help you design a fully integrated conversational experience.
Users
Applications and channels support many users. Users are scoped to the channel they are engaging on. Cross channel user identification can be achieved, but requires domain specific logic implemented by a secondary application. All user bound procedures of the API are bound to a channel specific snaps_user_id.
Conversations
Conversations represent a distinct set of interactions between an application and an end user. At any given time, only a single application can send messages to a user.
The entirety of a user's interactions are delineated by changes in conversational control. That is, a control change from one application to another, ends one conversation and begins another in the Snaps system. However, a user experiences these conversations as a single integrated thread with multiple participants.
Applications also have access to the entirety of a user's interactions; we call this the transcript. The transcript represents all messages from all applications along with a number of other events that enrich the transcript. Events such as click to website, page views, purchases and other custom events are layered into the transcript to provide customer service agents and machine learning algorithms with optimal context.
Check out conversational control documentation to learn more.
Getting Started
Learn how to setup an application in the Snaps Platform.
Learn how to listen for webhook events from the Snaps Conversations API.
Calling the API
Learn how to authenticate with the API.
Learn how to manage control of conversations.
Learn how to send messages to users.
Learn how to retrieve and view your user's conversation transcripts.
Updated about 1 year ago