Chatwoot

​

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

FRONTEND_URL=https://chatwoot.your-domain.com

• 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).

​

Configurar a integração

WHATSAPP_CLOUD_BASE_URL=https://pilotstatus.com.br/api/layer/meta

​

Modo de canal: espelho via API vs nativo Cloud

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

​

Enviar um template pelo Chatwoot

• O comando /template. Digite /template <nome> [valor1, valor2, ...] no compositor: os valores separados por vírgula preenchem o {{1}}, {{2}}, … do template, em ordem. Um argumento escrito button_<N>=valor preenche uma variável de botão — um placeholder numerado de URL ou, num número oficial, o código de um botão de copiar código —, em que N é a posição do botão na lista de botões do template, começando em 1, e todos os botões contam (veja Templates):
  /template link_pagamento_pix Maria, R$ 10, 21/09/2026, button_1=SdjLn
  
  Um argumento button_<N>= não consome um número posicional: Ana, button_2=SdjLn, 50 preenche {"1": "Ana", "2": "50", "button_2": "SdjLn"}. Os valores não podem conter vírgula — R$ 10,00 viraria dois valores (R$ 10 e 00). Qualquer outro texto chave=valor continua sendo um valor posicional comum.
• Os parâmetros de template nativos do Chatwoot. Templates enviados com o template_params do próprio Chatwoot são atendidos, inclusive no formato estruturado que o seletor de templates de WhatsApp dele monta (processed_params com body e buttons): os parâmetros do body preenchem as variáveis do template, e os parâmetros de botão (URL e copiar código) viram button_<N> pela posição.

​

Submissões de Flow chegam como nota privada

• Espelho via API (Modelo A) — o Pilot Status está no caminho, então corrige as duas metades: a bolha pública é substituída por uma linha fixa curta (📋 Formulário respondido) no lugar do rótulo da Meta, e as respostas são publicadas como nota privada na mesma conversa — uma linha campo: valor por resposta. Os atendentes leem no mesmo tópico; o cliente nunca vê a nota.
• Nativo Cloud (Modelo B) — o Chatwoot lê o webhook da Meta por conta própria e não tem parser para nfm_reply, então a mensagem cai com content: null. É uma limitação do Chatwoot; nenhuma configuração daqui muda o que o parser dele entende. O Pilot Status não espelha essas conversas (espelhar duplicaria toda mensagem), então nesse modo não há nota privada e não há nada que a gente consiga acrescentar ao tópico.

​

O que o atendente vê no Chatwoot

• Resposta que a Pilot Status recusa fica marcada como falha, com o motivo. Quando uma resposta escrita no Chatwoot não pode ser enviada — o WhatsApp está recusando envios do número, a cobrança está suspensa, a janela de 24h está fechada num número oficial, o /template não existe, o anexo não tem URL pública —, a mensagem fica marcada como falha no Chatwoot, com o motivo na bolha, e uma nota privada na conversa explica o porquê. Ela não é retentada. A mesma falha aparece nos Logs do número, com o seu código de erro.
• Nativo Cloud (Modelo B): respostas de atendentes aparecem nos Logs. O próprio Chatwoot envia à Meta a resposta da inbox nativa, pela camada da Pilot Status. A Pilot Status a registra como mensagem de saída com origin: "CHATWOOT" nos Logs, em GET /v1/messages e em GET /v1/messages/history, e atualiza o status conforme a Meta informa entrega e leitura. Ela não tem detalhe de envio e não conta no consumo de mensagens do seu plano. Detalhes: Camada Meta → Envios ficam registrados nos Logs.
• Nativo Cloud (Modelo B): mensagens enviadas pela API da Pilot Status caem na conversa aberta do contato. O Chatwoot abre uma conversa nova para o contato cada vez que a anterior é resolvida; a mensagem da API vai atrás dela. Se não houver conversa aberta, a Pilot Status abre uma, e a resposta do cliente entra nela.
• Nativo Cloud (Modelo B): “Esta mensagem não é suportada. Você pode visualizar esta mensagem no aplicativo do WhatsApp.” Em números em coexistência, o WhatsApp às vezes entrega um aviso provisório (erro 131060, “This message is unavailable”) antes da mensagem real, com o mesmo id — mais comum na primeira mensagem de um contato novo ou depois de um longo silêncio. O Chatwoot fica com o primeiro que recebe, então a Pilot Status segura o aviso por alguns segundos e o descarta quando a mensagem real chega. Quando o WhatsApp nunca entrega o conteúdo para a API, o aviso é entregue como está: a mensagem existe só no aplicativo do WhatsApp, e a bolha é o sinal para conferir lá.
• Espelho API (Modelo A): mídia que ainda não está disponível. O espelho espera até 20 segundos o arquivo recebido ser guardado e então posta a bolha com o anexo. Se ele ainda não estiver disponível, a bolha diz [mídia] seguido de um link, e o link abre o arquivo assim que ele é guardado. Um arquivo que chega sem nome recebe o nome do tipo e o id da mensagem — por exemplo imagem-3EB03F18.jpg.

​

Enviar histórico para o Chatwoot

• 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).

​

Pausar ou desconectar

​

Chamadas de voz

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

• Painel de Chat ao Vivo
• Retenção de Dados e Modos de PII — o relay do Chatwoot continua funcionando mesmo no modo RELAY_ONLY.