Como conectar o WhatsApp ao Chatwoot pela API oficial

Conectar o WhatsApp ao Chatwoot pela API oficial é o caminho certo quando você quer vários agentes no mesmo número, histórico organizado e disparos dentro das regras da Meta. O Chatwoot é a caixa de entrada visual: ele mostra as conversas numa tela de atendimento, mas quem fala com a WhatsApp Cloud API por trás não é ele. A API oficial não tem app próprio de conversa, então alguma ferramenta precisa dar cara de atendimento humano para essa conexão, e o Chatwoot faz esse papel.

A diferença de quem conecta pela covercut é onde a integração acontece. Você não monta nada na plataforma de desenvolvedores da Meta nem configura webhook na mão: o número entra pelo fluxo oficial e, na hora de plugar o Chatwoot, a própria covercut cria a caixa de entrada e liga tudo. Vou mostrar como isso funciona na prática e onde as coisas costumam travar, porque quando um cliente chega reclamando que "o Chatwoot não recebe mensagens", o problema quase nunca está no Chatwoot.

Como a conexão realmente funciona

Vale entender o desenho antes de sair clicando. A covercut é a ponte entre a Meta e o Chatwoot. Ela recebe as mensagens que chegam no seu número pela Cloud API e as empurra para dentro do Chatwoot; quando o agente responde por lá, o caminho é o inverso, a resposta volta pela covercut e sai pela API oficial. O Chatwoot nunca conversa direto com a Meta nesse modelo, o que muda bastante o passo a passo em relação aos tutoriais genéricos que você encontra por aí.

Na prática isso quer dizer que você não vai criar um canal "WhatsApp Cloud" no Chatwoot nem colar Phone Number ID e Business Account ID em lugar nenhum. A caixa de entrada que a covercut cria é um canal de API, e é ela que fica responsável por entregar e receber as mensagens.

O que preparar antes de começar

Duas coisas precisam existir antes do primeiro clique. Pular qualquer uma é o que mais gera retrabalho:

• Seu número conectado na covercut. Isso é feito uma vez, pelo Embedded Signup (o fluxo oficial da Meta), e já resolve credenciais, webhook e coexistência. Se o número ainda roda no app WhatsApp Business do celular, você não precisa apagar nada: com a coexistência ele passa a funcionar no app e na API ao mesmo tempo, mantendo o histórico.
• Uma instância do Chatwoot, em nuvem ou instalada por você, com dois dados em mãos: o ID da conta (o número que aparece na URL do Chatwoot, tipo /accounts/1) e um token de acesso de um usuário com permissão para criar caixas de entrada.

Só isso. Não é preciso número novo dedicado, não é preciso mexer em token da Meta, não é preciso abrir a plataforma de desenvolvedores.

Conectando o Chatwoot pelo painel da covercut

Com o número já conectado, o resto leva poucos minutos. No painel da covercut você entra em Integração Chatwoot, escolhe o número que vai atender por lá e preenche três campos:

