Skip to main content
Custom tags are key-value pairs that can be attached to user interactions to pass contextual metadata along with the response. These tags are used to send analytics data to AI for Service, where they can be used for dashboards, reporting, and segmentation. The tags added in Agent Platform are shared in the Execute API response payload. Client applications can consume and use these tags as needed.

​
Message Types

Tags can be added at three levels:
TypeDescription
UserUsed to emit user-specific data. Applies across all sessions for a user.
SessionUsed to emit session related data. Applies to a single session.
MessageUsed to emit message-level fields. Applies to an individual message.
In the response, all three different message types are shared as different objects. Learn More.

​
Adding Custom Tags

Custom tags can be defined and emitted from the following:
  • Code Tools
  • Workflow Tool(Script Nodes)
  • Agent Preprocessor
  • Response Processor
Tags are defined using the following format.
  • Each tag type is declared as a separate statement (user, session, and message-level tags) and cannot be combined in a single statement.
  • One or more tags of the same type can be updated using a single statement.
  • Tag name cannot be empty.
  • Tag value can be a static value or a dynamic variable like memory, environment, content or context variable. Variables are resolved at runtime during emitting.
// Single Tag update

tags.addUserLevelTag(tagname: string, tagvalue:string|boolean|number)
tags.addSessionLevelTag(tagname: string, tagvalue:string|boolean|number)
tags.addMessageLevelTag(tagname: string, tagvalue:string|boolean|number)

// Multi Tag Update

tags.addUserLevelTag({“tagname1: "tagvalue1", “tagname2”: "tagvalue2"})
tags.addSessionLevelTag({“tagname1: "tagvalue1", “tagname2”: "tagvalue2"})
tags.addMessageLevelTag({“tagname1: "tagvalue1", “tagname2”: "tagvalue2"})
Examples 
tags.addUserLevelTag({ "name": "John","location": "San Jose", "region": env.region })
tags.addMessageLevelTag("sentiment", "positive")

​
Runtime Behavior

  • Variable values for Tags are resolved before inclusion.
  • Tags from different sources are aggregated and added to the response payload.
  • If the same tag is updated at a different time during execution, the latest value of the tag is retained, and other values are overwritten.
  • Tags from multiple surfaces within a request are aggregated and emitted as a single tags object in the response payload.
  • Tags are emitted only at the end of the request execution.

​
Execute API Response Payload

Tags are appended to the agent response payload in Execute API. 
{
 "tags": {
   "user": [
     { "tier": "premium" }
   ],
   "session": [
     { "intent": "billing_inquiry" }
   ],
   "message": [
     { "sentiment": "positive" }
   ]
 }
}
  • Only tag types with values are included.
  • Empty arrays are omitted
Learn more about how tags are returned in the response.

​
Using Tags in AI for Service

Custom tags are used for analytics and reporting in AI for Service. They can be used for:
  • Custom dashboards
  • Filtering and segmentation
  • Analytics and reporting
More on using Custom Tags in AI for Service