> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-reply rules: answer inbound keywords automatically

> Configure keyword-triggered replies, consent keywords, agent handoffs, and flow triggers for inbound SMS, WhatsApp, RCS, and Viber messages.

# Auto-Reply Rules

Auto-reply rules watch inbound messages for keywords and execute an action the moment one matches: send a reply, record an opt-in or opt-out, hand the message to a deployed AI agent, or start an automation flow. A contact who texts `HOURS` gets your opening times back in seconds; a contact who texts `SUPPORT` is routed to your agent — with no one watching the inbox.

Rules live under **Settings → Auto-Reply Rules** in the dashboard and apply to inbound messages on SMS, WhatsApp, RCS, and Viber.

## When to use it

Reach for auto-reply rules when the right response to an inbound message is deterministic — the keyword alone decides what should happen:

* **Appointment confirmations.** Text `YES` to confirm, `NO` to decline. Each keyword sends the acknowledgement you wrote and can kick off a flow that updates the booking.
* **Information keywords.** `HOURS`, `LOCATION`, `MENU`, `PRICES` — a fixed reply that answers itself, so the conversation never needs an agent's time.
* **List growth.** An opt-in keyword (`JOIN`, `SUBSCRIBE`) records consent the moment a contact texts it, so they can be enrolled into your marketing lists and journeys.
* **Triage.** `SUPPORT` forwards the turn to a deployed AI agent or opens a flow, while everything else continues in the inbox as usual.

