Skip to content Skip to navigation Skip to topbar

Insights API (v3) - Twilio Insights endpoints

(new)

Public beta

Conversation Insights, including the APIs, is currently available as a public beta release and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

Conversation Insights 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

Twilio Insights API.

Endpoints

/v3/InsightsDomains/Conversations/Metadata

Fetch Metadata for the Conversations domain

/v3/InsightsDomains/Conversations/Query

Execute a semantic query

/v3/InsightsDomains/Conversations/Query

Fetch semantic query results

Fetch Metadata for the Conversations domain

GET/v3/InsightsDomains/Conversations/Metadata

Base url: https://insights.twilio.com (base url)

Fetch Metadata for the Conversations domain.

Request

Security: Basic Auth

Responses

200400429500

successful operation

Schema

Property nameTypeRequiredPIIDescriptionChild properties

domainstring

Optional

The business domain name for which metadata is being provided

Example: Insights

cubesarray[object]

Optional

List of data cubes available in the domain, each containing measures and dimensions

Show cubes 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

Fetch Metadata for the Conversations domain

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 fetchMetadata() {
11  const metadata = await client.insights.v3.metadata.fetch();
12
13  console.log(metadata.domain);
14}
15
16fetchMetadata();

Response

1{
2  "cubes": [
3    {
4      "name": "name",
5      "description": "description",
6      "measures": [
7        {
8          "name": "name",
9          "description": "description",
10          "type": "type",
11          "aggregation": "aggregation"
12        }
13      ],
14      "dimensions": [
15        {
16          "name": "name",
17          "description": "description",
18          "type": "type"
19        }
20      ]
21    }
22  ],
23  "domain": "domain"
24}

Execute a semantic query

POST/v3/InsightsDomains/Conversations/Query

Base url: https://insights.twilio.com (base url)

Execute a semantic query against the Conversations domain.

Request

Security: Basic Auth

Query string

Property nameTypeRequiredPIIDescription

pageSizeinteger<int32>

Optional

Number of items per page

Example: 20Minimum: 1

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

domainstring

Optional

The business domain to execute the query against

Example: Conversations

queryobject

required

Structured query definition that specifies what data to retrieve and how to filter, group, and order it

Show query properties

Responses

200400429500

Successful query response

Schema

Property nameTypeRequiredPIIDescriptionChild properties

domainstring

Optional

Indicates the business domain the query was executed against

Example: Insights

itemsarray[object]

Optional

Array of result objects containing the query results. Each object contains properties matching the requested measures and dimensions.

Example:

[{"Id":"conv1","Languages":["en"],"Channels":["voice"],"OperatorResult.Value":"positive"},{"Id":"conv2","Languages":["en","es"],"Channels":["chat"],"OperatorResult.Value":"negative"}]

Show items properties

metaobject

Optional

Pagination metadata containing navigation tokens and result information, this schema should according to convention be added to the response payload's 'meta' attribute

Show meta 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

Execute a semantic query

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 createQueryResults() {
11  const query = await client.insights.v3.query.create({
12    query: {
13      measures: ["measures"],
14      dimensions: ["dimensions"],
15      filters: [
16        {
17          op: "AND",
18          expressions: [
19            {
20              op: "IN",
21              field: "field",
22              values: ["values"],
23            },
24          ],
25        },
26      ],
27      orderBy: [
28        {
29          field: "field",
30          direction: "DESC",
31        },
32      ],
33    },
34  });
35
36  console.log(query.domain);
37}
38
39createQueryResults();

Response

1{
2  "domain": "domain",
3  "items": [
4    {}
5  ],
6  "meta": {
7    "key": "key",
8    "pageSize": 20,
9    "previousToken": "previousToken",
10    "nextToken": "nextToken"
11  }
12}

Fetch semantic query results

GET/v3/InsightsDomains/Conversations/Query

Base url: https://insights.twilio.com (base url)

Request

Security: Basic Auth

Query string

Property nameTypeRequiredPIIDescription

pageTokenstring

required

Pagination token

Example: eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0=

Responses

200400429500

Successful query response

Schema

Property nameTypeRequiredPIIDescriptionChild properties

domainstring

Optional

Indicates the business domain the query was executed against

Example: Insights

itemsarray[object]

Optional

Array of result objects containing the query results. Each object contains properties matching the requested measures and dimensions.

Example:

[{"Id":"conv1","Languages":["en"],"Channels":["voice"],"OperatorResult.Value":"positive"},{"Id":"conv2","Languages":["en","es"],"Channels":["chat"],"OperatorResult.Value":"negative"}]

Show items properties

metaobject

Optional

Pagination metadata containing navigation tokens and result information, this schema should according to convention be added to the response payload's 'meta' attribute

Show meta 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

Fetch semantic query results

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 fetchQueryResults() {
11  const query = await client.insights.v3.query.fetch({
12    pageToken: "pageToken",
13  });
14
15  console.log(query.domain);
16}
17
18fetchQueryResults();

Response

1{
2  "domain": "domain",
3  "items": [
4    {}
5  ],
6  "meta": {
7    "key": "key",
8    "pageSize": 20,
9    "previousToken": "previousToken",
10    "nextToken": "nextToken"
11  }
12}