Switchboard

The following guide covers key concepts around the Sunshine Conversations Switchboard API, how it can be integrated with a custom bot or one of our bot partners’ platforms, and how to pass control of the conversation between Zendesk and your bot using the switchboard.

Handover with the switchboard

With Sunshine Conversations’ Switchboard API, you can achieve bot-to-human handover across messaging channels and business systems. The switchboard allows you to programmatically route a user’s conversation through third party systems such as bot frameworks and helpdesk systems, similarly to how an operator patches phone calls via a switchboard. An unlimited number of business systems can be connected to the switchboard and you can move the conversation either to the next integration in the chain or directly to a specific system.

Zendesk’s Agent Workspace and AnswerBot are built-in to Sunshine Conversations and leverage the switchboard. For specialized use cases or industry-specific flows, the Bot Marketplace showcases a variety of bot partners who have integrated to the switchboard and the Sunshine Conversations platform.

Switchboard use cases

Bot to human agent handover

Intelligent bots can scale your customer service team, however even the cleverest bot will eventually need to escalate an issue to a human being. The business is represented by two different switchboard integrations: a bot and a help desk business system integration.

When the end user first reaches out, their messages are routed to the bot integration. When the user asks a question that the bot cannot handle, the bot integration will pass the conversation’s control to the business integration.

Bot agent handover

Once the agent has solved the end user’s problem, they will close the ticket from their help desk system, and the user will be switched back to the bot integration for any further questions or support requests.

Human agents delegating tasks to a “utility bot”

Bots are perfect for automating certain workflows within a conversation so that agents can more efficiently serve multiple customers at once. Flows such as payments, authentication, or knowledge base FAQs are great candidates for switchboard bot integrations. Once the agent identifies the next step for the customer, the agent can trigger the bot and pick up the conversation with the customer once they’ve completed their transaction with the bot.

Multi-system escalation

For businesses who have tiered support, it’s possible that a conversation starts at the first tier and then needs to move to another support system altogether. In this situation, the switchboard can hand off the conversation seamlessly between systems so that agents at every level have full context on the customer’s request.

Key Switchboard Concepts

Conversational control model

Pass control

The passControl action will immediately switch the flow of the specified conversation over to the specified switchboardIntegration (or the defined nextSwitchboardIntegration when using the keyword next), and can be thought of as a “cold transfer,” where the switchboard receiving the “pass” is expected to respond.

Offer and accept control

In the real world, humans aren’t always immediately available. Different systems might also benefit from being able to share control of a conversation, instead of an abrupt transfer of control. A more natural bot-agent handoff can be implemented by introducing two new actions: offerControl and acceptControl.

In this scenario, instead of abruptly passing the control of a conversation to a helpdesk integration and disconnecting itself, the bot integration instead offers control of the conversation to the helpdesk integration, while remaining on the line.

Once a human agent joins the ticket via the helpdesk, the help desk integration can issue an acceptControl action, which removes control from the bot integration and gives it to the helpdesk integration. Finally, when the problem is solved, the agent can close the ticket, and the helpdesk integration issues a passControl action to restore bot control.

Pass offer accept control

Switchboards and switchboard integrations

A switchboard is a group of integrations that can share or transfer control of a conversation between each other. For each conversation, all switchboard integrations have an associated status of either active, pending or standby.

Switchboard integration status

The switchboard integration status is a matter of signaling; an active switchboard integration is expected to respond to user messages while a standby integration is not.

The pending status is used for a switchboard integration that has been offered control of a conversation, but has not accepted control of it yet.

There can only be one active and one pending switchboard integration at the same time for a given conversation.

Switchboard with switchboard integrations

Switchboard integrations

Integrations are the vehicle for sending and receiving messages from third party business systems and bots. They come in the form of native integrations baked into the Sunshine Conversations platform, or as custom integrations that communicate via the Sunshine Conversations API and webhooks. Native integrations include Zendesk’s Agent Workspace. Custom integrations could be your own webhook or one of Sunshine Conversations’ bot partners in our marketplace.

Custom integrations and native integrations

A switchboard integration represents an integration’s membership within a switchboard, as well as their presence and status in an ongoing conversation. Integrations can live on their own, without being a member of a switchboard. An integration not being part of a switchboard (or linked to a disabled switchboard) will simply receive subscribed message events as if the switchboard did not exist. A switchboard integration however requires an attached integration in order to send and receive messages.

The active and pending switchboard integrations for a given conversation will receive all events related to activities within that conversation. Switchboard integrations may opt to receive conversation related events even when they are in standby mode. This allows integrations to keep track of conversation events so that they have context on hand if and when they are switched to active status for a given conversation.

