The Pendo Conversations API lets you capture complete AI agent interactions, including visitor-submitted prompts, agent responses, and visitor feedback, from your frontend or backend code. This data powers Agent Analytics features like use case identification, issue detection, and conversation review.
This article covers the client-side and server-side implementation methods. For other ways to send Agent Analytics data, see Send Agent Analytics data to Pendo.
Requirements
To send conversation events using the client-side or server-side method, you need:
- Full conversations activated for your agent in Pendo. For setup steps, see Add and configure AI agents in Pendo.
- The Agent ID for the agent you want to instrument. To find it, go to Product > Agent Analytics, then select the settings icon next to the agent name.
- Access to your product's codebase and a developer environment where you can deploy changes.
- The Track Event shared secret for your application, if you're using the server-side method. For retrieval steps, see Send conversation events on the server side below.
Send conversation events on the client side
Update your app's frontend code to call window.pendo.trackAgent() wherever your AI agent handles user interactions. This 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, agenticProperties, properties)Parameters
-
eventType(string, required): One of"prompt","agent_response", or"user_reaction". -
agenticProperties(object, required): Event-specific conversation data and metadata. For a full list of supported fields, see Conversation properties. -
properties(object, optional): Standard Pendo event properties, such asdurationorexperiment. These are sent alongside the conversation properties and appear in the event payload as theeventPropertiesobject.
Example conversation flow
The examples below show how to send a visitor prompt, record the agent's response, and capture visitor feedback as part of the same conversation.
Important: 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',
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',
content: 'To reset your password, go to Settings > Account > Reset Password.',
agentModelsUsed: ['gpt-3.5-turbo'],
suggestedPrompt: false,
toolsUsed: ['knowledge_base'],
agentFilesUploaded: []
},
{
experiment: 'experiment_abc'
});Visitor reacts to 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', // 'positive', 'negative', or 'unreact'
agentUserReactionComments: ['that feedback was really useful!'],
agentModelsUsed: ['gpt-3.5-turbo'],
suggestedPrompt: false,
toolsUsed: ['knowledge_base'],
agentFilesUploaded: []
});Additional examples
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: []
});Send conversation events on the server side
Use the server-side method when the Pendo Web SDK isn't available in your environment; for example, in mobile apps, backend services, or non-web environments.
To authenticate server-side requests, you need the Track Event shared secret for your application. This is different from the subscription key found in your Pendo installation or integration keys.
A subscription admin can find 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 the Conversations API endpoint documentation for technical details on formatting your request, including regional endpoints, required headers, and code examples.
The server-side request body uses the same property schema 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.
Tip: If your application retries API calls or replays events, reuse the same messageId to avoid duplicate records in Pendo.