Skip to contentSkip to navigationSkip to topbar
Twilio Docs

Intelligence API (v3) - Conversations 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(link takes you to an external page). 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(link takes you to an external page). If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

Overview

overview page anchor

Retrieve conversations processed by an intelligence configuration, including associated execution metadata and contextual information.

The Conversations resource lets you to inspect conversations alongside their applied intelligence, including which rules were evaluated, which language operators ran, and what results were produced.

Use this resource to understand how Conversational Intelligence was applied to a given interaction and to correlate conversation transcripts with language operator results.

Endpoints

Retrieve a list of Conversations

list-conversations page anchor

GET/v3/Conversations

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

Retrieve a list of Conversations processed by an Intelligence Configuration.

Request

list-conversations-request page anchor

Query string

list-conversations-query-string page anchor
Property nameTypeRequiredPIIDescription
pageSizeinteger

Optional

Not PII

The maximum number of resources to return

Default: 50Minimum: 1Maximum: 1000
pageTokenstring

Optional

Not PII

Token for pagination

createdAtBeforestring<date-time>

Optional

Not PII

Filter by Conversations created before this timestamp.

createdAtAfterstring<date-time>

Optional

Not PII

Filter by Conversations created after this timestamp.

statusenum<string>

Optional

Not PII

Filter by Conversation status.

Possible values:
ACTIVEINACTIVECLOSED
channelIdstring

Optional

Not PII

Filters Conversations by the underlying channel resource ID, such as a Call ID or Message ID.

channelsarray[enum<string>]

Optional

Not PII

Filters Conversations that include one or more of the specified communication channels (OR match).

Possible values:
VOICESMSRCSEMAILWHATSAPPCHATAPISYSTEM
conversationConfigurationIdstring

Optional

Not PII

The configuration id used to generate the Conversation.

Example: conv_configuration_00000000000000000000000000
intelligenceConfigurationIdsarray[string]

Optional

Not PII

Filters Conversations activated by one or more of the specified Intelligence Configuration IDs (OR match).

operatorIdsarray[string]

Optional

Not PII

Filters Conversations to those where at least one of the specified Language Operators was executed (OR match).

Responses

list-conversations-responses page anchor
200400401403404429500

An array of Conversations.

SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
itemsarray[object]

Optional

Not PII

List of conversations.

metaobject

Optional

Not PII
Retrieve a list of ConversationsLink to code sample: Retrieve a list of Conversations
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 and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function listConversations() {

11
  const conversations = await client.intelligence.v3.conversations.list({

12
    limit: 20,

13
  });

14


15
  conversations.forEach((c) => console.log(c.id));

16
}

17


18
listConversations();

Response

Note about this response
1
{

2
  "items": [

3
    {

4
      "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2",

5
      "accountId": "AC00000000000000000000000000000000",

6
      "name": "Customer Support Call - Order #12345",

7
      "status": "CLOSED",

8
      "createdAt": "2026-01-15T10:30:00Z",

9
      "updatedAt": "2026-01-15T10:45:30Z",

10
      "intelligenceConfigurationIds": [

11
        "intelligence_configuration_01kermhm82e5mr98nbeh1hpmbn"

12
      ],

13
      "conversationConfigurationId": "conv_configuration_00000000000000000000000000",

14
      "channels": [

15
        "VOICE"

16
      ],

17
      "channelIds": [

18
        "CA1234567890abcdef1234567890abcdef"

19
      ],

20
      "participants": [

21
        {

22
          "id": "conv_participant_01k1etx3jbfx88476ccja0889c",

23
          "name": "John Customer",

24
          "type": "CUSTOMER",

25
          "addressValues": [

26
            "+15551234567"

27
          ]

28
        },

29
        {

30
          "id": "conv_participant_01k1etx3jbfx88476ccja0889d",

31
          "name": "Sarah Agent",

32
          "type": "HUMAN_AGENT",

33
          "addressValues": [

34
            "agent-sarah@example.com"

35
          ]

36
        }

37
      ],

38
      "operatorResultIds": [

39
        "intelligence_operatorresult_01k6fc25s7epm9qtk8rszbv3q5"

40
      ]

41
    },

42
    {

43
      "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv3",

44
      "accountId": "AC00000000000000000000000000000000",

45
      "name": "Sales Inquiry - WhatsApp",

46
      "status": "ACTIVE",

47
      "createdAt": "2026-01-15T14:20:00Z",

48
      "updatedAt": "2026-01-15T14:22:00Z",

49
      "intelligenceConfigurationIds": [

50
        "intelligence_configuration_01kermhm82e5mr98nbeh1hpmbn"

51
      ],

52
      "conversationConfigurationId": "conv_configuration_00000000000000000000000000",

53
      "channels": [

54
        "WHATSAPP"

55
      ],

56
      "channelIds": [

57
        "SM9876543210fedcba9876543210fedcba"

58
      ],

59
      "participants": [

60
        {

61
          "id": "conv_participant_01k1etx3jbfx88476ccja0889e",

62
          "name": "Maria Customer",

63
          "type": "CUSTOMER",

64
          "addressValues": [

65
            "whatsapp:+15559876543"

66
          ]

67
        },

68
        {

69
          "id": "conv_participant_01k1etx3jbfx88476ccja0889f",

70
          "name": "AI Sales Assistant",

71
          "type": "AI_AGENT",

72
          "addressValues": [

73
            "bot-sales@example.com"

74
          ]

75
        }

76
      ],

77
      "operatorResultIds": [

78
        "intelligence_operatorresult_01k6fc25s7epm9qtk8rszbv3q7"

79
      ]

80
    }

81
  ],

82
  "meta": {

83
    "key": "items",

84
    "pageSize": 2,

85
    "nextToken": "next_page_token_example"

86
  }

87
}

