BYON
Number Management
View, monitor, and manage your BYON numbers.
After onboarding numbers via Embedded Signup, you can manage them from your App's detail page in the dashboard.
Viewing numbers
Each BYON number shows:
| Field | Description |
|---|---|
| Phone number | The connected WhatsApp Business number |
| Display name | The WhatsApp Business display name |
| Health | Per-number status: active or unhealthy |
| Connected since | When the number was onboarded |
| Conversations | Active conversation count |
Health status
Each BYON number has a per-number status driven by whether its Meta access token is broken:
| Status | Meaning | Action needed |
|---|---|---|
| active | Token is valid, messages flow normally | None |
| unhealthy | Token is broken (revoked/expired) — sends and receives fail | Disconnect and re-run Embedded Signup |
App-level aggregate
Your App rolls its numbers up into an aggregate shown as healthy, degraded, or down:
- healthy — all numbers
active - degraded — at least one number
unhealthy - down — all numbers
unhealthy
Disconnecting a number
Via dashboard
To remove a BYON number from your App:
- Navigate to the number in your App's detail page
- Click Disconnect
- Confirm the action
Via API
You can also disconnect a number programmatically:
curl -X DELETE https://api.pipes.bot/v1/pool-numbers/pn_abc123 \
-H "Authorization: Bearer ak_your_app_key"Response
{ "success": true }Error reference
| Status | Code | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or invalid Authorization header |
| 403 | BYON_ONLY | Requires an ak_ key (not pk_) |
| 403 | FORBIDDEN | The number does not belong to your App |
| 404 | POOL_NUMBER_NOT_FOUND | Pool number not found |
| 404 | NOT_BYON_NUMBER | Only BYON numbers can be removed via API |
| 500 | INTERNAL_SERVER_ERROR | Failed to disconnect number |
What happens when you disconnect
Disconnecting a number:
- Removes the number from your App
- Cleans up associated conversations
- Revokes the webhook subscription with Meta (best-effort)
- The number can be re-onboarded later if needed
Billing
Each active BYON number costs $5/month, billed as part of your Pro or Pro+ subscription. Disconnecting a number stops billing for it at the end of the current billing cycle.