The switchboard only impacts events that are directly related to new conversation activity. Any switchboard integration linked to a custom integration will start receiving the following events if one or more of the following are true:

  • The switchboard integration has deliverStandbyEvents set to ‘true’
  • The switchboard integration is active for the related conversation
  • The switchboard integration is pending for the related conversation

v2 API events related to conversational activity accessible to a switchboard integration subscribed to standby events:

  • conversation:message
  • conversation:read
  • conversation:typing
  • conversation:postback
  • conversation:create
  • conversation:message:delivery:failure
  • conversation:message:delivery:channel
  • conversation:message:delivery:user
  • conversation:join
  • conversation:leave

Other events will be sent to all switchboard integrations linked to a custom integration.

Control transfer

Switchboards must designate one integration as the default. When a new conversation begins, this switchboard integration will begin with active status for that conversation. Typically, a bot represents the default integration.

When a switchboard integration wishes to transfer control to another, they may look at which other integrations are involved in a conversation, but they don’t need to.

Switchboard configuration includes an integration hierarchy graph, which dictates a default transfer path. Thus, a switchboard integration may escalate control of a conversation by performing a passControl or offerControl action without having to name any specific switchboard integration.

The switchboard integration may invoke these actions by calling the REST API or by sending a text message using the shorthand syntax, which are both detailed below.

What to expect during a switchboard project

Which problem is the switchboard solving?

Are you looking to solve bot-to-human handover? Are you passing a conversation through multiple third party systems as part of an escalation flow?

Your CX problem will drive the implementation of your switchboard and the switchboard integrations within it.

Bots on the switchboard

If you’d like to add a bot in your CX flow, you can either select one of Sunshine Conversations’ bot partners in our marketplace or bring your own bot to the switchboard.

Define your switchboard flow

Every switchboard needs a default integration, so define which of the custom integrations in your Sunshine Conversations application will be the first point of contact for your users. In a bot-to-human scenario, the bot is typically the default switchboard integration.

The following is an overview of the switchboard setup process. Each step is covered in more detail in the sections below:

  1. Create the switchboard
  2. Create the bot switchboardIntegration, specifying the existing custom integration or partner integration to be wrapped
  3. Create the agent switchboardIntegration, specifying the existing custom integration or partner integration to be wrapped, AND the bot’s switchboardIntegrationId as nextSwitchboardIntegration
  4. Update the bot switchboardIntegration with the agent switchboardIntegrationId as nextSwitchboardIntegration
  5. Update the switchboard with the bot’s switchboardIntegrationId as defaultSwitchboardIntegration
  6. To activate, update the switchboard with enabled: true

Enable the switchboard

Once you’re ready to launch your switchboard, turning it on is a simple API call away.

Shorthand syntax

Agents and bots may invoke passControl, offerControl, and acceptControl actions by sending a specially crafted text message. The syntax follows the structure used by template messages. The syntax supports both %(())% and %{{}}% variants.

ActionSyntaxAlternative Syntax
Pass control to next integration%((switchboard:passControl))%%{{switchboard:passControl}}%
Pass control to named integration%((switchboard:passControl:agent))%%{{switchboard:passControl:agent}}%
Offer control to next integration%((switchboard:offerControl))%%{{switchboard:offerControl}}%
Offer control to named integration%((switchboard:offerControl:bot))%%{{switchboard:offerControl:bot}}%
Accept offer to take control of the conversation%((switchboard:acceptControl))%%{{switchboard:acceptControl}}%

Unlike the template syntax, the shorthand syntax is not meant to be combined with any surrounding text. If a note is intended to be sent to the user along with the action, it must be sent as a separate message.

A message sent containing a valid syntax pattern will be intercepted and not shown to the appUser, and any surrounding message text will be discarded. To illustrate, if an agent sends a single message with the text “I’ll switch you over %((switchboard:passControl))%”, the control will be passed as if the agent had sent the text as %((switchboard:passControl))% on its own.

Configuring the switchboard with Zendesk and a bot partner

What you’ll need

You’ll need the following before you get started with switchboard and a 3rd party bot:

  • Zendesk license, or other business software
  • Bot partner license, purchased directly from the partner
  • Sunshine Conversations license so you can configure your switchboard

Grant the bot partner access to your Sunshine Conversations account

The majority of our bot partners support OAuth, meaning that you can connect your bot account to your Sunshine Conversations account at the click of a button. Doing so will grant the bot partner access to handle messages and other events for a specific Sunshine Conversations app.

Some bot partners may also request additional credentials so they can manage the switchboard on your behalf.

After you’ve granted the bot partner access through OAuth, the partner will appear in your list of app integrations, alongside Zendesk or any other configured channels.

Set up your bot

Build your bot flows on the bot platform and publish them according to the partner’s instructions.

Create a switchboard

