Earlier this month I wrote a big article on the history of Zendesk Conversation channels. This article explained the multiple solutions Zendesk offered with regard to chat channels ranging from the old Zopim Chat right up to their newest AI Agents powered by Ultimate.

A History of Zendesk chat and messaging channels

Over the years, Zendesk evolved from simple email ticketing to offering a full suite of customer care solutions. They now support multiple channels, AI agents, social integrations, and web widgets. This article will dive into how their complex platform works, helping navigate conversational setups.

Internal NoteThomas Verschoren

One of the sections of the article showed the following flowchart, showing a setup where a customer has both an AI Agent running on the existing Zendesk Bot technology, and a modern bot powered by Ultimate.

Since more and more Zendesk users will be doing the upgrade to this more modern and powerful automation solution the coming months, chances are that some of them will run into this exact scenario.

When migrating bot platforms you can't just migrate all your brands and flows at once. Most customers will want to approach this with a phased process where they migrate one brand (or channel) at a time from the Zendesk Bot to Ultimate. Or, if you're coming from the likes of Ada or Certainly, you might want to temporarily run your Ada bot and Zendesk AI Agent in tandem.

This article will show you how to set this up.

Some context

Zendesk Suite comes with the Sunshine Conversations platform build in. Sunshine Conversations, or SunCo in short is the engine that connects channels like WhatsApp or a web widget, Bots like Ultimate or Zendesk, and Agent environments like Zendesk together.

Within SunCo there's a tool called switchboard. The switchboard orchestrates the interaction between customers, agents and bots by routing an incoming conversation to the right AI Agent, and escalate to the right platform.

Each Zendesk environment, regardless of having actively used SunCo or not, has a switchboard. This switchboard links your messaging channels to the Zendesk Bots, and handles the handover from bot to agents in the Agent Workspace.

The switchboard has a list of switchboard integrations linked to it. These integrations are your bots and agent environments. The switchboard has a default integration it routes all conversations too, and your integrations all have a default next responder. So for example you can have the Zendesk Bot as the default integration, and it hand off conversations to the Zendesk Workspace.

Your entire SunCo setup has a list of integrations linked to it, these are your social channels, web widgets and mobile SDKs. Each integration has a default responder (one of the switchboard integrations), and also lists a next responder for when e.g. the bot escalates to an agent. Those responders can be the default ones, or ones specifically set for that integration.

All interactions with the switchboard and its integrations happens on the API level, so when you want to make change or inspect the switchboard you need to setup a Sunshine Conversation API credentials in the Admin Center.

Gathering the initial context

Switchboard

The first API call we're going to make is one to {{url}}/v2/apps/{{appId}}/switchboards

This returns our main switchboard used by our Zendesk instance. From this data we need to copy the id of the switchboard, in our case 5f8ece73c031ec000c74a680.

{
  "switchboards": [
    {
      "id": "5f8ece73c031ec000c74a680",
      "enabled": true,
      "defaultSwitchboardIntegrationId": "6419d5aad477770116cfa596"
    }
  ]
}

Switchboard integrations

Once we have our switchboard, we can collect its integrations. We do this by making an API call to {{url}}/v2/apps/{{appId}}/switchboards/{{id}}/switchboardIntegrations with id being the switchboard id we captured in the previous step.

This returns an array of all the current switchboard integrations. You'll find two important ones in this list: zd:agentWorkspace – in other words, your agents – and zd:answerBot – your Zendesk Bots.

{
    "switchboardIntegrations": [
        {
            "id": "5f8ece7337f5bd000d6ae0ff",
            "name": "zd-agentWorkspace",
            "integrationId": "5f8ecbf2e2059d2c993eab02",
            "integrationType": "zd:agentWorkspace",
            "deliverStandbyEvents": false,
            "nextSwitchboardIntegrationId": "6419d5aad477770116cfa596",
            "messageHistoryCount": 10
        },
        {
            "id": "6419d5aad477770116cfa596",
            "name": "answerBot",
            "integrationId": "5f8ece75e2059d2c9995186b",
            "integrationType": "zd:answerBot",
            "deliverStandbyEvents": false,
            "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff",
            "messageHistoryCount": 10
        }
    ]
}

If your instance has multiple brands and bots you might wonder why you're seeing only one zd:answerBot in this list. Zendesk obfuscates the list of bots in your instance and takes care of routing the right channel (brand) to the right bot with internal logic not accessible over the SunCo APIs. But no need to worry, you can (un)link Zendesk bots to channels in the Admin Center and Zendesk takes care of their own native bots.

The item we want to note down here is the integrationId of the zd:answerBot, in our case 5f8ece75e2059d2c9995186b.

Integrations

And finally we need a list of the existing integrations in our instance. We need the IDs of these integrations so that, once we link the Ultimate bot, we can revert some of these channels back to being linked to the Zendesk Bot.

We can collect all integrations by calling {{url}}/v2/apps/{{appId}}/integrations . This returns a long list of channels similar to this one (I removed some elements to make it more readable)

