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

# Connect and manage Numbers

> Connect a WhatsApp account with QuickLink, check its status, and start, stop, and configure Numbers.

A Number is one connected WhatsApp account. Messaging methods take its ID as
their first argument.

| Task | Permission |
| - | - |
| Create and follow QuickLinks | `quicklink:manage` |
| List and read Numbers | `sessions:read` |
| Start, stop, restart, configure, and change tiers | `sessions:manage` |

## Connect a Number with QuickLink

A QuickLink is a hosted page where the account owner links their WhatsApp. Create
one and send its URL to the person holding the phone:

```typescript theme={null}
const created = await messaging.quickLinks.create(
  {
    projectId: "<project-id>",
    externalId: "crm-account-42",
    configuration: { methods: ["qr", "pairing"] },
  },
  { idempotencyKey: "connect-crm-account-42" },
);

console.log(created.data.data.url, created.data.data.session);
```

`externalId` is your own reference. It appears on the new Number and in its
webhook events. With a project credential, omit `projectId`.

Follow progress until the status is `connected`:

```typescript theme={null}
const link = await messaging.quickLinks.retrieve("<quicklink-id>");
console.log(link.data.data.status, link.data.data.phone);
```

The status moves through `pending`, `opened`, `linked`, and `connected`, or ends
as `failed` or `cancelled`. Call `quickLinks.cancel(id)` to withdraw a link that
has not connected.

Page text, branding, and callback URLs are saved settings. Read and change them
with `platform.quickLinkSettings`. See [QuickLink](/integrations/quicklink).

## List your Numbers

```typescript theme={null}
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);
}
```

Omit `projectId` to list every Number in the team. Keep Number IDs as strings.
Use `testMode` to tell Test Numbers apart from real ones.

## Check a Number's status

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

The `session.status` webhook reports status changes as they happen. See
[Webhooks](/sdks/typescript/webhooks).

Read the linked WhatsApp account with `messaging.sessions.account("<number-id>")`.

Get session returns `newChatCapping` for a linked-device number, with the limit,
usage and reset time WhatsApp reported. It is `null` until Polymorfa has observed
the number. The `NewChatCapping` SDK type is available in the release that
follows this API change. See [WhatsApp new-chat cap](/guides/numbers/new-chat-cap).

## Start and stop a Number

```typescript theme={null}
await platform.sessions.start(
  "<number-id>",
  { projectId: "<project-id>" },
  { idempotencyKey: "start-support-2026-10-02" },
);

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

`start` confirms that the start was accepted, not that the Number connected.
Watch the status to see it connect. Starting a paid Number reserves credit
first. If the team cannot pay, `start` throws `PolymorfaPaymentRequiredError`.
See [Errors](/sdks/typescript/errors#402-the-team-cannot-pay).

`platform.sessions.stopMany({ sessionIds })` stops up to 100 Numbers at once.

## Restart or log out a Number

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

`logout` unlinks the WhatsApp account and returns an operation in the same way.
See [Wait for an operation](/sdks/typescript/events#wait-for-an-operation).

## Change a Number's configuration

Configuration covers history sync, hosted message storage, and observation of
presence, typing, labels, and quick replies. Read the current revision, then
send your change with it:

```typescript theme={null}
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"],
  },
});
```

`set` overrides a value for this Number. `reset` removes the override, so the
Number follows the project and team defaults again. A stale revision fails with
`409 state_conflict`. Change defaults with `platform.sessionConfiguration` and
`project.sessionConfiguration`. See [Session configuration](/console/sessions#configuration).

## Set Safe Mode for one Number

```typescript theme={null}
const safeMode = await platform.sessions.getSafeMode("<number-id>");
console.log(safeMode.data.data.effective);

await platform.sessions.updateSafeMode("<number-id>", {
  typing: "before_text",
  pacing: "inherit",
});
```

`inherit` removes the Number's override and uses the project setting.

## Change a Number's tier

A tier change is a quote followed by a confirmation:

```typescript theme={null}
const quoted = await platform.sessions.quoteTierChange("<number-id>", {
  tierOverride: "pro",
});
const quote = quoted.data.data;
console.log(quote.quote.amountCents, quote.quote.effectiveAtMs);

// After the customer accepts this exact quote:
await platform.sessions.setTierOverride("<number-id>", { quoteId: quote.id });

const result = await platform.sessions.retrieveTierChange("<number-id>", quote.id);
console.log(result.data.data.status);
```

Show the quoted charge before you confirm it. `amountCents` is in credits and
can have up to six decimal places. A quote expires after ten minutes. A `queued`
change has not been applied yet; read it again until it is `applied` or
`rejected`. Quote `tierOverride: null` to return the Number to the project's
tier. See [Billing](/console/billing#change-a-number-tier).

## Delete a Test Number

```typescript theme={null}
await platform.sessions.delete("<number-id>");
```

`delete` and `deleteMany` remove Test Numbers only. A real Number returns
`409`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.