Comunicação via PostMessage

Configuração Inicial

Para habilitar a comunicação via PostMessage:

Acesse Listar Agentes no painel principal
Selecione o agente desejado
Navegue até Widget nas configurações
Localize "Domínios autorizados para comunicação via postMessage"
Adicione os domínios autorizados (um por linha)

Importante

Por segurança, apenas domínios listados poderão comunicar com o widget.

Imagem 1: configuração de domínios autorizados

Funcionalidades

1. Controle de Tema

Alterne entre temas dark e light. O tema é persistido no sessionStorage.

iframe.contentWindow.postMessage({type: "dark"}, origin);
iframe.contentWindow.postMessage({type: "light"}, origin);

2. Metadados (META)

Envie metadados que serão disponibilizados para habilidades e integrações (chamadas de API, autenticação, etc).

iframe.contentWindow.postMessage({
  type: "meta",
  userId: "12345",
  token: "abc123xyz",
  apiKey: "key_secret_789",
  plano: "Premium"
}, origin);

Características dos Metadados

Invisíveis para a IA: O LLM não tem acesso aos metadados
Uso em Habilidades: Disponíveis para integrações, APIs e validações
Persistência: Salvos no sessionStorage e mantidos entre conversas
Segurança: Ideal para tokens, IDs e credenciais de integração

Comportamento

Metadados permanecem entre conversas automaticamente
Ao iniciar nova conversa, dados do sessionStorage são reutilizados
Para remover metadados, use o comando logout
Enviar novos metadados substitui os anteriores completamente

Casos de uso:

Tokens de autenticação para APIs
IDs de usuário para integrações
Chaves de acesso para serviços externos
Dados de sessão para validações

3. Contexto para o LLM

Envie informações que serão visíveis para a IA e incluídas no contexto da conversa.

Regra Importante sobre type

Apenas estes valores de type são comandos especiais:

type: "dark" — Comando de tema
type: "light" — Comando de tema
type: "meta" — Comando de metadados
type: "logout" — Comando de limpeza

Qualquer outro valor (ou ausência de type) entra no contexto da IA.

// ✅ Contexto - IA VÊ (sem type)
iframe.contentWindow.postMessage("Usuário na página de checkout", origin);

// ✅ Contexto - IA VÊ (sem type)
iframe.contentWindow.postMessage({
  pagina: "checkout",
  itens: 3
}, origin);

// ❌ METADADOS - IA NÃO VÊ (type: "meta")
iframe.contentWindow.postMessage({
  type: "meta",
  userId: "12345"
}, origin);

// ✅ Contexto - IA VÊ (type diferente dos comandos especiais)
iframe.contentWindow.postMessage({
  type: "evento",
  acao: "produto_visualizado"
}, origin);

// ✅ Contexto - IA VÊ (type qualquer que não seja dark/light/meta/logout)
iframe.contentWindow.postMessage({
  type: "meuEvento",
  dados: "informação qualquer"
}, origin);

Quando usar Contexto vs Metadados

Contexto	Metadados (`type: "meta"`)
✅ IA vê a informação	❌ IA não vê
Informações para guiar a conversa	Dados para integrações/APIs
Comportamento do usuário	Tokens, IDs, credenciais
Estado da aplicação	Chaves de acesso
Qualquer `type` exceto os 4 especiais	Apenas `type: "meta"`

Exemplo prático:

// CONTEXTO - IA usa para personalizar resposta
iframe.contentWindow.postMessage(
  "Cliente VIP visualizando produtos premium",
  origin
);

// METADADOS - Usados pela habilidade de API (IA não vê)
iframe.contentWindow.postMessage({
  type: "meta",
  userId: "12345",
  apiToken: "secret_token",
  tipoCliente: "VIP"
}, origin);

// CONTEXTO - IA vê (type não é um comando especial)
iframe.contentWindow.postMessage({
  type: "navegacao",
  secao: "produtos-premium"
}, origin);

4. Logout (Limpeza de Metadados)

Limpa metadados do sessionStorage e inicia uma nova conversa.

