Resumo: Configure um endpoint HTTPS público, registre-o como seu webhook do Whapi.Cloud, e seu servidor receberá cada evento do WhatsApp como um POST JSON. Verifique o campo type para rotear a lógica, depois chame POST /messages/text com to e body para responder. Esse loop de dois passos — receber evento, enviar reação — é toda integração neste guia. Comece com o roteamento de mensagens de texto; adicione ramificações condicionais conforme seu caso de uso crescer.
O Princípio Central: Evento → Reação
A integração da API do WhatsApp é orientada a eventos, não é um SDK de mensagens. Algo acontece no WhatsApp, o Whapi.Cloud notifica seu servidor via webhook, seu código decide a reação e a API a executa.
A sequência é fixa. Um usuário envia uma mensagem para o seu número do WhatsApp. O Whapi.Cloud captura esse evento e imediatamente dispara um HTTP POST para a URL do seu webhook com um payload JSON — quem enviou, que tipo de mensagem, o conteúdo. Seu servidor lê o payload, aplica a lógica de negócio e chama a REST API do Whapi.Cloud para enviar uma resposta, atualizar um registro de CRM ou acionar uma ação downstream. O loop se repete a cada evento subsequente.
Seu código nunca faz polling — o Whapi.Cloud envia cada evento do WhatsApp para o seu webhook no momento em que acontece. A única pergunta que sua lógica de negócio responde: dado este evento, o que acontece a seguir?
Confirmações de entrega, reações com emoji, toques em botões, mudanças de membros em grupos e eventos de chamadas — todos disparam webhooks. O texto de entrada é um tipo de evento entre oito. Mapear a taxonomia completa para decisões de negócio é o que separa uma integração funcional de uma incompleta. Desenvolvedores familiarizados com webhooks do Stripe ou callbacks do Twilio reconhecerão o padrão imediatamente.
Por Que Usar um Gateway em Vez da API Oficial?
O Whapi.Cloud se conecta via sockets de sessão web. Escaneie um QR code e envie sua primeira mensagem em minutos — sem verificação da Meta nem aprovação de templates.
A plataforma oficial do WhatsApp Business exige verificação empresarial, integração com BSP e templates de mensagens pré-aprovados antes de enviar uma única mensagem proativa. O Whapi.Cloud cobra uma assinatura fixa sem taxas por conversa. Mais de 3.300 equipes de desenvolvimento o utilizam em produção em vários países.
Uma desvantagem real: o Whapi.Cloud não é oficialmente sancionado pela Meta, o que importa para setores regulados que exigem documentação formal de conformidade. Para e-commerce, bots de suporte, ferramentas de RH e sincronização de CRM — não é uma restrição bloqueante. O guia de primeiros passos cobre o que você precisa antes da sua primeira chamada de API.
A Taxonomia Completa de Eventos do WhatsApp
Cada categoria de eventos corresponde a uma classe distinta de decisões de negócio que sua lógica de roteamento deve tratar — e a taxonomia completa é mais ampla do que a maioria dos desenvolvedores espera antes de sua primeira integração.
Cada evento que o Whapi.Cloud entrega compartilha a mesma estrutura externa: um POST JSON para o seu webhook com um campo type que identifica a categoria do evento. Seu handler ramifica por type primeiro, depois extrai os subcampos específicos daquela categoria.
| Categoria de Evento | Tipos de Eventos Específicos | Reação de Negócio Típica |
|---|---|---|
| Mensagem de entrada | text, image, audio, video, document, sticker, location, contact card | Rotear para handler IA, encaminhar ao CRM, resposta automática, marcar conversa |
| Interação interativa | button reply, quick reply, list selection, template response | Avançar máquina de estados da conversa, confirmar pedido, acionar ação de backend |
| Reação com emoji | reaction added, reaction removed | Registrar pontuação de sentimento, acionar acompanhamento, atualizar métrica de satisfação |
| Status da mensagem | sent, delivered, read, played (voice note) | Atualizar campo de entrega no CRM, cancelar timer de reengajamento, acionar sequência de acompanhamento |
| Evento de chamada | incoming call initiated, call missed, call rejected | Registrar chamada perdida, enviar mensagem automatizada de solicitação de callback |
| Evento de grupo | participant joined, participant left, admin changed, group created/archived | Atualizar lista de membros, enviar mensagem de boas-vindas, sincronizar com sistema de RH |
| Evento de label | label applied to chat, label removed | Segmentar contato no CRM, acionar campanha, atualizar estágio do pipeline |
| Evento de canal | follower joined channel, channel update published | Enviar confirmação ao inscrito, sincronizar analytics, acionar fluxo de notificação |
A regra de roteamento é consistente em todas as linhas: leia o campo type, ramifique para o handler correspondente, extraia os subcampos relevantes para aquele tipo. Uma mensagem "image" precisa de um handler diferente de uma interação "button_reply" — ambos chegam como requisições POST para a mesma URL do webhook, mas a estrutura do payload e sua lógica de negócio diferem completamente.
Caminhos para Integração
Seja escrevendo código de servidor ou configurando uma ferramenta de workflow visual, toda integração segue o mesmo loop evento→reação — apenas as ferramentas mudam.
| Abordagem | Requisito Técnico | Tempo até a Primeira Mensagem | Ideal Para |
|---|---|---|---|
| REST API (Python / Node.js / PHP) | Cliente HTTP, qualquer backend com URL pública | ~30 minutos | Lógica de negócio personalizada, chatbots IA, conectores CRM |
| Make (módulo nativo do Whapi.Cloud) | Somente conta no Make | ~10 minutos | Não-desenvolvedores, equipes de automação de marketing |
| n8n (self-hosted ou nuvem) | Instância n8n (Docker ou nuvem) | ~15 minutos | Equipes técnicas que querem controle de workflow self-hosted |
| cURL / Postman | Nenhum além da própria ferramenta | ~5 minutos | Testar endpoints, prova de conceito |
Os usuários de Make e n8n configuram um nó disparador de webhook que recebe o mesmo payload JSON que um backend personalizado receberia. Os nós então leem os campos do evento e chamam o endpoint de envio do Whapi.Cloud como reação. O modelo evento→reação não muda; a lógica de negócio fica em um canvas visual em vez de código.
Configuração do Webhook: O Lado Receptor
A configuração do webhook no Whapi.Cloud requer três entradas: a URL do seu endpoint, os tipos de eventos que você quer receber e um segredo opcional para verificação de requisições. O endpoint deve ser acessível publicamente via HTTPS.
Configure o webhook nas configurações do seu canal no Whapi.Cloud. Uma vez salvo, o Whapi.Cloud começa a encaminhar os eventos do WhatsApp para sua URL como requisições HTTP POST com um corpo JSON. Os eventos chegam em tempo real — tipicamente em algumas centenas de milissegundos após a ação no WhatsApp. Não há intervalo de polling a configurar e nenhuma conexão persistente a manter do seu lado. A referência completa do formato do payload do webhook documenta todos os campos que seu handler precisará processar.
Durante o desenvolvimento, o ngrok expõe uma porta local a uma URL HTTPS pública. Defina essa URL como seu webhook temporário, execute seu handler localmente e inspecione os payloads ao vivo antes de se comprometer com um deploy em servidor.
Retorne HTTP 200 antes de processar. Isso não é opcional. O Whapi.Cloud tenta reenviar a entrega se o seu endpoint não responder dentro do tempo limite. Confirme a requisição imediatamente, envie o payload para uma thread em segundo plano ou fila de tarefas, e processe de forma assíncrona. Misturar confirmação e processamento no mesmo caminho síncrono causa eventos duplicados quando sua lógica é lenta.
Do Webhook à Resposta: Um Exemplo de Código Funcional
Qualquer linguagem com cliente HTTP — Python, Node.js, PHP, Go — integra da mesma forma. Sem SDK proprietário, sem wrapper para instalar. O handler abaixo roteia mensagens de entrada e envia respostas via POST /messages/text.
from flask import Flask, request, jsonify
import requests
import threading
app = Flask(__name__)
WHAPI_TOKEN = "your_channel_token" # from panel.whapi.cloud/dashboard
WHAPI_URL = "https://gate.whapi.cloud/messages/text"
def send_reply(to: str, body: str) -> None:
# Calls sendMessageText — required: to (chat ID), body (message text)
requests.post(
WHAPI_URL,
headers={"Authorization": f"Bearer {WHAPI_TOKEN}"},
json={"to": to, "body": body}
)
def process_event(data: dict) -> None:
for msg in data.get("messages", []):
if msg.get("from_me"):
continue # skip outbound confirmations
sender = msg.get("chat_id") # e.g. "[email protected]"
msg_type = msg.get("type", "")
if msg_type == "text":
text = msg.get("text", {}).get("body", "").lower()
if any(w in text for w in ["hello", "hi", "hey"]):
send_reply(sender, "Hey! How can I help you today?")
elif "price" in text or "pricing" in text:
send_reply(sender, "Check our pricing: https://whapi.cloud/price")
elif "order" in text:
send_reply(sender, "Please share your order number and we'll check its status.")
else:
send_reply(sender, "Thanks! Our team will get back to you shortly.")
elif msg_type == "image":
send_reply(sender, "Got your image — our team will review it.")
elif msg_type == "button_reply":
btn_id = msg.get("button_reply", {}).get("id", "")
send_reply(sender, f"You selected: {btn_id}. Processing your request...")
elif msg_type == "reaction":
# Reactions carry sentiment data — log them, don't reply by default
emoji = msg.get("reaction", {}).get("text", "")
msg_id = msg.get("reaction", {}).get("msg_id", "")
print(f"Reaction {emoji} on message {msg_id} from {sender}")
@app.route("/webhook", methods=["POST"])
def webhook():
data = request.get_json()
# Acknowledge immediately — never block on processing
threading.Thread(target=process_event, args=(data,)).start()
return jsonify({"status": "ok"}), 200
if __name__ == "__main__":
app.run(port=5000)Quatro ramificações de roteamento são visíveis: cumprimentar com palavras-chave de saudação, oferecer preços com intenção de compra, solicitar esclarecimento em consultas de pedidos, registrar reações para sentimento. A mesma estrutura condicional escala para centenas de ramificações — ou substitua toda a cadeia if/elif por uma chamada de LLM. O handler do webhook em si permanece igual. Para os passos de deploy em produção com filas Celery, veja o guia do bot WhatsApp em Python.
Em um deploy real, substitua a thread em segundo plano por uma fila de tarefas (Celery, RQ, ou um serviço de fila em nuvem) para garantias de retry e escalabilidade horizontal. A confirmação do webhook e a lógica de negócio devem permanecer separadas — essa fronteira é a decisão arquitetural fundamental em toda integração em escala.
Tipos de Mensagens Interativas como Entradas de Eventos Distintos
Respostas de botões, seleções de lista e respostas rápidas são tipos de eventos distintos com estruturas de payload separadas. Cada um requer sua própria ramificação de roteamento no seu código.
Quando um usuário toca em um botão em uma mensagem interativa do WhatsApp, o Whapi.Cloud entrega um evento button_reply. O payload contém o ID do botão que você atribuiu ao construir a mensagem, não o texto visível da etiqueta. Sua lógica de roteamento verifica o ID, tornando os fluxos interativos determinísticos — nenhuma formulação do usuário aciona acidentalmente a ramificação errada.
Considerações típicas:
-
button_reply: Extraia
button_reply.id— o ID programático que você definiu ao construir a mensagem de botão. Roteie para o handler correspondente sem nenhuma análise de texto. -
list_reply: Extraia tanto
list_reply.idquantolist_reply.title— o ID conduz a lógica, o título é útil nas mensagens de confirmação enviadas de volta ao usuário. -
reaction: Extraia
reaction.text(o caractere emoji) ereaction.msg_id(para qual mensagem foi reagido). Mapeie para registro de sentimento ou use como sinal leve de satisfação sem interromper a conversa. -
Atualizações de status: Cada evento de status carrega
statuses[].statuscomo"sent","delivered"ou"read". Atualize seu campo de CRM, cancele um timer de reengajamento ou inicie uma sequência de acompanhamento com base nas transições de status.
As confirmações de leitura são dados comportamentais, não apenas registros de entrega. Um prospect que lê sua mensagem de preços às 21h mas não responde está dizendo algo ao seu CRM. Roteie os eventos de status para sua camada de dados — são sinais para agir, não ruído a filtrar.
Arquitetura de Chatbot IA no WhatsApp
Um LLM entre o webhook e a resposta da API transforma um número do WhatsApp em um agente IA. A arquitetura tem três camadas. A camada intermediária é onde a maioria das equipes toma a decisão que determina se o chatbot se sente coerente ou quebrado.
Camada um: o Whapi.Cloud entrega a mensagem de entrada para o seu webhook. Camada dois: seu servidor recupera o histórico de conversa do armazenamento persistente, acrescenta a nova mensagem, chama a API do LLM com o contexto completo da conversa e envia a resposta de volta via Whapi.Cloud. Camada três: o provedor de LLM — OpenAI, Anthropic ou Gemini — recebe uma janela de contexto preparada, não o payload bruto do webhook.
A camada que a maioria das equipes subestima é o armazenamento. As conversas têm estado — persista o histórico chaveado por chat_id, limite às últimas 15-20 rodadas antes de cada chamada ao LLM. Sem armazenamento persistente, seu IA lê cada mensagem como se a conversa tivesse acabado de começar.
A transferência para um agente humano é o segundo padrão crítico: nenhuma IA resolve 100% das conversas corretamente. Construa um gatilho de escalonamento explícito — uma correspondência de palavra-chave, um limiar de pontuação de confiança ou um limite de rodadas de conversa — que roteie o chat para um agente humano. Marque a conversa no seu CRM, notifique o agente e, opcionalmente, envie ao usuário uma mensagem de confirmação. Seu webhook continua entregando mensagens durante a transferência; a lógica de roteamento simplesmente muda o handler de IA para fila humana.
O repositório do GitHub do Whapi.Cloud inclui templates de bots em Python e Node.js que implementam esse padrão de três camadas com armazenamento, roteamento e lógica de chamada de API já escritos. Clone, configure seu token e credenciais de LLM, e execute.
Casos de Uso Empresariais em Diversos Setores
O loop evento→reação se aplica de forma idêntica em todos os setores onde o WhatsApp é um canal de comunicação ativo — apenas a lógica de negócio dentro muda.
-
E-commerce: Pedido confirmado no evento de compra, lembrete de carrinho abandonado no timeout de inatividade, rastreamento de confirmação de leitura para medir a taxa de entrega-para-resposta.
-
Clínicas de saúde usam menus de resposta de botão para formulários de admissão, disparam lembretes de consulta 24h e 2h antes do horário, e enviam um acompanhamento de não comparecimento quando chega uma confirmação de leitura sem resposta.
-
Imóveis: Uma consulta de entrada dispara uma lista curta por orçamento e localização via respostas de botão, leads qualificados roteados para a fila do agente com um registro de CRM criado automaticamente no mesmo evento.
-
Para RH e operações internas, escalas de turno são enviadas como mensagens em grupo, a confirmação do funcionário é rastreada via status de leitura e documentos de onboarding são entregues automaticamente a partir de eventos de gatilho do sistema de RH.
Considerações para Produção
Quatro decisões determinam se uma integração aguenta o tráfego real. Confirme antes de processar e deduplique pelo ID da mensagem — pule qualquer um e você processará alguns eventos duas vezes.
-
Confirmar antes de processar. Retorne HTTP 200 imediatamente. Mova a lógica de negócio para uma thread em segundo plano ou fila de tarefas. O Whapi.Cloud tenta reenviar no timeout — misturar confirmação e processamento no mesmo caminho síncrono produz eventos duplicados.
-
Os IDs de mensagem são sua chave de deduplicação. Armazene cada ID processado com um TTL curto (Redis funciona bem) e pule o reprocessamento quando o mesmo evento chegar duas vezes. Condições de rede ocasionalmente entregam duplicatas mesmo de infraestrutura confiável.
-
Controle o ritmo de envios em números novos. Os canais de produção do Whapi.Cloud não têm limites rígidos de taxa de API. O risco é a detecção de spam do lado do servidor do WhatsApp — picos repentinos de volume em números recém-ativados atraem penalidades. Implemente uma fila de envio com delays modestos entre mensagens ao fazer broadcast para listas grandes a partir de um número novo.
-
Sessões de chatbot IA precisam de três configurações desde o primeiro dia: histórico chaveado por
chat_id, limite de contexto para as últimas 15-20 rodadas antes de cada chamada ao LLM, e limpeza de sessões expiradas após uma janela de inatividade configurável. Pule qualquer uma e você depurará erros de overflow de contexto ou estado obsoleto em produção.
A infraestrutura do Whapi.Cloud lida com atualizações do protocolo do WhatsApp automaticamente — sua integração não quebra quando o WhatsApp lança uma nova versão do cliente. Para orientação sobre aquecimento de número e padrões de envio seguro, o guia de mensagens seguras cobre os comportamentos que realmente acionam as penalidades do WhatsApp.
O Que Dizem as Equipes que Desenvolvem com o Whapi.Cloud
"O Whapi.Cloud se tornou uma parte fundamental da nossa comunicação com clientes. Automatizamos atualizações de produtos, notificações de pedidos e mensagens de suporte sem precisar de templates ou aprovações da Meta."
— Oscar T., CTO
"Conectamos o WhatsApp aos nossos fluxos de trabalho usando n8n em apenas alguns minutos. Sem código, sem complicações — tudo funcionou na primeira tentativa."
— Martin P., Desenvolvedor
"Tudo é simples, intuitivo e fácil de navegar. A documentação é clara e todas as informações que preciso estão bem na tela."
— Roberto K., Desenvolvedor Web
Os desenvolvedores escrevem a lógica de negócio; o Whapi.Cloud cuida da entrega pelo WhatsApp. Essa separação é o que torna a arquitetura escalável — seu código de roteamento roda de forma idêntica em um VPS de $5 ou em um cluster conteinerizado, porque a complexidade do protocolo fica no lado do gateway. Mapeie cada evento de negócio para uma reação no WhatsApp: essa é a arquitetura completa.
