Skip to content
Shortcut: /, ⌘K or Ctrl+K

Start, stop and restart Numbers

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

View as Markdown

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.

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 for one Number, or List sessions for every Number in the team or project, including disconnected ones.

cURL
curl "https://api.polymorfa.com/platform/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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);
Graph API
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/$WABA_ID/phone_numbers" \
  -H "Authorization: Bearer $POLYMORFA_PROJECT_TOKEN"

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 API Get ban safe health. See BanSafe.

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.

Connection type and device #

Get session account (API Get session account), API Get 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.

phonePlatformMeaning
androidWhatsApp or WhatsApp Business runs on an Android phone.
iosWhatsApp or WhatsApp Business runs on an iPhone.
meta_cloudMeta hosts the number through Cloud API.
unknownThe phone has not reported a recognized platform.
accountTypeConsole labelMeaning
whatsapp_appNormalWhatsApp app, connected as a linked device.
business_appWABAWhatsApp Business app, connected as a linked device.
meta_cloudCloudMeta Cloud API.
meta_coexistenceCoexMeta 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

cURL
curl -X POST "https://api.polymorfa.com/platform/sessions/$SESSION_ID/stop" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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 (API Stop sessions). 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.

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.

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 (API Logout session). A 202 response accepts the request; it does not confirm that unlinking finished. A disconnect event reports connection state, not a completed logout.

cURL
curl -X POST "https://api.polymorfa.com/platform/sessions/$SESSION_ID/logout" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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 (API Delete session) permanently removes a test number. Delete sessions (API Delete sessions) removes up to 100 test numbers. For a real Number, both return 409 without removing anything.

cURL
curl -X DELETE "https://api.polymorfa.com/platform/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $POLYMORFA_KEY"
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 (API Quote session tier change). 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 (API Set session tier override).
  3. Poll 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.

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 and note configuration.revisions.session.
  2. Send it as revision to Update session (API Update session), with the fields to set and the overrides to remove:
JSON
{
  "revision": 2,
  "configuration": {
    "set": { "historySync": { "mode": "deliver" } },
    "reset": ["historySync.requestFull"]
  }
}
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 and Update session configuration defaults (GET or API Update session configuration defaults). 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.

FieldValues
historySync.modemetadata_only or deliver. See History sync processing.
historySync.requestFulltrue requests full history on the next pairing.
observation.presenceMode, typingMode, quickReplyModeoff, events or cache
observation.labelModeoff, 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.

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

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.
  • View usage: opens the Number's charges and metered usage in its owning project. See Usage and credits.

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