Skip to main content
A session represents one connected or testing number. Messaging API operations address a session with its stable session identifier. The typed public status values are CONNECTING, CONNECTED, and DISCONNECTED. Active teams can connect through the Console or create a shareable QuickLink. Number funding is checked when pairing starts. Creating a link does not reserve paid service or bypass Meta Cloud API and Test Numbers access requirements.

​
Add a number in Console

Open a project, go to Numbers, and select New number. The closeable setup flow offers four paths:
  • Create a testing number for free takes about 10 seconds and adds a simulated number for development and automated tests. It does not connect to WhatsApp.
  • Link a real number now takes about 2 minutes. Console creates a QuickLink and opens its hosted pairing flow. Scan the QR code or enter a pairing code on the phone, confirm the connection, and the number appears in the list.
  • Send a QuickLink takes about 2 minutes and opens a per-link settings review for connection type, pairing methods, phone handling, and history sync. Generate the hosted link, then copy it, share it, or show it as a QR code. The link remains active until use or cancellation, connects one number to the selected project, and Console shows when it is opened, linked, and connected. See QuickLink.
  • Import existing sessions takes about 10 minutes and shows source-specific guidance for Baileys and whatsmeow authentication state.
On a Free team, real-number paths show Requires Pay-As-You-Go when the team has used its real-number allowance. Send a QuickLink for a real number always shows it. An upgrade prompt below the choices opens Billing. Link a real number now and testing numbers stay available within the allowance. Closing the dialog while pairing inside Console cancels that pending connection. Closing the dialog after sending a QuickLink does not invalidate it; the link remains usable until it connects a number or you cancel it. Generate a new link creates a separate invitation. The Connection column shows an icon beside Connected, Connecting, Stopped, or Error, with a reason when action is required. Connected and connecting numbers offer Stop connection. A number stopped from Console offers Start connection. A failed runtime offers Restart connection, and a logged-out real number directs you to link it again. Inspector ownership remains in the separate Owned by column and does not change connection health. The Health column sits beside Connection and shows how the number is sending: its band, its score out of 100, and how many safety findings are open. The two columns mean different things. Connection is whether the number is online; Health is whether it is sending the way a person does. A number that has not sent enough yet shows no score, and a number BanSafe has no measurement for, such as a testing number, reads Not available. The column covers every measured number in the project, not only the first page of the table. Select a number to see its findings, or open Safety for the whole project. See Safety. The Device column shows how each number reaches WhatsApp. An icon shows the phone’s operating system: Android, iOS, or Meta for numbers that Meta hosts. The label beside it shows the account type: A linked number reports its operating system when it connects. Until then, the column shows an empty icon. Filter the column by account type. The number’s details show the same information under Device. The table keeps the number name and phone or session ID in its first, widest column. Open any column heading to sort or filter by that property. Drag the edge of a heading to resize it; Console remembers the width in that browser. Filters and Sort are also available beside the table actions. Add more than one rule; each filter and sort appears as an editable pill in the toolbar. Numbered sort pills show which property runs first. Type a text filter, then press Enter or select Apply. The table and its columns stay visible when no rows match. Added uses the date-range picker, and Owned by lets you choose a team member or Unowned. Columns fit the available page width by default. After resizing, select Fit columns to restore that layout. Owned by shows the user’s avatar and name; Customer shows a customer icon and name. Type uses a plain icon and label. The actions under More are also available when you right-click the row. Use them to manage the number, open its usage, API logs or Customer, copy its phone number or Number ID, or control the connection. You can remove a testing number from Console. For a production number, select Deletion help and contact support; Console does not remove it. Actions that need a phone number or Customer appear only when that data exists. Selecting a number opens its own page. Use Numbers / selected Number at the top to search for another number or return to All numbers. The picker keeps the Number in its owning project. The common Number controls use horizontal tabs: Overview, Connections, Safety, Funding, Calls, and Settings. Available tabs depend on the Number’s capabilities. Each tab has a shareable URL. Funding is available for real numbers; testing numbers keep their existing setup and removal controls. Start connection, Stop connection, or Restart connection appears in the Number page header, based on its connection state. The action stays available while you switch tabs. Connections contains linked connections and account health, Safety contains health and findings, and Funding contains the plan, limit and priority. Open Settings for configuration, Customer transfer and deletion help.

​
Number usage

Choose View usage from a production number’s row menu to check its charges and metered usage. The team-wide list opens the number’s owning project and keeps the number selected when you open a product chart. Monthly outgoing-call and credit-limit progress use the current UTC month. Testing numbers do not have this action. See Usage and credits.

​
Number spending budgets

Owners and admins of Pay-As-You-Go teams open a real number’s row menu and select Budget to open its Funding tab with the limit and priority form focused. The same action works in the team-wide Numbers list and opens the number’s own project. Select Save changes to save both values. Owners and admins can also set initial values when creating a real number. Testing numbers do not have this action. See spending budgets for monthly limits, reservations and already-paid service.

