Skip to main content
Version: v0.31.0

Auto-reply to inbound messages with rules

Automation rules let a session reply on its own. Each rule watches the session's inbound messages and, when one matches, sends a fixed text back through the normal send path — no webhook listener or background worker required on your side. Rules live on the session and are evaluated in order, so you can layer a specific reply on top of a broad one.

This guide shows you how to create, list, update, and delete rules, how to write a match condition, and how the built-in guards keep replies from looping.

Prerequisites
  • A session in the ready state — see Connect a Session.
  • An API key with the operator role or higher, sent as X-API-Key — see Authentication.
  • The key must not be restricted to selected chats (allowedChats, v0.23.6+): every automation-rule route refuses such a key with 403, whatever its role. See Scope a key to chats.
  • A working understanding of sending messages, since a rule's reply uses the same send path.

The examples assume these shell variables:

export BASE="http://localhost:2785/api"
export API_KEY="YOUR_API_KEY"
export SESSION="8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a"

In production, BASE is your own domain over TLS; the /api prefix is unchanged.

How a rule fires​

Two guards run before any rule is evaluated: the message must not be fromMe (so the session's own sends never trigger a self-reply), and it must be fresh. Only then are the rules walked in order, and the first match wins. The cooldown is checked last, against that one rule: if it is still cooling down in this chat the message goes unanswered rather than passing to a later rule; otherwise the cooldown starts and then the reply is sent. The cooldown starts before the send, so a burst of matching messages gets one reply even while the first send is in flight, and a reply that fails still leaves the chat silent for the whole cooldown. Cooldowns are keyed by rule and chat together, so two rules hold independent cooldowns in the same chat. They are held in the gateway process's memory: a restart clears them, and another node does not share them.

Create a rule​

POST /api/sessions/{sessionId}/automation-rules takes a name, the replyText to send back, an optional conditions object, and a per-chat cooldownSeconds.

curl -X POST "$BASE/sessions/$SESSION/automation-rules" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Greet new enquiries",
"replyText": "Thanks for reaching out — we reply within the hour.",
"conditions": {
"conditions": [
{ "field": "isGroup", "operator": "is", "value": false },
{ "field": "body", "operator": "contains", "value": "price" }
]
},
"cooldownSeconds": 300
}'
FieldTypeRequiredNotes
namestringyesDisplay name for the rule, max 100 characters.
replyTextstringyesText sent back into the chat when the rule matches, max 4096 characters.
conditionsobjectnoMatch conditions in the webhook filter format. Omit or leave empty to match every inbound message except those in chats whose kind is channel, broadcast or status.
cooldownSecondsintegernoPer-chat quiet period that starts when the rule fires, in seconds. Default 60, range 0–86400. 0 disables the cooldown for this rule.
enabledbooleannoWhether the rule is active. Default true.

The response (201 Created) echoes the saved rule:

{
"id": "b7c1d2e3-4f5a-6789-0abc-def012345678",
"sessionId": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
"name": "Greet new enquiries",
"enabled": true,
"conditions": {
"conditions": [
{ "field": "isGroup", "operator": "is", "value": false },
{ "field": "body", "operator": "contains", "value": "price" }
]
},
"replyText": "Thanks for reaching out — we reply within the hour.",
"cooldownSeconds": 300,
"createdAt": "2026-08-05T09:14:00.000Z",
"updatedAt": "2026-08-05T09:14:00.000Z"
}

Save the id — you need it to fetch, update, or delete the rule.

A session can hold at most AUTOMATION_MAX_PER_SESSION rules (default 32). A create that lands at or over the cap is rejected with 400; rules that already exceed the cap are grandfathered — they keep working and are not deleted. Set the variable to 0 for no cap.

Write a match condition​

Conditions reuse the webhook filter format, scoped to the message family. A condition is { field, operator, value, caseSensitive? }, and every condition in a rule must match (AND). Omit conditions or send it empty to match every inbound message except those in chats whose kind is channel, broadcast or status — useful as a catch-all that still respects the guards and cooldown.

