Glossary

Definitions for the terms used across the OpenWA documentation. Each entry is scoped to how the term applies in OpenWA v0.7.6 — 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. Track it through webhooks.

Legacy ack integer

The 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	CACHE_TYPE	memory (default), redis
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 carry the owa_k1_ prefix (for example owa_k1_3f9a…). The first master key is set with the API_MASTER_KEY environment variable; additional keys are minted through the API. 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.

warning

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), a group (120363123456789@g.us), or status (status@broadcast). Most message and contact endpoints take a chatId.

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

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.

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 you choose at creation. 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.

warning

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.

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 cache and job queue. Selected with CACHE_TYPE=redis. 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',
});

await client.sessions.start('my-session');
const result = await client.messages.sendText('my-session', {
  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.