Keyword auto-reply worked examples

The Auto-Reply Rules guide covers the rule form: fields, match types, scope. This page goes the other direction — concrete scenarios with the exact request, the match outcome to expect, and where the evidence lands afterward. Work through them against your own workspace before you ship a keyword program to customers. Prerequisites: an API key (live keys are prefixed dv_live_sk_), and at least one number on SMS (or your chosen channel) that can receive inbound replies.

export ORBIT_API_KEY="dv_live_sk_…"
export ORBIT_API="https://api.orbit.devotel.io/api/v1"

1. Exact, contains, and starts-with with expected results

Matching is never case-sensitive, and Exact and Starts-with trim leading and trailing whitespace before comparing. The table below assumes four active rules on the sms channel, created in the order listed:

Keyword	Match type	Action
`HOURS`	exact	reply
`SUPPORT`	contains	reply
`HELP`	starts_with	reply
`JOIN`	exact	opt-in

Inbound body	Result	Why
`HOURS`	`HOURS` rule fires	Exact equality after trimming and case folding.
`hours`	`HOURS` rule fires	Trailing whitespace is trimmed; case never matters.
`HOURS PLEASE`	nothing matches	Exact requires the whole body; nothing else covers this text.
`need support now`	`SUPPORT` rule fires	Contains finds the keyword anywhere in the body.
`HELP me`	`HELP` rule fires	Starts-with accepts a keyword followed by more words.
`PLEASE HELP`	nothing matches	Starts-with anchors at the beginning; Contains would match instead.

Create any of these over the API to follow along:

curl -X POST "$ORBIT_API/settings/keyword-rules" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "HOURS",
    "channel": "sms",
    "match_type": "exact",
    "action": "reply",
    "response_text": "We are open Mon–Fri, 9am–5pm ET. Reply SUPPORT for a person."
  }'

Response — 201

{
  "data": {
    "id": "keywordRule_…",
    "keyword": "HOURS",
    "channel": "sms",
    "matchType": "exact",
    "action": "reply",
    "responseText": "We are open Mon–Fri, 9am–5pm ET. Reply SUPPORT for a person.",
    "agentId": null,
    "flowId": null,
    "active": true,
    "createdAt": "2026-08-28T09:12:41.000Z"
  },
  "meta": { "request_id": "req_…", "timestamp": "2026-08-28T09:12:41.000Z" }
}

2. An inbound text, one fired rule, end to end

A customer texts in; the reply goes out asynchronously. Here is the sequence with the evidence to expect at each step:

The inbound arrives. The customer sends hours to your SMS number from their handset.
The platform matches it. The body trims and case-folds to HOURS, which satisfies the exact rule above. Since this rule is the first — and only — match, its action executes.
The reply is sent. The response text goes out through the same billed outbound pipeline as any send. A plain body like the example is delivered verbatim; you can also reference the matched keyword or the sender’s number with tokens, e.g. "Thanks for asking about {{extra.keyword}} — we will text {{contact.phone}} during opening hours." The {{extra.from}} and {{extra.to}} tokens carry the sender and the receiving number when you need them raw.
Confirm in the dashboard. The inbound appears in the Inbox conversation for that contact; the reply appears in the same thread, and as an outbound row across Messages → Tools → Delivery log. Because the log’s filters map one-to-one onto the messages API, the API equivalent of the lookup is:

curl "$ORBIT_API/messages?direction=inbound&q=%2B14155550100" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response — 200 (inbound and reply share the customer’s number on from/to in opposite directions):

{
  "data": [
    {
      "id": "msg_b2c3d4e5f6a7b8c9d0",
      "channel": "sms",
      "direction": "inbound",
      "status": "received",
      "from": "+14155550100",
      "created_at": "2026-08-28T09:14:03.000Z"
    },
    {
      "id": "msg_c3d4e5f6a7b8c9d0e1",
      "channel": "sms",
      "direction": "outbound",
      "status": "delivered",
      "to": "+14155550100",
      "created_at": "2026-08-28T09:14:04.000Z"
    }
  ],
  "meta": {
    "request_id": "req_…",
    "timestamp": "2026-08-28T09:14:04.100Z",
    "pagination": { "cursor": null, "has_more": false, "total": 2 }
  }
}

The reply rows a rule produces are ordinary outbound messages — if the workspace has message suppression enabled, an identical body repeated inside the suppression window is collapsed like any duplicate send. Your own opt-out vocabulary (QUIT, UNSUBSCRIBE, brand-specific words) writes to the same consent records the built-in STOP handling maintains:

curl -X POST "$ORBIT_API/settings/keyword-rules" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "UNSUBSCRIBE",
    "channel": "sms",
    "match_type": "contains",
    "action": "opt-out",
    "response_text": "You are unsubscribed. Reply JOIN to start receiving messages again."
  }'

