Intelligence API (v3) - Operators endpoints

(information)

Legal information

Conversation Intelligence, including the APIs, may use artificial intelligence or machine learning technologies and is subject to the terms of the Predictive and Generative AI/ML Features Addendum. For more details on AI usage and data, see AI Nutrition Facts for Conversation Intelligence.

Conversation Intelligence is not PCI compliant or a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA or PCI.

Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

Overview

Define and manage language operators. Conversational Intelligence uses GenAI-powered language operators to transform conversation text into structured insights.

Language operators produce structured outputs and can be reused across multiple intelligence configurations. Language operators are executed automatically according to rules you define.

Use Twilio-authored language operators for common use cases (Sentiment, Summary, Next Best Response, and Script Adherence) or create custom language operators to meet your business needs.

Endpoints

/v3/ControlPlane/Operators

Create an Operator

/v3/ControlPlane/Operators

Retrieve a list of Operators

/v3/ControlPlane/Operators/{id}

Retrieve an Operator

/v3/ControlPlane/Operators/{id}

Update an Operator

/v3/ControlPlane/Operators/{id}

Delete an Operator

/v3/ControlPlane/Operators/{id}/Versions

Retrieve a list of Operator Versions

/v3/ControlPlane/Operators/{id}/Versions/{version}

Retrieve a specific Operator Version

Create an Operator

POST/v3/ControlPlane/Operators

Base url: https://intelligence.twilio.com (Twilio Intelligence API)

Create a custom language operator. You can define a reusable, programmable conversational analysis task tailored to your business needs.

Request

Security: Basic Auth

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

read-only

Optional

The unique identifier for the Language Operator. Assigned by Twilio (TTID).

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

displayNamestring

required

Display name of the Language Operator describing its purpose.

descriptionstring

Optional

Description of the Language Operator further explaining its purpose.

versioninteger

read-only

Optional

Numeric Operator version. Automatically incremented with each update on the resource, used to ensure integrity when updating the Operator.

authorenum<string>

read-only

Optional

The creator and maintainer of the Language Operator.

Available values:

SELF - Created and maintained by the customer (Custom Operator)
TWILIO - Created and maintained by Twilio (Twilio-Authored Operator)

Possible values:

SELFTWILIO

promptstring

required

The natural language instructions used by the operator to analyze the conversation.

Within the prompt, users can reference parameters using the {{parameters.[param_name]}} syntax. Parameter values are provided to the Operator by the Intelligence Configuration Rule at runtime.

Note: Prompts will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their prompts omitted from the API.

outputFormatenum<string>

required

The structure of the result returned by the Language Operator (specific to what the LLM returns, not the entirety of the Operator Result resource).

Available values:

TEXT: The Operator will return plaintext from the LLM.
JSON: the Operator will return a structured object with schema defined in output_schema
CLASSIFICATION: The Operator will return the determined classifier string.

Possible values:

TEXTJSONCLASSIFICATION

outputSchemaobject

Optional

Required for JSON output only. this will be set to a JSON Schema object describing the properties & data types of the response. Please see https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

Will include the following keywords:

type : Must be set to object
properties: An object containing the property names and their data types you would like the LLM to return

Additional details on JSON output formatting:

The root level type of a JSON schema must be set to object
The following property data types are supported : string, number, boolean, integer, object, array, anyOf
Definitions with $defs / $ref are supported
Max 100 object properties and 10 levels of nesting are supported
Max 1000 enum values across all enum properties are supported
Notable JSON Schema keywords not supported include:
- For strings: minLength, maxLength
- For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems
Structured Operator Results will be returned in the same order as the ordering of keys in the schema
In the event an Operator execution request is refused for safety reasons the Operator Result API response will include a new field called refusal to indicate that the LLM refused to fulfill the request
Twilio will automatically set additionalProperties to false and specify all provided fields as required (constraints of Structured Outputs). You don't need to pass these fields as part of your JSON schema. Twilio will automatically overwrite any user-provided values for these fields.

trainingExamplesarray[object]

Optional

An array of example input/output pairs used to illustrate the intended behavior of the Language Operator. These examples help guide the model's understanding of expected input–output relationships and improve consistency during evaluation and testing.

Note: Training examples will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their training examples omitted from the API.

Show trainingExamples properties

contextobject

Optional

Optionally specifies which contextual data sources (Memory, Knowledge) the operator can access during execution. Context objects will be passed in by the Intelligence Configuration Rule at runtime.

Note: this simply gives the LLM access to these context objects – ultimately the LLM will determine whether to actually call for context at runtime.

Show context properties

parametersobject

Optional

Defines the schema of the parameters that are provided when running the operator, including required and optional values that determine the operator's behavior. The values of the parameters themselves are passed in by the attached Intelligence Configuration.

Show parameters properties

Responses

201400429500

