Contexto customizado

O canal Widget aceita dados do seu site — usuário logado, página, plano, pedido — junto com cada mensagem. Esse payload não aparece como fala do visitante. Ele entra no prompt enviado à LLM, num bloco chamado Custom Contextual Information.

Esse é o nome exato da seção, em inglês, mesmo se o Agente e o visitante falarem português. A boa prática é citar esse nome na description de cada property da tool.

---

O que o Agente vê

A cada mensagem, o prompt da LLM inclui um bloco neste formato:

### Custom Contextual Information
Here is some additional contextual information known by the system that may be useful to you:

{
  "userId": "usr_9182",
  "email": "ana@empresa.com",
  "plan": "pro",
  "page": "/billing"
}

O Agente não preenche {{userId}} sozinho. Ele lê Custom Contextual Information se a description da property mandar.

Nota

Não coloque token, senha, cookie de sessão nem chave de API nesse payload. O texto inteiro entra no prompt da LLM.

---

Inserir o contexto no site

O script de embed continua o mesmo. Ajuste só a ChannelURL ou chame a API JavaScript depois do load.

Na plataforma, os snippets ficam em CRM → Canais → Visão Geral, na seção Contexto do widget.

1. Parâmetro de URL context

O valor segue em toda mensagem até ser sobrescrito via JavaScript. Use quando o dado já existe no carregamento da página.

<script>
  const context = encodeURIComponent(JSON.stringify({
    userId: "usr_9182",
    email: "ana@empresa.com",
    plan: "pro",
    page: window.location.pathname
  }));

  window.ZV2Widget = {
    ChannelURL: "https://widget.endless.zaia.app/widget/channel/SEU_CANAL_ID?context=" + context
  };
</script>
<script src="https://widget.endless.zaia.app/script/widget-loader.js" async></script>

2. window.zaia.context (recomendado no embed)

Depois que o widget-loader.js sobe, a página ganha window.zaia (alias: window.endless). Use depois do login ou quando a rota muda.

<script>
  function setWidgetContext(payload) {
    if (!window.zaia || !window.zaia.context) {
      window.setTimeout(function () { setWidgetContext(payload); }, 50);
      return;
    }
    window.zaia.context.set(payload);
  }

  setWidgetContext({
    userId: currentUser.id,
    email: currentUser.email,
    plan: currentUser.plan,
    page: window.location.pathname
  });
</script>

• window.zaia.context.set(valor) — string ou objeto. Objeto vira JSON. A próxima mensagem do visitante já leva o valor novo.
• window.zaia.context.clear() — a próxima mensagem vai sem contexto.

Se você chamar set antes do iframe terminar de carregar, o loader guarda o valor e reenvia quando o chat estiver pronto.

3. postMessage (só embed próprio do iframe)

Se você montou o iframe na mão, sem o loader:

iframe.contentWindow.postMessage(
  { type: "set-context", payload: { userId: "usr_9182", plan: "pro" } },
  "*"
);

iframe.contentWindow.postMessage({ type: "clear-context" }, "*");

O Widget só aceita essas mensagens da janela pai. Com o loader no ar, use window.zaia.context.

---

Boa prática: apontar a property para Custom Contextual Information

Dois lugares trabalham juntos:

1. Prompt do Agente — regra geral.
2. Description de cada property — regra local. É o passo que mais evita o Agente perguntar o ID de novo.

No Agent Builder (Builder → Advanced / Avançado), acrescente no Prompt:

Custom Contextual Information:
A cada mensagem o sistema inclui um bloco chamado Custom Contextual Information no prompt.
Esse JSON vem do site (Widget), não do visitante. Use-o nas tools sem perguntar de novo.
Campos esperados: userId, email, plan, page.

Se userId estiver em Custom Contextual Information, chame a tool de consulta com esse ID.
Se o bloco estiver vazio, atenda como visitante anônimo. Nunca invente userId.
Não recite o JSON na resposta. Use os dados para agir.

Publique a versão (draft → deploy) para o Widget de produção usar o Prompt novo.

---

Exemplo: Requisição HTTP

O site manda userId. A description da property aponta para Custom Contextual Information. O Agente preenche e dispara a API.

1. Vá em Builder → Ferramentas.
2. Crie uma tool Requisição HTTP.
3. Configure:

Campo	Valor
Name	Consultar cliente no CRM
Description	Busca o cliente autenticado. Preencha userId com o valor presente em Custom Contextual Information. Não peça o ID se o bloco já trouxer o campo.
Method	GET
URL	https://api.seudominio.com/customers/{{userId}}

4. Em Properties, crie userId (string, obrigatória). Na description da property:

Preencha esta property com o userId presente dentro da Custom Contextual Information. Não pergunte ao visitante se o campo já estiver no bloco.

5. Ligue a tool ao Agente e publique.

O Property Picker insere {{userId}} em URL, headers, query ou body. A LLM lê Custom Contextual Information, copia o userId para a property e a tool executa.

O mesmo padrão vale para POST/PATCH: declare {{email}} ou {{plan}} e, na description de cada property, mande preencher com o campo correspondente em Custom Contextual Information.

Veja também HTTP Request Tool.

---

Exemplo: Inserção de Linha em Tabela

Para registrar quem falou com o Widget, sem API externa:

1. Crie uma Table com colunas user_id, email, plan, page, notes.
2. Crie a tool Inserção de Linha em Tabela apontando para essa Table.
3. Na description: Registra o visitante autenticado. Preencha user_id, email, plan e page com os campos presentes em Custom Contextual Information. Use notes só com o que a pessoa pediu.
4. Ligue a tool ao Agente e publique.

Veja também Table Tools.

---

Client-Side Call

Client-Side Call dispara um evento no navegador (abrir um modal, ir para /checkout). Não substitui o contexto: Custom Contextual Information diz quem está na página; a tool diz o que fazer no browser.

Na description da property userId:

Preencha esta property com o userId presente dentro da Custom Contextual Information.

O canal Widget precisa ter Permitir ferramentas client-side habilitado. Sem isso, o evento não chega na página.

---

Validar

1. Abra o site com o Widget.
2. No DevTools → Console: window.zaia.context.set({ userId: "usr_9182", plan: "pro", page: "/billing" }).
3. Envie: “Qual é o meu plano?” e, em seguida, “Busca meus dados no CRM”.
4. O Agente deve usar o plano do contexto e chamar a Requisição HTTP com userId=usr_9182, sem perguntar o ID.
5. Em Executions, a property da tool deve aparecer preenchida.

Para limpar: window.zaia.context.clear(). A mensagem seguinte não deve mais usar usr_9182.

---

O que não fazer

• Não trate o contexto como mensagem do usuário. Ele não entra no histórico visível do chat.
• Não descreva a property só como “ID do usuário”. Sem apontar para Custom Contextual Information, o Agente costuma perguntar o valor no chat.
• Não coloque segredo no payload. Esse texto entra no prompt da LLM.
• Não dependa só de ?context= se o login acontece depois do load — chame set quando a sessão existir.
• Não invente chave que o JSON, a property e a description não compartilham. userId no payload + userId na property + “presente em Custom Contextual Information” na description.

A Developer Platform API também aceita um campo context ao executar um Agente. Essa API está em alpha, sujeita a mudanças.