Como usar a API oficial do WhatsApp no Chatwoot em menos de 5 minutos

Resposta curta: com o número já conectado na Datafy API, a ligação com o Chatwoot é uma troca de dados em dois sentidos e leva poucos minutos. No Chatwoot você vai em settings, inboxes, add inbox, escolhe o tipo API, dá um nome e cola no campo de webhook a URL que a aba Chatwoot do painel da Datafy já gera pronta, e clica em create API channel. De volta na Datafy, você preenche quatro valores do Chatwoot: a URL base, o account ID, o inbox ID e o API token. Salva as configurações e está conectado. A partir daí as mensagens chegam no Chatwoot, as respostas dadas ali saem pelo WhatsApp, e em coexistência até a mensagem enviada do celular aparece na caixa de entrada.

Principais pontos

• No Chatwoot, o tipo da caixa de entrada é API. Não é o canal de WhatsApp nativo, e essa escolha é o que faz a integração funcionar.
• A URL de webhook você não monta: a aba Chatwoot do painel da Datafy gera a URL do número e você só copia.
• Os quatro valores do Chatwoot ficam em lugares diferentes: barra de endereços, configurações da conta, engrenagem da inbox e configurações do perfil.
• Funciona nos dois sentidos, e em coexistência a mensagem enviada pelo celular do número também aparece no Chatwoot.
• O atendente continua preso à janela de 24 horas. Com a janela fechada, a resposta pela caixa de entrada não sai: só template aprovado.

Antes: o número conectado

A integração começa com um número já funcionando na API oficial. No painel da Datafy você cria o canal, recebe o token sk_live_xxx na criação, conecta o número escaneando o QR code com o celular e pronto: todos os endpoints da API oficial ficam disponíveis, sem criar conta de desenvolvedor, sem criar aplicativo na Meta e sem esperar aprovação de permissões.

Sobre os "menos de 5 minutos": eles contam a partir de quem já tem um portfólio empresarial no Facebook. Criar a BM é etapa anterior e não entra nesse relógio. O passo a passo da conexão está aqui.

Passo 1: a caixa de entrada no Chatwoot

No Chatwoot:

1. Clique em settings.
2. Clique em inboxes.
3. Clique em add inbox.
4. Na lista de canais, escolha API.
5. Dê um nome à caixa de entrada. Um nome que identifique o número, se você for ligar vários.
6. No campo de URL do webhook, cole a URL gerada pela Datafy (o passo 2 explica onde ela está).
7. Clique em create API channel.

É só isso do lado do Chatwoot. A caixa de entrada do tipo API é genérica de propósito: ela recebe e devolve mensagens por HTTP, e é exatamente o que a Datafy precisa do outro lado.

Passo 2: a URL de webhook, na aba Chatwoot da Datafy

No painel da Datafy, abra o número e vá na aba Chatwoot. A URL de webhook daquele número já aparece gerada ali. Copie e cole no campo do Chatwoot.

Essa URL é o endereço para onde o Chatwoot manda as mensagens que o atendente escreve. Ela é específica do número, então, se você tem vários números, cada um tem a sua URL e a sua caixa de entrada.

Como usar a API oficial do WhatsApp no ChatwootCanal DATA7 · 5 min · assistir no YouTube

Passo 3: os quatro valores do Chatwoot na Datafy

Volte à aba Chatwoot da Datafy. Agora é a Datafy que precisa saber como falar com o seu Chatwoot, e são quatro campos:

Um ponto que costuma travar a primeira tentativa: a URL base é só o endereço do servidor, sem caminho nenhum depois da barra. Se você copiar a barra de endereços inteira, com a rota da tela em que estava, a integração não fecha.

Outro ponto: o API token é o token do usuário do Chatwoot, no perfil, e não um token de aplicação. É o mesmo valor que você usaria para chamar a API do Chatwoot em qualquer outra integração, então trate como credencial e não deixe circular por grupo de trabalho.

Clique em salvar configurações. Está conectado.

Passo 4: o teste nos dois sentidos

Vale rodar a sequência inteira antes de colocar a equipe para atender. São cinco testes, e cada um cobre um caminho diferente:

O quarto teste é o que separa uma integração de API oficial comum de uma em coexistência. Se o número foi conectado como um aplicativo do WhatsApp Business que já existia, o atendimento manual pelo celular continua acontecendo, e essas mensagens enviadas pelo celular aparecem no Chatwoot junto com as da API. É o mesmo histórico, no mesmo lugar.

No último teste, a Meta limita documento a 100 MB. Num teste de referência, o primeiro PDF escolhido passava disso e precisou ser trocado por um arquivo mais leve. Os outros limites da Meta, para referência: imagem 5 MB, áudio 16 MB, vídeo 16 MB.

O atendente também segue a janela de 24 horas

Aqui está a parte que nenhuma caixa de entrada resolve, e que vale entender antes de colocar time para atender.

Resposta dada pelo Chatwoot é mensagem de serviço, e mensagem de serviço só sai com a janela de atendimento daquele cliente aberta. A janela abre quando o cliente manda mensagem, dura 24 horas, e só uma nova mensagem dele renova o prazo. Resposta de atendente, de bot ou de automação não aumenta nada. E cada cliente tem a sua janela.

Quando o prazo termina e alguém tenta responder pela caixa de entrada, o efeito é traiçoeiro: a requisição pode ser aceita com HTTP 200 e um identificador de mensagem, e a falha chegar depois pelo webhook de status, com o erro correspondente. O atendente vê a mensagem enviada na tela e o cliente não recebe nada. Se o seu fluxo depende disso, trate o status como fonte de verdade, não a tela.