Language Operator resource created.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

read-only

Optional

The unique identifier for the Language Operator. Assigned by Twilio (TTID).

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

displayNamestring

Optional

Display name of the Language Operator describing its purpose.

descriptionstring

Optional

Description of the Language Operator further explaining its purpose.

versioninteger

read-only

Optional

Numeric Operator version. Automatically incremented with each update on the resource, used to ensure integrity when updating the Operator.

authorenum<string>

read-only

Optional

The creator and maintainer of the Language Operator.

Available values:

SELF - Created and maintained by the customer (Custom Operator)
TWILIO - Created and maintained by Twilio (Twilio-Authored Operator)

Possible values:

SELFTWILIO

promptstring

Optional

The natural language instructions used by the operator to analyze the conversation.

Within the prompt, users can reference parameters using the {{parameters.[param_name]}} syntax. Parameter values are provided to the Operator by the Intelligence Configuration Rule at runtime.

Note: Prompts will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their prompts omitted from the API.

outputFormatenum<string>

Optional

The structure of the result returned by the Language Operator (specific to what the LLM returns, not the entirety of the Operator Result resource).

Available values:

TEXT: The Operator will return plaintext from the LLM.
JSON: the Operator will return a structured object with schema defined in output_schema
CLASSIFICATION: The Operator will return the determined classifier string.

Possible values:

TEXTJSONCLASSIFICATION

outputSchemaobject

Optional

Required for JSON output only. this will be set to a JSON Schema object describing the properties & data types of the response. Please see https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

Will include the following keywords:

type : Must be set to object
properties: An object containing the property names and their data types you would like the LLM to return

Additional details on JSON output formatting:

The root level type of a JSON schema must be set to object
The following property data types are supported : string, number, boolean, integer, object, array, anyOf
Definitions with $defs / $ref are supported
Max 100 object properties and 10 levels of nesting are supported
Max 1000 enum values across all enum properties are supported
Notable JSON Schema keywords not supported include:
- For strings: minLength, maxLength
- For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems
Structured Operator Results will be returned in the same order as the ordering of keys in the schema
In the event an Operator execution request is refused for safety reasons the Operator Result API response will include a new field called refusal to indicate that the LLM refused to fulfill the request
Twilio will automatically set additionalProperties to false and specify all provided fields as required (constraints of Structured Outputs). You don't need to pass these fields as part of your JSON schema. Twilio will automatically overwrite any user-provided values for these fields.

trainingExamplesarray[object]

Optional

An array of example input/output pairs used to illustrate the intended behavior of the Language Operator. These examples help guide the model's understanding of expected input–output relationships and improve consistency during evaluation and testing.

Note: Training examples will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their training examples omitted from the API.

Show trainingExamples properties

contextobject

Optional

Optionally specifies which contextual data sources (Memory, Knowledge) the operator can access during execution. Context objects will be passed in by the Intelligence Configuration Rule at runtime.

Note: this simply gives the LLM access to these context objects – ultimately the LLM will determine whether to actually call for context at runtime.

Show context properties

parametersobject

Optional

Defines the schema of the parameters that are provided when running the operator, including required and optional values that determine the operator's behavior. The values of the parameters themselves are passed in by the attached Intelligence Configuration.

Show parameters properties

Bad request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Create an 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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createOperator() {
11  const operator = await client.intelligence.v3.operators.create({
12    displayName: "displayName",
13    prompt: "prompt",
14    outputFormat: "TEXT",
15  });
16
17  console.log(operator.id);
18}
19
20createOperator();

Response

1{
2  "id": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
3  "displayName": "Script Adherence",
4  "description": "Measuring whether the agent stuck to the script",
5  "version": 1,
6  "author": "SELF",
7  "prompt": "prompt",
8  "outputFormat": "JSON",
9  "outputSchema": {
10    "type": "object",
11    "properties": {
12      "score": {
13        "type": "integer"
14      },
15      "explanation": {
16        "type": "string"
17      }
18    },
19    "required": [
20      "score",
21      "explanation"
22    ],
23    "additionalProperties": false
24  },
25  "trainingExamples": [
26    {
27      "input": "This is an example sentence which qualifies the lead as HOT.",
28      "output": "{\"score\": 5, \"explanation\": \"The agent followed the script closely and addressed all key points effectively.\"}"
29    }
30  ],
31  "context": {
32    "memory": {
33      "enabled": true
34    },
35    "knowledge": {
36      "enabled": true
37    }
38  },
39  "parameters": {
40    "scale": {
41      "type": "integer",
42      "default": 5,
43      "description": "Maximum score for evaluating script adherence."
44    }
45  }
46}

Retrieve a list of Operators

GET/v3/ControlPlane/Operators

Base url: https://intelligence.twilio.com (Twilio Intelligence API)

