Conversational Control

The Conversations API enables multiple applications to listen to and send messages to a user on a specific channel. An important aspect of allowing multiple applications to message the user is managing the conversational control flow.

There are are two primary actions of the Conversations API available to help us manage the conversational control flow; POST conversations/passcontrol and POST conversations/takecontrol.

In addition, you may discover the application_id in control of a user's conversation with GET conversations/currentcontrol/:snaps_user_id. You can also GET api/conversations/listapplications/:channelId and GET api/conversations/listchannels to discover the channel and application landscape surrounding your application.

Pass Control

Users will begin their experience with the conversational control being assumed by the bot application. If a user triggers a request for a live human agent, the bot application will pass control to the customer service application. Once the customer service application has resolved the issue, it should pass control back to the bot application.

When calling conversations/passcontrol, applications should POST two params:

  • snaps_user_id: The ID of the user you are requesting control of.
  • application_id: The ID of the application you want to pass control to. You may leave this blank in order to pass back to the primary conversation.

When calling conversations/passcontrol your application should expect a 200 response status code. If any other status code is returned, the request was unsuccessful and the control change event was not emitted to the receiving application's webhook.

const basic_auth = `Basic ${ Buffer.from(credentialsId + ':' + credentialsSecret).toString('base64') }`;
request({
  uri: "https://snapsmedia.io/api/conversations/passcontrol",
  method: "POST",
  headers: { Authorization: basic_auth },
  json: {
    snaps_user_id: '',
    application_id: ''
  },
}, (err, response, body) => {
  if (err) return console.error(err);
  console.log("status code:", response.statusCode);
  console.dir(body, { depth: null });
});

Take Control

The conversations/takecontrol action is used when your application needs to message a user but does not have conversational control for the specific user. This should not be confused with assuming control from a control change webhook event.

When taking control from another application, you are required to POST one param:

  • snaps_user_id: The ID of the user you are requesting a conversation with.
const basic_auth = `Basic ${ Buffer.from(credentialsId + ':' + credentialsSecret).toString('base64') }`;
request({
  uri: "https://snapsmedia.io/api/conversations/takecontrol",
  method: "POST",
  headers: { Authorization: basic_auth },
  json: {
    snaps_user_id: '',
  },
}, (err, response, body) => {
  if (err) return console.error(err);
  console.log("status code:", response.statusCode);
  console.dir(body, { depth: null });
});

Current Control

Your application should manage the state of conversations with a user, however there are times when you may need to GET conversations/currentcontrol/:snaps_user_id for a user.

const basic_auth = `Basic ${ Buffer.from(credentialsId + ':' + credentialsSecret).toString('base64') }`;
request({
  uri: "https://snapsmedia.io/api/conversations/currentcontrol/:snaps_user_id",
  method: "GET",
  headers: { Authorization: basic_auth }
}, (err, response, body) => {
  if (err) return console.error(err);
  console.log("status code:", response.statusCode);
  console.dir(body, { depth: null });
});
/*
{
  conversation_id,	
  conversation_start,
  snaps_channel_user_id,
  applicationOwner: {
    "name": "AI Dog Food Bot",
    "description": "Helps dog owners find the best food for their pup.",
    "receiverType": "primary",
     "id": "5c5e462bcba59b08e5d37f34f"
  }
}
*/

Channel List Applications

Your application may need to discover other applications to manage conversational control flow. To get a list of applications you will need to make a GET request to api/conversations/listapplications/<channelId>.

