# 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: ```mermaid {title="Rule execution flow"} sequenceDiagram participant Conv as Conversation box Rule participant Trigger as Trigger participant Ops as Language
Operators participant Ctx as Context participant Act as Action
(Webhook) end participant App as Your Endpoint Conv->>Trigger: Conversation event
(communication, inactive, end) Trigger->>Ops: Trigger fires,
execute operators with parameters opt LLM decides at runtime whether to retrieve context Ops->>Ctx: Tool call: fetch profile
traits and observations Ctx-->>Ops: Conversation Memory results Ops->>Ctx: Tool call: search
knowledge bases Ctx-->>Ops: Enterprise Knowledge results end Ops->>Ops: GenAI analysis with
conversation + context Ops->>Act: Operator results Act->>App: POST results
to your endpoint ``` ## 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**](/docs/conversations/intelligence/use-twilio-authored-language-operators): Pre-built language operators for common use cases. They're ready to use in production. * [**Custom language operators**](/docs/conversations/intelligence/create-custom-language-operators): User-defined language operators tailored to your specific business needs or domains. > \[!NOTE] > > 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](/docs/conversations/memory): Information about the customer in the conversation * [Enterprise Knowledge](/docs/conversations/knowledge): Information about your business's products, policies, or processes Learn more about [context](#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 *n*th 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. > \[!NOTE] > > 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: 1. The intelligence configuration passes available Conversation Memory or Enterprise Knowledge data to any [context-aware language operators](#context-aware-language-operators).\ If a language operator isn't context-aware or doesn't support a particular context type, it ignores that data. 2. Language operators query the data as part of their execution lifecycle. 3. 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](/docs/conversations/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 ](/docs/conversations/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](/docs/conversations/intelligence/business-customer-data). ## Prerequisites Before you define a rule, you must complete the following tasks: * [Create an intelligence configuration](/docs/conversations/intelligence/create-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](/docs/conversations/intelligence/create-custom-language-operators). ## Define a rule Learn how to define rules for your intelligence configuration. Defining a rule involves these steps: 1. Add [language operators](#language-operators). 2. Apply [triggers](#triggers) and [actions](#actions). 3. (Optional) Enable [context](#context). You can define rules using Twilio Console or the API. > \[!NOTE] > > 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. ## API To define a rule using the API: 1. To retrieve the language operator IDs you want to use, make a `GET` request to the [Operators resource](/docs/api/intelligence/v3/Operators): Retrieve a list of language operators ```js // Download the helper library from https://www.twilio.com/docs/node/install const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio"; // Find your Account SID at twilio.com/console // Provision API Keys at twilio.com/console/runtime/api-keys // and set the environment variables. See http://twil.io/secure // For local testing, you can use your Account SID and Auth token const accountSid = process.env.TWILIO_ACCOUNT_SID; const apiKey = process.env.TWILIO_API_KEY; const apiSecret = process.env.TWILIO_API_SECRET; const client = twilio(apiKey, apiSecret, { accountSid: accountSid }); async function listOperators() { const operators = await client.intelligence.v3.operators.list({ limit: 20 }); operators.forEach((o) => console.log(o.id)); } listOperators(); ``` ```python # Download the helper library from https://www.twilio.com/docs/python/install import os from twilio.rest import Client # Find your Account SID at twilio.com/console # Provision API Keys at twilio.com/console/runtime/api-keys # and set the environment variables. See http://twil.io/secure # For local testing, you can use your Account SID and Auth token api_key = os.environ["TWILIO_API_KEY"] api_secret = os.environ["TWILIO_API_SECRET"] account_sid = os.environ["TWILIO_ACCOUNT_SID"] client = Client(api_key, api_secret, account_sid) operators = client.intelligence.v3.operators.list(limit=20) for record in operators: print(record.id) ``` ```csharp // Install the C# / .NET helper library from twilio.com/docs/csharp/install using System; using Twilio; using Twilio.Rest.Intelligence.V3; using System.Threading.Tasks; class Program { public static async Task Main(string[] args) { // Find your Account SID at twilio.com/console // Provision API Keys at twilio.com/console/runtime/api-keys // and set the environment variables. See http://twil.io/secure // For local testing, you can use your Account SID and Auth token string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY"); string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET"); string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID"); TwilioClient.Init(apiKey, apiSecret, accountSid); var _operators = await OperatorResource.ReadAsync(limit: 20); foreach (var record in _operators) { Console.WriteLine(record.Id); } } } ``` ```java // Install the Java helper library from twilio.com/docs/java/install import com.twilio.Twilio; import com.twilio.rest.intelligence.v3.Operator; import com.twilio.base.ResourceSet; public class Example { // Find your Account SID at twilio.com/console // Provision API Keys at twilio.com/console/runtime/api-keys // and set the environment variables. See http://twil.io/secure // For local testing, you can use your Account SID and Auth token public static final String API_KEY = System.getenv("TWILIO_API_KEY"); public static final String API_SECRET = System.getenv("TWILIO_API_SECRET"); public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID"); public static void main(String[] args) { Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID); ResourceSet operators = Operator.reader().limit(20).read(); for (Operator.ListOperatorResponse operator : operators) { System.out.println(operator.getId()); } } } ``` ```ruby # Download the helper library from https://www.twilio.com/docs/ruby/install require 'twilio-ruby' # Find your Account SID at twilio.com/console # Provision API Keys at twilio.com/console/runtime/api-keys # and set the environment variables. See http://twil.io/secure # For local testing, you can use your Account SID and Auth token api_key = ENV['TWILIO_API_KEY'] api_secret = ENV['TWILIO_API_SECRET'] account_sid = ENV['TWILIO_ACCOUNT_SID'] @client = Twilio::REST::Client.new(api_key, api_secret, account_sid) operators = @client .intelligence .v3 .operators .list(limit: 20) operators.each do |record| puts record.id end ``` ```bash curl -X GET "https://intelligence.twilio.com/v3/ControlPlane/Operators?PageSize=20" \ -u $TWILIO_API_KEY:$TWILIO_API_SECRET ``` You can use the following Twilio-authored language operators: {/* When you update this file, review /conversation-intelligence/quickstart.mdx and /conversation-intelligence/define-rules.mdx, /use-twilio-authored-language-operators.mdx for IDs */} * [Script Adherence operator](/docs/conversations/intelligence/use-twilio-authored-language-operators#script-adherence-operator) | `intelligence_operator_01kf34tcyefpyb1t4m0nbd8rxg` * [Next Best Response (NBR) operator](/docs/conversations/intelligence/use-twilio-authored-language-operators#next-best-response-nbr-operator) | `intelligence_operator_01kea27sy7ffsafmtsfp17nzx4` * [Summary operator](/docs/conversations/intelligence/use-twilio-authored-language-operators#summary-operator) | `intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn` * [Sentiment operator](/docs/conversations/intelligence/use-twilio-authored-language-operators#sentiment-operator) | `intelligence_operator_01kcrvw16kfa88qvgrfmr7y151` 2. Do either of the following: * To create an intelligence configuration with rules included, make a `POST` request to the [Intelligence Configurations resource](/docs/api/intelligence/v3/Configurations). * To update an existing intelligence configuration to add rules, make a `PUT` request to the [Intelligence Configurations resource](/docs/api/intelligence/v3/Configurations) 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 ```js // Download the helper library from https://www.twilio.com/docs/node/install const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio"; // Find your Account SID at twilio.com/console // Provision API Keys at twilio.com/console/runtime/api-keys // and set the environment variables. See http://twil.io/secure // For local testing, you can use your Account SID and Auth token const accountSid = process.env.TWILIO_ACCOUNT_SID; const apiKey = process.env.TWILIO_API_KEY; const apiSecret = process.env.TWILIO_API_SECRET; const client = twilio(apiKey, apiSecret, { accountSid: accountSid }); async function updateConfiguration() { const configuration = await client.intelligence.v3 .configurations("intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5") .update({ displayName: "my-intelligence-configuration", rules: [ { operators: [ { id: "intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn", }, ], triggers: [ { on: "CONVERSATION_END", }, ], actions: [ { type: "WEBHOOK", method: "POST", url: "https://crm.example.com/conversation_summary", }, ], context: { knowledge: { bases: ["know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"], }, }, }, ], }); console.log(configuration.accountId); } updateConfiguration(); ``` ```python # Download the helper library from https://www.twilio.com/docs/python/install import os from twilio.rest import Client from twilio.rest.intelligence.v3 import ConfigurationList # Find your Account SID at twilio.com/console # Provision API Keys at twilio.com/console/runtime/api-keys # and set the environment variables. See http://twil.io/secure # For local testing, you can use your Account SID and Auth token api_key = os.environ["TWILIO_API_KEY"] api_secret = os.environ["TWILIO_API_SECRET"] account_sid = os.environ["TWILIO_ACCOUNT_SID"] client = Client(api_key, api_secret, account_sid) configuration = client.intelligence.v3.configurations( "intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5" ).update( update_configuration_request=ConfigurationList.UpdateConfigurationRequest( { "displayName": "my-intelligence-configuration", "rules": [ ConfigurationList.RuleUpdateRequestPayload( { "operators": [ ConfigurationList.Operator( { "id": "intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn" } ) ], "triggers": [ ConfigurationList.Trigger( {"on": "CONVERSATION_END"} ) ], "actions": [ ConfigurationList.Action( { "type": "WEBHOOK", "method": "POST", "url": "https://crm.example.com/conversation_summary", } ) ], "context": ConfigurationList.Context( { "knowledge": ConfigurationList.ContextKnowledge( { "bases": [ "know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] } ) } ), } ) ], } ) ) print(configuration.account_id) ``` ```csharp // Install the C# / .NET helper library from twilio.com/docs/csharp/install using System; using Twilio; using Twilio.Rest.Intelligence.V3; using System.Threading.Tasks; using System.Collections.Generic; class Program { public static async Task Main(string[] args) { // Find your Account SID at twilio.com/console // Provision API Keys at twilio.com/console/runtime/api-keys // and set the environment variables. See http://twil.io/secure // For local testing, you can use your Account SID and Auth token string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY"); string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET"); string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID"); TwilioClient.Init(apiKey, apiSecret, accountSid); var configuration = await ConfigurationResource.UpdateAsync( updateConfigurationRequest: new ConfigurationResource.UpdateConfigurationRequest .Builder() .WithDisplayName("my-intelligence-configuration") .WithRules(new List { new ConfigurationResource.RuleUpdateRequestPayload.Builder() .WithOperators(new List { new ConfigurationResource.Operator.Builder() .WithId("intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn") .Build() }) .WithTriggers(new List { new ConfigurationResource.Trigger.Builder() .WithOn("CONVERSATION_END") .Build() }) .WithActions(new List { new ConfigurationResource.Action.Builder() .WithType("WEBHOOK") .WithMethod("POST") .WithUrl(new Uri("https://crm.example.com/conversation_summary")) .Build() }) .WithContext( new ConfigurationResource.Context.Builder() .WithKnowledge( new ConfigurationResource.ContextKnowledge.Builder() .WithBases(new List { "know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" }) .Build()) .Build()) .Build() }) .Build(), pathId: "intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5"); Console.WriteLine(configuration.AccountId); } } ``` ```java // Install the Java helper library from twilio.com/docs/java/install import java.net.URI; import java.util.Arrays; import java.util.HashMap; import java.util.Map; import com.twilio.Twilio; import com.twilio.rest.intelligence.v3.Configuration; public class Example { // Find your Account SID at twilio.com/console // Provision API Keys at twilio.com/console/runtime/api-keys // and set the environment variables. See http://twil.io/secure // For local testing, you can use your Account SID and Auth token public static final String API_KEY = System.getenv("TWILIO_API_KEY"); public static final String API_SECRET = System.getenv("TWILIO_API_SECRET"); public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID"); public static void main(String[] args) { Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID); Configuration.Operator operator1 = Configuration.Operator.builder("intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn").build(); Configuration.Trigger trigger1 = Configuration.Trigger.builder(Configuration.On.CONVERSATION_END).build(); Configuration.Action action1 = Configuration.Action .builder(Configuration.Type.WEBHOOK, Configuration.Method.POST, URI.create("https://crm.example.com/conversation_summary")) .build(); Configuration.ContextKnowledge contextKnowledge = Configuration.ContextKnowledge.builder(Arrays.asList("know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx")) .build(); Configuration.Context context = Configuration.Context.builder().knowledge(contextKnowledge).build(); Configuration.RuleUpdateRequestPayload ruleUpdateRequestPayload1 = Configuration.RuleUpdateRequestPayload.builder(Arrays.asList(operator1), Arrays.asList(action1)) .triggers(Arrays.asList(trigger1)) .context(context) .build(); Configuration.UpdateConfigurationRequest updateConfigurationRequest = Configuration.UpdateConfigurationRequest .builder("my-intelligence-configuration", Arrays.asList(ruleUpdateRequestPayload1)) .build(); Configuration.UpdateConfigurationResponse response = Configuration.updater("intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5", updateConfigurationRequest) .update(); System.out.println(response.getAccountId()); } } ``` ```ruby # Download the helper library from https://www.twilio.com/docs/ruby/install require 'twilio-ruby' # Find your Account SID at twilio.com/console # Provision API Keys at twilio.com/console/runtime/api-keys # and set the environment variables. See http://twil.io/secure # For local testing, you can use your Account SID and Auth token api_key = ENV['TWILIO_API_KEY'] api_secret = ENV['TWILIO_API_SECRET'] account_sid = ENV['TWILIO_ACCOUNT_SID'] @client = Twilio::REST::Client.new(api_key, api_secret, account_sid) configuration = @client .intelligence .v3 .configurations('intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5') .update( update_configuration_request: { 'displayName' => 'my-intelligence-configuration', 'rules' => [ { 'operators' => [ { 'id' => 'intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn' } ], 'triggers' => [ { 'on' => 'CONVERSATION_END' } ], 'actions' => [ { 'type' => 'WEBHOOK', 'method' => 'POST', 'url' => 'https://crm.example.com/conversation_summary' } ], 'context' => { 'knowledge' => { 'bases' => [ 'know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx' ] } } } ] } ) puts configuration.account_id ``` ```bash UPDATE_CONFIGURATION_REQUEST_OBJ=$(cat << EOF { "displayName": "my-intelligence-configuration", "rules": [ { "operators": [ { "id": "intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn" } ], "triggers": [ { "on": "CONVERSATION_END" } ], "actions": [ { "type": "WEBHOOK", "method": "POST", "url": "https://crm.example.com/conversation_summary" } ], "context": { "knowledge": { "bases": [ "know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] } } } ] } EOF ) curl -X PUT "https://intelligence.twilio.com/v3/ControlPlane/Configurations/intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5" \ --json "$UPDATE_CONFIGURATION_REQUEST_OBJ" \ -u $TWILIO_API_KEY:$TWILIO_API_SECRET ``` ```json { "accountId": "AC00000000000000000000000000000000", "id": "intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5", "displayName": "real-time-intelligence-config", "description": "Intelligence configuration to trigger real-time script adherence operator", "version": 1, "rules": [ { "operators": [ { "id": "intelligence_operator_01kcv35pnkeysaf6z6cqtbpegn" } ], "triggers": [ { "on": "CONVERSATION_END" } ], "actions": [ { "type": "WEBHOOK", "method": "POST", "url": "https://crm.example.com/conversation_summary" } ], "context": { "knowledge": { "bases": [ "know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] } } } ], "dateCreated": "2026-01-12T08:18:17Z", "dateUpdated": "2026-01-12T08:18:17Z" } ``` ## Console To define a rule using Twilio Console: 1. In [Twilio Console](https://1console.twilio.com), go to **Products & services** > **Conversation Intelligence** > **Intelligence configurations**. 2. Find your intelligence configuration and click **Create rule**. 3. Follow the instructions in the UI to: * Add language operators and set parameters. * Apply triggers and actions. * (Optional) Enable context. 4. Review and save your rule.