Retrieve a list of Operators for the account, including those not attached to an Intelligence Configuration. This request returns both Twilio-authored and custom language operators.

Request

Security: Basic Auth

Query string

Property nameTypeRequiredPIIDescription

pageSizeinteger

Optional

The maximum number of resources to return

Default: 50Minimum: 1Maximum: 1000

pageTokenstring

Optional

Token for pagination

Responses

200429500

List of available Language Operators

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

itemsarray[object]

Optional

List of available Language Operators

Show items properties

Property nameTypeRequiredPIIDescriptionChild properties

idstring

read-only

Optional

The unique identifier for the Language Operator. Assigned by Twilio (TTID).

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

displayNamestring

Optional

Display name of the Language Operator describing its purpose.

descriptionstring

Optional

Description of the Language Operator further explaining its purpose.

versioninteger

read-only

Optional

Numeric Operator version. Automatically incremented with each update on the resource, used to ensure integrity when updating the Operator.

authorenum<string>

read-only

Optional

The creator and maintainer of the Language Operator.

Available values:

SELF - Created and maintained by the customer (Custom Operator)
TWILIO - Created and maintained by Twilio (Twilio-Authored Operator)

Possible values:

SELFTWILIO

promptstring

Optional

The natural language instructions used by the operator to analyze the conversation.

Within the prompt, users can reference parameters using the {{parameters.[param_name]}} syntax. Parameter values are provided to the Operator by the Intelligence Configuration Rule at runtime.

Note: Prompts will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their prompts omitted from the API.

outputFormatenum<string>

Optional

The structure of the result returned by the Language Operator (specific to what the LLM returns, not the entirety of the Operator Result resource).

Available values:

TEXT: The Operator will return plaintext from the LLM.
JSON: the Operator will return a structured object with schema defined in output_schema
CLASSIFICATION: The Operator will return the determined classifier string.

Possible values:

TEXTJSONCLASSIFICATION

outputSchemaobject

Optional

Required for JSON output only. this will be set to a JSON Schema object describing the properties & data types of the response. Please see https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

Will include the following keywords:

type : Must be set to object
properties: An object containing the property names and their data types you would like the LLM to return

Additional details on JSON output formatting:

The root level type of a JSON schema must be set to object
The following property data types are supported : string, number, boolean, integer, object, array, anyOf
Definitions with $defs / $ref are supported
Max 100 object properties and 10 levels of nesting are supported
Max 1000 enum values across all enum properties are supported
Notable JSON Schema keywords not supported include:
- For strings: minLength, maxLength
- For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems
Structured Operator Results will be returned in the same order as the ordering of keys in the schema
In the event an Operator execution request is refused for safety reasons the Operator Result API response will include a new field called refusal to indicate that the LLM refused to fulfill the request
Twilio will automatically set additionalProperties to false and specify all provided fields as required (constraints of Structured Outputs). You don't need to pass these fields as part of your JSON schema. Twilio will automatically overwrite any user-provided values for these fields.

trainingExamplesarray[object]

Optional

An array of example input/output pairs used to illustrate the intended behavior of the Language Operator. These examples help guide the model's understanding of expected input–output relationships and improve consistency during evaluation and testing.

Note: Training examples will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their training examples omitted from the API.

Show trainingExamples properties

contextobject

Optional

Optionally specifies which contextual data sources (Memory, Knowledge) the operator can access during execution. Context objects will be passed in by the Intelligence Configuration Rule at runtime.

Note: this simply gives the LLM access to these context objects – ultimately the LLM will determine whether to actually call for context at runtime.

Show context properties

parametersobject

Optional

Defines the schema of the parameters that are provided when running the operator, including required and optional values that determine the operator's behavior. The values of the parameters themselves are passed in by the attached Intelligence Configuration.

Show parameters properties

metaobject

Optional

Show meta properties

{
  "items": [
    {
      "id": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
      "displayName": "Script Adherence",
      "description": "Measuring whether the agent stuck to the script",
      "version": 1,
      "author": "SELF",
      "prompt": "Your job is to determine if a contact center agent sticks to the script. Fetch the script from Knowledge using the Knowledge tool. Rate the interaction from 0-{{parameters.scale}}.",
      "outputFormat": "JSON",
      "outputSchema": {
        "type": "object",
        "properties": {
          "score": {
            "type": "integer"
          },
          "explanation": {
            "type": "string"
          }
        },
        "required": [
          "score",
          "explanation"
        ],
        "additionalProperties": false
      },
      "trainingExamples": [
        {
          "input": "This is an example sentence which qualifies the lead as HOT.",
          "output": "{\"score\": 5, \"explanation\": \"The agent followed the script closely and addressed all key points effectively.\"}"
        }
      ],
      "context": {
        "memory": {
          "enabled": true
        },
        "knowledge": {
          "enabled": true
        }
      },
      "parameters": {
        "scale": {
          "type": "integer",
          "default": 5,
          "description": "Maximum score for evaluating script adherence."
        }
      }
    },
    {
      "id": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt9c",
      "displayName": "Sentiment Analysis",
      "description": "Analyze customer sentiment throughout the conversation",
      "version": 2,
      "author": "TWILIO",
      "outputFormat": "CLASSIFICATION",
      "context": {
        "memory": {
          "enabled": false
        },
        "knowledge": {
          "enabled": false
        }
      },
      "parameters": {}
    }
  ],
  "meta": {
    "key": "items",
    "pageSize": 2,
    "nextToken": "next_page_token_example"
  }
}

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Retrieve a list of Operators

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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listOperators() {
11  const operators = await client.intelligence.v3.operators.list({ limit: 20 });
12
13  operators.forEach((o) => console.log(o.id));
14}
15
16listOperators();

