Conversation Groups (Beta)

🚧

In Beta

This feature is in Beta. If you have questions or comments, email [email protected].

Create Conversation Groups to organize conversations. Conversation Groups are dynamic and driven by criteria that you define. New conversations automatically appear in Conversation Groups when they meet the criteria.

Use RSQL to define the criteria that best suits your needs. Then, to include conversations in your Conversation Groups, apply the group criteria to conversations as Conversation Metadata.

If you previously applied metadata to conversations, and the metadata values meet the criteria of the group, those conversations will be automatically included in the Conversation Group.

For example:

  • Dan is the Head of Sales in his company and wants to group calls based on the type, such as internal and external. Using the metadata labels internal and external, Dan can group conversations and query them by label.

  • Ashna manages the Customer Experience team and wants to manage conversations with dozens of vendor companies. She can create Conversation Groups by adding a unique metadata identifier for each vendor. Ashna can then query conversations by vendor label.

  • Tom is the Chief Quality Assurance Manager and wants to analyze the customer conversations for a team member named John. Tom creates metadata labels for role agentId and name such as johndoe and janedoe. Tom can then query conversations based on role and name.

Perform create, read, update, and delete operations on Conversation Groups using the Management API.

This page describes the following operations for Conversation Groups:

Authentication

These requests require an access token, as described in Authenticate.


Create conversation group

This section describes how to create a conversation group.

To create a conversation group, use the POST https://api.symbl.ai/v1/manage/group operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"

curl \
  --url "https://api.symbl.ai/v1/manage/group" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
      "name": "<NAME>",
      "description": "<DESCRIPTION>",
      "criteria": "<CRITERIA>"
    }'

Where:

  • <ACCESS_TOKEN> is a valid API access token.
  • <NAME>, <DESCRIPTION>, and <CRITERIA> are valid values for the corresponding request body parameters.

For additional reference information, see Create a Conversation Group.

Request Body Parameters

ParameterTypeDescription
nameString, mandatoryName of the group. A string value with no special characters, with the exception of except -, _, and . The maximum allowed length is 128 characters.
descriptionString, optionalDescription to capture any additional details of the group and its purpose. The maximum allowed length is 512 characters.
criteriaString / RSQL format, mandatoryThe criteria in RSQL format that applies to conversations in this group. For more information about writing RSQL queries, see Parser for RSQL / FIQL.

Response

The following table describes the response body that is returned by this request.

Field

Description

group

Contains the response fields for the group.

id

The group ID. Can be used to update and delete the group.

name

The name of the group that you specified in your request.

description

The description of the group that you specified in your request.

criteria

The RSQL query that you specified in your request.

Example response

{
   "group" : {
      "criteria" : "conversation.metadata.org==sales",
      "description" : "All conversations for the Sales org.",
      "id" : "5297480609562624",
      "name" : "Sales Meetings"
   }
}

Create multiple conversation groups

This section describes how to create multiple conversation groups with one request.

To create multiple conversation groups, use the POST https://api.symbl.ai/v1/manage/groups operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"

curl \
  --url "https://api.symbl.ai/v1/manage/groups" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '[
      {
        "name": "<NAME>",
        "description": "<DESCRIPTION>",
        "criteria": "<CRITERIA>"
      },
      {
        "name": "<NAME>",
        "description": "<DESCRIPTION>",
        "criteria": "<CRITERIA>"
      }
    ]'

Where:

  • <ACCESS_TOKEN> is a valid API access token.
  • <NAME>, <DESCRIPTION>, and <CRITERIA> are valid values for the corresponding request body parameters. These parameters appear in each of the groups that you create.

Request Body Parameters

ParameterTypeDescription
nameString, mandatoryName of the group. A string value with no special characters, with the exception of except -, _, and . The maximum allowed length is 128 characters.
descriptionString, optionalDescription to capture any additional details of the group and its purpose. The maximum allowed length is 512 characters.
criteriaString / RSQL format, mandatoryThe criteria in RSQL format that applies to conversations in this group. For more information about writing RSQL queries, see Parser for RSQL / FIQL.

Response

