Guia técnico

Como otimizar o onboarding da API oficial usando Embedded Signup

Menos abandono no cadastro do cliente: o fluxo que engrena e os pontos em que a pessoa desiste, para você cortar fricção de verdade.

Tem a senha deste guia ou da comunidade? A da comunidade vale para todos os materiais.

Quero fazer parte e receber esse tipo de conteúdo

Guia técnico

Como otimizar o onboarding da API oficial usando Embedded Signup

Reduza fricção no cadastro de clientes na Cloud API: Embedded Signup, permissões e primeiras mensagens em minutos.

Última atualização: 30 de março de 2026

Mapa completo de onboarding

Para a visão em um único diagrama com todos os passos da implantação (BM, verificação, coexistência, templates), abra o Mapa de implantação Meta.

Visão geral do fluxo

O Embedded Signup permite que o seu cliente conecte o número de WhatsApp à sua plataforma sem sair da sua interface. O fluxo completo, quando bem implementado, leva menos de 5 minutos.

flowchart LR A["CTA Conectar"] --> B["Facebook Login"] B --> C{"Tem BM?"} C -->|Sim| D["Escolhe BM"] C -->|Não| E["Cria BM"] D --> F["WABA"] E --> F F --> G["Número"] G --> H["SMS / voz"] H --> I["Callback + code"] I --> J["Backend grava token"]

Visão geral das etapas

O Embedded Signup permite que o seu cliente conecte o número de WhatsApp à sua plataforma sem sair da sua interface. As etapas seguem a mesma numeração do mapa geral de onboarding: as etapas 1–3 (CNPJ, BM, Verificação) são pré-requisitos cobertos no material principal. Antes de iniciar, o tech provider precisa montar o app e adicionar o produto WhatsApp (setup único).

