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.

1. Configurando o App no Meta for Developers

Antes de iniciar o Embedded Signup, o app precisa estar corretamente configurado no Meta for Developers.

Permissões obrigatórias

Configuração do Webhook

O webhook é essencial para receber eventos em tempo real. Configure-o antes de iniciar o fluxo de Embedded Signup.

• URL do webhook deve ser HTTPS com certificado válido
• O verify token deve ser uma string única e secreta
• Inscreva-se nos campos: messages, message_template_status_update, account_update
• Responda ao challenge de verificação com status 200

2. Implementando o Embedded Signup

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}

3. Boas práticas para reduzir 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

4. Pós-conexão: primeiras mensagens

Após o Embedded Signup, o número está conectado mas ainda não pode enviar mensagens proativas. Você precisa:

1. Registrar o número: POST /{phone-number-id}/register
2. Criar um template: submeta para aprovação da Meta (leva de minutos a 24h)
3. Enviar a primeira mensagem: use o template aprovado via POST /{phone-number-id}/messages

5. Checklist de go-live