> ## Content Index > Fetch the complete content index at: https://internalnote.com/llms.txt > Use this file to discover other available public pages before exploring further. # Collecting SunCo user information for AI Agents powered by Ultimate - URL: https://internalnote.com/ultimate-sunco-user-information/ - Published: 2024-12-05T09:00:32.000Z - Updated: 2025-09-08T06:40:57.000Z - Description: Zendesk has a multi-layered messaging system integrating AI bots, APIs, and Sunshine Conversations. This article explores setting up Ultimate Bot for personalized interactions, accessing user data like WhatsApp numbers, and leveraging APIs to enhance conversational workflows. - Author: Thomas Verschoren - Tags: AI Agents 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 channelsOver 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.![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/icon/internalnote_social_eggshell@2x-10.png)Internal NoteThomas Verschoren![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/thumbnail/fb-deviceinfo-6-1.png)](https://internalnote.com/history-of-zendesk-messaging/) 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. ```json "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" } } ``` https://api.smooch.io/v2/apps/{{app\_id}}/users/{{user\_id}} 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. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/client_diagram_v2.png) And, conveniently for our use case, it contains exactly what we need. The users' phone number at `clients[type="whatsapp"].raw.from` ```json "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" } ] ``` https://api.smooch.io/v2/apps/{{app\_id}}/users/{{user\_id}}/clients # 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 `` field and store the `id` key as `user_id` ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/Action.png) 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. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/Add-Action.png) 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. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/Logs.png) ### 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. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/API.png) In Ultimate go to the API integrations and setup a new API integration. I called mine *SunCo UserData*, but chose whatever fits you. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/API-Parameters.png) 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. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/API-Production.png) 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](https://www.base64encode.org/?ref=internalnote.com) to create this encoded token, or you can copy yours from Postman if you're testing and following along there. 💡 If anyone can get the native Authorization working, let me know! ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/API-Success.png) 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. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/Flow.png) 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](https://docs.smooch.io/guide/conversation-extensions/?ref=internalnote.com) 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. ![](https://storage.ghost.io/c/ca/c0/cac0c82b-bc4d-4404-9eb4-9cc75e8d045e/content/images/2024/12/Extensions.png) ## Sign up for Internal Note Turning Zendesk into practice. – A newsletter about Zendesk written by Thomas Verschoren. Subscribe Email sent! Check your inbox to complete your signup. No spam. Unsubscribe anytime.