Consent keywords deserve a separate note. Orbit already recognizes the common opt-out and opt-in words (`STOP`, `START`, and their equivalents across languages) before your rules run, and that built-in handling is not something you configure here — see [How keyword rules interact with consent handling](#how-keyword-rules-interact-with-the-inbox-flows-and-consent) before you create STOP-style rules of your own. Your obligations around consent and quiet hours stay with you: rules are a tenant-owned control, and the responsibility for what your replies say and when they send is yours.

## Rule anatomy

Each rule has five parts:

| Field             | What it controls                                                                                                                                  |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Keyword**       | The text to match — a word, phrase, or (with the regex match type) a pattern.                                                                     |
| **Match type**    | How the keyword is compared to the message. See below.                                                                                            |
| **Channel**       | Which channel the rule watches: `sms`, `whatsapp`, `rcs`, or `viber`. A rule only fires on its own channel.                                       |
| **Action**        | What happens on a match: **Auto-Reply**, **Opt-In**, **Opt-Out**, **Forward to Agent**, or **Trigger Flow**.                                      |
| **Response text** | Required for Auto-Reply; optional confirmation for Opt-In / Opt-Out. Forward to Agent takes an agent ID and Trigger Flow takes a flow ID instead. |

### Match types

Matching is **never case-sensitive** — every match type folds case, so `hours`, `HOURS`, and `Hours` are the same keyword:

* **Exact** — the whole message (after trimming leading and trailing whitespace) must equal the keyword. Use it for single-word commands like `YES` or `STOP`-adjacent vocabulary.
* **Contains** — the keyword appears anywhere in the message. Use it for phrases buried in free text, like replies containing `unsubscribe`.
* **Starts with** — the message begins with the keyword. `HELP` matches `HELP me` and `HELP please`, but not `PLEASE HELP`.
* **Regex** — a full regular expression, matched case-insensitively against the first 1,000 characters of the message. Patterns that could backtrack catastrophically (nested quantifiers like `(a+)+`, alternation inside a quantifier like `(a|b|c)+`) are rejected when you save the rule and re-checked every time a rule is evaluated, so a dangerous pattern can never stall message processing. Write a single quantifier or a character class like `[abc]+` instead.

### Precedence when several rules match

Rules are evaluated **in creation order — oldest first — and the first matching rule wins.** One inbound message fires at most one keyword rule.

That makes ordering your job:

* Create the **specific** rules before the **general** ones. An `exact: YES` rule created before a `contains: YES` rule wins for a bare `YES`; the contains rule still catches `yes that works`.
* A broad `contains` or catch-all rule created early shadows every more specific rule created after it — the specific one never fires. If your fallback is swallowing keyword traffic, the fallback is older than it should be.
* To re-sequence, delete the broad rule and re-create it so it becomes the newest.

### Scope: account-wide per channel

Rule scope has two dimensions people routinely conflate:

* **Channel, not number.** A rule applies to inbound messages on **every reply-capable number you have** on that channel — long codes and short codes alike. Rules are not tied to a specific number, messaging service, or sender pool.
* **Reply-capable senders only.** A rule can only fire when the message came in on a number that receives inbound SMS. An alphanumeric sender ID cannot receive replies, so keyword automation does nothing for those senders. The settings page shows a status banner that tells you whether you have a reply-capable number and links to **Numbers** if you don't — treat "no reply-capable number" as "keyword rules are not live yet."

## Configure a rule

Open **Settings → Auto-Reply Rules** and select **Create rule**. Fill in the keyword, channel, match type, and action, then save. A rule can be saved disabled and flipped on later.

Three worked examples, from the most common setups:

### A YES confirmation rule

1. **Keyword:** `YES` — **Match type:** Exact — **Channel:** `sms`.
2. **Action:** Auto-Reply.
3. **Response text:** `Thanks — your appointment is confirmed. Reply NO to reschedule.`

The exact match confines this to a bare `YES` (any letter case). Pair it with a second exact rule on `NO` that triggers a reschedule flow instead of a reply.

### A BOOK rule that returns a link

1. **Keyword:** `BOOK` — **Match type:** Exact — **Channel:** `whatsapp`.
2. **Action:** Auto-Reply.
3. **Response text:** `Pick a time that suits you: https://your-booking-page.example`

The same pattern covers `MENU`, `PRICES`, `LOCATION`. Keep one intent per keyword — a contact who texts `BOOK` asked the one question.

### A catch-all that routes to the inbox

A catch-all isn't a special action — it's a **Contains** rule with a very short keyword (or a broad regex) created **last**, so every more specific rule beats it. For messages that match nothing else, use **Forward to Agent** (send the turn to a deployed AI agent) or **Trigger Flow** (start a triage flow) instead of a canned reply. If you have no agent deployed for the channel, unmatched messages already land in the inbox — you only need the catch-all when the fallback should do something specific.

## How keyword rules interact with the inbox, flows, and consent

The order things happen on an inbound message matters:

1. **Built-in consent handling runs first.** Orbit recognizes the standard opt-out and opt-in vocabulary (multilingual `STOP` / `START` and their equivalents, including zero-width-character obfuscation a carrier might leave in) before any keyword rule is consulted. Those words are processed as opt-outs/opt-ins directly and your keyword rules are never asked about them — so don't try to override `STOP` with a custom Auto-Reply rule; it will never fire.
2. **Keyword rules are checked next, in creation order.** The first match executes its action. Custom **Opt-Out** and **Opt-In** rules (your own vocabulary — `QUIT`, `JOIN`, brand-specific keywords) write to the same consent and suppression records the built-in handler uses, so a custom opt-out keyword blocks future sends on that channel exactly like a built-in one.
3. **No match → normal routing.** When no rule matches, the message continues to the deployed AI agent for the channel if you have one, and otherwise opens or continues the conversation in the **Inbox** for a human.

An **Auto-Reply** send goes through the same outbound pipeline as any message you send — including opt-out checks — so a contact who has opted out of the channel is not reopened by a keyword reply. **Forward to Agent** hands the turn to a deployed agent you pick by ID, and **Trigger Flow** runs an automation flow with the inbound message as its context — the flow's history shows the keyword that started it.

If you use [message suppression](/guides/message-suppression), be aware it operates on identical outbound bodies: a contact who triggers the same keyword twice inside your suppression window receives the duplicate reply only once. Auto-reply and suppression counters are independent — one doesn't block the other permanently — but a repeat keyword inside the window can be suppressed like any duplicate send.

## Testing and edge cases

* **Test with a real handset.** Send the keyword to your number from a phone, then check the conversation in the **Inbox** and the outbound reply in the [Delivery log](/guides/delivery-log). A matched rule produces a visible reply; a built-in consent keyword produces a consent change and is never attributable to any rule.
* **Disabled rules never fire.** Use the enabled/disabled state in the rules table to stage changes instead of deleting and re-creating.
* **Case never matters, accents always do.** Matching folds case but not accents — `CAFE` and `CAFÉ` are different keywords. If your audience uses both, create a rule per variant or use a regex like `caf[eé]`.
* **Emoji are literal.** An exact rule on `👍` matches a message whose entire body is that emoji and nothing else. For emoji mixed into sentences, use Contains.
* **Trimming is your friend only at the edges.** Leading and trailing whitespace is ignored for Exact and Starts With, but a zero-width or invisible character injected by a carrier inside the body can still defeat an Exact match. If a rule that "should match" does not, switch to Contains or a regex.
* **Regex checks only the first 1,000 characters** of the message. An Exact and Contains comparison reads the whole body; a pattern that only matches beyond the first 1,000 characters never fires.
* **Short codes are first-class.** Rules apply to short codes the same way they apply to long codes — the only requirement is that the sender can receive inbound.
* **Audit what fired.** There is no separate rule-hit counter: the record of a fired rule is the reply in the conversation thread and Delivery log, the consent change on an opt-in/opt-out rule, or the run in the flow's history for Trigger Flow. When investigating "why did the wrong reply go out," check rule creation order first — precedence (oldest matching rule wins) is the usual answer.

## See also

* [Opt-out and suppression posture](/compliance/opt-out-suppression) — how consent and blocking work across channels
* [Message suppression](/guides/message-suppression) — the duplicate-body guard for outbound sends
* [Frequency caps](/guides/frequency-caps) — limiting how many sends a contact receives
* [Build your first flow](/guides/build-first-flow) — the automation flows a keyword rule can trigger
* [Inbox setup](/guides/inbox-setup) — where unmatched inbound messages land