Implementing Messaging Metadata

Introduction

Messaging metadata lets you attach additional information to conversations in the Zendesk SDK. This metadata can be used to provide context to agents, automate routing, and personalize the support experience for your users.

For more details, see the Using messaging metadata with the Zendesk Web Widget and SDKs.

For example, you can tag conversations with promo codes, set custom fields for order numbers, or indicate user segments—all directly from your app.

Warning: The SDK must be initialized before using any of these APIs. See Initialize the SDK for more details.

For a working example, see the Zendesk SDK Metadata Demo App.

Use cases

Here are some common use cases showing how tags and custom fields can enhance ticket management in Zendesk:

• Tagging conversations: Add tags like promo_code, vip_user, or bug_report to help agents quickly identify the context of a conversation.
• Custom fields: Set custom ticket fields (e.g., order number, flight number, subscription type) to pass structured data to Zendesk.
• Routing: Use tags or fields to automate routing to the right department or agent group.

Setting conversation fields

You can set values for conversation fields to add structured data to a conversation. Conversation fields must be created as custom ticket fields in Zendesk Admin Center and configured to allow end user input.

Kotlin

val fields = mapOf("4422761977114" to "FA2590")
Zendesk.instance.messaging.setConversationFields(fields)

Java

Map<String, Object> fields = new HashMap<>();
fields.put("4422761977114", "FA2590");
Zendesk.getInstance().getMessaging().setConversationFields(fields);

Note: Conversation fields are stored in the SDK and are only applied to a conversation when the user starts a new conversation or sends a new message.

Warning: System ticket fields (for example, Priority) are not supported. Supported value types: string, number, boolean.

For more information, see Using messaging metadata with the Zendesk Web Widget and SDKs.

Clearing conversation fields

Clear all stored conversation fields when the client-side context changes (for example, when the user logs out or switches context).

Kotlin

Zendesk.instance.messaging.clearConversationFields()

Java

Zendesk.getInstance().getMessaging().clearConversationFields();

Note: This does not affect fields already applied to existing conversations.

Setting conversation tags

Tags are simple string labels you can attach to conversations for quick filtering, routing, or reporting.

Kotlin

val tags = listOf("promo_code", "discount")
Zendesk.instance.messaging.setConversationTags(tags)

Java

List<String> tags = new ArrayList<>();
tags.add("promo_code");
tags.add("discount");
Zendesk.getInstance().getMessaging().setConversationTags(tags);

Note: Tags are stored in the SDK and are only applied to a conversation when the user starts a new conversation or sends a new message.

Clearing conversation tags

Clear all stored conversation tags when the client-side context changes.

Kotlin

Zendesk.instance.messaging.clearConversationTags()

Java

Zendesk.getInstance().getMessaging().clearConversationTags();

Note: This does not affect tags already applied to existing conversations.

FAQ

Q: When are conversation fields and tags actually applied to a conversation?
A: Fields and tags are only applied when the user starts a new conversation or sends a new message. Setting them in the SDK does not immediately update existing conversations.

Q: Can I use system ticket fields (like Priority) as conversation fields?
A: No. Only custom ticket fields created in Zendesk Admin Center and configured for end-user input are supported. System fields are not supported.

Q: What types of values can I use for conversation fields?
A: Supported types are string, number, and boolean.

Q: Will clearing fields or tags remove them from existing conversations?
A: No. Clearing fields or tags only removes them from the SDK's local storage. Any fields or tags already applied to existing conversations remain unchanged.

Q: Where can I find a working example?
A: See the Zendesk SDK Metadata Demo App for practical usage.