Every conversation event sent to Pendo, whether through the client-side method, server-side API, Python SDK, or TypeScript SDK, uses the same property schema. This article defines all supported properties.
For implementation instructions, see the article for your method:
- Send conversation events using the client-side or server-side API
- Install the Python SDK to send conversation and trace data
- Install the TypeScript SDK to send conversation and trace data
- Automate Conversations API implementation with an AI skill
Event types
Each conversation event represents a single message. The eventType (client-side) or type (server-side) field determines how Pendo categorizes it:
| Event type | Description |
|---|---|
prompt |
A message submitted by the visitor to the agent. |
agent_response |
A response returned by the agent to the visitor. |
user_reaction |
Feedback submitted by the visitor on an agent response, for example, positive or negative. |
agent_trace |
An internal event emitted by the Python and TypeScript SDKs to record trace spans for a conversation. These events power conversation traces in Agent Analytics and don't appear as visible messages. |
Required properties
These properties are required for every conversation event.
| Property | Type | Description |
|---|---|---|
agentId |
string | The unique identifier for the AI agent, created when you added the agent in Pendo. |
conversationId |
string | A unique identifier for the entire conversation session. All messages in the same conversation must share this ID. |
messageId |
string | A unique identifier for this specific message. Must be unique within the conversation. |
content |
string | The content of the message, for example, the visitor's prompt text, the agent's response text, or a feedback value (positive, negative, or unreact) for user_reaction events. |
ID and sequencing rules
Follow these rules to ensure Pendo can correctly group and analyze messages:
-
conversationIdandmessageIdmust be stable and unique in your system, for example, generated by your chat backend. - All messages in the same conversation must use the same
conversationId. Incorrect or reused IDs can cause messages to appear out of order or in the wrong conversation. - The prompt and the agent's response are separate messages and must use different
messageIdvalues. - For
user_reactionevents, reuse themessageIdof the response the feedback is associated with.
Optional properties
| Property | Type | Description | Default |
|---|---|---|---|
suggestedPrompt |
boolean | Whether the prompt was suggested by the system rather than typed manually by the visitor. | false |
toolsUsed |
array of strings | Tools or functions called to generate the agent's response, for example, ['search', 'calculator']. |
[] |
agentModelsUsed |
array of strings | AI models used to generate the response, supporting multi-model scenarios, for example, ['gpt-4', 'claude-3']. Replaces modelUsed. |
[] |
agentFilesUploaded |
array of objects | Files uploaded during this message exchange. Each object contains type (file type) and name (file name), for example, [{ "type": "csv", "name": "data.csv" }]. File contents aren't captured. Replaces fileUploaded. |
[] |
agentUserReactionComments |
array of strings | Written comments accompanying a visitor reaction (thumbs-up or thumbs-down), allowing visitors to provide text feedback alongside their reaction. Used with user_reaction events. |
[] |
agentSubagentsUsed |
array of strings | Subagents called during the conversation, for example, ['research_agent', 'code_agent']. |
[] |
agentInputTokenCount |
integer | Number of LLM input tokens used to generate the agent's response. Available on trace events only. | 0 |
agentOutputTokenCount |
integer | Number of LLM output tokens used to generate the agent's response. Available on trace events only. | 0 |
Note: Optional properties are surfaced in Agent Analytics only when included in your implementation. If they aren't sent, the corresponding charts and details won't appear.
Deprecated properties
These properties are still accepted for backward compatibility but have been replaced by newer alternatives. Update your implementation to use the replacement properties when possible.
| Property | Type | Replaced by | Description |
|---|---|---|---|
modelUsed |
string | agentModelsUsed |
The AI model that generated the response or processed the prompt, such as gpt-4. Use agentModelsUsed for multi-model support. |
fileUploaded |
boolean | agentFilesUploaded |
Whether the visitor uploaded one or more files during this message exchange. Use agentFilesUploaded to capture file type and name. |