Setup Links

A Setup Link is a one-time URL you give your customer. They click it, log into their Facebook Business account, authorize your app, and a WABA + phone numbers get provisioned automatically — no manual config on your side.

This is the recommended onboarding flow for any multi-tenant SaaS.

You ──► generate Setup Link ──► send to customer
                                       │
                                       ▼
                          Customer clicks ──► Meta's Embedded Signup
                                                       │
                                                       ▼
                              Customer authorizes your app, picks/verifies phone
                                                       │
                                                       ▼
                          We receive the OAuth callback ──► provision WABA + phones
                                                       │
                                                       ▼
                                  Webhook to you ──► `whatsapp.phone_number.created`

Generating a setup link

POST /admin/tenants/{tenantId}/customers
{
  "name": "Clínica San Lucas",
  "external_id": "clinic_001"
}

POST /admin/customers/{customerId}/setup-links
{
  "successRedirectUrl": "https://your-app.com/onboarding/success",
  "failureRedirectUrl": "https://your-app.com/onboarding/failed",
  "expiresAt": "2026-05-25T23:59:59Z"
}

{
  "id": "abc123-...",
  "url": "https://cloud.gosendapi.com/signup/abc123-...",
  "status": "pending",
  "expiresAt": "2026-05-25T23:59:59Z",
  "successRedirectUrl": "https://your-app.com/onboarding/success",
  "failureRedirectUrl": "https://your-app.com/onboarding/failed"
}

What the customer sees

When they open the URL:

1. Landing page with your project name and a “Continue with Facebook” button
2. Meta’s Embedded Signup popup — they choose:
   • Which Business Manager (or create one)
   • Which phone number to register (or buy a new one via Meta)
   • Which display name to use
3. PIN verification for the phone (SMS or call)
4. Permissions screen — they authorize your app to send/receive on the WABA
5. Redirect to your successRedirectUrl with ?status=success&waba_id=...

The whole flow takes 2-5 minutes if they already have a Facebook Business account, 15-30 minutes if creating from scratch.

What happens server-side

After the customer completes the flow:

1. Meta calls our OAuth callback
2. We exchange the auth code for a long-lived System User access token
3. We encrypt and store the token
4. We fetch the phone number metadata from Meta
5. We persist the WABA + phone(s) linked to the Customer
6. We fire webhooks to your endpoint:
   • whatsapp.phone_number.created — with the new phone_number_id
7. We redirect the customer’s browser to your successRedirectUrl

By the time the customer lands back on your app, the WABA is ready to send/receive.

Setup link properties

Theming the landing page

You can pass a themeConfig to make the landing match your brand:

{
  "themeConfig": {
    "primaryColor": "#10B981",
    "backgroundImage": "https://your-cdn.com/onboarding-bg.jpg",
    "logoUrl": "https://your-cdn.com/logo.png",
    "companyName": "Acme SaaS"
  }
}

Reconnecting a number

If a customer’s access token expires (revoked password, deauthorized our app, etc.), the phone goes into disconnected status. Generate a reconnect setup link to walk them through reauthorization without re-creating the WABA:

POST /admin/customers/{customerId}/setup-links
{
  "reconnectPhoneNumberId": "<internal_phone_id>"
}

The flow is identical from the customer’s perspective, but the existing WABA’s token is refreshed (no new WABA created).

Best practices

• Set successRedirectUrl to a page that polls for the new phone_number_id until the webhook arrives. Sometimes the redirect happens before our DB has the WABA persisted (rare, but possible).
• Show a “what to expect” page before the link. Customers panic when they see Facebook OAuth — explain what’s about to happen.
• Pre-populate the customer’s email in your CRM with the link, so they have it for later if they close the browser mid-flow.
• Add a timeout to expiresAt of 7-30 days. Shorter = more secure but more friction if the customer takes time to act.

Common issues

Coming next

• White-label landing: full-page custom domain like signup.yourcompany.com
• API key bootstrap: customer immediately gets a per-WABA token to use in their own systems
• Multi-step onboarding: pre-collect info before Meta flow, post-survey after

See Customers concept for the full lifecycle.