Connect and manage 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:

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:

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.

List your Numbers

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

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. 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.

Start and stop a Number

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. platform.sessions.stopMany({ sessionIds }) stops up to 100 Numbers at once.

Restart or log out a Number

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.

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:

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.

Set Safe Mode for one Number

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:

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.

Delete a Test Number

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

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

Get started

Tools and clients

TypeScript SDK

Connect numbers

WhatsApp

Campaigns

Your team

Testing

Help and updates

Connect and manage Numbers

Connect a Number with QuickLink

List your Numbers

Check a Number’s status

Start and stop a Number

Restart or log out a Number

Change a Number’s configuration

Set Safe Mode for one Number

Change a Number’s tier

Delete a Test Number

​Connect a Number with QuickLink

​List your Numbers

​Check a Number’s status

​Start and stop a Number

​Restart or log out a Number

​Change a Number’s configuration

​Set Safe Mode for one Number

​Change a Number’s tier

​Delete a Test Number

Connect a Number with QuickLink

List your Numbers

Check a Number’s status

Start and stop a Number

Restart or log out a Number

Change a Number’s configuration

Set Safe Mode for one Number

Change a Number’s tier

Delete a Test Number