Using messaging metadata with the Zendesk Web Widget and SDKs

Messaging metadata uses conversation fields and conversation tags (also known as custom ticket fields and custom ticket tags) to gather more information about the
support issue or product or service. You can also use this metadata for better ticket
routing in Agent Workspace by creating triggers in Admin Center. You can add messaging
metadata to your tickets and add them to your Help Center Submit a Request form if you
want end users to see the custom fields.
You can also use conversation fields and tags to send your agent messaging metadata from
Web Widget and Zendesk SDKs via client-side APIs. This enables the automatic transfer of
relevant information, such as product SKU, confirmation number, or order ID, to the
agent. This additional metadata aids in providing comprehensive context and enhancing
the quality of support provided.
The benefits of messaging metadata are:
Better agent context. Agents rely on correct contextual information presented in
their Agent Workspace view. Missing data or data provided by the end user can be
error-prone. By providing relevant information programmatically, you reduce the
errors and time spent asking for information.
Improved routing. Businesses rely on information in ticket fields and tags to
route the ticket to the correct agent group quickly. By providing more complete
data, routing the ticket to the correct agent group is more efficient.
Optimal experience for the end user. End users won’t have to re-enter data
already available on the client side.
Improved automation flows. Bot builders can leverage the additional data for a
better end-user experience.
Feature parity with the Classic Web Widget Support SDKs, which
supports ticket fields and tags.


This article includes the following topics:
Messaging metadata
overview
Configuring for messaging
metadata
Adding a conversation
field
Using the metadata
APIs
Using metadata in AI agent conversations




Messaging metadata overview

Suppose you have an online store, and an end user is looking at a specific shoe. On
this page, there are the product SKU, size, and color options. When the end user has
questions about this shoe, it is necessary to know the above information so the
agent knows exactly what shoe the end user is interested in. Without custom ticket
fields, the live or AI agent must ask the end user for all this information before
answering the question.
With messaging metadata, you can get this data programmatically from the page or by
having the end user fill out a form or a combination. For example, using a custom
ticket field, you can use an API to retrieve the product SKU from the product page.
Since the end user may or may not have selected the color and size, an AI agent (for
example) can query these using custom ticket fields and display their default
values. The end user can update the values or leave the default ones.
This is different from using variables and custom fields in AI agent standard responses or bot builder (legacy). With messaging metadata:
End users do not have to manually enter data that exists on the page they
are visiting. For example, if an end user is on a return order form and the
order id exists on that page, you can programmatically retrieve that number
instead of having the end user type it in.
Extra context can be added automatically to assist the agent. For example,
if an end user has their shopping cart open, you can set a conversation
field “Active Shopping Cart” to true.
You can control the path followed by an AI agent. For example, if an end
user is on a page for Brand A, you can set this in a field so that the bot
traverses the Brand A path.





Configuring for messaging metadata

Conversation fields need to be configured within Admin Center to allow
their values to be set by an end user when the fields are created. Conversation tags
do not need any prerequisite steps before the metadata API can be used.
The first step to using messaging metadata is determining what data you want to
collect and how to use it. This is entirely dependent on your use case. You must
fully understand the end-user experience when your developer sets the ticket field
and tag values programmatically on the Zendesk Web Widget and SDKs.
Once you understand your data, the following steps are performed:
A Zendesk admin creates a custom ticket field and passes the field name and
ID to a developer, along with the use and desired data to collect.
A developer codes the call to the metadata API using the field ID to connect
the value to that field.
The data is programmatically set in the metadata API at runtime and is
available in the next session.
Ticket field and tag data are added to the support ticket at the time of
ticket creation.




Note: Messaging metadata is applied to only one ticket. If a
subsequent ticket is created that relates to the same conversation, messaging
metadata is applied only to the first ticket.

The ticket fields and tags metadata are applied to the ticket on ticket creation. For
example, if you configure your widget to instantly chat with a live agent (rather
than an AI agent), then opening the widget instantly creates a new ticket and only
the ticket fields and tags that have been set prior to the ticket being created are
added to it.
Once a ticket is closed, messaging metadata in the backend (such as tickets) is reset
to an empty null state. Currently, messaging metadata persists on the client side
and will be addressed in a future release.



Adding a conversation field

Customers on any Support plan can create conversation fields, but you must have messaging configured and be using the
messaging Web Widget or SDKs for messaging.
System ticket fields, such as the Priority
field, are not supported. They appear in the default contact form (and any other
ticket form), when accessed from the help center but do not appear in the Web
Widget.

Note: Regular expression, Date, and Multi-select custom fields can be set through the
metadata APIs but are not displayed in the conversation.
You can verify a conversation field has been set by viewing the ticket information
within Zendesk Agent Workspace or with Zendesk APIs. See Using messaging metadata for an
example.

To add a conversation field
In Admin Center, click
Objects and rules in the sidebar, then select Tickets > Fields.
Click Add field.
Select a field type, then enter a Display name.
(Optional) Enter a Description for the custom field. This is visible
to admins only.
Under Permissions, select Customers can edit.
Note: Because the values can be set via a public
client-side API call, the data should always be treated as if an end
user has provided the data. Using these APIs is not recommended for
sensitive data.

Enter a Title shown to customers.
If the agent must complete the field to solve the ticket, select Required
to solve a ticket. This option is not available on all field
types.
Note: When agents merge a ticket, they don't
need to fill in the required fields because merged tickets bypass Solved
and go directly to Closed. This setting is also bypassed if a business
rule changes the ticket to Solved because a system process solves the
ticket rather than an agent.

