Como usar apps no painel

Use este guia para criar apps incorporados no painel da IAra.

Para que servem apps no painel

Apps no painel permitem exibir sistemas externos dentro da tela de atendimento. Isso ajuda agentes a consultar pedidos, pagamentos, histórico, dados de CRM ou informações internas sem sair da conversa.

Na tela: A área de integrações mostra os apps que podem ser conectados ao painel.

Criar app no painel

1. Acesse Configurações > Integrações > Apps no painel.
2. Clique em Configurar.
3. Informe nome do app.
4. Informe a URL HTTPS onde o app está hospedado.
5. Salve.
6. Abra uma conversa e confirme se a nova aba aparece.

Receber contexto da conversa

A IAra envia contexto para o app usando window.postMessage. No app incorporado, implemente um listener:

function isJSONValid(value) {
  try {
    JSON.parse(value);
    return true;
  } catch {
    return false;
  }
}

window.addEventListener('message', function (event) {
  if (!isJSONValid(event.data)) {
    return;
  }

  const eventData = JSON.parse(event.data);

  if (eventData.event === 'appContext') {
    const { conversation, contact, currentAgent } = eventData.data;
    console.log({ conversation, contact, currentAgent });
  }
});

Solicitar dados sob demanda

Se o app precisar atualizar o contexto, envie uma mensagem para a janela pai:

window.parent.postMessage('chatwoot-dashboard-app:fetch-info', '*');

O nome da chave pode manter chatwoot-dashboard-app por compatibilidade técnica com a base herdada.

Cuidados

• Use HTTPS.
• Não exponha tokens sensíveis no frontend.
• Valide origem (event.origin) quando possível.
• Trate ausência de contato, conversa ou agente.
• Crie tela de erro amigável se o app externo ficar indisponível.