API Oficial para SaaS (provedor)

Se você tem um SaaS e quer que seus clientes conectem o WhatsApp API Oficial (Cloud API) sem sair do seu produto, a D-API funciona como provedor: você embute um fluxo de conexão, cada número conectado vira uma conexão na sua conta D-API, e você é cobrado por conexão. Você repassa como quiser para o seu cliente.

Você é um usuário normal da D-API (sua API key secreta fica no seu backend).
Seu cliente conecta o número dele; a conexão fica sob a sua conta, identificada por um connectionId.
Cobrança da Meta é do seu cliente (ele usa o método de pagamento dele na WABA). A D-API só cobra a taxa de plataforma por conexão de você.

Como funciona

O Embedded Signup da Meta não roda no domínio do seu SaaS (a Meta exige domínios cadastrados). Por isso o fluxo roda numa página hospedada pela D-API (connect.d-api.cloud), que você abre como popup. O resultado volta pro seu app por postMessage. Seu domínio não precisa ser cadastrado na Meta.

Crie uma publishable key

Uma publishable key (pk_live_…) é pública de propósito: só inicia o onboarding — não envia mensagens nem lê dados. Crie no painel em Integrações → Publishable Keys, ou via API com a sua 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.

Abra o connect no seu frontend

Use o pacote d-api-sdk (entry d-api-sdk/connect):

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

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

const { connectionId, phoneNumber, accessToken } = await connect.start({
  webhookUrl: "https://seu-saas.com/hooks/dapi", // opcional
  webhookMode: "normalized",                     // opcional (padrão)
  metadata: { tenantId: "acme-42" },             // opcional, volta no webhook
});

Isso abre o popup hospedado, roda o Embedded Signup e resolve com o connectionId (e o access token da Meta). Também dá para fazer o handshake “na mão”, em HTML puro — veja o exemplo completo.

Associe o connectionId ao seu cliente

Guarde o connectionId retornado no seu banco, ligado ao cliente correspondente. A partir daí, esse número é uma conexão normal da D-API.

Envie mensagens pelo seu backend

Com a sua API key secreta (nunca no navegador), o connectionId é o sessionId nas rotas normais de envio:

import { DApi } from "d-api-sdk";

const dapi = new DApi({ apiKey: "<SUA_API_KEY_SECRETA>" });
await dapi.messages.sendText({ sessionId: connectionId, to, text });

Coexistência (manter o app WhatsApp Business)

Por padrão o fluxo cria/onboarda um número novo na API Oficial. Se o seu cliente quer manter o app WhatsApp Business no mesmo número (coexistência), passe mode: "coexistence":

const { connectionId } = await connect.start({ mode: "coexistence" });

O fluxo é o mesmo do padrão — a janela vai direto para a Meta e volta com o connectionId. A diferença é o que a Meta pede ao cliente: escanear um QR no app WhatsApp Business. A sincronização do histórico começa automaticamente e pode levar alguns minutos; oriente o cliente a manter o app aberto.

Webhooks

Você define o webhook da conexão no connect.start({ webhookUrl }), e pode alterar depois pela rota de atualização de sessão. Os eventos chegam com o id da conexão/sessão no payload — então você pode apontar todas as conexões para um único endpoint e distribuir pelo connectionId.

O resultado chega por dois caminhos

Toda conexão criada pelo connect hospedado é anunciada duas vezes, sem opção a configurar:

o connect.start() resolve no navegador com o connectionId e o access token;
um webhook session.created vai para o webhookUrl daquela conexão, com todos os dados — incluindo o access token e o seu metadata.

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

Em fluxo mobile, não trate a rejeição do start() como falha — confirme pelo session.created (ou pela rota de listagem de conexões) antes de mostrar erro para o seu cliente.

Correlacionar com o seu cliente (`metadata`)

metadata é um JSON livre seu, guardado com a conexão e devolvido intacto em data.metadata do session.created. É o que permite ligar a conexão ao tenant sem depender do retorno síncrono:

await connect.start({
  webhookUrl: "https://seu-saas.com/hooks/dapi",
  metadata: { tenantId: "acme-42", plano: "pro" },
});

Limite: 512 bytes de JSON serializado. O valor viaja na URL do diálogo da Meta, e acima disso o start() lança erro antes de abrir a janela. Guarde ali identificadores, não objetos de negócio inteiros.

metadata é opcional e novo na versão 1.3.0 do SDK. Integrações em 1.2.0 ou anterior seguem funcionando sem alteração — apenas recebem metadata: {} no evento.

Formato dos eventos (`webhookMode`)

Você escolhe em que formato os eventos chegam:

`webhookMode`	O que chega no seu endpoint
`normalized` (padrão)	O evento canônico da D-API — o mesmo payload de uma conexão não-oficial, então um único handler serve as duas.
`meta_passthrough`	O corpo cru do webhook da Meta, sem tradução — para quem já tem um parser do formato oficial.

const { connectionId } = await connect.start({
  webhookUrl: "https://seu-saas.com/hooks/dapi",
  webhookMode: "meta_passthrough", // padrão: "normalized"
});

Dá para trocar depois em Atualizar conexão (webhookMode).

Access token da Meta

O resultado do connect.start() traz também o access token da Meta daquela conexão, já descriptografado — útil se você quer chamar a Graph API direto (por exemplo, para gerenciar templates ou o catálogo por fora da D-API):