Response

1{
2  "items": [
3    {
4      "id": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
5      "displayName": "Script Adherence",
6      "description": "Measuring whether the agent stuck to the script",
7      "version": 1,
8      "author": "SELF",
9      "prompt": "Your job is to determine if a contact center agent sticks to the script. Fetch the script from Knowledge using the Knowledge tool. Rate the interaction from 0-{{parameters.scale}}.",
10      "outputFormat": "JSON",
11      "outputSchema": {
12        "type": "object",
13        "properties": {
14          "score": {
15            "type": "integer"
16          },
17          "explanation": {
18            "type": "string"
19          }
20        },
21        "required": [
22          "score",
23          "explanation"
24        ],
25        "additionalProperties": false
26      },
27      "trainingExamples": [
28        {
29          "input": "This is an example sentence which qualifies the lead as HOT.",
30          "output": "{\"score\": 5, \"explanation\": \"The agent followed the script closely and addressed all key points effectively.\"}"
31        }
32      ],
33      "context": {
34        "memory": {
35          "enabled": true
36        },
37        "knowledge": {
38          "enabled": true
39        }
40      },
41      "parameters": {
42        "scale": {
43          "type": "integer",
44          "default": 5,
45          "description": "Maximum score for evaluating script adherence."
46        }
47      }
48    },
49    {
50      "id": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt9c",
51      "displayName": "Sentiment Analysis",
52      "description": "Analyze customer sentiment throughout the conversation",
53      "version": 2,
54      "author": "TWILIO",
55      "outputFormat": "CLASSIFICATION",
56      "context": {
57        "memory": {
58          "enabled": false
59        },
60        "knowledge": {
61          "enabled": false
62        }
63      },
64      "parameters": {}
65    }
66  ],
67  "meta": {
68    "key": "items",
69    "pageSize": 2,
70    "nextToken": "next_page_token_example"
71  }
72}

Retrieve an Operator

GET/v3/ControlPlane/Operators/{id}

Base url: https://intelligence.twilio.com (Twilio Intelligence API)

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

idstring

requiredread-only

The unique identifier (TTID) of the Language Operator.

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

Responses

200404429500

A Language Operator resource.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

read-only

Optional

The unique identifier for the Language Operator. Assigned by Twilio (TTID).

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

displayNamestring

Optional

Display name of the Language Operator describing its purpose.

descriptionstring

Optional

Description of the Language Operator further explaining its purpose.

versioninteger

read-only

Optional

Numeric Operator version. Automatically incremented with each update on the resource, used to ensure integrity when updating the Operator.

authorenum<string>

read-only

Optional

The creator and maintainer of the Language Operator.

Available values:

SELF - Created and maintained by the customer (Custom Operator)
TWILIO - Created and maintained by Twilio (Twilio-Authored Operator)

Possible values:

SELFTWILIO

promptstring

Optional

The natural language instructions used by the operator to analyze the conversation.

Within the prompt, users can reference parameters using the {{parameters.[param_name]}} syntax. Parameter values are provided to the Operator by the Intelligence Configuration Rule at runtime.

Note: Prompts will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their prompts omitted from the API.

outputFormatenum<string>

Optional

The structure of the result returned by the Language Operator (specific to what the LLM returns, not the entirety of the Operator Result resource).

Available values:

TEXT: The Operator will return plaintext from the LLM.
JSON: the Operator will return a structured object with schema defined in output_schema
CLASSIFICATION: The Operator will return the determined classifier string.

Possible values:

TEXTJSONCLASSIFICATION

outputSchemaobject

Optional

Required for JSON output only. this will be set to a JSON Schema object describing the properties & data types of the response. Please see https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

Will include the following keywords:

type : Must be set to object
properties: An object containing the property names and their data types you would like the LLM to return

Additional details on JSON output formatting:

