![Visão geral dos Apps de Dashboard: cadastrar nome e URL, abrir o app incorporado à conversa e trocar o contexto atualizado com postMessage.](/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBBbGdSIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--ce2a5f67ceb850732025953763a642294e5b1663/1730736611-como-usar-apps-no-dashboard.png)

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

```js
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:

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

A resposta chega no mesmo listener com o envelope `appContext`.

## Formato resumido

```json
{
  "event": "appContext",
  "data": {
    "conversation": {
      "id": 123,
      "display_id": 57,
      "status": "open",
      "inbox_id": 9,
      "messages": []
    },
    "contact": {
      "id": 81,
      "name": "Maria",
      "email": "maria@example.com",
      "phone_number": "+5511999999999",
      "custom_attributes": {}
    },
    "currentAgent": {
      "id": 7,
      "name": "Ana",
      "email": "ana@example.com"
    }
  }
}
```

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.