Conversation groups

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.

FieldDescription
groupContains the response fields for the group.
idThe group ID. Can be used to update and delete the group.
nameThe name of the group that you specified in your request.
descriptionThe description of the group that you specified in your request.
criteriaThe 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.

FieldDescription
groupsA 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.

FieldDescription
groupContains the response fields for the group.
idThe group ID. Can be used to update and delete the group.
nameThe name of the group.
descriptionThe description of the group.
criteriaThe 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.

FieldDescription
groupsA 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.

ParameterData TypeDescription
limitInteger (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.
offsetInteger (int16)Specifies a non-negative number of items to skip before applying the limit.
orderString / enumSpecifies 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.
startTimeString / ISO 8601 date formatSpecifies 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.
endTimeString / ISO 8601 date formatSpecifies 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.
sortStringSpecifies one or more fields to be used to sort the results.
filterString / RSQL formatSpecifies 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.

FieldDescription
conversationsContains 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.

FieldDescription
groupContains the response fields for the group.
idThe group ID. Can be used to update and delete the group.
nameThe name of the group that you specified in your request.
descriptionThe description of the group that you specified in your request.
criteriaThe 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.

FieldDescription
deletedSpecifies whether the group was deleted.
idThe ID of the group that you deleted.
typeReturns group.

Example response

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