# Conditions

**Conditions** control whether an individual [Actions](/rcs-experience-schema/reference/actions.md) executes at runtime. An action's `conditions` array is evaluated before the action runs; if the conditions are not satisfied, the action is skipped.

A `conditions` array MAY contain any mix of [Condition](#condition) objects and [Operator](#operator) objects. Operators are used to compose multiple conditions with boolean logic.

## Condition Properties

| Property          | Type                       | Required | Default | Constraints                         | Description                                                                |
| ----------------- | -------------------------- | -------- | ------- | ----------------------------------- | -------------------------------------------------------------------------- |
| `channelTypes`    | string \| array of string  | No       | —       | —                                   | Restricts to one or more channel type identifiers (e.g. `"rcs"`, `"dsc"`). |
| `channelIds`      | integer \| string \| array | No       | —       | —                                   | Restricts to specific channel IDs.                                         |
| `tags`            | string \| array of string  | No       | —       | —                                   | Requires the conversation to have these tag(s) assigned.                   |
| `deviceTypes`     | string \| array of string  | No       | —       | If available                        | Restricts to device type(s).                                               |
| `devicePlatforms` | string \| array of string  | No       | —       | If available                        | Restricts to device platform(s).                                           |
| `comparisons`     | array of Comparison        | No       | —       | Each item: array of exactly 3 items | Attribute value comparisons.                                               |
| `unit`            | string                     | No       | —       | `"km"`, `"m"`, `"mi"`, `"ft"`       | Unit for distance comparisons.                                             |
| `precision`       | number                     | No       | —       | —                                   | Decimal precision for numeric comparisons.                                 |

## Comparison Operators

Each entry in `comparisons` is a three-element array: `[attributeName, operator, value]`.

| Operator     | Applies to              | Semantics                                                     |
| ------------ | ----------------------- | ------------------------------------------------------------- |
| `==`         | string, number, boolean | Attribute value equals comparison value (strict equality).    |
| `!=`         | string, number, boolean | Attribute value does not equal comparison value.              |
| `<`          | number                  | Attribute value is less than comparison value.                |
| `>`          | number                  | Attribute value is greater than comparison value.             |
| `<=`         | number                  | Attribute value is less than or equal to comparison value.    |
| `>=`         | number                  | Attribute value is greater than or equal to comparison value. |
| `contains`   | string                  | Attribute value contains comparison value as a substring.     |
| `startsWith` | string                  | Attribute value starts with comparison value.                 |
| `endsWith`   | string                  | Attribute value ends with comparison value.                   |

The third element (comparison value) MUST be a string, number, or boolean.

## Operator

An **Operator** object is inserted into the `conditions` array to combine adjacent Condition objects with boolean logic.

| Property   | Type   | Required | Constraints              | Description                |
| ---------- | ------ | -------- | ------------------------ | -------------------------- |
| `operator` | string | **Yes**  | `"AND"`, `"OR"`, `"NOT"` | Logical operator to apply. |

### AND / OR / NOT Semantics

* **AND** — All conditions on both sides MUST be satisfied.
* **OR** — At least one condition on either side MUST be satisfied.
* **NOT** — The following condition MUST NOT be satisfied.

{% hint style="info" %}
When no Operator is specified between multiple Condition objects in a `conditions` array, the platform's default combining behavior is AND. For explicit control, always include Operator objects.
{% endhint %}

## Composition Rules

{% stepper %}
{% step %}

#### Condition and Operator evaluation order

Condition objects and Operator objects are evaluated in array order.
{% endstep %}

{% step %}

#### Operator scope

An Operator applies to the Conditions immediately surrounding it.
{% endstep %}

{% step %}

#### NOT scope

NOT applies only to the Condition immediately following it.
{% endstep %}

{% step %}

#### Nesting

Nesting is achieved by ordering Conditions and Operators carefully; the schema does not support a parenthetical grouping syntax.
{% endstep %}
{% endstepper %}

## Examples

### Single Condition — Channel Type

Execute this action only on RCS channels:

```json
{
  "conditions": [
    {
      "channelTypes": "rcs"
    }
  ],
  "send": {
    "message": {
      "text": "Here is your RCS-enhanced order summary.",
      "carousel": [
        {
          "title": "Order ACM-12345",
          "description": "2x Acme Pro Runner — Size 10",
          "media": "https://cdn.acme.com/products/pro-runner.jpg"
        },
        {
          "title": "Order total",
          "description": "$149.99 — Paid"
        }
      ]
    }
  }
}
```

### Single Condition — Attribute Comparison

Execute this action only when the attribute `accountTier` equals `"premium"`:

```json
{
  "conditions": [
    {
      "comparisons": [
        ["accountTier", "==", "premium"]
      ]
    }
  ],
  "send": {
    "message": {
      "text": "As a Premium member, you qualify for free expedited shipping on this return."
    }
  }
}
```

### Multiple Comparisons Within One Condition

Multiple entries in the `comparisons` array within a single Condition are combined with AND:

```json
{
  "conditions": [
    {
      "comparisons": [
        ["accountTier", "==", "premium"],
        ["orderTotal", ">=", 100]
      ]
    }
  ],
  "assignTags": "eligible-for-gift"
}
```

### AND Operator — Two Conditions

Both conditions must be satisfied:

```json
{
  "conditions": [
    {
      "channelTypes": "rcs"
    },
    {
      "operator": "AND"
    },
    {
      "comparisons": [
        ["hasOptedIn", "==", true]
      ]
    }
  ],
  "send": {
    "message": {
      "text": "You are subscribed to RCS promotional messages."
    }
  }
}
```

### OR Operator — Two Conditions

Either condition satisfies the check:

```json
{
  "conditions": [
    {
      "tags": "vip-customer"
    },
    {
      "operator": "OR"
    },
    {
      "comparisons": [
        ["lifetimeSpend", ">=", 1000]
      ]
    }
  ],
  "execute": "vip-offer-workflow"
}
```

### NOT Operator — Negated Condition

Execute this action only when the user does NOT have the `opted-out` tag:

```json
{
  "conditions": [
    {
      "operator": "NOT"
    },
    {
      "tags": "opted-out"
    }
  ],
  "send": {
    "message": {
      "text": "We have a special offer just for you this week!"
    }
  }
}
```

### Complex Composition — Tags AND (Channel OR Attribute)

```json
{
  "conditions": [
    {
      "tags": "active-subscriber"
    },
    {
      "operator": "AND"
    },
    {
      "channelTypes": ["rcs", "dsc"]
    },
    {
      "operator": "OR"
    },
    {
      "comparisons": [
        ["forceRichContent", "==", true]
      ]
    }
  ],
  "send": {
    "message": {
      "text": "Here is your personalized weekly summary.",
      "mediaType": "image",
      "media": "https://cdn.acme.com/summaries/weekly-2025-03.png"
    }
  }
}
```

### Channel ID Restriction

Restrict an action to specific channel IDs:

```json
{
  "conditions": [
    {
      "channelIds": [101, 204]
    }
  ],
  "send": {
    "message": {
      "text": "This message targets channels 101 and 204 only."
    }
  }
}
```

### Distance-Based Condition

Check proximity using coordinates with unit specification:

```json
{
  "conditions": [
    {
      "comparisons": [
        ["distanceToStore", "<=", 5]
      ],
      "unit": "km",
      "precision": 1
    }
  ],
  "send": {
    "message": {
      "text": "You are within 5 km of an Acme store. Visit us today!"
    }
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://playbook.nativemsg.com/rcs-experience-schema/reference/conditions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.