Embedded Signup: como o cliente conecta o próprio número à API do WhatsApp, e por que a versão 2 morre em 15 de outubro de 2026
A documentação da Meta atualizada em 21 de maio de 2026 marca a data de descontinuação do Embedded Signup v2: 15 de outubro de 2026, com migração obrigatória para a v4. No mesmo texto está o teto que trava agência iniciante: 10 novos clientes conectados por janela móvel de 7 dias.
O que é o Embedded Signup e o que ele resolve?
É a tela de autenticação e autorização que a Meta oferece para que um cliente conecte o próprio número à WhatsApp Business Platform dentro do site ou do painel do fornecedor, sem sair dali e sem entregar senha para ninguém. O fluxo coleta os dados do negócio, gera automaticamente todos os ativos que a plataforma exige e concede ao aplicativo do fornecedor acesso a esses ativos.
O efeito prático é o que interessa a quem opera: o cliente clica em um botão, faz login com a credencial dele, aceita os termos, escolhe ou cria o portfólio de negócios e a conta do WhatsApp Business (WABA), verifica o número e define o nome de exibição. Ao final, a janela que abriu o processo recebe três coisas: o ID da WABA, o ID do número e um código de token trocável.
Esse código não serve para nada sozinho. A documentação exige que ele seja enviado ao seu servidor e usado em uma chamada servidor a servidor para trocar o código por um token de negócio, registrar o número do cliente para uso na Cloud API, inscrever seu app nos webhooks da WABA do cliente e, no caso de Solution Partner, compartilhar a linha de crédito.
Quantos clientes dá para conectar por semana?
Dez. Por padrão, a Meta permite conectar até 10 novos clientes em uma janela móvel de 7 dias, e apenas clientes recém conectados contam para esse limite. A contagem atual aparece no painel Partner overview do WhatsApp Manager, e a Meta avisa por e-mail quando o fornecedor se aproxima do teto.
O caminho para sair dele está no mesmo documento:
- Concluir a verificação do negócio (Business Verification), o App Review e a Access Verification eleva o limite automaticamente para 200 novos clientes por janela móvel de 7 dias.
- Acima de 200 por semana, é preciso se candidatar a Meta Business Partner.
- Independentemente do volume, não é possível conectar cliente algum enquanto o app não tiver acesso avançado aprovado no App Review para cada permissão que ele usa.
Há uma armadilha registrada em nota: WABAs existentes que foram criadas originalmente pelo app de desenvolvedor não podem ser selecionadas nem conectadas diretamente pelo fluxo do Embedded Signup. Quem começou o projeto em ambiente de teste e depois tentou levar o mesmo ativo para produção pelo fluxo padrão esbarra exatamente aí.
Quais permissões o fluxo pede e o que o cliente enxerga?
Para o caso de uso mais comum, que é apenas Cloud API, a documentação indica duas permissões: whatsapp_business_management, necessária se o app precisa acessar configurações da WABA e templates do cliente, e whatsapp_business_messaging, necessária se o app precisa acessar configurações do número ou vai ser usado para enviar e receber mensagens.
O detalhe que muda o roteiro de testes: enquanto o app está em modo de desenvolvimento, essas permissões aparecem na tela de autorização para qualquer pessoa com papel de admin, developer ou tester no app. Quando o app vai para modo Live, só aparecem no fluxo as permissões que foram aprovadas para acesso avançado no App Review. É por isso que um fluxo que funcionava em teste some com metade das telas quando entra em produção.
Sobre a propriedade dos ativos, a documentação é categórica e vale citar para qualquer cliente desconfiado: o negócio conectado pelo Embedded Signup é dono de todos os seus ativos de WhatsApp e tem acesso completo ao WhatsApp Manager, e o fornecedor não pode restringir esse acesso de forma alguma.
Por que o cliente abandona o fluxo, e como descobrir onde?
Se o cliente fecha o fluxo antes de concluir, a Meta envia um evento de mensagem para o navegador que abriu a janela, com a propriedade data.current_step indicando em qual tela ele parou. É o instrumento que transforma abandono em diagnóstico, e a maioria das integrações simplesmente ignora esse evento.
| Valor de current_step | Tela correspondente |
|---|---|
BUSINESS_ACCOUNT_SELECTION | Portfólio de negócios |
WABA_PHONE_PROFILE_PICKER | Seleção de WABA |
WHATSAPP_BUSINESS_PROFILE_SETUP | Criação de WABA |
PHONE_NUMBER_SETUP | Adição do número |
PHONE_NUMBER_VERIFICATION | Verificação do número |
PERMISSIONS | Revisão de permissões |
A documentação também recomenda um atalho que reduz abandono na origem: se o fornecedor já conhece dados do negócio do cliente, é possível injetar essa informação previamente no fluxo, o que reduz significativamente o número de telas com as quais o cliente precisa interagir.
O que muda para agências e plataformas no Brasil
A data de 15 de outubro de 2026 é o item de agenda. Todo fornecedor brasileiro que integrou o Embedded Signup na versão 2 tem até lá para migrar para a v4, sob risco de interrupção do onboarding de novos clientes. Quem terceirizou a integração precisa cobrar essa migração agora, não em setembro.
Dois pontos favorecem a operação local. O fluxo está disponível em 30 idiomas, com português do Brasil na lista, e o idioma é acionado automaticamente conforme a língua em que o cliente usa o Facebook. E existe a conta sandbox, válida por 30 dias, que permite simular um cliente completando o fluxo sem poluir a conta real com portfólios e WABAs de teste, ainda que o número da sandbox não envie nem receba mensagem.
A diferença de cobrança também precisa estar clara na proposta comercial. Se o fornecedor é Solution Partner, ele já precisa ter linha de crédito e compartilhá-la com o cliente durante o onboarding. Se é Tech Provider ou Tech Partner, o cliente conectado precisa anexar um meio de pagamento à própria conta antes de conseguir enviar qualquer mensagem. Quem vende sem explicar isso descobre no dia da virada. O desenho geral do canal está no nosso guia da API oficial do WhatsApp, e a comparação com atalhos não oficiais está em API oficial contra API não oficial.
Leitura crítica
O Embedded Signup é a peça que profissionalizou o mercado brasileiro de WhatsApp, e o mérito é menos técnico do que contratual: ele acabou com a prática de pedir a senha do cliente ou o código de verificação por mensagem. O ativo nasce no nome do cliente, e essa propriedade não pode ser restringida pelo fornecedor. Qualquer proposta que ainda dependa de acesso compartilhado a credencial está fora do padrão da plataforma.
O teto de 10 clientes por semana, porém, tem um efeito colateral que raramente é dito. Ele empurra fornecedor pequeno para a verificação de negócio antes de ter volume que justifique o esforço, e cria um incentivo perverso para que revendas conectem clientes por baixo de um único parceiro maior, o que devolve ao cliente final a mesma opacidade que o fluxo tentou eliminar. Vale perguntar a qualquer fornecedor sob qual app o seu número vai ser conectado.
A cadência de versões também merece ceticismo operacional. Um fluxo com v2, v3 e v4 convivendo, e com data de morte marcada para a versão que boa parte do mercado ainda usa, indica produto em evolução rápida. Integrar é barato. Manter integrado é o custo recorrente que ninguém coloca na planilha.