Get started
Pair a WhatsApp number
Pairing always happens inside the Shiftwa dashboard — not via the API. This page walks through the flow and what each status means.
Pairing steps
- Open app.shiftwa.dev → Numbers → click Add number.
- Enter the number in E.164 format (e.g. +6281234567890) and an optional label (e.g. 'alfi', 'cs-jakarta'). The label becomes the per-request sender hint.
- On your phone, open WhatsApp → Settings → Linked devices → Link a device, then scan the QR shown in the modal.
- Wait a few seconds. Status flips to active and the modal closes automatically.
Number lifecycle
The status of each number is visible in the dashboard and in the GET /v1/numbers response. Only numbers in active or idle take pool rotation traffic.
| Status | Meaning |
|---|---|
connecting | Gateway is preparing the socket. QR not yet available. |
qr | QR is ready to scan. Auto-refreshes every ~15s until paired. |
active | Sender is healthy, ready to take send requests. |
idle | Connected but no recent traffic. Still able to send. |
disconnected | Session dropped (phone off, logged out, etc.). Operator must rescan the QR in the dashboard. |
banned | WhatsApp flagged this number. Contact support — we can help escalate. |
Best practice
- Pair at least 2 numbers for mission-critical traffic — automatic rotation absorbs the hit if one drops.
- Use descriptive labels (e.g. 'alfi-cs', 'budi-billing'). The same label becomes the per-request sender hint.
- Avoid personal phone numbers. Use dedicated business numbers on a separate plan.