Agent Chats API

Send AI chat sessions and message feedback to BuildBetter

Use Agent Chats to analyze the quality of your AI product conversations. BuildBetter stores each conversation as a session, extracts qualitative Signals, and keeps explicit message feedback linked to the assistant response that received it.

Agent Chats focus on the user experience. They identify steering and correction, misunderstanding, repetition, capability gaps, missing context, incomplete outcomes, response-quality gaps, user friction, product opportunities, and explicit positive or negative feedback.

Set up an application

1. Open Agent Chats

   In BuildBetter, open Library → Agent Chats, then select Set up Agent Chats. Ask a workspace administrator if Agent Chats is not available in your workspace.

2. Create an application

   Give the application a name and a stable key. Use one application for each agent or product whose conversations you want to filter separately. This registers your existing agent. It does not build a new agent. The setup action also creates its first ingest credential.

3. Configure privacy

   Set content capture, participant type, allowed environments, retention, redaction, and conversation access before you send production data.

4. Create an ingest credential

   Copy the secret when BuildBetter shows it. The secret is shown once. Store it in a server-side secret manager and do not put it in browser code. Use Manage ingest credentials to create or revoke credentials later. These credentials are upload secrets, not billing credits.

Authentication

Send the ingest secret in X-BuildBetter-Agent-Key. This is an ingestion-only credential. It is different from your organization API key.

X-BuildBetter-Agent-Key: bb_agent_...
Content-Type: application/json

The request body must also contain the application agentKey. BuildBetter validates that the key and secret belong to the same application.

Send a conversation

Send events to:

POST https://api.buildbetter.app/v3/rest/agent-conversations/ingest

The following example sends one user message and one finalized assistant response.

curl "https://api.buildbetter.app/v3/rest/agent-conversations/ingest" \
  -H "Content-Type: application/json" \
  -H "X-BuildBetter-Agent-Key: $BUILDBETTER_AGENT_SECRET" \
  -d '{
    "agentKey": "support-agent",
    "externalSessionId": "chat_123",
    "status": "open",
    "agentVersion": "2026-08-26",
    "source": {
      "sdk": "vercel-ai",
      "version": "5.0.0"
    },
    "context": {
      "productArea": "analytics",
      "surface": "dashboard-assistant",
      "routeTemplate": "/dashboards/:dashboardId",
      "pathname": "/dashboards/db_42",
      "entryPoint": "ask-ai",
      "entityType": "dashboard",
      "entityId": "db_42",
      "environment": "production",
      "release": "web-2026.08.26",
      "properties": {
        "plan": "growth"
      }
    },
    "participants": [
      {
        "externalId": "user_42",
        "displayName": "Avery Chen",
        "username": "avery",
        "email": "[e-mail]",
        "companyExternalId": "account_17",
        "boundary": "external"
      }
    ],
    "events": [
      {
        "externalEventId": "user_1",
        "revision": 1,
        "sequence": 1,
        "occurredAt": "2026-08-26T18:00:00.000Z",
        "type": "user_message",
        "participantExternalId": "user_42",
        "content": "Why did revenue drop this month?"
      },
      {
        "externalEventId": "assistant_1",
        "revision": 1,
        "sequence": 2,
        "occurredAt": "2026-08-26T18:00:03.000Z",
        "type": "assistant_message",
        "final": true,
        "content": "Revenue fell because upgrades declined by 12%.",
        "model": {
          "provider": "openai",
          "name": "gpt-5"
        },
        "usage": {
          "inputTokens": 740,
          "outputTokens": 31,
          "latencyMs": 1840
        },
        "trace": {
          "traceId": "trace_abc",
          "spanId": "span_123"
        }
      }
    ]
  }'

BuildBetter returns the stable session ID and the event counts for the batch.

{
  "sessionId": "0198e42f-8027-7fd6-b514-8ee755e50590",
  "acceptedEventCount": 2,
  "deduplicatedEventCount": 0,
  "revisedEventCount": 0,
  "processingStatus": "pending"
}

pending means BuildBetter accepted the data and queued signal extraction. It does not mean extraction is complete.

Session and event identity

BuildBetter uses agentKey plus externalSessionId as the stable session identity. Continue to send new events with the same values while the conversation is active.

Each event needs:

• externalEventId: a stable ID from your system.
• sequence: the event’s position in the session. Sequence numbers must be unique.
• revision: start at 1. Increase it when you correct an existing event.
• occurredAt: an ISO 8601 timestamp.
• type: such as user_message, assistant_message, or feedback.

Retries with the same sanitized event content are deduplicated. If the content changes, send a revision greater than the stored revision. A revision cannot change the event sequence or type, and a finalized event cannot become partial again.

Events in one request do not have to be in array order. BuildBetter uses sequence to order them. Open sessions wait at sequence gaps. Ended or abandoned sessions process through permanent gaps.

Finalize a session

Send status: "ended" after the conversation ends. You can send only the final lifecycle update if the earlier events already exist, but every ingest request must contain at least one event. A common pattern is to include the last new event with the terminal status.

Use status: "abandoned" when the user leaves before the agent reaches an outcome.

Send message feedback

Send feedback as its own event. targetEventExternalId must point to an earlier assistant_message in the same session.

curl "https://api.buildbetter.app/v3/rest/agent-conversations/ingest" \
  -H "Content-Type: application/json" \
  -H "X-BuildBetter-Agent-Key: $BUILDBETTER_AGENT_SECRET" \
  -d '{
    "agentKey": "support-agent",
    "externalSessionId": "chat_123",
    "status": "open",
    "participants": [],
    "events": [
      {
        "externalEventId": "feedback_assistant_1",
        "revision": 1,
        "sequence": 3,
        "occurredAt": "2026-08-26T18:00:10.000Z",
        "type": "feedback",
        "feedback": {
          "targetEventExternalId": "assistant_1",
          "rating": "negative",
          "labels": ["incorrect", "missing-context"],
          "comment": "That compares this month with the wrong period."
        }
      }
    ]
  }'

