Workflow: Choosing between client-side messaging metadata and AI agent conversation tags

When working with messaging conversations, there are two different ways to use tags:

Client-side messaging metadata, set by the Web Widget or SDKs
Tags added in an AI agent flow, using Sunshine Conversations CRM actions such as Add conversation tags

These two methods can look similar because both can affect the context of a conversation and the ticket created from it. However, they are designed for different use cases and behave differently over time. This article explains how each option works, when to use it, and what to consider when deciding which one is best for your workflow. This workflow includes the following sections:
Understanding the difference
Tagging options for messaging conversations
Persistence of tags in Sunshine Conversations
When to use each tagging method
Additional resources


Expand all tabs



document.addEventListener('DOMContentLoaded', function () {
const toggleBtn = document.getElementById('master-toggle');

toggleBtn.addEventListener('click', function () {
const action = this.getAttribute('data-action');
const headers = document.querySelectorAll('.accordion');

headers.forEach(header => {
const isActive = header.classList.contains('active');
const panel = header.nextElementSibling; // Grabs the corresponding .panel container

if (action === 'expand' && !isActive) {
// Open it by simulating a standard click
header.click();
} else if (action === 'collapse' && isActive) {
// Close it by simulating a standard click
header.click();
}
});

// Flip button text and states
if (action === 'expand') {
this.setAttribute('data-action', 'collapse');
this.textContent = 'Collapse all tabs';
} else {
this.setAttribute('data-action', 'expand');
this.textContent = 'Expand all tabs';
}
});
});
Understanding the difference Client-side messaging metadata
Client-side messaging metadata is set from the frontend, such as:

the Web Widget loaded on a website
an SDK implementation

With this method, your developer sends metadata from the client into the messaging conversation. This can include conversation fields and conversation tags.
For tags, the Web Widget or SDK sends values using the messaging metadata APIs. In the conversation metadata, this appears as zen:ticket:tags.
This method is useful when the information is already available in the client, such as:

the product page the customer is viewing
an order number already displayed in the app
the customer’s current cart state
a known context that should be passed into the ticket

Adding tags to the conversation via a CRM action
This represents the CRM action in AI Advanced Agents that can be applied at different levels (see Creating and adding configured actions for AI agents).
This method is useful when the tag should be determined by the logic of the AI agent conversation itself, for example:

the user went through a specific path in a Dialogue or Procedure
the bot identified a use case during the conversation
the bot collected values that should be reflected in the conversation or downstream ticket

Although both methods use tags, they are not the same mechanism.
Tagging options for messaging conversations Option 1: Using client-side messaging metadata
If you want to pass tags from the Web Widget or from a mobile SDK, use the client-side messaging metadata APIs.
This approach is useful when:

the tag value is known when the conversation begins
the tag comes from the page or app context
you want to pass context into the conversation before a ticket is created
you want to manage tag values from the frontend

Examples include:

tagging a conversation based on the page category
tagging a conversation with a product family
tagging a conversation based on the customer’s logged-in experience

Benefits of client-side metadata tags
Client-side metadata tags are a good fit when the tag is tied to the customer’s current session context in the widget or app.
Benefits include:

The data can be set automatically without asking the customer to provide it
The tags can be set as soon as the page or app state is known
The data can be cleared using the messaging metadata APIs when the frontend context changes
This approach is well suited to information that is only relevant to the current client-side experience

Option 2: Using tags in an AI agent flow
If you want the bot to decide when tags should be added during a conversation, use the Add conversation tags CRM action in your AI agent flow.
This approach is useful when:

the tag depends on what happens during the bot flow
the tag should be added after the user answers a question
the tag reflects the conversation path or intent
the tag is part of your AI agent logic rather than your frontend implementation

Examples include:

adding a tag after the customer selects a support topic
adding a tag when the AI agent identifies a billing or return scenario
adding a tag to influence downstream routing or reporting

Benefits of AI agent flow tags
Using Add conversation tags in an AI agent flow is a good fit when the tag should be controlled by the bot itself.
Benefits include:

Tags can be added based on conversation logic
Tags can use values collected during the flow
Tags can be applied consistently across channels where the AI agent is used
Tags can help downstream routing, reporting, or field selection logic

Persistence of tags in Sunshine Conversations When using AI agent flow tagging with Sunshine Conversations, it is important to understand that information stored on a Sunshine Conversations conversation persists on that conversation. In Sunshine Conversations, a conversation is a persistent object. Metadata and tags added to that conversation remain associated with it until they are changed or overwritten. Because of this, Add conversation tags should be used with a clear understanding of how long the tag should remain attached to the conversation. This leads to two valid implementation choices. Choice 1: The tag should persist on the conversation
In some workflows, persistent tagging is the correct behavior.
Use this option when the tag is meant to remain associated with the conversation as part of the intended workflow, such as:

identifying the overall type of conversation
preserving a long-lived classification for future use
supporting downstream handling across the same Sunshine Conversations conversation

Choice 2: The tag is only valid for the current session
In other workflows, the tag is only relevant to the current session or a specific moment in the flow.
In this case, you should take steps to prevent the tag from carrying over unintentionally in the same Sunshine Conversations conversation.
A practical way to do this is to use the CRM action Overwrite conversation tags to clear the existing tags where needed.
For example, you can:

clear the conversation tags at the beginning of the flow
clear them at a specific point before applying new session-specific tags
clear them whenever you want to avoid carrying over metadata from an earlier interaction

If needed, an empty value can be submitted using a space character (" ") to effectively clear the existing conversation tags in the flow.
This approach is useful when tags are intended to be session-scoped rather than conversation-scoped.
When to use each tagging method Client-side messaging metadata
Choose client-side messaging metadata when:

the tag value is known in the Web Widget or SDK
the information comes from the page or app context
the tag should be managed from the frontend
the context is tied to the current widget or app experience

Add conversation tags in an AI agent flow
Choose Add conversation tags in an AI agent flow when:

the bot should decide when to add the tag
the tag depends on user responses or flow logic
the tag is part of the AI agent workflow
persistent conversation-level tagging is acceptable or intended

If you use Add conversation tags for information that is only valid for the current session, plan how to clear or overwrite those tags so they do not carry over unexpectedly. The most important distinction is behavior over time:
Client-side metadata is designed around frontend-managed context
Sunshine Conversations conversation tags persist on the conversation until they are changed or overwritten
Choosing the right method depends on whether the tag should reflect client context or bot flow logic, and whether the tag should be temporary or persistent. Additional resources If you would like to learn more, see:
Using messaging metadata with the Zendesk Web Widget and SDKs
About configured actions for AI agents
Creating and adding configured actions for AI agents
Available CRM actions for AI agents and Sunshine Conversations
Sunshine Conversations key concepts
