Skip to main content
O Pilot Status possui uma integração nativa com o Chatwoot: conecte qualquer número de WhatsApp a uma conta Chatwoot e as conversas sincronizam bidirecionalmente — mensagens recebidas do WhatsApp aparecem no Chatwoot, e as respostas dos agentes no Chatwoot são entregues no WhatsApp.
Página do Chatwoot do Pilot Status

A página do Chatwoot — status da conexão, alternância de espelhamento, IDs de inbox/conta, reconectar e atualização de credenciais.

​
Pré-requisito: FRONTEND_URL (Chatwoot self-hosted)

Se você executa um Chatwoot self-hosted, a variável de ambiente FRONTEND_URL deve estar configurada antes de conectar:
  • Use a URL pública exata (mesmo esquema/host do navegador), sem barra no final, acessível pela internet — nunca localhost nem um IP interno.
  • Reinicie ambos os containers web e sidekiq depois (o Rails deriva default_url_options[:host] a partir dela na inicialização).
Sem FRONTEND_URL, o Chatwoot não consegue construir URLs absolutas de anexos nem webhooks de saída válidos. Sintomas no Pilot Status: mensagens marcadas como “Falha ao enviar”, mídia nunca entregue, e ArgumentError: Missing host to link to! nos logs do Chatwoot/sidekiq.
Para validar: envie uma mensagem com um anexo em uma conversa de teste — nenhum Missing host to link to! nos logs, a mensagem aparece como enviada no Pilot Status, e a mídia chega no WhatsApp.

​
Configurar a integração

A integração é configurada por número na página Chatwoot do painel do Pilot Status.
1

