Skip to main content
Version: v0.31.0

Plugin Catalog

The twelve official plugins maintained in the openwa-plugins marketplace repository. Each entry lists what the plugin does, the permissions it declares, its configuration keys, and the minimum OpenWA version it requires.

Every plugin here is an extension that runs sandboxed in a worker thread and hooks message:received (some hook more) — except supabase-otp-hook, which declares no hooks at all and is driven entirely by its ingress route. For the runtime model and the permission system, see Plugin Architecture. To install and configure a plugin, see Plugins Overview.

Since v0.23.6 a Baileys session, once it reconnects, also passes on the messages WhatsApp queued while it was offline: inbound ones reach message:received, and those the account sent from its phone reach message:sent. An older gateway dropped both. The plugins below do not all treat that backlog as live: faq-bot, group-translate and ai-responder skip a message that reaches them more than five minutes after it was sent, after-hours answers only when the shop was closed at the message's own send time as well as on arrival, chatwoot-adapter and rocketchat-adapter relay it, and gsheets-logger logs it at its send time. Each plugin's section gives its own rule.

Summary​

PluginDoesPermissionsStatusRequires
after-hoursAway reply outside business hoursmessages:sendstable≥ 0.7.0
ai-responderOpenAI-compatible auto-reply, last in the responder chainnet:fetch, messages:sendbeta≥ 0.8.0
chat-flowStateful numbered-menu botmessages:send, storage:usestable≥ 0.7.0
chatwoot-adapterTwo-way Chatwoot inbox sync + handovernet:fetch, conversation:send, webhook:ingress, engine:read, storage:usestable≥ 0.8.7
faq-botKeyword/regex auto-replymessages:sendstable≥ 0.7.0
group-translateIn-group auto-translationmessages:send, engine:read, net:fetch, storage:usestable≥ 0.8.0
gsheets-loggerLogs message events to a Google Sheetnet:fetch, storage:usestable≥ 0.7.0
http-actionRun REST API calls from chat commandsnet:fetch, conversation:send, storage:usestable≥ 0.8.0
rocketchat-adapterRocket.Chat Omnichannel relay for direct text chats (preview)net:fetch, conversation:send, webhook:ingress, storage:use, engine:readdevelopment≥ 0.30.0
supabase-otp-hookDeliver Supabase phone OTPs over WhatsAppwebhook:ingress, messages:sendbeta≥ 0.8.16
typebot-connectorRun a Typebot flow as the bot brainnet:fetch, conversation:send, storage:usestable≥ 0.8.2
voice-transcriptionVoice notes → text webhook eventnet:fetch, messages:send, storage:usebeta≥ 0.8.0

Requires is the minOpenWAVersion. All twelve are documented at the versions published in the marketplace catalog; column values come from each plugin's manifest.json.

Permissions glossary

messages:send lets the plugin send and reply to messages. conversation:send is the integration-SDK capability that relays messages back into a chat (used by the adapters/connectors that own their own send path). engine:read lets a plugin read engine state such as group info. net:fetch lets it make outbound HTTP calls through the host's SSRF-guarded fetch, restricted to the hosts in the manifest's net.allow list plus, for each config key named in net.allowConfigHosts, the https origin of the URL the operator configured under it (a value that is not an https URL, or that carries credentials, adds nothing, and since v0.24.0 the grant covers that scheme and port only). That second half is how a plugin with an empty net.allow still reaches the backend you point it at. webhook:ingress lets a plugin expose a verified inbound URL (signed by the caller — for example Chatwoot HMAC or Standard Webhooks) that the host authenticates before the plugin runs. storage:use lets a plugin read and write its own key-value store through ctx.storage; it is required from OpenWA v0.17.0, and before that release the store was reachable with no permission declared at all. A plugin that declares no permissions can only read hook events.

Upgrade these plugins before upgrading the gateway to v0.17.0

Seven of the eight plugins that declare storage:use above need at least the versions listed in their tables below — 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, voice-transcription 1.2.3 — installed before the gateway moves to v0.17.0. The Requires column does not encode this: none of the seven raised its minOpenWAVersion, because the new versions run unchanged on an older gateway, which ignores a permission string it does not recognise. It is the older plugin versions that break on v0.17.0, and they break quietly: the denial lands at the plugin's next storage call rather than at load, and a plugin that stores during onEnable ends up in ERROR instead of merely losing the write. after-hours, faq-bot, and supabase-otp-hook never touch ctx.storage and need no upgrade, and ai-responder declares no storage:use either. The eighth, rocketchat-adapter, requires OpenWA 0.30.0 or later, so it needs no upgrade for v0.17.0.

after-hours​

Replies with a configurable away message to messages received outside business hours.

FieldValue
Identifierafter-hours
Version0.2.16
Statusstable
Requires OpenWA≥ 0.7.0 (tested 0.31.0)
Typeextension
Permissionsmessages:send
Hooksmessage:received
RepositoryOpenWA-plugins/after-hours

What it does. Holds a per-weekday business-hours schedule interpreted in a configurable IANA timezone. When a message arrives outside the open window for that day, it sends the configured away message as a quoted reply, throttled to at most once per chat per cooldownSec. Since 0.2.8 a message is answered only when the shop was closed both when it was sent and now. That matters for the backlog a v0.23.6 or newer Baileys session delivers after an outage: a message written during opening hours is not answered just because the session came back after closing, and one written overnight but delivered after opening is not told the shop is closed. Since 0.2.10 the plugin claims an attempted reply before delivery completes, so a slow send cannot let another responder answer the same message; a failed send is logged and retains its claim, and the failure backoff controls later attempts. Since 0.2.16 a failed send that may nevertheless have gone out (an error saying the message may or may not have been sent, v0.31.0, or a capability timeout) also keeps the cooldown, so the away message is not repeated; any other failed send releases it. Since 0.2.12 a message delivered already deleted (type: 'revoked' placeholder on OpenWA v0.26.0+) is skipped instead of answered with the away message, and since 0.2.15 call and masked placeholders are skipped the same way, while a captionless photo or sticker is still answered. Group chats are ignored unless respondInGroups is set, and a WhatsApp Channel (@newsletter) or broadcast-list (@broadcast) chat is never replied to at all, since the account cannot hold a conversation there. A malformed schedule or unknown timezone fails the enable, so the plugin shows as ERROR in the dashboard rather than misbehaving silently. A config edit saved after enable cannot fail that way: the host forwards it fire-and-forget, so the plugin stays ENABLED, skips every message with a warning in its log, and only its health check turns unhealthy.

Configuration.

KeyRequiredDefaultDescription
scheduleyes—JSON object mapping mon..sun to "HH:MM-HH:MM" (24-hour) or null for closed. An absent day is closed, and at least one day must be open. A window belongs to the day it opens on, so "22:00-06:00" under mon stays open into Tuesday morning. "00:00-00:00" means open all day; any other window whose open equals its close is rejected.
timezonenoUTCIANA timezone the schedule is interpreted in, e.g. Asia/Jakarta.
awayMessageyes—Reply sent outside business hours.
cooldownSecno3600Minimum seconds between after-hours replies to the same chat. 0 replies every time. A reply that fails always installs a 60-second backoff on that chat whatever this value is, so a permanently blocked send cannot turn every inbound message into another attempt.
respondInGroupsnofalseWhether to reply in group chats.

Example schedule:

{ "mon": "09:00-17:00", "tue": "09:00-17:00", "wed": "09:00-17:00",
"thu": "09:00-17:00", "fri": "09:00-17:00", "sat": "09:00-13:00", "sun": null }

ai-responder​

Answers inbound WhatsApp messages with a reply from any OpenAI-compatible Chat Completions API, as the last responder in the chain.

FieldValue
Identifierai-responder
Version0.1.7
Statusbeta
Requires OpenWA≥ 0.8.0 (tested 0.31.0)
Typeextension
Permissionsnet:fetch, messages:send
Hooksmessage:received
RepositoryOpenWA-plugins/ai-responder

What it does. Sends the text of each inbound message, cut to maxInputChars, with the optional systemPrompt to an OpenAI-compatible Chat Completions endpoint (<apiBaseUrl>/chat/completions), converts the Markdown in the model's answer to WhatsApp formatting and sends it as a quoted reply (since 0.1.6, a model reply that becomes empty after Markdown conversion is logged as a failed attempt rather than sent blank). OpenAI is the default provider, and any provider that serves an OpenAI-compatible /chat/completions endpoint works through apiBaseUrl and model. It is single-turn: each message goes out on its own, so the model never sees earlier messages or its own earlier replies. It runs at hook priority 97, after every other responder in this catalog, so a command, a menu, a keyword rule or the away message always answers first and it only sees what none of them claimed. Every message it takes up is claimed ({ continue: false }) at once, before the provider answers, and the provider call runs in the background, so a slow provider never delays message delivery; if the provider fails or times out, the error is logged and the contact gets no reply, and no other plugin answers it either. A message it passes down the chain untouched, never claimed and never sent to the provider, is one that is not from the engine, was sent by this account or has no text; a shared contact card, poll, catalog order, product card, location or (since 0.1.6) forwarded message (isForwarded: true); a group message unless respondInGroups is on, and a group message with no identifiable sender; a WhatsApp Channel, broadcast-list or status update; one sent more than five minutes before it arrived, such as the backlog a v0.23.6 or newer Baileys session delivers after an outage; a message that arrives while the resolved config is invalid, which logs a warning; and one over the per-chat or per-session hourly limit or arriving while eight provider calls are already open. A Baileys whole-catalog share arrives as type unknown with the catalog title as its body and is answered. Both hourly limits count every message claimed in the hour, answered or failed, and are kept in memory, so a gateway restart or a re-enable starts a fresh hour.

