Hosted WhatsApp Onboarding

Let your customers connect their own WhatsApp Business numbers to your platform — through a Lodgestory-hosted page, driven entirely by API. No Lodgestory login, no Lodgestory branding.

TL;DR

• What it is — your backend mints a one-time onboarding link; your customer opens it, signs in with Facebook, picks their WhatsApp number, and it lands as a connected channel in your workspace — tagged with your tenant reference.
• Who it's for — partners building on the Lodgestory API who onboard many businesses (tenants) onto WhatsApp and want their users to never leave their product's context.
• Top outcome — WhatsApp onboarding becomes a single API call plus a redirect. Each tenant keeps ownership of their WhatsApp Business Account and is billed by Meta directly — Lodgestory adds no markup.

At a glance

What is Hosted WhatsApp Onboarding?

If you run a platform whose customers each need their own WhatsApp number — a booking engine, a property-management system, a vertical CRM — the hard part of WhatsApp is not sending messages. It is onboarding: Meta's Embedded Signup flow, phone registration, two-step PINs, webhook subscriptions, and all the recovery paths when a PIN is forgotten or a number needs re-verification.

Hosted WhatsApp Onboarding packages all of that behind one API call:

1. You call the Lodgestory API with your tenant's reference and a return URL. You get back a one-time hosted link.
2. Your tenant opens the link on a neutral page that shows your name, signs in with Facebook, and picks the WhatsApp number to connect. Lodgestory guides them through PIN entry and, when needed, SMS/voice re-verification — with no dead ends.
3. Lodgestory registers the number, connects it as a channel in your workspace, and sends the tenant back to your URL with your tenant reference and the new channel id.

From that moment you can send and receive messages for that tenant through the Lodgestory public API, route replies with webhooks, and manage everything programmatically.

Ownership and billing stay clean: the WhatsApp Business Account belongs to your tenant. They add their own payment method during signup, and Meta bills them directly for conversations. Lodgestory never rebills or marks up Meta's charges.

How it all works

sequenceDiagram
    participant P as Your backend
    participant L as Lodgestory API
    participant T as Tenant's browser
    participant M as Meta

    P->>L: POST /channel-onboarding/{org}/links (tenantRef, redirectUrl)
    L-->>P: onboardingUrl (shown once)
    P->>T: Send / redirect tenant to onboardingUrl
    T->>L: Open hosted page
    T->>M: Facebook sign-in + WhatsApp Embedded Signup
    M-->>T: Account & number shared
    T->>L: Pick number, enter two-step PIN
    L->>M: Register number, attach messaging infrastructure
    L-->>T: Redirect to your redirectUrl?status=success&tenant_ref=...&channel_id=...
    L-->>P: channel.connected webhook (if subscribed)
    P->>L: GET /links/{linkId} — confirm COMPLETED + channelId
    P->>L: Send messages for this tenant via the messaging API

Every link moves through a simple lifecycle you can observe from the API:

stateDiagram-v2
    [*] --> PENDING: link created
    PENDING --> IN_PROGRESS: tenant signed in with Facebook
    IN_PROGRESS --> FINALIZING: number being connected
    FINALIZING --> COMPLETED: channel live
    FINALIZING --> IN_PROGRESS: connect failed — tenant can retry
    PENDING --> REVOKED: you revoke
    IN_PROGRESS --> REVOKED: you revoke
    COMPLETED --> [*]

EXPIRED is reported for any link whose lifetime lapsed before completion. Expired and revoked links show the tenant a friendly "ask your provider for a new link" screen — nothing breaks.

Recipe: onboard a tenant end to end

Prerequisite: an API bearer token for an Admin or Account Owner — see Accounts & sign-in for the token flow.

1. Mint a link when your tenant clicks "Connect WhatsApp" in your product:

curl -X POST "https://api.lodgestory.com/api/wp-crm/channel-onboarding/{organisationId}/links" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantRef": "tenant_8412",
    "partnerDisplayName": "Acme Bookings",
    "redirectUrl": "https://app.acme.com/integrations/whatsapp/return",
    "expiresInMinutes": 1440
  }'

Response:

{
  "link": {
    "id": "6f0c1c8e-...",
    "tenantRef": "tenant_8412",
    "status": "PENDING",
    "channelId": null,
    "expiresAt": "2026-08-03T10:00:00.000Z"
  },
  "onboardingUrl": "https://lodgestory.com/onboard/whatsapp/wG4t...one-time-token"
}

The onboardingUrl is returned once and never again — hand it to the tenant immediately or store it. Links are cheap; mint a new one any time.

2. Send the tenant to onboardingUrl — open it in a new tab or redirect. The page shows your partnerDisplayName, not Lodgestory.

3. The tenant connects — Facebook sign-in, number selection, six-digit two-step PIN. If the PIN is wrong or the number needs re-verification, the page walks them through an SMS or voice-call code without restarting.