Reúna três credenciais do Chatwoot

  • Instance URL — a URL base do seu Chatwoot (ex.: https://chatwoot.your-domain.com ou https://app.chatwoot.com).
  • Account ID — o número na URL do seu Chatwoot após /app/accounts/.
  • User Access Token — nas configurações de perfil do seu Chatwoot.
2

Conecte no Pilot Status

Abra a página Chatwoot no painel, selecione o número de WhatsApp e cole os três valores. O Pilot Status cria automaticamente a inbox e o webhook na sua conta Chatwoot — você nunca cola uma URL de webhook manualmente. Números não oficiais (web/QR) recebem uma inbox de API (espelho de mensagens); números oficiais Meta Cloud recebem uma inbox nativa whatsapp_cloud — veja o pré-requisito abaixo.
3

Converse

Mensagens recebidas do WhatsApp (incluindo mídia) abrem conversas na nova inbox; as respostas dos agentes voltam para o WhatsApp. O histórico de mensagens e o status de entrega permanecem sincronizados.
Números oficiais (API Meta Cloud) exigem WHATSAPP_CLOUD_BASE_URL. Para um número oficial, o Pilot Status cria uma inbox nativa whatsapp_cloud (pré-preenchida com o phone number ID, o WABA ID e sua chave ps_) para que o Chatwoot fale com a Meta através da camada do Pilot Status. O WHATSAPP_CLOUD_BASE_URL global do seu Chatwoot self-hosted precisa apontar para a camada Meta do Pilot Status antes de conectar:
Deixado no padrão (graph.facebook.com), o Chatwoot valida sua chave ps_ direto na Meta e a conexão falha com “invalid credentials” / um 422 (“Chatwoot rejected the WhatsApp Cloud channel”). Essa variável é global no Chatwoot: se o mesmo servidor também roda inboxes Meta Cloud diretas (cada uma com seu próprio token da Meta), apontá-la para o Pilot Status quebra essas — use uma instância Chatwoot dedicada para os números do Pilot Status. Concretamente, uma inbox reapontada cuja chave de API do canal seja um token Meta cru (e não uma chave ps_) falha silenciosamente no envio: a camada rejeita com 401 e o Chatwoot deixa a resposta presa com o ícone de relógio e sem entrega. Toda inbox whatsapp_cloud roteada pela camada precisa usar a chave ps_ do número como chave de API do canal. O Chatwoot Cloud (app.chatwoot.com) não consegue definir essa variável e não é suportado para números oficiais. Setup completo: Chamadas de Voz no Chatwoot → Passo 1.

​
Modo de canal: espelho via API vs nativo Cloud

Todo número conecta em um de dois modos. Escolha no seletor Modo de canal na página do Chatwoot (padrão Automático):
  • Espelho via API (Modelo A) — o Pilot Status espelha mensagens e mídia para uma inbox de API do Chatwoot. Só chat (sem voz nativa). Não depende de WHATSAPP_CLOUD_BASE_URL, então funciona em Chatwoot compartilhado.
  • Nativo WhatsApp Cloud (Modelo B) — o Chatwoot fala com a Meta direto pela camada do Pilot Status, via inbox nativa whatsapp_cloud. Habilita voz/chamada nativa e mensagem nativa (sem espelho). Exige Chatwoot dedicado com WHATSAPP_CLOUD_BASE_URL apontando para a camada (veja o aviso acima).
  • Automático (padrão) — números oficiais → nativo; não oficiais → espelho.
Os dois modos entregam texto e mídia (imagem, áudio, vídeo, documento). A escolha depende de três perguntas: o número é oficial ou não oficial, o Chatwoot é compartilhado ou dedicado, e você precisa de voz nativa.
Trocar de modo = reconexão = inbox nova. Mudar o modo de um número já conectado cria uma inbox nova no Chatwoot; o histórico é re-espelhado e os mapeamentos de conversa antigos são resetados (conversas abertas não migram). Quando possível, escolha o modo antes de conectar.

​
Enviar histórico para o Chatwoot

Números oficiais Meta de coexistência (um WhatsApp Business App migrado para a plataforma via Embedded Signup) importam ~30 dias de histórico de conversa no connect. Esse histórico aparece no painel /chat, mas não é espelhado automaticamente para o Chatwoot. Na página do Chatwoot, o botão Sincronizar histórico p/ Chatwoot reenvia esse histórico já armazenado para a inbox conectada.
  • Ambos os modos de canal (números de coexistência). Funciona com o Chatwoot conectado como espelho via API (Modelo A) ou como inbox nativa whatsapp_cloud (Modelo B). No nativo, o replay é só de entrada — o histórico recebido do cliente é reenviado; as respostas do próprio negócio não são reinjetadas (elas nunca apareceram na inbox nativa mesmo) — e é melhor rodar em janela de manutenção, pois pode notificar os atendentes ao (re)criar as conversas.
  • Ordem preservada, data no texto. As mensagens entram em ordem cronológica (mais antiga primeiro). Como o Chatwoot carimba cada mensagem com a hora do import (não aceita data retroativa), a data/hora original é adicionada no início do texto de cada mensagem — [dd/mm/aaaa hh:mm], no fuso do tenant.
  • Idempotente. Re-clicar é seguro — só reenvia mensagens que ainda não chegaram.
  • Ao final (modo espelho via API), as conversas tocadas são marcadas como lidas e resolvidas para não inundar os atendentes de notificações. O modo nativo não consegue marcar como lida automaticamente — rode em janela de manutenção.
  • Mídia antiga cuja referência na Meta já expirou pode entrar como [mídia] (os bytes da mídia são capturados para o armazenamento no momento do import, então a mídia recente sobrevive).
Via API pública / MCP: POST /v1/chatwoot/history-sync (chave com escopo de número), ou as ferramentas MCP chatwoot_history_replay (iniciar), chatwoot_history_replay_get (progresso) e chatwoot_history_replay_cancel.

​
Pausar ou desconectar

Na mesma página do Chatwoot você pode pausar a sincronização por número (um botão de alternância — nada é excluído; ative-o novamente para retomar) ou desconectar a integração por completo.

​
Chamadas de voz

As chamadas de voz e a inbox do Chatwoot são superfícies separadas — os eventos de chamada do WhatsApp não são publicados nas conversas do Chatwoot. Há duas formas de trabalhar com chamadas:
  1. Atender chamadas no painel do Pilot Status (pronto para uso, sem configuração): a página /chat do painel tem um softphone integrado que atende e faz chamadas de voz do WhatsApp para ambos os tipos de conexão — números da API Meta oficial (Meta Cloud API) via WebRTC e números não oficiais (Pilot Status web) por meio de uma sessão de áudio no servidor. Veja Visão geral de Chamadas.
  2. Usar o canal de voz nativo do próprio Chatwoot (avançado, self-hosted): o Chatwoot v4.15+ traz um canal de voz nativo; você pode roteá-lo através do Pilot Status apenas para números da API Meta Cloud — em um Chatwoot self-hosted, aponte a URL base do WhatsApp Cloud para a camada Meta do Pilot Status (/api/layer/meta), crie uma inbox manual do WhatsApp Cloud para o número e adicione um webhook do Pilot Status com escopo naquele número, com o evento calls, apontando para o webhook da inbox do Chatwoot. O Chatwoot Cloud (app.chatwoot.com) e os números não oficiais não são suportados nesse caminho.

​
Relacionados