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

# Rules and Tags

> Use rules in the Hypersender SMS app to filter, tag, forward, and auto-reply to incoming SMS on the phone, and read the tags in your webhooks.

Rules decide what happens to each incoming SMS before it leaves the phone. A rule can keep a message on the device, hide its notification, add tags, send an automatic reply, or stop the rules below it. Tags travel with the message to your [webhooks](#tags-in-webhooks), so your backend knows what kind of message it is.

Rules run on the phone, so they work the same whether or not the phone has a fast connection, and they need no setup on the server.

> [!NOTE]
>
> Rules need Hypersender SMS 1.50 or newer. In the Arabic version of the app, rules are called **الفلاتر**.

## The Rules tab

Open the **Rules** tab in the app. The top of the screen has three buttons:

* **Test all rules** runs a sample message through every rule.
* **Sender lists** holds lists of numbers or sender names that rules can use.
* **Activity** shows the last 100 messages that matched a rule.

Below them is **Forward only messages that match a rule**, then your rules, then the templates.

![The Rules tab with two rules, and the list of templates](https://mintcdn.com/hypersender/ia-WQ1K4yk3iyu2U/images/sms/rules-list.webp?fit=max\&auto=format\&n=ia-WQ1K4yk3iyu2U\&q=85\&s=168cf0d4a2e5dc7fca645d9402606a3b)

### Forward only messages that match a rule

This switch sets what happens when no rule makes a decision:

* **Off (default):** every SMS is forwarded to Hypersender, unless a rule says **Don't forward**.
* **On:** an SMS is forwarded only when a rule says **Forward to Hypersender**. Everything else stays on the phone.

Turn it on when the phone should send only specific messages to your server, such as verification codes.

## How a rule is built

Tap a rule to edit it, or tap **New rule**. The editor has four parts:

1. **Rule name.** Shown in the list and the activity log.
2. **Preview.** The rule as a sentence, updated as you edit.
3. **When an SMS…** One or more conditions, and whether **All conditions must match** or **Any condition is enough**.
4. **Then…** One or more actions.

At the bottom, **Rule is on** turns the rule on or off without deleting it, and **Test this rule** lets you try it before saving.

![The rule editor showing the preview, a message text condition with keywords, a pattern condition, and the tag and forward actions](https://mintcdn.com/hypersender/ia-WQ1K4yk3iyu2U/images/sms/rules-editor.webp?fit=max\&auto=format\&n=ia-WQ1K4yk3iyu2U\&q=85\&s=01fdefbb5f6f48b3a3e369ecf017421d)

## Conditions

| Condition | Options | Notes |
| - | - | - |
| **Message text** | contains any of, is exactly one of, starts with one of, matches pattern | Case-insensitive. Arabic diacritics and letter variants (أ/إ/ا, ى/ي, ة/ه) are ignored, and Arabic digits match 0–9. Patterns are regular expressions. |
| **Sender** | is, contains, starts with, ends with, matches pattern | A number or a sender name like `BANK-EG`. `01001234567` and `+201001234567` are treated as the same number. |
| **Sender list** | is in, is not in | Uses a list from **Sender lists**. |
| **Sender type** | a short code, a sender name, a phone number | Short codes have fewer than 7 digits. Sender names contain letters. |
| **SIM** | SIM 1, SIM 2, any SIM | The SIM the message arrived on. |
| **Time and days** | inside, outside a window; days of the week | Uses the phone's clock. A window like `22:00`–`06:00` runs past midnight. |
| **Message type** | normal, flash | Flash (class 0) messages pop up on the screen and most phones don't store them. |

## Actions

| Action | What it does |
| - | - |
| **Forward to Hypersender** | Sends the message to your account and webhooks. This is the default unless forward-only-matching is on. |
| **Don't forward** | Keeps the message on the phone only. |
| **Notify** | Always shows a notification, even if a later rule says not to. |
| **Don't notify** | Hides the notification. The message is still saved on the phone. |
| **Tag** | Adds one or more tags to the message. See [Tags in webhooks](#tags-in-webhooks). |
| **Auto-reply** | Replies to the sender. See [Auto-replies](#auto-replies). |
| **Stop here** | Rules below this one are not checked for this message. |

## How rules combine

Rules run from top to bottom, in the order shown in the list. Use the arrows on each rule to change the order.

* **Forwarding and notifications:** the first matching rule that decides wins. Later rules can't change it.
* **Tags:** tags from every matching rule are added together, without duplicates.
* **Auto-reply:** the first matching rule with an auto-reply sends it.
* **Stop here:** rules below are skipped for that message.
* **No decision:** the message is forwarded and notified, unless forward-only-matching is on.

> [!TIP]
>
> Put narrow rules first and broad rules last. For example, put a VIP rule that always notifies above a rule that hides notifications for promotions.

## Templates

Templates are ready-made rules. Tap **+** next to one to add it, then tap the new rule to change it.

| Template | What it does | Tags |
| - | - | - |
| **Block promotional SMS** | Messages with words like `offer`, `promo`, `عرض`, or `خصم` stay on the phone, with no notification. | – |
| **Forward only OTP codes** | Messages with words like `code`, `OTP`, `كود`, or `تحقق` and a 4 to 8 digit number are tagged and forwarded. Offers to turn on forward-only-matching. | `otp` |
| **Bank alerts** | Creates a **Banks** sender list and tags messages from those senders. | `bank` |
| **After-hours auto-reply** | Outside 09:00–18:00, Sunday to Thursday, replies once a day per sender. | – |
| **Opt-out handling** | Replies such as `STOP`, `UNSUBSCRIBE`, or `إلغاء` are tagged and get a confirmation SMS, once every 30 days per sender. | `opt-out` |
| **Personal SIM** | Messages on SIM 2 stay on the phone and are not forwarded. | – |
| **VIP customers** | Messages from your **VIP customers** list are tagged and always notify. | `vip` |
| **Carrier messages** | Messages from short codes, such as balance and bundle notices, stay on the phone with no notification. | – |

## Test before saving

**Test this rule** at the bottom of the editor takes a sender, a message, a SIM, a time, and the day. It shows whether the rule matches, which conditions passed or failed, and the result: forwarded or not, notification or not, tags, and any auto-reply.

**Test all rules** does the same for the whole list, so you see how your rules work together. Tests never send anything.

![The test result for one rule, and the Test all rules screen with the combined result](https://mintcdn.com/hypersender/ia-WQ1K4yk3iyu2U/images/sms/rules-test.webp?fit=max\&auto=format\&n=ia-WQ1K4yk3iyu2U\&q=85\&s=b87b98f1d1ed1b463d26007b62129095)

## Activity and sender lists

**Activity** lists the last 100 matches: when the message arrived, on which SIM, which rule matched, and what happened. It is stored on the phone only. Tap **Clear** to empty it.

**Sender lists** are named lists of numbers or sender names, one per line. Use them in the **Sender list** condition. You can type entries or add them from your contacts. A rule that uses a deleted list stops matching until you choose another one.

![The rule activity log and the sender lists screen](https://mintcdn.com/hypersender/ia-WQ1K4yk3iyu2U/images/sms/rules-activity.webp?fit=max\&auto=format\&n=ia-WQ1K4yk3iyu2U\&q=85\&s=26869c2a7cab765afcd3acb1c0cf1757)

## Auto-replies

An auto-reply sends an SMS back to the sender when the rule matches.

* The reply goes out from the same SIM that received the message.
* It is never sent to short codes or sender names, so you won't reply to your bank or carrier by mistake.
* Each sender gets at most one reply per rule within the cooldown you set, from 1 hour to 30 days. The default is 24 hours.
* A failed reply is not retried, so a sender never gets the same reply twice.
* The reply can be up to 480 characters and can include `{sender}`, `{time}`, and `{sim}`.

Auto-replies are sent from the phone and are not reported to the API.

## Tags in webhooks

Tags added by rules are sent with the message in the [`message.phone.received`](https://docs.hypersender.com/v2/api-reference/sms-webhooks/messages-events/message-received) webhook, together with the SIM the message arrived on:

```json theme={null}
{
  "event": "message.phone.received",
  "data": {
    "id": "9f1c2b7e-4d3a-4c8e-9b6f-2a7d5e8c1f04",
    "phone_id": "3b8e6d21-5a7c-4f19-8e2d-6c4a9b0f7e13",
    "from_phone_number": "+201000000002",
    "to_phone_number": "+201000000001",
    "content": "Your code is 4455",
    "sim": "SIM2",
    "tags": ["otp"],
    "status": "received",
    "received_at": "2026-11-20 00:04:24"
  }
}
```

* `tags` is always a list. Messages without tags send `[]`.
* Tags are lowercase. A message keeps up to 10 tags, and each tag is up to 40 characters in the app.
* `sim` is `SIM1` or `SIM2`.
* Tags also appear on received messages returned by the [messages API](https://docs.hypersender.com/v2/api-reference/sms/messages/index-messages.md).

A typical handler routes the message by tag:

```php theme={null}
$data = $request->input('data');
$tags = $data['tags'] ?? [];

match (true) {
    in_array('otp', $tags) => VerifyCode::dispatch($data),
    in_array('opt-out', $tags) => Subscriber::where('phone', $data['from_phone_number'])->delete(),
    in_array('bank', $tags) => RecordBankAlert::dispatch($data),
    default => StoreInboundMessage::dispatch($data),
};

return response()->noContent();
```

## Import and export

Open the menu (⋮) on the Rules tab:

* **Export rules** saves your rules and sender lists to a file.
* **Share rules** sends the file through any app.
* **Import rules** adds rules from a file below your current ones. Nothing is replaced.

Use this to set up several gateway phones the same way.

## Examples

> [accordion] Send only verification codes to the server
>
> 1. Add the **Forward only OTP codes** template and accept the offer to turn on **Forward only messages that match a rule**.
> 2. Add your own words to the keyword list if your services use other wording.
> 3. In your webhook, handle messages tagged `otp`.
>
> Every other SMS stays on the phone.

> [accordion] Keep a personal SIM private on a dual-SIM phone
>
> Add the **Personal SIM** template. Messages on SIM 2 stay on the phone. To use SIM 1 as the personal one, edit the rule and change the SIM condition.

> [accordion] Route support replies by customer tier
>
> 1. Create a sender list called **VIP customers** with your key customers' numbers.
> 2. Add the **VIP customers** template and move it to the top.
> 3. In your backend, send messages tagged `vip` to a priority queue.

> [accordion] Answer customers after working hours
>
> Add the **After-hours auto-reply** template, then change the window, the days, and the reply text. Use `{sender}` in the text to include the customer's number.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.