const {
  connectionId,
  accessToken,          // token da Graph API — SEGREDO
  accessTokenKind,      // "permanent" | "long_lived" | "short_lived" | "unknown"
  accessTokenLabel,     // resumo em português, pronto para exibir
  accessTokenExpiresAt, // ISO-8601, ou null quando não expira
} = await connect.start({ ... });

No Embedded Signup a Meta emite um token permanente (accessTokenKind: "permanent", accessTokenExpiresAt: null) — é o caso normal aqui. Os outros tipos aparecem quando o token foi trocado manualmente: long_lived (~60 dias) e short_lived (~1 hora).

O accessToken é segredo: com ele dá para enviar mensagens e administrar a WABA do seu cliente. Encaminhe para o seu backend e pronto — não registre em log, não salve no localStorage, não exponha em URL.

Se preferir que o token não trafegue pelo navegador, ignore o campo e busque no seu backend quando precisar, com a sua API key secreta:

curl https://api.d-api.cloud/api/v1/connections/cloud-api/<CONNECTION_ID>/access-token \
  -H "Authorization: <SUA_API_KEY_SECRETA>"

A resposta traz o token e a mesma classificação — veja Obter access token da Meta.

Quando a conexão falha

Se o onboarding não conclui, a janela hospedada mostra o motivo em português, com o código embaixo — um print dela já serve para o suporte. O mesmo motivo volta para o seu app:

{ type: "dapi-connect-result", ok: false, error: "trial_required", errorLabel: "A conta D-API do parceiro precisa de uma assinatura ativa para criar conexões." }

Com o SDK, o connect.start() rejeita com essa mensagem. Se você fez o handshake na mão, cheque o ok antes de ler o data — numa falha não existe data, e ler data.connectionId direto faz você perder o motivo real:

if (!msg.ok) {
  throw Object.assign(new Error(msg.errorLabel || msg.error), { code: msg.error });
}

`error`	O que aconteceu	O que fazer
`trial_required`	A sua conta D-API (a do parceiro) não tem assinatura ativa.	Ative o plano/teste na sua conta.
`number_in_use`	O número já está conectado em outra conta.	Desconecte antes de reconectar.
`invalid_key`	Publishable key inválida, expirada ou revogada.	Gere outra.
`plan_not_ready`, `billing_not_ready`	Cobrança da sua conta ainda não configurada.	Finalize o cadastro de cobrança.
`missing_code`, `access_denied`	A Meta não devolveu o código — geralmente o cliente cancelou.	Peça para repetir.
`config_error`	Configuração do app Meta no servidor da D-API.	Falar com o suporte da D-API.
`onboarding_failed`	A Meta não concluiu o cadastro do número.	Tentar novamente.

trial_required, plan_not_ready e billing_not_ready são sobre a sua conta D-API, não a do seu cliente — é a taxa de plataforma por conexão. A cobrança das conversas continua sendo da conta Meta do cliente.

Cobrança (pass-through)

A cobrança das conversas pela Meta é do seu cliente: durante o Embedded Signup ele usa o método de pagamento da conta Meta dele na WABA. A D-API não cobra as conversas — só a taxa de plataforma por conexão ativa, na sua conta. Lembre o seu cliente de finalizar o método de pagamento no WhatsApp Manager, se a Meta pedir.

Segurança

A publishable key é pública por design: escopo onboard apenas, com rate limit. O pior caso de vazamento é alguém iniciar um popup de Embedded Signup — sem acesso a dados nem envio.
A sua API key secreta nunca vai para o navegador — só no seu backend.
O resultado do onboarding só é entregue para a janela que abriu o popup, e o SDK valida que a mensagem veio do domínio hospedado da D-API.
O access token da Meta volta pela página hospedada no fragmento da URL (#…), que o navegador nunca envia ao servidor — ele não aparece em log de acesso nem em Referer, e a página o apaga da barra de endereço depois de repassar. Daí em diante a responsabilidade é sua: mande para o backend e não persista no browser.

Exemplo completo (HTML puro)

Um único arquivo, sem framework, mostrando o fluxo popup + postMessage passo a passo.

Introdução

API Oficial (SaaS)

Assistente de Integração

Ligações

Webhooks

API Oficial para SaaS (provedor)

Como funciona

Coexistência (manter o app WhatsApp Business)

Webhooks

O resultado chega por dois caminhos

Correlacionar com o seu cliente (`metadata`)

Formato dos eventos (`webhookMode`)

Access token da Meta

Quando a conexão falha

Cobrança (pass-through)

Segurança

Exemplo completo (HTML puro)

​Como funciona

​Coexistência (manter o app WhatsApp Business)

​Webhooks

​O resultado chega por dois caminhos

​Correlacionar com o seu cliente (metadata)

​Formato dos eventos (webhookMode)

​Access token da Meta

​Quando a conexão falha

​Cobrança (pass-through)

​Segurança

Exemplo completo (HTML puro)

Como funciona

Coexistência (manter o app WhatsApp Business)

Webhooks

O resultado chega por dois caminhos

Correlacionar com o seu cliente (`metadata`)

Formato dos eventos (`webhookMode`)

Access token da Meta

Quando a conexão falha

Cobrança (pass-through)

Segurança