The following table describes the response body that is returned by this request.

Field

Description

groups

A list of conversation groups. For the response fields specific to a conversation group, see Create Conversation Group.

Example response

{
   "groups" : [
      {
         "criteria" : "conversation.metadata.org==sales",
         "description" : "All conversations for the Sales org.",
         "id" : "5696974778007552",
         "name" : "Sales Meetings"
      },
      {
         "criteria" : "conversation.metadata.type==customer_meeting",
         "description" : "All customer meetings.",
         "id" : "5080154559741952",
         "name" : "Customer Meetings"
      },
      {
         "criteria" : "conversation.metadata.type==internal_meeting",
         "description" : "All customer meetings.",
         "id" : "5523249155801088",
         "name" : "Internal Meetings"
      }
   ]
}

Get conversation group

This section describes how to get a conversation group.

To get a conversation group, use the GET https://api.symbl.ai/v1/manage/group/{groupId} operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
GROUP_ID="<GROUP_ID>"

curl --request GET \
  --url "https://api.symbl.ai/v1/manage/group/$GROUP_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Where:

For additional reference information, see Fetch Conversation Group by ID.

Response

The following table describes the response body that is returned by this request.

Field

Description

group

Contains the response fields for the group.

id

The group ID. Can be used to update and delete the group.

name

The name of the group.

description

The description of the group.

criteria

The RSQL query that describes the group criteria.

Example response

{
   "group" : {
      "criteria" : "conversation.metadata.org==sales",
      "description" : "All conversations for the Sales org.",
      "id" : "5699708356919296",
      "name" : "Sales Meetings"
   }
}

Get all conversation groups

This section describes how to get a list of your conversation groups.

To get a list of your conversation groups, use the GET https://api.symbl.ai/v1/manage/groups operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"

curl --request GET \
  --url "https://api.symbl.ai/v1/manage/groups" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Where:

Response

The following table describes the response body that is returned by this request.

Field

Description

groups

A list of conversation groups. For the response fields specific to a conversation group, see Get Conversation Group.

Example response

{
   "groups" : [
      {
         "criteria" : "conversation.metadata.org==sales",
         "description" : "All conversations for the Sales org.",
         "id" : "5696974778007552",
         "name" : "Sales Meetings"
      },
      {
         "criteria" : "conversation.metadata.type==customer_meeting",
         "description" : "All customer meetings.",
         "id" : "5080154559741952",
         "name" : "Customer Meetings"
      },
      {
         "criteria" : "conversation.metadata.type==internal_meeting",
         "description" : "All customer meetings.",
         "id" : "5523249155801088",
         "name" : "Internal Meetings"
      }
   ]
}

Get conversations from group

This section describes how to get conversations from a conversation group.

To get conversations from a conversation group, use the GET https://api.symbl.ai/v1/manage/group/{groupId} operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
GROUP_ID="<GROUP_ID>"

curl --request GET \
  --url "https://api.symbl.ai/v1/groups/$GROUP_ID/conversations" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Where:

Optional query parameters

The following table describes the optional query parameters that can be used with this request.

Parameter

Data Type

Description

limit

Integer (int16)

Specifies a non-negative integer count, to indicate that no more than count items in the result will be returned. limit set to 0 returns 0 items in the result.

Value must be between 0 to 65536.

offset

Integer (int16)

Specifies a non-negative number of items to skip before applying the limit.

order

String / enum

Specifies the order in which the results should be sorted. By default, the order is based on the startTime field of the associated conversation.

Valid values are asc and desc.

startTime

String / ISO 8601 date format

Specifies the start of the datetime range for the results to be returned. This startTime is associated with the startTime field of the associated conversation. If the startTime parameter is not included, then startTime is calculated as startTime = endTime - duration('7 days').

Valid values are ISO 8601 formatted strings with value less than current timestamp and less than endTime.

endTime

String / ISO 8601 date format

Specifies the end of the datetime range for the results to be returned. This endTime is associated with the endTime field of the associated conversation. If endTime is not included, then the current date and time is used as endTime automatically.

