waba-embedded-signup

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:

{
  "name": "Tenant Support",
  "description": "Synthetic child profile",
  "short_name": "SUPPORT",
  "inherit_templates": true,
  "billing_model": "organization",
  "sandbox": true
}

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

{
  "name": "Dedicated Tenant",
  "whatsapp_business_account": {
    "waba_id": "123456789012345",
    "phone_number_id": "987654321098765",
    "access_token": "<injected secret>"
  },
  "sandbox": true
}

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:

{
  "webHookUrl": "https://example.com/webhooks/profile-complete",
  "sandbox": true
}

• 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:

{
  "event": "COMPLETED",
  "profile_id": "00000000-0000-0000-0000-000000000000",
  "timestamp": "2026-08-09T12:00:00Z"
}

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-onboarding-runbook.md, and references/whatsapp-sender-profile-mapping.md. Use sender-profile-architect for tenant boundaries and waba-template-author for the first template.