If the end user must complete this field to submit the ticket, select
Required to submit a request.
Configure any additional options depending on your field type.
(Optional) Specify a Default value for the custom field.
Note: The default value in a drop-down list only applies
to new tickets created by agents through the Support interface or
created by users wherever the ticket form is displayed. If you change an
existing ticket form to one with a drop-down list with a default option,
the default option is not displayed and is shown as blank.

Click Save or, to create another custom field, click the drop-down
icon, select Save, and add another.
Save the Field ID of the field you just created as you'll need it when using
the metadata API.


Once created, developers can use the /api/v2/ticket_fields API to
view conversation field data. Here is an example response:
[
{
url: "https://z3n-lhills.zendesk.com/api/v2/ticket_fields/10093547287955.json",
id: 10093547287955,
type: "integer",
title: "Bike Order id",
raw_title: "Bike Order id",
description:
"An API will populate this bike order id value",
raw_description:
"An API will populate this bike order id value",
position: 9999,
active: true,
required: false,
collapsed_for_agents: false,
regexp_for_validation: "\A[-+]?\d+\z",
title_in_portal: "Bike Order Id",
raw_title_in_portal: "Bike Order Id",
visible_in_portal: true,
editable_in_portal: true,
required_in_portal: false,
tag: null,
created_at: "2022-10-04T04:48:05Z",
updated_at: "2022-10-04T04:48:05Z",
removable: true,
agent_description: "Order id from our bikes catalog",
},
]


Clearing the conversation field

There may be times when you must clear the conversation field values. This
depends on your use case and is done when the retrieved data is no longer valid.
For example, suppose you are using conversation fields to collect data from an
end user’s online cart. If the end user deletes all items in their cart, your
collected data is no longer valid, and you can clear those conversation field
values.
You clear conversation fields using the clearConversationFields(
) API.




Adding a conversation tag

Tags are words or combinations of words you can use to add more context to tickets
and topics. You can apply tags to tickets, users, and organizations. For example,
tag all requests that are actually sales inquiries with a tag like 'sales' or
'about_sales.' You can then create a view or a report to track these requests.
For more information, see About tags.



Using the metadata APIs

See Using messaging metadata in the developer
documentation for an example of using the metadata APIs.


Setting conversation fields and tags

You set the conversation field values using the
setConversationFields API. For example, if your custom
ticket field ID is 10093547287955 and you want to set its value to the string '548832222',
then you would call:
zE('messenger:set', 'conversationFields', [{ id: '10093547287955',
value: '548832222'}]);
If you use a custom drop-down field or any field that associates a field value
with a tag, setting the custom field value also sets the custom tag value in the
resulting ticket.









Client-side API to set conversation fields




Web Widget
zE('messenger:set',
'conversationFields', [{ id: '{field ID}', value:
'{value}'}])


iOS
Zendesk.instance.setConversationFields(["{field ID}” :
“{field ID}"])


Android
Zendesk.instance.setConversationFields(listOf(
TicketField(id="{field ID}", value="{value}"
)))


Unity
ZendeskSdk.Instance.Messaging.SetConversationFieldsAsync(Dictionary<string,
object> ticketFields)




Here is an example response for setConversationFields:
conversation: {
...
metadata: {
"zen:ticket_field": "30289064739483",
...
},
}

Note: {field ID} must be a string. If not, it
will be converted to a string. {value} must be a string,
number, or boolean.


Tip: You can then use the information from this
response in AI agent conversations. See Using metadata in AI agent conversations.
You set conversation tag values with the
setConversationTags API. Similar to the
setConversationFields API, if you set a custom tag
associated with an editable custom field, then the custom field is set. If the
custom tag is associated with a private (non-editable) custom field, then the
custom field is not set.









Client-side API to set conversation tags




Web Widget
zE('messenger:set',
'conversationTags', ['{tag value}', '{tag
value}'])


iOS
Zendesk.instance.setConversationTags(["{tag value}",
"{tag value}"])


Android
Zendesk.instance.setConversationTags(listOf("{tag
value}", "{tag value}"))


Unity
ZendeskSdk.Instance.Messaging.SetConversationTags(List<string>
tags)




Here is an example response using
setConversationTags:
conversation: {
...
metadata: {
"zen:ticket:tags": "likes-nike-trainers, frequent-shopper",
},
}



Clearing conversation fields and tags

You can clear conversation field values and tags when the client side
context changes. For example, the end user moves away from a product page to
your main store landing page. Any data you collected from that product page is
no longer valid.
To do this, use the ClearConversationFields and
ClearConversationTags APIs. These clear all conversation
fields and tags. You cannot clear an individual field or tag.









Client-side API to clear conversation fields and tags




Android

Zendesk.instance.clearConversationFields()
Zendesk.instance.removeConversationTags()



Unity

ZendeskSdk.Instance.Messaging.ClearConversationFields()
ZendeskSdk.Instance.Messaging.ClearConversationTags()









Using metadata in AI agent conversations

Fields updated using the metadata APIs will be populated with existing data and can
be edited by end users when presented with this step during a conversation with an
AI agent.
To use metadata in AI agent conversations, first create a custom ticket field and then see
the following resources for how to use that field in an AI agent:

For advanced AI agents: Creating and adding actions for advanced AI
agents

For legacy AI agents: Understanding answer flow step
types