BYON Overview
Bring Your Own Number — use your own WhatsApp Business number with Pipes.bot.
BYON (Bring Your Own Number) lets you connect your own WhatsApp Business number to Pipes.bot. Instead of using shared pool numbers, your customers and contacts message your number directly, and all conversations route to your application.
BYON is available on Pro and Pro+ plans as an add-on at $5/number/month.
Pool vs BYON
| Feature | Pool Numbers | BYON |
|---|---|---|
| Number ownership | Shared Pipes.bot numbers | Your own WhatsApp Business number |
| Conversation model | 1:1 — you and your bot | N:M — any sender to your app |
| Onboarding | Send a WhatsApp code | Meta Embedded Signup flow |
| API key | Tenant API key (pk_) | Per-App API key (ak_) |
| Delivery | WebSocket | Webhook + WebSocket (dual) |
| Use case | Personal AI agent | Products, services, multi-user apps |
| Plans | All plans | Pro and Pro+ only |
How it works
BYON is built around the App model. Each App is an application endpoint that owns one or more BYON numbers. All messages on those numbers route to the App owner.
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Customer A │────►│ │ │ │
└──────────────┘ │ Your BYON │────►│ Your App │
┌──────────────┐ │ Number │ │ (webhook + │
│ Customer B │────►│ │ │ WebSocket) │
└──────────────┘ └──────────────┘ └──────────────┘- Create an App — Choose a slug, get an
ak_API key - Onboard a number — Use Meta's Embedded Signup to connect your WhatsApp Business number
- Configure delivery — Set a webhook URL for your App (WebSocket also available)
- Receive messages — All messages from any sender on your BYON number are delivered to your App
- Reply — Use the REST API with your
ak_key to send responses
API versions
Each App uses one of two API contracts for inbound events and replies:
- API v2 (new Apps): Meta's webhook data delivered as-is inside a small envelope, including statuses and every other Meta field, with no stored conversations. Every field Meta sends for WhatsApp users who hide their phone number behind a username (BSUIDs) reaches you.
- Legacy (Apps created before API v2): Meta-like payloads reshaped by Pipes.bot, with a
conversationIdper sender.
Your App's settings page shows which version it uses. Upgrading a legacy App is one-way. See BYON API v2 Migration and API v2 Example Payloads.
Next steps
- BYON Quickstart — Run the demo app end-to-end
- Creating an App — Set up your first BYON App
- Embedded Signup — Onboard WhatsApp Business numbers
- Webhook Delivery — Configure message delivery
- Number Management — Monitor and manage BYON numbers
- BYON API v2 Migration — Move your App to API v2