The root level type of a JSON schema must be set to object
The following property data types are supported : string, number, boolean, integer, object, array, anyOf
Definitions with $defs / $ref are supported
Max 100 object properties and 10 levels of nesting are supported
Max 1000 enum values across all enum properties are supported
Notable JSON Schema keywords not supported include:
- For strings: minLength, maxLength
- For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems
Structured Operator Results will be returned in the same order as the ordering of keys in the schema
In the event an Operator execution request is refused for safety reasons the Operator Result API response will include a new field called refusal to indicate that the LLM refused to fulfill the request
Twilio will automatically set additionalProperties to false and specify all provided fields as required (constraints of Structured Outputs). You don't need to pass these fields as part of your JSON schema. Twilio will automatically overwrite any user-provided values for these fields.

trainingExamplesarray[object]

Optional

An array of example input/output pairs used to illustrate the intended behavior of the Language Operator. These examples help guide the model's understanding of expected input–output relationships and improve consistency during evaluation and testing.

Note: Training examples will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their training examples omitted from the API.

Show trainingExamples properties

contextobject

Optional

Optionally specifies which contextual data sources (Memory, Knowledge) the operator can access during execution. Context objects will be passed in by the Intelligence Configuration Rule at runtime.

Note: this simply gives the LLM access to these context objects – ultimately the LLM will determine whether to actually call for context at runtime.

Show context properties

parametersobject

Optional

Defines the schema of the parameters that are provided when running the operator, including required and optional values that determine the operator's behavior. The values of the parameters themselves are passed in by the attached Intelligence Configuration.

Show parameters properties

Resource not found

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Retrieve an 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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchOperator() {
11  const operator = await client.intelligence.v3
12    .operators("intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5")
13    .fetch();
14
15  console.log(operator.id);
16}
17
18fetchOperator();

Response

1{
2  "id": "intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5",
3  "displayName": "Script Adherence",
4  "description": "Measuring whether the agent stuck to the script",
5  "version": 1,
6  "author": "SELF",
7  "prompt": "Your job is to determine if a contact center agent sticks to the script. Fetch the script from Knowledge using the Knowledge tool. Rate the interaction from 0-{{parameters.scale}}.",
8  "outputFormat": "JSON",
9  "outputSchema": {
10    "type": "object",
11    "properties": {
12      "score": {
13        "type": "integer"
14      },
15      "explanation": {
16        "type": "string"
17      }
18    },
19    "required": [
20      "score",
21      "explanation"
22    ],
23    "additionalProperties": false
24  },
25  "trainingExamples": [
26    {
27      "input": "This is an example sentence which qualifies the lead as HOT.",
28      "output": "{\"score\": 5, \"explanation\": \"The agent followed the script closely and addressed all key points effectively.\"}"
29    }
30  ],
31  "context": {
32    "memory": {
33      "enabled": true
34    },
35    "knowledge": {
36      "enabled": true
37    }
38  },
39  "parameters": {
40    "scale": {
41      "type": "integer",
42      "default": 5,
43      "description": "Maximum score for evaluating script adherence."
44    }
45  }
46}

Update an Operator

PUT/v3/ControlPlane/Operators/{id}

Base url: https://intelligence.twilio.com (Twilio Intelligence API)

Request

Security: Basic Auth

Headers

Property nameTypeRequiredPIIDescription

if-Matchstring

Optional

Current ETag/version required for conditional update

Path parameters

Property nameTypeRequiredPIIDescription

idstring

requiredread-only

The unique identifier (TTID) of the Language Operator.

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

read-only

Optional

The unique identifier for the Language Operator. Assigned by Twilio (TTID).

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

displayNamestring

required

Display name of the Language Operator describing its purpose.

descriptionstring

Optional

Description of the Language Operator further explaining its purpose.

versioninteger

read-only

Optional

Numeric Operator version. Automatically incremented with each update on the resource, used to ensure integrity when updating the Operator.

authorenum<string>

read-only

Optional

The creator and maintainer of the Language Operator.

Available values:

SELF - Created and maintained by the customer (Custom Operator)
TWILIO - Created and maintained by Twilio (Twilio-Authored Operator)

Possible values:

SELFTWILIO

promptstring

required

The natural language instructions used by the operator to analyze the conversation.

Within the prompt, users can reference parameters using the {{parameters.[param_name]}} syntax. Parameter values are provided to the Operator by the Intelligence Configuration Rule at runtime.

Note: Prompts will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their prompts omitted from the API.

outputFormatenum<string>

required

The structure of the result returned by the Language Operator (specific to what the LLM returns, not the entirety of the Operator Result resource).

Available values:

TEXT: The Operator will return plaintext from the LLM.
JSON: the Operator will return a structured object with schema defined in output_schema
CLASSIFICATION: The Operator will return the determined classifier string.

Possible values:

TEXTJSONCLASSIFICATION

outputSchemaobject

Optional

