Skip to content
Step conditions

Step conditions

A channel step (in_app, email, push, chat, sms, stream) can carry a filters field that decides whether it runs. The other step types do not evaluate filters. A step whose condition is false is skipped: a channel step records a message with status skipped and skipReason: "condition", and the run goes on with the next step. A step with no filters, or an empty array, always runs.

{
  "stepId": "sms-vip",
  "type": "sms",
  "controlValues": { "body": "Your order shipped." },
  "filters": [
    {
      "combinator": "AND",
      "conditions": [
        { "on": "subscriber", "field": "data.plan", "operator": "EQUAL", "value": "vip" },
        { "on": "payload",    "field": "amount",    "operator": "LARGER", "value": 100 }
      ]
    }
  ]
}

Structure

filters is an array of groups. The step runs if any group passes (the top-level array is OR).

A group has:

FieldMeaning
combinator"AND" (the default) or "OR", case-insensitive. Anything other than OR is AND.
conditionsLeaf tests.
groupsNested groups, combined with the same combinator.

A group with no conditions and no nested groups passes.

A condition has:

FieldMeaning
onThe data source: subscriber, payload, or the stepId of an earlier http_request or agent_message step (its saved output).
fieldA dot path inside the source, for example data.plan or statusCode.
operatorOne of the operators below.
valueThe comparand.
negatedtrue inverts the result.

Operators

OperatorPasses when
EQUALThe field is present and equals value: the string forms match, or both are numbers and numerically equal.
NOT_EQUALThe opposite of EQUAL. A missing field counts as not equal.
LARGER, SMALLER, LARGER_EQUAL, SMALLER_EQUALBoth sides are numbers (or numeric strings) and the comparison holds.
BETWEENThe field is a number within [min, max] inclusive. value must be a two-element list.
NOT_BETWEENThe field is a number below min or above max. Same value shape; an invalid shape is false.
INThe field is present and equals one element of value, which is a list or a comma-separated string.
NOT_INThe field is not in value.
IS_DEFINEDThe field exists and is not null.
LIKEBoth are strings and the field contains value. Case-sensitive substring test.
NOT_LIKEBoth are strings and the field does not contain value. A non-string is not a match.
ANY_INThe field is a list and at least one element is in value.
ALL_INThe field is a list and every element is in value. An empty list passes.

An unknown operator never matches.

Fail closed

If filters is not valid JSON, or a condition cannot be evaluated, the step is skipped and the message gets skipReason: "condition_invalid". notify prefers sending nothing to sending to everyone because a condition was broken. condition_invalid is distinct from condition so a broken filter is visible in Activity and does not look like a filter working as intended.

Branching on an HTTP call

Because http_request saves its response, a condition can use it:

{ "on": "check", "field": "statusCode", "operator": "EQUAL", "value": 200 }

This is how a delayed send re-checks that it still applies: put an http_request step that asks your service just before the send, and a condition like the one above on the send. When your service already knows the send is moot, cancelling the trigger stops the run outright instead.