Create custom language operators

Custom language operators let you define and create your own language understanding tasks and perform conversational analysis that is:

• Unique to your business, tailored to your domain, terminology, and workflows
• Configurable, giving you full control over instructions and expected output
• Flexible, supporting both real-time and post-conversation use cases

You define what you want to extract using freeform instructions (prompt) and can optionally add context (Conversation Memory, Enterprise Knowledge) for more personalized and grounded results. The outcome is returned as a language operator result you can consume and activate in downstream systems.

The following are examples of custom language operators that augment human agents or trigger automation:

• Personalized greeting recommendations based on customer history and business context
• Real-time compliance checks to detect required disclosures or prohibited language
• Live objection handling using common objections unique to your products and services
• Custom lead qualification based on your proprietary scoring criteria
• Tailored summaries that are specific to your business and personalized to the customer

A custom language operator consists of the following components:

• Prompt
• Output format
• Parameters
• (Optional) Context capabilities

A prompt provides instructions for analyzing incoming conversations. You describe in natural language the task you want the language operator to perform with your conversations.

For guidance on how to write effective prompts, see Prompting best practices.

For examples, see Example use cases.

You can specify the desired output format (outputFormat) for your custom language operator:

• TEXT: Plain text (default)
• JSON: Structured JSON object
• CLASSIFICATION: Classifier string

When you provide a JSON schema, the language operator formats its output according to that schema. This helps ensure consistent and predictable results that are easier to parse and integrate with other systems.

Learn more about Structuring JSON schema.

Using parameters, custom language operators can accept dynamic inputs at runtime. Parameters make language operators configurable, reusable across intelligence configurations, and able to adapt their behavior based on the context of each conversation.

You must reference parameters directly in the language operator prompt using special syntax that substitutes the parameter values at runtime.

You define and use parameters in two places:

• Custom language operator: Where you define the parameter schema
• Intelligence configuration rule: Where you specify parameter values set at runtime

Together, these control how the language operator behaves during execution. When a rule triggers, the following occurs:

1. Conversation Intelligence loads the language operator and its parameter schema.
2. The intelligence configuration rule supplies parameter values.
3. Default values are applied where values are not provided.
4. The knowledge source content is resolved (if applicable).
5. The prompt is rendered with parameter substitutions.
6. The language operator executes using the combined prompt, parameters, and context.

Learn more about Defining parameters.

You can optionally enable context capabilities for your custom language operator. When enabled, the language operator can access contextual data during execution to:

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

You enable context capabilities using two on/off toggles: one for Conversation Memory and one for Enterprise Knowledge.

When a language operator has Conversation Memory or Enterprise Knowledge enabled and becomes context-aware, it can query that data during execution. The language operator determines at runtime whether to use the provided context based on its relevance to the prompt and conversation transcript.

Learn more about business and customer data for language operators.

For context to work:

• The language operator must declare support for Conversation Memory or Enterprise Knowledge.
• The intelligence configuration rule must provide the context resources, such as customer profiles or knowledge bases.

Learn more about how language operators use knowledge search and memory tools.

You can provide training examples to help improve language operator results by contextualizing, clarifying, signaling intent, and adding specificity to your request.

Training examples consist of a sample input and the corresponding expected output:

• Input: Provide sample communications for the language operator to use as an example conversation
• Output: Provide what you would expect the language operator result to be for the given input

The language operator uses these examples to better understand the task you are asking it to perform.

To ensure the best possible results from your custom language operators, follow these prompting best practices:

• Specify the task clearly and use explicit instructions:

  Clearly state what you want the model to do, and specify the style or format of the response. This reduces ambiguity and ensures that the model provides the desired output.

  Example: Instead of asking "Tell me about this customer", ask:

  Copy code block

  Provide a concise summary of the customer's needs with regard to moving and storage.

• Include context:

  Providing relevant context can help the model generate more relevant and coherent responses, especially for complex queries.

  Example:

  Copy code block

  Given our company's emphasis on recurring revenue over one-time purchases, how strong a lead is this prospect?

• Ask specific questions and limit open-ended inputs:

  Formulate precise questions to elicit clear and focused responses. Narrow the scope to avoid broad or vague answers.

  Example:

  Copy code block

  What are three key factors this customer is looking for in an insurance provider?

