Capture full conversations with the Conversations API

Last updated: April 23, 2026 01:44

The Conversations API lets you capture complete AI agent interactions in Pendo, including both visitor-submitted prompts and the agent's responses. This data helps you analyze full conversation flows, evaluate agent performance, and identify top use cases and issues over time with Agent Analytics.

Full conversation capture unlocks a deeper view of how your AI agents perform. You can review the complete back-and-forth between visitors and agents, view visitor feedback, track suggested prompt use and file uploads, and use this metadata to power Agent Analytics features like issue detection, which automatically highlights broken or low-quality conversations.

Important: If you haven't received any conversation data, you can switch back to prompts-only. For instructions on upgrading your capture type, see Switch a prompt-only agent to full conversations.

Choose an implementation method

How you send conversation data to Pendo depends on where your AI agent runs.

Client-side (web apps). Use the trackAgent() method to send conversation events directly from your frontend code. Requires the Pendo Web SDK.
Server-side (mobile apps and non-web environments). Use the server-side Conversations API to send events from your backend. Required for mobile apps (iOS and Android) and other environments where the Pendo Web SDK isn't available.
AI-assisted setup. Use the Pendo setup-agent-analytics skill with an AI coding assistant like Claude Code or Cursor to scan your codebase and add the correct instrumentation automatically. The skill detects your project framework and AI agents, then adds the appropriate client-side or server-side tracking calls for you. For a full walkthrough, see Automate Conversations API implementation with an AI skill.

All methods capture the same conversation data and use the same property schema.

Requirements

To send conversation events, you need:

Full conversations activated for your agent. For more information, see Add and configure AI agents in Pendo.
The Agent ID, provided during activation or available in the agent's settings.
Access to your product’s codebase and a developer environment where you can deploy changes.
The Track Event shared secret for the application your agent is associated with if you're using the server-side method. For more information, see Send conversation events on the server side.

Conversation properties

