Engagement events

Engagement events record what a user does around an answer, such as sending, editing, stopping, copying, or approving a tool. They contain interaction metadata rather than message text. Feedback comments are stored with their ratings, not as engagement events. The assistant-ui cloud runtime reports these events automatically, and the dashboard uses them to show engagement and satisfaction. For explicit message feedback and application scores, see Feedback and scores.

How events are recorded

The runtime subscribes once per thread list to its composer, message, thread, and store events at the root scope, so a visited thread that stays mounted in the background adds no second listener and a run that ends after the user switched away is still recorded. Each event is attributed by the thread id it carries. An event for a thread the list does not know is dropped rather than sent without a thread. It reports these 16 kinds.

The runtime also remembers when each run starts and ends. That timing supplies the message_sent gap and the run_stopped duration. It keeps the remembered run endings, shown errors, and shown suggestions for up to 256 threads.

Delivery, validation, and storage

cloud.events.track adds a normalized event to a local buffer and returns immediately. The client flushes as soon as 20 events are waiting, after a two second debounce, on the pagehide event, when document visibility becomes hidden, and when you call dispose(). A request carries at most 50 events and uses keepalive: true; dispose() removes the listeners, clears its timer, and flushes the buffer. Delivery never blocks the interface. A failed scheduled or 20-event flush retries after 250 milliseconds and then 1,000 milliseconds. A page-exit, hidden-page, or dispose() flush sends once and ends a pending retry.

Before buffering, the client applies these limits.

The endpoint is POST /v1/events with { events }. The server accepts 1 to 50 events, validates each value as an integer from 0 to 2,147,483,647, and accepts property keys of 1 to 64 characters. It silently drops an event that names a thread the caller does not own, while keeping the rest of the batch. A successful request answers 202 with { "accepted": n }, where n is the number stored.

The event endpoint is limited to 600 requests per 60 seconds for each user. At the limit it answers 429, { "error": "rate_limited" }, and a Retry-After header.

The cloud keeps the raw event rows and a daily rollup by project, UTC day, user, and kind. The rollup records a count, a value sum, and a value count. It also keeps four thread flags from event kinds: copied, stopped, regenerated, and edited.

What the dashboard derives

The dashboard's satisfaction value is a rule over the thread's ratings, flags, and run count, not a model judgement. A thumbs up on any message makes the positive side true, and a thumbs down on any message makes the negative side true. A rating outranks behaviour: positive behaviour counts only on a thread with no thumbs down, and negative behaviour only on a thread with no thumbs up. A thread with both ratings is mixed.

positive = threads.thumbs_up OR (NOT threads.thumbs_down AND (threads.copied OR threads.run_count >= 2))
negative = threads.thumbs_down OR (NOT threads.thumbs_up AND (threads.stopped OR threads.regenerated OR threads.edited))
satisfied    = positive AND NOT negative
mixed        = positive AND negative
dissatisfied = negative AND NOT positive
none         = NOT positive AND NOT negative

The signal filter on Threads uses these values.

What the Engagement page shows

Engagement answers what people do around responses. It opens with the Answered, Continued, Stopped, Regenerated, Copied, and Came back tiles, then shows the Feedback block. It then shows the conversation funnel, the satisfaction split, interaction mix, reactions and satisfaction over time, results by model and topic, and an hour by weekday heatmap. Features used groups attachment use, suggestion impressions and clicks, branching, tool approvals and rejections, read aloud, voice input, thread switching, errors shown, and attachment failures.

From your code

Use cloud.events.track when your UI has an interaction that the runtime does not report. The call joins the next delivery batch.

cloud.events.track({
  kind: "suggestion_clicked",
  thread_id: threadId,
  props: { source: "sidebar" },
});

cloud.events.track({
  kind: "error_shown",
  thread_id: threadId,
  value: 1,
  props: { code: "upstream_timeout" },
});

After delivery, the event appears in the thread page's Activity tab and in the Engagement page's counts.

To keep run reports while turning off engagement events, set events to false. Set telemetry itself to false to turn off both run reports and events.

import { AssistantCloud } from "assistant-cloud";

const cloud = new AssistantCloud({
  baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL!,
  anonymous: true,
  telemetry: { events: false },
});

Troubleshooting