snaps-sonic-app

A client library for applications of the snaps-sonic-server.

Usage no npm install needed!

<script type="module">
  import snapsSonicApp from 'https://cdn.skypack.dev/snaps-sonic-app';
</script>

README

Overview

Snaps offers a channel agnostic handover protocol that enables conversational control flow for chatbot applications and human CS agents. For example, Snaps may have integrated an automated conversational experience within your website, native iOS application and/or FB Messenger page. The automated chatbot will help the user with information on shipping status, handle product specific FAQs, and conduct a customer satisfaction survey.

However, there are instances when customers are better served by engaging with a human agent. The Snaps Sonic Server exposes an interface that provides a consistent mechanism across messaging channels to receive control of a conversation, serve the customer, and then return control to the automated chatbot.

alt text

Definitions

Bot

The bot represents the experience as a whole and refers to a unique bot within the Snaps platform. Bots have users, channels and apps.

Bot User

A bot user is the customer engaging with the bot experience on a specific channel.

Channel

A channel is the platform where the conversation is occurring. Different customers may engage the bot experience on different channels. (FB Messenger, Twitter, Slack, SMS, web or native app)

App

An app is a chatbot or a human agent application that participates in providing the bot experience for the customer. Apps may have control of a conversation for a specific bot user. The Snaps-Sonic-Server is designed to support apps in this control flow process.

Human Agent

A human agent is typically a customer care associate that has been given control of a specific conversation on a specific channel. A customer care provider will have an app that takes control of the conversation and facilitates the the human agent portal.

Transcript

The transcript is the history of a specific bot user conversation across all apps. Given that many of our channels offer rich experiences, a transcript is not necessarily human readable in it's JSON form. A transcript can be acquired by calling sonicApp.getTranscript({ botUserId, type: 'JSON', cb }). A transcript can be rendered in the Snaps Conversational Marketing Cloud. To get a URL to view the transcript, call sonicApp.getTranscript({ botUserId, type: 'URL' }). Human agents requesting a transcript url are authenticated and authorized via the Snaps CMC. We also provide the Snaps web bot client to further support different workflows for transcript review.

Connecting your app

The Snaps Sonic Server leverages web sockets to implement a realtime conversational control flow experience. We provide the snaps-sonic-client library to make implementation a breeze. Below is an example of initializing a connection with the Snaps Sonic Server and registering event handlers. The SNAPS_APP_ID and SNAPS_APP_SECRET are intended for server side environments and should be protected and handled with care. Credentials can be acquired securely via the Snaps CMC.


  const SNAPS_APP_ID = process.env.SNAPS_APP_ID;
  const SNAPS_APP_SECRET = process.env.SNAPS_APP_SECRET;
  const sonicApp = require('snaps-sonic-app')({
   appId: SNAPS_APP_ID, // your app specific key - required
   appSecret: SNAPS_APP_SECRET, // your app specific secret - required
   botIds: ["yourBotId1", "yourBotId2"], // bot ids to listen for - required
   retryHandoverFor: 300, // retry seconds, defaults to 5 mins
   retryHandoverInterval: 30 // defaults to 30 seconds
  });

  sonicApp.init(options, (err, client) => {
    if (err) return someErrorHandler(err);
    sonicApp.listen('handover', handoverEventHandler);
    sonicApp.listen('handoverConfirmed', handoverConfirmedEventHandler);
    sonicApp.listen('takeover', takeoverHandler);
    sonicApp.listen('takeoverConfirmed', takeoverConfirmedHandler);
    sonicApp.listen('userSay', userSayHandler);
    sonicApp.listen('agentSay', agentSayHandler);
  });

Events

Apps will send and receive events. The payload will be the same whether your app is sending or receiving an event. Your application will only receive userSay and agentSay events when it is the app in control of the conversation.

handover

A handover event is used to send control to another app. When the snaps-sonic-client receives a handover event, it will automatically send a handoverConfirmed event and then call the handoverEventHandler you have assigned. To handover the conversation to another app you will call sonicApp.send('handover', payload). In the case where the app that is assigned the handover does not respond with with a handoverConfirmed event, the sonicApp will retry the handoff based on the retry configuration.

handover sample payload

{
  "botId":  "5a709e5d7bf66c6c5e050b2c",
  "botUserId":  "5a709e5d7bf66c6c5e050b2c",
  "fromAppId": "5a709e5d7bf66c6c5e050b2c",
  "toAppId": "5a709e5d7bf66c6c5e050b2c",,
  "channel": "web",
  "time": 1518302460
}

handoverConfirmed

The handoverConfirmed event is primarily handled by the snaps-sonic-app library. It will send a handoverConfirmed event upon receiving a handover. The library will also update the inControlApp property upon receiving a handoverConfirmed app. If you have additional work to do, you can assign a handoverConfirmedEventHandler to the event.

handoverConfirmed sample payload

{
  "botId":  "5a709e5d7bf66c6c5e050b2c",
  "botUserId":  "5a709e5d7bf66c6c5e050b2c",
  "fromAppId": "5a709e5d7bf66c6c5e050b2c",
  "toAppId": "5a709e5d7bf66c6c5e050b2c",
  "channel": "web",
  "time": 1518302461
}

takeover

A takeover event is used to proactively take control of a conversation. In contrast to the handover event, the app sending the takeover event will have immediate control of the conversation. A takeoverConfirmed event will still be received to acknowledge the control flow change. If the takeoverConfirm event is not received the snaps-sonic-app library will ensure the formerly inControlApp is aware of the control flow change when it comes back online.

takeover sample payload

{
  "botId":  "5a709e5d7bf66c6c5e050b2c",
  "botUserId":  "5a709e5d7bf66c6c5e050b2c",
  "fromAppId": "5a709e5d7bf66c6c5e050b2c",
  "toAppId": "5a709e5d7bf66c6c5e050b2c",,
  "channel": "web",
  "time": 1518302460
}

takeoverConfirmed

The takeoverConfirmed event is handled by the snaps-sonic-app library. If you have additional work to do on this event, you can assign a takeoverConfirmedEventHandler to the event.

takeoverConfirmed sample payload

{
  "botId":  "5a709e5d7bf66c6c5e050b2c",
  "botUserId":  "5a709e5d7bf66c6c5e050b2c",
  "fromAppId": "5a709e5d7bf66c6c5e050b2c",
  "toAppId": "5a709e5d7bf66c6c5e050b2c",,
  "channel": "web",
  "time": 1518302460
}

UserSay

Once your app has control of a conversation, the sonicApp will receive userSay events.

userSay sample payload

{
  "botId":  "5a709e5d7bf66c6c5e050b2c",
  "botUserId":  "5a709e5d7bf66c6c5e050b2c",
  "channel": "web",
  "time": 1518302461,
  "input":  {
    "type": "text", // text, image, location
    "value": "text string or image url" // go over this with Connor to see what the payloads look like
  }
}

AgentSay

The agentSay event supports text, urls and images.

AgentSay sample

{
  "botId":  "5a709e5d7bf66c6c5e050b2c",
  "botUserId":  "5a709e5d7bf66c6c5e050b2c",
  "input":  {
    "type": "text", // text, url, image, location
    "value": "text string or image url" // go over this with Connor to see what the payloads look like
  }
}