Como o WhatsApp Embedded Signup funciona para plataformas SaaS

Se o seu produto SaaS permite que cada cliente conecte o próprio número do WhatsApp, você precisa de algo mais robusto do que um botão de “conectar”.

WhatsApp não é apenas uma credencial de API. Uma conexão real envolve um Meta Business Portfolio, uma conta do WhatsApp Business, um número, permissões, estado de revisão, estado de pagamento, webhooks e um jeito claro de saber qual cliente do seu produto é dono daquele número.

Embedded Signup é o fluxo hospedado pela Meta para coletar essa conexão do cliente. A Kapso transforma isso em uma primitiva de produto: um link de conexão para cada cliente.

A versão curta

Para uma plataforma SaaS, Embedded Signup é o fluxo de “conectar WhatsApp” que o seu cliente completa dentro de uma janela controlada pela Meta.

O cliente faz login com Facebook ou credenciais da Meta Business, escolhe ou cria os ativos do negócio, aceita os termos necessários, concede permissões e conecta um número do WhatsApp. Quando o fluxo termina, a sua plataforma recebe identificadores como o ID da conta do WhatsApp Business e o ID do número.

O seu produto deve tratar isso como um ciclo de vida:

1. Criar ou identificar o cliente no seu sistema.
2. Gerar um link de conexão para esse cliente.
3. Deixar o cliente completar o fluxo da Meta.
4. Detectar a conexão com redirects, webhooks ou ambos.
5. Guardar o phone_number_id conectado e usá-lo para mensagens, webhooks, workflows e inbox.

O que a Meta controla

A Meta controla a interface do Embedded Signup e as validações da plataforma.

Isso inclui:

• Autenticação com Facebook ou Meta.
• Seleção ou criação do Business Portfolio.
• Seleção ou criação da conta do WhatsApp Business.
• Verificação ou pareamento do número.
• Aceitação dos termos.
• Permissões concedidas ao app.
• Revisão do display name, verificação do negócio, revisão do WABA, pagamento e restrições de conta.

O seu app pode iniciar o fluxo e finalizar a conexão, mas não pode contornar os requisitos da Meta. Se o negócio tiver dados legais incompletos, um WABA em revisão, problemas de pagamento ou um número bloqueado, a conexão pode falhar ou ficar pendente.

O que o seu produto precisa modelar

O seu produto controla a relação com o cliente e o modelo de dados ao redor da conexão.

No mínimo, guarde:

O erro comum é guardar apenas o número final. Em produção, os problemas de suporte geralmente estão no estado intermediário: qual negócio completou o fluxo, qual número escolheu, se a Meta voltou para o app, se o webhook chegou e se o WABA ainda está em revisão.

Dedicated vs coexistência com WhatsApp Business App

Existem dois modos comuns.

Dedicated Cloud API é API-first. O número fica na WhatsApp Business Platform e é pensado para escala. Para plataformas, a configuração padrão da Kapso é uma conexão dedicated com provisionamento de número, sem impedir que a equipe escolha coexistência quando o Business App precisa continuar ativo.

A coexistência com WhatsApp Business App permite que o cliente continue usando o app no telefone enquanto a Kapso também recebe eventos por API. É útil para pequenos negócios que precisam de operação humana no app e automação em paralelo.

A coexistência é conveniente, mas tem mais casos extremos. O cliente precisa ver o fluxo com QR, conexões antigas com outros provedores podem bloquear o onboarding e às vezes é necessário limpar estado residual dentro da Meta. Se o seu produto precisa de automação estável e alto volume, use dedicated. Se você vende para pequenos negócios que vivem no WhatsApp Business App, coexistência pode ser a melhor experiência.

Como a Kapso implementa isso

Na Kapso, você cria um cliente, gera um link de conexão e entrega esse link para o cliente. O cliente completa o fluxo da Meta. A Kapso finaliza a conexão e o seu produto recebe os identificadores necessários.

Quando você usa links hospedados pela Kapso, o seu produto consome APIs e webhooks da Kapso em vez de pedir tokens de acesso da Meta diretamente ao cliente.

curl -X POST https://api.kapso.ai/platform/v1/customers/{customer_id}/setup_links \
  -H "X-API-Key: $KAPSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "setup_link": {
      "success_redirect_url": "https://app.example.com/whatsapp/success",
      "failure_redirect_url": "https://app.example.com/whatsapp/failed",
      "allowed_connection_types": ["dedicated"],
      "provision_phone_number": true
    }
  }'

O link pode configurar:

• URLs de sucesso e erro.
• Idioma, incluindo português, espanhol e inglês.
• Tipos de conexão permitidos.
• Provisionamento de número.
• Cores do onboarding hospedado.
• Reconexão de um número existente.

Os links expiram depois de 30 dias. Ao criar um novo link ativo, o link anterior é revogado para aquele cliente.

Se o cliente estava usando um link antigo quando você gera um novo, o seu produto deve tratar o anterior como inválido. Mostre sempre o link mais recente e deixe claro no suporte qual tentativa de conexão ainda está ativa.

Como detectar que terminou

Use redirects e webhooks quando puder.

Redirects são bons para UX. Eles permitem mostrar “conectado”, “pendente” ou “tente de novo” quando o cliente volta da Meta.

Webhooks são melhores como verdade de backend. Um webhook de projeto como whatsapp.phone_number.created permite guardar o phone_number_id, reconciliar estado e continuar o provisionamento.

O redirect pode ser perdido se o cliente fechar a janela. O webhook pode chegar depois que a tela mudou. Juntos, eles deixam o fluxo mais resiliente.

Checklist antes de publicar o fluxo

Antes de expor esse fluxo para clientes, o seu produto deve conseguir responder:

• Qual cliente é dono desta conexão?
• Que tipo de conexão oferecemos?
• O cliente terminou o fluxo da Meta ou abandonou?
• Qual phone_number_id ficou conectado?
• Qual WABA é usado para gerenciar templates?
• O número está pendente de revisão?
• Qual webhook confirmou a conexão?
• Como o cliente reconecta se a Meta revogar credenciais?
• Que dados de suporte mostramos quando a Meta bloqueia o fluxo?

A melhor experiência de “conectar WhatsApp” parece simples porque o produto já modelou o estado por baixo.

Onde a Kapso entra

A Kapso é útil quando o onboarding de WhatsApp faz parte do seu produto, não de uma integração isolada.

Com Kapso Platform, você pode mapear tenants para clientes Kapso, gerar links de conexão, detectar conexões concluídas, enviar a partir do número do cliente, assinar webhooks, usar Workflows e levar conversas para um inbox quando uma pessoa precisa assumir.

Embedded Signup conecta os ativos do WhatsApp. O seu produto ainda precisa de uma camada operacional ao redor desses ativos. A Kapso fornece essa camada.