Availability rules

An availability rule controls which content the AI Agent can access during a conversation, based on the values of variables. A rule is set through the availability_rules field on a supported resource, such as a knowledge article. When a rule is set, the AI Agent can only use the resource on conversations where the variables’ values match the rule.

Rule schema

A rule is a two-level tree of conditions (a root group plus one level of nested groups):

1
{
2
  "match": "all" | "any",
3
  "conditions": [ <Condition> | <ConditionGroup>, ... ]
4
}

Condition

1
{
2
  "variable": { "id": "<variable id>" },
3
  "operator": "<operator>",
4
  "value": "<string | number | boolean | null>",
5
  "case_sensitive": false
6
}

• variable — required. An object { "id": "<variable id>" } identifying the variable to test. See Variable references.
• operator — required. The comparison to apply (see Operators below).
• value — required for non-unary operators; omit for unary operators (is_set, is_not_set).
• case_sensitive — optional, defaults to false. Only meaningful for the equality (equals, does_not_equal) and string (starts_with, ends_with, contains, does_not_contain) operators. Omitted from responses when false.

ConditionGroup

A condition group applies a nested combinator to a list of conditions. Condition groups may contain only Condition objects — further nesting is not supported.

1
{
2
  "match": "all" | "any",
3
  "conditions": [ <Condition>, ... ]
4
}

Variable references

A condition references a variable by its id:

1
{ "id": "5df263b7db5a7e6ea03fae9b" }

The id is the stable identifier for a variable configured on your Agent. Look up the ids for your Agent through the Variables API.

Not every variable can be used in an availability rule. Variables whose value is set dynamically during a conversation aren’t available when a rule is evaluated, so referencing one returns a 400 with the Variable not usable in a rule error.

Operators

Unary operators (is_set, is_not_set) must not include a value field. Sending value with a unary operator returns a 400 error.

Validation errors

The API returns 400 for the following rule errors:

A validation failure returns a 400 with the error in the standard envelope:

1
{
2
  "errors": [
3
    {
4
      "type": "bad_request",
5
      "message": "Invalid request",
6
      "details": "{'availability_rules': {'conditions': {0: {'variable': {'id': ['Unknown variable.']}}}}}"
7
    }
8
  ]
9
}

Examples

Each example references variables by id. The ids below are illustrative — use the ids of the variables configured on your own Agent.

Language targeting

Match only when the conversation language (variable 5df263b7db5a7e6ea03fae9b) is English:

1
{
2
  "match": "all",
3
  "conditions": [
4
    {
5
      "variable": { "id": "5df263b7db5a7e6ea03fae9b" },
6
      "operator": "equals",
7
      "value": "en"
8
    }
9
  ]
10
}

Presence targeting

Match only when a variable has a value. Here 664c0a1e9f3b2d4a8e7c1a02 is the loyalty_id variable, and the unary is_set operator takes no value:

1
{
2
  "match": "all",
3
  "conditions": [
4
    {
5
      "variable": { "id": "664c0a1e9f3b2d4a8e7c1a02" },
6
      "operator": "is_set"
7
    }
8
  ]
9
}

Numeric comparison

Match only when a numeric variable exceeds a threshold. Here 664c0a1e9f3b2d4a8e7c1a07 is the loyalty_points variable:

1
{
2
  "match": "all",
3
  "conditions": [
4
    {
5
      "variable": { "id": "664c0a1e9f3b2d4a8e7c1a07" },
6
      "operator": "greater_than",
7
      "value": 1000
8
    }
9
  ]
10
}

Compound rule — any of several markets

Match on conversations from either Canada or the United States, where 664c0a1e9f3b2d4a8e7c1a04 is the region variable:

1
{
2
  "match": "any",
3
  "conditions": [
4
    {
5
      "variable": { "id": "664c0a1e9f3b2d4a8e7c1a04" },
6
      "operator": "equals",
7
      "value": "CA"
8
    },
9
    {
10
      "variable": { "id": "664c0a1e9f3b2d4a8e7c1a04" },
11
      "operator": "equals",
12
      "value": "US"
13
    }
14
  ]
15
}

Compound rule — subscription plan with a nested group

Match paying users who are also on a higher loyalty tier, using a nested condition group. Here 664c0a1e9f3b2d4a8e7c1a05 is the subscription_plan variable and 664c0a1e9f3b2d4a8e7c1a06 is the loyalty_tier variable:

1
{
2
  "match": "all",
3
  "conditions": [
4
    {
5
      "variable": { "id": "664c0a1e9f3b2d4a8e7c1a05" },
6
      "operator": "does_not_equal",
7
      "value": "free"
8
    },
9
    {
10
      "match": "any",
11
      "conditions": [
12
        {
13
          "variable": { "id": "664c0a1e9f3b2d4a8e7c1a06" },
14
          "operator": "equals",
15
          "value": "gold"
16
        },
17
        {
18
          "variable": { "id": "664c0a1e9f3b2d4a8e7c1a06" },
19
          "operator": "equals",
20
          "value": "platinum"
21
        }
22
      ]
23
    }
24
  ]
25
}