Retrieve a Conversation

fetch-conversation page anchor

GET/v3/Conversations/{id}

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

Request

fetch-conversation-request page anchor

Path parameters

fetch-conversation-path-parameters page anchor
Property nameTypeRequiredPIIDescription
idstring
required
Not PII

The unique identifier of the conversation.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2Pattern: ^conv_conversation_[0-7][0-9a-z]{25}$

Responses

fetch-conversation-responses page anchor
200400401403404429500

Conversation object.

SchemaExample
Property nameTypeRequiredPIIDescriptionChild properties
idstring

Optional

Not PII

The id of the Conversation attached to the Operator Result.

Example: conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2Pattern: ^conv_conversation_[0-7][0-9a-z]{25}$
accountIdSID<AC>

Optional

Not PII

The ID of the account that owns the Conversation.

Pattern: ^AC[0-9a-fA-F]{32}$Min length: 34Max length: 34
namestring

Optional

Not PII

Display name of the Conversation.

statusenum<string>

Optional

Not PII

The status of the Conversation.

Possible values:
ACTIVEINACTIVECLOSED
createdAtstring<date-time>

Optional

Not PII

Timestamp for when the Conversation was created.

updatedAtstring<date-time>

Optional

Not PII

Timestamp for when the Conversation was last updated.

intelligenceConfigurationIdsarray[string]

Optional

Not PII

The Intelligence Configuration(s) associated with the Conversation.

conversationConfigurationIdstring

Optional

Not PII

The id of the Configuration for a Conversation.

Example: conv_configuration_00000000000000000000000000
channelsarray[enum<string>]

Optional

Not PII

The communication channel(s) included in the Conversation.

Possible values:
VOICESMSRCSEMAILWHATSAPPCHATAPISYSTEM
channelIdsarray[string]

Optional

Not PII

The underlying channel resource ids associated with this Conversation, such as a Call ID or Message ID.

participantsarray[object]

Optional

Not PII

Metadata for Participants of the Conversation.

communicationsarray[object]

Optional

Not PII

Metadata for the Communications that make up the Conversation.

operatorResultIdsarray[string]

Optional

Not PII

List of Operator Result IDs generated from this Conversation.

Retrieve a ConversationLink to code sample: Retrieve a Conversation
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 and Auth Token at twilio.com/console

5
// and set the environment variables. See http://twil.io/secure

6
const accountSid = process.env.TWILIO_ACCOUNT_SID;

7
const authToken = process.env.TWILIO_AUTH_TOKEN;

8
const client = twilio(accountSid, authToken);

9


10
async function fetchConversation() {

11
  const conversation = await client.intelligence.v3

12
    .conversations("conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2")

13
    .fetch();

14


15
  console.log(conversation.id);

16
}

17


18
fetchConversation();

Response

Note about this response
1
{

2
  "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2",

3
  "accountId": "AC00000000000000000000000000000000",

4
  "name": "Customer Support Call - Order #12345",

5
  "status": "CLOSED",

6
  "createdAt": "2026-01-15T10:30:00Z",

7
  "updatedAt": "2026-01-15T10:45:30Z",

8
  "intelligenceConfigurationIds": [

9
    "intelligence_configuration_01kermhm82e5mr98nbeh1hpmbn"

10
  ],

11
  "conversationConfigurationId": "conv_configuration_00000000000000000000000000",

12
  "channels": [

13
    "VOICE"

14
  ],

15
  "channelIds": [

16
    "CA1234567890abcdef1234567890abcdef"

17
  ],

18
  "participants": [

19
    {

20
      "id": "conv_participant_01k1etx3jbfx88476ccja0889c",

21
      "name": "John Customer",

22
      "type": "CUSTOMER",

23
      "addressValues": [

24
        "+15551234567"

25
      ]

26
    },

27
    {

28
      "id": "conv_participant_01k1etx3jbfx88476ccja0889d",

29
      "name": "Sarah Agent",

30
      "type": "HUMAN_AGENT",

31
      "addressValues": [

32
        "agent-sarah@example.com"

33
      ]

34
    }

35
  ],

36
  "communications": [

37
    {

38
      "id": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv2",

39
      "participantId": "conv_participant_01k1etx3jbfx88476ccja0889d",

40
      "content": {

41
        "text": "Thank you for calling customer support. How can I help you today?"

42
      },

43
      "createdAt": "2026-01-15T10:30:15Z"

44
    },

45
    {

46
      "id": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv3",

47
      "participantId": "conv_participant_01k1etx3jbfx88476ccja0889c",

48
      "content": {

49
        "text": "Hi, I need help tracking my order #12345."

50
      },

51
      "createdAt": "2026-01-15T10:30:30Z"

52
    },

53
    {

54
      "id": "conv_communication_01k1etk2y5f1y9fpe2epfdtvv9",

55
      "participantId": "conv_participant_01k1etx3jbfx88476ccja0889d",

56
      "content": {

57
        "text": "I'd be happy to help you with that. Let me look up your order."

58
      },

59
      "createdAt": "2026-01-15T10:30:45Z"

60
    }

61
  ],

62
  "operatorResultIds": [

63
    "intelligence_operatorresult_01k6fc25s7epm9qtk8rszbv3q5",

64
    "intelligence_operatorresult_01k6fc25s7epm9qtk8rszbv3q6"

65
  ]

66
}