Pular para o conteúdo
D-APITestar grátis

api oficial · onboarding

Embedded Signup WhatsApp dentro do seu SaaS, em um popup

Coloque o Embedded Signup WhatsApp no seu painel sem app Meta próprio e sem cadastrar domínio: o cliente conecta o número oficial num popup hospedado pela D-API e o seu backend recebe o connectionId.

SaaS testa 14 dias com o time técnico ajudando na integração.

conexões na D-API
1.875
de uptime garantido em contrato
99,9%
datacenters no Brasil
4
por ligação de WhatsApp na API não-oficial
R$ 0
  • Seu domínio fica de fora da Meta

    O fluxo roda numa página hospedada pela D-API, aberta como popup. A Meta exige domínio cadastrado, e quem está cadastrado é o da D-API.

  • Chave pública no navegador

    A publishable key só inicia o onboarding. Ela não envia mensagem nem lê dados, então pode ficar no frontend sem expor a sua API key.

  • Resultado por dois caminhos

    O connect.start() resolve no navegador e o webhook session.created confirma no backend, com o seu metadata intacto.

  • Erro legível para o suporte

    Quando a conexão falha, o popup mostra o motivo em português com o código, e o mesmo código volta para o seu app.

O Embedded Signup WhatsApp é o fluxo da Meta em que o cliente conecta o número na API oficial sem sair do produto que está usando. Para um SaaS, ele resolve o pior momento da venda da API oficial: o cliente fechou contrato e agora precisa ligar o número, e qualquer passo fora do seu painel vira chamado de suporte. Com a D-API, o fluxo inteiro cabe num botão do seu onboarding, abre um popup, e o número volta como uma conexão pronta para enviar mensagens.

Por que o popup roda num domínio da D-API

A Meta só executa o Embedded Signup em domínios cadastrados no app dela. Cadastrar o domínio de cada parceiro não escala, então a D-API hospeda a página do fluxo e você a abre como popup. O resultado volta para a janela que abriu o popup por postMessage, e o SDK confere que a mensagem veio do domínio hospedado da D-API antes de aceitar.

Na prática, o seu SaaS ganha três coisas. Você não precisa criar nem aprovar um app Meta próprio. Você não precisa ser Tech Provider, porque o fluxo roda no app da D-API. E o seu domínio de produção, de homologação ou de cada cliente white label funciona sem cadastro algum na Meta.

Os três passos da integração

O trabalho do seu time se resume a criar uma chave, abrir o popup e guardar o identificador que volta.

1. Crie uma publishable key

A publishable key (pk_live_…) é pública por design. O escopo dela é só iniciar o onboarding, com limite de 30 requisições por minuto, e o pior caso de vazamento é alguém abrir um popup de Embedded Signup sem acesso a dados nem envio. Ela é criada no painel, em Integrações → Publishable Keys, ou pelo seu backend com a API key secreta:

curl -X POST https://api.d-api.cloud/api/v1/connections/cloud-api/publishable-keys \
  -H "Authorization: SUA_API_KEY_SECRETA" \
  -H "Content-Type: application/json" \
  -d '{}'

A resposta traz o key uma única vez. Guarde num lugar de configuração do frontend, como faria com uma chave pública de pagamento.

2. Abra o popup com o DApiConnect

No frontend, o pacote d-api-sdk expõe o DApiConnect pela entrada d-api-sdk/connect. Ele abre o popup, faz o handshake e devolve a conexão:

import { DApiConnect } from "d-api-sdk/connect";

const connect = new DApiConnect({ publishableKey: "pk_live_…" });

async function conectarNumeroOficial(tenantId: string) {
  const { connectionId, phoneNumber } = await connect.start({
    webhookUrl: "https://seu-saas.com/hooks/dapi",
    webhookMode: "normalized",
    metadata: { tenantId },
  });
  await fetch("/api/whatsapp/conexoes", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ tenantId, connectionId, phoneNumber }),
  });
}

O start() aceita quatro opções, todas opcionais:

Opção O que faz
mode standard (padrão) conecta um número novo; coexistence mantém o app WhatsApp Business no mesmo número
webhookUrl Para onde vão os eventos dessa conexão
webhookMode normalized (padrão), no formato canônico da D-API, ou meta_passthrough, com o corpo cru da Meta
metadata JSON seu, devolvido no webhook session.created, com até 512 bytes serializados

Quem prefere não usar o SDK pode fazer o handshake na mão, em HTML puro, abrindo connect.d-api.cloud/connect e respondendo à mensagem dapi-connect-ready com a publishable key. A D-API mantém um exemplo público desse fluxo em um único arquivo.

3. Guarde o connectionId no tenant

O connectionId é o sessionId da conexão nas rotas normais de envio. A partir desse momento o número é uma conexão como qualquer outra da sua conta, e o seu backend envia com a API key secreta, que nunca vai para o navegador.

Trate o session.created como confirmação

O resultado do onboarding é anunciado duas vezes, sem opção a configurar: o start() resolve no navegador e um webhook session.created vai para o webhookUrl daquela conexão, com todos os dados e com o seu metadata em data.metadata.

