- You are a regular D-API user (your secret API key stays in your backend).
- Your customer connects their own number; the connection lives under your account,
identified by a
connectionId. - Meta billing belongs to your customer (they use their own payment method on the WABA). D-API only charges you the per-connection platform fee.
How it works
Meta’s Embedded Signup does not run on your SaaS domain (Meta requires registered domains). That is why the flow runs on a page hosted by D-API (connect.d-api.cloud), which you open as a popup. The result comes back to your
app via postMessage. Your domain does not need to be registered with Meta.
1
Create a publishable key
A publishable key (The response returns the
pk_live_…) is public on purpose: it only starts the
onboarding — it does not send messages or read data. Create one in the Dashboard
under Integrations → Publishable Keys, or via the API with your secret API key:key only once — store it.2
Open connect in your frontend
Use the This opens the hosted popup, runs the Embedded Signup, and resolves with the
d-api-sdk package (entry d-api-sdk/connect):connectionId (and the Meta access token). You can also
do the handshake “by hand”, in plain HTML — see the
full example.3
Associate the connectionId with your customer
Store the returned
connectionId in your database, linked to the corresponding
customer. From then on, that number is a regular D-API connection.4
Send messages from your backend
With your secret API key (never in the browser), the
connectionId is the
sessionId in the regular send routes:Coexistence (keep the WhatsApp Business app)
By default the flow creates/onboards a new number on the Official API. If your customer wants to keep the WhatsApp Business app on the same number (coexistence), passmode: "coexistence":
connectionId. The difference is what Meta asks the customer to do:
scan a QR code in the WhatsApp Business app. History sync starts automatically and
may take a few minutes; tell the customer to keep the app open.
Webhooks
You set the connection’s webhook inconnect.start({ webhookUrl }), and you can
change it later through the session update route. Events arrive with the
connection/session id in the payload — so you can point every connection to a single
endpoint and dispatch by connectionId.
The result arrives through two paths
Every connection created through the hosted connect is announced twice, with nothing to configure:connect.start()resolves in the browser with theconnectionIdand the access token;- a
session.createdwebhook goes to that connection’swebhookUrl, with all the data — including the access token and yourmetadata.
window.opener, so the postMessage that
start() waits for never arrives: the promise may reject with “Conexão cancelada”
while the connection was created normally. The same applies to native app webviews.
Correlating with your customer (metadata)
metadata is your own free-form JSON, stored with the connection and returned
intact in data.metadata of session.created. It is what lets you link the
connection to the tenant without depending on the synchronous return:
start() throws an error before opening the window. Store
identifiers there, not entire business objects.
metadata is optional and new in SDK version 1.3.0. Integrations on 1.2.0
or earlier keep working with no changes — they just receive metadata: {}
in the event.Event format (webhookMode)
You choose the format in which events arrive:
webhookMode).
Meta access token
Theconnect.start() result also includes the connection’s Meta access token,
already decrypted — useful if you want to call the Graph API directly (for
example, to manage templates or the catalog outside D-API):
accessTokenKind: "permanent", accessTokenExpiresAt: null) — that is the normal case here. The other
types appear when the token was swapped manually: long_lived (~60 days) and
short_lived (~1 hour).
If you prefer the token not to travel through the browser, ignore the field and
fetch it from your backend when you need it, with your secret API key:
When the connection fails
If onboarding does not complete, the hosted window shows the reason in Portuguese, with the code below it — a screenshot of it is enough for support. The same reason comes back to your app:connect.start() rejects with that message. If you did the
handshake by hand, check ok before reading data — on failure there is no
data, and reading data.connectionId directly makes you lose the real reason:
trial_required, plan_not_ready, and billing_not_ready concern your
D-API account, not your customer’s — this is the per-connection platform fee.
Conversation billing remains on the customer’s Meta account.Billing (pass-through)
Meta’s conversation billing belongs to your customer: during Embedded Signup they use the payment method of their own Meta account on the WABA. D-API does not charge for conversations — only the platform fee per active connection, on your account. Remind your customer to finish setting up the payment method in WhatsApp Manager, if Meta asks for it.Security
- The publishable key is public by design:
onboardscope only, with rate limiting. The worst case of a leak is someone starting an Embedded Signup popup — with no access to data and no sending. - Your secret API key never goes to the browser — only to your backend.
- The onboarding result is delivered only to the window that opened the popup, and the SDK validates that the message came from D-API’s hosted domain.
- The Meta access token comes back through the hosted page in the URL fragment
(
#…), which the browser never sends to the server — it does not show up in access logs or inReferer, and the page removes it from the address bar after handing it off. From then on it is your responsibility: send it to your backend and do not persist it in the browser.
Full example (plain HTML)
A single file, no framework, showing the popup + postMessage flow step by step.
