O pedido chega na mesa do time de tecnologia mais ou menos assim: “precisamos que o sistema mande WhatsApp para o cliente quando o status mudar, e que as respostas apareçam para o comercial”. Simples na frase, mas a primeira decisão já define semanas de trabalho. Integrar direto com a API da Meta ou com a API de uma plataforma que já cuida do atendimento? Este guia de API do WhatsApp para desenvolvedores mostra as duas rotas, o que cada uma exige e onde os projetos costumam travar.
A resposta direta: a API oficial do WhatsApp é a Cloud API da Meta, acessada pela Graph API, com autenticação por token e eventos entregues por webhook. Integrar direto com ela dá controle total, mas o seu time passa a construir tudo o que fica em volta: inbox, filas, histórico, usuários. Integrar com a API de uma plataforma de atendimento reduz esse trabalho ao que é específico do seu negócio, como criar contatos e disparar mensagens a partir do seu CRM ou ERP.
As peças da API do WhatsApp para desenvolvedores: o vocabulário básico
Antes de escrever código, vale alinhar o vocabulário com quem vai cuidar da conta na Meta. Nós explicamos o lado de negócio no post sobre o que é a WhatsApp Cloud API. Do lado técnico, as peças são estas:
| Peça | O que é | Por que importa para o dev |
|---|---|---|
| Portfólio empresarial | A “conta da empresa” na Meta | É onde ficam usuários, apps e permissões |
| WABA | Conta do WhatsApp Business dentro do portfólio | Agrupa números e modelos de mensagem |
| Phone number ID | Identificador de cada número na API | Vai na URL de envio de mensagens |
| App da Meta | Aplicativo criado no painel de desenvolvedores | Recebe o webhook e gera os tokens |
| Token de acesso | Credencial enviada no cabeçalho das chamadas | Sem token de longa duração, a integração cai |
| Modelos de mensagem | Textos aprovados pela Meta | Únicos permitidos fora da janela de 24h |
| Webhook | Endpoint seu que recebe eventos | Mensagens recebidas e status de envio chegam por aqui |
Rota 1: integrar direto com a Cloud API da Meta
Na integração direta, o seu sistema conversa com a Graph API. O envio é uma requisição HTTP para o endpoint de mensagens do número, com o token no cabeçalho e um JSON dizendo destinatário, tipo de mensagem e conteúdo. O recebimento é o caminho inverso: a Meta chama o seu webhook.
Webhook: o que a documentação exige
Segundo a documentação de webhooks da Meta, ao configurar o endpoint a Meta envia um GET com os parâmetros hub.mode, hub.challenge e hub.verify_token. O seu servidor confere se o token bate com o que você cadastrou e devolve o challenge. O endpoint precisa de HTTPS com certificado válido; certificado autoassinado não é aceito.
Depois da verificação, cada evento chega por POST com um JSON. A Meta assina os payloads com SHA256 no cabeçalho X-Hub-Signature-256, usando o App Secret. Validar essa assinatura não é obrigatório, mas é a forma de garantir que o evento veio mesmo da Meta.
Status de mensagem e reenvios
O campo messages do webhook traz tanto mensagens recebidas quanto o status das mensagens enviadas: sent, delivered, read e failed, entre outros. Um detalhe que pega muita gente: de acordo com o guia de webhooks do WhatsApp, se o seu endpoint não responder 200, a Meta tenta de novo com frequência decrescente por até 7 dias. Isso gera notificações duplicadas. O seu handler precisa ser idempotente.
Responda 200 rápido e processe depois. Webhook que faz consulta pesada antes de responder vira fila de reenvio e evento duplicado.
O que você vai construir sozinho nessa rota
- Tela para atendentes lerem e responderem conversas, com histórico.
- Controle de usuários, permissões e distribuição de conversas.
- Armazenamento de mídias recebidas (a API entrega um ID, não o arquivo pronto).
- Gestão de modelos de mensagem e de quem pode enviar cada um.
- Controle da janela de 24 horas por contato.
- Respeito ao limite de mensagens do número. Veja como funcionam os degraus em limite de mensagens da WhatsApp API.
Para produtos que vão vender o próprio atendimento, ou casos muito específicos, essa rota faz sentido. Para a maioria das empresas que só precisa integrar o WhatsApp a um sistema que já existe, é reinventar a roda.
Rota 2: usar a API de uma plataforma de atendimento
Aqui, a plataforma já está conectada à Cloud API, já recebe os webhooks da Meta e já oferece inbox, filas e relatórios. O seu sistema conversa com a API da plataforma, não com a Meta. O escopo do desenvolvedor encolhe para o que é do negócio:
- Criar ou atualizar o contato quando ele se cadastra no seu sistema.
- Buscar um contato para saber se ele já existe antes de criar outro.
- Enviar uma mensagem quando acontece um evento (pedido, vencimento, agendamento).
- Marcar o contato com etiquetas para segmentar campanhas e atendimento.
A conversa que nasce dessa mensagem fica na plataforma, onde a equipe responde. O seu código não precisa saber nada de atendente, fila ou histórico.
API do WhatsApp para desenvolvedores: comparação das duas rotas
| Critério | Cloud API direta | API de plataforma |
|---|---|---|
| Quem recebe o webhook da Meta | Seu servidor | A plataforma |
| Interface para atendentes | Você constrói | Pronta |
| Autenticação | Token da Meta (app e usuário do sistema) | Token da plataforma |
| Escopo de código | Envio, recebimento, mídia, estado da conversa | Eventos do seu negócio |
| Manutenção quando a Meta muda algo | Sua | Da plataforma |
| Controle sobre cada detalhe | Total | Limitado ao que a API expõe |
| Melhor para | Produtos de mensageria, casos muito específicos | Integrar CRM, ERP, e-commerce ao atendimento |
Passo a passo para uma integração sem surpresas
- Mapeie os eventos. Liste o que, no seu sistema, deve gerar mensagem: cadastro, pedido, vencimento. Para cada um, defina se é modelo aprovado (fora da janela) ou resposta dentro de conversa.
- Peça os modelos com antecedência. A aprovação de modelos depende da Meta. Não deixe para a semana do lançamento.
- Padronize telefones na origem. Grave sempre código do país, DDD e número, só dígitos. A Meta recomenda enviar com o sinal de mais e o código do país; sem isso, o envio pode falhar ou ir para outro número.
- Use um token por sistema integrado. Fica fácil revogar o acesso de um sistema sem derrubar os outros.
- Faça busca antes de criar contato. Evita duplicados que depois atrapalham campanhas e relatórios.
- Trate erros por código. Número inválido, fora da janela e limite atingido pedem ações diferentes. Registre o erro com o ID do contato.
- Teste em ambiente controlado. Use números da equipe antes de abrir para a base real.
- Documente para o próximo dev. Quais endpoints, quais tokens, quem é dono da conta na Meta.
Se o destino da integração é um CRM, o nosso guia de integração da API oficial com CRMs ajuda a desenhar o que sincronizar em cada direção.
Como fazer isso no ClikChat
O ClikChat é a rota 2. O número fica conectado pela API oficial (WABA) ou por QR Code, e a plataforma cuida do webhook da Meta, do inbox multicanal, dos departamentos, das etiquetas e dos relatórios.
Para o desenvolvedor, a API do ClikChat funciona com tokens gerados no painel e documentação Swagger, onde dá para ver os endpoints e testar as chamadas. Com ela, o seu CRM ou ERP cria e busca contatos, envia mensagens e trabalha com etiquetas. Consulte o Swagger da sua conta para os parâmetros exatos de cada recurso.
Há ainda dois pontos de integração que não exigem que o seu sistema chame o ClikChat:
- Bloco de integração HTTP no ChatBot Inteligente. O fluxo, montado no construtor visual, faz uma requisição para a sua API no meio da conversa, por exemplo para consultar um pedido pelo número informado pelo cliente.
- WhatsApp Flows com webhook. Nos formulários nativos da Meta montados no ClikChat (só API oficial), as respostas podem ser enviadas para um webhook seu, com até 10 tentativas de entrega.
Perguntas frequentes
A API do WhatsApp é gratuita para desenvolvedores?
As mensagens enviadas pela API oficial são cobradas diretamente pela Meta, conforme regras de categoria e país. Consulte a tabela oficial de preços antes de estimar custo. Plataformas de atendimento cobram a assinatura delas à parte.
Preciso de servidor próprio para usar a API do WhatsApp?
Na integração direta, sim: você precisa de um endpoint HTTPS com certificado válido para o webhook. Usando a API de uma plataforma, quem recebe o webhook da Meta é a plataforma, e o seu sistema só faz chamadas de saída.
Qual a diferença entre Cloud API e API On-Premises?
A Cloud API é hospedada pela Meta. A On-Premises era instalada na infraestrutura da própria empresa e foi descontinuada pela Meta. Hoje, integrar com a API oficial significa integrar com a Cloud API.
Consigo enviar qualquer mensagem pela API a qualquer hora?
Não. Mensagem livre só dentro da janela de 24 horas aberta pelo cliente. Fora dela, apenas modelos aprovados pela Meta.
Como evitar mensagens duplicadas no webhook?
Guarde o ID de cada evento processado e ignore repetições. A Meta reenvia quando não recebe resposta 200, então duplicidade é esperada e precisa ser tratada.
A API do ClikChat substitui a integração direta com a Meta?
Para integrar sistemas da empresa ao atendimento, na maioria dos casos sim, porque a plataforma já cuida da conexão oficial. Se você precisa de algum recurso da Meta que a API da plataforma não expõe, a integração direta continua sendo o caminho.
Conclusão
Escolher a rota certa é a decisão mais importante da API do WhatsApp para desenvolvedores. Integração direta com a Cloud API dá controle total e muito trabalho em volta. A API de uma plataforma deixa o seu time focado nos eventos do negócio. Se quiser testar a segunda rota com tokens, Swagger e inbox pronto para a equipe, teste o ClikChat grátis por 3 dias.