4. Handle the return redirect. On success the tenant lands on:

https://app.example.com/integrations/whatsapp/return?status=success&tenant_ref=tenant_8412&channel_id=91b2...

Treat the redirect as a hint, not the source of truth — the tenant can close the tab before it fires.

5. Confirm from your backend (authoritative):

// Node 18+ — no dependencies
const res = await fetch(
  `https://api.lodgestory.com/api/wp-crm/channel-onboarding/${orgId}/links/${linkId}`,
  { headers: { Authorization: `Bearer ${token}` } },
);
const link = await res.json();

if (link.status === 'COMPLETED') {
  // Map the connected channel to your tenant and enable WhatsApp in your product
  await db.tenants.update(link.tenantRef, { whatsappChannelId: link.channelId });
}

Poll every few seconds while your tenant is mid-flow, or skip polling entirely by subscribing to the channel.connected event in Webhooks and matching the channel from your stored link.

6. Start messaging. The channelId is exactly the channel id the messaging API takes — create a chat and send from your tenant's new number the moment the link completes.

curl -X POST "https://api.lodgestory.com/api/wp-crm/messaging/create-chat" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"organisationId":"{organisationId}","channelId":"91b2...","countryCode":"91","phoneNumber":"9999999999","firstName":"Asha"}'

API reference

All four management endpoints live under api/wp-crm/channel-onboarding/{organisationId} and require an Admin or Account Owner bearer token. Interactive reference: https://api.lodgestory.com/api/docs/public → Channel Onboarding.

Create fields

Statuses: PENDING → IN_PROGRESS → FINALIZING → COMPLETED, plus REVOKED and the computed EXPIRED.

Errors you may see: 404 unknown link id (also returned for links belonging to another workspace), 409 on revoke after completion, and — during a tenant's flow — a phone_already_connected conflict if that WhatsApp number is already live in another workspace.

Rate limits: 30 link creations and 60 list reads per minute, 120 polls per minute, per organisation.

What your tenant sees

A neutral, mobile-friendly page titled "Connect WhatsApp Business" with your display name — no Lodgestory branding:

1. Connect with Facebook — Meta's official Embedded Signup in a popup. The tenant creates or reuses their Meta Business account, shares (or creates) a WhatsApp Business Account, and adds their payment method with Meta.
2. Pick the number — when the account has more than one number, a selection screen; a single account with a single number skips straight ahead.
3. Two-step PIN — the six-digit PIN belonging to that number. A wrong or forgotten PIN never dead-ends: the page offers an SMS or voice-call verification code so the tenant can verify and set a new PIN on the spot.
4. Done — a success screen, then an automatic return to your redirectUrl.

Closing the tab mid-flow is safe: reopening the same link resumes at the number-selection step without a second Facebook sign-in.

Security notes

• Link URLs are unguessable and shown exactly once at creation; Lodgestory does not store them in readable form.
• Links are single-completion, time-limited, and revocable at any moment before completion.
• The tenant's Meta credentials never pass through your systems, and Meta access tokens are never exposed to the tenant's browser.
• redirectUrl must be HTTPS, and it is fixed at link creation — nothing the tenant does can change where they are sent.

Limits & good to know

• One number, one workspace. A WhatsApp number can be connected to a single Lodgestory workspace at a time. A tenant bringing a number that is live elsewhere sees a clear error and your poll shows the failure reason.
• Meta onboarding velocity. Meta limits how many new businesses can complete Embedded Signup per rolling week. Planning a bulk migration of tenants? Talk to us first so the rollout is sized correctly.
• Reconnecting is safe. Running a link for a number that is already connected to your workspace re-verifies and refreshes it — no duplicates.
• Links are not precious. Expired, revoked, or lost links cost nothing — mint a fresh one.

FAQ

Who pays for WhatsApp messages?
Your tenant, directly to Meta, on the payment method they add during signup. Lodgestory adds no markup.

The tenant says the Facebook popup never opened.
Ad or popup blockers. The page detects this and shows instructions; the tenant reloads after allowing popups.

The redirect never hit my server but the tenant says they finished.
The redirect is best-effort — always confirm with GET /links/{linkId} or the channel.connected webhook.

Can I brand the page with my logo and colors?
The page is neutral and shows your partnerDisplayName. Deeper theming is on the roadmap — tell us what you need.

Can I onboard other channels this way?
Hosted onboarding covers WhatsApp Business today. Instagram, Messenger, Email, and Web Chat are connected from the Lodgestory dashboard.

Related

• Accounts & sign-in — getting a partner API token.
• Webhooks — subscribe to channel.connected and message events.
• Connections — the in-dashboard way to connect channels.
• Interactive API reference — https://api.lodgestory.com/api/docs/public.