Embedded Signup

BYON numbers are onboarded through Meta's Embedded Signup — a guided flow that connects a WhatsApp Business number to Pipes.bot and grants the necessary API permissions.

Starting the flow

From your App's detail page, click Add Number. This opens Meta's Embedded Signup dialog where the number owner:

1. Logs into their Meta Business account
2. Selects or creates a WhatsApp Business Account (WABA)
3. Selects the phone number to connect
4. Grants Pipes.bot permission to manage messages

What happens during signup

When the flow completes, Pipes.bot automatically:

All of this happens in the background — you'll see the new number appear in your App's number list within a few seconds.

Token lifecycle

The access token provided by Meta is a System User Token with a long expiry. Pipes.bot monitors token health. Each number's own status is active or unhealthy (driven by whether its token is broken). The healthy / degraded / down values you see are the App-level aggregate across its numbers — see Number Management.

If a token breaks (e.g. the user revokes access in Meta Business Manager), the number's health status changes and you'll see a warning in your dashboard. To fix it, remove the number and re-run Embedded Signup.

Who can complete signup

The person completing the Embedded Signup flow must have admin access to the Meta Business Account that owns the WhatsApp number. This is typically:

• Your customer (if you're building a product for others)
• You (if connecting your own business number)

Programmatic signup via API

If you need to start the Embedded Signup flow programmatically (e.g. from your own onboarding UI), use the token endpoint to generate a one-time signup URL.

POST /v1/apps/token
Authorization: Bearer ak_your_app_key
Content-Type: application/json

Request

Response

{
  "token": "<JWT>",
  "expiresAt": "2025-01-15T10:45:00.000Z"
}

The token is an HS256 JWT valid for 15 minutes and single-use — its JTI is consumed when signup completes, so it can onboard exactly one number.

Usage

Use the returned token to redirect the user to the signup flow:

https://app.pipes.bot/apps/{slug}?token={token}

The signup URL completes by calling POST /v1/apps/onboard with the token and Meta's authorization code; on success the user is redirected to your redirectUrl with ?numberId=&phone= appended.

Example

const res = await fetch("https://api.pipes.bot/v1/apps/token", {
  method: "POST",
  headers: {
    Authorization: "Bearer ak_your_app_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    redirectUrl: "https://yourapp.com/onboarding/complete",
    metadata: { partnerId: "partner_123" },
  }),
});

const { token, expiresAt } = await res.json();

// Redirect the user to complete Embedded Signup
const signupUrl = `https://app.pipes.bot/apps/your-app-slug?token=${token}`;

The metadata object is stored with the onboarding session and can be used to correlate the signup with your internal records.

Next steps

• Webhook Delivery — Set up message delivery for your App
• Number Management — Monitor connected numbers