iframe.contentWindow.postMessage({type: "logout"}, origin);

Quando usar Logout

Trocar de usuário/conta
Remover credenciais e tokens antigos
Garantir que nova conversa não reutilize metadados

Importante

Nova conversa não remove metadados automaticamente. Use logout para limpá-los.

Exemplo Completo

const iframe = document.getElementById('intelliframe');
const origin = document.getElementById('eva-widget').getAttribute('data-origin');

// 1. Aplicar tema
iframe.contentWindow.postMessage({type: "light"}, origin);

// 2. Enviar METADADOS (invisíveis para IA, usados em habilidades)
iframe.contentWindow.postMessage({
  type: "meta",
  userId: "12345",
  apiToken: "Bearer abc123",
  emailUsuario: "[email protected]"
}, origin);

// 3. Enviar CONTEXTO (visível para IA)
iframe.contentWindow.postMessage(
  "Usuário João está navegando na seção de eletrônicos",
  origin
);

// 4. Contexto com type personalizado (IA também vê)
iframe.contentWindow.postMessage({
  type: "navegacao",
  secao: "eletronicos",
  timestamp: Date.now()
}, origin);

// 5. Ao fazer logout - limpar metadados
function aoFazerLogout() {
  iframe.contentWindow.postMessage({type: "logout"}, origin);
}

Resumo de Comandos

Comando	Sintaxe	IA Vê?	Uso
Tema Escuro	`{type: "dark"}`	❌	Interface
Tema Claro	`{type: "light"}`	❌	Interface
Metadados	`{type: "meta", ...}`	❌	Habilidades/APIs
Logout	`{type: "logout"}`	❌	Limpar metadados
Contexto	Sem `type` ou `type` diferente dos acima	✅	Conversa com IA

Fluxo de Dados

COMANDOS ESPECIAIS (type: dark/light/meta/logout)
└─> Ações do sistema
    └─> IA não vê

CONTEXTO (sem type OU type não especial)
└─> Contexto da conversa
    └─> LLM processa a informação
    └─> Influencia respostas da IA

METADADOS (type: "meta")
└─> sessionStorage
    └─> Habilidades/Integrações
    └─> Persistem entre conversas
    └─> Removidos apenas com logout

Boas Práticas

Faça:

Use type: "meta" exclusivamente para tokens, IDs e dados de integração
Use mensagens sem type ou com type personalizado para contexto da IA
Envie logout ao trocar de usuário para limpar metadados
Aguarde o carregamento do iframe antes de enviar comandos

Evite:

Usar type: "meta" para dados que a IA deve ver
Enviar credenciais em contexto (use sempre type: "meta")
Assumir que nova conversa limpa metadados
Usar type: "dark", type: "light", type: "meta" ou type: "logout" para outros fins

Exemplo: E-commerce

// METADADOS - Para chamadas de API (IA não vê)
iframe.contentWindow.postMessage({
  type: "meta",
  customerId: "cust_12345",
  apiKey: "sk_live_abc123",
  storeId: "store_789"
}, origin);

// CONTEXTO - Para personalizar conversa (IA vê)
iframe.contentWindow.postMessage({
  carrinho: {
    itens: 3,
    valor: 599.90
  },
  ultimaCompra: "15 dias atrás",
  categoriaInteresse: "eletrônicos"
}, origin);

// CONTEXTO com type personalizado - IA também vê
iframe.contentWindow.postMessage({
  type: "evento_compra",
  status: "carrinho_ativo",
  produtos: ["smartphone", "fone", "capa"]
}, origin);

Neste exemplo:

A IA pode dizer "Vejo que você tem 3 itens no carrinho"
A IA não tem acesso ao apiKey (usado pela habilidade para API)
A IA vê o type: "evento_compra" pois não é um comando especial

Configuração Inicial​

Funcionalidades​

1. Controle de Tema​

2. Metadados (META)​

3. Contexto para o LLM​

4. Logout (Limpeza de Metadados)​

Exemplo Completo​

Resumo de Comandos​

Fluxo de Dados​

Boas Práticas​

Exemplo: E-commerce​