API de WhatsApp híbrida: como combinar a Cloud API e uma API não oficial
Entenda a arquitetura híbrida de WhatsApp: o cliente integra a Cloud API da Meta e a GoZAP como duas pontas separadas, com custos e eventos distintos.
O que significa usar uma arquitetura híbrida?
“Híbrida” descreve como o cliente compõe seu sistema: um serviço próprio tem duas integrações distintas, uma com a WhatsApp Business Platform da Meta e outra com a API GoZAP. O sistema escolhe qual conexão atende cada fluxo. São duas pontas independentes na arquitetura.
A Meta descreve a WhatsApp Business Platform e a Cloud API como plataforma empresarial de mensagens. A GoZAP oferece dois modos nativos: Web, por QR ou código de pareamento, e Mobile, com registro pelo número diretamente no socket mobile, sem celular nem emulador. No modo Web, a API usa whatsmeow, uma implementação multidevice do WhatsApp Web. O envio pela Cloud API ocorre na integração direta entre a aplicação do cliente e a Meta.
Como a coexistência da GoZAP se encaixa?
No modo Web, a GoZAP tem a rota POST /device/coexistence/connect, que recebe o QR e a origem do provedor de tecnologia e vincula um companion à conta WhatsApp Business móvel. Esse QR é o exibido pelo provedor durante Embedded Signup. É uma conexão de coexistência; não transforma a GoZAP em cliente de envio pela Graph/Cloud API.
O endpoint recebe os campos qr e origin e é autenticado como parte da API da instância. Para parear pelo modo Web por outros caminhos, a API também oferece POST /device/pair/qr e POST /device/pair/code.
POST /device/coexistence/connect Content-Type: application/json
{“qr”:“QR_DA_COEXISTENCIA”,“origin”:“ORIGEM_DO_PROVEDOR”}
Na arquitetura híbrida, o próprio cliente mantém sua credencial e chamada oficial à Meta. Nesse fluxo do modo Web, a rota GoZAP vincula o companion indicado pelo QR. A GoZAP também oferece o modo Mobile, que registra a conta pelo número; veja o guia do modo Mobile sem celular. As duas integrações têm autenticação, mensagens, eventos e cobrança separados.
Como separar responsabilidades e eventos?
Registre quais casos de uso passam pela Cloud API e quais passam pela GoZAP. Encaminhe cada operação por uma integração definida, sem duplicar automaticamente a mesma ação nas duas pontas.
A aplicação que escolhe a Cloud API faz a chamada oficial à Meta e processa os eventos correspondentes. A política de cobrança também é da Meta e depende da categoria e do mercado da mensagem.
O pareamento por QR ou código inicia o modo Web. A GoZAP dispõe ainda de webhooks por instância em /webhook e eventos SSE em /sse; esses eventos pertencem ao caminho GoZAP.
Identifique a plataforma que processou cada envio e acompanhe a resposta correspondente. Uma resposta HTTP ou confirmação de transporte não equivale a entrega ou leitura da mensagem.
Aplicação do cliente → Cloud API da Meta Aplicação do cliente → API GoZAP → modo Web ou Mobile
O diagrama representa uma divisão de chamadas feita pelo sistema do cliente. Não há compartilhamento automático de credenciais ou sincronização implícita entre as plataformas.
Como organizar o roteamento dos fluxos?
Registre se o fluxo usa a plataforma oficial ou a API GoZAP e identifique o sistema que inicia cada envio. Na conexão Meta, considere as categorias marketing, utilidade, autenticação e serviço. Na conexão GoZAP, mapeie o recurso usado, como envio de texto ou mídia.
Mantenha os eventos Cloud API e GoZAP em caminhos diferentes na aplicação. Para GoZAP, a instância dispõe de webhooks configuráveis em /webhook e eventos transmitidos por /sse. Seu consumidor pode aplicar regras próprias de registro e encaminhamento a cada origem.
Registre qual conexão iniciou o envio e qual endpoint recebeu o evento. Assim a equipe consegue distinguir um erro da chamada Meta de uma falha no caminho GoZAP, sem atribuir a uma plataforma a resposta emitida pela outra.
O desenho de roteamento também define as responsabilidades de suporte e cobrança: uma operação iniciada pela Cloud API segue a conta e as categorias da Meta; uma operação GoZAP usa a instância e a assinatura GoZAP.
Como funciona a cobrança de cada ponta?
A Meta lista quatro categorias de mensagens na sua página oficial de preços: marketing, utilidade, autenticação e serviço. Desde 1º de julho de 2025, a cobrança descrita é por mensagem empresarial entregue, segundo categoria e mercado. A página registra mudanças com vigência a partir de 1º de outubro de 2026. A tarifa aplicável depende da categoria e do mercado da conta.
A GoZAP usa assinatura mensal por plano e quantidade de instâncias, sem tarifa por mensagem nesse modelo. Preços vigentes em 5 de outubro de 2026:
| Faixa da assinatura GoZAP | Valor mensal |
|---|---|
| 1 instância | R$ 27,00 |
| 2 a 10 instâncias | R$ 25,00 por instância |
| Starter, até 100 instâncias | R$ 200,00 |
| Enterprise, até 300 instâncias | R$ 449,99 |
Essas cobranças não se misturam: a aplicação administra a integração Cloud API diretamente com a Meta e paga a assinatura da GoZAP separadamente.
Na assinatura GoZAP, cinco instâncias na faixa de 2 a 10 custam R$ 125,00 por mês.
Quando não escolher a GoZAP
Se todos os envios precisam ocorrer pela Cloud API oficial, implemente essa integração diretamente com a Meta. A GoZAP conecta pelos modos Web e Mobile, ambos fora da API oficial da Meta, e não substitui esse caminho de envio. Se sua regra interna proíbe APIs não oficiais, use apenas plataformas oficiais.
Se a equipe precisa instalar e operar o servidor da API na própria infraestrutura, o serviço hospedado da GoZAP não atende a esse requisito. Se o projeto exige SLA contratual, região específica de hospedagem ou política de retenção detalhada, exija esses termos no contrato antes de selecionar o serviço.
Para outros caminhos de integração, veja a migração de sessão WhatsApp, a configuração de webhooks GoZAP no n8n e a integração de Chatwoot com GoZAP.