In this API, each conversation event is treated as a message and represents either a visitor prompt, an agent response, or a visitor reaction (feedback, such as thumbs-up or thumbs-down on the agent's response). Visitor messages that submit questions or instructions to the agent are referred to as prompts.

Both the client-side and server-side methods use the same property schema to describe each conversation event.

Required properties

These properties are required for every conversation event. Follow these rules so Pendo can correctly group and analyze each message within a conversation:

conversationId and ‎messageId must 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.
Feedback (for example, thumbs-up or thumbs-down on a response) is captured as ‎user_reaction events. For these events, set ‎eventType or ‎type to ‎user_reaction and use the ‎content property to send the feedback value, (positive, ‎negative, or ‎unreact).

Property	Type	Description
`agentId`	string	The unique identifier for the AI agent, created at the time you added the agent in Pendo.
`conversationId`	string	A unique identifier for the entire conversation session. All related messages must share this ID.
`messageId`	string	A unique identifier for the specific message being recorded. It must be unique within the conversation.
`content`	string	The content of the current message (for example, the visitor’s prompt, the agent’s response, or a feedback value like ‎`positive`).

Recommended properties

To capture more detailed analytics about which models and tools your agents use, and whether visitors upload files, include these properties whenever they're available so Pendo can surface this conversation data in Agent Analytics.

Property	Type	Description	Default
`suggestedPrompt`	boolean	Indicates whether the prompt was suggested by the system rather than typed manually by the visitor.	false
`toolsUsed`	array of strings	A list of tools or functions used to generate the agent's response (for example, `['search', 'calculator']`).	[]
`agentModelsUsed`	array of strings	A list of AI models used to generate the response, supporting multi-model scenarios (for example, `['gpt-4', 'claude-3']`). Supersedes `modelUsed`.	[]
`agentFilesUploaded`	array of objects	A list of files uploaded during this message exchange. Each object contains `type` (file type) and `name` (file name). Supersedes `fileUploaded`.	[]
`agentUserReactionComments`	array of strings	Text comments accompanying user reactions (thumbs up/down), allowing visitors to provide written feedback along with their reaction. Used with `user_reaction` events.	[]
`agentSubagentsUsed`	array of strings	A list of subagents used during the conversation, similar to `toolsUsed` (for example, `['research_agent', 'code_agent']`).	[]
`agentInputTokenCount`	integer	Amount of LLM input tokens used to generate the agent's response.	0
`agentOutputTokenCount`	integer	Amount of LLM output tokens used to generate the agent's response.	0

Deprecated properties

Property	Type	Description	Default
`modelUsed`	string	Identifier for the AI model that generated the response or processed the prompt (for example, `gpt-4`, `claude-3`). Still accepted for backward compatibility; use `agentModelsUsed` for multi-model support.	null
`fileUploaded`	boolean	Whether the visitor uploaded one or more files during this message exchange. File contents aren't captured. Still accepted for backward compatibility; use `agentFilesUploaded` for richer file data.	false

Send conversation events on the client side

Update your app's frontend code to call the window.pendo.trackAgent() method wherever your AI agent handles user interactions. This client-side method captures prompts, responses, and visitor feedback.

Make sure window.pendo is available in the same runtime context as your AI agent UI (for example, after the Pendo Web SDK has initialized).

Syntax

window.pendo.trackAgent(eventType, properties, eventProperties)

Parameters

eventType (string, required): One of "prompt", "agent_response", or "user_reaction".
properties (object, required): Event-specific data and metadata.
eventProperties (object, optional): Custom event properties.

Example conversation flow

The examples below show how to send a visitor prompt, record the agent’s response, and track a visitor's feedback, all as part of the same conversation session.

Warning: Ensure timestamps and IDs preserve message order. Incorrect sequencing can affect session analysis.

Each message in a conversation must have a unique messageId. The prompt and the agent's response are separate messages and must use different IDs. Feedback reuses the messageId of the response it's associated with.

Visitor sends a prompt:

window.pendo.trackAgent('prompt', {
  agentId: 'agent_234',
  conversationId: 'conv_789',
  messageId: 'msg_prompt_001', // Unique ID for this prompt
  content: 'How do I reset my password?',
  agentModelsUsed: ['gpt-3.5-turbo'],
  suggestedPrompt: false,
  toolsUsed: [],
  agentFilesUploaded: []
});

Agent responds:

window.pendo.trackAgent('agent_response', {
  agentId: 'agent_234',
  conversationId: 'conv_789',
  messageId: 'msg_response_001', // Different ID from the prompt
  content: 'To reset your password, go to Settings > Account > Reset Password.',
  agentModelsUsed: ['gpt-3.5-turbo'],
  suggestedPrompt: false,
  toolsUsed: ['knowledge_base'],
  agentFilesUploaded: []
});

Visitor leaves feedback (for example, a thumbs-up) on the agent's response:

window.pendo.trackAgent('user_reaction', {
  agentId: 'agent_234',
  conversationId: 'conv_789',
  messageId: 'msg_response_001', // Reuses the response ID to tie feedback to it
  content: 'positive', // Can be 'positive', 'negative', or 'unreact'
  agentModelsUsed: ['gpt-3.5-turbo'],
  suggestedPrompt: false,
  toolsUsed: ['knowledge_base'],
  agentFilesUploaded: []
});

The content value for feedback can be "positive", "negative", or "unreact".

Additional examples

These examples show how file uploads and suggested prompts appear in conversation events.

Visitor uploads a file with a prompt:

window.pendo.trackAgent('prompt', {
  agentId: 'document-analyzer123',
  conversationId: 'conv_456',
  messageId: 'msg_789',
  content: 'Analyze this spreadsheet for trends',
  agentModelsUsed: ['gpt-4'],
  suggestedPrompt: false,
  agentFilesUploaded: [{ "type": "csv", "name": "data.csv" }]
});

Visitor uses a suggested prompt:

window.pendo.trackAgent('prompt', {
  agentId: 'writing-assistant123',
  conversationId: 'conv_321',
  messageId: 'msg_654',
  content: 'Write a professional email to a client',
  agentModelsUsed: ['claude-3'],
  suggestedPrompt: true,
  agentFilesUploaded: []
});

Event properties and custom tags

You can also add custom event properties in a third optional parameter. The event properties field would look something like this:

{
    "experiment": "experiment_1",
    "language": "english"
}

Combined example with the full trackAgent call:

window.pendo.trackAgent('prompt', 
{
  agentId: 'agent_234',
  conversationId: 'conv_789',
  messageId: 'msg_prompt_001', // Unique ID for this prompt
  content: 'How do I reset my password?',
  agentModelsUsed: ['gpt-3.5-turbo'],
  suggestedPrompt: false,
  toolsUsed: [],
  agentFilesUploaded: []
}, 
{
    "experiment": "experiment_1",
    "language": "english"
});

Send conversation events on the server side

Send conversation events from your backend when the Pendo Web SDK isn't available in your environment, like on mobile and extension apps.

To set up server-side conversation events, you need the Track Event shared secret, which is different from the subscription key found in your Pendo installation or integration keys.

A subscription admin can access the shared secret by going to Settings > Subscription settings > Applications, selecting the relevant app, then selecting Show next to Track Event shared secret.

After you have your shared secret, see our Conversations API endpoint documentation for technical details on how to format your API request, including regional endpoints, required headers, and code examples.

The server-side request body uses the same conversation properties as the client-side method. For property definitions, see Conversation properties.

Processing and visibility

Conversation data is processed in hourly batches.

After your code is live in production, new messages typically appear within 15 minutes after the start of the next batch. You can view conversation data from Product > Agent Analytics by selecting the agent and opening the Conversations tab.

Server-side conversation events follow the same timestamp processing rules as Track Events. Use current timestamps whenever possible. Events with past timestamps outside the current hour won't appear until daily or weekly reprocessing. Pendo can't process events with timestamps older than seven days.

Visitors who interact only through server-side agent events appear in Agent Analytics but aren't reflected on the Visitors page or counted as active time in your application. The Count Track Events as time in app setting doesn't apply to agent events.

Note: If your application retries API calls or replays events, make sure you reuse the same messageId to avoid duplicate records in Pendo.