Comunicação via PostMessage

A funcionalidade de comunicação via PostMessage permite que aplicações web enviem comandos JavaScript para alterar dinamicamente o tema do widget EvaGPT e enviar informações contextuais às conversas.

Configuração Inicial

Para habilitar a comunicação via PostMessage:

1. Acesse Listar Agentes no painel principal

2. Selecione o agente desejado

3. Navegue até Widget nas configurações

4. Localize "Domínios autorizados para comunicação via postMessage"

5. Adicione os domínios autorizados (um por linha)

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

---

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 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