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