Some bot partners can create a switchboard on your behalf. If you’d like to create and manage your own switchboard, read below:

You’ll need to create a switchboard to house your switchboard integrations.

Switchboards are created with an empty post body. They begin in a disabled state by default so as to not interfere with the delivery of messages while it is being configured. We’ll enable the switchboard as the final step of this guide.

The {appId} should be the app containing the bot partner’s OAuth integration and your business system. The {appId} can be found by navigating to your app settings from the Sunshine Conversations dashboard. You can also use the Sunshine Conversations API to make a GET request to “List Apps” and retrieve the app_id.

POST /v2/apps/:app_id/switchboards

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards \
     -X POST \
     -u app_keyid:app_secretkey

Create switchboard integrations

In this step, we’ll place your existing bot integration on the switchboard. We’ll focus on a bot-to-agent handover use case, where you’re using Zendesk as a business system and a 3rd party bot to handle initial incoming messages.

The first integration you will set up is to the third party bot partner.

The second integration is to your Zendesk-connected webhook so that end users can reach your bot via your connected channels.

Finally, you’ll make a PATCH request to ensure that every switchboard integration has a value specified for nextSwitchboardIntegrationId.

Bot platform

To find the value of a bot partner’s “integrationType,” go to their Sunshine Conversations marketplace page and find the value from the URL: `https://app.smooch.io/integrations/
curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations \
     -X POST \
     -d '{"name": "bot", "integrationType": "CLIENT_ID", "deliverStandbyEvents": false}' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

Zendesk

Use the zd:agentWorkspace integrationType.

You should ensure that standby events are set to false for the Zendesk integration, otherwise every user message will be sent to the ticket (instead of a single digest message upon passControl.)

You should also ensure that the Zendesk integration specifies how many messages from the bot-end user history to include. This integer is set through the messageHistoryCount key. Note that if you’re using the Agent Workspace, the message history will always be the last 10 messages.

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations \
     -X POST \
     -d '{"name": "ZD", "integrationType": "zd:agentWorkspace", "deliverStandbyEvents": false, "messageHistoryCount": 10, "nextSwitchboardIntegrationId": "BOT_SWITCHBOARD_INTEGRATION_ID" }' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

Bot-to-agent handover on the switchboard

Update your bot switchboard integration

Update your existing bot switchboard integration to include the key nextSwitchboardIntegrationId and reference the Zendesk switchboard integration you just created. This way, every switchboard integration has a reference to the next integration in the loop.

You can also call GET /switchboardintegrations from the API to retrieve the ID of your switchboard integration.

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations/:switchboard_integration_id \
     -X PATCH \
     -d '{"nextSwitchboardIntegrationId": "ZENDESK_AW_SWITCHBOARD_INTEGRATION_ID"}' \
     -H 'content-type: application/json' \
     -u app_keyid:appsecretkey

Enable your switchboard

After you’ve configured your bot, you’re ready to enable your switchboard and handover the conversation.

First, you’ll need to enable your switchboard so the bot and agent switchboard integrations are active.

This API can be used to enable a switchboard, as well as to update the defaultSwitchboardIntegrationId. A defaultSwitchboardIntegrationId is required in order to enable a switchboard. For the purposes of this bot-to-agent handover flow, we recommend setting the default integration to your bot’s switchboard integration ID.

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards/:switchboard_id \
     -X PATCH \
     -d '{"defaultSwitchboardIntegrationId": "BOT_SWITCHBOARD_INTEGRATION_ID", "enabled": true}' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

Configuring the switchboard with Zendesk and your own bot

What you’ll need

You’ll need the following before you get started with switchboard and your in-house bot:

  • Zendesk license, or other business software
  • Sunshine Conversations license so you can configure your switchboard
  • Your own bot running as a web service

Add your bot to your app

Using the v2 API, create a custom integration through the API or dashboard to add your bot to your Sunshine Conversations app.

Create a switchboard

You’ll need to create a switchboard to house your switchboard integrations.

Switchboards are created with an empty post body. They begin in a disabled state by default so as to not interfere with the delivery of messages while it is being configured. We’ll enable the switchboard as the final step of this guide.

The {app_id} should be the app containing your bot and your business system. You can also use the Sunshine Conversations API to make a GET request to “List Apps” and retrieve the app_id.

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards \
     -X POST \
     -u app_keyid:app_secretkey

Create switchboard integrations

In this step, you’ll make two POST requests and one PATCH request to tie your existing integrations to your switchboard. We’ll focus on a bot-to-agent handover use case, where you’re using Zendesk as a business system and a bot to handle initial incoming messages. These API calls use basic authentication generated from the Sunshine Conversations admin dashboard.

You should ensure that standby events are set to false for the Zendesk integration, otherwise every user message will be sent to the ticket (instead of a single digest message upon passControl.)

You should also ensure that the Zendesk integration specifies how many messages from the bot-end user history to include. This integer is set through the messageHistoryCount key. Note that if you’re using the Agent Workspace, the message history will always be the last 10 messages.

The first integration you will set up is to your bot.

The second integration is to your Zendesk-connected webhook so that end users can reach your bot via your connected channels.

Finally, you’ll make a PATCH request to ensure that every switchboard integration has a value specified for nextSwitchboardIntegrationId.

Bot

The integrationId in the body of the POST is the ID of the custom integration (webhook) associated with your bot. You can make a GET request to retrieve the ID of the custom integration.

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations \
     -X POST \
     -d '{"name": "bot", "integrationId": "CUSTOM_INTEGRATION_ID"}' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

Zendesk

Use the zd:agentWorkspace integrationType.

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations \
     -X POST \
     -d '{"name": "ZD", "integrationType": "zd:agentWorkspace", "deliverStandbyEvents": false, "messageHistoryCount": 10, "nextSwitchboardIntegrationId": "BOT_SWITCHBOARD_INTEGRATION_ID" }' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

Complete the switchboard

In order to achieve bot-to-human handover on the switchboard, you’ll need to update and enable your switchboard.

Pass control from bot to agent

Now that your switchboard is enabled, you can pass control from your bot to your Zendesk agent.

Conversational control

Use the passControl action or shorthand syntax to incorporate a “Speak to an agent” flow in the bot interface.

When an end user engages with this flow (e.g. by tapping a “quick reply” button or typing “Speak to an agent”) then the conversation should be passed from the bot to the next switchboard integration— your Zendesk agent.

Once the conversation has moved into the Zendesk agent workspace, use the shorthand syntax to pass control from the agent back to the bot. In this context, it’s the agent persona who hands the conversation back to the bot.

The shorthand syntax will send a text message for the switchboard to interpret— end users won’t see the content of the shorthand syntax.

You can paste the shorthand syntax directly into the body of the ticket to submit, or you can use an existing Zendesk feature like macros or triggers to send the passControl action.

Listening to conversational control events

Your bot will need to listen to the v2 webhooks switchboard events so your bot knows when it’s received control of the conversation again:

{
  "app": {
    "id": “app:id"
  },
  "webhook": {
    "id": "webhook:id",
    "version": "v2"
  },
  "events": [
    {
      "id": "5fcd6c2d300a01000cd658df",
      "createdAt": "2020-12-06T23:41:33.182Z",
      "type": "switchboard:passControl",
      "payload": {
        "conversation": {
          "id": "f03c24679b0d471c5457893a",
          "type": "personal",
          "activeSwitchboardIntegration": {
            "id": "5fcd6bcaecb85b000cff12f1",
            "name": "webhook",
            "integrationId": "5fcd6b888947e5000c9ea434",
            "integrationType": "custom"
          }
        },
        "metadata": {
          "lang": "en-ca"
        }
      }
    }
  ]
}

Receiving a passControl event shows which integration is active in the conversation and therefore expected to respond to the user.

Switchboard webhooks for pass, offer, and accept control are detailed in the API reference.

Metadata sent to Zendesk

When passing control to Zendesk’s Agent Workspace you can include metadata to populate ticket fields on the Zendesk ticket. Note that this feature is currently only available to customers using Agent Workspace and not earlier versions of Support.

If a ticket has pre-existing values before passControl handover, the metadata sent with passControl will override the existing ticket values.

The schema for the metadata is as follows

dataCapture.systemField.<name_of_system_field> : "value"

dataCapture.ticketField.<custom_ticket_field_id>: "value"

So, for example, the JSON of a passControl body sent to Zendesk would look like:

{
   "switchboardIntegration": "zd:agentWorkspace",
   "metadata": {
       "dataCapture.ticketField.54321": "Blue",
       "dataCapture.ticketField.98112": "981235",
       "dataCapture.systemField.requester.name": "Frodo",
       "dataCapture.systemField.requester.email": "sneaky.hobbit@ringbearers.org",
   }
}

Zendesk system fields

A subset of Zendesk system ticket fields are supported in the switchboard:

  • priority
  • organization_id
  • group_id
  • assignee_id
  • tags
  • brand_id
  • requester.name
  • requester.email

Zendesk custom ticket fields

Custom ticket fields need to be created by the accounts. The ticket fields created by the account and their IDs are available using the Zendesk Support API. Note that this API follows a separate integration process than the Sunshine Conversations API. Learn how to get started with the Support API as a Zendesk Developer here.

Are you interested in becoming a Sunshine Conversations bot partner?

Sunshine Conversations is not accepting new bot partner submissions at this time. Please check back soon!