Valid values are ISO 8601 formatted strings with value less than current timestamp and greater than startTime.

sort

String

Specifies one or more fields to be used to sort the results.

filter

String / RSQL format

Specifies a filter string in RSQL format to filter the results.

  • Filter parameter should be a valid RSQL string however it can't have OR logical Operator.
  • Filter parameter can not have more than 2 parameters in its filters. There is no limit on filters though, so user can add any number of filters using maximum of two parameters.

Response

The following table describes the response body that is returned by this request.

Field

Description

conversations

Contains the response fields for the group. For response fields specific to a conversation, see Manage Conversations.

Example response

{
   "conversations" : [
      {
         "endTime" : "2022-08-03T00:44:18.552Z",
         "id" : "4659234242297856",
         "members" : [],
         "metadata" : {
            "org" : "sales",
            "type" : "customer_meeting"
         },
         "name" : "Meeting with Customer 1",
         "startTime" : "2022-08-03T00:43:31.032Z",
         "type" : "meeting"
      },
      {
         "endTime" : "2022-08-03T00:46:13.040Z",
         "id" : "6278546367447040",
         "members" : [],
         "metadata" : {
            "org" : "sales",
            "type" : "customer_meeting"
         },
         "name" : "Meeting with Customer 2",
         "startTime" : "2022-08-03T00:45:25.520Z",
         "type" : "meeting"
      }
   ]
}

Update conversation group

This section describes how to update a conversation group.

To update a conversation group, use the PUT https://api.symbl.ai/v1/manage/group/{groupId} operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
GROUP_ID="<GROUP_ID>"

curl --request PUT \
  --url "https://api.symbl.ai/v1/manage/group/$GROUP_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
      "id": "<GROUP_ID>",
      "name": "<NAME>",
      "description": "<DESCRIPTION>",
      "criteria": "<CRITERIA>"
    }'

Where:

  • <ACCESS_TOKEN> is a valid API access token.
  • <GROUP_ID> is the ID of a group that you previously created.
  • <NAME>, <DESCRIPTION>, and <CRITERIA> are valid values for the corresponding request body parameters.

For additional reference information, see Update Conversation Group by ID.

Request Body Parameters

ParameterTypeDescription
idString, mandatoryID of the group. Must match the ID that was used in the path.
nameString, mandatoryName of the group. A string value with no special characters, with the exception of except -, _, and . The maximum allowed length is 128 characters.
descriptionString, optionalDescription to capture any additional details of the group and its purpose. The maximum allowed length is 512 characters.
criteriaString / RSQL format, mandatoryThe criteria in RSQL format that applies to conversations in this group. For more information about writing RSQL queries, see Parser for RSQL / FIQL.

Response

The following table describes the response body that is returned by this request.

Field

Description

group

Contains the response fields for the group.

id

The group ID. Can be used to update and delete the group.

name

The name of the group that you specified in your request.

description

The description of the group that you specified in your request.

criteria

The RSQL query that you specified in your request.

Example response

{
   "group" : {
      "criteria" : "conversation.metadata.org==engineering",
      "description" : "All conversations for the Engineering org.",
      "id" : "5696974778007552",
      "name" : "Engineering Meetings"
   }
}

Delete conversation group

This section describes how to delete a conversation group.

To delete a conversation group, use the DELETE https://api.symbl.ai/v1/manage/group/{groupId} operation:

👍

Try our interactive examples!

We provide interactive versions of these code samples: curl

To get started with our code samples, see Set Up Your Test Environment.

ACCESS_TOKEN="<ACCESS_TOKEN>"
GROUP_ID="<GROUP_ID>"

curl -s \
  --request DELETE \
  --url "https://api.symbl.ai/v1/manage/group/$GROUP_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "Content-Type: application/json"

Where:

For additional reference information, see Delete Conversation Group by ID.

Response

The following table describes the response body that is returned by this request.

Field

Description

deleted

Specifies whether the group was deleted.

id

The ID of the group that you deleted.

type

Returns group.

Example response

{
   "deleted" : true,
   "id" : "5699708356919296",
   "type" : "group"
}

Did this page help you?