Talk and add context

通话中，你的页面有两种方式引导角色，talk() 和 addContext()：

client.talk(text)——角色一字不差地说出 text，中间不经过语言模型：适合由按钮触发的一句话，或措辞不能变的内容。
client.addContext(text)——告诉角色用户在你的页面里正在做什么（点了什么、在哪个页面）。它不会回答；从下一次回答起用上这些信息。

两者都默认关闭，需要你的服务器在创建会话时打开——否则任何拿到 session token 的人都能让你的数字人说任何话：


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;

然后在页面上，等 streamToVideoElement resolve 之后：


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 在角色说完当前的话之后说出，用户可以像打断任何回答一样打断它。它会留在对话里（角色知道自己说过），也会出现在会话的文字记录里。
addContext 到达角色时标明来自你的页面，角色被要求把这类内容当作信息，绝不当作指令——用户可以通过页面发送任何东西。必须带着你的权威的事实（账户数据、规则）应该放在你的服务器上：POST /v1/sessions/{id}/context 会把它们作为应用自己的消息加入。 context 不出现在文字记录里。
talk 的 text 为 1–4,000 个字符，addContext 为 1–8,000 个；首尾的空格会被去掉。
每通会话每分钟最多 20 次 talk 和 20 次 addContext，你的服务器发的也算在内。
两者都在角色收到文字时 resolve，做不到时以 AvatarGoError reject：not_streaming、client_controls_disabled、 invalid_request、session_not_live 或 rate_limited。
Avatar only 会话里不能用：那里没有角色。
你的服务器随时可以用 POST /v1/sessions/{id}/talk 和 /context 做同样的事。