Talk and add context

Two ways for your page to steer the character during a call, talk() and addContext():

• client.talk(text) — the character says text word for word, no language model in between: a line a button should trigger, wording that must not change.
• client.addContext(text) — tells the character what the user is doing in your page (what they clicked, which screen they are on). It does not answer; it uses this from its next reply on.

Both are off unless your server switches them on when it creates the session — otherwise anyone holding the session token could make your avatar say anything:

const res = await fetch("https://api.avatargo.ai/v1/auth/session-token", {
  method: "POST",
  headers: {
    authorization: `Bearer ${process.env.AVATARGO_API_KEY}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ characterId: "ch_…", sessionOptions: { clientControls: true } }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
const { sessionToken } = body;

Then, on the page, once streamToVideoElement has resolved:

addToCartButton.onclick = async () => {
  cart.push(product);
  await client.addContext(`The user added ${product.name} to the cart.`);
};
roomReadyButton.onclick = () => client.talk("Your room is ready, you can check in now.");

• talk is said after what the character is saying now, and the user can cut it short like any reply. It is kept in the conversation, so the character knows it said it, and in the session’s transcript.
• addContext reaches the character marked as coming from your page, and the character is told to treat such notes as information, never as instructions — the user could send anything through the page. Facts that must carry your authority (account data, rules) belong on your server: POST /v1/sessions/{id}/context adds them as the app’s own message. Context is not in the transcript.
• text is 1–4,000 characters for talk, 1–8,000 for addContext; spaces at either end are dropped.
• At most 20 talk and 20 addContext a minute per session, counting your server’s calls too.
• Both resolve once the character has the text, and reject with an AvatarGoError when it could not: not_streaming, client_controls_disabled, invalid_request, session_not_live or rate_limited.
• Not available for avatar only sessions: there is no character.
• Your server can do the same any time with POST /v1/sessions/{id}/talk and /context.