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
• Key switchboard concepts
• What to expect during a switchboard project
• Shorthand syntax
• Configuring the switchboard with Zendesk and a bot partner
• Switchboard integration for custom integrations (webhook)
• Pass control from bot to agent
• Per-channel default responder
• Metadata sent to Zendesk

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. In this example, the business is represented by two different switchboard integrations: a bot and a help desk business system.

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

Once the agent has solved the end user’s problem, they will close the ticket from their help desk system, at which point the user’s conversation would be 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 pass control to the bot, who can pick up the conversation with the customer and pass control back to the agent once the bot-assisted workflow is completed.

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 tickets in a given system can contain relevant history, while only being created when they need to be actioned within that system, and not before (signalled by the passControl).

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 having abrupt transfers of control as the only option. 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 can instead offer control of the conversation to the help desk integration, while remaining on the line.

Once a human agent joins the ticket via the help desk, the help desk integration can issue an acceptControl action, which transfers control from the bot integration to the help desk integration. Finally, when the problem is solved, the agent can close the ticket, and the help desk integration would issue a passControl action to return the conversation to the bot, ready for the next interaction.

Release control

The releaseControl action clears any existing active or pending switchboard integrations for a conversation. Typically this is used when a system in the escalation hierarchy considers the conversation to be resolved and there is no further action required. For example, when a human operator solves the user’s problem by marking a support ticket as closed. If the user then returns to the conversation after control has been released, the conversation will be once again assigned to the default switchboard integration, and the escalation flow restarts.

Note that the use of releaseControl differs from the case of using passControl to hand off back to the default integration. When using passControl, the assigned switchboard integration is determined based on the switchboard configuration when the interaction concludes. When using releaseControl, the assigned switchboard integration is not computed until the user returns to the conversation and starts a new interaction. If the switchboard configuration was changed in the meantime, the new default will be correctly used.

Unlike the Offer and accept control scenario above, this is an explicit means for returning conversation control back to its starting state, rather than escalating control to the next system in the hierarchy.

The releaseControl action does not create a webhook event when the ticket closes successfully.

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 signalling; an active switchboard integration is expected to respond to user messages while a standby integration is not.

The pending status is used for a switchboardIntegration 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 switchboardIntegration at a given time for a given conversation.

Switchboard integrations

Integrations are the vehicle for sending messages and other events to third party business systems and bots. They come in the form of native integrations baked into the Sunshine Conversations platform, OAuth integrations, or as custom integrations that define webhooks. Native integrations include Zendesk’s Agent Workspace, OAuth integrations are used by Sunshine Conversations’ bot partners listed in the marketplace, while custom integrations can point to your own system or any other public HTTPS endpoint.

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.

The active and pending switchboardIntegrations for a given conversation will receive all events related to activities within that conversation. switchboardIntegrations may opt to receive conversation related events even when they are in standby mode; This allows an integration to keep track of conversation events so that they have context on hand-off 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

When a switchboardIntegration is active (or configured with deliverStandbyEvents: true), they can expect to receive the following v2 API events (related to conversational activity):

• conversation:message
• conversation:read
• conversation:typing
• conversation:postback

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

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

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

Control transfer

Switchboards’ configuration must designate a defaultSwitchboardIntegration. When a new conversation begins, this switchboard integration will be assigned the active status for that conversation. Typically, a bot (or a Tier-1 agent-system) would usually be defined as the defaultSwitchboardIntegration.

Each switchboard integration’s configuration can include an nextSwitchboardIntegrationId, which dictates a default transfer path when the next keyword is used. Thus, a switchboard integration may escalate control of a conversation by performing a passControl or offerControl action without having to name a 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

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 id or partner integrationType 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

   1. Skip this step when the agent switchboardIntegration is Zendesk Agent Workspace
5. Update the switchboard with the bot’s switchboardIntegrationId as defaultSwitchboardIntegration
6. To activate, update the switchboard with enabled: true

The default switchboard integration specifies which of the switchboard 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. Having a default switchboard integration defined is a pre-requisite to activate a switchboard.

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.