Ratings are positive or negative. A feedback event can contain a rating, labels, a comment, or any combination of them. BuildBetter creates explicit-feedback Signals deterministically and does not use model credits for that conversion. The normal qualitative analysis of finalized assistant responses uses response credits.

In Signals, use the Agent Chat source filters to separate explicit_feedback from qualitative_inference and to filter positive or negative ratings.

Vercel AI SDK

See the Node SDK and Vercel wrapper preview for the planned SDK integration. The package is not published to npm.

For an HTTP integration, persist finalized messages in your server-side completion handler. Send only visible user and assistant text through the conversation endpoint above. Include only text parts, not reasoning, files, system prompts, or tool inputs and outputs.

Assign each event its sequence and timestamp when you first persist it. Keep those values stable when you filter hidden content or send only new messages. Do not recalculate sequences from the current batch index.

Check the HTTP response status. If delivery fails, retain the event data for a retry. Do not expose the ingest secret in browser code.

One request accepts at most 500 events and 2 MiB. One event accepts at most 256 KiB.

Context and filters

Set context at the session level when it applies to the whole chat. An event can also supply context to override the session defaults.

Field	Use
productArea	A stable product area, such as analytics or crm.
surface	The exact experience, such as dashboard-assistant, bob, or copilot-sidebar.
routeTemplate	A low-cardinality route, such as /dashboards/:dashboardId.
pathname	The actual path where the chat occurred.
entryPoint	The control or flow that opened the chat.
entityType and entityId	The product object in context.
environment	production, staging, or another configured environment.
release	Your application or agent release.
properties	Up to 50 additional JSON values.

These fields make Agent Chats filterable by agent, product area, surface, environment, and related object.

Participant identity

Use a stable externalId for each participant. If you send displayName, username, or email, externalId is required. You can also send a BuildBetter personId UUID when you already know the canonical Person.

Set boundary to:

• external for a customer, prospect, or other product user.
• internal for a team member.

BuildBetter can use the identity and boundary in signal attribution. Configure redaction before you send personal data that your workspace does not need.

One unique, case-insensitive email match can link an existing Person in the destination workspace. An explicit personId takes precedence. Unknown or cross-workspace Person UUIDs are rejected. This endpoint does not create or modify people.

companyExternalId stores your company’s external ID on the participant. It does not create or link a canonical Company record. Participant properties store up to 50 custom JSON values. See the identity and properties reference for limits and SDK field mappings.

ownerUserId controls access, not customer identity. Use an active BuildBetter user UUID from the destination workspace for owner-only chats. If omitted, the application’s access policy applies. Workspace access is the default. Enabling Agent Chats does not connect another workspace’s data.

Privacy and retention

Application settings apply before storage and hashing.

• Status: Active accepts uploads. Disabled stops new uploads without deleting stored conversations.
• Content capture: Turn it off to retain counts and status without message content. On the next ingest for a session, stored content, participants, jobs, and Signals for that session are permanently deleted.
• Redacted field names: Remove matching keys from message payloads, feedback, model metadata, usage, traces, context, and participant identity fields.
• Redacted text patterns: Replace exact sensitive text before storage.
• Retention: Set a value from 1 through 3650 days, or leave it blank for no application-specific limit. Reducing retention can permanently delete older conversations.
• Allowed environments: Leave the list blank to accept all environments. If you configure a list, each request must resolve to an allowed context.environment. This does not select a destination workspace.
• Conversation access: Use workspace access or restrict the application to selected BuildBetter user UUIDs. Reducing access also restricts existing chats and Signals. A later change back to workspace access does not restore historical access.

BuildBetter also masks common secret fields, bearer tokens, private keys, long binary payloads, and common provider secret formats.

Billing

BuildBetter meters agent_response_processed units. One visible finalized assistant response is one response unit. Appending a new response adds only the new unit. A successful idempotent retry does not add another unit.

Explicit positive or negative feedback creates its explicit-feedback Signal without model credits. The session can still use credits when BuildBetter runs normal qualitative analysis on finalized assistant responses.

Coding-agent sessions and Projects through MCP

The MCP Agent Session tools are for uploaded coding-agent session artifacts, such as Codex or Claude Code sessions. They are separate from the Agent Chats ingestion endpoint above.

To create a Projects V2 project and attach an uploaded coding-agent session:

1. Call create-project and keep the returned project publicId.
2. Call upload-agent-session with either normalized events or supported native JSONL.
3. Call associate-agent-session with resourceType: "project", the project publicId, and the uploaded session ID.
4. Call get-project or list-associated-agent-sessions to verify the association.

MCP upload, project creation, and association are mutating actions. They require OAuth user context and explicit user approval.

Troubleshooting

Response	Meaning
400	The payload is invalid or too large, the environment is missing or blocked, or feedback does not target an earlier assistant event.
401	The ingest secret is missing, revoked, or does not match the application key.
404	Agent Chats is not enabled for the workspace or the application does not exist.
409	An event changed without a higher revision, moved to another sequence, changed type, or reused an occupied sequence.

If a retry returns a high deduplicatedEventCount, the API is working as intended. If processingStatus is billing_blocked, add credits or adjust the relevant quota. If it is capture_disabled, enable content capture in the application settings before you send more content.