Messaging user data in AI agents - Advanced

This guide will walk you through the process of using the Sunshine Conversations APIs in order to surface messaging user data in AI agents - Advanced flows. This method can be used to collect a user's verified email identity, or to detect whether or not a messaging user has been authenticated.

Note: Some Sunshine Conversations actions are already built in. This guide will walk you through how to incorporate additional user data into your bot flows by using the Sunshine Conversations API.

Overview

In this guide, we will be using the Integration Builder to make calls to the Sunshine Conversations API. We will be gathering additional data from the Sunshine Conversations Get User endpoint, which requires a user.id. To obtain this user.id we first need to make a request to the List Participants endpoint to find the end user participant currently interacting with our bot-driven conversation. Every conversation has an id generated when it first starts. This id is saved to a system parameter in AI agents - Advanced as platformConversationId. This is what we'll use to fetch our participants.

Once we have these two API integrations set up, we will be able to extract additional user fields for use as data as parameters in our bot flow.

Step 1. Conversation API keys

To make calls to the Sunshine Conversation API, your API Integration will need to be supplied with a Conversation API key, which you can create in Admin Center. This will provide you with an App ID, Key ID, and Secret key. For the API Integrations you create below, you will set the Authorization type to Basic Auth, with the Key ID for the Username, and Secret key for the Password. The App ID will be used in the URL of the endpoints we create below.

Step 2. List participants

First, create the List Particpants API integration with the following settings:

• Method type: GET
• URL: https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/conversations/{{platformConversationId}}/participants

Sample response:

{
  "statusCode": 200,
  "data": {
    "participants": [
      {
        "userId": "6824e96733d337097c54071c",
        "id": "68278940987d88b47bd9ca19",
        "unreadCount": 0,
        "lastRead": "2025-07-11T19:09:44.120Z",
        "clientAssociations": [
          {
            "type": "sdk",
            "clientId": "6824e96733d337097c54071d"
          }
        ]
      }
    ],
    "meta": {
      "hasMore": false
    }
  },
  "requestParameters": {
    "platformConversationId": "682789406ea4d75b392a3a0f"
  }
}

You'll use the following JSONata query in order to extract the userId from the payload:

data.participants.userId

Step 3. Get user

Next, create the Get User call.

• Method type: GET
• URL: https://YOUR_DOMAIN.zendesk.com/sc/v2/apps/YOUR_APP_ID/users/{{userId}}

Sample response:

{
  "statusCode": 200,
  "data": {
    "user": {
      "zendeskId": "35104420567444",
      "signedUpAt": "2025-07-11T19:09:44.120Z",
      "hasPaymentInfo": false,
      "identities": [
        {
          "type": "email",
          "value": "[email protected]",
          "verification": "low"
        }
      ],
      "toBeRetained": true,
      "id": "6824e96733d337097c54071c",
      "profile": {
        "surname": "Bear",
        "givenName": "Yogi",
        "email": "[email protected]",
        "locale": "en-US",
        "localeOrigin": "apiRequest"
      },
      "authenticated": true
    }
  },
  "requestParameters": {
    "userId": "6824e96733d337097c54071c"
  }
}

You can now use the following JSONata queries to extract the following properties from the response:

• Authentication state (boolean): data.user.authenticated
• Verified email (string): data.user.identities.value
• Support user id (string): data.user.zendeskId

Step 4. Bot flows

Now that we have the API Integrations built we will want to add them to our bot flows in order to retrieve the verified email identity, or to check if a user has been authenticated or not. Order the API Integrations so that the result of the "List participants" node flows into the "Get user" node.

View full size

When both requests are successful, we will have the user’s verified email and authenticated state available as flow parameters, and we can continue the flow from here or link back to the start of the flow.