Para retomar conversa fora da janela, o caminho é template aprovado adequado à finalidade, e template não reabre a janela: é a resposta do cliente que abre um novo período de 24 horas.

O que o Chatwoot não muda: o custo

Ter uma caixa de entrada bonita não altera a cobrança da Meta, que considera as mensagens entregues, a categoria e o país do destinatário.

Até 30 de setembro de 2026, mensagem de serviço dentro da janela não é cobrada. A partir de 1º de outubro de 2026, cada número empresarial passa a ter 1.000 mensagens de serviço gratuitas por mês, e a cobrança começa na 1.001ª mensagem de serviço entregue, mesmo dentro da janela. A franquia é por número de telefone, não por cliente nem por conversa, e não vale para marketing, utilidade ou autenticação.

Um detalhe sobre a franquia: ela está na documentação da Datafy, e o anúncio da Meta aparece na versão em inglês da página de preços. Confira sempre a tabela vigente antes de fechar orçamento. O que muda em outubro de 2026.

Um detalhe que favorece quem atende em coexistência: mensagem enviada pelo celular não é cobrada, porque a cobrança é da mensagem enviada pela API. E, como a franquia é por número, distribuir o atendimento entre mais números multiplica a franquia gratuita. Isso resolve o custo, não a operação: dividir o atendimento entre números é decisão sua.

Por que não usar o bate-papo do painel no lugar

O painel da Datafy tem uma aba de bate-papo que mostra as mensagens ao vivo, com o payload de cada uma, e é tentador usar aquilo como atendimento. Não é para isso. A própria Datafy delimita: "não é para ser utilizado como bate-papo ou multi-atendimento, é apenas para logs."

Os limites deixam isso claro: o bate-papo guarda 7 dias de mensagens e no máximo 100 mensagens por conversa, e não mostra o conteúdo de imagem ou vídeo, só sinaliza que chegou. Serve para depurar integração, e é ótimo nisso. Como usar o log e ver o payload.

Para atender, os caminhos são o Chatwoot, outro sistema de atendimento, ou um construído por você. Como montar um atendimento do zero.

Quando você precisar sair da caixa de entrada

Algumas coisas não passam pelo Chatwoot e vão direto na API. A primeira chamada de sempre, para descobrir os seus identificadores:

GET https://cloud.datafyapi.com.br/me
Authorization: Bearer sk_live_xxx

{
  "cliente_id": "uuid-do-cliente",
  "phone_number_id": "106540352242922",
  "waba_id": "366634483210360",
  "business_id": "123456789"
}

Para falar com quem está fora da janela, é template, e antes de enviar vale conferir quais estão aprovados:

GET https://cloud.datafyapi.com.br/templates
Authorization: Bearer sk_live_xxx

E o envio, pelo mesmo endpoint de qualquer mensagem:

POST https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages
Authorization: Bearer sk_live_xxx
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "retomada_atendimento",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "body",
        "parameters": [ { "type": "text", "text": "Maria" } ]
      }
    ]
  }
}

O token vai sempre no cabeçalho. Quando o cliente responder o template, a janela abre e o atendimento volta a acontecer normalmente pelo Chatwoot.

Vale lembrar as camadas de limite, que continuam valendo mesmo com o atendimento humano no meio: a Datafy aceita 500 requisições por minuto nas rotas de envio, respondendo 429 com os segundos a aguardar, e a Meta trabalha com 80 mensagens por segundo em número registrado padrão e 20 por segundo em número do WhatsApp Business App em coexistência.

Perguntas frequentes

Qual tipo de caixa de entrada eu crio no Chatwoot?

O tipo API. Não é o canal nativo de WhatsApp: é a caixa de entrada genérica que troca mensagens por HTTP.

O que é exatamente a URL base do Chatwoot?

É o endereço da sua instalação até antes da primeira barra do caminho. Copiar a barra de endereços inteira, com a rota da tela aberta, é o erro mais comum.

Onde fica o API token?

No seu perfil do Chatwoot, em profile settings, descendo até o fim da página, no token de acesso.

Preciso montar a URL de webhook na mão?

Não. A aba Chatwoot do painel da Datafy gera a URL daquele número já pronta, e você só copia e cola.

A mensagem que o atendente manda pelo celular aparece no Chatwoot?

Aparece, quando o número está em coexistência. É esse o teste que vale fazer antes de colocar a equipe para atender.

Posso responder pelo Chatwoot a qualquer momento?

Só com a janela de 24 horas daquele cliente aberta. Fora dela, a resposta livre não chega, mesmo que a tela mostre a mensagem enviada, e a falha aparece no webhook de status. Para retomar, template aprovado.

O Chatwoot muda o quanto eu pago em mensagens?

Não. Quem cobra as mensagens é a Meta, no cartão do seu portfólio empresarial. O Chatwoot é só a interface de atendimento, e a Datafy cobra a conexão do número.

Como decidir

Se você precisa de uma caixa de entrada para a equipe atender o WhatsApp oficial e não quer construir interface, o Chatwoot resolve com uma caixa de entrada do tipo API e quatro valores preenchidos na Datafy. Faça a ligação, rode os cinco testes e só então distribua os atendentes.

O que a integração não resolve é regra da Meta: a janela de 24 horas, a necessidade de template fora dela e a cobrança por mensagem entregue continuam iguais. Planeje o atendimento em cima disso, e não em cima do que a tela permite clicar.

Leia também

• Como conectar um número na API oficial do WhatsApp
• Como ver o payload das mensagens em tempo real
• Como criar um atendimento de WhatsApp do zero
• A mensagem de serviço vai ser paga em outubro de 2026