Empresa brasileira · Entrega automática · Suporte em português Seg a sex, 9h as 18h · PIX em reais
ProxyBox
API de WhatsApp · Integrações

Como ligar o Chatwoot à API de WhatsApp?

Passo a passo para espelhar as conversas da instância no Chatwoot e responder de lá, com o webhook para colar, opções e limites. Beta.

7 min de leitura Atualizado em 14 de novembro de 2026
Resposta curta
No Chatwoot, crie uma caixa de entrada do tipo API. Na ProxyBox, grave a integração com PUT /integrations/chatwoot (endereço do Chatwoot, account_id, inbox_id e o token de acesso) e cole no Chatwoot o endereço de webhook que a ProxyBox mostra (https://proxybox.com.br/api/whatsapp/integrations/chatwoot/<instância>/<token>). Mensagens recebidas viram conversas no Chatwoot; as respostas dos atendentes saem pelo seu número.

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_groups falso, 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?

  1. Uma instância conectada da ProxyBox e a chave.
  2. Um Chatwoot em endereço https público (a ProxyBox recusa endereços internos e http).
  3. 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átis

Passo 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:

bash
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:

bash
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

  1. Do celular de outra pessoa, mande uma mensagem para o número da instância. Ela deve aparecer como nova conversa no Chatwoot.
  2. Responda no Chatwoot. A resposta deve chegar ao celular, e a mensagem no Chatwoot deve ficar com a marca de enviada.
  3. 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":

  1. cada mensagem criada pela integração leva uma marca que a identifica na volta;
  2. um eco gravado antes de espelhar (conversa e texto) descarta a mensagem que acabou de ser criada;
  3. marcas no envio e no id devolvido evitam que o aviso message.sent gerado 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

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

Perguntas frequentes

Preciso ter o Chatwoot instalado por conta própria?
Sim. O Chatwoot é do cliente (na nuvem dele ou no servidor dele), em endereço https público. A ProxyBox faz a ponte entre a instância de WhatsApp e a caixa de entrada do tipo API.
As respostas dos atendentes seguem os limites da API?
Sim. Quem responde pelo Chatwoot fica sujeito ao ritmo, à lista de não perturbe, à trava de contato novo e aos limites diários, porque a resposta sai pela mesma operação de envio.
Se o Chatwoot cair, perco as mensagens?
As mensagens recebidas naquele intervalo não são espelhadas no Chatwoot. Há até 3 tentativas imediatas, mas não há fila durável. Elas continuam disponíveis nas conversas da API e nos avisos.

Guias relacionados

Pronto para colocar no ar?

Comece no sandbox, grátis. Quando funcionar, contrate a instância do seu número e pague com PIX ou saldo.

Com IP brasileiro dedicado R$ 89,90/mês
Só a instância (traga o seu IP) R$ 39,90/mês
Travou em alguma etapa?Manda o print do erro no WhatsApp. Respondemos em português.
Suporte em português Fale no WhatsApp