# Create an intelligence configuration

An intelligence configuration defines *how* and *when* language operators analyze your conversations. It determines:

* Which language operators to run
* When they should execute (trigger conditions)
* How results should be handled

Intelligence configurations operate exclusively on conversations from [Conversation Orchestrator](/docs/conversations/orchestrator), ensuring that language operators run on a unified, cross-channel conversation lifecycle.

This guide covers how to create an intelligence configuration using Twilio Console or the API.

## Conversation and intelligence configurations

To use Conversation Intelligence, you must associate your intelligence configuration with one or more [conversation configurations](/docs/conversations/orchestrator/concepts/core#conversation-configuration). A conversation configuration:

* Provides a channel-agnostic, normalized representation of customer conversations and their metadata.
* Unifies interactions across voice and text channels, including Voice, SMS, RCS, and Chat.
* Resolves and automatically attaches customer identities through Profiles.

### Why use Conversation Orchestrator with Conversation Intelligence?

Conversation Intelligence requires Conversation Orchestrator. Conversation Orchestrator provides a complete, unified view of every interaction:

* **Cross-channel analysis**: Analyze conversations across voice, SMS, WhatsApp, chat, and other channels with a unified conversation lifecycle.
* **Customer-aware language analysis**: Language operators can incorporate customer attributes for richer, personalized analysis.
* **Cohesive analysis for multi-channel journeys**: When a customer moves from voice → SMS → WhatsApp, Conversation Intelligence treats it as one continuous interaction.

> \[!WARNING]
>
> To maintain data hygiene and consistency across products, when a conversation is deleted from [Conversation Orchestrator](/docs/conversations/orchestrator), the corresponding conversation and its associated operator results are automatically deleted from Conversation Intelligence. This synchronization might take some time to complete.

### How conversation and intelligence configurations work

The following describes how conversation and intelligence configurations interact:

1. The conversation configuration activates your intelligence configuration.
2. The configuration of your conversation configuration, such as which channels send data and how to create conversations, determines which interactions your intelligence configuration analyzes.
3. When conversation events occur (messages, recordings, or transcript segments), the conversation configuration does the following:
   * Detects the event
   * Applies your intelligence configuration rules
   * Triggers the corresponding language operators

## Prerequisites

Before you create an intelligence configuration, you must [create a conversation configuration and a memory store](/docs/conversations/memory/getting-started).

You don't need to migrate your existing Twilio channel integration to the Conversations API. However, you can:

* Enable automatic conversation creation with capture rules, which create or update Conversations on channel events.
* Continue using Voice APIs or TwiML and add parameters to manage Conversations more precisely.

## Create an intelligence configuration

Creating an intelligence configuration involves the following steps:

1. Create an intelligence configuration.
2. Attach one or more conversation configurations to the intelligence configuration.

**Note**: Create a separate intelligence configuration for each use case, organizing them by purpose or function. For example, create one intelligence configuration for live agent assist and another for AI agent observability.

You can define intelligence configuration rules when you create an intelligence configuration or later. Rules provide specific instructions on how to execute language operators. For more information, see [Define rules](/docs/conversations/intelligence/define-rules).

You can create an intelligence configuration using either 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 create and manage intelligence configurations.

## Console

To create an intelligence configuration using Twilio Console:

1. In [Twilio Console](https://1console.twilio.com), go to **Products & services** > **Conversation Intelligence** > **Intelligence configurations**.
2. Click **Create intelligence configuration**.
3. Set a **Name** (for example, `Voice Support Assistant`).
4. Optionally, set a **Description** (for example, `Real-time sentiment and post-call summaries`).
5. Under **Attach Conversation Configuration**, select the conversation configuration you created earlier.
   This determines *which conversations your intelligence configuration will analyze*. For example, if you attach a conversation configuration that captures `VOICE` calls on `+1 (888) 888-8888`, your intelligence configuration will only analyze conversations from that number.
6. To save the intelligence configuration, click **Submit**.

## API

To create an intelligence configuration using the API:

1. Make a `POST` request to the [Intelligence Configurations resource](/docs/api/intelligence/v3/Configurations).

   Create an intelligence configuration

   ```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 createConfiguration() {
     const configuration = await client.intelligence.v3.configurations.create({
       displayName: "my-intelligence-configuration",
       description: "Captures voice calls for Conversation Intelligence analysis",
       rules: [],
     });

     console.log(configuration.accountId);
   }

   createConfiguration();
   ```

   ```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.create(
       create_configuration_request=ConfigurationList.CreateConfigurationRequest(
           {
               "displayName": "my-intelligence-configuration",
               "description": "Captures voice calls for Conversation Intelligence analysis",
               "rules": [],
           }
       )
   )

   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.CreateAsync(
               createConfigurationRequest: new ConfigurationResource.CreateConfigurationRequest
                   .Builder()
                   .WithDisplayName("my-intelligence-configuration")
                   .WithDescription("Captures voice calls for Conversation Intelligence analysis")
                   .WithRules(new List<ConfigurationResource.RuleCreationRequestPayload> {

                   })
                   .Build());

           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.CreateConfigurationRequest createConfigurationRequest =
               Configuration.CreateConfigurationRequest
                   .builder("my-intelligence-configuration",
                       Arrays.asList(

                           ))
                   .description("Captures voice calls for Conversation Intelligence analysis")
                   .build();

           Configuration.CreateConfigurationResponse response = Configuration.creator(createConfigurationRequest).create();

           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
                   .create(
                     create_configuration_request: {
                       'displayName' => 'my-intelligence-configuration',
                       'description' => 'Captures voice calls for Conversation Intelligence analysis',
                       'rules' => [

                       ]
                     }
                   )

   puts configuration.account_id
   ```

   ```bash
   CREATE_CONFIGURATION_REQUEST_OBJ=$(cat << EOF
   {
     "displayName": "my-intelligence-configuration",
     "description": "Captures voice calls for Conversation Intelligence analysis",
     "rules": []
   }
   EOF
   )
   curl -X POST "https://intelligence.twilio.com/v3/ControlPlane/Configurations" \
   --json "$CREATE_CONFIGURATION_REQUEST_OBJ" \
   -u $TWILIO_API_KEY:$TWILIO_API_SECRET
   ```

   ```json
   {
     "accountId": "AC00000000000000000000000000000000",
     "id": "intelligence_configuration_01kermhm82e5mr98nbeh1hpmbn",
     "displayName": "real-time-intelligence-config",
     "description": "Captures voice calls for Conversation Intelligence analysis",
     "version": 1,
     "rules": [],
     "dateCreated": "2026-01-12T08:18:17Z",
     "dateUpdated": "2026-01-12T08:18:17Z"
   }
   ```
2. To attach the intelligence configuration, make a [`PUT` request to the Conversations Configuration resource](/docs/api/conversations/v2/Conversation#update-conversation-by-id).

   This determines *which conversations your intelligence configuration will analyze*. For example, if you attach a conversation configuration that captures `VOICE` calls on `+1 (888) 888-8888`, your intelligence configuration will only analyze conversations from that number.

   Attach your intelligence configuration to a conversation configuration

   ```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.conversations.v2
       .configurations("<CONVERSATION_CONFIGURATION_ID>")
       .update({
         displayName: "my-conversations-configuration",
         description:
           "Captures voice calls for Conversation Intelligence analysis",
         conversationGroupingType: "GROUP_BY_PARTICIPANT_ADDRESSES",
         memoryStoreId: "<MEMORY_STORE_ID>",
         channelSettings: {
           VOICE: {
             captureRules: [
               {
                 from: "*",
                 to: "<TWILIO_PHONE_NUMBER>",
               },
             ],
           },
         },
         intelligenceConfigurationIds: ["<INTELLIGENCE_CONFIGURATION_ID>"],
       });

     console.log(configuration.statusUrl);
   }

   updateConfiguration();
   ```

   ```python
   # Download the helper library from https://www.twilio.com/docs/python/install
   import os
   from twilio.rest import Client
   from twilio.rest.conversations.v2 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.conversations.v2.configurations(
       "<CONVERSATION_CONFIGURATION_ID>"
   ).update(
       update_configuration_request=ConfigurationList.UpdateConfigurationRequest(
           {
               "displayName": "my-conversations-configuration",
               "description": "Captures voice calls for Conversation Intelligence analysis",
               "conversationGroupingType": "GROUP_BY_PARTICIPANT_ADDRESSES",
               "memoryStoreId": "<MEMORY_STORE_ID>",
               "channelSettings": {
                   "VOICE": ConfigurationList.UpdateConfigurationRequestChannelSettingsValue(
                       {
                           "captureRules": [
                               ConfigurationList.UpdateConfigurationRequestChannelSettingsValueCaptureRules(
                                   {"from": "*", "to": "<TWILIO_PHONE_NUMBER>"}
                               )
                           ]
                       }
                   )
               },
               "intelligenceConfigurationIds": ["<INTELLIGENCE_CONFIGURATION_ID>"],
           }
       )
   )

   print(configuration.status_url)
   ```

   ```csharp
   // Install the C# / .NET helper library from twilio.com/docs/csharp/install

   using System;
   using Twilio;
   using Twilio.Rest.Conversations.V2;
   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(new UpdateConfigurationOptions(
               "<CONVERSATION_CONFIGURATION_ID>") {
               UpdateConfigurationRequest =
                   new ConfigurationResource.UpdateConfigurationRequest.Builder()
                       .WithDisplayName("my-conversations-configuration")
                       .WithDescription("Captures voice calls for Conversation Intelligence analysis")
                       .WithConversationGroupingType("GROUP_BY_PARTICIPANT_ADDRESSES")
                       .WithMemoryStoreId("<MEMORY_STORE_ID>")
                       .WithChannelSettings(new Dictionary<
                                            string,
                                            ConfigurationResource
                                                .UpdateConfigurationRequestChannelSettingsValue>() {
                           { "VOICE",
                             new ConfigurationResource.UpdateConfigurationRequestChannelSettingsValue
                                 .Builder()
                                 .WithCaptureRules(
                                     new List<
                                         ConfigurationResource
                                             .UpdateConfigurationRequestChannelSettingsValueCaptureRules> {
                                         new ConfigurationResource
                                             .UpdateConfigurationRequestChannelSettingsValueCaptureRules
                                             .Builder()
                                             .WithFrom("*")
                                             .WithTo("<TWILIO_PHONE_NUMBER>")
                                             .Build()
                                     })
                                 .Build() }
                       })
                       .WithIntelligenceConfigurationIds(
                           new List<string> { "<INTELLIGENCE_CONFIGURATION_ID>" })
                       .Build()
           });

           Console.WriteLine(configuration.StatusUrl);
       }
   }
   ```

   ```java
   // Install the Java helper library from twilio.com/docs/java/install

   import java.util.Arrays;
   import java.util.HashMap;
   import java.util.Map;
   import com.twilio.Twilio;
   import com.twilio.rest.conversations.v2.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.UpdateConfigurationRequest updateConfigurationRequest =
               Configuration.UpdateConfigurationRequest
                   .builder("Captures voice calls for Conversation Intelligence analysis",
                       Configuration.ConversationGroupingType.GROUP_BY_PARTICIPANT_ADDRESSES,
                       "<MEMORY_STORE_ID>",
                       new HashMap<String, Map<String, Object>>() {
                           {
                               put("VOICE", new HashMap<String, Object>() {
                                   {
                                       put("captureRules",
                                           Arrays.asList(new HashMap<String, Object>() {
                                               {
                                                   put("from", "*");
                                                   put("to", "<TWILIO_PHONE_NUMBER>");
                                               }
                                           }

                                               ));
                                   }
                               });
                           }
                       })
                   .displayName("my-conversations-configuration")
                   .intelligenceConfigurationIds(Arrays.asList("<INTELLIGENCE_CONFIGURATION_ID>"))
                   .build();

           Configuration.UpdateConfigurationResponse response =
               Configuration.updater("<CONVERSATION_CONFIGURATION_ID>")
                   .setUpdateConfigurationRequest(updateConfigurationRequest)
                   .update();

           System.out.println(response.getStatusUrl());
       }
   }
   ```

   ```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
                   .conversations
                   .v2
                   .configurations('<CONVERSATION_CONFIGURATION_ID>')
                   .update(
                     update_configuration_request: {
                       'displayName' => 'my-conversations-configuration',
                       'description' => 'Captures voice calls for Conversation Intelligence analysis',
                       'conversationGroupingType' => 'GROUP_BY_PARTICIPANT_ADDRESSES',
                       'memoryStoreId' => '<MEMORY_STORE_ID>',
                       'channelSettings' => {
                         'VOICE' => {
                           'captureRules' => [
                             {
                               'from' => '*',
                               'to' => '<TWILIO_PHONE_NUMBER>'
                             }
                           ]
                         }
                       },
                       'intelligenceConfigurationIds' => [
                         '<INTELLIGENCE_CONFIGURATION_ID>'
                       ]
                     }
                   )

   puts configuration.status_url
   ```

   ```bash
   UPDATE_CONFIGURATION_REQUEST_OBJ=$(cat << EOF
   {
     "displayName": "my-conversations-configuration",
     "description": "Captures voice calls for Conversation Intelligence analysis",
     "conversationGroupingType": "GROUP_BY_PARTICIPANT_ADDRESSES",
     "memoryStoreId": "<MEMORY_STORE_ID>",
     "channelSettings": {
       "VOICE": {
         "captureRules": [
           {
             "from": "*",
             "to": "<TWILIO_PHONE_NUMBER>"
           }
         ]
       }
     },
     "intelligenceConfigurationIds": [
       "<INTELLIGENCE_CONFIGURATION_ID>"
     ]
   }
   EOF
   )
   curl -X PUT "https://conversations.twilio.com/v2/ControlPlane/Configurations/%3CCONVERSATION_CONFIGURATION_ID%3E" \
   --json "$UPDATE_CONFIGURATION_REQUEST_OBJ" \
   -u $TWILIO_API_KEY:$TWILIO_API_SECRET
   ```

   ```json
   {
     "related": {},
     "statusUrl": "https://www.example.com"
   }
   ```

## Next steps

* [Define rules for your intelligence configuration](/docs/conversations/intelligence/define-rules).
* Review the [Conversation Intelligence API reference](/docs/api/intelligence/v3) and the [Conversation Orchestrator API reference](/docs/api/conversations/v2).