Because it runs last, typebot-connector (priority 85), which claims every message in its scope, fully starves it on a session running both, so enable one or the other per session. after-hours claims only the first message in each chat per cooldownSec window, and faq-bot with a fallbackReply only the first unmatched message per fallbackCooldownSec window, so the contact gets that reply and then a model answer.

Every answered message goes to the provider

The text of every message the plugin answers, up to maxInputChars, goes to the configured provider (api.openai.com by default), and contacts are not told. Group messages are included only with respondInGroups. The system prompt is not confidential, since a contact can try to make the model reveal or ignore it, and nothing reviews a reply before it is sent from the account, so do not enable the plugin where a wrong answer in the account's name is unacceptable.

Configuration.

KeyRequiredDefaultDescription
apiBaseUrlyeshttps://api.openai.com/v1Base URL of an OpenAI-compatible API. Must be https, or http on localhost, 127.0.0.1 or [::1], with no embedded credentials, query string (?) or fragment (#); anything else fails enable. An https host is added to net.allow automatically; a local model also needs its address in SSRF_ALLOWED_HOSTS on the gateway.
apiKeyyesnoneBearer key for the provider, sent only to apiBaseUrl. Stored redacted. A local server that ignores the key still needs a non-empty value.
modelyesgpt-4o-miniModel id sent with every request. The request always carries max_tokens, which a model that accepts only max_completion_tokens rejects.
systemPromptnononeInstructions for tone and scope, sent with every message. Not confidential.
respondInGroupsnofalseAlso answer in group chats. Every message in every group then goes to the provider.
maxRepliesPerChatPerHourno20Messages answered per chat per clock hour.
maxRepliesPerSessionPerHourno200Messages answered per WhatsApp session per clock hour, across all chats.
maxInputCharsno2000The message text sent to the provider is cut to this many characters.
maxOutputTokensno500Sent as max_tokens, bounding the length and cost of each reply.
timeoutMsno15000Provider request timeout, clamped to 1000-25000 ms.

chat-flow​

An interactive, stateful auto-reply: a trigger word opens a greeting plus a numbered menu, and replies walk a configurable menu tree.

FieldValue
Identifierchat-flow
Version1.1.20
Statusstable
Requires OpenWA≥ 0.7.0 (tested 0.31.0)
Typeextension
Permissionsmessages:send, storage:use
Hooksmessage:received
RepositoryOpenWA-plugins/chat-flow

What it does. A trigger word (or any message that carries text, if trigger is empty) sends a greeting and a numbered menu. The user's reply selects an option; selections traverse a menu tree of arbitrary depth, where leaf nodes end the flow. State is kept per (session, chat), and in a group it is scoped to the sender as well, so members walk the menu independently without clobbering each other's position (since 1.1.15 a group message with no sender author is ignored so it cannot share a chat-wide slot, and since 1.1.16 per-conversation storage keys are bounded to 184 UTF-8 bytes so 128-character session IDs in group chats stay within OpenWA v0.28.0+'s storage key limit). It expires after 15 minutes of inactivity; re-sending the trigger restarts an active flow. A reply that matches no option re-sends the current menu, but only twice: the third consecutive miss drops the flow silently, so a contact who has stopped following the menu, or another bot on the far end, cannot hold it open forever. A WhatsApp Channel or broadcast-list chat is ignored outright, whatever trigger is set to. A message with no text (a sticker, a voice note, an image without a caption) never reaches the flow. A shared contact card, a poll, a catalog order, a shared product card, a location and (since 1.1.18) a forwarded message (isForwarded: true) never start or advance it either, whatever trigger is set to: contact cards and polls since 1.1.7, because host v0.23.2 fills their body, orders and product cards since 1.1.9, because from OpenWA 0.23.5 they arrive as order and product, on Baileys with the order note or product title as the body, and locations and forwarded messages since 1.1.18. A Baileys whole-catalog share arrives as type unknown with the catalog title as its body, so it still reaches the menu and, with an empty trigger, starts the flow. Since v0.23.6 a Baileys session gives a body to three kinds of message that used to arrive empty and be ignored: a tapped list row (its title), a business's list prompt (its description, else its title) and a native-flow button reply whose only text is the button label in its parameters (that label), provided those parameters also carry the button's id. With an empty trigger a list prompt a business sends the account therefore starts the flow, and inside an open flow each of them is read as an answer like typed text, so one that matches no option key re-sends the menu and counts as a miss. Since 1.1.10, messages WhatsApp held during a disconnect no longer walk the menu, draw "Invalid option" or spend a miss: a message written more than 5 minutes before the menu it would answer, and delivered more than 5 minutes late, is ignored, a reply to a menu shown before the outage still counts if it arrives within the 15-minute expiry, and a backlog under 5 minutes old is handled as live. Since 1.1.12 replies are queued in chat order without holding the message hook during delivery, and a failed send is logged and does not block later queued replies. Since 1.1.15 consumed message IDs are retained for 3 days across completed flows, trigger restarts, and expired menu states, so a redelivered message is ignored instead of restarting or advancing the menu a second time (and since 1.1.18 already-compacted expired states skip redundant storage writes, while healthCheck() reports invalid live config reloads). The plugin is session-scoped (sessionScoped) and ships a visual flow editor (configUi) the dashboard opens in a sandboxed frame, so the tree can be designed without hand-editing JSON (since 1.1.18 the editor validates the greeting, option text, duplicate keys, and reserved keys such as __proto__ before saving).

Configuration.

KeyRequiredDefaultDescription
greetingyes—The greeting plus menu sent when the flow starts.
optionsyes—The menu tree: an array of { key, text, options? } nodes that nest arbitrarily. At least one option is required; a config without one is rejected.
triggerno—Word that starts the flow (case-insensitive). Empty means any message that carries text starts it.
respondInGroupsnofalseWhether to run in group chats.

Example options tree:

{
"trigger": "menu",
"greeting": "Hi! Reply with a number:\n1. Pricing\n2. Support",
"options": [
{ "key": "1", "text": "Plans start at Rp100.000/mo." },
{ "key": "2", "text": "Support — reply with a number:\n1. Billing\n2. Technical",
"options": [
{ "key": "1", "text": "Billing: billing@example.com" },
{ "key": "2", "text": "A ticket has been created — we'll reply shortly." }
] }
]
}

chatwoot-adapter​

Two-way sync between a WhatsApp session and a Chatwoot inbox, with human handover — relay WhatsApp into Chatwoot, send agent replies back, and silence other OpenWA bots on that chat while a human agent is in control.

FieldValue
Identifierchatwoot-adapter
Version0.9.22
Statusstable
Requires OpenWA≥ 0.8.7 (tested 0.31.0)
Typeextension
Permissionsnet:fetch, conversation:send, webhook:ingress, engine:read, storage:use
Hooksmessage:received, message:sent
RepositoryOpenWA-plugins/chatwoot-adapter

What it does. Binds one Chatwoot account (apiToken + accountId + inboxId) to a WhatsApp session. Inbound WhatsApp messages (1:1 and groups, with media) are relayed into a Chatwoot API-channel inbox as incoming messages; agent replies (outgoing, non-private) are sent back to WhatsApp. Assigning a human agent in Chatwoot triggers handover — other OpenWA bots stop auto-replying on that chat until the assignee is cleared. Since 0.9.19 resolving a conversation no longer silences the chat, and since 0.9.20 no status change moves a chat between human and bot: only an assignee change does, so a resolved conversation with no assignee keeps its automation, and an agent who continues a resolved thread is not interrupted by a bot. A Chatwoot AI assistant in the assignee field (agent_bot, captain_assistant) does not count as a human agent (since 0.9.20). A chat that 0.9.18 or earlier left silenced by a resolve, in the closed state, is released on its next status change provided no human agent is assigned then, or by assigning and then unassigning an agent. Since 0.9.21 assignee changes are applied in the order Chatwoot committed them, so, when the event reports its commit time (the updated_at entry of changed_attributes), one committed before the last change applied to the conversation is ignored whatever order the webhooks arrive in, and a chat whose held conversation was deleted in Chatwoot returns to the bots when the next message creates its replacement (a hold recorded before 0.9.21 is released by assigning and then unassigning an agent on the new conversation). The host enforces that silence, not each plugin: while the chat is human or closed it stops passing the chat's inbound messages (message:received) to every plugin other than chatwoot-adapter, auto-repliers or not, so gsheets-logger writes no row for them and voice-transcription does not transcribe them. Other hook events still reach every plugin. Since v0.23.6 the host applies that silence to the chat rather than to one id of it: a takeover or closed state recorded while the contact was still known by its privacy id (@lid) keeps withholding the chat's inbound messages after the gateway learns the phone number, where an older gateway passed them to the other plugins again. A state left on a chat's @lid form before the upgrade therefore silences its phone form too, until an assignee change hands the chat back. The match runs through the gateway's lid mapping, which keeps every lid a number has been mapped to, so on a number WhatsApp recycled to a new owner the two owners' chats count as one: a takeover, a closed state or a hand-back on either applies to both. Since v0.26.0 the mapping joins chats only through a pair an engine has reported: a pair carried over from an older gateway, or restored from a backup that holds no report-origin data, joins nothing until an engine reports it again, so until then a takeover recorded under a lid does not reach the phone form of the chat, nor the reverse. Chatwoot contacts are keyed on the WhatsApp JID, so matching is stable across WhatsApp's @lid migration, and a group maps to one synthetic contact with sender-prefixed messages. Inbound and outbound are serialized by a per-chat lock, so a cold-start burst can't create duplicate contacts or conversations; both directions are idempotent.

On Baileys, v0.23.6 fills the body of three kinds of business interactive message that an older gateway delivered empty, and that the adapter therefore posted as a placeholder line naming the type. A tapped list row now arrives as the row's title and a business's list prompt as its description (else its title), where Chatwoot showed 💬 unknown. A native-flow button reply whose only text is the button label in its parameters arrives as that label, provided those parameters also carry the button's id, where Chatwoot showed 💬 text. In a group all three now carry the sender prefix. Since 0.9.9 a catalog order reaches Chatwoot as 🛒 Order <id> with the customer's note, and a shared product card as its title and product id with any accompanying text, instead of bare text; this needs OpenWA 0.23.5, and the order's token is never relayed.

Messages that arrived while the session was disconnected are relayed after it reconnects (from OpenWA 0.23.6 on the Baileys engine). Chatwoot shows each at the time it was relayed, not when it was sent, and in the order they reached the gateway, which during that catch-up can differ from the order they were written. An inbound message whose duplicate check the host refuses is queued for retry instead of lost (0.9.9), as can happen when a reconnect delivers a backlog across many chats and exceeds the host's 32 concurrent capability calls. Since 0.9.11 a webhook carrying a session scope resolves only the conversation mappings owned by that session, legacy mappings included, so an unknown scoped conversation cannot send a reply or change handover through another session's mapping. Since 0.9.14 mappings, delivery markers, queued retries, and history-import state are isolated by Chatwoot destination (baseUrl origin, accountId, and inboxId): pointing a session at a different origin, account, or inbox starts a fresh destination without writing into the previous inbox's conversation, while retries queued for another destination stay held until that destination is active again and its session dispatches a fresh event. History markers are also scoped to the destination conversation ID, so deleting and replacing a Chatwoot conversation imports history into the new conversation. Legacy mappings from before 0.9.14 are rebound through the configured account's contact lookup on the chat's next inbound WhatsApp message; an agent reply or handover event that arrives for an unmigrated legacy mapping before then throws so the host retries it instead of dropping it, and the webhook handler accepts both conversation_updated and conversation_status_changed (including root-shaped conversation payloads). Since 0.9.15 retry-queue and bulk-backfill storage keys are bounded to 184 UTF-8 bytes for long destination URLs, session IDs, and message IDs. Since 0.9.18 a message whose id the engine could not read (an empty id, which whatsapp-web.js reports when it cannot read one) is relayed without a de-duplication marker, so a re-delivery of it can show twice in Chatwoot.

A 1:1 contact carries the phone number derived from the chat id, sent only when it is valid E.164; a group, or a contact still known only by its @lid, has none. Since 0.9.8 a contact created without a number (because WhatsApp had not revealed it yet, or because an adapter older than 0.5.7 created it) gets one on that chat's next inbound message. The update is sent once per chat, and a number Chatwoot refuses is recorded rather than retried on every later message. After upgrading to 0.9.8, each existing chat sends that update once on its first inbound message, which replaces a phone_number edited by hand in Chatwoot.

An agent's Reply to in Chatwoot is relayed as a real WhatsApp quote where the engine allows it. A text reply is quoted; if the quoted message is no longer available (for example because it has fallen outside the engine's retained window) the engine refuses the quote and the reply is re-sent unquoted rather than failing. Since 0.9.21 only that refusal triggers the unquoted re-send: any other send failure, including the 409 that says a send may or may not have been sent (v0.31.0), fails the delivery so the host's retry decides, which can deliver a reply twice but never loses one silently. An unquoted plain-text reply follows the session's linkPreview config default when the session sets one (gateway v0.30.3 and later); the adapter leaves the preview flag unset, and a quoted reply or one with an attachment takes no preview option. A reply carrying an attachment is never quoted — the engine's media path cannot quote at all.

