Skip to contentSkip to navigationSkip to topbar
Twilio Docs

Execute a semantic query

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

POST/v3/InsightsDomains/Conversations/Query

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

Execute a semantic query against the Conversations domain.

Request

create-query-results-request page anchor

Authentication

authentication page anchor

Query string

create-query-results-query-string page anchor
Property nameTypeRequiredPIIDescription
pageSizeinteger<int32>

Optional

Not PII

Number of items per page

Example: 20Minimum: 1

Request body

create-query-results-request-body page anchor
Encoding type:application/json
Schema
Property nameTypeRequiredPIIDescriptionChild properties
domainstring

Optional

Not PII

The business domain to execute the query against

Example: Conversations
queryobject
required
Not PII

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

Responses

create-query-results-responses page anchor
200400429500

Successful query response

Schema
Property nameTypeRequiredPIIDescriptionChild properties
domainstring

Optional

Not PII

Indicates the business domain the query was executed against

Example: Insights
itemsarray[object]

Optional

Not PII

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"}]
metaobject

Optional

Not PII

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

Execute a semantic queryLink to code sample: Execute a semantic query
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 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


39
createQueryResults();

Response

Note about this 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
}