O segundo caminho existe por causa do celular. Em navegador mobile o popup abre como aba, sem window.opener utilizável, e o postMessage que o start() espera não chega. A promise pode rejeitar com “Conexão cancelada” enquanto a conexão foi criada normalmente. O mesmo vale em webview de app nativo.

Por isso, a regra para o seu backend é ligar a conexão ao cliente pelo session.created, usando o tenantId do metadata, e tratar o retorno do navegador como atalho de interface. Em fluxo mobile, antes de mostrar erro, confirme pelo webhook ou pela listagem de conexões. O limite de 512 bytes do metadata existe porque o valor viaja na URL do diálogo da Meta. Acima disso, o start() lança erro antes de abrir a janela, então guarde ali identificadores e deixe os objetos de negócio no seu banco. O guia de webhooks da API de WhatsApp mostra como montar o handler que recebe esse evento.

Quando a conexão falha

Um onboarding que falha sem motivo claro custa horas de suporte. No fluxo hospedado, a janela mostra o motivo em português com o código embaixo, e um print dela já serve para o seu time. O mesmo motivo volta para o seu app no campo error, com o texto pronto em errorLabel:

error O que aconteceu O que fazer
trial_required A sua conta D-API não tem assinatura ativa Ativar plano ou teste na sua conta
number_in_use O número já está conectado em outra conta Desconectar antes de reconectar
invalid_key Publishable key inválida, expirada ou revogada Gerar outra chave
plan_not_ready, billing_not_ready Cobrança da sua conta ainda não configurada Finalizar o cadastro de cobrança
missing_code, access_denied A Meta não devolveu o código, em geral porque o cliente cancelou Pedir para repetir
onboarding_failed A Meta não concluiu o cadastro do número Tentar novamente

Repare que trial_required, plan_not_ready e billing_not_ready falam da sua conta de parceiro, a da taxa de plataforma por conexão. A cobrança das mensagens continua na conta Meta do seu cliente. Mostre esses três casos para o seu time interno, e não para o cliente final.

Quem implementou o handshake na mão precisa checar o ok antes de ler o data. Numa falha não existe data, e ler data.connectionId direto descarta o motivo real.

O access token da Meta, com cuidado

O resultado do start() também traz o access token da Meta daquela conexão, já descriptografado, com accessTokenKind, accessTokenLabel e accessTokenExpiresAt. Ele serve para quem quer chamar a Graph API direto, por exemplo para gerenciar o catálogo por fora da D-API. Com esse token dá para enviar mensagens e administrar a WABA do cliente, então trate como segredo: mande para o seu backend, sem log, sem localStorage e sem URL.

A página hospedada devolve o token no fragmento da URL, a parte depois do #, que o navegador nunca envia ao servidor, e apaga o fragmento da barra de endereço depois de repassar. Se preferir que o token nem passe pelo navegador, ignore o campo e busque no backend por GET /api/v1/connections/cloud-api/{id}/access-token, detalhado em WhatsApp Cloud API.

Coexistência pelo mesmo botão

Parte dos seus clientes já atende pelo app WhatsApp Business e não quer abrir mão dele. Para esse perfil, o mesmo DApiConnect abre o fluxo com mode: "coexistence". A janela vai direto para a Meta, que pede ao cliente para escanear um QR no app, e volta com o connectionId. A coexistência do WhatsApp Business com a API explica o que muda para o número e como o histórico chega.

Por onde começar

Crie a publishable key, coloque o botão de conexão oficial ao lado do QR code da não oficial e escreva o handler do session.created antes do resto. Com isso, o número oficial do cliente entra no seu produto pela mesma porta que os demais. A lista completa de opções e erros está na documentação da D-API.

Time D-API. Atualizado em .

Perguntas frequentes

O meu cliente precisa ter o Business Portfolio verificado para passar pelo Embedded Signup?

Não para conectar. Ele precisa de uma conta do Facebook e de um Business Portfolio, que pode ser criado no próprio popup. A Meta mantém limites de envio menores até o portfólio ser verificado.

Posso testar o Embedded Signup com o número de teste da Meta?

Não. Os números de teste da Meta não passam pelo Embedded Signup. O teste precisa de um número real, e o trial da D-API inclui webhook, templates e coexistência.

Dá para usar o app Meta do meu SaaS no lugar do app da D-API?

Hoje não. O Embedded Signup roda no app Meta da D-API, e a janela da Meta mostra o nome D-API. App próprio e Solution ID do parceiro não são suportados.

O que acontece se o cliente fechar o popup no meio do fluxo?

Nenhuma conexão é criada e ele pode tentar de novo. Com o SDK, o start() rejeita com a mensagem de conexão cancelada, e você pode oferecer o botão outra vez.

Meu cliente já tem uma WABA com número ativo. Ele precisa criar outra?

Não necessariamente. No painel da D-API existe a opção de selecionar uma WABA existente: o cliente faz login na Meta e escolhe um número que já está lá.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.