An agent's attachment is sent to WhatsApp by URL (its Chatwoot data_url), so the gateway downloads the file from that URL itself. Since v0.23.6 the download leaves through the session's egress proxy when the session has one; an older gateway fetched it from its own address. If the proxy cannot reach your Chatwoot host (a WhatsApp-only proxy, or a Chatwoot only the gateway's own network can reach), every agent reply carrying an attachment fails, caption included, while text-only replies still go through. Set SESSION_PROXY_URL_FETCH=false on the gateway (see Configuration) to fetch attachments directly again.

Agent replies and conversation-status changes arrive on an account-level Chatwoot webhook that OpenWA verifies (HMAC) before the adapter sees it — agent-bot / inbox webhooks are unsigned and are not supported.

Configuration.

KeyRequiredDefaultDescription
baseUrlyes—Public https origin of your Chatwoot, e.g. https://app.chatwoot.com. Its host is auto-allowed through the manifest's net.allowConfigHosts. Origin only — a value carrying a path, query string (?) or fragment (#) makes the plugin fail to enable, and one saved on a running plugin makes the message hooks and the agent-reply webhook fail and marks healthCheck() unhealthy until it is corrected.
apiTokenyes—A Chatwoot access token (Profile > Access Token, or an agent-bot token) with access to the API-channel inbox. Stored redacted. A per-session override or integration instance that points baseUrl at another origin does not inherit it (v0.26.0+); give that override its own token.
accountIdyes—Numeric Chatwoot account id.
inboxIdyes—Numeric id of the API-channel inbox.
relayGroupsnotrueRelay group chats as well as 1:1.
relayMedianotrueUpload media from WhatsApp as Chatwoot attachments.
relayOwnMessagesnotrueMirror messages the account itself sends, whether from the linked phone, the WhatsApp app, or the OpenWA API, so the thread is not one-sided. Chatwoot agent replies are never duplicated.
backfillLimitno0When a chat first opens in Chatwoot, import this many recent messages from it, both directions, so agents see prior context. 0 disables it; the range is 0 to 100. Attachments are imported only at 25 or below, since a larger import would exceed the host's 30-second budget, so older media arrives as a placeholder line. Works on whatsapp-web.js only: Baileys cannot fetch a chat's history, so nothing is imported there, and after three failed attempts on a chat the plugin's health message counts it among the chats that gave up on history import.
backfillAllOncenofalseIn addition to the per-conversation backfill, run a one-time sweep importing the history of every existing chat. Needs backfillLimit above 0 and the whatsapp-web.js engine to do anything, and runs once per session; a large inbox takes a while.
Mint the instance with the Chatwoot secret, not a generated one

The adapter verifies the webhook HMAC signature against the instance's ingress secret, so that secret must equal the secret Chatwoot shows on the webhook's edit form — and Chatwoot generates the secret itself, so it can only be copied into OpenWA. You need Chatwoot v4.12.0 or newer, the first release whose account-level webhooks carry a per-webhook secret and a timestamped signature (X-Chatwoot-Timestamp). Create the webhook at Integrations → Webhooks, subscribed to message_created, conversation_updated, and conversation_status_changed, then mint the instance with POST /api/integration/plugins/chatwoot-adapter/instances, passing the Chatwoot webhook secret as secret.

The dashboard can mint it too: the Plugins page's per-plugin Instances tab carries a Secret field, so paste Chatwoot's value there. What must not happen is leaving that field blank, on either path: the server then generates a random secret that can never match Chatwoot's, and every agent reply fails HMAC verification with a 401. The secret cannot be edited after minting; to change it, delete the instance and re-mint.

faq-bot​

Auto-replies to inbound messages from configurable keyword or regex rules.

FieldValue
Identifierfaq-bot
Version0.2.22
Statusstable
Requires OpenWA≥ 0.7.0 (tested 0.31.0)
Typeextension
Permissionsmessages:send
Hooksmessage:received
RepositoryOpenWA-plugins/faq-bot

What it does. Matches each inbound message against an ordered list of rules. Each rule is contains, exact (both case-insensitive), or regex (compiled with the i flag). The first matching rule wins, and its reply is sent as a quoted reply. Rules see only messages that carry text: a sticker, image or voice note arrives with an empty body and is passed over before matching, so it can never draw a fallback and a media-capable plugin behind faq-bot still sees it. Since 0.2.6 a shared contact card and a poll are dropped by type as well, because host v0.23.2 fills their body and a vCard is free text that readily matches a contains or regex rule; business button and list replies are real answers and are still matched. Since 0.2.11 a catalog order and a shared product card are refused the same way, and since 0.2.20 so are a location and a forwarded message (isForwarded: true), so the event passes down the chain instead of matching a rule or drawing the fallback: a v0.23.5 gateway types an inbound order and a shared product card as order and product on both engines, and on Baileys fills their body where it used to be empty (an order's from the customer's note, else the order title; a product card's from the text sent with the card, else the product title). A Baileys whole-catalog share arrives as type unknown with the catalog title as its body, so it can still match a rule or draw fallbackReply. A v0.23.6 gateway fills the body of list messages on Baileys: a tapped list row now carries the row's title as its body and a business's list prompt its description (else its title), where both arrived empty and were passed over. So does a native-flow button reply whose only text is the button label in its parameters, provided those parameters also carry the button's id: it now carries that label as its body. Without the id the reply still arrives empty and is passed over. A list reply or native-flow reply is therefore matched like any other answer, and so is a list prompt a business sends the account; any of them can draw fallbackReply. On Baileys the same release also types tapped buttons, tapped list rows and a business's list prompts as text rather than unknown, and since v0.23.7 whatsapp-web.js types a tapped button, a tapped list row and a template button reply text as well; that changes nothing here, since faq-bot filters on neither type. If nothing matches and fallbackReply is set, the fallback is sent, throttled per chat by fallbackCooldownSec. A matched rule carries its own throttle, fixed in code rather than configurable: since 0.2.6 the same inbound text in the same chat is answered at most once every 10 seconds, which stops the plugin trading one canned line at full message rate with an autoresponder on the other end. The window keys on the text rather than on the rule, comparing it trimmed, lowercased and truncated to 200 characters, so two different questions that match the same rule are both answered; a message silenced by that window is still claimed, so a plugin behind faq-bot does not answer it either. Group chats are ignored unless respondInGroups is set, and a WhatsApp Channel or broadcast-list chat is never answered at all. An invalid regex rule is skipped with a warning (since 0.2.17 the conservative heuristic screen also rejects ambiguous repeated alternations hidden by overlapping wrapper atoms such as ^((a|aa)a)+$, checks literal prefix overlap case-insensitively, and parses hex, unicode, control, and backreference escapes, and since 0.2.20 treats zero-width assertions, lookarounds, and nullable quantified groups as non-consuming; since 0.2.21 it also skips a rule whose bounded quantifiers multiply past a fixed state budget through nesting or a sequence, such as ((a?){9}){9}, and a repeated alternation whose branches overlap behind a skipped atom or a leading group, such as ^(a{0}b|b)+$, while still accepting a length-limited run pinned by a separator, such as \w{3,20}@; only administrators should configure regex rules); a structurally invalid rules value fails fast and shows as ERROR in the dashboard (or turns healthCheck() unhealthy when saved after enable, with compiled rules cached across messages since 0.2.20). Since 0.2.10 a regex rule sees only the first 150 characters of a message, which reduces backtracking work for a pattern the heuristic screen does not catch. A pattern that needs to match further in than that will not fire; contains and exact cannot backtrack and still see the whole message, so contains stays the right mode for "does this message mention X anywhere". Since 0.2.12 a message is answered only within five minutes of when it was sent: one that reaches the plugin later, as the backlog a v0.23.6 or newer Baileys session delivers after a long outage does, is left unanswered instead of drawing a burst of replies quoted to old messages. One that matches a rule is still claimed, so no other bot answers it, and one that matches nothing passes down the chain; the age is measured against the gateway's clock, so keep it in sync. Since 0.2.14 rule and fallback replies claim their message before delivery completes, so a slow send cannot activate another responder; a failed send is logged, releases its cooldown slot and retains the claim on that message. Since 0.2.21 a failed send also backs off for 60 seconds, per chat and inbound text for a rule reply and per chat for the fallback: during the backoff a message that matches a rule is still claimed but not answered, and one that would draw the fallback passes down the chain unanswered. Since 0.2.22 a failed fallback send that may nevertheless have gone out (an error saying the message may or may not have been sent, v0.31.0, or a capability timeout) keeps its cooldown slot, so the fallback is not sent twice within fallbackCooldownSec.

Configuration.

KeyRequiredDefaultDescription
rulesyes—JSON array of { mode, pattern, reply } rules, where mode is contains, exact, or regex.
fallbackReplyno""Reply sent when no rule matches. Empty stays silent.
fallbackCooldownSecno600Minimum seconds between fallback replies to the same chat. 0 replies every time.
respondInGroupsnofalseWhether to reply in group chats.

Example rules:

[
{ "mode": "contains", "pattern": "harga", "reply": "Harga mulai Rp100.000. Ketik 'menu' untuk detail." },
{ "mode": "exact", "pattern": "menu", "reply": "1) Harga 2) Jam buka 3) Lokasi" },
{ "mode": "regex", "pattern": "^/start", "reply": "Selamat datang! Ada yang bisa kami bantu?" }
]

group-translate​

Auto-translates group messages between participants' languages via a LibreTranslate backend, controlled in-chat with /tr commands.

FieldValue
Identifiergroup-translate
Version1.3.19
Statusstable
Requires OpenWA≥ 0.8.0 (tested 0.31.0)
Typeextension
Permissionsmessages:send, engine:read, net:fetch, storage:use
Hooksmessage:received
RepositoryOpenWA-plugins/group-translate

What it does. Learns each group member's language from what they type (or pins it with /tr setlang), then posts a combined reply translating each message into the other languages present. Everything is managed in-chat with /tr commands: only /tr help is open to anyone, and every other command, /tr status included, needs a group admin or a delegate they granted control to; grant and revoke themselves are admin-only. State-changing commands are admin-gated, resolved via ctx.engine.getGroupInfo (hence engine:read). Because WhatsApp delivers a group message's author under a privacy id (…@lid) while the participant list comes back under phone ids, an admin who fails the direct comparison is re-resolved to their phone identity through the host and compared again, so admin commands work across the @lid/phone split. Translation is disabled until an admin runs /tr on. Outbound translate calls go through the host's SSRF-guarded ctx.net.fetch. A per-call timeout plus a circuit breaker back off a slow or flaky backend instead of stalling the chat (since 1.3.17, host net.fetch concurrency rejections are excluded from the LibreTranslate circuit-breaker failure count). Since 1.3.18 a message's translation runs after the hook has returned, so a slow backend delays only the reply and not the plugins that run later in the chain, and a translation can arrive after the reply of one of them; at most four target languages are translated at a time for one message; and the group introduction is recorded as sent before it is posted and unrecorded if the post fails. A failed group admin lookup counts as an empty admin list (since 1.3.9): delegated controllers still work and denyReply decides whether the sender is told. A /tr command is claimed as soon as it is recognized, so no other plugin answers it even when the lookup is slow, since 1.3.14 per-group command ordering is kept across live configuration reloads and per-session config changes, and since 1.3.15 per-group storage keys are bounded to 184 UTF-8 bytes for long session and group identifiers.

Catalog orders and shared product cards are never translated (since 1.3.8): from OpenWA 0.23.5 they arrive as order and product, on Baileys with the order note or product title as the body, which was posted back into the group as a quote-reply and fed to language detection. A Baileys share of a whole catalog still arrives as unknown with the catalog title as its body and is translated like any other text. Since 1.3.9 a message that reaches the plugin more than 5 minutes after it was sent is not translated, and a /tr command that late is claimed but not run, since a replay can arrive out of order; send it again once the session is back. This is the backlog a v0.23.6 or newer Baileys session delivers after reconnecting, and the age is measured against the gateway's clock, so keep it in sync. Since 1.3.16 (on OpenWA 0.29.1+, where both engines set isForwarded), forwarded group messages are translated into the group's languages, including the forwarder's own, without teaching or switching the forwarder's learned language or running a /tr command. Since 1.3.19 a message whose id the engine could not read is translated and posted unquoted, where the reply failed and the translation was dropped.

Which backends are reachable without repackaging

Since v1.3.0 the manifest ships net.allow for localhost and 127.0.0.1 — loopback on any port — and declares libretranslateUrl in net.allowConfigHosts, which admits an operator-configured host over https only. So a loopback backend and a public https backend both work as shipped. The one shape still needing a manifest edit and a re-package is a plain-http backend on a non-loopback host (for example http://libretranslate:5000 inside a Docker network) — add its host:port to net.allow, or put it behind https.

The host-level loopback guard is separate and applies regardless: a localhost/127.0.0.1 (or other private) address still needs SSRF_ALLOWED_HOSTS set on the OpenWA host, because the SSRF guard blocks those by default. The default libretranslateUrl is a loopback address, so out of the box the plugin cannot reach its backend until that is set.

Configuration.

KeyRequiredDefaultDescription
libretranslateUrlyeshttp://localhost:7001Base URL of your LibreTranslate instance. Loopback on any port works as shipped; any other host is admitted over https only. A loopback or private address also needs SSRF_ALLOWED_HOSTS on the gateway.
libretranslateApiKeyno—Secret API key, if your instance requires one. Redacted on read.
timeoutMsno4000Per-request timeout for each detect or translate call. Translation runs outside the host hook budget (since 1.3.18), so this bounds how long a slow backend delays the reply.
commandPrefixno/trThe in-chat command prefix.
minLengthno2Minimum message length to translate.
maxLengthno2000Maximum message length to translate.
denyReplynofalseReply "admins only" when a non-admin runs a restricted command.
announceInGroupsnofalsePost the bot's introduction the first time it sees a message in a group. Off by default — one enable would otherwise announce the bot into every group the account belongs to. /tr help prints the same text on demand.

In-chat commands (default prefix /tr):

CommandWhoEffect
/tr helpanyoneShow the command list, at most once per minute per group.
/tr statusadmin or delegateShow whether translation is on and per-participant languages.
/tr on · /tr offadmin or delegateEnable or disable translation in this group.
/tr setlang <code> [@user]admin or delegatePin a participant's language.
/tr auto [@user]admin or delegateResume auto-learning a participant's language.
/tr ignore · /tr unignore [@user]admin or delegateSkip or resume translating a participant.
/tr grant · /tr revoke [@user]admin onlyDelegate or remove control to a non-admin participant.

A delegate is a non-admin the group's admins granted control with /tr grant. Only grant and revoke are restricted to real group admins; every other gated command accepts an admin or a delegate. A denied command answers nothing unless denyReply is on, so an unauthorized user cannot amplify replies into the group.

gsheets-logger​

Logs every WhatsApp message event to a Google Sheet via a service account — an append-only audit trail across all sessions.

FieldValue
Identifiergsheets-logger
Version0.3.20
Statusstable
Requires OpenWA≥ 0.7.0 (tested 0.31.0)
Typeextension
Permissionsnet:fetch, storage:use
Hooksmessage:received, message:sent, message:failed, message:ack
RepositoryOpenWA-plugins/gsheets-logger

What it does. Writes one row per message event — across message:received, message:sent, message:failed, and message:ack — to a Google Sheet, using a fixed 14-column schema. It authenticates as a Google service account (JWT RS256) with no runtime dependencies. Writes are buffered and flushed in batches, with retain-on-failure (rows are kept and retried on a Sheets error), a 5000-row cap, and persistence to plugin storage so the buffer survives a restart. A flush sends at most 500 rows or about 500,000 characters (since 0.3.19), so a backlog after an outage drains over several flushes. The buffer is stored after each flush that lands and when the plugin is disabled, so a hard kill (SIGKILL, out of memory) loses the rows buffered since the last successful flush: at most flushIntervalSec worth while flushes succeed, and every row held back while the Sheets API refuses appends. Since 0.3.13 persisted rows carry a destination fingerprint without credentials: rows for a previous spreadsheet or service account are parked under buffer:undelivered before the new destination starts, and if parking fails the plugin logs the error, retains the rows and keeps the previous client, so a later retry can deliver to the original destination. It declares two permissions, net:fetch and storage:use (the latter since 0.3.3, for the buffer that survives a restart), and its net.allow names just the two hosts it ever calls — oauth2.googleapis.com and sheets.googleapis.com. It never sends messages and never reads contacts. Inbound messages on a chat another plugin holds in a human or closed handover (a Chatwoot takeover, for example) never reach the plugin and are not logged; since v0.23.6 a handover recorded under a chat's @lid form covers its phone form too, and the reverse. Its message:sent, message:failed and message:ack rows are unaffected.

The 14 columns, one row per event:

timestamp | sessionId | event | direction | chatId | from | to | senderName | isGroup | type | body | messageId | ackStatus | error

timestamp is UTC. Since 0.3.11 message rows (message:received and message:sent) carry the message's own send time instead of the time the plugin handled it, so a message delivered after a reconnect is logged at the time it was sent; ack and failure rows keep the handling time, since they carry no time of their own. Rows are appended as events arrive, so the backlog a v0.23.6 or newer Baileys session delivers after reconnecting lands below newer rows with its original time: sort by timestamp for chronological order. On Baileys, v0.23.6 also changes two columns for business interactive messages. A tapped button, template quick-reply or list row, and a list prompt, are logged with type text where an older gateway logged unknown. A list row (its title), a list prompt (its description, else its title) and a native-flow button reply with no other text (the button label from its parameters, provided those parameters also carry the button's id) now fill body, where an older gateway left it empty. From OpenWA 0.23.5 orders and product cards log as order and product on both engines, where they logged as unknown before, and on Baileys body carries the order note (else its title) or the product card text (else the product title) instead of an empty string; a share of the whole catalog still logs as unknown, with the catalog title in body on Baileys. Since OpenWA v0.31.0 a whatsapp-web.js message that shares several contacts logs its vCards, newline-joined, in body, as Baileys already did, where body was empty.

On whatsapp-web.js, the error column of a message:failed row changes for a bulk item and for every single send except a forward, when the page's send call throws something other than a plain Error. For WhatsApp Web's own error classes a gateway before v0.23.6 logged only the minified class name, t, and v0.23.6 and v0.23.7 logged page threw followed by a JSON summary of what the page threw. Since v0.24.0 the row carries WhatsApp Web rejected the operation: followed by the thrown name and message, each cut at 200 characters, and the running WhatsApp Web build in parentheses when the page could read it; the full summary stays in the gateway log. A plain Error reaches the row as before, and so does any error from a forward. Since OpenWA v0.27.0 a failed bulk voice-note item (ptt: true) arrives on message:failed with type voice, matching single voice-note sends (earlier gateways sent audio), and since OpenWA v0.28.0 whatsapp-web.js system notices (E2E_NOTIFICATION, NOTIFICATION_TEMPLATE, NOTIFICATION, BROADCAST_NOTIFICATION, GROUP_NOTIFICATION, PROTOCOL, DEBUG) are dropped before message:received, message:sent, and message:ack instead of logging as unknown rows.

Setup requires two separate authorizations

Enabling the Google Sheets API on the project and sharing the spreadsheet with the service account (as Editor) are independent steps. Skipping either fails with a different 403 in the logs. See the plugin's README for the full setup walkthrough.

Configuration.

KeyRequiredDefaultDescription
serviceAccountJsonyes—Full service-account key JSON. Stored as a secret. Share the sheet with this account's client_email as Editor.
spreadsheetIdyes—The ID from the sheet URL, between /d/ and /edit. Surrounding whitespace is trimmed, and an ID with anything but letters, digits, hyphens and underscores is rejected (since 0.3.19).
sheetTabnoLogsTarget tab name. The tab must already exist, with a header row of your choosing — the plugin appends data rows only. A blank value falls back to Logs (since 0.3.19).
flushIntervalSecno5Seconds between flushes.
flushBatchSizeno20Flush early once this many rows are buffered. Suppressed while a flush is failing, so during a Sheets outage the buffer keeps growing and retries stay on flushIntervalSec instead of hammering the API on every event.
message:ack rows

The message:ack rows fill the messageId and ackStatus columns and require OpenWA ≥ 0.6.1; older builds never emitted the hook. Since OpenWA v0.27.0 the hook fires only for messages the account sent (with foreign-chat receipts ignored on Baileys), so reading an inbound message on the phone no longer writes an ack row, and since OpenWA v0.28.0 Baileys also emits delivered and read for outbound group messages once every group member has received or read the message (status broadcast posts remain at sent).

http-action​

Trigger safe REST API requests from WhatsApp commands and map JSON responses back to chat — connect WhatsApp to an existing HTTPS API without webhook middleware.

FieldValue
Identifierhttp-action
Version0.2.20
Statusstable
Requires OpenWA≥ 0.8.0 (tested 0.31.0)
Typeextension
Permissionsnet:fetch, conversation:send, storage:use
Hooksmessage:received
RepositoryOpenWA-plugins/http-action

What it does. Each inbound message is matched against an ordered list of actions; the first matching action wins, and its trailing arguments are parsed (a double-quoted run is kept as one argument). Polls and shared contact cards never match: since host v0.23.2 a poll arrives with its question as the body and a contact card with its full vCard (several joined by newlines when the card carries more than one: on Baileys since v0.23.2, on whatsapp-web.js since v0.31.0), so a poll titled with a configured prefix would otherwise fire a request and claim the message. Since 0.2.9 a placed catalog order and a shared product card never trigger an action either, and since 0.2.18 neither do a location or a forwarded message (isForwarded: true): a v0.23.5 gateway types a placed order as order and a shared product card as product, and on Baileys fills the body those two used to arrive without (an order's from the customer's note, else the order title; a product card's from the text sent with the card, else the product title). A Baileys whole-catalog share arrives as an unknown message with the catalog title as its body, so a catalog titled with a configured prefix can still trigger an action. A v0.23.6 gateway fills the body of list messages on Baileys, which used to arrive with an empty body: a tapped list row now carries the row's title and a business's list prompt its description (else its title), so either can fire an action, and so can a native-flow button reply whose only text is the button label in its parameters, which now arrives with that label as its body when those parameters also carry the button's id. Pick prefixes a list prompt or a whole-catalog title will not collide with. A matched action issues a fixed-origin GET or JSON POST to a single HTTPS baseUrl — the path is server-relative and every interpolated segment is URL-encoded, so a message can never change the host or inject a path segment. The JSON response is rendered into a reply via {{response.field}} templates, with separate notFoundTemplate and errorTemplate. Direct chats are the default; group chats are ignored unless respondInGroups is set, and a WhatsApp Channel or broadcast-list chat is never acted on. One request runs per message, idempotent across WhatsApp redelivery (storage-backed dedup, with concurrent redeliveries of the same message ID serialized since 0.2.15), with a per-chat cooldown and an off-dispatch handler so a slow upstream never stalls the inbound hook (since 0.2.18, messages that match no action skip background dispatch altogether). Since 0.2.15, before dispatching a POST the plugin records a 3-day intent marker keyed to the backend origin, auth settings, action, and chat, and stores the rendered reply once the POST completes: if the WhatsApp reply fails to send and the message is redelivered, a stored reply for the same backend, action, and chat is sent directly without repeating the POST or waiting for the chat cooldown, whereas if the earlier POST threw or timed out so its outcome is unknown (or the action or backend config changed meanwhile) the plugin replies that the result could not be confirmed (The result of this command could not be confirmed. Please contact the operator before trying again.) instead of repeating the write. Since 0.2.19 the request template is rendered and validated before that marker is written, so a POST whose template cannot be rendered answers with errorTemplate and records no POST intent, where it was reported as an unconfirmed write; and a POST that gets a 2xx response whose body is not valid JSON or is larger than 256 KiB, or whose replyTemplate cannot be rendered, is recorded as completed with the could-not-be-confirmed reply as its stored reply, so a redelivery sends that notice without repeating the write. Since 0.2.10 a POST action is not run when its command reaches the plugin more than five minutes after WhatsApp accepted it, as the backlog a v0.23.6 or newer Baileys session delivers after reconnecting does: the contact gets a quoted reply saying the command arrived late and was not run and asking them to send it again, and that reply is not held back by cooldownSeconds. GET actions still run, since a late lookup returns current data. The age is measured on the gateway's clock, so keep it synchronized: a clock more than five minutes fast refuses every POST.

Configuration.

KeyRequiredDefaultDescription
baseUrlyes—Single HTTPS origin every request targets. Auto-added to net.allow via allowConfigHosts.
actionsyes—JSON array of one to 25 action objects (shape below). Values inside an action's request.headers are stored and returned unmasked by GET /api/plugins and GET /api/plugins/{id}, so put credentials in authToken; the plugin logs a warning at enable naming the actions that set headers.
authTypenononenone, bearer, or apikey.
authTokencond.—Bearer token or API key, per authType. Stored redacted.
apiKeyHeadercond.X-API-KeyHeader name when authType is apikey.
respondInGroupsnofalseRun in group chats.
timeoutMsno3000Per-request timeout. Min 500.
cooldownSecondsno3Minimum seconds between replies in a chat, shared by every action rather than per action: the key is the session and chat alone. 0 disables it.

Each action is { id, match: { type, value, caseSensitive? }, request: { method, path, query?, headers?, bodyTemplate? }, replyTemplate, notFoundTemplate?, errorTemplate? }. match.type is exact or prefix. Template variables: args.0, args.1, … plus message.id, message.body, chat.id, sender.id, sender.phone, sender.name, session.id, and response.<path> (the parsed JSON body).

rocketchat-adapter​

Development preview of a text-only bridge between direct WhatsApp conversations and Rocket.Chat Omnichannel: WhatsApp text opens a visitor room, and an agent's plain-text reply goes back to WhatsApp.

FieldValue
Identifierrocketchat-adapter
Version0.1.1
Statusdevelopment
Requires OpenWA≥ 0.30.0 (tested 0.31.0)
Typeextension
Permissionsnet:fetch, conversation:send, webhook:ingress, storage:use, engine:read
Hooksmessage:received
RepositoryOpenWA-plugins/rocketchat-adapter

What it does. Relays each direct WhatsApp text message into a Rocket.Chat Omnichannel room and sends an agent's plain-text reply back to that WhatsApp chat. Every WhatsApp chat gets its own visitor and room, registered through Rocket.Chat's visitor REST API under a random per-chat visitor token, so the plugin needs no Rocket.Chat administrator token; an administrator is still needed to enable Omnichannel, make an agent available and set up the webhook. A visitor carries the chat's phone number when it is a telephone id; for a privacy id (@lid) the plugin asks engine:read for the host's mapping, then for the contact's own phone id, within 1.5 seconds, and registers the visitor without a number when neither answers. Agent replies arrive on the instance's omnichannel ingress route, which declares the shared-secret scheme on the X-RocketChat-Livechat-Token header: before the plugin runs, the host compares that header with the instance secret (the Secret Token of Rocket.Chat's Omnichannel webhook, not an HMAC), refuses a mismatch with 401, acknowledges an accepted delivery with a plain 200 ok, and answers 503 from its session-alive preflight while the bound session has no live engine.

Only direct text moves. From WhatsApp the plugin relays a text message of 1 to 4096 characters that a contact sent in a one-to-one chat; groups, channels, broadcast lists, status posts, every other message type and the account's own sent messages are ignored. From Rocket.Chat it relays an agent's plain-text message of up to 4096 characters, not a visitor echo, internal note, system message, edit or attachment, and a reply for a room or visitor token it has no mapping for is acknowledged and ignored. The plugin is an observer: it runs at hook priority 20, never claims a message, and does not silence other bots when an agent takes a room, so keep other responders off the session. It has no backlog rule, so a message that a v0.23.6 or newer Baileys session delivers after an outage is relayed like a live one. Since 0.1.1 a message whose id the engine could not read is relayed under a stable id derived from its chat, send time and text, so a re-delivery of it is still de-duplicated.

Inbound messages are queued in plugin storage and delivered to Rocket.Chat off the hook path by up to four workers, in order within each chat; a failing message gets five attempts, with increasing delays between them, before it becomes a dead letter. The queue holds 100 pending messages, and a full queue does not accept the next one; dead letters are kept separately, up to 100 for seven days. The plugin keeps at most 500 chat mappings per destination and session: when a new contact arrives, the least recently used mapping with no pending work is dropped, and a later reply from its old room is ignored. Queues survive a restart but resume draining only once the bound session dispatches a hook or webhook. Delivery is at least once: a crash, a storage failure or a send that the gateway reports as possibly delivered (an error saying the message may or may not have been sent, v0.31.0) can produce a duplicate on the retry, and the last 500 reply ids are remembered to suppress repeats. With the host queue off (QUEUE_ENABLED unset, the default) an agent webhook runs inline within 5 seconds, and the typing pause before a WhatsApp send (SIMULATE_TYPING) can use most of that for a reply of about 100 characters or more. If the handler overruns the budget, the host files a dead letter and its reconciler replays the delivery; the per-room lock and the remembered reply ids keep the replay from sending the reply twice. QUEUE_ENABLED=true gives the handler the longer queued budget. The reference environment is Rocket.Chat 8.0.1; confirm that your edition offers Omnichannel before deploying.

Mint a session-bound instance with your own secret

Mint the instance with POST /api/integration/plugins/rocketchat-adapter/instances, setting sessionScope and config.sessionId to the WhatsApp session UUID and secret to a random value of 16 to 512 characters that you also paste into the Secret Token of Rocket.Chat's Omnichannel webhook. Point that webhook at /api/ingress/rocketchat-adapter/{instanceId}/omnichannel and subscribe it to Agent Messages. Use one instance per session and destination, set the same department on the instance and on the plugin config if you use one, and enable the plugin only for that session: a config that resolves to another origin, department or session is kept apart on purpose.

Configuration.

KeyRequiredDefaultDescription
baseUrlyesnoneRocket.Chat https origin only. A path, query string, fragment, credentials or a wildcard host fails the config, and plain http is refused even in a lab. Its host is added to net.allow automatically; an internal hostname also needs SSRF_ALLOWED_HOSTS on the gateway.
sessionIdyesnoneExact OpenWA session UUID, at most 100 characters. A message from any other session is ignored, and the ingress instance's session scope must name the same session.
departmentnononeOmnichannel department name or ID, at most 200 characters, passed when visitors are registered. Changing it starts a separate mapping namespace.
deadLetterActionnononereplay returns the retained dead letters to the pending queue, up to its capacity; clear discards them without deleting visitor mappings or pending work. Needs a fresh deadLetterActionId.
deadLetterActionIdcond.noneId of the operation, 1 to 100 letters, digits, hyphens or underscores. Required with replay or clear; reusing one of the last 100 ids does not repeat the operation.

supabase-otp-hook​

Deliver Supabase Auth phone OTPs over WhatsApp. Supabase's Send SMS hook (Standard Webhooks-signed) is verified host-side, and the plugin sends the OTP via an OpenWA WhatsApp session — with synchronous feedback to Supabase.

FieldValue
Identifiersupabase-otp-hook
Version0.3.17
Statusbeta
Requires OpenWA≥ 0.8.16 (tested 0.31.0)
Typeextension
Permissionswebhook:ingress, messages:send
Hooks— (ingress-driven)
RepositoryOpenWA-plugins/supabase-otp-hook

What it does. Supabase calls the plugin's OpenWA ingress URL. The host verifies the Standard Webhooks signature against the instance secret (webhook-id / webhook-timestamp / webhook-signature, base64 HMAC-SHA256, constant-time, 5-minute replay window) — a bad signature returns 401 before the plugin runs. The host then runs a session-alive preflight that returns 503 on a dead WhatsApp session, and fast-acks Supabase with a bodiless 204 on accept (0.3.7; the ack used to carry a JSON body declared as application/json, which gateways v0.20.0 through v0.23.5 sent as text/plain whatever the route declared, so Supabase rejected it as invalid JSON, discarding a code the plugin had already sent; a v0.23.6 or newer gateway honors a declared application/json again, but the ack stays a bodiless 204). The plugin parses { user: { phone }, sms: { otp } }, normalizes the phone to <digits>@c.us, and fires the WhatsApp send against a 1.5-second fail-fast window: a send that fails inside it throws. With the queue enabled (QUEUE_ENABLED=true) and Redis reachable, the host then retries the delivery (three attempts by default, INGRESS_MAX_ATTEMPTS, with exponential backoff from INGRESS_RETRY_DELAY_MS, 5 seconds by default) and dead-letters it for redrive once they are spent; with the queue off, the default, or Redis unreachable, the host dispatches once inline and writes the dead-letter row straight away. With the queue off its ingress reconciler then replays the delivery on later sweeps (every minute by default) until a replay succeeds or its attempts run out (five by default), so a code that failed its first attempt can arrive late; with the queue enabled and Redis unreachable it leaves the delivery alone until Redis answers. A whatsapp-web.js session whose WhatsApp Web page is reloading refuses a send with a retryable 409 (carrying code ENGINE_PAGE_RELOADING since v0.31.0) that can last a few minutes. With the queue enabled, a reload that outlasts the host's three default attempts dead-letters the delivery for redrive, so raise INGRESS_MAX_ATTEMPTS and INGRESS_RETRY_DELAY_MS for OTP traffic on such a session. A send that is merely slow is left to finish in the background rather than burning the worker's 5-second dispatch budget and retrying into a duplicate OTP. A send that fails after that window has closed reaches nobody, since Supabase was already acked: the plugin logs a warning and its health check (GET /api/plugins/supabase-otp-hook/health) reports last OTP send failed, and neither triggers a provider retry. With the queue enabled and Redis reachable, deliveries for one user.id are serialized, but a retried delivery can overtake a later one; with the queue off the host takes no ordering lock. Since 0.3.8 the route declares dedupOn: "body", so a v0.23.6 or newer gateway dedupes on a hash of the signed body: the attempts of one Supabase hook invocation carry the same bytes and collapse into a single send, each answered with the same bodiless 204, while a new sign-in carries a freshly generated OTP and is never collapsed into an earlier one. An older gateway ignores the key and dedupes on webhook-id, which catches a replay of one delivery rather than a provider retry: Supabase mints a fresh webhook-id per attempt, so there a retried hook is a new delivery and sends a second code. Since v0.3.0 the plugin no longer declares engine:read: the canonicalChatId round-trip it was used for could only ever return the same <digits>@c.us string, so it was dropped along with its 2-second race on the OTP critical path.

This is the canonical example of a plugin that owns an inbound URL rather than a chat hook: the webhook:ingress capability exposes the verified endpoint, and verification happens in the host (not the plugin) so a signature failure never reaches plugin code.

Configuration.

KeyRequiredDefaultDescription
appNameyes—Application name interpolated into the OTP message via {appName}.
messageTemplateno{appName} | Your verification code is {otp}Message body. Supports {appName} and {otp} placeholders; since 0.3.16 {otp} is required in the template.
fallbackSessionIdno—Session to send through if the request doesn't name one (trimmed since 0.3.16, with blank or * treated as unset).
debugnofalseVerbose logging.
Standard Webhooks secret

The instance secret you set in OpenWA is the same secret Supabase generates when you register the webhook URL — the host uses it to verify every delivery. OpenWA v0.8.16+ is required for the standard-webhooks signature scheme and the ingress preflight/response contract. Since 0.3.7 the ack is a bodiless 204, which needs Supabase Auth v2.172.0 or newer; every Supabase Cloud project is well past it, a self-hosted Auth below it has to be upgraded.

The dead-session 503 only holds when the instance is bound to a session

The host's preflight probes the instance's sessionScope. Bind the instance to a logged-in session and a dead session is reported to Supabase as 503 with a Retry-After header (v0.23.6+; since v0.26.0 the send-sms ingress route also answers 503 with Retry-After: 5 while the gateway is restoring plugins after startup, capped at 60 s), so the provider retries. Supabase Auth retries a 503 only when that header is present; an older gateway sends the 503 without one, so there Supabase fails the call instead of retrying it. Leave sessionScope blank, or set it to the wildcard *, and rely on the fallbackSessionId plugin config instead, and the preflight is skipped. A delivery whose fallback session is down then depends on timing: a send that fails inside the 1.5-second fail-fast window still throws, so with the queue enabled the host retries it and then dead-letters it for redrive, and without it dead-letters it at once, but one that fails after the window is acked 204 and lost, with no provider retry; only the plugin's warning log and its health check report it. Bind the instance wherever the sending session is known.

typebot-connector​

Run a Typebot flow as the brain of a WhatsApp bot — inbound messages drive a Typebot chat session, and the bot's text, media, and numbered-choice replies come back to WhatsApp.

FieldValue
Identifiertypebot-connector
Version0.3.11
Statusstable
Requires OpenWA≥ 0.8.2 (tested 0.31.0)
Typeextension
Permissionsnet:fetch, conversation:send, storage:use
Hooksmessage:received
RepositoryOpenWA-plugins/typebot-connector

What it does. On each inbound message in scope, the plugin resumes (or starts) the contact's Typebot session over the live Chat API and renders the bot's reply bubbles back into WhatsApp. Text bubbles are converted to WhatsApp formatting; image, video, and audio bubbles are sent as media; a choice step is shown as a numbered list and the contact's numeric reply is mapped back to the option. Typed inputs (email, number, date, …) are re-asked on a bad value, and a file-input step accepts a photo or file the contact sends. Typebot takes only the file there, so typed text is answered with a request for one, and an optional file step is skipped when the contact replies with the step's Skip label. Since 0.3.6 a text-input step also distinguishes file attachments (attachments.isEnabled) from audio clips (audioClip.isEnabled): when audio clips are enabled on a text step, an inbound voice note or audio file is uploaded and sent to Typebot as { type: 'audio', url }, when file attachments are enabled any accompanying caption is sent alongside attachedFileUrls, and an empty message at a text step is answered with Please type your answer to continue. instead of advancing the flow with an empty string (and since 0.3.9 empty answers at choice and rating steps are rejected the same way). The session resets when the flow ends or after the idle timeout, so the next message starts fresh. Since 0.3.10 it also resets when the flow reaches an input step the connector cannot show (the contact is told This step (<type>) can't be shown on WhatsApp.) and when apiHost or publicId changes, for a session stored since 0.3.10. It runs sandboxed in the plugin worker and polls Typebot's Chat API over the host's SSRF-guarded ctx.net.fetch — no public URL or webhook is required. Typebot holds the session state; the plugin persists only the session id and the bot's expected next input (with per-session storage keys bounded to 184 UTF-8 bytes for 128-character session IDs in group chats since 0.3.7). Media bubbles are sent by URL, and since v0.23.6 a session with an egress proxy downloads them through that proxy, where an older gateway fetched them from its own address. If the proxy cannot reach the host serving your Typebot media, those bubbles fail and are skipped while the rest of the turn still arrives; set SESSION_PROXY_URL_FETCH=false on the gateway to fetch them directly again. A text part sent in a 1:1 chat is unquoted, so from gateway v0.30.3 it follows the session's linkPreview config default when the session sets one, and can differ between sessions; the connector leaves the preview flag unset, and a text part quoted in a group, or a media part, takes no preview option.

The connector claims every message in a chat it is in scope for (hook priority 85), so a Typebot outage produces silence rather than another plugin answering on this bot's behalf, and handlers that run after it (a higher priority number than 85) never see those chats; do not run another auto-reply, menu or FAQ plugin on the same session. A shared contact card, a poll, a catalog order, a product card, and (since 0.3.9) a location do not answer the current step and are never uploaded as media attachments: the contact is asked to type instead and the flow stays put (orders and product cards since 0.2.9, because from OpenWA 0.23.5 their note or title fills the body on Baileys and could pick a numbered choice), and since 0.3.6 a message delivered already deleted (type: 'revoked' placeholder on OpenWA v0.26.0+, plus call and masked placeholders since 0.3.9) is ignored without starting or advancing a flow. A whole-catalog share still arrives as type unknown with the catalog title as its body, and the connector takes it as the answer. Since 0.3.0 messages WhatsApp delivers late after a reconnect no longer answer a step the contact had not seen yet: a message written more than 5 minutes before the current step was sent, and delivered more than 5 minutes late, is ignored, a reply to a step shown before the outage still answers it, and the idle reset counts from when it was written.

Configuration.

KeyRequiredDefaultDescription
apiHostyeshttps://typebot.ioPublic https URL of your Typebot: https://typebot.io for Cloud, or a self-hosted install on a public domain. Credentials, query strings (?), or fragments (#) in the URL are rejected and plain http fails enable (or turns healthCheck() unhealthy on a live reload since 0.3.9). Private and LAN addresses are blocked by the gateway SSRF guard unless the operator lists the exact host name in SSRF_ALLOWED_HOSTS; the plugin itself documents them as unsupported. Its host is auto-added to net.allow.
publicIdyes—Typebot public ID from the bot's Share settings.
apiTokenno—API token, only for a restricted/preview bot. Stored redacted.
respondInGroupsnotrueRun in group chats.
sessionTimeoutMinutesno30Idle minutes before the session resets.
passContactVariablesnotruePass waNumber, waName, waChatId as Typebot flow variables.
mediaHostno—Only for an older self-hosted Typebot that uploads files to a separate S3/MinIO host: the plugin sends the uploaded file there (must be https with no embedded credentials, query string, or fragment since 0.3.9). Leave it empty for Typebot main, which proxies uploads on its own origin. Auto-added to net.allow.

voice-transcription​

Transcribes inbound voice notes to text via an OpenAI-compatible speech-to-text backend and delivers a message.transcription event to your webhook.

FieldValue
Identifiervoice-transcription
Version1.3.9
Statusbeta
Requires OpenWA≥ 0.8.0 (tested 0.31.0)
Typeextension
Permissionsnet:fetch, messages:send, storage:use
Hooksmessage:received
RepositoryOpenWA-plugins/voice-transcription

What it does. On each inbound voice note (skipping self-sent fromMe, isStatusBroadcast, @newsletter, and @broadcast messages since 1.3.7), runs speech-to-text against any OpenAI-compatible /v1/audio/transcriptions endpoint (self-hosted Speaches/faster-whisper, or hosted Groq/OpenAI) and POSTs a message.transcription event to your delivery webhook — so a bot or AI can read and reply to audio. Transcription runs off the message-delivery path as an un-awaited task: it never touches the message.received payload, never blocks delivery, and is not bound by the 5-second hook budget. For each voice note it processes it delivers completed (with the transcript), failed, or skipped status, so a consumer knows the note arrived even when it can't be read. Since 1.3.8 a failed event is also sent when the plugin cannot record the note's de-duplication or hourly-cap entry in its storage (the speech-to-text call is then not made), and URL credentials, query strings and fragments are redacted from the reason text and from the logs. A note that arrives without a message id is not de-duplicated, and with chatDelivery reply its transcript is posted as a plain message rather than a quote-reply; self posts nothing when the note's recipient is empty or a group, channel or broadcast list. The plugin is in beta and disabled until enabled.

Treat the transcript as untrusted

transcription.text is attacker-controlled speech; the event marks it untrusted: true. A downstream LLM responder must place it in a user role, never a system or trusted context — a caller can speak injection instructions a typist never would.

Delivered event (POSTed to deliveryWebhookUrl):

{
"event": "message.transcription",
"sessionId": "…",
"messageId": "<waMessageId>",
"chatId": "…@c.us",
"status": "completed",
"source": "speech-to-text",
"untrusted": true,
"timestamp": 1758000000,
"transcription": { "text": "…", "language": "es", "provider": "faster-whisper", "model": "small" }
}

Correlate it to the original voice note by messageId. It arrives shortly after message.received, out of order — do not assume ordering. Since 1.3.0 the event carries timestamp, the voice note's original send time in Unix seconds, so a receiver can tell a note delivered after a reconnect from a live one; the field is left out when the inbound message carried none. A skipped event carries a reason (too_large, rate_limited, empty or media_unavailable) and a failed event carries the speech-to-text error text as its reason, in place of transcription. When deliverySecret is set, the body is HMAC-SHA256 signed in X-OpenWA-Signature: sha256=<hex>, the same scheme as core webhooks.

Configuration.

KeyRequiredDefaultDescription
sttBaseUrlyes—OpenAI-compatible STT base URL (/v1/audio/transcriptions is appended; must not carry credentials, a query string ?, or a fragment # since 1.3.7). An https host is admitted automatically; a localhost target also needs SSRF_ALLOWED_HOSTS on the host.
sttApiKeyno—Bearer key for a hosted backend (Groq/OpenAI). Blank for a local Speaches instance. Stored redacted.
modelnosmallWhisper model name, e.g. small, base, whisper-large-v3-turbo.
languageno(auto)Optional BCP-47 hint. Blank auto-detects.
providernofaster-whisperInformational label recorded in the delivered event.
timeoutMsno20000Per-request STT timeout. Min 1000, max 25000, and clamped in code as well as in the form: 30000 is the host's own per-capability budget (PLUGIN_CAP_TIMEOUT_MS), so a value that high expired with it and reported an STT timeout as a capability timeout.
enabledMessageTypesno["voice"]Message types to transcribe. Add audio to also transcribe non-PTT audio (more cost).
maxSizeBytesno16777216Skip audio larger than this.
maxPerHourno60Best-effort per-session hourly transcription cap.
deliveryWebhookUrlcond.—Endpoint receiving the event. An https host is admitted automatically. Optional if you only use chatDelivery.
deliverySecretno—HMAC-SHA256 signs the body in X-OpenWA-Signature. Stored redacted.
deliveryTimeoutMsno5000Delivery POST timeout. Min 1000, max 25000.
chatDeliverynooffAlso post the transcript into WhatsApp: off (webhook only), self (a note to your own number), or reply (a quote-reply in the chat the note came from; in a group chat every member sees it). Since 1.3.0, with reply, a voice note that reaches the plugin more than 5 minutes after it was sent is no longer quote-replied, and is not transcribed when that reply was its only destination.

This plugin ships net.allow for localhost, 127.0.0.1, api.groq.com:443, and api.openai.com:443, and since v1.1.0 also declares sttBaseUrl and deliveryWebhookUrl in net.allowConfigHosts — so any https STT or delivery URL you configure is admitted automatically, with no manifest edit and no re-package. The static entries are what still covers a plain-http local backend. For a deeper how-to, see Voice Transcription.

Per-session config support​

A sessionScoped plugin (the default) can carry per-session config overrides — two WhatsApp sessions under one plugin instance can run different settings. A plugin honors an override only if it re-reads ctx.config inside its hook rather than using a snapshot cached at enable. The status per plugin:

PluginPer-session configNotes
after-hoursSupportedAll fields per session; takes effect on next message.
ai-responderSupportedAll fields per session (different providers, models and system prompts); the hourly limits are counted per session and per chat.
chat-flowSupportedAll fields per session; flow state is per (session, chat), and per sender as well inside a group.
chatwoot-adapterSupported, with caveatAll fields per session — first-class multi-tenant shape, with mappings, delivery markers, history imports, and queued retries isolated per Chatwoot destination (baseUrl origin, accountId, inboxId) since 0.9.14. A message queued for retry is re-posted only once its destination is active and the plugin has seen an event for its session since it was last enabled; until then it stays queued and counted under pending retries in the plugin's health.
faq-botSupportedAll fields per session (different rule sets per number).
group-translateSupported, with caveatConfig-signature caching; two sessions pointing at different LibreTranslate backends share one coordinator slot and clobber each other's circuit-breaker state on alternation (keep one backend for all sessions, or run one OpenWA gateway per backend; this plugin has no per-session instance).
gsheets-loggerNot supportedSingle-buffer single-sink design; to log different sessions to different sheets, run one OpenWA gateway per sheet (this plugin has no per-session instance).
http-actionSupportedAll fields per session (different endpoints/action sets).
rocketchat-adapterSupported, with caveatConfig is re-read for each hook and webhook but bound to its sessionId: other sessions are ignored, so each session needs its own matching override and its own session-bound ingress instance. A change of origin, department or session selects a separate mapping namespace and does not migrate visitors, rooms or pending messages.
supabase-otp-hookSupportedAll fields per session; applies to the instance's bound session.
typebot-connectorSupportedAll fields per session; flow state is per (session, chat), and per sender as well inside a group, so participants do not interleave into one Typebot session.
voice-transcriptionSupported, with caveatConfig-signature caching; two sessions pointing at different STT backends share one coordinator slot and clobber each other's circuit-breaker state on alternation (keep one STT backend for all sessions, or run one OpenWA gateway per backend; this plugin has no per-session instance).

Since v0.26.0, an override or integration instance that points a host key (a key the manifest lists in net.allowConfigHosts, such as chatwoot-adapter's baseUrl or http-action's baseUrl) at another origin than the config beneath it inherits none of that config's secret fields, so a plugin with a secret beside its host key needs the secret set in the override too. See Scope a plugin to specific sessions.

For how to write a plugin that honors overrides, see Building a Plugin.

Next steps​