Build on-demand workflows with Conversation Intelligence

For each workflow you need:

• An intelligence configuration
• A conversationId from an active Conversation Orchestrator conversation
• A webhook endpoint to receive results

This example shows how to trigger a conversation summary at the moment of handoff, so the agent receives context as early as possible, without waiting for the conversation to close. When your application triggers a handoff, it makes an API request for on-demand rule execution, and Conversation Intelligence analyzes the transcript up to that point and delivers the result to your webhook.

1. In your intelligence configuration, define a Summary rule with the Summary operator and set the trigger to On-demand (triggers: []).

   For more information on rules and triggers, see Define rules.

   Write down the Rule ID. You'll need these IDs when making POST /v3/RuleExecutions requests.

2. To run the Summary rule on-demand, make a POST /v3/RuleExecutions request.

   Execute Summary

   Node.jsPythonC#JavaGoPHPRubytwilio-clicurl

   Report code block

   Copy code block

   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 createRuleExecution() {
   14
     const ruleExecution = await client.intelligence.v3.ruleExecutions.create({
   15
       intelligenceConfigurationId:
   16
         "intelligence_configuration_01k6fc25s7epm9qtk8rszbv3q5",
   17
       ruleId: "intelligence_configurationrule_01k6fc25s7epm9qtk8rszbv3q6",
   18
       conversationId: "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2",
   19
     });
   20
   
   21
     console.log(ruleExecution);
   22
   }
   23
   
   24
   createRuleExecution();

   A successful request returns 202 Accepted. Your handoff routing logic continues without waiting for the result.

3. Receive the Summary result in your webhook.

   Webhook: Summary result

   Copy code block

   1
   {
   2
     "accountId": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
   3
     "conversationId": "conv_conversation_xxxxxxxxxxxxxxxxxxxxxxxxx",
   4
     "intelligenceConfiguration": {
   5
       "id": "intelligence_configuration_xxxxxxxxxxxxxxxxxxxxxxxxx",
   6
       "displayName": "Agent Handoff",
   7
       "version": 1,
   8
       "ruleId": "intelligence_configurationrule_xxxxxxxxxxxxxxxxxxxxxxxxx"
   9
     },
   10
     "operatorResults": [
   11
       {
   12
         "id": "intelligence_operatorresult_xxxxxxxxxxxxxxxxxxxxxxxxx",
   13
         "operator": {
   14
           "id": "intelligence_operator_xxxxxxxxxxxxxxxxxxxxxxxxx",
   15
           "displayName": "Summary",
   16
           "version": 1
   17
         },
   18
         "outputFormat": "JSON",
   19
         "result": {
   20
           "summary": "Customer contacted support about a charge that appeared twice on their account. They confirmed the transaction date and amount. No resolution reached before handoff.",
   21
           "sentiment": "frustrated"
   22
         },
   23
         "dateCreated": "2026-09-18T15:04:22Z",
   24
         "referenceIds": [],
   25
         "executionDetails": {
   26
           "trigger": {
   27
             "on": "ON_DEMAND",
   28
             "timestamp": "2026-09-18T15:04:22.314081227Z"
   29
           }
   30
         },
   31
         "metadata": {
   32
           "system": {
   33
             "latencyMs": 3120,
   34
             "resolvedModel": "claude-3-haiku",
   35
             "inputCharacters": 8204,
   36
             "outputCharacters": 89,
   37
             "inputTruncated": false
   38
           }
   39
         }
   40
       }
   41
     ]
   42
   }

4. Surface the summary in your agent desktop.

   Your webhook handler receives the summary payload and extracts the result. From there, push it to your agent desktop using the mechanism your platform supports, such as a WebSocket event, a server-sent event, or a direct API request to your CRM or agent platform.

   Your webhook handler extracts the result object from the incoming payload:

   Copy code block

   1
   {
   2
     "result": {
   3
       "summary": "Customer contacted support about a charge that appeared twice on their account. They confirmed the transaction date and amount. No resolution reached before handoff.",
   4
       "sentiment": "frustrated"
   5
     }
   6
   }

• Define rules
• Use Twilio-authored language operators
• Create custom language operators