Para integrar o WhatsApp Business ao seu sistema pelo caminho oficial, você usa a WhatsApp Business Platform da Meta, direto pela Cloud API ou por uma plataforma que já opera essa API. O sistema envia mensagens, usa modelos aprovados (templates) para falar fora da janela de 24 horas e recebe respostas e status por webhook. Nós já fizemos essa integração na Maximune, pela plataforma Helena, e construímos a caixa única de atendimento do CirurgiaJá.
Atuamos como desenvolvedores do projeto, e esta página não representa a Meta nem o WhatsApp. Ela explica como escolher a conexão, quais regras da Meta mudam o desenho do sistema e os problemas que vimos no código de produção. Faz parte do nosso trabalho de integração de sistemas.
API oficial, plataforma ou QR Code: qual conexão escolher
Essa primeira decisão define regras, custo e risco.
| Caminho | Como conecta | O que considerar |
|---|---|---|
| Cloud API direta | Seu sistema fala com a Meta, com webhooks assinados. | Mais controle. Você constrói a tela de atendimento e cuida de templates, limites e tokens. |
| Plataforma sobre a API oficial | Seu sistema fala com a plataforma, que fala com a Meta. Foi o caso da Helena na Maximune. | Mesmas regras da Meta, com caixa de atendimento pronta. Soma a mensalidade da plataforma. |
| Conexão por QR Code | O número é pareado como aparelho, por provedores como Z-API e Evolution. | Fora da Cloud API. Sem templates e sem janela, mas com risco de restrição do número. |
Sobre o último caminho, seja qual for o provedor, o próprio WhatsApp avisa que apps não oficiais violam os termos e podem levar a restrição ou banimento, e suas diretrizes citam clientes não oficiais e disparo automático em massa. Por isso não indicamos conexão por QR Code para campanha nem para disparo proativo. Para esse uso, o caminho é a API oficial.
Janela de 24 horas e templates: a regra que decide o desenho
Quando o cliente escreve para a empresa, abre uma janela de atendimento de 24 horas, e cada nova mensagem dele reinicia a contagem. Com a janela aberta, a equipe responde em texto livre. Depois que ela fecha, só saem templates aprovados. Na prática, a tela do atendente precisa saber se a janela está aberta e, se não estiver, oferecer só os modelos permitidos.
Todo template pertence a uma categoria: marketing, utilidade (utility) ou autenticação. A revisão é automática e pode levar até 24 horas. Só template aprovado pode ser enviado, e ele pode ser pausado por feedback negativo ou baixa leitura. A categoria dá mais trabalho do que parece:
- Utilidade exige duas coisas: a mensagem não pode ser promocional e precisa ser específica ou solicitada pelo usuário, ou essencial para ele.
- Marketing é o padrão: conteúdo misto, como um aviso de pedido com uma promoção, conta como marketing. Uma pesquisa genérica de satisfação também não passa como utilidade.
- A Meta pode reclassificar depois de aprovar: um template de utilidade pode virar marketing, normalmente com aviso de 1 dia, e o uso indevido recorrente traz restrições.
Um exemplo de clínica: o lembrete da próxima dose é candidato natural a utilidade, e uma campanha de reativação é marketing. A palavra final sobre a categoria é da Meta.
Também pesam na conta:
- Opt-in: a pessoa precisa aceitar receber mensagens, sabendo de qual empresa. A política também manda respeitar pedidos de bloqueio, dentro e fora do WhatsApp.
- Limite de envio: conta números únicos fora da janela em 24 horas móveis, vale para o portfólio inteiro e começa em 250. Verificar o negócio é um dos caminhos para subir.
- Custo por mensagem: a Meta cobra por mensagem entregue, conforme categoria e país. Desde 1º de outubro de 2026, mensagens de serviço acima da faixa gratuita de 1.000 por mês, por número, e utilidade respondida dentro da janela também são cobradas.
Onde a integração com WhatsApp costuma dar problema
Estes pontos saíram do código de um CRM de atendimento nosso em produção, que hoje roda com Z-API e Evolution. Vários deles valem para qualquer conexão.
O mesmo evento chega duas vezes
Na Cloud API, a Meta tenta entregar o webhook por até 7 dias, e isso pode gerar notificações duplicadas. Nosso receptor grava cada evento antes de processar, com uma chave formada pelo ID da mensagem ou pelo conteúdo, e ignora o que já viu. O erro fica registrado, e o evento pode ser reprocessado sem pedir nada ao provedor.
Trocar de provedor sem reescrever a caixa de entrada
Cada provedor tem formato próprio de mensagem e de status. Isolamos isso numa camada: cada número declara por qual conexão opera, e o resto do sistema não precisa saber. Assim dá para migrar número por número, sem chave geral e sem parar o atendimento.
Nem todo contato chega com telefone
Conversas iniciadas pelo atendente podem vir com um identificador de privacidade no lugar do número. Sem cuidado, isso gera conversa órfã ou cadastro duplicado. Fazemos o vínculo quando uma mensagem revela o telefone real e existe exatamente um contato compatível. Outro detalhe: em mensagem enviada pela empresa, o nome que vem no evento é o da própria empresa. Se o sistema aceitar, renomeia o cliente errado.
Áudio que não toca
Na conexão por QR Code, a mídia pode chegar criptografada. Se o arquivo for salvo direto, o áudio aparece na conversa e não toca. Tratamos com download pelo provedor e, se ele falhar, abrimos o arquivo com a chave da própria mensagem. Na Cloud API o cuidado é outro: a URL da mídia expira em 5 minutos e exige token, então o download precisa ser rápido e em segundo plano.
Anúncio que chega sem texto
Quem clica num anúncio de WhatsApp costuma chegar sem texto digitado, e a regra de origem por palavra-chave não encontra nada. Por isso a origem segue uma ordem: identificador do anúncio, depois texto da primeira mensagem, depois a origem padrão do número.
Número caído, robô sem saída
Na conexão por QR Code, o número pode desconectar, então o sistema acompanha o estado de cada um e guarda o último erro. O envio passa por uma fila por número, com ritmo limitado e aumento gradual em número novo. Isso reduz o risco, sem eliminar. E o chatbot tem tempo limite: sem resposta, a conversa vai para a fila de atendimento.
O que precisa estar pronto antes de começar
- Portfólio e número: negócio verificado e número definido. Um número em uso no app WhatsApp Business pode entrar na Cloud API por coexistência, por meio de um parceiro da Meta e com limitações.
- Base com opt-in: onde e como cada contato aceitou receber mensagens.
- Templates escritos: um por finalidade, sem misturar aviso e promoção.
- Webhook: endereço HTTPS com certificado válido, pois autoassinado não é aceito, e validação do cabeçalho X-Hub-Signature-256 com o app secret.
- Regra de atendimento: filas, horários e quem assume quando o robô para.
- Cuidado com saúde: a política proíbe usar o WhatsApp para fornecer telemedicina e restringe informações de saúde quando a lei proíbe. Veja mais em software para saúde.
Projetos em que fizemos
Maximune: a clínica de vacinação de Belo Horizonte conversa com pacientes pelo WhatsApp Business via Helena, com templates aprovados e webhooks com assinatura HMAC. Rotinas automáticas enviam lembrete de dose, fazem a triagem na véspera do atendimento e disparam campanhas de reativação.
CirurgiaJá: o CRM sob medida de uma clínica cirúrgica reúne as conversas numa caixa única, com fila, atribuição automática, respostas por atalho e chatbots de triagem. A implantação começou pelo atendimento e depois vieram leads, follow-up, agenda e orçamentos. Para esse tipo de sistema, veja desenvolvimento de CRM.
Prazo e custo da integração com WhatsApp
O custo tem duas partes: o desenvolvimento e a operação, que inclui o que a Meta cobra por mensagem e a plataforma, se houver. O que pesa no desenvolvimento:
- Caminho escolhido: ligar o sistema a uma plataforma pronta é menor do que construir uma caixa de atendimento própria.
- Só avisos ou conversa de ida e volta: disparo de lembrete é mais simples do que fila, atribuição e chatbot.
- Quantidade de templates e gatilhos: cada automação tem regra e teste.
- Vínculo com o cadastro: casar conversa com cliente exige limpar os telefones.
- Mídia e histórico: guardar áudio e documentos soma armazenamento e segurança.
Cada etapa tem proposta por escrito com valor fechado. Para ter uma faixa do seu caso, use a calculadora de projetos.
Perguntas frequentes
Dá para mandar mensagem no WhatsApp para quem nunca falou com a empresa?
Pela API oficial, só com template aprovado e com opt-in da pessoa, que precisa saber de qual empresa vai receber mensagens. Fora da janela de 24 horas, texto livre não é permitido.
O que é a janela de 24 horas do WhatsApp?
É o período que começa quando o cliente escreve para a empresa e reinicia a cada nova mensagem dele. Nesse tempo, a equipe responde livremente. Depois que fecha, só saem templates aprovados.
Quanto tempo a Meta leva para aprovar um template?
A revisão é automática e pode levar até 24 horas. Um template aprovado ainda pode ser pausado por feedback negativo ou baixa leitura, e a Meta pode mudar a categoria dele depois.
Posso usar o mesmo número no celular e na API oficial?
Existe a coexistência, que conecta um número do app WhatsApp Business à Cloud API por meio de um parceiro da Meta, com limitações. Listas de transmissão, por exemplo, ficam desativadas. Vale avaliar caso a caso.
Vale usar conexão por QR Code em vez da API oficial?
Serve para atendimento de baixo volume ou transição, sabendo do risco. Ela fica fora da Cloud API, e o WhatsApp avisa que apps não oficiais podem levar a restrição ou banimento. Para campanha e disparo proativo, indicamos a API oficial.
Quanto custa integrar o WhatsApp ao sistema?
Depende do caminho, do número de automações e de haver ou não caixa de atendimento própria. A operação tem custo à parte, porque a Meta cobra por mensagem entregue. A calculadora de projetos dá uma faixa inicial.