Define rules for your intelligence configuration

Rules define when and how your intelligence configuration analyzes a conversation. Each rule is a conversational analysis task that specifies:

What you want to understand
When analysis should run
Which data the analysis should use
What to do with the results

How rules work at runtime

The following diagram shows how a rule executes during a conversation:

Rule components

Rules let you orchestrate language operators throughout the conversation lifecycle. A rule has the following components:

Component	What it defines	Examples
Language operators	What meaning to extract from the conversation text	Sentiment, intent, topic detection
Triggers	When the language operators should run	On communication (with an option for every N communications), On conversation inactive, On conversation end
Actions	What to do with language operator results	Send a webhook
Context	What additional data to provide to language operators to improve results	Customer Memory, Enterprise Knowledge

Language operators

A language operator defines the type of meaning or insight to extract from the conversation. All language operators in the same rule run at the times specified by the trigger. There are two types of language operators:

Twilio-authored language operators: Pre-built language operators for common use cases. They're ready to use in production.
Custom language operators: User-defined language operators tailored to your specific business needs or domains.

(information)

Twilio-authored vs. custom language operators

By default, your intelligence configuration has access to Twilio-authored language operators. If you want to use your own language operators for your specific use case, define them before defining your rule.

You can include up to five language operators in a single rule.

Language operator parameters

A language operator can have one or more parameters, which control its behavior at runtime. Each language operator has its own set of parameters.

Context-aware language operators

Enabling context lets a language operator:

Personalize its output
Use business or domain information
Produce more accurate and relevant results

When you add a language operator, Twilio Console or the API shows if it supports context-awareness. A context-aware language operator can use extra data to improve results:

Conversation Memory: Information about the customer in the conversation
Enterprise Knowledge: Information about your business's products, policies, or processes

Learn more about context.

Triggers

A trigger determines when your rule and its attached language operators run during the conversation lifecycle.

With triggers, you can decide whether language operators run in real time during the conversation or after it ends, depending on your use case.

Available triggers

On communication: Starts on each new communication received from any participant (voice utterances, messages, transcripts). Ideal for real-time analysis like sentiment, intent detection, or agent assist.
- Every N communications: Starts on every nth communication instead of every single one. For example, setting n to 5 runs the rule on every 5th message. Use this trigger to reduce costs when you don't need analysis on every utterance but still want periodic insights during the conversation.
On conversation inactive: Starts when a conversation moves to an inactive state.
On conversation end: Starts once when the conversation is closed. Commonly used for summarization, disposition classification, and output consolidation.

When using the API, set the on field in the trigger object to one of the following values:

Trigger	API value	Example
On communication	`COMMUNICATION`	`{"on": "COMMUNICATION"}`
Every N communications	`COMMUNICATION`	`{"on": "COMMUNICATION", "every": 5}`
On conversation inactive	`CONVERSATION_INACTIVE`	`{"on": "CONVERSATION_INACTIVE"}`
On conversation end	`CONVERSATION_END`	`{"on": "CONVERSATION_END"}`

Actions

An action defines what should happen after your rule's language operators run and produce results. Each time the rule fires, the results from all language operators in the rule are delivered through the action.

With actions, you can deliver or use language operator results outside Twilio, typically in your business systems or downstream workflows.

(information)

Supported actions

Intelligence configurations only support webhook actions.

Webhook actions

A webhook sends the language operator result payload to an external HTTP endpoint you control.

When you set up a webhook action, you configure:

URL: The endpoint that should receive language operator results
Method: GET or POST

Examples

Send real-time language operator results to an agent desktop: A rule triggered on every communication posts sentiment, intent, or Natural Language Understanding (NLU) outputs to https://example.com/agent-assist.
Deliver a summary when a conversation ends: A rule triggered when conversation ends posts a final summary object to your Customer Relationship Management (CRM) at https://crm.example.com/conversation-summary.
Periodic sentiment check: A rule triggered every 5 communications posts a sentiment snapshot to https://example.com/periodic-sentiment, reducing cost while still tracking shifts during the conversation.
On-demand analysis: Use the API-based execution trigger to run operators against an active conversation whenever your application needs it, without waiting for an automated trigger.

Context

With context, you can give your language operators extra information about the customer or your business to produce more accurate and personalized results. When you add context to the rule, here's what happens:

The intelligence configuration passes available Conversation Memory or Enterprise Knowledge data to any context-aware language operators.
If a language operator isn't context-aware or doesn't support a particular context type, it ignores that data.
Language operators query the data as part of their execution lifecycle.
Language operators determine at runtime whether to use the provided context, based on whether it thinks the context is relevant.

For context to work, both the rule and the language operator must have the corresponding context enabled.

You can add the following types of context for your rule:

Conversation Memory
Enterprise Knowledge

Language operators that don't support a particular context type will ignore those settings.

Conversation Memory

