Como funciona a integração com o WhatsApp (mensagens transacionais)
Atualizado em 12/11/2026
A integração com o WhatsApp permite que a loja avise o cliente sobre o andamento da compra pelo aplicativo que ele mais usa: pedido recebido, pagamento aprovado, código de rastreio a caminho. São as chamadas mensagens transacionais, enviadas por modelos oficiais aprovados pelo WhatsApp Business.
Você a encontra em Comunicações > WhatsApp: Configurar. É a mesma tela que aparece em Marketing & SEO > Integrações, no item WhatsApp: são dois caminhos para o mesmo lugar.
Quanto custa (e por que isso importa)
A cobrança de cada mensagem é feita pela Meta, dona do WhatsApp, e o preço depende da categoria da mensagem. Essa diferença é o ponto mais importante de entender antes de ativar.
- Utilidade (transacional): avisos ligados a um pedido real, como pagamento aprovado e código de rastreio. Custam bem menos de um centavo de dólar por envio (na casa de US$ 0,008).
- Marketing (promocional): mensagens de divulgação, como carrinho abandonado e newsletter. São muito mais caras, na casa de US$ 0,06 por envio, cerca de oito vezes o valor de uma mensagem de utilidade.
Recomendação: mantenha ativos apenas os avisos transacionais (pedido e rastreio) e deixe desligados os disparos de carrinho abandonado e de newsletter pelo WhatsApp. Assim cada mensagem custa cerca de um centavo, e você usa o canal para informar, não para fazer campanha.
A proposta da integração é justamente essa: avisar o cliente sobre a compra dele, não substituir o e-mail marketing. Os valores acima são uma referência e podem variar conforme a tabela da Meta. Para conferir os preços atuais por categoria e país, consulte a tabela oficial de preços da plataforma WhatsApp Business.
Escolha o número antes de tudo
Antes de qualquer configuração, decida qual número de telefone vai enviar as mensagens. Aqui existe uma regra que não abre exceção: o número precisa ser novo (nunca usado no WhatsApp) ou um número que já esteja 100% na Cloud API.
- Um número novo, exclusivo dos disparos (recomendado): uma linha que ainda não foi usada em nenhum WhatsApp.
- Um número que já é Cloud API: se você já tem uma conta oficial na WhatsApp Cloud API, o número dela serve.
Atenção: um número que está em uso no WhatsApp comum ou no aplicativo WhatsApp Business (aquele instalado no celular) não serve para as mensagens transacionais. Essa conexão entra no chamado modo de coexistência, em que a Meta bloqueia a criação e a atualização dos modelos, e a sincronização falha com o aviso "esta conta não tem permissão para criar ou atualizar modelos". Para reaproveitar um número desses, seria preciso migrá-lo por completo para a Cloud API, o que o desliga do aplicativo no celular.
Por isso, use um número exclusivo para a integração, separado do WhatsApp de atendimento. Além de evitar o problema de coexistência, se esse número for suspenso você perde apenas o canal de envio automático, nunca o telefone que seus clientes usam para falar com a loja.
Para conseguir um número novo rápido, um caminho prático é contratar uma linha pré-paga, e nesse caso um chip digital (eSIM) costuma agilizar, porque a ativação é feita na hora, sem esperar a entrega de um chip físico. O que importa é que ele receba o código de verificação da Meta por SMS ou ligação. Assim que tiver a linha em mãos, deixe o número reservado só para a integração e não ative o WhatsApp dele no celular, para o número não cair no modo de coexistência e continuar apto a gerenciar os modelos.
Antes de conectar, deixe a conta pronta na Meta
A conexão acontece em uma janela da própria Meta (a empresa dona do WhatsApp), e é nela que o número é cadastrado e verificado. Você não precisa cadastrar o número antes: o que trava a conexão costuma ser uma etapa da conta empresarial que a Meta exige e ainda não foi feita. Confira esta lista antes de conectar:
- Verificação da empresa iniciada — a Meta pede que o seu negócio seja verificado. Enquanto a empresa aparecer como não verificada, parte dos recursos fica bloqueada.
- Autenticação de dois fatores (2FA) ativada — uma camada de segurança que a Meta exige na conta empresarial.
- Documentos do CNPJ enviados — a Meta confirma a identidade da empresa com documentos oficiais (o cartão CNPJ e o que mais ela solicitar).
- Forma de pagamento cadastrada — sem uma forma de pagamento válida, a Meta limita o envio de mensagens.
- Número livre e celular em mãos — o número não pode ter uma conta ativa no WhatsApp comum nem no aplicativo WhatsApp Business no momento da verificação, e precisa receber o código da Meta por SMS ou ligação durante a conexão.
Sobre a forma de pagamento: as cobranças da Meta são feitas em dólar americano, então ela precisa ser um cartão de crédito, que aceita cobrança internacional. Boleto e Pix não atendem nesse caso.
Se a conexão não concluir, quase sempre falta um desses itens na conta da Meta.
Se você ainda não tem uma conta do WhatsApp Business
Quem já tem uma conta na Cloud API escolhe essa conta na própria janela da Meta, durante a conexão. Se ainda não tem, crie a conta antes, no Gerenciador de Contas do WhatsApp da Meta (a tela API traz o link), escolhendo a opção Usar somente nome de exibição. A conta nasce só com o nome, e o número entra depois, pela janela da Meta, no momento da conexão.
Na criação, a Meta pede o Nome de exibição do WhatsApp Business (o nome que o cliente vê na conversa) e a Categoria da empresa. O nome de exibição precisa condizer com o nome comercial e seguir as diretrizes da Meta: enquanto ele estiver em análise, ou se for recusado, a Meta não deixa o número enviar mensagens.
Crie uma conta nova em vez de vincular uma conta que já existe no aplicativo do celular. A conta vinculada recai no modo de coexistência, o mesmo que bloqueia os modelos.
Como a configuração está organizada
Comunicações > WhatsApp: Configurar abre a Visão geral, que lista as etapas da integração na ordem em que elas são feitas, cada uma com o seu botão. O menu à esquerda da configuração leva direto a cada parte:
- Visão geral — a seção Etapas da integração, com Conexão com a Meta (botão Configurar), Modelos de mensagem (botão Sincronizar) e Teste de envio (botão Testar). A etapa Botão flutuante só aparece para a loja que ainda usa o botão antigo.
- API — a conexão com a Meta e a escolha da conta e do número que enviam as mensagens.
- Modelos de Mensagem — instala ou atualiza, na sua conta, os modelos de mensagem que a loja usa.
- Teste de Envio — manda uma mensagem de exemplo para o seu celular.
A conexão tem um selo de estado, que aparece na linha Conexão com a Meta da visão geral e na seção Conexão da tela API, e se repete nas seções das telas de modelos e de teste. Ele resume, em uma palavra, em que ponto a integração está:
- Ativa (verde) — conectada, com a conta e o número escolhidos e o envio ligado.
- Falta a conta e o número (amarelo) — a conexão foi feita, mas a escolha da conta ou do número não foi concluída.
- Autorização vencida (amarelo) — a permissão dada à Meta expirou, e as mensagens param de sair até você reconectar.
- Desligada (cinza) — tudo configurado, mas o envio está desligado. As mensagens que estavam na fila param em Falha e podem ser reagendadas no histórico depois de religar.
- Não conectada (cinza) — a conexão ainda não foi feita.
Como conectar
Com a conta da Meta pronta, a conexão acontece na tela API, em duas seções.
Na seção Conexão, no item Conta da Meta, o botão amarelo Conectar API abre a página Conectar o seu WhatsApp. Nela, o botão Conectar WhatsApp abre a janela da Meta, onde tudo acontece em sequência: você escolhe a Conta Empresarial, cadastra o número que vai enviar as mensagens e confirma o código que a Meta envia por SMS ou ligação. A permissão vale só para a conta escolhida ali.
Depois que você termina na Meta, a conclusão leva cerca de um minuto, porque a plataforma registra o número e ativa os avisos da conta. Mantenha a página aberta até voltar à tela API, que mostra o resultado no topo:
- Conectado com número registrado — a mensagem "WhatsApp conectado e número registrado." indica que está tudo pronto, e a conta e o número já voltam gravados.
- Conectado — a mensagem "WhatsApp conectado." indica que a autorização foi concluída. Confira a conta e o número na seção abaixo e faça um teste de envio antes de contar com os disparos.
- Recusa — o aviso diz o que faltou: nenhuma conta autorizada, conta escolhida que a Meta não confirmou para esta conexão, conta sem número cadastrado na Cloud API, autorização que alcançou só a conta de teste da Braavo ou autorização que não está mais válida. Refaça a conexão escolhendo a conta da sua empresa. Quando a Meta não responde no momento, o aviso pede para refazer a conexão em alguns minutos, ou para carregar as contas e confirmar a conexão.
Se você sair da janela da Meta antes de concluir, a página avisa e o botão Conectar WhatsApp continua disponível para recomeçar. Depois da primeira conexão, o botão da tela API passa a se chamar Reconectar.
A seção Conta e número mostra quem envia as mensagens. Quando a conexão termina com o número registrado, os dois campos já voltam preenchidos e basta conferir. Os botões de carregar servem para trocar a escolha ou completar uma conexão que voltou sem ela:
- Conta Empresarial (WABA ID) — a conta do WhatsApp Business que faz os disparos. O botão Carregar contas busca na Meta as contas que a autorização alcançou.
- Número de telefone — o número que aparece para o cliente. O botão Carregar números busca os números da conta escolhida, por isso a conta vem primeiro.
Os números que não servem aparecem na lista com o motivo ao lado: fora da Cloud API, desconectado na Meta, ou nome de exibição em análise, recusado ou sem aprovação na Meta. O número de teste da Meta também vem identificado, porque só alcança destinatários cadastrados na Meta e não serve para atender clientes.
Antes de você carregar as listas, cada campo mostra apenas o número de identificação gravado, e o nome da conta só aparece depois de Carregar contas. Ao terminar, clique em Gravar.
Atenção: ao gravar, a plataforma confere a conta escolhida com a Meta e pede a ela o envio dos status de entrega (é isso que faz o histórico de mensagens mostrar Entregue e Lido). Por isso o aviso pode trazer mais do que "Dados gravados". Se a conexão atual não alcançar a conta escolhida, ou se a Meta não responder na hora, a tela não grava a troca e diz o motivo: clique em Reconectar e marque a conta na tela da Meta, ou tente de novo em alguns minutos. A conta de teste da Braavo também é recusada, porque ela não é da loja. Se a Meta recusar a assinatura dos status, as mensagens saem, mas os status de entrega podem não chegar.
Ao reconectar, confira a conta e o número quando a tela voltar: a autorização nova pode alcançar uma conta diferente da anterior. Se os campos não vierem atualizados, carregue as contas de novo, porque a escolha antiga continua no campo até ser trocada.
O interruptor de envio
Ainda na seção Conexão, o interruptor Enviar as mensagens pelo WhatsApp (o link Saiba mais dele traz o caminho para criar a conta na Meta) controla se as notificações da loja saem por este canal. A conexão já o liga, então ele serve principalmente para pausar os envios sem desfazer a conexão: desligado, as notificações deixam de sair pelo WhatsApp.
A tela não deixa ligar o interruptor antes da conexão. Se você tentar, ela pede para clicar em Conectar API antes de ativar e não grava nada.
Quando a autorização da Meta vence
As conexões feitas antes da janela atual da Meta têm validade de cerca de 60 dias. Quando faltam 10 dias ou menos, a tela API mostra um aviso amarelo com o prazo; depois do vencimento, o selo passa a Autorização vencida e as mensagens param de sair.
Para renovar, faça a conexão de novo pela janela da Meta, descrita acima: ela substitui a autorização antiga. O aviso fala em clicar em Conectar API, mas, com a conta já conectada, o botão na tela se chama Reconectar.
Sincronizar os modelos
As mensagens do WhatsApp só saem por modelos aprovados pela Meta. A tela Modelos de Mensagem instala na sua conta os modelos que a loja usa. Ela depende da Conta Empresarial: enquanto a conta não estiver escolhida na tela API, um aviso amarelo pede essa escolha antes de sincronizar.
- Ação na conta da Meta — Criar modelos novos na primeira carga. A Meta recusa a criação de um modelo que já existe na conta, então, para reenviar o texto de modelos já instalados, escolha Atualizar modelos existentes. Na atualização, a Meta aceita uma edição por modelo a cada 24 horas (e até 10 a cada 30 dias), e o modelo ainda em análise não pode ser editado.
- Modelo a sincronizar — deixe em Todos os modelos para percorrer a lista inteira. Escolha um modelo para reenviar apenas ele, o que é útil quando um único envio falhou.
O botão Sincronizar modelos envia um modelo por vez, de propósito: a Meta limita quantas chamadas aceita em sequência, e o ritmo controlado evita bloqueios por excesso de requisições. Ele fica desabilitado enquanto a Conta Empresarial não estiver escolhida. O andamento aparece no Registro da sincronização, linha a linha, com a situação ao lado do título (em andamento, pausada, interrompida ou concluída), e o botão Pausar interrompe a fila depois do modelo que está sendo enviado (o mesmo botão vira Retomar). Se a conexão cair no meio, a sincronização para, e o Retomar tenta de novo o modelo que ficou sem resposta. Ao final, se algum modelo falhou, o resumo informa quantos e as linhas com problema ficam em vermelho, para você reenviar cada um pelo campo Modelo a sincronizar.
Depois de enviados, os modelos passam pela análise da Meta. Para acompanhar a aprovação, editar ou remover um modelo, a própria tela traz um link para o gerenciador de modelos no painel da Meta.
Testar o envio
A tela Teste de Envio confirma que a integração funciona de ponta a ponta. Ela só libera o teste depois que a tela API estiver concluída (conta conectada e número escolhido) e mostra de qual número a mensagem vai sair, para você conferir o remetente.
Em Número de WhatsApp que recebe o teste, digite o número com DDD. O código do país (55) é acrescentado automaticamente para números nacionais. O botão Enviar teste manda o modelo de pedido aprovado, com dados de exemplo no lugar das variáveis. Se esse modelo ainda não estiver aprovado na sua conta, o envio usa o modelo de exemplo da Meta (hello_world), e o resultado informa qual modelo foi usado.
Se a mensagem chegar ao seu celular, está tudo certo. Se o teste avisar que não há modelo apto na conta, sincronize os modelos e aguarde a aprovação da Meta antes de tentar de novo.
Sobre o botão flutuante do WhatsApp
O botão flutuante (aquele ícone fixo na loja que abre uma conversa) é outra ferramenta. Hoje ele é configurado em Marketing & SEO > PopUps (novo), como o tipo de pop-up Botão do WhatsApp. A integração descrita aqui cuida apenas das mensagens transacionais automáticas, que são coisa diferente do botão de contato.
A loja que ainda usa o botão antigo vê também a parte Botão Flutuante nesta configuração. Desligá-lo ali é definitivo: o botão sai da loja, a parte deixa de aparecer, e o caminho para voltar a ter um botão do WhatsApp passa a ser os Pop-ups. O pop-up só aparece na loja com o ajuste Usar a versão nova dos pop-ups ligado, no botão Ajustes da lista de PopUps (novo). Ligar esse ajuste também tira da loja os PopUps (antigo) e a barra de privacidade antiga, como explica o artigo "Como ativar o botão de WhatsApp na loja".