# Conditions

**Conditions** control whether an individual [Actions](https://playbook.nativemsg.com/rcs-experience-schema/reference/actions) 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!"
    }
  }
}
```