View as Markdown Open in ChatGPT Open in Claude

App events & page awareness

Tell the avatar something happened in your app, and let it read the page it is sitting on.

A call does not have to be driven only by speech. notify() hands the avatar something that happened in your UI so it can take a turn about it unprompted, and readPage() lets it see the page it is embedded in.

notify()

Give the event a stable slug and the avatar decides what to say about it, in character.

tsx

const { notify } = useAvatar();

notify?.({
  name: "cart.abandoned",
  data: { items: 3, total: "$82.00" },
  policy: "idle_only",
});

Prop	Type	Default	Description
`name`Required	`string`	No default	A stable slug matching ^[a-z0-9][a-z0-9_.]{0,63}$ — never prose. This is what the brain is told happened, so free text here would put your page content straight into a turn instruction.
`data`Optional	`Record<string, unknown> \| string`	No default	Structured detail, serialized and fenced as untrusted reference data. Capped at 512 characters.
`policy`Optional	`AppEventPolicy`	`"idle_only"`	When the event is allowed to take a turn. See the table below.
`say`Optional	`string`	No default	Speak this verbatim and skip the brain. An escape hatch for scripted lines; the brain-mediated form is what keeps the avatar in persona. Capped at 1000 characters.
`cooldownMs`Optional	`number`	`5000`	Per-name gap before this event may fire again.

Policies

Policy	Behaviour
`idle_only`	The default. Take a turn only if the avatar is not already busy. An avatar that talks over the user because they scrolled is worse than one that stays quiet.
`queue`	Wait for the current turn to finish, then take one.
`interrupt`	Cut in immediately. Reserve it for things the user genuinely needs to hear now.
`context_only`	Do not speak. Just remember it for later turns.

Limits

The SDK gates events before they reach the socket, so a chatty UI cannot flood the session.

Limit	Value
Per-name cooldown	`5000ms (override with cooldownMs)`
Rate limit	`5 events per 10s window`
data length	`512 characters`
say length	`1000 characters`

A dropped event (cooldown or rate limit) is logged, never thrown — the gate doing its job is not your bug. An invalid event (bad slug, oversized data or say) is your bug, and surfaces as an INVALID_INPUT error.

readPage()

Reads the host page into an index of named handles and sends it as page context, so the avatar can talk about what is on screen.

tsx

const { readPage } = useAvatar();

const result = readPage?.();
if (result && !result.sent) {
  console.log("not sent:", result.reason);
}

It returns null when the platform has no page surface, and otherwise a PageReadResult:

tsx

type PageReadResult = {
  index: PageIndex;
  /** Exactly the text that went up the wire. */
  context: string;
  sent: boolean;
  reason?: "wrong_mode" | "no_session" | "not_granted" | "unchanged";
};

Reading is manual today — nothing calls readPage() for you. Call it after navigation if you want the avatar to keep up with where the user is.

Capabilities

What the avatar may do to your page is resolved server-side from the avatar's own document and delivered when the session starts. read is the parent: without it the server forces the other two off, because acting on a page it cannot see is a worse feature than not acting at all.

tsx

type PageCapabilities = {
  read: boolean;
  scroll: boolean;
  navigate: boolean;
};

Extraction is local, but the uplink is gated. A reason of not_granted means the avatar has no read capability — the page was indexed in the browser and then not sent. Grant it on the avatar in the Platform, not in code.

Camera Perception

Events