Meta WhatsApp: coexistência entre API Cloud e app Business no celular

O que é coexistência?

Coexistência é o modo oficial em que o lojista mantém o WhatsApp Business no celular e, ao mesmo tempo, conecta a API Cloud para inbox web, automações e integrações (como ZapDoPro). A Meta chama isso de onboarding com whatsapp_business_app_onboarding no Embedded Signup v4.

Não é “gambiarra”: é fluxo homologado — quando a configuração no app Meta está correta.

Por que importa

Sem coexistência bem configurada, o popup de conexão pode pedir número novo e gerar erro de número já registrado. O lojista acha que “a plataforma quebrou”, mas a causa costuma ser Configuration ID ou tipo de feature errado no painel Meta.

Requisitos do lojista

• WhatsApp Business App (não o WhatsApp comum), versão atualizada.
• Número já ativo nesse app.
• No popup Meta, escolher conectar conta existente (QR no app), não digitar outro número.

Webhooks essenciais na coexistência

Além de messages, a Meta recomenda campos como:

• history — histórico após onboarding
• smb_app_state_sync — contatos do app
• smb_message_echoes — mensagens enviadas pelo celular
• account_update — mudanças na conta

Isso permite que o inbox na plataforma reflita o que acontece no telefone.

ZapDoPro e modelo SaaS

Cada loja conecta sua WABA e seu número (phone_number_id único por página). O cliente final vê o nome verificado da loja, não um número compartilhado da plataforma. Token e webhook são centralizados na arquitetura de Tech Provider, mas a identidade no chat é sempre do negócio.

Checklist rápido antes de conectar

1. Configuration ID v4 com Cloud API + coexistência no Meta Developers.
2. Variáveis de Embedded Signup alinhadas no servidor (featureType, sessionInfoVersion).
3. Add-on WhatsApp API ativo na conta ZapDoPro.
4. Pré-voo no painel: coexistência pronta antes de abrir o popup.

Leitura relacionada

Compare com soluções arriscadas no artigo WhatsApp API oficial vs não oficial.