flowchart TD SETUP["Setup do Tech Provider
(Criar app + Produto WhatsApp)"] --> E4["4 · Preparação do WhatsApp"] E4 --> E6["6 · Conexão via
Embedded Signup"] E6 --> E7["7 · Templates"] E7 --> E8["8 · Operação"]

Setup do Tech Provider

Estes passos são feitos uma vez pelo tech provider, antes de onboardar clientes. Não correspondem a uma etapa numerada do mapa: são pré-requisitos da plataforma.

Criar app no Meta for Developers

Acesse developers.facebook.com e crie um app do tipo Business.

Tipo do app: Business (não "Consumer" ou "Gaming")
Vincule à BM verificada
Defina o nome do app (aparece para o cliente no Embedded Signup)

Edge case app: app tipo errado ou BM errada vinculada gera erros no fluxo de login e permissões. Revise Business settings do app e dono da BM antes do primeiro Embedded Signup com cliente.

Permissões obrigatórias

Permissão	Para quê serve	Necessita App Review?
`whatsapp_business_management`	Gerenciar WABA, números e templates	Sim
`whatsapp_business_messaging`	Enviar e receber mensagens	Sim
`business_management`	Acesso à Business Manager do cliente	Sim

Dica: Solicite todas as permissões de uma vez no App Review. Submissões separadas atrasam a aprovação e podem gerar inconsistências.

Adicionar produto WhatsApp

No painel do app, adicione o produto WhatsApp. Isso cria automaticamente uma WABA (WhatsApp Business Account) vinculada à sua BM.

A WABA é criada automaticamente sob a BM que é dona do app
Configure o display name da WABA (aparece para o destinatário)
Configure um método de pagamento na WABA (cartão de crédito ou créditos pré-pagos): obrigatório para enviar mensagens em produção

Edge case cobrança: o cartão/método da API do WhatsApp (conversas) é independente do pagamento de anúncios Facebook/Instagram. Cada número/WABA pode exigir cadastro próprio; cartão internacional em USD é o cenário mais comum.

Configurar webhooks

Webhooks são como a API avisa seu servidor sobre mensagens recebidas, status de entrega, etc. Configure antes do primeiro Embedded Signup com cliente.

Configure uma URL HTTPS pública no seu servidor
Implemente o endpoint de verificação (GET com challenge)
Assine os campos do webhook: messages (mensagens recebidas e status de entrega) e message_template_status_update (status de aprovação de templates)
Teste com a ferramenta de teste do painel da Meta

Evite em produção: usar ngrok (ou túnel equivalente) como URL fixa do webhook. Para testes locais funciona; em produção o túnel pode cair ou mudar e você perde eventos. Prefira servidor com HTTPS válido e endpoint estável.

Edge cases webhook: valide X-Hub-Signature-256 com o app secret (rejeite payload sem assinatura válida). Timeouts ou 200 lento podem fazer a Meta reenfileirar ou desativar entregas: responda rápido e processe trabalho pesado fora da thread do request.

flowchart TD TP1["Acessar developers.facebook.com"] --> TP2["Criar app tipo Business"] TP2 --> TP3["Vincular à BM verificada"] TP3 --> TP4["App Review (permissões)"] TP4 --> TP5["Adicionar produto WhatsApp"] TP5 --> TP6["Configurar webhook HTTPS"] TP6 --> TP7["Configurar pagamento (USD)"] TP7 --> TP8(["Pronto para Embedded Signup
com clientes"])

Etapa 4: Preparação do WhatsApp

Corresponde à Etapa 4 do mapa de onboarding (estágio WAB). O número de telefone do cliente precisa estar pronto antes da conexão.

flowchart TD START{"Número novo ou
já no WhatsApp?"} -->|Chip novo| DEDIC["Linha dedicada"] START -->|Já no WhatsApp Business| COEX_Q{"Manter app no celular
+ API?"} START -->|Em outra API
Z-API / Evolution / BSP| DESCON["Desconectar no app
aguardar 24h+"] COEX_Q -->|Sim| ELEG{"Elegível?
7+ dias no WAB"} COEX_Q -->|Não| API["API / Embedded Signup"] ELEG -->|Sim| COEX["Coexistência
QR Code"] ELEG -->|Não| WAIT["Usar número mais tempo
no Business App"] WAIT --> ELEG DESCON --> API DEDIC --> API COEX --> VERIFY["SMS / voz / PIN ou QR"] API --> VERIFY VERIFY --> OK(["Número OK"])

Edge cases número: erro "já registrado em uma conta WhatsApp" → desvincule do provedor/BSP anterior no celular e aguarde alguns minutos; se persistir após API não oficial, pode levar semanas de uso estável no Business App. Coexistência exige WhatsApp Business (versão recente), não o app pessoal. PIN: excesso de tentativas → esperar ~12h antes de novo ciclo. Número bloqueado ou limite de telefones na WABA → tratar pelo Gerenciador do WhatsApp / suporte Meta.

Coexistência (QR Code)

A coexistência mantém o WhatsApp Business App no celular e a API oficial no mesmo número, vinculados por QR Code (requisitos e prazos de elegibilidade mudam; o mapa completo detalha passo a passo).

O número continua ativo no WhatsApp Business no celular
Tráfego pela API segue regras e cobrança da plataforma; uso pelo app segue políticas do app
Útil quando o escritório não quer perder o app no telefone nem o histórico elegível à importação

Etapa 6: Conexão via Embedded Signup

Corresponde à Etapa 6 do mapa (estágio Conexão). No fluxo direto o cliente faz Coexistência via QR Code; no Embedded Signup, a conexão acontece via Facebook Login na sua plataforma.

Simulação interativa do fluxo

A recriação abaixo foi feita pela WhatsApp Founders para fins didáticos: ela não é uma tela da Meta, não se conecta a nenhum serviço e não coleta dados. Serve para você reconhecer, etapa por etapa, o que o seu cliente vê ao clicar em "Conectar". Navegue com Avançar / Voltar, troque o portfólio empresarial no dropdown, ou escolha "Conectar um app do WhatsApp Business" para ver o caminho de coexistência via QR Code.

O fluxo real só acontece em domínio da Meta. Ao implementar, o Embedded Signup abre uma janela em facebook.com. Se um cliente seu vir essa tela em qualquer outro endereço, ou se alguém pedir o código de verificação dele por telefone, e-mail ou mensagem, é golpe.

Simulação didática do fluxo de Embedded Signup

Diálogo da Meta (recriado)

Ativos de negócios

Dados da empresa

Número de telefone

Verificar número

QR Code

Tela 1: ativos de negócios compartilhados com a sua plataforma

Você pode usar ativos existentes ou criar outros.

Portfólio empresarial

M Verificado

Conta do WhatsApp Business

Selecione uma conta do WhatsApp Business

Tela 5: conexão por QR Code (coexistência)

No fluxo real, a Meta exibe aqui um QR Code de vínculo. O desenho abaixo é ilustrativo, gerado aleatoriamente, e não é escaneável.

QR ilustrativo: não é escaneável

No fluxo real, o caminho no celular do cliente é WhatsApp → Configurações → Aparelhos conectados.

O que a Meta mostra em seguida:

Confirme ou edite o nome da conta
Reveja as permissões da sua plataforma
Conectando (alguns instantes)
Conta conectada

Importar contatos e histórico de conversas

Sua conta poderá compartilhar o perfil empresarial, os contatos, o histórico de conversas dos últimos 6 meses e outras informações relevantes.

Como a Meta descreve o processo:

Procure por uma mensagem da conta comercial oficial do Facebook e toque em Conectar.
Caso não veja essa mensagem, toque em Menu ou em Configurações e selecione Conta e Plataforma comercial.
Escolha se você quer compartilhar seu histórico de conversas
A Meta exibe um código de acesso na tela dela, usado só dentro do app. Nenhum código é pedido ou exibido por esta página.

Em vez disso, use um código de acesso

Política de Privacidade e Termos (ilustrativos)

Recriação didática do diálogo de Embedded Signup, feita pela WhatsApp Founders. Não é a Meta, não é o Facebook, nenhum campo é editável e nenhum dado é coletado ou enviado.

Inicializando o Facebook Login

O fluxo começa com o Facebook Login Dialog. O SDK do Facebook JS precisa ser carregado na página.

Onde criar o config_id: No Meta App Dashboard, vá em Facebook Login > Settings e crie uma configuração. O config_id gerado é o que você usa no código abaixo.

FB.login(function(response) {
  if (response.authResponse) {
    const code = response.authResponse.code;
    // Envie o code para seu backend
    // para trocar por um System User Access Token
  } else {
    // Usuário cancelou ou erro no login
    console.error('Embedded Signup cancelado ou falhou');
  }
}, {
  config_id: 'SEU_CONFIG_ID',
  response_type: 'code',
  override_default_response_type: true,
  extras: {
    setup: {
      // Pré-preencha dados do cliente se tiver
      business: { name: 'Nome da Empresa' }
    },
    // Para clientes que já têm WABA e só querem conectar:
    // feature_type: 'only_waba_sharing'
  }
});

Importante: Use response_type: 'code' e troque o code por um token no backend. Nunca exponha tokens no frontend.

feature_type: 'only_waba_sharing': Use esta opção quando o cliente já tem uma WABA criada e só quer compartilhá-la com a sua plataforma. Pula a criação de BM e WABA, reduzindo fricção.

Trocando o code por token

No seu backend, faça a troca do authorization code por um access token de longa duração. Use sempre a versão mais recente da Graph API:

GET https://graph.facebook.com/v22.0/oauth/access_token
  ?client_id={app-id}
  &client_secret={app-secret}
  &code={code-received}

Versionamento: Substitua v22.0 pela versão mais recente da Graph API. Versões são depreciadas a cada ~2 anos. Consulte a documentação de versões.

Reduzindo abandono

flowchart TD A["Abandono alto"] --> B{"Onde para?"} B -->|Login Meta| C["CTA claro + por quê"] B -->|BM| D["Pré-preencher empresa"] B -->|SMS| E["Formato E.164 + dicas"] B -->|Erro| F["Mensagens específicas"] C --> G(["Medir funil"]) D --> G E --> G F --> G

Pontos críticos de abandono

Momento do login Facebook: muitos clientes hesitam. Explique que é necessário para conectar o WhatsApp oficialmente e que você não terá acesso ao Facebook pessoal.
Seleção/criação da BM: clientes com múltiplas BMs se confundem. Se possível, pré-selecione a BM correta.
Verificação do número: o código SMS pode atrasar. Ofereça a opção de verificação por ligação como fallback imediato.
Erros de permissão: se o usuário não é admin da BM, o fluxo falha silenciosamente. Detecte isso verificando o campo response.authResponse e mostre mensagem clara: "Você precisa ser administrador do Business Manager para conectar o WhatsApp."

UX que funciona

Mostre um stepper visual com as etapas do processo
Adicione um vídeo curto (30s) mostrando o fluxo completo
Tenha um chat de suporte disponível durante o onboarding
Envie e-mail com instruções antes do cliente iniciar

Etapa 7: Templates

Corresponde à Etapa 7 do mapa (estágio Templates). Templates são mensagens pré-aprovadas pela Meta, obrigatórios para iniciar conversas fora da janela de 24h.

Boas práticas para aprovação rápida

Use linguagem clara e profissional
Inclua o nome da empresa no template
Evite linguagem promocional agressiva
Sempre inclua uma forma de opt-out (para templates de marketing)
Use variáveis nomeadas ({{nome}}, {{pedido_id}}) com exemplos realistas ao submeter

flowchart LR T1["Criar template"] --> T2["Submeter à Meta"] T2 --> T3{"Status"} T3 -->|OK| T4["Usar em produção"] T3 -->|Rejeitado| T5["Corrigir + resubmit"] T3 -->|Pausado| T6["Quality rating"] T5 --> T2 T6 --> T2

Edge cases templates: conteúdo promocional em categoria utilidade → rejeição. Variáveis sem exemplos realistas atrasam análise. Quality rating baixo ou feedback negativo pode pausar o template ou afetar o número: corrija copy e segmentação antes de escalar volume.

Dica de founder: Crie um template genérico de boas-vindas antes do onboarding e use-o imediatamente após a conexão. Isso dá ao cliente a sensação de que "já está funcionando".

Etapa 8: Operação

Corresponde à Etapa 8 do mapa (estágio Operação). Após o Embedded Signup, o número está conectado mas ainda não pode enviar mensagens proativas. Passos finais:

Registrar o número: POST /{phone-number-id}/register
Usar template aprovado: envie a primeira mensagem via POST /{phone-number-id}/messages
Monitorar quality rating: números novos começam no tier de 250 mensagens/24h: escala automaticamente com rating verde

Checklist de go-live

Item	Status	Observação
App tipo Business vinculado à BM verificada	Obrigatório	Tipo errado ou BM errada = erros no Embedded Signup
Produto WhatsApp adicionado + pagamento	Obrigatório	Cartão USD na WABA para envios em produção
App aprovado no App Review	Obrigatório	Submeta com screenshots e vídeo do fluxo
Webhook recebendo eventos	Obrigatório	URL HTTPS estável; valide X-Hub-Signature-256
Token de sistema configurado	Obrigatório	Use System User token, nunca User token
Template de boas-vindas aprovado	Recomendado	Crie antes do primeiro onboarding
Error handling implementado	Recomendado	Trate pelo menos os 5 erros mais comuns
Analytics no funil de signup	Recomendado	Meça cada etapa para otimizar
Fluxo testado com conta real	Obrigatório	Teste com um número que não está na API

Resumo: edge cases por etapa

Etapa	Situação	Ação típica
Setup · App	Tipo errado / BM errada	Revise Business settings do app; vincule BM verificada correta.
Setup · Produto WhatsApp	Pagamento ausente	Cadastrar cartão USD na WABA; independente de anúncios FB/IG.
Setup · Webhooks	Timeout / assinatura inválida	Responder rápido; validar X-Hub-Signature-256; evitar ngrok em produção.
4 · Preparação WhatsApp	Outra API / PIN bloqueado / coex inelegível	Desconectar + 24h; esperar ~12h para PIN; 7+ dias no WAB para coexistência.
6 · Conexão (Embedded Signup)	Abandono / permissão insuficiente	CTA claro; pré-preencher BM; mensagem de admin obrigatório.
7 · Templates	Rejeição / pausa	Categoria correta; exemplos realistas; melhorar quality rating.
8 · Operação	Tier travado / rating baixo	Aquecer volume; monitorar quality rating.