Required for JSON output only. this will be set to a JSON Schema object describing the properties & data types of the response. Please see https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

Will include the following keywords:

type : Must be set to object
properties: An object containing the property names and their data types you would like the LLM to return

Additional details on JSON output formatting:

The root level type of a JSON schema must be set to object
The following property data types are supported : string, number, boolean, integer, object, array, anyOf
Definitions with $defs / $ref are supported
Max 100 object properties and 10 levels of nesting are supported
Max 1000 enum values across all enum properties are supported
Notable JSON Schema keywords not supported include:
- For strings: minLength, maxLength
- For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems
Structured Operator Results will be returned in the same order as the ordering of keys in the schema
In the event an Operator execution request is refused for safety reasons the Operator Result API response will include a new field called refusal to indicate that the LLM refused to fulfill the request
Twilio will automatically set additionalProperties to false and specify all provided fields as required (constraints of Structured Outputs). You don't need to pass these fields as part of your JSON schema. Twilio will automatically overwrite any user-provided values for these fields.

trainingExamplesarray[object]

Optional

An array of example input/output pairs used to illustrate the intended behavior of the Language Operator. These examples help guide the model's understanding of expected input–output relationships and improve consistency during evaluation and testing.

Note: Training examples will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their training examples omitted from the API.

Show trainingExamples properties

contextobject

Optional

Optionally specifies which contextual data sources (Memory, Knowledge) the operator can access during execution. Context objects will be passed in by the Intelligence Configuration Rule at runtime.

Note: this simply gives the LLM access to these context objects – ultimately the LLM will determine whether to actually call for context at runtime.

Show context properties

parametersobject

Optional

Defines the schema of the parameters that are provided when running the operator, including required and optional values that determine the operator's behavior. The values of the parameters themselves are passed in by the attached Intelligence Configuration.

Show parameters properties

Responses

200400404412429500

Updated Language Operator resource.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

read-only

Optional

The unique identifier for the Language Operator. Assigned by Twilio (TTID).

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

displayNamestring

Optional

Display name of the Language Operator describing its purpose.

descriptionstring

Optional

Description of the Language Operator further explaining its purpose.

versioninteger

read-only

Optional

Numeric Operator version. Automatically incremented with each update on the resource, used to ensure integrity when updating the Operator.

authorenum<string>

read-only

Optional

The creator and maintainer of the Language Operator.

Available values:

SELF - Created and maintained by the customer (Custom Operator)
TWILIO - Created and maintained by Twilio (Twilio-Authored Operator)

Possible values:

SELFTWILIO

promptstring

Optional

The natural language instructions used by the operator to analyze the conversation.

Within the prompt, users can reference parameters using the {{parameters.[param_name]}} syntax. Parameter values are provided to the Operator by the Intelligence Configuration Rule at runtime.

Note: Prompts will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their prompts omitted from the API.

outputFormatenum<string>

Optional

The structure of the result returned by the Language Operator (specific to what the LLM returns, not the entirety of the Operator Result resource).

Available values:

TEXT: The Operator will return plaintext from the LLM.
JSON: the Operator will return a structured object with schema defined in output_schema
CLASSIFICATION: The Operator will return the determined classifier string.

Possible values:

TEXTJSONCLASSIFICATION

outputSchemaobject

Optional

Required for JSON output only. this will be set to a JSON Schema object describing the properties & data types of the response. Please see https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

Will include the following keywords:

type : Must be set to object
properties: An object containing the property names and their data types you would like the LLM to return

Additional details on JSON output formatting:

The root level type of a JSON schema must be set to object
The following property data types are supported : string, number, boolean, integer, object, array, anyOf
Definitions with $defs / $ref are supported
Max 100 object properties and 10 levels of nesting are supported
Max 1000 enum values across all enum properties are supported
Notable JSON Schema keywords not supported include:
- For strings: minLength, maxLength
- For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems
Structured Operator Results will be returned in the same order as the ordering of keys in the schema
In the event an Operator execution request is refused for safety reasons the Operator Result API response will include a new field called refusal to indicate that the LLM refused to fulfill the request
Twilio will automatically set additionalProperties to false and specify all provided fields as required (constraints of Structured Outputs). You don't need to pass these fields as part of your JSON schema. Twilio will automatically overwrite any user-provided values for these fields.

trainingExamplesarray[object]

Optional

An array of example input/output pairs used to illustrate the intended behavior of the Language Operator. These examples help guide the model's understanding of expected input–output relationships and improve consistency during evaluation and testing.

Note: Training examples will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their training examples omitted from the API.

Show trainingExamples properties

contextobject

Optional

Optionally specifies which contextual data sources (Memory, Knowledge) the operator can access during execution. Context objects will be passed in by the Intelligence Configuration Rule at runtime.

Note: this simply gives the LLM access to these context objects – ultimately the LLM will determine whether to actually call for context at runtime.