​
Session import

To import a Baileys session:
  1. Stop writes to the Baileys authentication state.
  2. Reserve the destination through QuickLink, then request its handoff key with POST /platform/sessions/{sessionId}/handoff-keys.
  3. Seal the SignalStoreSnapshot to the returned key and calculate the SHA-256 hash of the snapshot.
  4. Submit the sealed envelope and hash to POST /platform/sessions/{sessionId}/handoff-import.
  5. Keep Baileys offline until Polymorfa reports the imported number as connected.
For whatsmeow, keep the device store offline and take one consistent database snapshot containing the device record and Signal tables. Use the assisted migration path for that snapshot; Console does not accept raw database uploads. Keep the original store unchanged until Polymorfa confirms the imported number is connected.
Do not run the source and imported copies at the same time. Competing linked devices can invalidate the session.

​
Connection methods

A 202 logout response accepts the request; it does not confirm that unlinking has finished. A disconnect event describes connection state, not completed logout. GET /platform/sessions/{sessionId}/me, GET /messaging/{session}/profile, and the session.connected webhook describe the connected account with two fields: Connect a real number with POST /messaging/quicklinks, then open or share the returned URL. Credentials need direct-pairing access for the Number to retrieve a raw QR code or pairing code from /messaging/{session}/pair/*; requests without that access return 403. See QuickLink for the complete flow.

​
Batch actions and number tiers

Use POST /platform/sessions/stop or POST /platform/sessions/delete for a batch of 1–100 session IDs in sessionIds. Add projectId to limit a team key’s request to one project. Project tokens are limited to their own project. To change a number’s tier, request a quote with POST /platform/sessions/{sessionId}/tier-quotes, review its charge and effective time, then confirm the returned quoteId with PATCH /platform/sessions/{sessionId}. See Billing. Create testing numbers through QuickLink with configuration.testing. Each listed session includes status and nullable statusReason. Use both fields when presenting connection health; statusReason distinguishes a manual stop, logout, temporary restriction, timeout, and runtime failure. Read a number’s present Health, estimate source, and recorded findings with GET /platform/bansafe/health/{session}. See BanSafe.

​
Testing numbers

Creating a testing number requires projectId. name is optional. country accepts one of the 243 WhatsApp-supported ISO alpha-2 country codes and defaults to US. Search the Console picker by country name, short name, or calling code. The generated Number ID is an opaque decimal string, using the same format as other Numbers. Use testMode, not an ID prefix, to identify a Test Number. Test Numbers do not start a real WhatsApp connection. See Connect API methods for the strict request and result schemas.

​
Where to go next

Numbers

Browse pairing and lifecycle methods.

Sandbox

Exchange messages between testing numbers.

Webhooks

Subscribe to session events.

Teams and accounts

Inspect account and project operations.

​
Configuration

The number inspector shows effective configuration, where each value comes from, and whether the runtime has applied the latest change. Team and project defaults apply only to fields without a session override. Read the session, then send its configuration.revisions.session as revision:
Send updates to PUT /platform/sessions/{sessionId}. A reset removes the explicit override; it does not replace it with today’s default. Stale revisions return a conflict so concurrent edits cannot overwrite each other. Manage team defaults with GET or PUT /platform/session-configuration. Include projectId to manage project defaults. Use the corresponding team or project revision from the last read. Configuration reads reject unknown query parameters with 400 rather than ignoring them. History remains limited by recipient consent. HMS stays disabled unless separately authorized; configuration cannot enable storage or change an authorized region or retention grant by itself. Runtime application is asynchronous: a saved change can remain pending until the connected runtime acknowledges it. Direct creation is retired. Old creation requests return 410 with resource_gone; use QuickLink for new reservations. Reconnect, update, disconnect, and delete continue to operate on existing sessions. Observation settings also live inside configuration.observation: presenceMode, typingMode, quickReplyMode, and labelMode. The first three accept off, events, or cache; labels also accept project. They apply to Linked Devices. Meta Cloud API and Test Numbers reject explicit observation settings they cannot apply. Observation changes require observation access; label changes also require label-management access. The older observation-policy write endpoints return a migration error. Read endpoints remain available. A session override that exceeds the project observation ceiling returns 400; lower the requested mode or update the project defaults first. The Numbers table and Number page show the time left in each number’s charged 24-hour window. The countdown continues while a number is stopped or disconnected. Paid window expired means the purchased time has ended; No paid window means the number has no charged window. Test numbers do not display a paid countdown. For funding and renewal rules, see Billing. A number’s Budget action opens its Funding tab at /sessions/<numberId>?tab=funding, so you can return directly to that tab. Existing links with number and panel=limits remain supported. Customer-assigned number links open the same Number page. Project limits and project priority stay in Usage → Funding controls.