The releaseControl action does not currently have a shorthand syntax.

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 (for access to APIs and to 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 Zendesk integration. 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 switchboard integration you will set up is for the third party bot partner’s integration.

The second switchboard integration will be for your Zendesk (Agent Workspace) integration, so that end users can reach your bot via your connected channels.

Switchboard integration for bot platforms (OAuth)

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/<clientId>

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations \
     -X POST \
     -d '{"name": "bot", "integrationType": "CLIENT_ID", "deliverStandbyEvents": false "nextSwitchboardIntegrationId": null}' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

If your bot (or other business system) does not integrate via OAuth, please see configuring a switchboardIntegration for a customIntegration below for how to configure a switchboardIntegration for a customIntegration.

Switchboard integration for Zendesk

Specify zd:agentWorkspace as the 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

Please note:

• deliveryStandbyEvents: should usually be set to false for Zendesk (type:"zd:agentWorkspace") switchboardIntegrations.
• messageHistoryCount: Note that if you’re using the Agent Workspace (with Suite or Chat), the message history will ignore this setting, including the last 10 messages of the conversation by default. Otherwise, with Zendesk Support or other business systems with a v1 webhook, specify how many messages (1-10) from the bot-end user history to include.
• When using the Agent Workspace (with Suite or Chat), it is possible to extend the length of the message history by specifying which Sunshine Conversations message ID marks the start of the history: include the first_message_id in the metadata object of calls to the passControl API endpoint.

{
    "switchboardIntegration": "zd-agentWorkspace",
    "metadata": {
        "first_message_id": "603012d7e0a3f9000c879b67"
    }
}

• When using the Agent Workspace (with Suite or Chat), it is possible to force the Support ticket’s channel type by including origin_source_type in the metadata object of calls to the passControl API endpoint. This value will override the ticket channel that Agent Workspace usually resolves to.

{
    "switchboardIntegration": "zd-agentWorkspace",
    "metadata": {
        "origin_source_type": "twilio"
    }
}

This is the list of allowed origin_source_type values and the via.channel of the corresponding Messaging tickets created in Zendesk:

Enable your switchboard

Now that you’ve configured your bot and Zendesk Agent Workspace switchboard integrations, you’re ready to enable your switchboard and handover the conversation.

This API call can be used to enable a switchboard, as well as to update the defaultSwitchboardIntegrationId in the same request. A defaultSwitchboardIntegrationId is required when enabling a switchboard so that the switchboard knows where to direct net-new conversations. In most cases, this will be your bot’s switchboardIntegrationId.

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

Switchboard integration for custom integrations (webhook)

A custom integration contains a webhook which can point to any external system or integration (without OAuth), including bots, other business systems, etc. Follow these steps when adding such a system to a switchboard.

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", "deliverStandbyEvents": false}' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

Please note:

• deliveryStandbyEvents: should usually be set to false; when set to true, user messages will be delivered even when this switchboardIntegration is not the activeSwitchboardIntegration.
• messageHistoryCount: for backwards compatibility with customIntegrations with v1.x webhooks only, this parameter controls how many (1-10) messages to include in the auto-generated digest message. The digest message is sent to v1.x webhooks when the corresponding switchboardIntegration becomes active as a result of a passControl API call. customIntegrations with version: v2 webhooks will not receive a digest message and should instead listen for passControl events and call the GET @/conversations/:id endpoint to fetch the required history.

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.

Per-channel default responder

You can assign a unique default responder to each channel by setting a defaultResponderId for your integrations. The defaultResponderId is the identifier of the switchboard integration you want to act as the initial responder for the given channel. See create switchboard integrations for more information on switchboard integrations.

curl $SUNSHINE_CONV_ROOT/v2/apps/:app_id/integrations/:integration_id \
     -X PATCH \
     -d '{"defaultResponderId": "SWITCHBOARD_INTEGRATION_ID"}' \
     -H 'content-type: application/json' \
     -u app_keyid:app_secretkey

When a channel has a defaultResponderId assigned, its switchboard integration will take precedence over the switchboard’s default responder for new conversations. Existing conversations will not reflect the latest setting unless releaseControl is performed to hand off the conversation to its default responder. See releaseControl for more information.

Channels without a defaultResponderId assignment will be handled by the switchboard’s default responder. You can remove a per-channel default responder by setting defaultResponderId to null.

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.

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",
        "first_message_id": "603012d7e0a3f9000c879b67"
    }
}

• ticketField metadata entries are only processed when the passControl results in the creation of a new ticket. (net-new user within Zendesk or previous ticket is closed)
• requester metadata entries are only processed when the passControl results in the creation of a net-new Zendesk user.

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

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.

Zendesk Bot responding with custom integrations

You can configure Zendesk Bot within Sunshine Conversations’ Switchboard without it being the default responder. In this scenario, the Zendesk Bot is part of your switchboard configuration but is only involved based on specific business logic. For example, suppose you have a custom integration that determines the identity of the user. Based on who the user is, you may want to direct them to various bots, including the Zendesk Bot. This allows you to do so while also allowing the proper greeting or answer execution.

When passing control to the Zendesk Bot, you must include the following metadata to trigger the bot’s greeting and default answer for a connected channel.

zen:answerbot:execute_flow: "channel="

We support only an integration_id forwarded from the original user conversation event. For example, if you select conversation:create for the example payload, the integration ID is events:payload:source:integrationId.

Here’s an example JSON of a passControl body sent to Zendesk:

{
    "switchboardIntegration": "zd-answerBot",
    "metadata": {
        "zen:answerbot:execute_flow": "channel=6086368afhfb5541d229n898"
    }
}

Are you interested in becoming a Sunshine Conversations bot partner?

If you’re interested in becoming a Sunshine Conversation Partner, see Sunshine Conversations Connect for more information.