Show context properties

parametersobject

Optional

Defines the schema of the parameters that are provided when running the operator, including required and optional values that determine the operator's behavior. The values of the parameters themselves are passed in by the attached Intelligence Configuration.

Show parameters properties

Bad request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Resource not found

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Precondition failed (e.g., ETag mismatch)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Update an 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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function updateOperator() {
11  const operator = await client.intelligence.v3
12    .operators("intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5")
13    .update({
14      displayName: "displayName",
15      prompt: "prompt",
16      outputFormat: "TEXT",
17    });
18
19  console.log(operator.id);
20}
21
22updateOperator();

Response

1{
2  "id": "intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5",
3  "displayName": "Script Adherence",
4  "description": "Measuring whether the agent stuck to the script",
5  "version": 1,
6  "author": "SELF",
7  "prompt": "prompt",
8  "outputFormat": "JSON",
9  "outputSchema": {
10    "type": "object",
11    "properties": {
12      "score": {
13        "type": "integer"
14      },
15      "explanation": {
16        "type": "string"
17      }
18    },
19    "required": [
20      "score",
21      "explanation"
22    ],
23    "additionalProperties": false
24  },
25  "trainingExamples": [
26    {
27      "input": "This is an example sentence which qualifies the lead as HOT.",
28      "output": "{\"score\": 5, \"explanation\": \"The agent followed the script closely and addressed all key points effectively.\"}"
29    }
30  ],
31  "context": {
32    "memory": {
33      "enabled": true
34    },
35    "knowledge": {
36      "enabled": true
37    }
38  },
39  "parameters": {
40    "scale": {
41      "type": "integer",
42      "default": 5,
43      "description": "Maximum score for evaluating script adherence."
44    }
45  }
46}

Delete an Operator

DELETE/v3/ControlPlane/Operators/{id}

Base url: https://intelligence.twilio.com (Twilio Intelligence API)

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

idstring

requiredread-only

The unique identifier (TTID) of the Language Operator.

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

Responses

204404429500

Language Operator deleted

Resource not found

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Delete an 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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function deleteOperator() {
11  await client.intelligence.v3
12    .operators("intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5")
13    .remove();
14}
15
16deleteOperator();

Retrieve a list of Operator Versions

GET/v3/ControlPlane/Operators/{id}/Versions

Base url: https://intelligence.twilio.com (Twilio Intelligence API)

Retrieve a paginated list of all versions for a given Language Operator.

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

idstring

requiredread-only

The unique identifier (TTID) of the Language Operator.

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

Query string

Property nameTypeRequiredPIIDescription

pageSizeinteger

Optional

The maximum number of resources to return

Default: 50Minimum: 1Maximum: 1000

pageTokenstring

Optional

Token for pagination

Responses

200404429500

A paginated list of Operator versions.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

itemsarray[object]

Optional

List of Operator versions.

Show items properties

metaobject

Optional

Show meta properties

Resource not found

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Retrieve a list of Operator Versions

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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function listOperatorVersions() {
11  const versions = await client.intelligence.v3
12    .versions("intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5")
13    .list({ limit: 20 });
14
15  versions.forEach((v) => console.log(v.version));
16}
17
18listOperatorVersions();

Response

1{
2  "items": [
3    {
4      "version": 5,
5      "status": "PREVIEW",
6      "dateCreated": "2026-02-10T14:00:00Z"
7    },
8    {
9      "version": 4,
10      "status": "ACTIVE",
11      "dateCreated": "2026-01-15T10:45:30Z"
12    },
13    {
14      "version": 3,
15      "status": "DEPRECATED",
16      "dateDeprecated": "2026-01-10T00:00:00Z",
17      "retirementDate": "2026-04-10T00:00:00Z",
18      "dateCreated": "2025-11-01T08:00:00Z"
19    },
20    {
21      "version": 2,
22      "status": "RETIRED",
23      "dateDeprecated": "2025-09-01T00:00:00Z",
24      "dateRetired": "2025-12-01T00:00:00Z",
25      "dateCreated": "2025-06-15T12:00:00Z"
26    }
27  ],
28  "meta": {
29    "key": "items",
30    "pageSize": 4
31  }
32}

Retrieve a specific Operator Version

GET/v3/ControlPlane/Operators/{id}/Versions/{version}

Base url: https://intelligence.twilio.com (Twilio Intelligence API)

Request

Security: Basic Auth

Path parameters

Property nameTypeRequiredPIIDescription

idstring

requiredread-only

The unique identifier (TTID) of the Language Operator.

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

versioninteger

required

The numeric version number of the Language Operator.

Responses

200404429500

A specific Language Operator version.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

idstring

read-only

Optional

The unique identifier for the Language Operator. Assigned by Twilio (TTID).