• Break down complex tasks:

  For complex or multi-step tasks, consider breaking them into simpler, sequential prompts.

  Example:

  Copy code block

  - Step 1: List the key moments in this conversation. - Step 2: Compare these with the following script.

• Use examples to guide format:

  Offering a sample response can set expectations for the type and style of answer you anticipate.

  Example:

  Copy code block

  Describe the key features the customer wants in a car. For instance, 'The customer is looking for a sports car with low mileage and a good infotainment system'.

  If you have multiple examples, consider using Training examples to provide these in a structured way.

• Provide constraints when necessary:

  Introducing constraints like word limits or particular formats can help control the output.

  Example:

  Copy code block

  Summarize the conversation in 100 words or fewer.

Knowledge search and memory tools give language operators access to Enterprise Knowledge and Conversation Memory, enabling more accurate and personalized responses.

• Knowledge search tool: Performs semantic search over knowledge bases to retrieve documentation, policies, and product information.
• Memory tools: Provides access to historical context and user attributes for personalized responses. Memory tools include:
  • Observational memory search tool: Searches observations automatically extracted from past conversations with the customer.
  • Trait memory fetch tool: Fetches attributes explicitly set about a customer, such as name, preferences, and VIP status.

For a language operator to use these tools, set the following in the language operator configuration and intelligence configuration rule:

Note: Conversation Memory doesn't require additional configuration in the intelligence configuration rule because the system automatically handles user identification.

When knowledge search or memory tools are enabled in your operator and intelligence configuration, the language operator can invoke them during execution. While leaving this unguided works for some language operators, explicitly referencing the tool in the prompt can improve results.

To help the language operator correctly identify and use these tools, follow these best practices when writing your prompt:

• Use the exact name: Always refer to the tool as the "knowledge search tool", "observational memory search tool", or "trait memory fetch tool" in the prompt. This ensures consistency with the tool's description and helps the language operator recognize it.

• Structure your instruction: Use clear sections, such as "Goal" and "Steps".

  • If the language operator should always use the tool, reference it in both the Goal and Steps sections.
  • If the language operator should conditionally use the tool, clearly define the conditions in the Steps section.

• Don't reference the knowledge base IDs in the prompt: The language operator doesn't understand them and might hallucinate. The language operator interacts with the knowledge search tool only using query strings.

Use JSON schema to define the expected output structure when using structured JSON as the output format for your custom language operator.

A JSON schema for custom language operator results must be an object type. At minimum, a valid schema must include the following keywords:

• type: Must be set to object
• properties: An object defining the property names and their data types that the language operator should return

The following example shows a valid JSON schema for a tailored summarization use case:

1
{
2
    "type": "object",
3
    "properties": {
4
        "budget": { "type": "string" },
5
        "authority": { "type": "string" },
6
        "need": { "type": "string" },
7
        "timeline": { "type": "string" }
8
    }
9
}

When creating a JSON schema for your custom language operator, keep the following guidelines in mind:

• When you choose outputFormat: JSON, you must provide a matching output schema (outputSchema), and the language operator's structured output will conform to this schema. See Troubleshooting: Response schema validation for failures related to response schema.
• 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, enum, anyOf
• Each output response has a maximum limit of 8,800 characters. To keep your output responses within this limit, follow these guidelines when designing the output schema:
  • Flatten your JSON structure: Avoid overly nested JSON objects. Each nesting level adds extra characters when producing the JSON structure.
  • Use efficient data types: Use Boolean (true/false) or integer (1/0) values for classifications.
  • Abbreviate JSON property keys: Use concise, common abbreviations. For example, use cust_id instead of customer_identification_number.
  • Minimize redundancy: Only include fields that are absolutely necessary for your downstream processes.
• Max 100 object properties and 5 levels of nesting are supported.
• Max 500 enum values across all enum properties are supported.
• Notable JSON Schema keywords not supported include:
  • For strings: minLength, maxLength, pattern, format
  • For numbers: minimum, maximum, multipleOf
  • For objects: patternProperties, unevaluatedProperties, propertyNames, minProperties, maxProperties
  • For arrays: unevaluatedItems, contains, minContains, maxContains, minItems, maxItems, uniqueItems
