Glossary
Definitions for the terms used across the OpenWA documentation. Each entry is scoped to how the term applies in OpenWA v0.31.0, not the broader industry meaning. Skim for the term you need; cross-references link to the page that uses it in context.
ACK
A WhatsApp message delivery acknowledgement. Each outbound message advances through a
sequence of delivery states. OpenWA surfaces these on the message.ack event and webhook
as a neutral status string — the same five values regardless of which engine
is selected:
status | Meaning |
|---|---|
failed | The message failed to send. |
pending | Queued locally, not yet sent. |
sent | Reached WhatsApp's servers. |
delivered | Delivered to the recipient's device. |
read | Read (or played, for voice and video notes) by the recipient. |
Delivery is monotonic: a message only moves forward. On Baileys since v0.28.0, message.ack also reports delivered and read for a group message the account sent once every non-self member in the group roster has delivered or read it. On whatsapp-web.js since v0.28.0, per-recipient delivery and read timestamps for an outbound message can be read with GET /api/sessions/{sessionId}/messages/{chatId}/{messageId}/receipts. Track delivery events through webhooks.
ack integerThe payload also carries a deprecated ack integer (-1 failed, 0 pending, 1 sent,
2 delivered, 3 read) kept only for backward compatibility. Read the neutral status
field instead. There is no separate "played" value: both engines collapse the played
state into read, so a played status or an ack of 4 never reaches the event or
webhook.
Adapter
A pluggable implementation that swaps a capability without changing application code. Adapters are chosen at startup by environment variable:
| Capability | Env variable | Options |
|---|---|---|
| Database | DATABASE_TYPE | sqlite (default), postgres |
| Storage | STORAGE_TYPE | local (default), s3 |
| Cache | REDIS_ENABLED | false (default), true |
| Engine | ENGINE_TYPE | whatsapp-web.js (default), baileys |
See Configuration for the full variable list.
API key
The credential that authenticates every API request, sent in the X-API-Key header.
Keys the gateway generates or mints through the API carry the owa_k1_ prefix (for example
owa_k1_3f9a…). The first master key can be set with the API_MASTER_KEY environment
variable and is used as given, so it need not carry that prefix; in production it must be
at least 32 characters. Additional keys are minted through the API.
Each key carries a role and can be narrowed to source IPs (allowedIps), sessions
(allowedSessions) and, since v0.23.6, chats (allowedChats, a list of groups and
contacts). Never commit a key — examples in these docs use the placeholder YOUR_API_KEY.
curl http://localhost:2785/api/health/ready \
-H "X-API-Key: YOUR_API_KEY"
See Authentication.
Auth state
The WhatsApp linked-device credentials persisted to disk so a session reconnects without a fresh QR scan. The whatsapp-web.js engine stores a Chrome profile; the Baileys engine stores credential files. Treat auth state as irreplaceable — deleting it forces the user to scan a new QR code.
Auth state is a secret. Anyone with a copy can act as the linked WhatsApp account. Back it up with the same care as a private key.
Baileys
A WhatsApp engine that connects to WhatsApp Web over a WebSocket
directly, with no browser. Select it with ENGINE_TYPE=baileys. Baileys uses far less
memory than the Chromium-based default, at the cost of tracking the WhatsApp Web protocol
more closely.
Chat ID
The identifier of a WhatsApp conversation, expressed as a JID. It is an individual
(628123456789@c.us, or <lid>@lid for a user known only by a privacy id), a group
(120363123456789@g.us), a channel (<id>@newsletter), a broadcast list (<id>@broadcast),
or status (status@broadcast). Most message and contact endpoints take a chatId. A send or message-action body needs the id with its domain: a bare number such as 628123456789 answers 400 (v0.26.0+).
Engine
The component that connects OpenWA to WhatsApp. OpenWA ships two pluggable engines,
selected with ENGINE_TYPE:
whatsapp-web.js is the default (Puppeteer-driven Chromium); baileys is
the browser-free alternative. OpenWA normalizes the two engines' JID dialects to
one neutral form at the engine boundary, so application code stays engine-agnostic.
Event
A system occurrence delivered to subscribers, such as message.received, message.ack,
session.status, or session.qr. Events drive webhooks and the real-time
WebSocket channel. See Webhooks.
Health check
An endpoint for monitoring and orchestrators. GET /api/health returns basic status
(and the running version, but only to a request carrying a valid API key, v0.19.0+),
GET /api/health/live is a liveness probe, and GET /api/health/ready is a readiness
probe that verifies the auth/audit and data databases respond (it does not probe the
cache). A failing readiness probe returns 503. See Deployment.
Idempotency key
An optional caller-generated Idempotency-Key header on twelve single-recipient send routes in v0.25.0. Within its 24-hour window, the gateway replays a completed result for the same key and payload, rejects a different route or payload with 422, and answers 409 while the result is unresolved. An ambiguous engine failure keeps the reservation to avoid sending twice, while a failure that proves nothing was handed to WhatsApp, such as a 4xx or 501 refusal before the engine call, a WhatsApp rate limit on Baileys (v0.26.0+), or an engine refusal before the write when the session or connection is not ready, a media, sticker or preview thumbnail cannot be fetched or read, or on Baileys the recipient is not on WhatsApp or the quoted or forwarded message is not found in that chat (v0.27.0+), frees it. Since v0.31.0 a video sticker whose conversion fails on whatsapp-web.js and, on Baileys, a media upload that WhatsApp's media host refuses free it too. See Sending messages. The separate X-OpenWA-Idempotency-Key on a webhook identifies its delivery for receiver-side deduplication; it is not a send request header.
JID
The WhatsApp identifier format, inherited from XMPP (Jabber ID); the user-facing Chat ID is a JID. The same entity can appear in more than one dialect:
| Dialect | Example | Used by |
|---|---|---|
<phone>@c.us | 628123456789@c.us | The neutral form OpenWA exposes |
<phone>@s.whatsapp.net | 628123456789@s.whatsapp.net | Baileys' raw form |
<id>@g.us | 120363123456789@g.us | A group |
<lid>@lid | 185…@lid | A LID (privacy ID) |
OpenWA normalizes engine IDs to the single neutral dialect at the engine boundary.
LID
A WhatsApp privacy identifier (<number>@lid) that addresses a user without exposing
their phone number — increasingly common in groups and communities. The number in a LID is
not a phone number; a separate mapping resolves it to a phone when WhatsApp supplies one.
OpenWA keeps an unresolved LID as-is rather than guessing a phone. Every mapping it learns is
stored in the lid_mappings table. Since v0.26.0 only a pair an engine has reported makes a phone
id and the LID count as the same person in webhook and automation filters, the message and status
list filters, and a key's allowedChats; a phone learned only from a cache lookup is kept for
display. Mappings stored by older versions, and those restored from an older backup, are display
data until an engine reports the pair, and an id a key or filter names exactly still matches.
On Baileys, the chat list (GET /api/sessions/{sessionId}/chats) gives a chat held under a LID that
has no saved, verified or push name an empty name, and carries its phone as phone when the
session can map the LID (v0.31.0+): title such a chat by phone, else by id. whatsapp-web.js
lists no phone, and a chat the page gives no title is listed under its own id.
Multi-session
Running multiple independent WhatsApp sessions inside one OpenWA instance — one session per phone number. Each session has its own auth state and connection. See Sessions.
QR code
The code scanned in the WhatsApp mobile app (Linked devices) to link a new
session. The API delivers it on the session.qr event; a generated code is
short-lived and regenerates until scanned. See First Session.
Session
A single WhatsApp Web connection — one phone number equals one session. The core unit
OpenWA manages, addressed by a session ID the server generates at creation. The only value
you choose is the name; the id comes back in the create response and is what every later
route takes in its path. Sessions move through a
lifecycle from creation to connected:
See Sessions.
Swagger
The interactive, auto-generated API documentation served at /api/docs (for example
http://localhost:2785/api/docs). It is enabled outside production and disabled in
production by default; opt in on a production deployment with ENABLE_SWAGGER=true. For
hand-written endpoint docs, see the API Reference.
A public /api/docs exposes your full API schema. Keep Swagger off (or access-restricted)
on internet-facing deployments.
Webhook
An HTTP callback OpenWA sends to a URL you register when an event occurs — a message arrives, a session changes status, and so on. Failed deliveries are retried. Configure webhooks per session and verify their signatures. See Webhooks.
Webhook outbox
The persisted outbound-delivery records used to recover a dispatch interrupted before it settles. In v0.25.0, replay covers a stranded queued record as well as a pending one. A terminal failure is not retried by the replay sweep: an administrator can redrive it only when payload retention was enabled and the row is still replayable. Receiver-side deduplication is required because replay can repeat a delivery. See Webhooks for replay, retention and redrive limits.
WebSocket
A protocol for real-time, bidirectional communication. OpenWA uses it for the dashboard's live updates and, internally, for the Baileys engine's connection to WhatsApp.
whatsapp-web.js
The default engine. It drives a headless Chromium browser through
Puppeteer to interact with WhatsApp Web. It is selected with
ENGINE_TYPE=whatsapp-web.js, or by leaving ENGINE_TYPE unset.
Supporting terms
Terms referenced above, defined once for completeness.
Puppeteer
The Node.js library that controls a headless Chromium browser. The whatsapp-web.js engine uses it to drive WhatsApp Web.
Redis
An in-memory data store used (optionally) for the rate-limit counters, the cache connection and
WebSocket fan-out across replicas (REDIS_ENABLED=true), and for the job queue (QUEUE_ENABLED=true).
Cached data is ephemeral and rebuilds from the database.
SDK
The official JavaScript/TypeScript client, published as @rmyndharis/openwa. It wraps the
HTTP API behind a typed OpenWAClient:
import { OpenWAClient } from '@rmyndharis/openwa';
const client = new OpenWAClient({
baseUrl: 'http://localhost:2785',
apiKey: 'YOUR_API_KEY',
});
// Session calls are addressed by the server-generated id, not the name.
const sessionId = '8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a';
await client.sessions.start(sessionId);
const result = await client.messages.sendText(sessionId, {
chatId: '628123456789@c.us',
text: 'Hello from OpenWA',
});
console.log(result.messageId);
See the SDK overview.
Abbreviations
| Abbreviation | Meaning |
|---|---|
| ACK | Acknowledgement |
| API | Application Programming Interface |
| HTTP | HyperText Transfer Protocol |
| JID | Jabber ID |
| JSON | JavaScript Object Notation |
| LID | WhatsApp privacy identifier |
| LTS | Long Term Support |
| QR | Quick Response (code) |
| REST | Representational State Transfer |
| S3 | Simple Storage Service |
| SDK | Software Development Kit |
| TLS | Transport Layer Security |
| URL | Uniform Resource Locator |
| WS | WebSocket |
Next steps
- Follow the API conventions reference for request and error shapes.
- Browse the full API Reference.
- Hit a snag? Check Troubleshooting.