Coexistência WhatsApp + Cadastro Incorporado: Tutorial DEFINITIVO!
Links importantes
WhatsApp Coexistência e Cadastro Incorporado: O Guia Definitivo (2026)
Bora pra ação! Hoje vamos mergulhar em um dos tópicos mais avançados e menos documentados da API Oficial do WhatsApp: a Coexistência e o Cadastro Incorporado (Embedded Signup). Este é um passo a passo super detalhado, do zero, com informações que você simplesmente não encontrará em outro lugar.
Se você tem um sistema (SaaS, White Label) e quer oferecer a API Oficial para seus clientes de forma profissional, permitindo que eles conectem suas contas dentro da sua própria plataforma, este guia é para você.
Material de Apoio
Todo o material de apoio, incluindo os vídeos e textos que usei para a aprovação do meu aplicativo na Meta, está disponível logo acima nesta página.
Pré-requisitos: O Que Você Precisa Ter em Mãos
- Um Aplicativo da Meta Já Criado: Se você ainda não criou seu app, assista nosso vídeo da semana passada sobre o novo processo de criação de apps e depois volte aqui.
- Acesso ao Gerenciador de Negócios (Business Manager): Você precisa ser administrador da conta de negócios onde seu app está.
- Para Coexistência: O número de telefone final deve estar em um celular com o WhatsApp Business instalado (o WhatsApp comum não funciona).
Passo 1: Crie o Token de Usuário do Sistema (System User Token)
Este token será a chave mestra que seu sistema usará para se comunicar com a Meta. É a primeira e mais crucial etapa.
- Acesse seu Gerenciador de Negócios (business.facebook.com).
- No menu, vá em Usuários > Usuários do sistema. Crie um novo usuário com a função de Admin.
- Com o usuário criado, clique em "Gerar novo token".
- Selecione o aplicativo correto (o que você criou para esta finalidade).
- Defina a expiração do token. Para produção, selecione "Nunca".
- Selecione as Permissões (ESSENCIAL): Marque as quatro permissões a seguir:
whatsapp_business_managementwhatsapp_business_messagingbusiness_management
- Clique em "Gerar token", copie o código gerado e guarde-o em um local seguro. Você não poderá vê-lo novamente.
Passo 2: Configurando o Cadastro Incorporado
Agora vamos configurar a "tela" que aparecerá dentro do seu sistema para que seus clientes conectem as contas.
- No painel de desenvolvedores, acesse seu aplicativo.
- No menu lateral, vá em Casos de uso > Personalizar (dentro da opção do WhatsApp).
- Clique em "Configurar cadastro incorporado" no menu que aparecer.
- Crie uma Configuração de Login:
- Clique para criar uma nova configuração.
- Marque as duas primeiras opções: "Cadastro incorporado" e "API de mensagens do WhatsApp".
- Em "Ativos", selecione "Contas do WhatsApp Business" e marque todas as sub-opções.
- Em "Permissões", verifique se as mesmas permissões do token estão selecionadas.
- Salve a configuração.
Aprovação do App é Necessária para Coexistência!
Para que a funcionalidade de Coexistência funcione, seu aplicativo precisa passar pela Análise da Meta. Sem a aprovação, o Cadastro Incorporado só permitirá adicionar números novos (que não estão em uso). Com a aprovação, você libera a opção de conectar um número que já está ativo no app WhatsApp Business.
Passo 3: A Dica de Ouro - Configurando Domínios e a URL Correta
Esta é a parte que a documentação não explica direito e onde a maioria trava. Para que o popup de login da Meta funcione dentro do seu site, você precisa autorizar seus domínios em TRÊS lugares diferentes:
- Login com o Facebook: No menu do app, vá em Login com o Facebook > Configurações e adicione a URL exata do seu sistema que conterá o fluxo de cadastro em "URIs de redirecionamento do OAuth válidas".
- Configurações Básicas do App: Em Configurações > Básica, adicione o domínio principal do seu aplicativo no campo "Domínios do aplicativo".
- Cadastro Incorporado: Volte para a tela de configuração do Cadastro Incorporado e, na seção "Gerenciamento de domínios", adicione novamente os domínios e subdomínios que usarão o recurso.
O Segredo da URL de Onboarding que Ninguém Conta!
Se você seguir a documentação da Meta e usar o SDK do Facebook para gerar a URL do popup de cadastro, há uma grande chance de ela ser gerada com parâmetros incorretos, o que impedirá a troca final de tokens. A solução é "roubar" a URL correta:
- Na tela de configuração do Cadastro Incorporado, use a ferramenta de teste "Entrar com o Facebook".
- Quando o popup abrir, copie a URL completa que aparece na barra de endereço do navegador.
- Use essa URL como base para construir a chamada no seu sistema, apenas substituindo os parâmetros dinâmicos (como o `state`). Isso garante que a chamada seja feita no formato exato que a Meta espera.
Com essas configurações, seu sistema estará pronto para realizar o fluxo de Cadastro Incorporado, obter o token de acesso do cliente e, a partir daí, gerenciar a conta de WhatsApp Business dele através da API. É um processo complexo, mas que abre um mundo de possibilidades para quem desenvolve soluções SaaS.
Se você não quer passar por toda essa complexidade e prefere uma solução pronta, o Z-PRO já tem tudo isso implementado, testado e aprovado. Qualquer dúvida, é só chamar. Tamo junto!
Material de Apoio para Aprovação de APP
1- Resposta sugerida para a Meta –
Permissão whatsapp_business_messaging
O aplicativo ZPRO utiliza a permissão whatsapp_business_messaging para possibilitar a comunicação entre empresas e seus clientes por meio da API oficial do WhatsApp Business.
A plataforma oferece um ambiente de multiatendimento, onde diferentes operadores podem receber, responder e gerenciar conversas de forma centralizada e organizada.
A permissão é necessária para:
Enviar e receber mensagens de clientes que entram em contato pelo WhatsApp;
Carregar e recuperar mídias enviadas nas conversas (imagens, áudios, documentos e vídeos);
Registrar e gerenciar números comerciais vinculados à conta WhatsApp Business da empresa;
Exibir e atualizar informações do perfil comercial;
Obter dados analíticos agregados para melhorar a experiência de atendimento, sempre sem identificação pessoal.
Como valor agregado, o ZPRO melhora a produtividade das empresas ao centralizar conversas, organizar atendimentos em equipe, reduzir tempo de resposta e garantir uma experiência mais eficiente e profissional para o cliente final.
A permissão é essencial, pois sem ela o aplicativo não conseguiria realizar sua função principal: permitir que empresas se comuniquem de forma oficial, segura e integrada com seus clientes pelo WhatsApp Business.
2- Resposta sugerida para a Meta — Permissão whatsapp_business_management
O aplicativo ZPRO utiliza a permissão whatsapp_business_management para gerenciar os ativos comerciais do WhatsApp Business que pertencem aos nossos clientes ou aos quais eles nos concedem acesso.
Essa permissão é necessária para que a plataforma ofereça as seguintes funcionalidades:
Conectar e gerenciar contas do WhatsApp Business diretamente pelo painel do ZPRO;
Criar, listar, editar e utilizar modelos de mensagem (message templates) aprovados pela Meta;
Administrar números de telefone comerciais, incluindo verificações, configurações e status de conexão;
Gerenciar assinaturas de webhook, essenciais para receber eventos de mensagens e atualizações em tempo real;
Gerar e acessar códigos QR usados para iniciar conversas com a empresa;
Coletar análises e métricas agregadas da conta, visando melhorar o desempenho do atendimento e a experiência do usuário.
O valor para o usuário é permitir que empresas consigam configurar, administrar e monitorar toda sua operação de WhatsApp Business em um único painel, sem necessidade de ações manuais externas. Isso reduz tempo operacional, melhora a gestão de atendimento e garante maior eficiência.
A permissão é indispensável para que o ZPRO ofereça sua funcionalidade principal: centralizar, organizar e gerenciar de forma segura todos os ativos do WhatsApp Business da empresa, permitindo uma operação de atendimento profissional e integrada.
3- Resposta sugerida — Permissão business_management
O aplicativo ZPRO utiliza a permissão business_management para acessar e gerenciar ativos que pertencem às empresas clientes dentro do Business Manager, conforme autorizado por elas.
Essa permissão é necessária para:
Vincular e gerenciar a conta do WhatsApp Business dentro do Gerenciador de Negócios do cliente;
Confirmar e validar ativos comerciais, como números de telefone e contas do WhatsApp;
Gerenciar permissões e acessos relacionados ao WhatsApp Business dentro do Business Manager;
Sincronizar informações administrativas importantes para o funcionamento correto da API oficial do WhatsApp dentro da plataforma;
Obter informações agregadas e anônimas de desempenho, que ajudam a melhorar as ferramentas e relatórios oferecidos aos usuários.
O valor para o usuário é que o ZPRO facilita toda a configuração e operação do WhatsApp Business sem que o cliente precise navegar manualmente pelo Business Manager. Isso torna o processo mais rápido, seguro e integrado, permitindo que a empresa configure sua operação de atendimento de forma simples e centralizada.
A permissão é essencial para o funcionamento da plataforma, pois sem ela o aplicativo não conseguiria vincular ativos, gerenciar configurações ou validar o uso da API oficial do WhatsApp, etapas fundamentais para que o cliente possa enviar e receber mensagens dentro do ZPRO.
Leve seu negócio para o próximo nível
Este tutorial é apenas a ponta do iceberg. A ZDG é uma empresa com mais de 5 anos de mercado que já ajudou mais de 7.000 assinantes com a criação de soluções de automação de atendimentos e chatbots para WhatsApp com o melhor custo-benefício do mercado
Se você que quer começar do zero e aprender por conta própria:
Conheça a Comunidade ZDG e aprenda a automatizar seus atendimentos no WhatsApp com ferramentas open-source gratuitas. Tenha acesso a cursos essenciais de integrações, infraestrutura e aos nossos exclusivos auto-instaladores de sistemas como Whaticket, Chatwoot, Typebot e N8N.
Se você que busca um sistema avançado completo:
Conheça o Sistema Z-PRO, uma plataforma de multi-atendimento completa com flowbuider nativo para criação de chatbots, integração com inteligência artificial e modo White Label para revenda no modelo SAAS. Unifique WhatsApp (oficial e não oficial), Instagram, Facebook, Telegram e até ligações PABX em um único lugar.