{
    "integrations": [
        {
            "id": "61ea8723f4aa6100eb8a69e5",
            "type": "web",
            "displayName": "Internal Note",
            "defaultResponder": {
                "id": "6419d5aad477770116cfa596",
                "integrationId": "5f8ece75e2059d2c9995186b",
                "integrationType": "zd:answerBot",
                "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
            }
        },
        {
            "id": "646b411abc0c536ba1a98263",
            "type": "whatsapp",
            "displayName": "WhatsApp",
            "defaultResponder": {
                "id": "6419d5aad477770116cfa596",
                "integrationId": "5f8ece75e2059d2c9995186b",
                "integrationType": "zd:answerBot",
                "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
            }
        },
        {
            "id": "6706411852c663af3215a44f",
            "type": "web",
            "displayName": "AI Agent (Ultimate)",
            "defaultResponder": {
                "id": "6419d5aad477770116cfa596",
                "integrationId": "5f8ece75e2059d2c9995186b",
                "integrationType": "zd:answerBot",
                "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
            }
        }
    ]
}

If we look closes to one of the integrations we'll note a few things:

{
  "id": "61ea8723f4aa6100eb8a69e5",
  "type": "web",
  "displayName": "Internal Note",
  "defaultResponder": {
    "id": "6419d5aad477770116cfa596",
    "integrationId": "5f8ece75e2059d2c9995186b",
    "integrationType": "zd:answerBot",
    "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
  }
}

The id is the id of the integration, and is what we use in the API to make changes to its configuration. Note down the IDs of the channels you want to keep on Zendesk, in my case it's one of the web widgets and my WhatsApp channel.

The defaultResponder > integrationId is where we define which Bot (or switchboard integration) answers when a customer talks to that channel. In our case this is currently always the Zendesk Bot. The nextSwitchboardIntegrationId defines who should pick up the conversation if the bot needs to escalate. In our case this corresponds with the Agent Workspace.

Connecting Ultimate

Connecting Ultimate to Zendesk happens via a Sunshine Conversation integration. This is entirely handled within Ultimate via a nice UI flow, but you do need to grab a set of Sunshine Conversation API credentials from the Zendesk Admin Center first. I highly recommend creating a new pair of credentials for this so you can keep a clear overview of tokens used for your own API work, Ultimate, and outbound messages via e.g. the Relay app.

When linking Ultimate to Zendesk you can choose between SunCo or SunCo groups. I prefer the latter. The setup is a bit more convoluted but it allows for linking multiple Ultimate bots to Zendesk. You can use Ultimate's routing rules to define which bot should answer which channel, similar to how you would setup Zendesk Bots and multiple channels in Zendesk itself.

Once you link Ultimate all your channels will answer with the Ultimate Bot you just configured. If we take a look at our previous integrations list for example, we'll now see that our integration has a new defaultResponder, while retaining all other settings.

{
  "id": "61ea8723f4aa6100eb8a69e5",
  "type": "web",
  "displayName": "Internal Note",
  "defaultResponder": {
      "id": "670646ef88ab3af5a96c49b1",
      "integrationId": "670646eeec1612bbbc225995",
      "integrationType": "ultimate",
      "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
  }
}

Reverting some channels back to Zendesk

In my setup I have two brands. One is Internal Note, one is my Ultimate demo environment.
While I want to keep the web widget I created in Zendesk for Ultimate to remain linked to the Ultimate AI Agent, I want to make sure that my Web Widget and WhatsApp channel for Internal Note still answer with a Zendesk Bot. Otherwise all demos I build for this website will break.

Learn how to build a full-featured Flow Builder Bot for Zendesk.

In this article we will build a full-featured Flow Builder Bot for Zendesk. We’ll use every step type, use API calls and variables and show you how to create a bot yourself in a full length video tutorial.

Internal NoteThomas Verschoren

In order to revert some integrations back to the Zendesk Bot we need to execute a final API call for each integration we want to revert.

We need to send a PATCH command to the following url: {{url}}/v2/apps/{{appId}}/integrations/{{id}} with id being the id of the integration we want to update.

The payload of this patch command contains the id of the switchboardIntegration we want to set as its defaultResponder, in my case the id of the zd:AnswerBot collected earlier in this article.

{
  "defaultResponderId": "6419d5aad477770116cfa596"
}

Once you've executed this command for each integration, you'll end up with a new integrations list that looks like this:

{
    "integrations": [
        {
            "id": "61ea8723f4aa6100eb8a69e5",
            "type": "web",
            "displayName": "Internal Note",
            "defaultResponder": {
                "id": "6419d5aad477770116cfa596",
                "integrationId": "5f8ece75e2059d2c9995186b",
                "integrationType": "zd:answerBot",
                "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
            }
        },
        {
            "id": "646b411abc0c536ba1a98263",
            "type": "whatsapp",
            "displayName": "WhatsApp",
            "defaultResponder": {
                "id": "6419d5aad477770116cfa596",
                "integrationId": "5f8ece75e2059d2c9995186b",
                "integrationType": "zd:answerBot",
                "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
            }
        },
        {
            "id": "6706411852c663af3215a44f",
            "type": "web",
            "displayName": "AI Agent (Ultimate)",
            "defaultResponder": {
              "id": "670646ef88ab3af5a96c49b1",
              "integrationId": "670646eeec1612bbbc225995",
              "integrationType": "ultimate",
              "nextSwitchboardIntegrationId": "5f8ece7337f5bd000d6ae0ff"
            }
        }
    ]
}

End User experience

The above is quite technical, but luckily for our end-user we end up with a nice experience with two very web widgets that respond with either a Zendesk or an Ultimate powered AI Agent.