Retrieve a list of Conversations

(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.

GET/v3/Conversations

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

Retrieve a list of Conversations processed by an Intelligence Configuration.

Request

Authentication

Basic Auth

Query string

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

200400401403404429500

An array of Conversations.

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

itemsarray[object]

Optional

Not PII

List of conversations.

Show items properties

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.

Show participants properties

operatorResultIdsarray[string]

Optional

Not PII

List of Operator Result IDs generated from this Conversation.

metaobject

Optional

Not PII

Show meta properties

{
  "items": [
    {
      "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv2",
      "accountId": "AC00000000000000000000000000000000",
      "name": "Customer Support Call - Order #12345",
      "status": "CLOSED",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:45:30Z",
      "intelligenceConfigurationIds": [
        "intelligence_configuration_01kermhm82e5mr98nbeh1hpmbn"
      ],
      "conversationConfigurationId": "conv_configuration_00000000000000000000000000",
      "channels": [
        "VOICE"
      ],
      "channelIds": [
        "CA1234567890abcdef1234567890abcdef"
      ],
      "participants": [
        {
          "id": "conv_participant_01k1etx3jbfx88476ccja0889c",
          "name": "John Customer",
          "type": "CUSTOMER",
          "addressValues": [
            "+15551234567"
          ]
        },
        {
          "id": "conv_participant_01k1etx3jbfx88476ccja0889d",
          "name": "Sarah Agent",
          "type": "HUMAN_AGENT",
          "addressValues": [
            "agent-sarah@example.com"
          ]
        }
      ],
      "operatorResultIds": [
        "intelligence_operatorresult_01k6fc25s7epm9qtk8rszbv3q5"
      ]
    },
    {
      "id": "conv_conversation_01k1etk2y5f1y9fpe2epfdtvv3",
      "accountId": "AC00000000000000000000000000000000",
      "name": "Sales Inquiry - WhatsApp",
      "status": "ACTIVE",
      "createdAt": "2026-01-15T14:20:00Z",
      "updatedAt": "2026-01-15T14:22:00Z",
      "intelligenceConfigurationIds": [
        "intelligence_configuration_01kermhm82e5mr98nbeh1hpmbn"
      ],
      "conversationConfigurationId": "conv_configuration_00000000000000000000000000",
      "channels": [
        "WHATSAPP"
      ],
      "channelIds": [
        "SM9876543210fedcba9876543210fedcba"
      ],
      "participants": [
        {
          "id": "conv_participant_01k1etx3jbfx88476ccja0889e",
          "name": "Maria Customer",
          "type": "CUSTOMER",
          "addressValues": [
            "whatsapp:+15559876543"
          ]
        },
        {
          "id": "conv_participant_01k1etx3jbfx88476ccja0889f",
          "name": "AI Sales Assistant",
          "type": "AI_AGENT",
          "addressValues": [
            "bot-sales@example.com"
          ]
        }
      ],
      "operatorResultIds": [
        "intelligence_operatorresult_01k6fc25s7epm9qtk8rszbv3q7"
      ]
    }
  ],
  "meta": {
    "key": "items",
    "pageSize": 2,
    "nextToken": "next_page_token_example"
  }
}

Bad request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Not PII

Twilio-specific error code

messagestring

Optional

Not PII

A human readable error message

httpStatusCodeinteger<int32>

Optional

Not PII

HTTP response status code

userErrorboolean

Optional

Not PII

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

paramsobject

Optional

Not PII

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

Unauthorized request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Not PII

Twilio-specific error code

messagestring

Optional

Not PII

A human readable error message

httpStatusCodeinteger<int32>

Optional

Not PII

HTTP response status code

userErrorboolean

Optional

Not PII

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

paramsobject

Optional

Not PII

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

Forbidden request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Not PII

Twilio-specific error code

messagestring

Optional

Not PII

A human readable error message

httpStatusCodeinteger<int32>

Optional

Not PII

HTTP response status code

userErrorboolean

Optional

Not PII

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

paramsobject

Optional

Not PII

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

Not PII

Twilio-specific error code

messagestring

Optional

Not PII

A human readable error message

httpStatusCodeinteger<int32>

Optional

Not PII

HTTP response status code

userErrorboolean

Optional

Not PII

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

paramsobject

Optional

Not PII

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

Not PII

Twilio-specific error code

messagestring

Optional

Not PII

A human readable error message

httpStatusCodeinteger<int32>

Optional

Not PII

HTTP response status code

userErrorboolean

Optional

Not PII

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

paramsobject

Optional

Not PII

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

Not PII

Twilio-specific error code

messagestring

Optional

Not PII

A human readable error message

httpStatusCodeinteger<int32>

Optional

Not PII

HTTP response status code

userErrorboolean

Optional

Not PII

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

paramsobject

Optional

Not PII

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 Conversations

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 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
18listConversations();

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}