Sunshine Conversations enables seamless switching between multiple parties within a conversation:

• The end-user

• The bot

• Agents

  This feature, called Switchboard, is explained in detail here.

❗️

Important

Agent handover using Switchboard is only supported for Sunshine Conversations user channels. It is not compatible with the ViaSay widget.

Set Up Agent Handover in Sunshine Conversations (via Zendesk)

To configure an agent handover through Sunshine Conversations, follow these steps:

1. Ensure You Have a Zendesk Integration in Your Sunshine Conversations App

This integration must be added by the Zendesk team. Contact your Zendesk representative to set it up.

2. Link Your ViaSay Bot with Your Sunshine Conversations App

Follow the instructions provided in the Sunshine Conversations documentation.

3. Create and Configure the Switchboard

The Switchboard must be configured via API using your Sunshine Conversations credentials. Detailed steps are provided in the Official Switchboard Documentation .

📓

Note

Sunshine Conversations uses two different "integration" concepts:

Sunshine Conversations uses two different "integration" concepts:

• Integration: This is set up via the Sunshine Conversations web UI.
• Switchboard Integration: This is a link between a Switchboard and an Integration.

In the following steps, always use Switchboard Integration IDs, not Integration IDs.

Summary of Creating and Configuring the Switchboard:

1. Obtain an Authentication Token: Use an HTTP client like Postman to call the Sunshine Conversations API. Create an API key in your Sunshine Conversations admin panel and generate a JWT token.
2. Get the Switchboard ID: Call the API (GET <https://api.smooch.io/v2/apps/:app_id/switchboards>). You should already have an existing Switchboard, as it is automatically created when adding the Zendesk integration to your app.
3. Add the ViaSay Chatbot Integration: Use the API call (POST /v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations) with the following payload:{"name": "mindsay_bot", "integrationType": "mindsay", "deliverStandbyEvents": false}
4. Retrieve the IDs of Your ViaSay Chatbot and Zendesk Switchboard Integrations: Use the API (GET /v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations) to get the value of the id attribute (not the integrationId). The Zendesk integration will have zd:agentWorkspace as integrationType.
5. Update the Zendesk Switchboard Integration: Set ViaSay Chatbot as the next Switchboard Integration (PATCH /v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations/:zendesk_switchboard_integration_id with payload:{ "nextSwitchboardIntegrationId": "<mindsay_switchboard_integration_id>" })
6. Update the ViaSay Chatbot Switchboard Integration: Set Zendesk as the next Switchboard Integration and enable standby events (PATCH /v2/apps/:app_id/switchboards/:switchboard_id/switchboardIntegrations/:mindsay_switchboard_integration_id with payload:{ "nextSwitchboardIntegrationId": "<zendesk_switchboard_integration_id>", "deliverStandbyEvents": true })
7. Enable and Configure the Switchboard: Make the Switchboard active and set ViaSay as the default integration (PATCH /v2/apps/:app_id/switchboards/:switchboard_id with payload:{"defaultSwitchboardIntegrationId": "<mindsay_switchboard_integration_id>", "enabled": true}).
   
   

   ❗️

   Important

   At step 6, set deliverStandbyEvents to true to ensure ViaSay receives a copy of the conversation between the end-user and the human agent. If not set, the conversation will appear incomplete on ViaSay Chatbot's conversation page.
   
   

4. Define the Agent Switchboard Integration ID in ViaSay

In your Sunshine Conversations channel configuration in ViaSay, enter the Zendesk Switchboard Integration ID. ViaSay Chatbot uses this ID to pass control to the agent handover solution.

Once this is set, handover to this service can be configured in bot actions.

📔

Notes About Handover

When an agent handover is executed in Zendesk using Sunshine Conversations:

• Closing a ticket in Zendesk does not automatically pass control back to the bot.
• The agent must manually pass control back to the bot before closing the ticket by using the Sunshine Conversations shorthand syntax: %((switchboard:passControl))%.

Delete a Sunshine Conversations Integration with a Switchboard

Currently, there is no automated way to delete a Sunshine Conversations integration with a configured Switchboard. Attempting to delete such an integration on either ViaSay or Sunshine Conversations will result in an error.

To delete the integration, you must first update the Switchboard:

• Ensure the defaultSwitchboardIntegrationId value of the Switchboard does not point to the ViaSay Chatbot Integration.
• Verify that no other Switchboard Integration has a nextSwitchboardIntegrationId pointing to the ViaSay Chatbot Integration.
• Remove the ViaSay Chatbot Integration from the Switchboard.

To make these updates, use the Sunshine Conversations Switchboards API and Switchboards Integrations API .