Using messaging metadata with the Zendesk Web Widget and SDKs

What's my plan?

Suite

Team, Growth, Professional, Enterprise, or Enterprise Plus

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
• Bot builder (legacy AI agents)

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:

1. 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.
2. A developer codes the call to the metadata API using the field ID to connect the value to that field.
3. The data is programmatically set in the metadata API at runtime and is available in the next session.
4. 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

1. In Admin Center, click Objects and rules in the sidebar, then select Tickets > Fields.
2. Click Add field.
3. Select a field type, then enter a Display name.
4. (Optional) Enter a Description for the custom field. This is visible to admins only.
5. 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.
6. Enter a Title shown to customers.
7. 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.
8. If the end user must complete this field to submit the ticket, select Required to submit a request.
9. Configure any additional options depending on your field type.
10. (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.
11. Click Save or, to create another custom field, click the drop-down icon, select Save, and add another.
12. 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.

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()

Bot builder (legacy AI agents)

Fields updated using the metadata APIs will be populated with existing data and can be edited by end users when presented with this step. For more information, see Understanding answer flow step types and Creating custom ticket fields.