Conversation Memory provides language operators with access to Profiles containing your customer's known attributes and conversational memories. Profiles include two main types of data:

Traits: Structured key/value attributes about the customer, like name, birthday, or last purchase date.
Conversational Memories: Automatically captured observations about the customer based on past conversational communications. Conversational Memories only appear if Conversation Memory has captured them during prior conversations.

Enterprise Knowledge

Enterprise Knowledge lets language operators access business artifacts you've configured, like FAQs, policy documents, product catalogs, or troubleshooting guides.

When you enable Enterprise Knowledge as context, you must select one or more knowledge bases. A knowledge base is a container for knowledge sources like documents or data sets. When you add a knowledge base, all its knowledge sources become available to eligible language operators at runtime.

Learn more about business and customer data for language operators.

Prerequisites

Before you define a rule, you must complete the following tasks:

Create an intelligence configuration.
If you want to use context-aware language operators, activate Conversation Memory and Enterprise Knowledge for your Twilio account.
If you want to use your own language operators instead of Twilio-authored ones, create custom language operators.

Define a rule

Learn how to define rules for your intelligence configuration. Defining a rule involves these steps:

Add language operators.
Apply triggers and actions.
(Optional) Enable context.

You can define rules using Twilio Console or the API.

(information)

When to use Twilio Console or the API

Twilio recommends using Twilio Console for most users. If you're an Independent Software Vendor (ISV) or use Infrastructure as Code (IaC) automation, use the API to programmatically define and manage rules.

APIConsole

To define a rule using the API:

To retrieve the language operator IDs you want to use, make a GET request to the Operators resource:
Retrieve a list of language operators
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID at twilio.com/console
5
// Provision API Keys at twilio.com/console/runtime/api-keys
6
// and set the environment variables. See http://twil.io/secure
7
// For local testing, you can use your Account SID and Auth token
8
const accountSid = process.env.TWILIO_ACCOUNT_SID;
9
const apiKey = process.env.TWILIO_API_KEY;
10
const apiSecret = process.env.TWILIO_API_SECRET;
11
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12

13
async function listOperators() {
14
const operators = await client.intelligence.v3.operators.list({ limit: 20 });
15

16
operators.forEach((o) => console.log(o.id));
17
}
18

19
listOperators();
You can use the following Twilio-authored language operators:
- Script Adherence operator | intelligence_operator_01kf34tcyefpyb1t4m0nbd8rxg
- Next Best Response (NBR) operator | intelligence_operator_01kea27sy7ffsafmtsfp17nzx4
- Summary operator | intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn
- Sentiment operator | intelligence_operator_01kcrvw16kfa88qvgrfmr7y151

Do either of the following:

To create an intelligence configuration with rules included, make a POST request to the Intelligence Configurations resource.
To update an existing intelligence configuration to add rules, make a PUT request to the Intelligence Configurations resource using the intelligence configuration ID.

The following example updates an existing intelligence configuration to add a rule that:

Uses the Summary operator
Runs once at the end of the conversation (CONVERSATION_END)
Uses Conversation Memory (customer_memory) to pull customer traits and conversational memories
Uses a knowledge base (knowledge) to anchor facts
Sends the final summary to a CRM endpoint via a webhook action (actions)

Define a rule with the Summary operator

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function updateConfiguration() {
14  const configuration = await client.intelligence.v3
15    .configurations("intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5")
16    .update({
17      displayName: "my-intelligence-configuration",
18      rules: [
19        {
20          operators: [
21            {
22              id: "intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn",
23            },
24          ],
25          triggers: [
26            {
27              on: "CONVERSATION_END",
28            },
29          ],
30          actions: [
31            {
32              type: "WEBHOOK",
33              method: "POST",
34              url: "https://crm.example.com/conversation_summary",
35            },
36          ],
37          context: {
38            knowledge: {
39              bases: ["know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"],
40            },
41          },
42        },
43      ],
44    });
45
46  console.log(configuration.accountId);
47}
48
49updateConfiguration();

Response

1{
2  "accountId": "AC00000000000000000000000000000000",
3  "id": "intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5",
4  "displayName": "real-time-intelligence-config",
5  "description": "Intelligence configuration to trigger real-time script adherence operator",
6  "version": 1,
7  "rules": [
8    {
9      "operators": [
10        {
11          "id": "intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn"
12        }
13      ],
14      "triggers": [
15        {
16          "on": "CONVERSATION_END"
17        }
18      ],
19      "actions": [
20        {
21          "type": "WEBHOOK",
22          "method": "POST",
23          "url": "https://crm.example.com/conversation_summary"
24        }
25      ],
26      "context": {
27        "knowledge": {
28          "bases": [
29            "know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
30          ]
31        }
32      }
33    }
34  ],
35  "dateCreated": "2026-01-12T08:18:17Z",
36  "dateUpdated": "2026-01-12T08:18:17Z"
37}