Guides WhatsApp Business Account onboarding through Sent, separating dashboard Embedded Signup, organization WABA inheritance, and direct child-profile credentials. Use for WABA connection, Meta signup, profile creation, access-token handling, phone number mapping, completion callbacks, or WhatsApp

WABA Onboarding and Embedded Signup Keep three integration paths distinct. Calling all of them “Embedded Signup” creates wrong API designs and unsafe credential handling. The three paths Path Where it starts Profile behavior Organization Embedded Signup Sent dashboard Connects the organization's WABA through the hosted Meta flow. There is no public Sent endpoint that starts this flow. Organization WABA inheritance POST /v3/profiles Omit whatsapp business account ; the child inherits the organization's connected WABA. Dedicated child profile WABA POST /v3/profiles Supply whatsapp business account.waba id and .access token ; phone number id is optional. If credentials are omitted and the organization has no connected WABA, profile creation returns 422 . Direct WABA credentials are a profile creation feature, not a public “Embedded Signup endpoint.” Authentication Use either: a profile specific key in x api key ; or an organization key in x api key plus x profile id when operating for an existing child profile. Only organization keys may use x profile id ; profile keys receive 403 . x sender id is legacy v1/v2 terminology. Path A: organization Embedded Signup 1. An authorized organization administrator opens the Sent dashboard WhatsApp connection flow. 2. The hosted Meta Embedded Signup UI collects the Meta authorization and WABA/number choices. 3. Confirm the organization shows a connected WABA before creating inheriting children. 4. Record non secret identifiers and audit who completed the action. Do not invent a POST /embedded signup or token exchange endpoint in Sent's public API. If building your own Meta Tech Provider integration outside the Sent dashboard, follow Meta's current documentation and keep that system separate from the Sent API contract. Meta's browser postMessage events use an event field and nested data/session information. Do not rewrite them as Sent webhook sub type envelopes. Path B: inherit the organization WABA Omit whatsapp business account : Use this only after the organization WABA is connected. Inheritance means the tenant shares that WABA boundary; confirm this matches the tenant/brand architecture. Path C: dedicated WABA credentials waba id and access token are required. phone number id is optional: when omitted, the current contract describes provisioning and registration during onboarding. The token needs the applicable WhatsApp Business messaging and management permissions. Inject it from a secret manager. Never log it, echo it, write it to fixtures, return it to the browser, include it in support output, or retain it in general profile storage. Sent does not return it in API responses. Complete the profile Call POST /v3/profiles/{profileId}/complete with the required webHookUrl : 202 means background processing started; there is no final status in that response. 200 can mean the profile was already complete and currently demonstrates lowercase completed . The completion callback can report COMPLETED , SUBMITTED , or failed . Treat the completion callback as its own integration surface. Its envelope uses event , not sub type : Preserve unknown event strings. Verify authenticity using the mechanism Sent documents for the callback endpoint and make processing idempotent. Verify operational readiness Profile WABA ID matches the intended business. Selected number is mapped to the intended profile. Template sharing/inheritance is intentional. A test template can be created with sandbox: true . The completion callback is reachable and idempotent. Returned message IDs are stored against the tenant/profile before webhook processing. Tokens and payment values are absent from logs. For ordinary message and template webhooks, follow Sent's current events reference; those are separate from Meta browser events and profile completion callbacks. Failure routing Failure Next action 422 when credentials are omitted Connect the organization WABA or provide dedicated credentials. 403 with profile key and x profile id Remove x profile id or use an authorized organization key. Wrong WABA/number Stop before completion and correct the profile mapping. Expired/under scoped token Replace it securely; never print it while diagnosing. Completion remains submitted Inspect prerequisite and callback evidence; do not assume final failure from the 202 . Use [references/waba embedded signup spec.md](references/waba embedded signup spec.md), [references/waba onboarding runbook.md](references/waba onboarding runbook.md), and [references/whatsapp sender profile mapping.md](references/whatsapp sender profile mapping.md). Use sender profile architect for tenant boundaries and waba template author for the first template.

waba-embedded-signup