# Start, stop and restart Numbers

> Control a Number's connection, read its status, change its tier and configure it.

After a Number connects, you control its connection, read why it is offline,
change its tier and adjust its configuration. Console and API controls act on
the same Number.

API paths address a Number by its Number ID, the `session` path segment. Keep
it as a string.

## Read a Number's status

**Console:**

Open a project and go to **Numbers**. The **Connection** column shows
**Connected**, **Connecting**, **Stopped** or **Error**. The **Health** column
beside it shows the Number's band and its score out of 100, and **Restriction**
shows any restriction Polymorfa applied. A Number without enough recent activity
shows **Not measured yet**. A Number BanSafe does not measure, such as a test
number, shows **Not available**. See [Safety in the Console](https://docs.polymorfa.com/safety/console).

Use **Columns** in the table toolbar to show **Device**, **Plan** and **Paid
time remaining**. They also appear on the Number's **Overview**.

Select a Number to open its page. The strip at the top shows its connection,
type, phone number, Number ID, Health and restriction, with the reason and the
action when the connection needs one. Its tabs are **Overview**, **Connections**,
**Safety**, **Funding** and **Settings**, depending on the Number's capabilities.
Test numbers have no **Connections** or **Funding**. **Settings** lists its own
sections: **General**, **Calls**, **Message storage**, **Catalogs**, **Customer**
and the delete or remove action. Each tab and section has its own URL.

**API:**

Call [Get session](https://docs.polymorfa.com/api/numbers/get-session) for one Number, or
[List sessions](https://docs.polymorfa.com/api/numbers/list-sessions) for every Number in the
team or project, including disconnected ones.

```bash cURL
curl "https://api.polymorfa.com/platform/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const numbers = await platform.sessions.list({ projectId: "<project-id>" });
for (const number of numbers.data.data) {
  console.log(number.sessionId, number.phone, number.status, number.testMode);
}

const number = await messaging.sessions.retrieve("<number-id>");
console.log(number.data.data.status, number.data.data.statusReason);
```

```bash Graph API
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/phone_numbers" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"
```

**Graph API:** Meta Cloud API Numbers: Supported. Linked Devices Numbers: Supported.

[List phone numbers](https://docs.polymorfa.com/api/graph/phone-numbers/list-phone-numbers)
returns your project's Numbers under a WhatsApp Business Account in Meta's
shape: display number, verified name, quality rating, platform and throughput.
It has no connection `status`; read that from Get session.

`status` is `CONNECTING`, `CONNECTED` or `DISCONNECTED`. The nullable
`statusReason` tells a manual stop apart from a logout, a temporary
restriction, a timeout or a runtime failure. Show both when you present
connection health. `testMode` is `true` for a test number; do not infer it
from the ID, which uses the same format for every Number.

Read Health with `GET /platform/bansafe/health/{session}`. See
[BanSafe](https://docs.polymorfa.com/safety/health).

*TypeScript:*

Omit `projectId` to list every Number in the team, and keep Number IDs as
strings. `testMode` is `true` for a test number. Read the linked WhatsApp
account with `messaging.sessions.account("<number-id>")`.

Connection state changes also arrive as `session.status`,
`session.connected`, `session.logged_out` and `session.phone_offline` events.
See [Webhooks](https://docs.polymorfa.com/development/webhooks).

### Connection type and device

[Get session account](https://docs.polymorfa.com/api/numbers/get-session-account)
(`GET /platform/sessions/{sessionId}/me`), `GET /messaging/{session}/profile`
and the `session.connected` event describe the connected account with two
fields. The Console shows the same values in the **Device** column and on the
Number page.

| `phonePlatform` | Meaning |
| --- | --- |
| `android` | WhatsApp or WhatsApp Business runs on an Android phone. |
| `ios` | WhatsApp or WhatsApp Business runs on an iPhone. |
| `meta_cloud` | Meta hosts the number through Cloud API. |
| `unknown` | The phone has not reported a recognized platform. |

| `accountType` | Console label | Meaning |
| --- | --- | --- |
| `whatsapp_app` | **Normal** | WhatsApp app, connected as a linked device. |
| `business_app` | **WABA** | WhatsApp Business app, connected as a linked device. |
| `meta_cloud` | **Cloud** | Meta Cloud API. |
| `meta_coexistence` | **Coex** | Meta Cloud API, with the WhatsApp Business app still active on the phone. |

A linked Number reports its operating system when it connects. Until then,
the Console shows an empty icon.

## Start, stop and restart

Stopping a Number disconnects it from WhatsApp without unlinking it. Starting
it reconnects. Restarting retries a Number whose runtime failed.

**Console:**

The Number page header shows **Start connection**, **Stop connection** or
**Restart connection**, depending on its state. The same actions are in the
row's **More** menu and its right-click menu.

- Connected and connecting Numbers offer **Stop connection**.
- A Number stopped from the Console offers **Start connection**.
- A failed runtime offers **Restart connection**.
- A logged-out real Number asks you to link it again with a new QuickLink.

**API:**

| Action | Method |
| --- | --- |
| [Start](https://docs.polymorfa.com/api/numbers/start-session) | `POST /platform/sessions/{sessionId}/start` |
| [Stop](https://docs.polymorfa.com/api/numbers/stop-session) | `POST /platform/sessions/{sessionId}/stop` |
| [Restart](https://docs.polymorfa.com/api/numbers/restart-session) | `POST /platform/sessions/{sessionId}/restart` |

```bash cURL
curl -X POST "https://api.polymorfa.com/platform/sessions/$SESSION_ID/stop" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
await platform.sessions.start("<number-id>", { projectId: "<project-id>" });

await platform.sessions.stop("<number-id>", { projectId: "<project-id>" });

const restart = await messaging.sessions.restart("<number-id>");
const settled = await platform.operations.wait(restart.data.operationId);
console.log(settled.data.status);
```

Stop and restart are asynchronous: read the status or wait for
`session.status` to confirm the result. To stop up to 100 Numbers at once,
send their IDs in `sessionIds` to
[Stop sessions](https://docs.polymorfa.com/api/numbers/stop-sessions)
(`POST /platform/sessions/stop`). Add `projectId` to limit a team key to one
project.

An accepted stop means stopping was requested, not that cleanup finished. Wait
for the stop operation to succeed before you start the next setup attempt. If a
stop result is uncertain, inspect the existing operation before retrying.

For a test number:

- Start is asynchronous. A ready Number resumes its existing runtime. A stopped
  Number starts again only after its cleanup is confirmed. Repeating a pending
  start keeps the same attempt.
- Restart waits for a confirmed stop, then starts the same Number. `202` means
  the request was accepted, not that the Number connected. Follow its stop and
  start operations, and resolve an unconfirmed one before you request another
  restart.

*TypeScript:*

`start` confirms that the start was accepted, not that the Number connected;
watch the status to see it connect. If the team cannot pay, it throws
`PolymorfaPaymentRequiredError`. `platform.sessions.stopMany({ sessionIds })`
stops up to 100 Numbers at once. See
[Wait for an operation](https://docs.polymorfa.com/development/operations#wait-for-an-operation).

Starting a paid Number reserves credit before it connects. Insufficient credit
returns `402`, and a new charge that would exceed a monthly project or Number
credit limit returns `409` `state_conflict`. A new paid window is charged only
after the connection succeeds. See [Billing](https://docs.polymorfa.com/billing).

## Log out a Number

Logging out unlinks Polymorfa from the phone. To use the Number again, connect
it with a new QuickLink.

Call [Logout session](https://docs.polymorfa.com/api/numbers/logout-session)
(`POST /platform/sessions/{sessionId}/logout`). A `202` response accepts the
request; it does not confirm that unlinking finished. A disconnect event
reports connection state, not a completed logout.

```bash cURL
curl -X POST "https://api.polymorfa.com/platform/sessions/$SESSION_ID/logout" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
const logout = await messaging.sessions.logout("<number-id>");
await platform.operations.wait(logout.data.operationId);
```

## Remove a Number

**Console:**

Open a test number's **More** menu and select **Remove number**. For a real Number,
select **Deletion help** and contact support; the Console does not remove real
Numbers.

**API:**

[Delete session](https://docs.polymorfa.com/api/numbers/delete-session)
(`DELETE /platform/sessions/{sessionId}`) permanently removes a test number.
[Delete sessions](https://docs.polymorfa.com/api/numbers/delete-sessions)
(`POST /platform/sessions/delete`) removes up to 100 test numbers. For a real
Number, both return `409` without removing anything.

```bash cURL
curl -X DELETE "https://api.polymorfa.com/platform/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
```

```typescript TypeScript
await platform.sessions.delete("<number-id>");
```

*TypeScript:*

`deleteMany` removes several test numbers in one call.

## Change a Number's tier

A tier decides which features a Number can use. To change it:

1. Request a quote with
   [Quote session tier change](https://docs.polymorfa.com/api/numbers/quote-session-tier-change)
   (`POST /platform/sessions/{sessionId}/tier-quotes`). The quote shows the
   full charge and effective time. It expires after ten minutes and does not
   change the Number.
2. Confirm the returned `quoteId` with
   [Set session tier override](https://docs.polymorfa.com/api/numbers/set-session-tier-override)
   (`PATCH /platform/sessions/{sessionId}`).
3. Poll [Get session tier change](https://docs.polymorfa.com/api/numbers/get-session-tier-change)
   until the change is applied or rejected.

An upgrade buys a fresh 24-hour window without refunding remaining time. A
downgrade applies at the end of the paid window. See
[Number tiers](https://docs.polymorfa.com/billing/number-tiers).

## Configure a Number

Configuration covers history sync, hosted message storage and observation of
presence, typing, labels and quick replies. A Number inherits team and project
defaults for every field it does not override, so a changed default reaches
every Number that still inherits it. Choices made on a QuickLink are fixed
when the link is issued.

**Console:**

Open the Number and select **Settings**, then **General**. The Number's configuration shows each
effective value, where it comes from and whether the Number has applied the
latest change.

**API:**

1. Read the Number with [Get session](https://docs.polymorfa.com/api/numbers/get-session) and
   note `configuration.revisions.session`.
2. Send it as `revision` to
   [Update session](https://docs.polymorfa.com/api/numbers/update-session)
   (`PUT /platform/sessions/{sessionId}`), with the fields to set and the
   overrides to remove:

```json JSON
{
  "revision": 2,
  "configuration": {
    "set": { "historySync": { "mode": "deliver" } },
    "reset": ["historySync.requestFull"]
  }
}
```

```typescript TypeScript
const current = await messaging.sessions.retrieve("<number-id>");
const revision = current.data.data.configuration?.revisions.session ?? 0;

await messaging.sessions.update("<number-id>", {
  revision,
  configuration: {
    set: { observation: { presenceMode: "events" } },
    reset: ["historySync"],
  },
});
```

A stale `revision` returns a conflict, so concurrent edits cannot overwrite
each other. A reset removes the override; the field then inherits the default
again.

Manage team defaults with
[Get session configuration defaults](https://docs.polymorfa.com/api/session-configuration/get-session-configuration-defaults)
and [Update session configuration defaults](https://docs.polymorfa.com/api/session-configuration/update-session-configuration-defaults)
(`GET` or `PUT /platform/session-configuration`). Add `projectId` for project
defaults, and send the matching team or project revision. Unknown query
parameters return `400`.

*TypeScript:*

Read the current revision, then send your change with it:

A stale revision throws `PolymorfaConflictError` with `state_conflict`. Change
team defaults with `platform.sessionConfiguration` and project defaults with
`project.sessionConfiguration`.

The Number applies a saved change asynchronously, so it can stay `pending`
until the connected runtime acknowledges it.

| Field | Values |
| --- | --- |
| `historySync.mode` | `metadata_only` or `deliver`. See [History sync processing](https://docs.polymorfa.com/messaging/linked-device-controls#history-sync-processing). |
| `historySync.requestFull` | `true` requests full history on the next pairing. |
| `observation.presenceMode`, `typingMode`, `quickReplyMode` | `off`, `events` or `cache` |
| `observation.labelMode` | `off`, `events`, `cache` or `project` |

Observation applies to Linked Devices Numbers. Meta Cloud API Numbers and test
numbers reject observation settings they cannot apply. Changing observation
requires observation access, and label changes also need label-management
access. A Number override above the project's observation ceiling returns
`400`; lower the mode or raise the project default first. See
[Linked-device controls](https://docs.polymorfa.com/messaging/linked-device-controls).

History sync is limited by the recipient's consent. Configuration cannot turn
on hosted message storage or change an authorized storage region or
retention.

## Paid time, budgets and usage

The Numbers table and Number page show the time left in each real Number's
charged 24-hour window. The countdown continues while a Number is stopped or
disconnected. **Paid window expired** means the purchased time ended; **No
paid window** means the Number has no charged window. Test numbers show no
countdown.

- **Budget**: owners and admins of Pay-As-You-Go teams select **Budget** in a
  real Number's row menu to open its **Funding** tab, set a monthly limit and
  priority, and select **Save changes**. You can also set both when you create
  the Number. See [Spending budgets](https://docs.polymorfa.com/billing/spending-budgets).
- **View usage**: opens the Number's charges and metered usage in its owning
  project. See [Usage and credits](https://docs.polymorfa.com/billing/usage#explore-consumption).

Project limits and project priority stay in **Usage → Funding controls**.

## Find and filter Numbers

The Numbers table keeps the Number's name and phone or Number ID in its first
column.

- Open a column heading to sort or filter by it. Add several rules; each
  appears as an editable pill in the toolbar, and numbered sort pills show
  which sort runs first.
- Drag a heading edge to resize a column. Select **Fit columns** to restore the
  default layout.
- Filter **Device** by account type, **Added** by date range and **Claimed by**
  by team member or **Unclaimed**.
- Use **Numbers / selected Number** at the top of a Number page to search for
  another Number or return to **All numbers**.

**Claimed by** shows the Number's Inspector claimant. The claimant and team
owners and admins see **Unclaim** under the name and in the Number's actions
menu; see
[Unclaim a Number](https://docs.polymorfa.com/testing/inspector/devices#unclaim-a-number). A claim does
not change connection health.

If a refresh fails, the list keeps the last information it loaded and shows a notice
with **Retry**. You can still create a Number while the list is unavailable.

## See also

- [Connect a number with QuickLink](https://docs.polymorfa.com/numbers/quicklink)
- [Number capabilities](https://docs.polymorfa.com/numbers/capabilities)
- [Webhooks](https://docs.polymorfa.com/development/webhooks)
