Como usar Apps no Dashboard

Os Apps de Dashboard incorporam uma página externa ao painel de conversas. Eles são úteis para mostrar pedidos, pagamentos ou dados de um CRM sem tirar o agente do atendimento.

Criar um App de Dashboard

1. Acesse Configurações → Integrações → Painel de Aplicativos e clique em Configurar. Essa é a integração usada para criar os Apps de Dashboard descritos neste guia.
2. Informe o nome do aplicativo e a URL HTTPS em que ele está hospedado.
3. Salve. Uma aba com o nome escolhido aparecerá na área de contexto da conversa.

Receber o contexto no aplicativo

Quando o iframe é carregado, a plataforma envia uma string JSON por postMessage. O objeto tem o evento appContext; dentro de data ficam conversation, contact e currentAgent.

window.addEventListener('message', event => {
  // Aceite apenas mensagens da janela que incorporou o app.
  if (event.source !== window.parent || typeof event.data !== 'string') return;

  let payload;
  try {
    payload = JSON.parse(event.data);
  } catch {
    return;
  }

  if (payload.event !== 'appContext') return;

  const { conversation, contact, currentAgent } = payload.data;
  // Atualize sua interface com os campos necessários.
});

Se o aplicativo conhece a origem exata do painel, valide também event.origin contra essa origem antes de ler os dados.

Solicitar o contexto atualizado

Para pedir novamente os dados da conversa aberta, envie a chave abaixo à janela principal:

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

A resposta chega no mesmo listener com o envelope appContext.

Formato resumido

{
  "event": "appContext",
  "data": {
    "conversation": {
      "id": 123,
      "display_id": 57,
      "status": "open",
      "inbox_id": 9,
      "messages": []
    },
    "contact": {
      "id": 81,
      "name": "Maria",
      "email": "[email protected]",
      "phone_number": "+5511999999999",
      "custom_attributes": {}
    },
    "currentAgent": {
      "id": 7,
      "name": "Ana",
      "email": "[email protected]"
    }
  }
}

O objeto conversation também pode conter mensagens, remetente, responsável, etiquetas e atributos do canal. Leia somente os campos necessários e tolere campos adicionais, porque o contexto pode evoluir entre versões.

Segurança

• Hospede o app em HTTPS e restrinja quem pode acessá-lo.
• Não confie em postMessage sem validar event.source, event.origin quando possível, o tipo e o formato do payload.
• Não grave tokens ou dados sensíveis no código entregue ao navegador.
• Aplique no seu backend as mesmas permissões que o usuário teria no sistema de origem.