Numbers overview
Each WhatsApp number in your account sends and receives messages as a device linked to the WhatsApp of that phone, the same way WhatsApp Web works. The phone keeps working, and Turbo Notify shows up under Linked devices with the name of your organization (on WhatsApp Business for Android, with the name the person typed when linking).
Main number and extra numbers
| Main number | Extra numbers | |
|---|---|---|
| How many | One per account | As many as your plan allows |
| Alias | Always main | You choose it when adding the number |
| Adding and pairing | In the dashboard, with a QR code or a code | Adding in the dashboard or through the API. Pairing in the dashboard (QR code or code) or through the API (code or QR code) |
| Billing | Included in the plan | Per number, see Billing |
Every message, contact and group route lives under the number:
/v1/numbers/{ref}/....
Every number also has an id (like num_0a1b2c3d4e5f60718293a4b5c6d7e8f9),
generated by Turbo Notify, that never changes, even if the alias is renamed.
On any route, the id works in place of the alias ({ref} accepts both).
An alias cannot start with num_.
Lifecycle of an extra number
| Step | What you do | Resulting status | Page |
|---|---|---|---|
| Add | POST /v1/numbers | pending | Adding |
| Pair | In the dashboard, Link number. Through the API, POST /v1/numbers/{ref}/pair. Both with a QR code or a code | pairing, then connected or failed | In the dashboard and with the API |
| Track | GET /v1/numbers/{ref} or number.* webhooks | the current status | Status |
| Disconnect and reconnect | POST /v1/numbers/{ref}/disconnect and .../connect | disconnected, connecting, connected | Connection |
| Remove | DELETE /v1/numbers/{ref} | removed right away, or a scheduled removal (scheduled_deletion_at) at the end of the period already paid, with its usual status until then | Removal |
A connected number can go down: the connection to WhatsApp can drop, Turbo Notify can move the connection internally (maintenance, load balancing, recovery from an internal failure), or someone can remove the connection under Linked devices on the phone.
When Turbo Notify can bring the number back on its own, the status is
reconnecting while that happens. If the number comes back within the
automatic reconnection window (about one minute), no webhook is sent: as far
as you are concerned, the number never went down. If it does not come back in
time, you receive number.disconnected, with at set to the moment the
number went offline, and Turbo Notify keeps trying to reconnect.
When the drop needs you, the notice arrives right away. If the connection was
removed on the phone, you receive number.revoked and the number has to be
paired again. The reason field of number.disconnected and
number.revoked tells you what happened, see
Reasons.
Tracking changes
Two ways, which can be combined:
- Webhooks
number.*tell you as soon as the number connects, disconnects, fails, is revoked, or has its removal scheduled, canceled or completed, see Webhook. Everynumber.*event carries the number’sidindata.id, and every event about a number carriesnumber_idin the envelope, so you can route the event to the right customer without looking anything up. - Polling
GET /v1/numbers/{ref}returns the current status and, during pairing, thepairingblock with the code to type or the QR code image. Use it to show them, because they are not sent by webhook. See Status.
If you resell numbers
When the numbers in your account belong to your customers, add each number
with one alias per customer and store the id the response returns: it shows
up in lookups and webhooks and does not change if the alias changes. The
resale guide walks through the full flow.
Your customer is the one who uses the code or scans the QR code on their own phone. The Pairing with the API page describes the screen that lets them finish on their own: a new code or QR code at any time, the right message for each failure reason, and the attempt limit that protects their number.