> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# BSP Transfer / Number Porting

> Move your existing WhatsApp Business Account from Infobip, Twilio, Vonage, MessageBird, or any other BSP to Orbit without losing your number, templates, or quality rating.

# BSP Transfer / Number Porting

Moving a WABA between Business Solution Providers (BSPs) is a managed Meta process. You keep:

* Your phone number
* Your display name (as-approved)
* Your approved templates
* Your quality rating (in most cases)
* Your messaging-limit tier

You **don't** keep:

* Historical message data — WhatsApp stores messages on Meta's side only for 30 days, and the conversation metadata is BSP-scoped. See [What happens to message history](#what-happens-to-message-history) below.
* Historical webhook delivery logs from your old BSP (those stay on their system).
* Saved templates that never got approved on the old BSP (those don't exist at Meta).

Plan 1–3 business days for the full migration. Outbound sending is paused for a window that's typically \< 15 minutes but can reach a few hours depending on the releasing BSP.

## Pre-migration checklist

Work through this **before** you initiate the transfer. Missing items cause the longest delays.

* [ ] Admin access on the **source BSP's WhatsApp management console** (Infobip, Twilio, etc.)
* [ ] Admin access on your **Meta Business Manager**
* [ ] A Facebook account with admin on the Business Manager that **currently owns** the WABA
* [ ] The WABA's 15-digit ID from Meta Business Manager → WhatsApp Accounts
* [ ] A record of approved templates (export from source BSP — you won't need to re-approve, but you will need to sync template names into Orbit)
* [ ] An outage window — 15 min typical, 4 h worst case
* [ ] Downstream consumers paused (campaigns, drip sequences) during the window
* [ ] A live webhook endpoint you want to point Orbit at (or use Orbit's inbox)

## Stage 1 — Release the WABA from the source BSP

Each BSP exposes this differently. Common recipes:

### From Twilio

1. **Console → Messaging → Try It Out → WhatsApp → Senders**
2. Open the sender, click **Migrate / Release**
3. Choose **Release to another BSP**. Twilio asks for a reason; "Switching to new BSP" is accepted.
4. Twilio sends a confirmation email to the Meta admin; approve it within 24 h.
5. Within Meta Business Manager, the WABA now shows **Solution Partner: Meta (unassigned)**.

### From Infobip

1. **Channels → WhatsApp → Senders** → open the sender
2. **Actions → Release from BSP**
3. Infobip emails their compliance team; they release typically within 1 business day.

### From Vonage

1. **Your Applications → WhatsApp → Settings → Release BSP ownership**
2. Confirm in Meta Business Manager email.

### From MessageBird / Bird

1. **Channels → WhatsApp → Settings → Change Provider → Release**.
2. Support ticket may be needed; Bird is slower than Twilio/Infobip for release.

### From 360dialog

1. Contact their support. 360dialog routes all releases through account managers — expect 1–2 business days.

### From Meta Cloud API (direct, no BSP)

Easiest. You're already on Meta's direct infrastructure and just need to assign Orbit as the new partner. Skip to Stage 2.

## Stage 2 — Assign Orbit as the new BSP

From Meta Business Manager:

1. **Settings → Business Assets → WhatsApp Accounts → pick your WABA**
2. **Partners** tab → **Add Partner**
3. Enter Devotel's Business Manager ID: `2047834185345896`
4. Role: **Manage WhatsApp Accounts**
5. Apply

You'll see Orbit listed as a Partner. The WABA is not yet routed to Orbit's sending infrastructure — Stage 3 does that.

## Stage 3 — Connect through Orbit's embedded sign-up

This is the same flow as a new WABA, but with two differences:

1. In the embedded popup, when asked **Create new or select existing**, pick **Select existing**.
2. Choose the WABA you just migrated.

Orbit claims the number and starts routing. You'll see status **Connected** in **Settings → Channels → WhatsApp**.

## Stage 4 — Sync templates

Meta keeps the approved templates but they need to be visible on Orbit's side for our template picker to show them.

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/templates/sync \
  -H "X-API-Key: dv_live_sk_..."
```

Or, from the dashboard: **Channels → WhatsApp → Templates → Sync from Meta**.

This pulls every approved, pending, and rejected template on the WABA and stores it in your Orbit account. Run-time takes \< 10 seconds per 100 templates.

## Stage 5 — Point webhooks + start sending

Meta delivers inbound messages and delivery receipts to Orbit's callback URL. Embedded Signup wires this automatically; if you enter it by hand in your WABA's **Configuration → Webhooks** panel, copy it verbatim — including the `/api/v1` prefix. A bare `/whatsapp/webhook` (no `/api/v1`) returns 404 and Meta silently stops delivering inbound messages.

```
https://api.orbit.devotel.io/api/v1/whatsapp/webhook
```

Then point your own backend at Orbit for delivery events: **Settings → Webhooks → New Endpoint**, subscribe to `message.received`, the delivery-lifecycle events `message.sent`, `message.delivered`, `message.read`, `message.failed`, and the template events `whatsapp.template.approved`, `whatsapp.template.rejected`, `whatsapp.template.quality_update`. Signature verification uses the endpoint secret Orbit generates — [details](/webhooks/security).

Send a test message. If it delivers with a normal `sent → delivered → read` progression, migration is complete.

## Migration checklist — copy-paste for your ops team

```
MIGRATION PLAN — WhatsApp BSP Transfer

Target window: ___________
Acceptable outage: 30 min (typical), 4 h (worst case)

T-24h  ☐ Notify downstream teams (marketing, CRM)
T-24h  ☐ Export approved template list from source BSP
T-1h   ☐ Pause drip campaigns + scheduled blasts
T-1h   ☐ Alert on-call for the window

T-0    ☐ Stage 1: Source BSP — initiate release
T-0    ☐ Stage 2: Meta BM — add Orbit as partner
T-0    ☐ Stage 3: Orbit embedded flow — select existing WABA
T-0    ☐ Stage 4: Sync templates (API or dashboard)
T-0    ☐ Stage 5: Update webhook endpoints

T+15m  ☐ Send test template to internal number
T+15m  ☐ Verify delivery receipt fires
T+30m  ☐ Resume drip campaigns
T+30m  ☐ Monitor quality rating for 24 h
```

## What happens to message history

**In-flight messages** at the moment of migration: in-flight means Meta has the payload but hasn't delivered yet. Meta completes delivery on the new BSP; delivery receipts route to Orbit's webhook.

**Past conversations** stay in the user's WhatsApp app. If they reply to a pre-migration message after you've migrated, Orbit receives the inbound message normally.

**Historical DLR logs** — source BSP's internal logs stay on their system. Export them before the migration window if you need them for reporting. Orbit only sees events from the migration moment onward.

**Templates** — approved templates carry over. Template analytics (sent / delivered / read counts) reset because they're BSP-scoped.

**24h session windows** — any open sessions (user messaged you in the last 24 h) stay open on Meta's side and you can reply freeform from Orbit the moment the connection is complete.

## Quality rating — what to watch

Your quality score is WABA-scoped, not BSP-scoped, so it carries across. But Meta re-evaluates based on aggregate sending in a rolling window. The first 24–72 h on Orbit:

* Don't spike volume — send at a pace comparable to pre-migration
* Avoid sending templates that had high block-rate on the old BSP; those metrics still count against you
* Make sure opt-out handling is wired — unsubscribes (STOP / BLOCK) must be respected

Quality can downgrade from Green → Medium if the first blast on Orbit triggers user blocks. Audit your template body for trust signals (sender name, clear purpose) before the first post-migration send.

## Rollback

Until Stage 3 completes, you can roll back simply by re-assigning the source BSP as the active partner in Meta Business Manager. After Stage 3 you'd need to re-initiate a release from Orbit to the old BSP — the old BSP may charge a re-onboarding fee.

If the migration goes sideways, email [whatsapp-support@devotel.io](mailto:whatsapp-support@devotel.io) with your WABA ID — we have a direct escalation path to Meta's BSP operations team.

## Troubleshooting

<Accordion title="Source BSP refuses to release">
  They're probably in a contract dispute or an unpaid invoice. Resolve the finance issue first — Meta won't force a release. If the BSP is unresponsive for >14 days you can file a BSP Transfer Request directly with Meta.
</Accordion>

<Accordion title="Meta shows WABA 'unassigned' but Orbit doesn't see it">
  Re-run the embedded sign-up and pick "Select existing". If the WABA still doesn't appear in the list, your Facebook account needs admin role on the Business Manager that owns the WABA — not just on Orbit's Partner access.
</Accordion>

<Accordion title="Templates didn't sync">
  Meta's GraphQL template endpoint rate-limits at 1 req/second. A very large template catalog (1,000+) takes several minutes. If still empty after 10 min, trigger the sync again; it's idempotent.
</Accordion>

<Accordion title="Messaging limit tier dropped after migration">
  The tier itself doesn't drop, but the trailing-7-day volume counter might register a gap. Keep sending at a healthy pace with green quality and the tier promotes automatically within 3–5 days.
</Accordion>