• Structured language operator results will be returned in the same order as the keys in the schema.
• If the language operator refuses a language operator execution request for safety reasons, the language operator result will include a refusal field.
• 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.

For additional JSON result schema examples, see Example use cases.

To review all available JSON schema syntax, see the JSON schema reference. You can also use JSON schema generators, such as transform.tools.

When creating a custom language operator, you define a parameter schema that describes:

• What parameters are available (parameter names)
• Parameter types
• Whether parameters are required
• Parameter default values (if applicable)
• How to reference parameters inside your prompt

Each parameter includes:

• type: The data type. Supported types are string, integer, number, boolean, and knowledge_base_and_source_ids.
• default: (Optional) A fallback value if the intelligence configuration doesn't provide one
• required: Whether the parameter must be provided at execution time
• description: A human-readable explanation of the parameter's purpose

The knowledge_base_and_source_ids parameter type allows a custom language operator to directly reference a specific knowledge source from a knowledge base. Use this for tasks like:

• Product-specific troubleshooting
• Policy-aware reasoning
• FAQ-informed agent guidance

The intelligence configuration rule passes the parameter value as a colon-separated string formatted:

<knowledge_base_id>:<knowledge_source_id>

• This parameter type only supports plain text knowledge sources.
• This parameter type doesn't support default values.

When the language operator executes, it uses the provided knowledge base ID and knowledge source ID to look up the corresponding knowledge source.

At runtime, Twilio retrieves the plain text content of that knowledge source and injects it into the operator prompt.

The following example shows how to define a knowledge_base_and_source_ids parameter in your custom language operator's parameter schema:

1
{
2
  "type": "object",
3
  "parameters": {
4
    "policy_doc": {
5
      "type": "knowledge_base_and_source_ids",
6
      "required": true,
7
      "description": "Policy document to reference for compliance checks."
8
    }
9
  }
10
}

You can reference parameters in your prompt using the following syntax:

{{parameters.<param_name>}}

At runtime, Twilio replaces these tokens with the values supplied by your intelligence configuration rule. For example, if you have a parameter named length, you can reference it in your prompt like this:

Provide a {{parameters.length}}-length summary of this conversation.

Before creating a custom language operator, check if any Twilio-authored language operator meets your needs.

You can create a custom language operator using Twilio Console or the API.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

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

13
async function createOperator() {
14
  const operator = await client.intelligence.v3.operators.create({
15
    displayName: "Personalized Greeting",
16
    description:
17
      "Creates a personalized, context-aware greeting for a customer.",
18
    version: 1,
19
    author: "SELF",
20
    prompt:
21
      "Generate a {{parameters.tone}} greeting for the customer. Use any available customer profile attributes (name, preferences, status) and relevant business knowledge to tailor the message. Return JSON with the greeting text and a brief justification.",
22
    outputFormat: "JSON",
23
    outputSchema: {
24
      type: "object",
25
      properties: {
26
        greeting: {
27
          type: "string",
28
        },
29
        justification: {
30
          type: "string",
31
        },
32
      },
33
    },
34
    context: {
35
      knowledge: {
36
        enabled: true,
37
      },
38
    },
39
    parameters: {
40
      tone: {
41
        type: "STRING",
42
        default: "friendly",
43
        required: false,
44
        description:
45
          "The tone of the greeting (e.g., friendly, professional, casual).",
46
      },
47
    },
48
  });
49

50
  console.log(operator.id);
51
}
52

53
createOperator();

1
{
2
  "id": "intelligence_operator_01kcgy1ew0e9x8re6jq542zt8b",
3
  "displayName": "Script Adherence",
4
  "description": "Creates a personalized, context-aware greeting for a customer.",
5
  "version": 1,
6
  "author": "SELF",
7
  "prompt": "Generate a {{parameters.tone}} greeting for the customer. Use any available customer profile attributes (name, preferences, status) and relevant business knowledge to tailor the message. Return JSON with the greeting text and a brief justification.",
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
    "knowledge": {
33
      "enabled": true
34
    }
35
  },
36
  "parameters": {
37
    "tone": {
38
      "type": "STRING",
39
      "default": "friendly",
40
      "required": false,
41
      "description": "The tone of the greeting (e.g., friendly, professional, casual)."
42
    }
43
  }
44
}

• Review custom language operator examples.