When a customer texts please unsubscribe me, the rule matches and two records change:

The contact’s channel preferences flip to opted-out, and an entry is appended to the consent history on that contact: action opt_out, method keyword, keyword UNSUBSCRIBE, with the timestamp.
An explicit consent record is written per channel — the same opt-out evidence you can review through the Opt-Out Lists API — so every later send to that contact is refused pre-send with RECIPIENT_OPTED_OUT until they opt back in.

Pair every opt-out keyword with the corresponding opt-in (action: "opt-in") so the customer has a way back. The built-in STOP/START vocabulary is handled before any rule runs — it is not a rule, cannot be shadowed by one, and a rule on STOP never fires.

4. Precedence in action: oldest matching rule wins

Rules are evaluated in creation order, and one inbound fires at most one rule. Suppose these four exist on sms, created in this exact API call order:

Created	Keyword	Match type	Behavior on `YES` vs `YES please`
1st	`YES`	exact	Wins the bare `YES`; the trailing-word form falls through.
2nd	`YES`	contains	Catches `yes please`, `YES that works`.
3rd	`YES`	starts_with	Reached only if the contains rule is disabled or deleted.
4th	`.*`	regex (catch-all)	Fires on anything nothing earlier claimed — which, with 1–3 active, is everything except YES-forms.

Flip the creation order — broad rules first — and the specifics never fire: the contains rule swallows every YES-form, and a catch-all created ahead of the rest swallows everything. To re-sequence, delete the broad rule and re-create it so it becomes the newest:

curl -X DELETE "$ORBIT_API/settings/keyword-rules/keywordRule_…" \
  -H "X-API-Key: $ORBIT_API_KEY"

…then POST it again. One nuance for pagination consumers: the rules list returns newest first (the same order the dashboard table uses), while matching walks oldest first — read the API page from the bottom up when reconstructing evaluation order.

5. The testing harness: prove a rule fired

There is no rule-hit counter. A fired rule is observable through its effects — the record custodians below are where you prove what happened:

Send a real inbound from a handset to your number: the keyword, in the case you expect customers to use.
Inbox. The conversation shows the inbound turn and, for a reply action, the outbound reply in the same thread.
Delivery log. The reply shows as an outbound row; watch it traverse queued → sent → delivered. The row is an ordinary send — the status alone doesn’t name the rule; the sibling inbound in the same conversation is the attribution.
Webhooks. If you subscribe to message status events, the reply’s delivery notification arrives where your sender id correlates — the envelope below is the shape to expect. See Webhook Events for the full status vocabulary.

{
  "id": "evt_01J9Y3ZKEDP8K2X9MTVA6B1C03",
  "type": "message.delivered",
  "created_at": "2026-08-28T09:14:06.000Z",
  "data": {
    "message_id": "msg_c3d4e5f6a7b8c9d0e1",
    "channel": "sms",
    "to": "+14155550100",
    "status": "delivered"
  }
}

Consent surface (opt-in / opt-out actions). The customer’s contact profile shows the flipped preference with the keyword entry in consent history; the Opt-Outs view lists the record.
Flow or agent actions. A trigger_flow match starts a run visible in the flow’s run history (the keyword rides into the run context); a forward_agent match hands the turn to the deployed agent, visible in the conversation timeline.
Audit log. Rule management — create, update, delete — lands in Settings → Audit log with the actor and timestamp, alongside the rest of your organization’s actions. Use it with creation order to reconstruct why the wrong rule won when precedence surprises you.

When a rule that should match doesn’t fire, check in order: the rule is active; the keyword casing is irrelevant but accents are not (CAFE ≠ CAFÉ); an Exact match is being defeated by invisible characters in the body (switch to Contains); or an earlier, broader rule is claiming the message first.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Keyword auto-reply worked examples: match types, opt-outs, and precedence in action

Keyword auto-reply worked examples

1. Exact, contains, and starts-with with expected results

2. An inbound text, one fired rule, end to end

4. Precedence in action: oldest matching rule wins

5. The testing harness: prove a rule fired

See also

​Keyword auto-reply worked examples

​1. Exact, contains, and starts-with with expected results

​2. An inbound text, one fired rule, end to end

​3. An opt-out keyword and the consent record change

​4. Precedence in action: oldest matching rule wins

​5. The testing harness: prove a rule fired

​See also

Keyword auto-reply worked examples

1. Exact, contains, and starts-with with expected results

2. An inbound text, one fired rule, end to end

3. An opt-out keyword and the consent record change

4. Precedence in action: oldest matching rule wins

5. The testing harness: prove a rule fired

See also