Context is king when it comes to providing good customer or employee support. When a customer is stuck on a checkout page, your AI Agent should be able to know that this is the most probable use case a customer is contacting you about. If they're looking at an order status page, the customer has a better experience if we pass that order number to the AI Agent or human agent instead of asking the customer to provide that context.

With the legacy Zendesk Bot we've been able to pass metadata to the bot, and this metadata would pre-fill custom fields you add as an ask for details step in Flow Builder. But with the arrival of the new AI Agents Advanced (née Ultimate), passing this data is handled a little bit differently.

Pre-filling custom fields in the Zendesk Bot with Messaging Metadata

This article contains three tutorials that explain how to use the new Messaging Metadata feature in Zendesk to pre-fill fields in your conversation bot flows.

Internal NoteThomas Verschoren

Since AI Agents Advanced were developed outside of the Zendesk ecosystem and relies on Sunshine Conversations to pass data back and forth between channels like the web widget and integrations like your AI Agent or Agent Workspace, retrieving that data is not as easy as with the old Flow Builder. But with that added complexity comes a lot more use cases that weren't possible before, so in the end, we win a lot more than we loose.

Flowset | Zendesk App | Cloudset

Dynamically guide Agents to help them work quicker, more accurately, and be more empowered. Amplify Zendesk for greater agility, productivity, accountability, and innovation.

CloudsetCloudset

In this article we'll handle the following scenarios:

1. We'll pass context to the web widget to be used in a conversation
2. We'll retrieve that context in our Bot Builder and use it in a reply
3. We'll update and set data in our Bot Builder and pre-fill custom fields in Zendesk upon escalation.

Let's dive in.

Passing data to the Web Widget

In this first flow we'll pass data to the Zendesk Widget and pre-fill a custom field in Agent Workspace. We do this by adding the following script after we initialize the Zendesk Web Widget.

zE("messenger:set", "conversationFields", [
  { id: "7662882404114", value: "Blade Runner" }
])

This script takes two parameters: an ID, which is the id of the custom field in Admin Center, and a value, which is, well, the value you want to pass to the field.
Important to note is that this field should be end-user editable.

When we add this code to our webpage and start a new conversation, we can use the Web Inspector of our browser to inspect a POST made to /appusers. Within the payload of this network action we can see conversation metadata which contains zen:ticket_field:7662882404114": "Blade Runner" , the data we just passed to the widget

{
    "conversations": [
        {
            "_id": "67b086dd3d4543c977962918",
            "type": "personal",
            "brandId": "4415880914322",
            "isDefault": true,
            "lastUpdatedAt": 1739622109.067,
            "createdAt": 1739622109.067,
            "metadata": {
                "zen:ticket_field:7662882404114": "Blade Runner"
            },
            "unreadCount": 0,
            "status": "active",
            "participants": [
                {
                    "_id": "67b086ddf9df531392498cee",
                    "appUserId": "67b086dd3d4543c97796290b",
                    "unreadCount": 0
                }
            ],
            "messages": []
        }
    ],
    //and more ...
}

And when we look at this conversation in Agent Workspace after escalation, we can also see our custom field being pre-filled.

This flow works for the legacy Zendesk Bot with flow builder, escalations via AI Agents Essential, and flows built on top of AI Agent Advanced.

Capturing metadata in AI Agent Advanced

With the old Flow Builder we could capture values in Custom Fields as parameters in flows. AI Agents Advanced can do the same thing, but it does require a bit of setup work in advance.

If we look back at the previous step, we can see that the data we pass to the Web Widget and conversation are stored as metadata in our conversation. This metadata is available when you are building out replies, and can be retrieved via Actions.
So let's start here.

Actions

To retrieve metadata from a conversation we need to create a new Action. This is done by navigating to the AI Agents Advanced dashboard, selecting Content and choosing Actions.

Within the configuration of your Action, chose Sunshine Conversation as the target, and select the Get conversation metadata Task. Retrieve the (Metadata) object and save it as a new parameter.

The value for Key is zen:ticket_field:7662882404114 . Make sure to replace the ID with the ID of your actual custom field! We call our parameter movie.

Using parameters in replies

By creating an action we can capture the metadata and store it in parameters. In order to actually use those values we need to do two things.

1. We need to add the action to a flow
2. We need to use a placeholder in our replies.

When we build a flow we can select our blocks and add our action to the first step of our flow. AI Agents Advanced allows to capture metadata at the start of any conversation too, but personally I prefer to contain all logic for a use case within that use case. It makes for easier troubleshooting.

After we run our action in the first step, we can then use the variable we set in subsequent actions by calling it via {{movie}}

There's one issue we run into though. If we do not pass a movie to the widget, our parameter will be blank and the customer will get weird reply. So, we should add a conditional step to our flow that checks the movie parameter in order to either show the pre-filled movie, or allow the customer to pick a movie from a list.

If you pass more than one variable to the widget you can either add an action per variable, or you can combine multiple retrievals in one action.

Updating metadata and passing data to agents upon escalation

So far we've taking data we send to the widget and used it in our reply. But there are scenario's where we want to send data from the conversation to Agent Workspace to be used in tickets, queues or triggers.

If we take a look at the flow we're building we need to ask the customer for a movie title if we don't pass one when the conversation starts.

We can do this by adding a visitor message block. We can then add either buttons with predefined titles, or we can process Free text written and store whatever the customer types.

One we've added our options we can select the Collect parameter option and store the input as a movie. One nice shortcut we can take here is leaving the parameter value field empty. This means that whatever label our button has, or whatever the customer types will be stored as the parameter's value.

And to wrap up the flow we can link all possible replies to an AI agent message that returns our {{movie}} parameter.

When a user then interact with our flow by either selecting a predefined movie or typing a random title, we can store the chosen option in our movie parameter and use it in our flow.

But, if we escalate this flow to an agent, they would not see this movie title in the custom field we used earlier. the movie parameter only lives within our dashboard and flows, and is not yet associated with the actual Sunshine Conversation conversation.

Passing data to Zendesk upon escalation.

If we want our movie to show up in Agent Workspace we need to add the movie title as metadata to our conversation. Similar to how we used actions to get the conversation metadata set by our script when loading the widget, we can use actions to set that same metadata.

Do this by creation a new action. But this time select Sunshine Conversations >> Update conversation metadata. As the Key, once again use zen:ticket_field:7662882404114 with the ID of your ticket field (which should be end-user editable), and add {{movie}} as the Value. By using our parameter as the value this will dynamically update our custom field value with – in our case – the chosen movie.

We can then use our action in an Escalation block, which means we'll send the latest value upon escalation to Agent Workspace.

And, similar to our first example, our agent sees the movie title right next to the ticket!

More use cases

Setting metadata for custom fields can be used for a lot of scenarios. We can use it to set a category field upon escalation to make routing to the right team easier. Or we can ask the customer for an order number and store that in the conversation, so that Agent Copilot or a sidebar app can make use of that data. You name it. The only requirement is that the custom ticket field is end-user editable.

If you want to update Dropdown fields, be sure to pass the associated tag as the value. For Lookup fields you need to pass the ID of the custom object, user or organization you wish to update.

I tried updating System Fields like subject or status the same way but sadly these fields don't seem to be accessible my adding them as conversation metadata on SunCo. (If you know how, let me know!)

Hope this was useful,

Thomas