const basic_auth = `Basic ${ Buffer.from(credentialsId + ':' + credentialsSecret).toString('base64') }`;
request({
  uri: "https://snapsmedia.io/api/conversations/listapplications/<channelId>",
  method: "GET",
  headers: { Authorization: basic_auth }
}, (err, response, body) => {
  if (err) return console.error(err);
  console.log("status code:", response.statusCode);
  console.dir(body, { depth: null });
 /*
  {
    "id": "5c5e455fd6a2fb813365aa8c",
    "name": "SMS Dog Food Channel",
    "environment": "production",
    "active": true,
    "orgId": "5a3c2e89c928bb7275e60f1a",
    "channelType": "sms",
    "endpoint": "+12084766550",
    "primaryReceiver": "5c5e462bcba59b08e5d37f34f",
    "applications": [{
      "name": "AI Dog Food Bot",
      "description": "Helps dog owners find the best food for their pup.",
      "receiverType": "primary",
      "createdAt": "2019-02-09T03:17:48.217Z",
      "updatedAt": "2019-02-09T03:17:48.217Z",
      "id": "5c5e462bcba59b08e5d37f34f"
    }, {
      "name": "Dog Food Delivery Service",
      "description": "Listens for new orders to trigger a delivery workflow.",
      "receiverType": "secondary",
      "createdAt": "2019-02-09T03:17:48.217Z",
      "updatedAt": "2019-02-09T03:17:48.217Z",
      "id": "5c5e462bcba59b08e5d22f3b"
    }],
    "createdAt": "2019-02-09T03:14:18.378Z",
    "updatedAt": "2019-02-09T03:17:48.270Z"
  }
*/
});

Application List Channels

Your application may want to discover the channels it's listening to for supporting your workflows. To get a list of channels for your application you will need to make a GET request to api/conversations/listchannels.

const basic_auth = `Basic ${ Buffer.from(credentialsId + ':' + credentialsSecret).toString('base64') }`;
request({
  uri: "https://snapsmedia.io/api/conversations/listchannels",
  method: "GET",
  headers: { Authorization: basic_auth }
}, (err, response, body) => {
  if (err) return console.error(err);
  console.log("status code:", response.statusCode);
  console.dir(body, { depth: null });
});
 /*
  {
  "id": "5c5e462bcba59b08e5d22f3b",
  "name": "Dog Food Delivery Service",
  "description": "Listens for new orders to trigger a delivery workflow.",
  "receiverType": "secondary",
  "webhook": "https://dogfood.snaps.io/webhook",
  "subscribedEvents": {
    "message_send": true,
    "message_delivery": true,
    "link_click": true,
    "add_to_cart": true,
    "page_view": true,
    "order_complete": true,
    "custom": true,
    "control_change": true,
    "user_property_set": true
  },
  "permissions": [
    "applications/listchannels",
    "channels/listapplications",
    "conversations/passcontrol",
    "conversations/takecontrol",
    "conversations/send",
    "conversations/transcript"
  ],
  "channels": [{
    "id": "5c5e44e3d6a2fb813365aa7e",
    "name": "Web Dog Food Channel",
    "environment": "production",
    "active": true,
    "channelType": "web",
    "endpoint": "dogs.snaps.io",
    "createdAt": "2019-02-09T03:13:17.794Z",
    "updatedAt": "2019-02-09T03:17:48.281Z",
  }, {
    "id": "5c5e455fd6a2fb813365aa8c",
    "name": "SMS Dog Food Channel",
    "environment": "production",
    "active": true,
    "channelType": "sms",
    "endpoint": "+12084766550",
    "createdAt": "2019-02-09T03:14:18.378Z",
    "updatedAt": "2019-02-09T03:17:48.270Z",
  }],
  "createdAt": "2019-02-09T03:17:48.217Z",
  "updatedAt": "2019-02-09T03:17:48.217Z"
}
*/

When calling conversations/passcontrol your application should expect a 200 response status code. If any other status code is returned, the request was unsuccessful and the control change event was not emitted to the receiving application's webhook.

Assume Control

A successful POST to conversations/passcontrol or conversations/takecontrol will emit a webhook event to all applications listening for those events on the subject channel. It is the responsibility of the to_application_id on the control_change event to assume conversational control with the user until the next control change event occurs. Checkout the control change event documentation to learn more.


What’s Next

Now that your application has control of the conversation, you can learn how to send messages.