Over these last few years Zendesk has seen a lot of changes in their approach to conversations, bots and messaging channels. They've grown from basic chat with Answer Bot towards a powerful, but complex, system of API layers covering Zendesk Messaging, Sunshine Conversations – and now – 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

If you follow the documentation and guidelines it's fairly easy to get your AI Agent, powered by Ultimate (Ultimate Bot in short) connected to your Zendesk instance and make sure that any information your customer entered in the chat becomes visible to your agents upon escalation.

But sometimes you want to do more complex setups that require you to dive into the Ultimate conversation data, or worse, into the Sunshine Conversation API. It's in those scenarios it becomes clear how many layers of integrations there's actually running in between your customer and your agents.

One of these scenarios came up recently: a customer of mine wanted to lookup information about their end-user contacting them via the Ultimate Bot. The user contacted them over WhatsApp and they wanted to automatically lookup information about the user in their CRM based on the WhatsApp number, to then great the user with their name and have context like recent orders available to the bot to display to the user. Since personalized interactions are imported to give good service, this seemed like a logical thing to implement.

Where is the phone number stored?

Sunshine Conversation User Object

All user information for conversations that happen via Ultimate or Messaging are stored in Sunshine Conversations and are accessible as metadata on the user object. Sunshine Conversations (SunCo) is the underlying layer that routes conversations between users, bots and agents, and stores user and conversation information for those elements to interact with.

"user": {
  "signedUpAt": "2023-07-19T06:04:06.199Z",
  "hasPaymentInfo": false,
  "identities": [],
  "toBeRetained": true,
  "id": "372b66ef40d51a45bad4a0b8",
  "profile": {
    "surname": "Verschoren",
    "givenName": "Thomas",
    "locale": "en-GB",
    "localeOrigin": "apiRequest"
  }
}

This data is accessible in Ultimate via actions. They allow you to grab information from the SunCo objects and store them as variables usable in conversations, conditional flows or API calls.

My first idea of grabbing the phone number was basic: create an action in Ultimate that gets the SunCo user object, grab the phone number and store it as a variable.

Sadly, no such data is available on the user level in SunCo metadata. But since the phone number does show up for agents in Zendesk upon escalation it has to be available somewhere in the SunCo data.

Clients

If you ask me to describe SunCo in one word I'd call it an onion. You can keep unwrapping layers to find new data hidden somewhere.

So, while diving into the APIs to find that WhatsApp number I found the clients object. It's a different object that inherits from the users object and contains information about our user on the different platforms they interact with.

And, conveniently for our use case, it contains exactly what we need. The users' phone number at clients[type="whatsapp"].raw.from

"clients": [
  {
    "integrationId": "64b77c147790bda022cc8143",
    "type": "whatsapp",
    "externalId": "1234567890",
    "id": "64b77cd6b2c7874df3249199",
    "displayName": "Thomas Verschoren",
    "status": "active",
    "raw": {
      "profile": {
        "name": "Thomas Verschoren"
      },
        "from": "32472123456"
      },
    "lastSeen": "2024-12-03T19:07:50.959Z",
    "linkedAt": "2023-07-19T06:04:06.194Z"
  }
]

Getting the phone number in Ultimate

Now that we know where our phone number is stored, let's get that number into our conversation.

This will be done in three steps:

1. We get the user_id and store it as a parameter
2. We make an API call to /clients get the phone_number and store it as a variable
3. We use that in our conversation

Getting the user ID

The user id is available in the SunCo metadata as an element in the user metadata. We can access this in Ultimate by creating an action that gets that piece of data.

This is done via Content > Actions > Create Action. Select the Sunshine Conversations target, and the Get User task. retrieve the <metadata> field and store the id key as user_id

Now that we have an action we need to run it at the right moment in order to grab our user_id. This can be done with an event-based action that triggers on Chat started. This is the earliest moment in the conversation we can start doing something, so it's ideal for grabbing our user_id

Doing so is done via Bot Settings > Events and Actions. Select Chat started in the event picker top right, and choose our action from the options that appear in the dropdown.

If you now start a new conversation over WhatsApp to your bot, you'll see the user_id appear in the conversation logs. Copy your user_id cause we need it for testing our API.

Getting the phone number via an API integration

As mentioned earlier, getting the actual phone numbers required making an API call to the /clients API endpoint for Sunshine Conversation.

Doing so in Ultimate requires us to setup an API Integration.
Before we move forward we do need to grab Sunshine Conversations credentials from our Zendesk instance. You can do this via the Admin Panel > Apps and Integrations > Conversations API. Copy down the App ID, Key ID and Secret Key.

In Ultimate go to the API integrations and setup a new API integration. I called mine SunCo UserData, but chose whatever fits you.

In the Request parameters section we need to define what variables we need in our API call. Since we're calling https://api.smooch.io/v2/apps/{{app_id}}/users/{{user_id}}/clients we need to set our user_id variable. Set the test value to the user_id we copied in the previous step, and set the type to string.
We do not need a variable for the app_id since that value will never change and is linked to our API credentials.

In the Production (default) section we enter our URL, replacing {{app_id}} with the actual App ID from our SunCo API tokens we copied earlier.

For authorization I ran into a little snag since it would not accept Key ID // Secret as a value for Basic Auth using the native Authorization tab. So I opted for a custom Header with Key Authorization and Value Basic (base64encoded KeyId:Secret) . I used https://www.base64encode.org to create this encoded token, or you can copy yours from Postman if you're testing and following along there.

And finally, in the Success section, we can add a Session parameter that grabs the WhatsAppNumber from the returned API data .
The number is stored in data.clients[type="whatsapp"].raw.from

Once setup you can save the API integration and use the Test Production button to see if everything works.

Using the API call in a use case reply

Now that we have our API call setup we can use this in flows. This is done by creating a new reply (or editing an existing one) and adding an API integration block to the conversation. This will create a lot of different branches in your conversation flow, but the important one is the Success branch. This is where the API successfully retrieved a phone number for the user.

Just as with any Ultimate flow, you can handle the failure and fallback cases independently. (Useful for scenarios where you use one reply for all your channels and want maybe to ask the user for a phone number in the fallback flow.

Since the WhatsAppNumber variable is set on the conversation level, I can now make subsequent API calls that use that variable as its input to retrieve user information from my CRM, or I can use the {{WhatsAppNumber}} syntax to print out the number in a Bot message.

Conclusion

There's plenty of powerful things hidden in the Sunshine Conversations API you can use in combination with AI Agents. Gathering (and updating) user information is just one of those.

One of the things I've been testing (or playing) with these last few weeks is Conversation Extensions which allow you to embed webforms or webpages in the widget and push the results of those form submission or website actions back to the conversation. But that's content for a future article.