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 and marks numbers as degraded or down if the token becomes invalid.

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": "tok_abc123..."
}

Usage

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

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

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 } = 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