• URL da instância Chatwoot, o endereço da sua conta (por exemplo https://chat.suaempresa.com).
• ID da Conta, aquele número da URL.
• Token de Acesso, o token do usuário do Chatwoot.

Ao salvar, a covercut cria a caixa de entrada no seu Chatwoot e já configura o webhook dela apontando para o lugar certo. Você não precisa preencher o ID da caixa de entrada: deixe em branco e o sistema cria uma nova. Se você já tem uma inbox de API criada e quer reaproveitar, aí sim informa o ID dela.

Depois de salvar, use o botão Testar Comunicação para confirmar que a URL, o ID e o token estão válidos. Passando no teste, mande uma mensagem de um celular qualquer para o número conectado: se ela aparecer como conversa nova no Chatwoot, a entrada está funcionando. Responda por lá e veja se chega no celular de teste. Só considere pronto quando os dois sentidos funcionarem.

Nas configurações avançadas dá para ajustar detalhes úteis do dia a dia, como ignorar mensagens de grupo, assinar as respostas com o nome do atendente, reabrir automaticamente conversas já resolvidas e, em coexistência, espelhar no Chatwoot as mensagens que você responde direto pelo app do celular.

Templates: a parte que a maioria descobre tarde

Aqui mora o mal-entendido mais comum. O Chatwoot deixa você digitar e enviar texto livremente, mas a API oficial tem uma regra rígida: fora da janela de 24 horas, você só consegue iniciar conversa com um template aprovado pela Meta.

A janela funciona assim: quando o cliente te manda uma mensagem, abre um período de 24 horas em que você responde com texto livre. Passado esse prazo sem nova mensagem dele, a única forma de reabrir o contato é com um modelo aprovado, nas categorias de marketing, utilidade ou autenticação. Quando alguém nos procura dizendo que "o Chatwoot não deixa mandar mensagem para um contato antigo", é quase sempre isso: a janela fechou e não há template aprovado configurado. Vale criar e aprovar seus modelos principais antes de colocar o time para operar, senão o atendimento trava no primeiro dia.

Coexistência: app e Chatwoot no mesmo número

Muita empresa já tem um número rodando no app WhatsApp Business, com histórico e contatos, e tem medo de perder tudo ao ir para a API. Não precisa. Com a coexistência, o número continua no app do celular e ao mesmo tempo alimenta o Chatwoot pela API.

Na prática, o dono do número segue respondendo pelo celular quando está na rua, enquanto a equipe atende pelo Chatwoot no computador. Sem coexistência, migrar o número para a API faz ele deixar de funcionar no app comum. Então, se manter o app importa para você, confirme que a conexão foi feita em modo de coexistência antes de validar o número.

Cuidando da qualidade do número

Conectar é só o começo. O que sustenta a operação no longo prazo é a qualidade do número, classificada pela Meta como alta, média ou baixa. Qualidade baixa reduz seus limites de envio e, no pior caso, restringe o número.

O que mais derruba a qualidade é disparar mensagem para quem não pediu para receber. Opt-in não é burocracia: é o que separa uma operação saudável de um número bloqueado. Antes de mandar mensagem ativa, tenha o consentimento do cliente. Some a isso a verificação da empresa no Gerenciador de Negócios, que ajuda a elevar os limites diários de conversas iniciadas por você. Esses limites sobem conforme volume, qualidade e verificação, e os patamares mudam com o tempo, então olhe sempre o que o Gerenciador da Meta mostra para a sua conta em vez de um número que você viu num artigo antigo.

Confira mais sobre qualidade de número aqui

Quem paga o quê

Uma dúvida que aparece sempre: quem cobra pelas mensagens? A Meta cobra por conversa, e essa cobrança vai direto para o cliente. Você cadastra o cartão da sua empresa na conta da Meta e é ela quem debita ali. A covercut não cobra por mensagem, conversa ou template e não intermedia esse pagamento.

O que a covercut cobra é uma mensalidade fixa pelo serviço: a plataforma, a conexão do número pelo fluxo oficial com suporte a coexistência, a criação da integração com o Chatwoot, a infraestrutura e o suporte. O Chatwoot em si pode ser autohospedado ou usado na nuvem, com custos próprios dependendo da escolha. Saber dessa separação evita surpresa: o valor por conversa é assunto entre você e a Meta.

Se o seu número já está conectado na covercut, o próximo passo concreto é abrir a Integração Chatwoot no painel, colar a URL, o ID da conta e o token do seu Chatwoot e salvar. A caixa de entrada e o webhook são criados na hora, e você economiza os dias de tentativa e erro que quase todo mundo enfrenta tentando ligar isso na mão.

Perguntas frequentes

Preciso apagar minha conta do WhatsApp Business para usar no Chatwoot?

Não. Com a coexistência, o mesmo número funciona no app WhatsApp Business do celular e na API oficial ao mesmo tempo, alimentando o Chatwoot. Você mantém o histórico e os contatos. Só quando a conexão é feita sem coexistência é que o número deixa de funcionar no app comum.

Preciso configurar webhook ou colar Phone Number ID no Chatwoot?

Não. Conectando pela covercut, você não cria o canal no Chatwoot nem toca no webhook da Meta. A covercut cria a caixa de entrada (um canal de API) e configura o webhook automaticamente quando você salva a integração no painel. Basta informar a URL do Chatwoot, o ID da conta e o token de acesso.

Por que minhas mensagens não aparecem no Chatwoot?

Quase sempre é a integração ainda não ativada ou uma credencial errada. Confira se a integração está ligada e salva para aquele número, se o ID da conta e o token estão corretos e se o token tem permissão para criar caixas de entrada no Chatwoot. Como o webhook é configurado pela covercut, a causa costuma estar nesses dados e não em ajuste manual na Meta. Se tudo parecer certo, o suporte consegue verificar a conexão.

Consigo enviar mensagem para qualquer contato pelo Chatwoot?

Não livremente. Fora da janela de 24 horas após a última mensagem do cliente, você só inicia conversa com um template aprovado pela Meta. Dentro da janela, o texto é livre. Por isso vale criar e aprovar seus templates principais antes de colocar a equipe para operar.

A covercut cobra por mensagem enviada pelo Chatwoot?

Não. A cobrança das conversas é feita pela Meta, direto no cartão que você cadastra na conta dela. A covercut cobra apenas uma mensalidade fixa pelo serviço de plataforma, conexão do número e suporte, sem taxa por mensagem, conversa ou template.