Recurso em beta: pode mudar. Esta é uma versão beta, em fase de testes.
Situação: versão beta, em fase de testes.
O que a integração faz?
- Entrada: cada mensagem recebida (e cada mensagem enviada do celular do número) vira mensagem numa conversa do Chatwoot. O contato é identificado pelo telefone; o nome vem do WhatsApp. Anexos são baixados e anexados.
- Saída: quando um atendente responde no Chatwoot, a ProxyBox envia a mensagem pelo número da instância e marca a mensagem do Chatwoot como enviada (
sent) ou com falha (failed). - Grupos: ignorados por padrão. Com
ignore_groupsfalso, as mensagens de grupo entram, com o nome de quem escreveu no começo do texto.
O Chatwoot faz o que a ProxyBox não faz: fila de atendimento, atribuição a atendentes, notas internas, respostas prontas. Veja também equipe e papéis para acesso ao painel da ProxyBox.
O que preciso antes?
- Uma instância conectada da ProxyBox e a chave.
- Um Chatwoot em endereço https público (a ProxyBox recusa endereços internos e http).
- No Chatwoot, uma conta com permissão de administrador para criar a caixa de entrada e gerar o token.
Passo 1: crio a caixa de entrada no Chatwoot
No Chatwoot, em Configurações > Caixas de entrada > Adicionar caixa de entrada, escolha API. Dê um nome ("WhatsApp da loja"). No campo da URL do webhook, deixe em branco por enquanto: você a preenche no passo 3. Anote o id da caixa (aparece na URL, .../inboxes/7/...) e o id da conta (.../accounts/1/...).
Quer rodar isto agora? O sandbox é grátis, não precisa de número e já vem com a chave da API.
Testar grátisPasso 2: pego o token de acesso
No Chatwoot, em Perfil > Token de acesso, copie o token. Use de preferência um usuário de serviço (um agente dedicado a esta integração), e não o seu.
Passo 3: gravo a integração na ProxyBox
No painel da instância, na área de integrações, ou pela API:
curl -X PUT "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot" \
-H "apikey: SUA_CHAVE" -H "Content-Type: application/json" \
-d '{
"url": "https://chat.suaempresa.com.br",
"account_id": 1,
"inbox_id": 7,
"api_token": "TOKEN_DO_CHATWOOT",
"ignore_groups": true,
"sign_messages": false,
"reopen_conversation": true,
"name_prefix": ""
}'
Antes de gravar, a ProxyBox testa a conexão com o Chatwoot; se o teste falhar, a gravação é recusada com a mensagem do problema. Para testar sem gravar, envie o mesmo corpo em POST /integrations/chatwoot/test.
| Campo | Para que serve |
|---|---|
url |
Endereço https do Chatwoot (público, sem usuário e senha na URL) |
account_id, inbox_id |
Números da conta e da caixa de entrada |
api_token |
Token de acesso; cifrado na ProxyBox e mostrado depois só como •••• e os 4 últimos |
ignore_groups |
true (padrão): grupos não entram no Chatwoot |
sign_messages |
true: o nome do atendente vai em negrito no início da mensagem enviada |
reopen_conversation |
true (padrão): reabre a conversa resolvida; false abre outra |
name_prefix |
Texto até 30 caracteres no início do nome dos contatos |
Para atualizar, o PUT é parcial: o que você omitir (inclusive o token) fica como está.
Passo 4: colo o webhook no Chatwoot
A resposta (e o painel) mostram o endereço do webhook, com o formato:
https://proxybox.com.br/api/whatsapp/integrations/chatwoot/<instância>/<token>
Copie o endereço inteiro e cole no Chatwoot, em Configurações > Caixas de entrada > (a sua caixa) > Configurações > URL do webhook; ou em Configurações > Integrações > Webhooks, marcando o evento message_created. O token do endereço é o segredo: quem o tem pode mandar mensagens para a integração. Se vazar, gire o token:
curl -X POST "https://proxybox.com.br/api/whatsapp/v1/integrations/chatwoot/rotate-token" -H "apikey: SUA_CHAVE"
O endereço antigo deixa de valer na hora. Cole o novo no Chatwoot.
Passo 5: testo
- Do celular de outra pessoa, mande uma mensagem para o número da instância. Ela deve aparecer como nova conversa no Chatwoot.
- Responda no Chatwoot. A resposta deve chegar ao celular, e a mensagem no Chatwoot deve ficar com a marca de enviada.
- Se algo falhar, o Chatwoot mostra uma nota privada na conversa com o motivo (opt-out, número desconectado, limite de ritmo, número sem WhatsApp, anexo recusado).
Como os loops são evitados?
Três camadas protegem contra o ciclo "o Chatwoot espelha a ProxyBox, que espelha o Chatwoot":
- cada mensagem criada pela integração leva uma marca que a identifica na volta;
- um eco gravado antes de espelhar (conversa e texto) descarta a mensagem que acabou de ser criada;
- marcas no envio e no id devolvido evitam que o aviso
message.sentgerado pela própria resposta volte ao Chatwoot.
Limite conhecido: se dois atendentes digitarem exatamente o mesmo texto na mesma conversa em até 2 minutos, o segundo é tratado como eco e não sai.
Quais são os limites?
- Sem fila durável. Se o Chatwoot estiver fora do ar, há até 3 tentativas imediatas; depois a mensagem daquele momento não é espelhada.
- Anexos até 25 MB. Falha de download: a mensagem segue com um aviso no texto.
- Mídia recebida. Se você também usa o S3, o anexo é baixado pelo caminho padrão da integração.
- Os limites da API valem para as respostas: 10 por minuto e 500 por dia no padrão, pausa entre mensagens.
- Chatwoot em nuvem ou próprio: o endereço precisa ser alcançável da internet; o certificado precisa ser válido.
O que está marcado como não confirmado?
Por honestidade, estes pontos da API do Chatwoot foram escritos a partir da documentação pública e não foram conferidos contra um Chatwoot real: o uso conjunto dos dois cabeçalhos de token em toda versão; a rota para criar o vínculo de contato com a caixa; o formato da resposta de criação de contato; o tipo exato da caixa de entrada API; os campos sender e attachments no corpo do webhook; e a devolução do campo de marca no webhook. O código aceita variações e, quando falta algo, pergunta ao Chatwoot ou ignora o anexo com uma nota. A assinatura HMAC do webhook do Chatwoot não é usada: o segredo é o token do endereço.
Se você notar diferença no seu Chatwoot, abra um ticket com a versão dele: ajustamos durante o teste.
Como desligo?
DELETE /integrations/chatwoot, ou o interruptor no painel. As conversas já criadas no Chatwoot continuam lá. Para consultar o estado (idle, ok ou error, último ok e último erro), use GET /integrations/chatwoot.
Comparado a ligar o Chatwoot na Evolution
Na Evolution, o Chatwoot é uma integração nativa do servidor. Na ProxyBox a ponte roda do nosso lado, porque o motor da instância fica isolado da internet. O resultado para você é o mesmo (conversas espelhadas), com a diferença de que as respostas passam pelas travas de segurança do número. Para quem migra, veja migrar da Evolution.
Veja também
- Bots de WhatsApp pela API: tipos e limites
- Equipe, papéis e métricas da API de WhatsApp
- Guardar mídia do WhatsApp no S3, R2 ou MinIO
- Integrações da API de WhatsApp: n8n, Make, Zapier
Índice completo: índice dos guias. Sobre o produto: API de WhatsApp com IP brasileiro dedicado.
Autoria: equipe técnica da ProxyBox. Atualizado em 11/11/2026, contra as notas técnicas da ponte com o Chatwoot (fontes da API do Chatwoot lidas em 11/11/2026). Recurso em beta.