Example: intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5Pattern: ^intelligence_operator_[0-7][0-9a-z]{25}$

displayNamestring

Optional

Display name of the Language Operator describing its purpose.

descriptionstring

Optional

Description of the Language Operator further explaining its purpose.

versioninteger

read-only

Optional

Numeric Operator version. Automatically incremented with each update on the resource, used to ensure integrity when updating the Operator.

authorenum<string>

read-only

Optional

The creator and maintainer of the Language Operator.

Available values:

SELF - Created and maintained by the customer (Custom Operator)
TWILIO - Created and maintained by Twilio (Twilio-Authored Operator)

Possible values:

SELFTWILIO

promptstring

Optional

The natural language instructions used by the operator to analyze the conversation.

Within the prompt, users can reference parameters using the {{parameters.[param_name]}} syntax. Parameter values are provided to the Operator by the Intelligence Configuration Rule at runtime.

Note: Prompts will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their prompts omitted from the API.

outputFormatenum<string>

Optional

The structure of the result returned by the Language Operator (specific to what the LLM returns, not the entirety of the Operator Result resource).

Available values:

TEXT: The Operator will return plaintext from the LLM.
JSON: the Operator will return a structured object with schema defined in output_schema
CLASSIFICATION: The Operator will return the determined classifier string.

Possible values:

TEXTJSONCLASSIFICATION

outputSchemaobject

Optional

Required for JSON output only. this will be set to a JSON Schema object describing the properties & data types of the response. Please see https://platform.openai.com/docs/guides/structured-outputs#supported-schemas

Will include the following keywords:

type : Must be set to object
properties: An object containing the property names and their data types you would like the LLM to return

Additional details on JSON output formatting:

The root level type of a JSON schema must be set to object
The following property data types are supported : string, number, boolean, integer, object, array, anyOf
Definitions with $defs / $ref are supported
Max 100 object properties and 10 levels of nesting are supported
Max 1000 enum values across all enum properties are supported
Notable JSON Schema keywords not supported include:
- For strings: minLength, maxLength
- For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
- For arrays: unevaluatedItems, contains, minContains, maxContains, uniqueItems
Structured Operator Results will be returned in the same order as the ordering of keys in the schema
In the event an Operator execution request is refused for safety reasons the Operator Result API response will include a new field called refusal to indicate that the LLM refused to fulfill the request
Twilio will automatically set additionalProperties to false and specify all provided fields as required (constraints of Structured Outputs). You don't need to pass these fields as part of your JSON schema. Twilio will automatically overwrite any user-provided values for these fields.

trainingExamplesarray[object]

Optional

An array of example input/output pairs used to illustrate the intended behavior of the Language Operator. These examples help guide the model's understanding of expected input–output relationships and improve consistency during evaluation and testing.

Note: Training examples will only be exposed for Custom Operators (author = SELF). Twilio-authored Operators (author = TWILIO) will have their training examples omitted from the API.

Show trainingExamples properties

contextobject

Optional

Optionally specifies which contextual data sources (Memory, Knowledge) the operator can access during execution. Context objects will be passed in by the Intelligence Configuration Rule at runtime.

Note: this simply gives the LLM access to these context objects – ultimately the LLM will determine whether to actually call for context at runtime.

Show context properties

parametersobject

Optional

Defines the schema of the parameters that are provided when running the operator, including required and optional values that determine the operator's behavior. The values of the parameters themselves are passed in by the attached Intelligence Configuration.

Show parameters properties

statusenum<string>

Optional

The lifecycle status of an Operator version.

Available values:

PREVIEW: Available but restricted to internal/testing visibility. Normal execution.
ACTIVE: Available for normal use.
DEPRECATED: Still executes normally, but a Warn event is emitted via the Watch product lifecycle system. Customers should migrate to a newer version.
RETIRED: Hard failure on execution. An Error is logged in Watch. Customers must manually update their Intelligence Configuration to a valid version.

Possible values:

PREVIEWACTIVEDEPRECATEDRETIRED

dateCreatedstring<date-time>

Optional

Timestamp of when this version was created.

Resource not found

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Retrieve a specific Operator Version

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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchOperatorVersion() {
11  const version = await client.intelligence.v3
12    .versions("intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5", 42)
13    .fetch();
14
15  console.log(version.id);
16}
17
18fetchOperatorVersion();

Response

1{
2  "id": "intelligence_operator_01k6fc25s7epm9qtk8rszbv3q5",
3  "version": 42,
4  "status": "ACTIVE",
5  "displayName": "Sentiment Analysis",
6  "description": "Analyzes conversation sentiment",
7  "author": "TWILIO",
8  "outputFormat": "JSON",
9  "outputSchema": {},
10  "context": {},
11  "parameters": {},
12  "trainingExamples": [],
13  "dateCreated": "2026-01-15T10:45:30Z"
14}