Skip to main content
Version: v0.31.0

Tour the dashboard

The dashboard is a web UI for everything you would otherwise drive through the API: create and connect sessions, scan QR codes inline, register webhooks with a visual filter builder, and — as an admin — mint and revoke API keys. This guide walks you through each area and what it does.

Prerequisites
  • A running OpenWA instance. See Quick start if you don't have one yet.
  • An OpenWA API key to sign in with. Generating one is covered in Authentication.

Sign in and what you'll see​

The dashboard ships inside the OpenWA process. With a default install it's served from the same origin and port as the API — open http://localhost:2785/ in a browser and sign in with your API key.

Sign-in checks the key with POST /api/auth/validate, so a key restricted with allowedChats (v0.23.6+) cannot sign in: the form reports API key is restricted to selected chats, and a signed-in tab whose key later gets a chat allowlist is signed out the next time it loads. Use a key without a chat allowlist for the dashboard.

Since v0.24.0, validation also returns scoped (whether the key has session restrictions); engineType arrived in v0.23.7, and since then operator and viewer keys no longer need the admin-only engine endpoint for status posts or Channels. An IP or session scope refusal is 403; a missing, unknown, revoked or expired key is 401.

What you can see is role-gated. The key's role (admin, operator, or viewer) decides which pages mount in the sidebar; since v0.24.0, a key restricted to selected sessions (allowedSessions) also loses the API Keys, Infrastructure and Plugins pages whatever its role; the gateway refuses such a key on /api/auth/api-keys, on every /api/infra route except the public /api/infra/health probe, and on GET /api/plugins. Admin-only pages are not just hidden — a non-admin who types the URL directly is redirected away.

PageWhat it's forRole
DashboardOverview: session counts, message volume, recent activity. Since v0.23.6 the 24-hour message chart shows its hours in the browser's time zone, and the 7- and 30-day charts are labelled as UTC days. Since v0.23.6 the Messages by type chart counts only messages inside the selected period; before, it also counted every message carrying metadata, whatever its date. The Messages Today tile counts from midnight in the gateway's own time zone; on PostgreSQL that holds since v0.23.6, and before it a gateway outside the database server's zone counted from a midnight shifted by the difference between the two zones. The Messages Today and Total Messages tiles and the message charts read GET /api/stats/overview and GET /api/stats/messages, which take an admin key with no session scope: an operator or viewer key, or an admin key restricted with allowedSessions, sees no count in those two tiles and no charts. Since v0.26.0 the session counts come from the session list while the statistics cannot be read, where they read 0; the Top chats chart labels a group that has no name by its id cut to the first and last digits (the tooltip keeps the whole id); and the charts stay left to right on right-to-left pagesall
SessionsCreate, start, stop, show the QR, and delete sessionsall
ChatsBrowse chat threads, updated live over WebSocketall
Number CheckerCheck whether numbers have a WhatsApp account without sending a message, one at a time or in bulk (v0.26.0+). See Other toolsall, but a check needs an operator key
WebhooksRegister and manage per-session webhook endpoints. The webhook routes are operator-only, so a viewer key gets no list; since v0.23.6 the page says so (No access to webhooks), and a list that fails to load for another reason shows the error instead of reporting that none are configured. Since v0.26.0 the page does not send the list request at all for a key below operator, since the gateway records each refusal as a failed authenticationall
TemplatesManage reusable message templates. Since v0.23.6 each row in the list has its own delete button, shown only to a key that can write templates. The template list route is operator-only: a key below operator gets No access to templates, and since v0.26.0 the page does not send the request (before, it showed the notice after a 403)all
Message TesterSend any message type (text, media, location, contact card, sticker, poll) to a number or a group (since v0.23.6, to several groups in turn), forward a message, run a bulk batch of text or (since v0.23.6) media, or check a numberall
LogsActivity and audit trailadmin
API KeysCreate, list, and revoke API keysadmin, no session scope
InfrastructureRuntime status and configurationadmin, no session scope
PluginsInstall, enable, and configure plugins. An ingress-capable plugin's config modal carries an Instances tab for provisioning Integration Fabric instances, one per external account, each with its own inbound webhook and secretadmin, no session scope

