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
andexternal
, 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 asjohndoe
andjanedoe
. 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:
- Create Conversation Group
- Create Multiple Conversation Groups
- Get Conversation Group
- Get All Conversation Groups
- Get Conversations from Group
- Update Conversation Group
- Delete Conversation Group
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
Parameter | Type | Description |
---|---|---|
name | String, mandatory | Name of the group. A string value with no special characters, with the exception of except - , _ , and ” . The maximum allowed length is 128 characters. |
description | String, optional | Description to capture any additional details of the group and its purpose. The maximum allowed length is 512 characters. |
criteria | String / RSQL format, mandatory | The 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 |
---|---|
| Contains the response fields for the group. |
| The group ID. Can be used to update and delete the group. |
| The name of the group that you specified in your request. |
| The description of the group that you specified in your request. |
| 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
Parameter | Type | Description |
---|---|---|
name | String, mandatory | Name of the group. A string value with no special characters, with the exception of except - , _ , and ” . The maximum allowed length is 128 characters. |
description | String, optional | Description to capture any additional details of the group and its purpose. The maximum allowed length is 512 characters. |
criteria | String / RSQL format, mandatory | The 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 |
---|---|
| 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:
<ACCESS_TOKEN>
is a valid API access token.<GROUP_ID>
is the ID of a group that you previously created.
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 |
---|---|
| Contains the response fields for the group. |
| The group ID. Can be used to update and delete the group. |
| The name of the group. |
| The description of the group. |
| 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:
<ACCESS_TOKEN>
is a valid API access token.
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
| 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:
<ACCESS_TOKEN>
is a valid API access token.<GROUP_ID>
is the ID of a group that you previously created.
Optional query parameters
The following table describes the optional query parameters that can be used with this request.
Parameter | Data Type | Description |
---|---|---|
| Integer (int16) | Specifies a non-negative integer Value must be between |
| Integer (int16) | Specifies a non-negative number of items to skip before applying the |
| String / enum | Specifies the order in which the results should be sorted. By default, the Valid values are |
| String / ISO 8601 date format | Specifies the start of the datetime range for the results to be returned. This Valid values are ISO 8601 formatted strings with value less than current timestamp and less than |
| String / ISO 8601 date format | Specifies the end of the datetime range for the results to be returned. This Valid values are ISO 8601 formatted strings with value less than current timestamp and greater than |
| String | Specifies one or more fields to be used to sort the results. |
| String / RSQL format | Specifies a filter string in RSQL format to filter the results.
|
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
| 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
Parameter | Type | Description |
---|---|---|
id | String, mandatory | ID of the group. Must match the ID that was used in the path. |
name | String, mandatory | Name of the group. A string value with no special characters, with the exception of except - , _ , and ” . The maximum allowed length is 128 characters. |
description | String, optional | Description to capture any additional details of the group and its purpose. The maximum allowed length is 512 characters. |
criteria | String / RSQL format, mandatory | The 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 |
---|---|
| Contains the response fields for the group. |
| The group ID. Can be used to update and delete the group. |
| The name of the group that you specified in your request. |
| The description of the group that you specified in your request. |
| 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:
<ACCESS_TOKEN>
is a valid API access token.<GROUP_ID>
is the ID of a group that you previously created.
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 |
---|---|
| Specifies whether the group was deleted. |
| The ID of the group that you deleted. |
| Returns |
Example response
{
"deleted" : true,
"id" : "5699708356919296",
"type" : "group"
}
Updated 5 days ago