Install and enable a plugin
Plugins extend a running OpenWA gateway in-process: they react to WhatsApp activity through typed lifecycle hooks and act through a narrow, permission-gated capability API — no fork, no core changes. This page shows you how to install a plugin, configure it, and enable it on a live gateway, then points you to the rest of the section.
A plugin is a self-contained folder — a manifest.json plus a compiled entry file — packaged as a .zip. It is installed disabled and runs only after an administrator explicitly enables it. Management is admin-only, over the REST API or the dashboard's Plugins page.
- A running OpenWA gateway. See Installation.
- An ADMIN-role API key with no
allowedSessionsorallowedChatsrestriction. Every plugin route requires the role; a key restricted to chats (v0.23.6+) is refused with403on all of them, and one restricted to sessions on all but the per-session config override. See Authentication. - A plugin
.zip. Grab one from the official catalog, or build one (see Building a plugin).
How plugins fit together
A plugin never touches the gateway's internals. It registers handlers for hook events and calls back into the host through capability namespaces, each gated by a permission it declared in its manifest.
The permissions a plugin can declare:
| Permission | Grants | Used for |
|---|---|---|
messages:send | ctx.messages.sendText / ctx.messages.reply | Auto-replies, notifications |
engine:read | Read-only engine queries (group info, contacts, chats, number check, chat history, canonical-id resolution) | Enriching events |
net:fetch | SSRF-guarded outbound HTTP, scoped to the manifest's net.allow host list (plus net.allowConfigHosts for operator-opened hosts); redirects are not followed, see the ctx.net.fetch contract | Calling external APIs |
webhook:ingress | ctx.registerWebhook — claim an inbound route | Integration Fabric (receive external webhooks) |
conversation:send | ctx.conversations.send, ctx.handover, ctx.mappings | Integration Fabric (normalized send, handover, identity map) |
search:provide | ctx.registerSearchProvider — serve the gateway's GET /api/search queries | Search plugins (required since v0.12.2) |
storage:use | ctx.storage.get / set / delete / list — the per-plugin key-value store | Persisting state across restarts (required since v0.17.0) |
The first three are the base outbound surface every plugin can use. The next two are the Integration Fabric — for bidirectional external integrations (helpdesk/CRM/chatbot handover) running as sandboxed plugins without a separate server. See Integration Fabric. The last two gate the search-provider capability and the per-plugin key-value store, so a search plugin and a plugin that persists state must each declare theirs explicitly.
A plugin that calls a capability it did not declare fails with a PluginCapabilityError. Capability calls are also confined to the sessions an operator activated the plugin for, not just the manifest's static scope. For the full hook list, capability surface, and lifecycle, see Plugin architecture.
storage:use became required in v0.17.0: a plugin reaches ctx.storage only if that string is in its manifest permissions array. Eight of the official plugins declare it, and seven of them need at least these versions — chatwoot-adapter 0.9.1, chat-flow 1.1.2, group-translate 1.3.1, gsheets-logger 0.3.3, http-action 0.2.2, typebot-connector 0.2.2, and voice-transcription 1.2.3. Upgrade to at least these versions before upgrading the gateway; the new versions run on an older gateway, which ignores the unrecognised permission string, while the old versions break on v0.17.0. after-hours, faq-bot, and supabase-otp-hook never touch ctx.storage and need no upgrade. The eighth, rocketchat-adapter, requires OpenWA 0.30.0 or later, so it needs no upgrade either.
A plugin below its floor is not refused at load. It is denied at its next storage call, so an upgraded gateway looks correct until the plugin tries to store — and a plugin that stores during onEnable lands in ERROR and stays disabled rather than merely losing the write. The fix is one manifest line, "storage:use", then a reload. Version floors per plugin are in the plugin catalog.
Disk-loaded plugins run in a worker_thread (V8-context isolation), but that is not an OS-level sandbox — a plugin can reach Node built-ins like fs and process. Install only plugins you trust, and review a plugin's declared permissions and sessions before enabling it.
The install flow
Installing a plugin from a .zip is a three-step sequence — install, configure, enable — because OpenWA never auto-runs freshly uploaded code.
All routes sit under the /api prefix and require an ADMIN key in the X-API-Key header. The examples below use the faq-bot plugin, which auto-replies from configurable keyword rules.
1. Install the package
Upload the .zip as multipart form field file:
curl -X POST "http://localhost:2785/api/plugins/install" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@faq-bot.zip"
The plugin is now installed but disabled — it is not running yet:
{
"id": "faq-bot",
"name": "FAQ / Auto-Reply Bot",
"version": "0.2.22",
"type": "extension",
"status": "installed",
"builtIn": false
}
If your gateway is configured with the official catalog, you can skip the build-and-upload step and install by URL instead: POST /api/plugins/install-url with body { "url": "<release-zip-url>" }. The download runs through the SSRF guard, which refuses an internal or reserved address on the original URL and on every redirect hop. It also refuses a redirect that downgrades from https to http: the call answers 400 with Failed to download plugin from URL: Refusing redirect that downgrades from https to http: <url>, unless the operator sets PLUGIN_DOWNLOAD_ALLOW_INSECURE_REDIRECTS=true. A chain that starts on http is not a downgrade, but http, then https, then http is still refused. Any public host is reachable: nothing restricts an install to a curated list, and the integrity control is the #sha256= pin described next. An https:// URL installs as-is; since v0.19.0 a plain http:// URL is also accepted, but only when it pins its expected bytes with a #sha256=<64-hex> fragment — verified fail-closed against the downloaded bytes before anything is installed — and is rejected before any fetch otherwise. Since v0.20.0 an https:// URL needs the pin too under NODE_ENV=production (the compose default): https authenticates the channel, not the bytes as reviewed, so a production catalog install without a pin fragment now fails until you pin the URL or set PLUGIN_INSTALL_REQUIRE_PIN=false. The fragment is never sent to the server, so a catalog download link can carry it. A malformed marker or a digest mismatch fails the install closed. After the transport rule and the pin requirement above, and before anything is downloaded, a URL that carries a user name or password is refused with 400 and Failed to download plugin from URL: URL must not contain credentials (userinfo), which since v0.31.0 no longer repeats the URL. See the catalog.
2. Configure it
Each plugin declares a configSchema in its manifest. Send the settings as a config object. For faq-bot, that means the reply rules and an optional fallback:
curl -X PUT "http://localhost:2785/api/plugins/faq-bot/config" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"config": {
"rules": "[{\"mode\":\"contains\",\"pattern\":\"hours\",\"reply\":\"We are open 9-5, Mon-Fri.\"}]",
"fallbackReply": "Thanks! Someone will reply shortly.",
"respondInGroups": false
}
}'
{ "success": true, "message": "Plugin faq-bot configuration updated" }
Config fields marked secret: true (an API key, a service-account JSON) are masked on read and preserved on an unchanged write — so you never have to re-paste a secret to edit an unrelated field. A write keeps a stored string secret when the field is sent empty or as ***, or when the key is left out of a PUT /api/plugins/{id}/config body, and the call still answers success: true; send a new value to replace it, or null to remove it (v0.26.0+). Since v0.28.0 PUT /api/plugins/{id}/config also deep-merges nested plain-object fields into the stored config and clears a key at any depth when sent null. A client that sends null for "not provided" must therefore leave the key out. Before v0.26.0 null kept the secret too; since v0.26.0 the dashboard's config form sends null for a secret field the operator clears. On the two built-in engine plugins (whatsapp-web.js and baileys), GET /api/plugins/{id} merges defaults and environment settings over stored config and masks secret keys (***) even when nothing is stored in the plugin registry: since v0.27.0, sending null for a top-level key (or at any nested depth since v0.28.0) removes that stored key so the .env setting applies again, and sending *** for a masked secret key that has no stored value is ignored so saving the object returned by GET /api/plugins/{id} does not overwrite .env; on whatsapp-web.js a partial puppeteer object also falls back to PUPPETEER_HEADLESS and PUPPETEER_ARGS for unset keys (v0.28.0+). A per-session write replaces that session's whole override, so any key left out of it, a secret included, is dropped. A per-session write that moves a host key (a key the manifest lists in net.allowConfigHosts, such as baseUrl) to another origin than the override already holds, or than the base config names when the override holds none, gets no stored secret back for *** or an empty string (v0.26.0+); send the secret with it. A list of secret values (for example, a rotating set of API keys) survives an append, and survives a removal when the remaining rows can be told apart by their non-secret fields: surviving entries keep their stored secret, while a genuinely new or edited row is never grafted with a stored value. Where the remaining rows cannot be told apart (a list of bare secret values, or rows that differ only by a secret), a removal stores nothing and answers success: false with This change to a list of masked secrets cannot be matched to the stored values; re-enter the remaining secret values (v0.23.7+), so send those secret values again instead of ***. Since v0.31.0, in a save of the same length in which a row moves (the rows are reordered, or a row is removed ahead of a kept row and another is added), a row whose other fields were edited with its mask untouched is saved without its secret, and so are the remaining rows of a group that differ from one another only by their secret when one of that group was edited or removed; enter those secrets again. Also since v0.31.0, a stored secret is saved on one row at most. A field that is not marked secret is returned as written: http-action keeps every action's request.headers inside its non-secret actions field, so those values come back unmasked and a credential belongs in its authToken instead.
OpenWA renders configSchema into the dashboard form and redacts secret fields, but it does not enforce the schema's types on write. A well-built plugin validates its own config defensively when it starts.
3. Enable it
Enabling runs the plugin's onLoad then onEnable lifecycle and registers its hooks:
curl -X POST "http://localhost:2785/api/plugins/faq-bot/enable" \
-H "X-API-Key: YOUR_API_KEY"
{ "success": true, "message": "Plugin faq-bot enabled successfully" }
The plugin is now live. Send a WhatsApp message containing "hours" to a connected session and it auto-replies. Confirm the running state any time:
curl "http://localhost:2785/api/plugins/faq-bot" \
-H "X-API-Key: YOUR_API_KEY"
If onLoad or onEnable throws, POST /api/plugins/{id}/enable answers HTTP 200 with { "success": false, "message": "<the error>" }, and the plugin's status becomes error. The two config writes answer the same way when the write fails. A script must check success rather than the status code. An unknown plugin id answers 404, and a request body that is not a valid config object answers 400, as does a per-session write to a global plugin.
A plugin never auto-enables after install. This keeps untrusted code from running silently. Across a gateway restart the operator's decision is kept (v0.10.5+): a plugin that was enabled is enabled again once the gateway is up. One whose re-enable fails shows error, and one that no longer loads is missing from GET /api/plugins (see Management endpoints). Disabling a plugin withdraws the decision.
The gateway restores the plugins an operator had enabled, one after another, before it opens its HTTP port, but it waits at most 60 seconds for that. When the wait runs out it logs plugin_restore_deferred, opens the port, and the plugins not yet restored keep coming up in the background, in order. Before v0.26.0 the port stayed closed until every plugin was back, so slow plugin backends could keep a gateway failing its health checks.
Until a plugin is up it reports installed and the hooks it owns do not run, so a request that arrives meanwhile is not seen by them (a send moderation veto, for one); do not rely on a plugin veto while a plugin is still restoring after a boot with slow plugins. Enable, disable, update, uninstall and an install of the same id answer 409 (Plugin <id> is still being restored after startup. Retry in a moment.) until the restore is done with it. A delivery to its ingress routes is refused with 503 and Retry-After, or held until it is up, as Author an Integration Fabric adapter describes.
On OpenWA ≥ 0.10.0 the dashboard intercepts an enable attempt when required config fields are unset and opens the plugin's config dialog with a warning, instead of the plugin landing in ERROR on a raw sandbox failure. Fields that declare a schema default are already seeded into the stored config at load, so only required fields without a default trigger the intercept.
Two runtime guarantees apply behind the scenes:
- Lifecycle ops are serialized per plugin id. Two concurrent
enablecalls for the same plugin can't double-runonEnableor register hooks twice; a racing caller is rejected. Install, update and uninstall of one id are serialized with them; before v0.26.0 an uploaded package skipped that lock, so it could interleave with an uninstall or update of the same id. - Integration instance bindings self-heal on restart. A boot-time reconciler re-derives every enabled Integration Fabric instance's session binding from the persisted instance rows, so a binding lost while a plugin was momentarily unloaded is restored on the next boot without an operator re-PATCH. An enabled instance bound to all sessions writes its config into the plugin's base config, and since v0.26.0 the secrets it contributed are taken back from that base config when the instance is deleted, disabled, moved to one session or saved without them (unless the base value was changed since). See Integration Fabric.
Scope a plugin to specific sessions
By default a plugin that declares sessions: ["*"] acts on every session. To restrict a session-scoped plugin to a subset, set its active sessions:
curl -X PUT "http://localhost:2785/api/plugins/faq-bot/sessions" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "sessions": ["sales", "support"] }'
Use ["*"] for all sessions or [] for none. A sessions value that is not a JSON array answers 400 (v0.26.0+); before, an object there was read as [], which switched the plugin off for every session. The session scope a plugin may act on is fixed by its manifest — activation can narrow it but never widen it past what the manifest's sessions allows.
To give one session different settings, set a per-session config override with PUT /api/plugins/{id}/config/{sessionId} (send an empty config to clear it). The override is deep-merged over the base config for that session's events: nested plain objects merge key by key, so a sparse override cannot drop a base key it did not touch (a nested secret in particular), while arrays and scalars are replaced wholesale. A host key is the exception (v0.26.0+): when the override points a key that the manifest lists in net.allowConfigHosts (such as baseUrl) at another origin than the base config names, it inherits none of the base config's secret fields and must bring its own, because a stored secret belongs to the host it was saved for. A list that holds a secret is dropped whole, and a host key that holds a list, an object or a number counts as another origin. An integration instance's own config follows the same rule over the layers beneath it, and an instance loses its own secrets while a per-session override has moved a host key the instance leaves unset away from the base config. Override support is per-plugin — a plugin honors it only if it re-reads its config per event — and each official plugin's status is listed in the plugin catalog.
Management endpoints
Every route below sits under /api and requires the ADMIN role.
| Method & path | Purpose |
|---|---|
GET /api/plugins | List installed plugins and their status |
GET /api/plugins/catalog | List the remote catalog, annotated with install state. A catalog with an entry whose id, name or version is not a non-empty string, or whose other text fields are not strings, is refused as a whole with 400 (v0.26.0+; the default catalog is unaffected, and a private PLUGIN_CATALOG_URL catalog must correct the entry). A null optional field is accepted and left out of the answer. A PLUGIN_CATALOG_URL that carries a user name or password is refused with 400 and Failed to fetch plugin catalog: URL must not contain credentials (userinfo), which since v0.31.0 no longer repeats the URL |
GET /api/plugins/{id} | Inspect one plugin (config secrets redacted) |
POST /api/plugins/install | Install from an uploaded .zip (multipart field file) |
POST /api/plugins/install-url | Install by downloading a .zip from any public https:// URL (SSRF-guarded on every redirect hop; a redirect from https to http is refused), or an http:// URL carrying a #sha256= integrity pin (in production every URL install needs the pin, v0.20.0+) |
POST /api/plugins/{id}/update | Update in place from a URL (keeps config + enabled state) |
POST /api/plugins/{id}/enable | Enable (runs onLoad → onEnable) |
POST /api/plugins/{id}/disable | Disable and unregister its hooks. For the engine ENGINE_TYPE selects, answers success: false and changes nothing (v0.23.6+) |
PUT /api/plugins/{id}/config | Update base config (body { "config": { … } }) |
PUT /api/plugins/{id}/config/{sessionId} | Set or clear a per-session config override |
PUT /api/plugins/{id}/sessions | Set which sessions a scoped plugin is active for |
GET /api/plugins/{id}/config-ui | Serve the plugin's sandboxed HTML config editor (Content-Security-Policy: sandbox, X-Content-Type-Options: nosniff) |
GET /api/plugins/{id}/health | Run the plugin's healthCheck. A sandboxed plugin with no running worker (disabled, never enabled, or failed) answers 200 with healthy: false (v0.23.7+), so alerting on this route also fires for a plugin you disabled on purpose |
DELETE /api/plugins/{id} | Uninstall and delete files (built-ins are protected) |
Since v0.31.0 an install, an install by URL and an update check a package's ingress declarations by the rules the loader applies at load, so a package the host would refuse is answered 400 with the reason before anything is written, and an update is refused before the running plugin is stopped, where it used to be stopped and unloaded first and rolled back if the new package then failed to load or enable, or the gateway began shutting down meanwhile. The checks include an unsigned route while ALLOW_UNSIGNED_INGRESS is off, an unsupported sdkVersion major, a missing webhook:ingress permission and, new in v0.31.0, an ingress that is not a list, an hmac-sha256 contentTemplate that is not a string, a header or timestampHeader that is not a string on an hmac-sha256 or shared-secret route, and a dedupHeader or conversationId.header that is not a string. An installed plugin whose manifest has one of the shapes new in v0.31.0 fails to load at boot: its status is error and the log names the field and, where the field belongs to a route, the route; v0.30.3 did not check these fields, so such a manifest could fail to load, fail at runtime or be read as if the field were absent.
Since v0.26.0 each successful install, update, uninstall, enable, disable, config write (base or per session) and session-activation change adds a row to the audit log (plugin_installed, plugin_updated, plugin_uninstalled, plugin_enabled, plugin_disabled, plugin_config_updated, plugin_sessions_updated), attributed to the calling key. The row carries the plugin id and, in metadata, the version and the download host (upload for an uploaded package), the config field names (never their values), or the session list; a per-session config write also sets the row's sessionId. A change that is refused, or that answers success: false, adds no row.
A plugin's status is one of installed, enabled, disabled, or error. A plugin whose load fails at boot is not loaded: GET /api/plugins does not list it, and GET /api/plugins/{id} and the other /api/plugins/{id} routes answer 404, except disable and DELETE, which act on its stored registry entry (disable withdraws the enable decision; DELETE removes the plugin). That entry is reconciled to error rather than left reporting installed or enabled, and keeps the plugin's config and enable decision: once the plugin loads again at a later boot, it is re-enabled if it had been enabled, while a corrected version installed on a running gateway loads as installed and runs once POST /api/plugins/{id}/enable is sent or, if it had been enabled, at the next restart (send disable before that restart to keep it off). The full request and response shapes are in the API reference.
In the dashboard's Plugins page, an installed plugin whose catalog entry lists a strictly newer version carries an update chip on its card, and the Install button shows a pending-update count (v0.19.0+) — the chip opens the Install drawer's catalog tab pre-filtered to that plugin, where the update flow lives.
Disable or uninstall
Disable a plugin to stop it without losing its config:
curl -X POST "http://localhost:2785/api/plugins/faq-bot/disable" \
-H "X-API-Key: YOUR_API_KEY"
The built-in engine the gateway runs on, the one ENGINE_TYPE (or the dashboard's Infrastructure → Engine setting) selects, cannot be disabled this way. Since v0.23.6 the call answers HTTP 200 with { "success": false } and a message to switch engines through configuration and restart (the message names the engine.type key, which ENGINE_TYPE sets), so a script must check success rather than the status code. Before, it reported success while sessions kept running on that engine.
Uninstall to remove the plugin, its files, its stored config and its ctx.storage data:
curl -X DELETE "http://localhost:2785/api/plugins/faq-bot" \
-H "X-API-Key: YOUR_API_KEY"
Since v0.25.0 an uninstall also hands every chat the plugin had taken over back to the bot. It leaves an Integration Fabric plugin's integration instances, with the ingress secret and config each one holds, and its conversation mappings in the database, so a plugin installed again finds them. Delete an instance for good with DELETE /api/integration/plugins/{pluginId}/instances/{instanceId}, which works once the plugin is gone. On SQLite that delete waits up to 10 seconds for another open database transaction and then answers 503 with nothing deleted (v0.26.0+); retry it.
Since v0.27.0 DELETE /api/plugins/{id} first clears the plugin's registry entry (config, activeSessions, sessionConfigs, and enabled: false) and flushes registry.json before unloading the worker or deleting files: if that upfront registry write fails, the call answers 500 with nothing removed (the plugin stays running), and while the uninstall is unloading the plugin any PUT /api/plugins/{id}/config* or PUT /api/plugins/{id}/sessions call answers 409. If removing the package directory or its storage folder fails after the plugin has been unloaded, the call answers 400 with the error, leaves the cleared registry entry so the same DELETE can be retried to finish cleanup, and writes a plugin_uninstalled audit row with metadata.partial: true and fileDeleteError. If the files are removed and only the final registry.json write to delete the emptied entry fails, DELETE answers 200 (success: true) and notes that repeating DELETE /api/plugins/{id} removes the emptied entry once registry.json is writable. When registry.json cannot be written on POST /api/plugins/{id}/enable, POST /api/plugins/{id}/disable, PUT /api/plugins/{id}/config, or PUT /api/plugins/{id}/config/{sessionId}, the gateway rolls back the in-memory change and answers 200 with success: false (while PUT /api/plugins/{id}/sessions answers 500).
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
401 Unauthorized | No X-API-Key header, or the key is invalid, expired, or revoked | Send a valid key. See Authentication. |
403 Forbidden | The key is valid but its role is below ADMIN, its allowedIps exclude the client, or its allowedSessions exclude the requested session (both since v0.24.0); or it is restricted to chats (allowedChats, v0.23.6+), which every plugin route refuses; or it is restricted to sessions (allowedSessions), which every plugin route refuses except PUT /api/plugins/{id}/config/{sessionId} for a session inside the key's scope | Use an unscoped ADMIN key. A role that is too low never surfaces as 401. |
404 Not Found on a plugin route | Plugin id not installed, or the plugin is installed but failed to load at boot (the boot log reports plugin_load_failed; since v0.23.6 a stricter ingress manifest check refuses some packages that earlier releases loaded, and v0.31.0 widens it to more manifest shapes) | Confirm the id with GET /api/plugins; ids are case-sensitive. For a plugin that failed to load, install a corrected version and enable it, or remove it with DELETE (see Management endpoints). |
Plugin shows installed after a restart | Either no enable decision is stored for it: it was never enabled, it was disabled before the restart, or it was enabled on a release before v0.10.5 that no longer recorded it as enabled when the gateway was upgraded (a restart on those releases cleared that status, and so did a clean shutdown from v0.6.2 on); or, from v0.26.0, the gateway is still restoring it | Enable it with POST /api/plugins/{id}/enable; restarts keep it enabled from then on. A plugin still restoring turns enabled, or error if it fails to come back, on its own. |
409 Conflict on enable, disable, update, DELETE, config, sessions, or an install of the same id | The plugin is still being restored after a start (v0.26.0+), or an uninstall is in progress (v0.27.0+) | Retry in a moment. The port opens after at most 60 seconds of restore, and a slow plugin can keep restoring in the background after that. |
Plugin is enabled but does nothing | Empty/invalid config, or wrong session scope | Re-check the config object and the plugin's active sessions. |
error status | Plugin threw during onLoad/onEnable (the enable call answers 200 with success: false), or, while it was running, its sandbox worker crashed (logged as sandbox_worker_exit) or, since v0.24.0, stopped answering (logged as sandbox_worker_unresponsive) | Inspect the error field from GET /api/plugins/{id} and the gateway logs. Once the cause is fixed, enable the plugin again; it is not restarted automatically. |
Capability call fails with PluginCapabilityError | Plugin used a permission it did not declare, or an out-of-scope session | This is the plugin author's fix — see Building a plugin. |
Next steps
- Browse ready-to-install plugins in the plugin catalog.
- Understand hooks, capabilities, and the sandbox in Plugin architecture.
- Write your own with Building a plugin.
- Ship it to others via Publishing a plugin.