Como migrar de API de WhatsApp: checklist para planejar a troca
Planeje a troca de API WhatsApp com inventário, QR ou código, rotas de eventos e corte controlado. Sessão e histórico são escopos distintos.
O que entra no plano de migração?
Uma troca de API envolve a sessão de WhatsApp, a configuração dos sistemas que enviam mensagens e recebem eventos e os dados mantidos pela aplicação. Separe esses elementos antes de alterar endpoints. Assim você sabe o que precisa ser migrado, o que precisa ser reconfigurado e o que permanece no sistema de origem.
A GoZAP conecta nos modos Web (QR ou código de pareamento) e Mobile (registro pelo número, sem celular nem emulador). Há também o session-migrator: a ferramenta atua sobre uma sessão autenticada do WhatsApp Web no navegador e a transfere para uma instância GoZAP em modo migration. Ela atende esse cenário de sessão; não é um conversor de credenciais ou configurações de qualquer API concorrente.
Como preparar origem, destino e consumidores?
Liste cada endpoint, tipo de mensagem, rotina agendada, webhook e consumidor. Anote também os responsáveis pelas credenciais e os eventos que acionam fluxos de negócio.
Identifique contatos, filas e registros que já ficam na sua aplicação. Registre separadamente o histórico que depende da API ou da sessão. O pareamento conecta uma sessão; não é uma promessa de copiar mensagens e mídias históricas.
Crie a instância e configure os consumidores para os recursos necessários. As rotas GoZAP de envio incluem /send/text e /send/media; a API também tem operações de grupos, contatos e status.
Antes do corte, registre uma correspondência entre a função antiga e o recurso novo. Por exemplo: envio textual para /send/text, envio de mídia para /send/media, consulta de webhooks para GET /webhook e leitura de erros para GET /webhook/errors. Essa matriz evita trocar uma URL sem atualizar o contrato usado pela aplicação.
Quais rotas entram na troca?
| Necessidade | Rota GoZAP | O que faz |
|---|---|---|
| Parear por QR | POST /device/pair/qr |
Inicia o pareamento por QR no modo Web. |
| Parear por código | POST /device/pair/code |
Solicita confirmação de pareamento por código no modo Web. |
| Enviar texto ou mídia | POST /send/text, POST /send/media |
Envia texto ou mídia usando a instância GoZAP. |
| Administrar webhooks | GET /webhook, POST /webhook |
Consulta e atualiza a configuração de webhooks da instância. |
| Consultar erros de webhook | GET /webhook/errors |
Lista erros de entrega de webhook registrados para a instância. |
| Receber eventos em fluxo | GET /sse |
Abre a conexão de eventos SSE da instância. |
| Administrar o proxy da instância | GET, POST ou DELETE /instance/proxy |
Consulta, configura ou remove o proxy associado à instância. |
| Usar ferramentas MCP | /mcp |
Expõe o transporte HTTP/SSE e RPC do serviço MCP, protegido por JWT Bearer. |
As rotas de envio e administração exigem autenticação conforme a API. As rotas e métodos acima permitem atualizar clientes e integrações sem depender de payload presumido. Para pareamento, o procedimento concreto é:
POST /device/pair/qr POST /device/pair/code
Como parear e mover a sessão?
No modo Web, escolha POST /device/pair/qr para o fluxo com QR ou POST /device/pair/code para o fluxo com código. Complete a aprovação do dispositivo vinculado no WhatsApp e acompanhe o estado da instância.
Se não há sessão do navegador para migrar, o modo Mobile registra a conta diretamente pelo número, sem celular nem emulador. Veja o guia do modo Mobile sem celular.
Quando a sessão autenticada estiver no WhatsApp Web do navegador, use o session-migrator para transferi-la para a instância GoZAP em modo migration. A ferramenta trabalha com essa sessão local; configuração e dados exclusivos de um servidor Evolution, WAHA ou WPPConnect exigem tratamento próprio.
Cadastre destinos na configuração /webhook ou consuma /sse, conforme o fluxo da aplicação. Direcione os consumidores para as rotas GoZAP correspondentes e mantenha suas credenciais sob o controle dos responsáveis pelo sistema.
O session-migrator transfere a sessão autenticada do navegador para a instância GoZAP. Planeje mensagens e mídias históricas como um fluxo de dados separado da migração de sessão e mantenha esses registros conforme a política da sua aplicação.
Uma migração fica mais clara quando sessão, rotas da aplicação e histórico são tratados como três itens separados.
Como organizar a janela de corte?
Faça um envio de texto e um de mídia, valide o recebimento de eventos e percorra os fluxos de grupos ou contatos que sua aplicação usa. Confira o resultado no sistema consumidor; resposta HTTP e ACK de transporte não comprovam entrega ou leitura pelo destinatário.
Atualize endpoints e webhooks na janela acordada com as equipes usuárias. Acompanhe erros, eventos recebidos e operações pendentes. Registre o horário da alteração e quem executou cada etapa.
Compare os fluxos ativos com o inventário e retire credenciais antigas quando deixarem de ser necessárias. Documente os registros que ficaram na origem e o estado final dos consumidores.
O pareamento, as chamadas da API e a entrega ao destinatário são etapas diferentes. A troca de endpoint não deve ser usada como evidência de que uma mensagem chegou ao WhatsApp ou de que uma conversa histórica foi copiada.
Quanto custa a assinatura GoZAP?
Preços GoZAP em 5 de outubro de 2026. A cobrança mensal é por plano e quantidade de instâncias, sem tarifa por mensagem nesse modelo.
| Faixa | 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 |
Para cinco instâncias, o cálculo da faixa de 2 a 10 é R$ 125,00 por mês. O valor da assinatura não representa uma tarifa por mensagem.
Quando não escolher a GoZAP
Se o sistema precisa operar exclusivamente pela Cloud API oficial, conecte-o diretamente à plataforma da Meta. A GoZAP oferece os modos Web e Mobile, e ambos ficam fora da API oficial da Meta. Se sua equipe exige executar o software na própria infraestrutura, uma API hospedada não atende ao requisito. Para projetos que exigem SLA contratual ou uma região de hospedagem especificada, condicione a escolha ao contrato que documenta esses termos.
Leia também o guia de migração de sessão WhatsApp, o tutorial de webhooks no n8n e a página sobre Chatwoot com GoZAP.