Como otimizar o onboarding da API oficial usando Embedded Signup

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.

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).

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)

Permissões obrigatórias

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

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

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.

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.

Inicializando o Facebook Login

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

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'
  }
});

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}

Reduzindo abandono

Pontos críticos de abandono

1. 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.
2. Seleção/criação da BM: clientes com múltiplas BMs se confundem. Se possível, pré-selecione a BM correta.
3. 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.
4. 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

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:

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

Checklist de go-live

Resumo: edge cases por etapa