The sidebar footer holds a theme button that cycles Light, Dark and System (the browser's colour scheme, and the default until you choose); from v0.10.0 until v0.24.0 it switched between light and dark only. The choice is remembered in your browser and applied before first paint, so there is no flash of the wrong theme. The accent-palette picker was removed in v0.10.0. There is no separate Settings page.

Since v0.23.6 an admin also sees a link next to the version in the sidebar when a newer OpenWA release has been published, pointing at that release's notes. The dashboard reads it from GET /api/infra/update-check, which, like every /api/infra route except the public /api/infra/health probe, takes an admin key with no session scope: an admin key restricted with allowedSessions gets 403 there, so the dashboard shows it no link. The route asks GitHub for the latest published release and caches the answer for six hours, or fifteen minutes after a failure. A failed check never shows an error: until the gateway has reached GitHub once there is no link, and a later failure keeps the last release it found. The request goes out directly, not through HTTP_PROXY or HTTPS_PROXY. Set UPDATE_CHECK_ENABLED=false where the gateway must not make that outbound request to api.github.com; see Configuration.

The dashboard is a thin front end

Every action below maps to a documented API route. The dashboard calls the same http://localhost:2785/api endpoints you'd call with curl. Where a page maps to an endpoint, this guide names it so you can script the same workflow.

Sessions: connect a number with an inline QR​

The Sessions page is where a WhatsApp number goes from "created" to "connected." Each row shows the session's live status, so you can see at a glance which numbers are online.

From a row you can:

  • Create a session and name it — POST /api/sessions.
  • Start or stop it — POST /api/sessions/{sessionId}/start, POST /api/sessions/{sessionId}/stop.
  • Show the QR to link a phone — GET /api/sessions/{sessionId}/qr.
  • Set an egress proxy, at create time or afterwards from the row's Proxy action: GET / PATCH /api/sessions/{sessionId}/proxy (since v0.23.4). Since v0.24.0, setting or clearing a proxy, at create time or from the modal, needs an admin key without session scope; with any other key the Proxy action opens read-only and the create form has no proxy field. The modal shows the host and whether credentials are stored, never the URL itself, and a read that fails is shown as a failure rather than as "no proxy configured", so saving from that state cannot silently clear a proxy nobody got to see. The change applies on the session's next start. Since v0.23.6 saving a proxy whose user name or password holds a % that begins no valid percent-escape is refused with 400, at create time and from the modal; write a literal % as %25. From the same release the proxy also carries the gateway's own fetch of a media URL sent for that session, the Message Tester's included, so set SESSION_PROXY_URL_FETCH=false if the proxy routes only WhatsApp traffic. See Sessions.
  • Delete it when you're done — DELETE /api/sessions/{sessionId}.

Opening a row's detail panel shows the session's name, status, id, phone, and timestamps as a full date and time (on a session card, a last-active time within the past day reads in hours since v0.26.0, as on the Dashboard; before, it fell back to a date after the first hour), plus an Auto-reject calls toggle (since v0.14.5). Flipping it writes autoRejectCalls through PATCH /api/sessions/{sessionId}/config, so the setting no longer needs an API call to reach. It applies from the next incoming call — no restart — and on Baileys call.received still fires first, so a webhook consumer sees the call either way. The toggle takes effect on Baileys only: whatsapp-web.js cannot reject a call, so on that engine the call keeps ringing, and since v0.23.6 the attempt is logged as a failed auto-reject rather than as a rejected call. call.received itself is not reliable on whatsapp-web.js. The toggle is read-only for a viewer key, and it is omitted entirely when the config could not be read, rather than rendering as off and asserting something the dashboard does not know. See Sessions & multi-session — Read and change a session's config for the other three settings the same route carries, linkPreview (since v0.30.3) among them.

Each row also surfaces a restriction badge when WhatsApp itself has placed a limit on the account (a reachout timelock, a TOS block, a proxy block, or on Baileys since v0.30.0 passkey_required when WhatsApp asks for a passkey during linking, which also appears on the pairing placeholder card and as a warning banner in the Connect Session modal on both the QR and Link with Phone Number tabs). The badge arrives live over the same WebSocket that drives the row status, so it appears and clears the moment the underlying session.restriction event fires — no page reload needed (since v0.14.0). See Sessions & multi-session — Account restrictions for what each kind means.

The inline QR view​

When you start a session that needs linking, a QR Code view opens right on the Sessions page — you don't fetch and render the QR yourself. The view refreshes the code by itself: while it is open the dashboard re-reads the QR every 5 seconds and also applies codes pushed over the WebSocket, so an expired code is replaced without any action from you. There is no countdown and no refresh button.

Scan it from your phone under WhatsApp → Linked Devices → Link a Device. Once the link succeeds the session flips to ready and the QR view closes on its own.

Since v0.23.6 the view follows the session more closely:

  • It opens only when the start leaves the session with an engine that still needs a code. A session that comes back already linked, or without an engine, opens no view, and a failed start that left no engine shows the gateway's error in a toast instead of a view that would wait forever.
  • It closes when its session fails, or disconnects with no engine left. When the session reports disconnected while its engine is still reconnecting, the displayed code is blanked at once, since a code from a dropped connection cannot be scanned, and the view waits for a fresh one. On Baileys a socket that drops while the QR waits reports initializing instead, so its old code stays on screen until the reconnected socket pushes a new one.
  • The row's Start and Reconnect buttons are disabled while its start request is in flight, and a stop that fails is reported in a toast on the Sessions and home pages.

The connect modal also offers a Link with Phone Number tab next to the QR code — a QR-free way to link a device. Enter a phone number in international format (digits only, no +), and the dashboard requests an 8-character pairing code via POST /api/sessions/{sessionId}/pairing-code. Type that code on the phone under Linked Devices → Link with phone number. The phone field uses a numeric keypad, and the code display is isolated to left-to-right so it reads correctly even in right-to-left locales. Since v0.23.6 the tab warns that on whatsapp-web.js, requesting a code for a number that already has a linked session can make WhatsApp unlink that device; use the QR tab when that session must stay up. Since v0.26.0 the gateway also refuses a code request with 409, without asking WhatsApp, on whatsapp-web.js when the number is the stored phone of another session of the gateway, and the phone field, whose hint still says digits only, reads a pasted number written with a plus, spaces, hyphens, dots or parentheses (+62 812-3456-7890) to its digits, digits of other scripts included. A paste of more than 15 digits, or with any other text, is refused with the field error and requests no code.

Under the hood the page re-reads the QR from the API every 5 seconds while the view is open, and applies refreshed codes pushed live over a WebSocket as well, which is why the image updates without a page reload. The QR endpoint returns a ready-to-render data URL:

curl http://localhost:2785/api/sessions/8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a/qr \
-H "X-API-Key: YOUR_API_KEY"
{
"qrCode": "data:image/png;base64,iVBORw0KGgoAAAANS...",
"status": "qr_ready"
}

If the session is already linked, the same call returns 400 (Session is already authenticated, no QR code needed) — the dashboard shows the session as connected instead of opening the QR view.

For the full session lifecycle and the same flow in curl and the SDK, see Sessions & multi-session.

Webhooks: build event filters without writing JSON​

The Webhooks page lists every webhook for a session with its URL, the events it subscribes to, and whether it's active. From here you can:

  • Add a webhook: set its URL, events, filters, signing secret and custom delivery headers (POST /api/sessions/{sessionId}/webhooks). Since v0.24.0 the form can generate and copy a secret. Secrets and headers stay write-only; leaving them unchanged while editing preserves the stored values. Headers reserved by the gateway, such as User-Agent and X-OpenWA-*, are refused.
  • Edit a webhook, or enable/disable it without deleting (PUT /api/sessions/{sessionId}/webhooks/{id}). Deliveries already waiting in the queue (since v0.23.6, with QUEUE_ENABLED=true) or between retries on the direct path (since v0.24.0) follow the webhook as it stands when each attempt runs: they go to the current URL with the current headers and secret, and they are dropped once the webhook is disabled or no longer subscribes to their event (a filter change does not reach them). Before, such a delivery kept the URL, headers and secret from when it was queued, even after the webhook was disabled. See Update a webhook.
  • Test it — send a synthetic delivery and see whether your endpoint accepts it (POST /api/sessions/{sessionId}/webhooks/{id}/test).
  • Delete it (DELETE /api/sessions/{sessionId}/webhooks/{id}).

The page keeps no delivery log. Deliveries that used up every retry, or were never attempted, are listed over REST at GET /api/webhooks/delivery-failures, which takes an admin key; see Cross-session diagnostics.

Since v0.25.0, retained failures can be sent again through POST /api/webhooks/delivery-failures/redrive. Payload retention is opt-in, and rows without a retained payload cannot be replayed. See Webhooks for the settings and the bounded redrive request.

The visual filter builder​

The event picker offers every event OpenWA emits, plus * to subscribe to all of them. It is kept in step with the backend list, so anything named in the event catalog can be selected here, including session.restriction, presence.update, group.join_request, and the three call outcomes. presence.update and the call outcomes (call.accepted, call.rejected, call.missed) are emitted by the Baileys engine only: a whatsapp-web.js session accepts the subscription and never fires them. Since v0.23.6 the page's Available Events reference describes every event in one line; before, most events showed only their name there. Since v0.26.0 the picker also lists message.receipt (Baileys only) and poll.vote (whatsapp-web.js, and Baileys too since v0.30.2). * does not deliver message.receipt, which must be named: the description of * reads All events except message.receipt, which must be named explicitly. Since v0.31.0 the Available Events lines for event.response and the three call outcomes say (Baileys only); the poll.vote line has named no engine since v0.30.2.

Beyond the event list, the page includes a filter builder for narrowing delivery by field, operator and value. The Chat ID field (chatId, with is and isNot, v0.23.6+) scopes a webhook to chosen chats. Since v0.25.0, message.ack and message.failed also carry chatId, so chat and chat-kind conditions can scope delivery events as well as message events.

An id value is either picked from the session's chats, which stores the id that chat carries, or typed by hand. A typed value without @ is read as a phone number, so type a group as its full <id>@g.us: bare digits become <digits>@c.us and match no group. Since v0.23.6 a condition's value goes through the same lid-to-phone mapping as the event, so a condition naming an @lid chat or contact keeps matching once the gateway learns the phone number behind that lid. Before v0.23.6 such a condition flipped at that moment while still reading correctly in the builder: an isNot condition started delivering the chat and an is condition stopped. Since v0.31.0 the chat picker finds a chat by a number typed as it is written (spaces, a plus sign, parentheses, hyphens and dots are ignored) and an unnamed privacy-id chat by the phone that titles it, and the chip and the suggestions call that chat by that phone. An id entry longer than 128 characters, which the gateway refuses, is counted as incomplete by the form, which says so and cannot be submitted until the entry is removed.

Use Test before relying on a webhook in production — it sends a sample payload to your URL so you can confirm the endpoint is reachable and returns a 2xx, without waiting for a real WhatsApp event.

For the payload shape of each event and how to verify the HMAC signature of a delivery, see Webhooks. A delivery carries the X-OpenWA-Signature header only when the webhook has a secret. The secret is optional and at least 16 characters; the gateway does not create one on its own, and the Add form can generate one on request (since v0.24.0).

API keys (admin): create, copy once, revoke​

The API Keys page is admin-only. It's where you provision the keys that every other client — including the dashboard itself — signs requests with.

From the page you can:

  • Create a key with a name (3 to 100 characters) and role (viewer, operator or admin; default operator) through POST /api/auth/api-keys. Since v0.24.0 the form also sets expiry and allowed IPs, and lets operator and viewer keys restrict sessions and chats. The list displays these restrictions. An empty session or chat list leaves that dimension unrestricted; allowedChats accepts at most 2000 entries in v0.25.0. See Authentication.
  • Re-scope an existing operator or viewer key from the same page (PUT /api/auth/api-keys/{id}, since v0.23.4). Saving a scope change is an authorization change, so every live /events socket holding that key is disconnected at once on the node that handles the save. Keys are per node: since v0.23.6 each node also re-checks its own sockets once a minute against its own key store, which a save on another node never changes, so repeat the change on every node (see Manage keys). An unchanged Save is not sent at all.
  • List existing keys by prefix, role, and usage (GET /api/auth/api-keys).
  • Revoke a key to disable it (POST /api/auth/api-keys/{id}/revoke), or delete it (DELETE /api/auth/api-keys/{id}). Since v0.31.0, when the key is the one the dashboard is signed in with, the confirmation says so: revoking or deleting it signs you out.
The full key is shown only once

When you create a key, the response includes the complete secret in the apiKey field — and that is the only time it's ever returned. Copy it immediately. Afterward, every list view shows only keyPrefix (the first 12 characters — the owa_k1_ prefix plus 5 hex chars, or (master key) for a key seeded from API_MASTER_KEY since v0.28.0), never the full value. If you lose it, revoke the key and create a new one.

Creating a key over the API returns the copy-once secret alongside its metadata:

curl -X POST http://localhost:2785/api/auth/api-keys \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "n8n integration", "role": "operator"}'
{
"id": "a1b2c3d4-...",
"name": "n8n integration",
"keyPrefix": "owa_k1_3f9a2",
"role": "operator",
"isActive": true,
"usageCount": 0,
"createdAt": "2026-06-26T10:00:00.000Z",
"apiKey": "owa_k1_3f9a...full-secret-here..."
}

The dashboard surfaces that apiKey value in a copy-to-clipboard panel at creation, then drops it. Every subsequent list call returns the same record without the apiKey field — only keyPrefix for identification.

For roles, what each can do, and IP/session scoping, see Authentication.

Infrastructure (admin)​

The Infrastructure page reflects runtime status from GET /api/infra/status and lets an admin reconfigure the stack in place via PUT /api/infra/config.

  • Database health is probed with a live SELECT 1 on each connection (the same probe /health/ready uses), not a cached isInitialized flag — so a PostgreSQL backend that dies after boot shows as down instead of staying green.
  • Webhook queue depth reports real BullMQ job counts (waiting + active + delayed, plus completed/failed). The phantom "Message Queue" card (no such queue exists) and the dead "Clear Failed Jobs" button (it had no handler) have been removed. View Bull MQ Dashboard copies the URL with a hint — a plain browser tab can't send the required ADMIN X-API-Key header, so opening one only 401'd.
  • Postgres schema (POSTGRES_SCHEMA) is exposed as a field, placing OpenWA's tables and migration ledger in a dedicated schema (default public; SQLite ignores it). The schema must already exist. Since v0.23.6 the name must be a lower-case identifier (a lower-case letter or underscore, then lower-case letters, digits or underscores, at most 63 characters, not starting with pg_), and saving anything else, such as a mixed-case or padded name, is refused with 400. The gateway applies the same rule at boot from v0.23.6, where earlier releases accepted a mixed-case or padded name, so on PostgreSQL a mixed-case name, whether saved from this page on an older release, set in the project .env or set in the host environment, now stops the start with an error naming the rule, as does a padded name set in the host environment or quoted in the project .env or data/.env.generated. Correct it before upgrading.
  • If /infra/status fails to load, the page shows an error and a Retry instead of an editable form seeded from defaults — so a save can no longer flip a running built-in database/Redis/storage to external + empty.
  • A rejected PUT /api/infra/config (an unknown engine type, a value carrying a newline that would inject an extra env var, since v0.31.0 a database.poolSize above 9007199254740991, a configuration that would not boot in production, or, since v0.26.0, one that fails the boot environment validation) now returns its real 4xx status, not 200 { saved: false }. A boot-validation refusal reads Refusing to save a configuration that fails boot validation. followed by the reason, and nothing is written; examples are the built-in Redis with REDIS_TLS=true or a named REDIS_USERNAME, and an S3 endpoint without http:// or https:// that the save changes or newly selects. A database or storage section may also leave out type since v0.26.0, which keeps the stored selection. A genuine persistence fault still returns 200 with { saved: false } and, since v0.31.0, a message that names data/.env.generated and, when the error has a code, that code (Failed to save configuration: data/.env.generated could not be written (EACCES). The server log has the cause.) where it used to carry the filesystem error's own text, which named the host's data directory; a failure before the write says only that the save failed and that the server log has the cause.
  • GET /api/settings requires an admin key, and now reports the real enableDocs (from ENABLE_SWAGGER), apiBaseUrl (from BASE_URL), and autoReconnect (the engine's actual default, on) — instead of hardcoded values.
  • When a setting on any infra card is being supplied by a higher-precedence layer, the card shows a Pinned by the environment variable notice that names the variable doing the pinning (since v0.14.2). Since v0.26.0 the notice sits beside every setting a save writes (the database, Redis, queue and storage settings and the built-in flags as well as the engine ones; 31 settings in all), and envPinned in GET /api/infra/status can name any of them, where it could name eight. A pinned POSTGRES_BUILTIN, REDIS_BUILTIN or MINIO_BUILTIN says the built-in container still starts at every boot while the flag is true and the service is in use, even with the toggle off, and a pinned host decides the built-in toggle of its service (Use Built-in PostgreSQL Container, Use Built-in Redis Container or Use Built-in MinIO Container). A saved-but-not-restarted change is labelled separately so you can tell the two apart. The Engine card gained this notice for the first time in the same release — it had no pin indicator before.
  • Since v0.26.0 the built-in toggles start from the saved configuration, and a switch between a bundled container and an external service that was saved but not restarted for is labelled on its card (Saved, but not applied yet: the server runs with an external service now, and a restart switches it to the built-in container, or the same the other way round). The restart dialog warns about the data move when the save changes the database type, or the PostgreSQL host, port or database name, or the storage type, S3 endpoint or bucket (a Redis change carries no such warning), and lists the built-in containers the restart stops, which keep their data and are not deleted. Since v0.27.1, when the next boot uses the built-in PostgreSQL container and Docker fails to start it, POST /api/infra/restart refuses the restart with 409 (RESTART_DATABASE_NOT_STARTED), leaves the running server up, and rolls back any configuration saved since boot (and answers 409 with RESTART_ALREADY_RUNNING if another restart is already in flight). A *_BUILTIN flag starts its container at boot only while its datastore is in use (PostgreSQL selected; Redis, the queue or the cache on; S3 storage) and its host is not pinned to another server. GET /api/infra/config adds builtInSet to its database, redis and storage sections, which is true when the saved configuration states the built-in mode, and GET /api/infra/status adds running, which is true while a bundled container OpenWA created is up and this instance's built-in flag is set (absent while Docker is unreachable), and, for S3, the endpoint in use.
  • GET /api/infra/config reports each field's effective value with boot precedence: the host environment first, then the project .env, then data/.env.generated (since v0.20.0). Before that, a value pinned outside the file stack (a Compose-set ENGINE_TYPE, DATABASE_TYPE, or REDIS_ENABLED) read back as the first-run default, so the form showed a pinned stack as unconfigured.

Other tools​

  • Message Tester sends any message type ad-hoc and runs a number check (GET /api/sessions/{sessionId}/contacts/check/{number}) — useful for validating a session before wiring it into an integration. You can also forward an existing message to another chat, and a bulk batch, of text or (since v0.23.6) media, shows live progress in the response panel and can be cancelled mid-run. Since v0.23.6 the Group picker is a searchable checkbox list: select up to 100 groups and the message goes to each in turn, 3 seconds apart, with progress and a cancel button. The run stops early when the gateway answers 409, 429 or 503 (and, since v0.26.0, 502, a 400 that says the session is not running, or no answer at all, reported as stopped: the gateway did not answer), since the remaining groups would fail the same way, and a forward ignores all but the first selected group, which serves as the chat to forward from only when From Chat ID is left empty. Bulk mode can also attach a file or a media URL (a full http:// or https:// address), sent as an image, video, audio or document with the message text as its caption. Audio carries no caption, so text next to audio is refused, text longer than 1024 characters is refused as the caption of an image, video or document, and a picked file too large to repeat inline for every recipient is refused before sending; use a public media URL for those. Since v0.26.0 a phone number typed or pasted in the digits of another script (or in the full-width forms of a CJK input method) is read as ASCII digits, and the bulk recipient list reads a chat id wrapped in CSV quotes without them. See Sending messages for the underlying send endpoints.
  • Number Checker (v0.26.0+) checks whether numbers have a WhatsApp account without sending anything, through GET /api/sessions/{sessionId}/contacts/check/{number}. That route needs an operator key, so a viewer key opens the page with its Check and Start Batch Check buttons disabled. Pick a ready session under WhatsApp Session, then use Single Check (a result card with the WhatsApp JID, a Copy button and Go to Message Tester, plus a Recent Checks table that Clear History empties) or Bulk Number Checker. A bulk run takes up to 100 unique numbers, one per line or comma-separated, and waits Safe Pacing Delay (ms) between lookups (1000, 2000 or 3000); it keeps running while you leave the page, lists each number as Registered, Unregistered or Failed (filters All, Registered, Not Registered and Failed), and Export Results (CSV) downloads the rows. Numbers are reduced to their digits (separators are dropped, and a leading 00 is removed from a number of 12 digits or more), so include the country code; an opt-in Auto-prefix +91 checkbox adds the India code to 10-digit numbers and to 11 digits with a leading 0, and leaves a number written with a plus or 00 as it is. The run stops at the first answer that would fail every later number too, which is 403 (the key is refused the route), 409, 502 or a 400 for a session that is not started, 429 (the gateway's request limit, 100 a minute by default), 503 (WhatsApp did not answer) or no answer at all, and Batch stopped counts the numbers not sent. Since v0.31.0 a stop on a 409 that carries ENGINE_PAGE_RELOADING names the WhatsApp Web page reload as the reason, where it said the session is not connected.
  • Chats shows live chat threads. New messages arrive over a WebSocket, so the thread updates without a refresh. The chat view renders call messages (voice/video, with "missed" for an unanswered call), shared locations (a 📍 Location preview instead of a raw base64 thumbnail), native polls, and masked business messages (a short notice explaining the text is only available on the primary phone). When inbound media is skipped (MEDIA_DOWNLOAD_ENABLED=false, or the item is over the byte cap), the bubble shows a 📎 Media placeholder (a document shows its card instead since v0.31.0, see below). The same placeholder appears when the media was downloaded but did not fit the message list's per-response inline budget (MESSAGE_LIST_INLINE_MEDIA_BUDGET_BYTES). The placeholder is a button, not a dead label: clicking it fetches the bytes through the per-message media route, and it reports Media unavailable when they genuinely are not there. Since v0.23.4 a download that failed outright keeps the placeholder too, instead of rendering as an empty bubble. Since v0.23.6:
    • On whatsapp-web.js, messages the thread backfills from the engine's chat history show their quote preview and call detail, as live messages already did, and a group message backfilled that way also names its sender, a participant outside the account's contacts included; before, such a message often showed no sender label. Baileys does not serve the chat-history route (it answers 501), so its threads show only stored messages and are unchanged.
    • A message sent through any route that quotes (media, location, contact card, poll, or text with quotedMessageId) stores the quoted message's text, as a text reply already did, so its quote box is no longer blank. The reply sent by tapping a business prompt (below) quotes the prompt's text the same way. The text comes from the gateway's stored copy of the quoted message: one it never stored, or one with no text of its own such as a caption-less image, still shows an empty box, and rows saved before the upgrade keep the empty quote they were saved with.
    • A reply staged in one chat is dropped when you open another chat or switch session. Before, it was carried across: a text reply there failed with 404, since the quoted message is not in that chat, and a media send quoted the previous chat's message.
    • An inbound Baileys business prompt shows its choices as buttons, and a tap sends the choice through POST /api/sessions/{sessionId}/messages/click-button. The choices are stored with the message, so they render again after a reload, but a tap still needs the prompt in the engine's store and fails with 404 when the store does not hold it: once newer traffic has evicted it, after the session is logged out through the gateway, which empties the store, or for a prompt that arrived with the history synced when the account was linked, which never enters it. After a tap the choices are disabled and the chosen one is marked, but only while that chat stays open: the answered state is not stored, so after a reload or once you open another chat the choices can be tapped again, and each tap sends WhatsApp another reply to the same prompt.
    • Escape closes the open chat, channel or status viewer and returns to the list. It leaves the key alone while a dialog, a menu or the media viewer is open, and in the emoji picker it closes only the picker. In the message search at the top of the page, Escape dismisses the open results, or cancels a search still pending, and leaves the chat open; pressed again, it closes the chat.
    • A read-only (viewer) key is offered no reply, react or delete action, sees the prompt buttons disabled, has no Post a status or home-page Disconnect, and opening a chat with it sends no mark-as-read. Since v0.26.0 it also has no New chat button and, of a chat's menu, only a group's Group info, read-only.
    • Since v0.26.0 the chat list has All, Unread, 1:1 chats, Groups and Unknown quick filters (grouped as Filter chats), applied after the search box. Unread keeps a chat marked unread. Unknown keeps the 1:1 chats whose contact is not saved in the account's address book; it reads GET /api/sessions/{sessionId}/contacts when first chosen and shows Retry if that read fails. An Archived entry heads the list while the session has archived chats: archived chats leave the main list unless a search matches them, and pinned chats lead it. Since v0.27.0 the Chats page uses a full-height layout with no page header: the session switcher sits at the top of the Chats sidebar, lists every session with its status badge (ready sessions are selectable, and session.status socket events update the list in place), and a search toggle button sits beside New chat in the sidebar header. The main navigation sidebar's collapse button sits in its own header beside the logo.
    • Since v0.26.0 the New chat button in the Chats sidebar header (operator keys only) opens a panel that lists the account's saved, unblocked contacts and takes a number typed with its country code, such as +49 170 1234567 (a national number starting with 0 is refused). A typed number is checked first, and the chat opens only for a number WhatsApp confirms (an error toast says the number is not registered on WhatsApp otherwise). On Baileys the panel also offers New group: a name of up to 100 characters and its participants, created through POST /api/sessions/{sessionId}/groups. whatsapp-web.js answers that route with 501, so the entry is not offered there.
    • Since v0.26.0 each group and 1:1 row has a chevron menu (More actions), repeated in the open chat's header menu, and every entry but Group info (and Contact info on 1:1 chats in v0.27.0+) needs an operator key. A group offers Group info, Pin chat, Mute notifications (for 8 hours, 1 week or Always), Archive chat, Mark as unread (only on a chat with no unread messages) and Leave group. A 1:1 chat offers Contact info (v0.27.0+), Save contact (Rename contact once saved; disabled for a chat known only by its @lid privacy id), the same pin, mute, archive and unread entries, Block contact (Unblock contact) and Clear chat and Delete chat (on both engines since v0.27.0; on whatsapp-web.js only in v0.26.0). Both of those also delete the gateway's stored copy of the chat's messages, media included, so export the history first if you need it; on Baileys a deleted chat also records chat_states.deletedAt so it stays out of the chat list until a newer message re-creates it. WhatsApp keeps at most three chats pinned, and a change the engine declines reports WhatsApp declined the change.
    • Since v0.26.0 Group info opens a dialog with an Info tab (name, picture, description, Save changes) and a Participants tab (Add a number with its country code, Make admin, Remove admin, Remove). What it offers follows what WhatsApp lets the session's account do: an admin changes everything, a member only the info of a group whose info is not locked to admins, and anyone else reads it (Only group admins can change this group.). Since v0.27.0 the message thread also groups messages under day separators (Today, Yesterday, or the date).
    • Since v0.26.0 the sidebar reads GET /api/sessions/{sessionId}/chats page by page, 1000 chats at a time, until the last, where an account with more than 1000 chats saw only the first 1000. A page that cannot be read shows a banner (Failed to load chats and the reason) with Retry, so an unreadable list is not mistaken for an empty one; a failed session read shows Failed to load sessions with Retry instead of No connected sessions. Avatars come from one batch request for the first 50 chats in list order (GET /api/sessions/{sessionId}/contacts/profile-pictures): only the pictures the list does not hold yet are requested, and the ones on screen stay while the rest load. An id the gateway skipped after another lookup timed out is absent from the answer and is asked for again at once.
    • Opening a chat marks it read (an operator write, POST /api/sessions/{sessionId}/chats/read) in one call after a quiet moment. Since v0.26.0 a read due while the browser tab is hidden waits and goes out when the tab is visible again. Since v0.31.0 a read also waits for the thread: while its messages are loading, or after loading them failed, the chat is not read, and the unread badge cleared when the chat was opened comes back if the load fails or the chat is left before the thread showed; the read goes out once the thread has loaded. On Baileys, which acknowledges the messages a read names, the call names up to the 100 newest incoming messages the dashboard has not acknowledged yet, where it named only the newest; whatsapp-web.js reads the whole chat. Also since v0.26.0 the dashboard no longer asks Baileys for live chat history when it opens a chat, since Baileys answers 501 to it.
    • Since v0.26.0 a message the gateway saw edited carries an Edited label, kept after a reload, and a deleted message keeps its This message was deleted placeholder without one. A long chat name is cut where its own script ends, so a Latin name on an Arabic or Hebrew page keeps its first letters.
    • Since v0.26.0 the status composer names each font (System, System text, Script, Bold, Morning Breeze, Calistoga, Exo 2, Courier Prime) instead of its number. whatsapp-web.js posts font ids 8 to 10 in the default font, so on that engine the composer offers only the first five; the API still accepts every id.
    • Since v0.31.0 an open chat's header has a search button for that chat's stored messages (operator keys only: it reads GET /api/search, which needs the operator role). Type text, pick a day with the date field, or both: with text the day narrows the results, and a day alone jumps the thread to that day's first loaded message; when none is loaded, the bar says so, or asks you to scroll up first if older messages are still to load. A hit older than the messages the thread has loaded is not scrolled to either: the bar asks you to scroll up in the chat first. Escape closes the bar before it closes the chat.
    • Since v0.31.0 a message typed in a chat but not sent is listed on that chat's row, after a Draft: label, in place of the last message until the chat is opened again. The draft is kept in the open page, not by the gateway.
    • Since v0.31.0 typing / and part of a template name in the message field lists up to eight of the session's templates, for operator keys only: those whose name contains the text, those that start with it first (for a bare /, the first eight by name). A line says when more match, and typing more narrows the list. The arrow keys move the highlight, Enter puts the highlighted template, or a click the one clicked, into the field with its header, body and footer joined by blank lines and its first placeholder selected, and Escape closes the list. The text then goes out like any other message, as written: the composer fills in no placeholders. While the field holds a template exactly as inserted and a placeholder is still in it, Send is disabled; once the text is edited it can be sent.
    • Since v0.31.0 the message field is multi-line and grows with its draft up to a maximum height, then scrolls: Enter sends and Shift+Enter breaks the line. Opening a chat with a mouse click on its row, or from the New chat panel, puts focus in the message field so that typing can start at once (a read-only key's field is disabled, so focus stays where it is); a tap, or a row selected with the keyboard, leaves focus where it is.
    • Since v0.31.0 a document shows as a card with its file name, its size where known and, for a PDF, a PDF mark, and a click still downloads it; a document the message list left out is the same card and a click fetches it, where it showed only the 📎 Media placeholder. A shared contact shows as a card with its name and phone in the thread, and as its name and phone on the chat list row, in a quoted reply and in a message search hit (the sidebar's and the in-chat search alike), where the raw BEGIN:VCARD text was printed.
    • Since v0.31.0 a chat WhatsApp holds under a privacy id (@lid) with no saved, verified or push name is titled by its phone number, in the list and in the chat header, when the list read carries one (Baileys, once the session can map the id: the phone of GET /api/sessions/{sessionId}/chats); both used to show the privacy id's own digits. The chat search finds a chat by a number typed as it is written, with spaces, a plus sign, parentheses, hyphens or dots, and an unnamed privacy-id chat by the phone that titles it.
    • Since v0.31.0 starting an audio or video message on this page pauses any other one that is playing.
    • On whatsapp-web.js a message deleted for everyone is drawn once, as its stored row: since v0.30.2 when WhatsApp Web lists it under the id of the delete notice, and since v0.30.3 also when the history names the chat or the author in the other id form (phone number or lid) than the stored row. A row known only from the engine history shows no delivery ticks (since v0.30.2), since that history carries no delivery status; it showed read ticks. Since v0.31.0 a stored-message read refused with no answer, 408, 429 or a 5xx shows a failed load, which loads again when the chat is opened again or the window is focused, where the thread showed the engine history alone as the whole thread until a reconnect.
    • Since v0.30.2 an entry with nothing to show is not drawn: an unknown message with no text, media, quote or prompt buttons in the chat window, and a channel update with neither text nor media in the Channels tab.
  • Status viewer plays a voice status with an inline <audio> player. Voice statuses are Ogg/Opus blobs, so earlier builds rendered them as a broken image; since v0.14.0 the viewer picks the right element for the media type (image, video, or audio) and exposes playback controls.
  • Language. The dashboard ships fifteen locales: Arabic, German, English, Spanish, French, Hebrew, Hindi, Indonesian, Italian, Korean, Brazilian Portuguese, Telugu, Turkish, Simplified Chinese, and Traditional Chinese (Hong Kong). Hindi arrived in v0.23.7. Indonesian arrived in v0.24.0. A browser set to European or generic Portuguese gets the Brazilian catalogue since v0.26.0, where it fell back to English. Each catalogue is a separate file requested at runtime: the detected language, plus the English fallback for any other language, when the dashboard loads, and another language when it is selected. A CDN or path allowlist in front of the dashboard assets must pass them. A failed load falls back to English and left-to-right text.
  • Logs (admin) gives you an activity and audit trail across the instance (GET /api/audit). API-key lifecycle events are recorded here: api_key_created, api_key_updated, api_key_deleted, api_key_revoked (each with the acting admin key, client IP, and target key), and api_key_auth_failed for rejected or denied keys. Since v0.26.0 plugin changes are recorded too: plugin_installed, plugin_updated, plugin_uninstalled, plugin_enabled, plugin_disabled, plugin_config_updated and plugin_sessions_updated, and since v0.27.0 phone_second_lid_reported (warn severity) is recorded when an engine reports a second @lid privacy id for a phone number already mapped to another reported @lid. Since v0.31.0 creating, changing and deleting a webhook record webhook_created, webhook_updated and webhook_deleted (info severity), each with the key and the session and, in its metadata, the webhook id, the URL host, the events and the active flag, plus the names of the fields an update changed and the previous host when it changed the URL; the metadata never holds the secret or the header values, or the URL's path and query, and an update that changes nothing records no row. The Error severity filter returns no rows, since nothing writes that severity. Export CSV downloads the newest 10,000 entries that match the active severity filter, with the search box applied to those; when more exist, or the gateway throttles the audit reads, the file holds the newest rows fetched and the dashboard says so, and a narrower severity filter reaches older entries. A cell that starts with =, +, -, @, a tab or a carriage return is prefixed with an apostrophe so a spreadsheet shows it as text.

Chat media and keyboard access​

In v0.25.0, poll messages include their choices, and archive-only media can load a preview from the stored archive. Message actions are keyboard-accessible: focus the thread's message bubble, move with the arrow keys, and tab to its reply, reaction and delete controls. These controls remain unavailable to a viewer key. Since v0.31.0 the dashboard's tab rows (Number Checker, the QR and phone-number tabs of the connect modal, plugin install and configuration, the chat sidebar and group info) take the left and right arrow keys (swapped in a right-to-left row), which wrap, and Home and End, selecting the tab as a click does, and the selected tab is the row's one Tab stop. See Sending messages for poll and media response fields.

Troubleshooting​

ProblemCauseFix
Sign-in fails with API key is restricted to selected chatsThe key carries an allowedChats allowlist (v0.23.6+)Sign in with a key that has no chat allowlist; see Scope a key to chats.
Sidebar is missing API Keys / Infrastructure / Plugins / LogsYour key isn't an admin key. Since v0.24.0, an admin key restricted with allowedSessions also hides API Keys, Infrastructure and Plugins (Logs stays)Sign in with an admin key that has no session restriction, or have an admin grant you one. Roles are described in Authentication.
A session awaiting its QR shows no Show QR buttonYour key is a viewer keyThe QR is operator-only over both REST and the socket, so the button renders only for a key with write access. Use an operator or admin key.
QR view never shows a codeThe engine is still starting, or it lost its connection and is reconnecting: since v0.23.6 a session whose status turns disconnected has its code blanked while the view waits for a fresh one (on Baileys a socket that drops while the QR waits reports initializing instead, and its old code stays until the next one arrives). A row left at qr_ready after its engine stopped, for example by a node that went down mid-pairing, opens a view that never fillsWait a few seconds for the next code. If none arrives, close the view and restart the session: Stop then Start, or Reconnect on a row with no engine behind it.
QR scanned but row stays "awaiting QR"The code expired before the phone finished linkingA fresh code arrives on its own every few seconds; scan the next one promptly. If none arrives, stop and start the session again.
Webhook Test returns a failureYour endpoint is unreachable or didn't return 2xxConfirm the URL is publicly reachable from the instance and responds with a 2xx. The toast after Test shows the status code your endpoint returned, or the error the gateway hit reaching it. A test leaves no delivery-failure or audit record. When the toast says Destination address is not allowed, the SSRF guard refused the request (the host does not resolve, it resolves to a blocked internal address, or your endpoint answered with a redirect), and the gateway log has a warning, SSRF guard blocked webhook test: ..., that names the reason.
You can't find a key's full secretThe full value is only shown once, at creationRevoke the old key and create a new one; copy it immediately this time.

For wider issues, see Troubleshooting.

Next steps​