Validate conversation events

Last updated: July 29, 2026 20:39

The event validator checks an AI agent conversation event payload against Pendo's requirements before you send it, so you can catch formatting problems that would otherwise cause events to be dropped or rejected. It's a developer tool on any AI agent's settings page in Agent Analytics.

You can validate payloads for either the browser SDK or the server API, and you can paste a full event, its properties only, or a JZB-encoded payload. The validator only previews your payload—it doesn't send the event or change any data in Pendo.

Use cases

Use the event validator to:

Confirm your payloads match Pendo's requirements before you instrument your AI agent, so events aren't dropped after you go live.
Investigate why expected conversation events aren't appearing in Agent Analytics by validating a sample payload.
Check a payload after moving from deprecated fields to their current replacements, such as agentModelUsed and agentFilesUploaded.

Availability

The event validator is available for AI agents that have conversations turned on. It appears on the agent's settings page, in the Event validator section, and can be used by anyone who can open that agent's settings.

For help turning on conversations, see Send conversation events using the client-side or server-side API.

Validate an event

Validate a conversation event payload to preview whether Pendo would accept it.

Go to Product > Agent Analytics.
From the AI agents list, select the gear icon next to the agent you want to check to open its settings page. Alternatively, open the agent's details page or a report, then select Actions > Edit settings in the top-right corner.
Go to the Event validator section.
Select the source that matches how you send events: Browser SDK or Server API.
Select an input format: Full event, Properties only, or JZB.
Paste your payload into the box. To start from an example, select a Template: prompt, agent_response, or user_reaction.
Select Validate event.
Review the result for each field, fix any issues, then validate again.

Read the validation results

The validator returns a status for each field and for the event overall:

Pass. The field meets all requirements.
Warn. The field has an issue you should address, such as a deprecated field or a value that doesn't match the selected agent or app. The event is generally still ingested.
Fail. The field has a critical error, such as a missing required field or an incorrect data type. The event is rejected and isn't ingested.
Info. Additional information about the field.

A payload with no fail results would be accepted by Pendo.

Formatting requirements

Check these common requirements before you validate:

toolsUsed must be an array of strings, such as ["View"], not a bare string like "View". A bare string causes the whole event to be dropped during decoding.
messageId must be a string, not a number. Send "msg_001", not 123.
browser_time must be an integer in milliseconds since epoch, with no decimals and not in seconds.
Events must be within the last seven days. Events dated more than 30 minutes in the future are flagged.
suggestedPrompt must be a boolean (true or false), not a string. The same applies to the deprecated fileUploaded field, though you should use agentFilesUploaded instead.
For user_reaction events, content must be positive, negative, or unreact. Put free-text feedback in agentUserReactionComments.

Field reference

The following tables list every field the validator checks, grouped by whether it's required, optional, set by Pendo, or deprecated.

Required event fields

These top-level fields are required on every event.

Field	Type	Notes
`type`	string	One of `prompt`, `agent_response`, or `user_reaction`.
`browser_time`	integer	Milliseconds since epoch. Must be within the last seven days and not more than 30 minutes in the future.
`visitor_id`	string	A non-empty visitor identifier.

Required message fields

The props object is required and includes these required fields.

Field	Type	Notes
`props.agentId`	string	Must match an AI agent configured in Pendo.
`props.conversationId`	string	Required and non-empty for conversational agents.
`props.messageId`	string	A non-empty string. Must not be a number.
`props.content`	string	The message content. For `user_reaction` events, must be `positive`, `negative`, or `unreact`.

Optional fields

These fields are optional.

Field	Type	Notes
`account_id`	string	An account identifier.
`url`	string	The page URL. Defaults to `http:///` if missing.
`props.toolsUsed`	array of strings	Must be an array of strings. A bare string drops the event.
`props.suggestedPrompt`	boolean	Whether the prompt was auto-suggested.
`props.agentModelUsed`	array of strings	Preferred over `modelUsed`. Supports multiple models.
`props.agentFilesUploaded`	array of objects	Preferred over `fileUploaded`. Each item needs a name and a file type, such as `csv`.
`props.agentSubagentsUsed`	array of strings	Names of subagents invoked.
`props.agentUserReaction` `Comments`	array	Written comments that accompany a `user_reaction`.
`props.agentInputTokenCount`	integer	LLM input tokens used to generate the response. Available on trace events only.
`props.agentOutputTokenCount`	integer	LLM output tokens used to generate the response. Available on trace events only.

Fields set by Pendo

Pendo populates these fields automatically. Don't set them manually.

Field	Type	Notes
`sessionId`	string	Analytics session ID.
`tabId`	string	Browser tab identifier.
`recordingId`	string	Session recording ID.
`app_id`	string or number	Application ID. Validated against the current app if present.
`subscription_id`	string or number	Subscription ID.

Deprecated and legacy fields

These fields still work but are being phased out. Use the current field instead.

Field	Type	Notes
`props.modelUsed`	string	Deprecated. Use `agentModelUsed`.
`props.fileUploaded`	boolean	Deprecated. Use `agentFilesUploaded`.
`props.prompt`	string	Legacy. Use `content`. If you set both `prompt` and `content`, `prompt` takes precedence.

Related resources