FieldTypeOperatorsvalue
sendercontact idis, isNotarray of ids or bare phone numbers
recipientcontact idis, isNotarray of ids or bare phone numbers
chatIdchat idis, isNotarray of chat ids; a group as its full <id>@g.us (v0.23.6+)
mentionscontact id listis, isNotarray of ids — matches if any mentioned id is in the list
typemessage typeis, isNotarray of text, image, video, audio, voice, document, sticker, location, contact, poll, call, revoked, order, product, masked, unknown (order and product v0.23.5+)
bodytextcontains, equalsa string; set "caseSensitive": true to match case
isGroupbooleanistrue or false
kindchat kindis, isNotarray of individual, group, channel, status, broadcast, unknown (v0.23.4+)
fromMebooleanistrue or false
hasMediabooleanistrue or false

Id matching is dialect-aware: a bare phone number, a @c.us JID, and the underlying @lid for the same contact all match each other, so "628123456789" and "628123456789@c.us" are equivalent. A phone and an @lid match only through a pair an engine has reported to the gateway (v0.26.0+): a mapping inherited from an older release, including one restored from a backup made on an older release, counts as unknown until an engine reports it again, and two different @lids never match through a shared phone. Since v0.23.6 an @lid written in the condition resolves the same way as the message's, so a rule naming a contact or chat by its @lid keeps matching once the gateway learns that identity's phone number; earlier releases flipped such a condition at that moment. A condition is validated on save — an unknown field, an unsupported operator, a wrong value type, an id entry over 128 characters on sender, recipient, chatId, or mentions (v0.28.0+), or an oversized body string returns 400 with a field-level message.

kind separates what isGroup cannot: a channel, a status update and a broadcast list are all isGroup: false, exactly like a one-to-one chat. Use { "field": "kind", "operator": "is", "value": ["individual"] } for a rule that should only ever answer a direct message.

chatId (v0.23.6+) confines a rule to specific conversations: { "field": "chatId", "operator": "is", "value": ["120363000000000000@g.us"] } answers in that group only, and isNot keeps a rule out of it. Write a group as its full <id>@g.us JID; bare digits are read as a phone number and match no group. A gateway older than v0.23.6 refuses a chatId condition as an unrecognized field.

On Baileys, since v0.23.6, a WhatsApp Business list prompt and a contact's tap on a button, template quick-reply or list row arrive as type: "text" rather than unknown, so a rule scoped to text now answers them too, and one scoped to unknown no longer does. A tapped list row also carries the row title in body, and a list prompt its description (else its title), where both arrived empty before, so a body condition can now match them. A native-flow reply with no body text of its own, whose parameters carry a button label next to its id, likewise carries that label in body, where it arrived empty before.

Since v0.23.7, a rule without an explicit kind condition skips channels, broadcast lists and status messages. Add the intended kind when a rule should answer there. On Baileys, since v0.24.0, a message received through a contact's broadcast list is filed under the sender's chat with kind: individual, so a rule without a kind condition answers it, a rule limited to individual matches it, and no kind value tells it apart from a direct message; a broadcast-list message that names no sender keeps kind: broadcast and is still skipped. Since v0.23.7, on whatsapp-web.js, button, template-button and list replies are type: "text"; rules that previously matched their engine-specific type tokens should match text instead. Since v0.24.0, unknown keys in the conditions object or a condition are refused with 400 rather than stored and ignored.

List, update, and delete​

All management routes are scoped to a session, so a wrong-session ruleId resolves to 404.

ActionMethod + path
List the session's rulesGET /api/sessions/{sessionId}/automation-rules
Get oneGET /api/sessions/{sessionId}/automation-rules/{ruleId}
UpdatePUT /api/sessions/{sessionId}/automation-rules/{ruleId}
DeleteDELETE /api/sessions/{sessionId}/automation-rules/{ruleId}

List rules​

curl "$BASE/sessions/$SESSION/automation-rules" \
-H "X-API-Key: $API_KEY"

Rules come back in evaluation order — oldest first, with the rule id as the same-second tiebreak — so the order you read here is the order the session walks them:

[
{
"id": "b7c1d2e3-4f5a-6789-0abc-def012345678",
"sessionId": "8f3c2b1a-9d4e-4c7a-8b2f-1e6d5a4c3b2a",
"name": "Greet new enquiries",
"enabled": true,
"conditions": null,
"replyText": "Thanks for reaching out — we reply within the hour.",
"cooldownSeconds": 60,
"createdAt": "2026-08-05T09:14:00.000Z",
"updatedAt": "2026-08-05T09:14:00.000Z"
}
]

Update a rule​

PUT accepts the same fields as create. Every field is optional — send only what changes. Disabling a rule stops it firing immediately, without deleting it:

curl -X PUT "$BASE/sessions/$SESSION/automation-rules/b7c1d2e3-4f5a-6789-0abc-def012345678" \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'

The response (200 OK) is the updated rule in the same shape as create. Since v0.26.0 the update writes only the fields you send, so two overlapping edits (a disable and a rename, say) no longer undo each other, and an update that loses a race with a delete answers 404 instead of bringing the rule back.

Delete a rule​

curl -X DELETE "$BASE/sessions/$SESSION/automation-rules/b7c1d2e3-4f5a-6789-0abc-def012345678" \
-H "X-API-Key: $API_KEY" -i

A successful delete returns 204 No Content with an empty body.

How the guards bound reply loops​

A rule that replies to anything would otherwise answer every message, including the ones it sent and the ones the contact sent seconds ago. Three guards keep that from happening:

  • fromMe. A rule never fires on a message the session itself sent, so a rule's own reply cannot trigger itself.
  • Freshness. A rule only fires on a message less than 5 minutes (300 s) old, so replaying history or a delayed webhook does not produce a stale reply. A message the engine reported without a timestamp counts as fresh. Since v0.23.6 a Baileys session also delivers the messages WhatsApp queued while it was down, which earlier releases dropped; after an outage, rules can answer the ones still under 5 minutes old, and the older ones get no reply.
  • Per-chat cooldown. Once a rule fires in a chat, that chat is silent to it for cooldownSeconds (default 60), counted from just before the reply is sent, so a reply that fails still starts it. The cooldown is keyed to the exact chat id the message arrived under (@c.us and @lid are not linked for cooldown). The gateway process holds it in memory and a restart clears it. This is the guard against two auto-repliers answering each other forever — disable it knowingly by setting cooldownSeconds: 0.

The reply itself goes through the normal text-send path, so it is subject to send pacing as any other send (a pacing refusal reaches the audit log), and it waits for the same typing pause as send-text (see Send a text message). The reply sets no linkPreview of its own, so the session's linkPreview default (v0.30.3+) applies to it when one is set. The request rate limiter (RATE_LIMIT_*) does not apply, because the reply is not an HTTP request.

Common errors​

Errors use the standard envelope { statusCode, message, error }. On a 400 validation failure, message is an array of field-level strings.

StatusCauseFix
400 Bad RequestA name or replyText over its cap or sent as a JSON boolean or object (v0.26.0+; a JSON number is still read as its text), a malformed conditions object (including an id condition entry over 128 characters in v0.28.0+), or the session is at its rule cap (AUTOMATION_MAX_PER_SESSION, default 32).Check the message array for the offending field; delete a rule before adding another at the cap.
401 UnauthorizedMissing, invalid, revoked, or expired X-API-Key.Send a valid, active key. See Authentication.
403 ForbiddenThe key is valid but its role is below operator, its IP or session scope excludes the request, or (v0.23.6+) the key is restricted to selected chats (allowedChats), which every automation-rule route refuses.Use an operator-or-higher key that carries no chat allowlist.
404 Not FoundNo rule with this id in this session: the rule id does not exist, it belongs to a different session, or the session itself does not exist. Since v0.23.6 a create for an unknown session answers 404; earlier releases answered 500. Listing the rules of an unknown session is not an error: it returns an empty array.Confirm both sessionId and the rule id.

Next steps​

  • Webhooks — the filter format rules reuse, and how to watch the replies a rule sends.
  • Safe sending — the send path a rule's reply passes through, including pacing.
  • API reference — the full automation-rule endpoint schemas.

Automation rules are readable over MCP as well: the AutomationRuleFindAll and AutomationRuleFindOne tools expose the two reads. Creating, updating and deleting a rule stays REST-only. See MCP.