Skip to main content

Conversation Groups (Beta)


In Beta Phase

This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai.

Conversation Groups allow you to create logical groups of conversations by setting the grouping criteria that suit your business requirement.

The criteria of the group can be applied to Conversation Metadata that can be any important information such as unique identifiers like agentId, customerId, userId, etc., or custom tags such as sales call, support call, internal discussion, etc.

Quick Start Guide#

This section provides step-by-step instructions on how to creating and use Conversation Groups.

Step 1: Create a Conversation Group#


To create a conversation group, make a POST request to Symbl using the following Conversation Group Management API:

POST https://api.symbl.ai/v1/manage/group

Request Body#

{
"name": "Calls made by John",
"description": "All the conversations of agent John Doe are captured in this Group.",
"criteria": "conversation.metadata.agentId==johndoe"
}

Request Body Parameters#

ParameterData TypeDescriptionRequiredValues Accepted
nameStringName of the group.MandatoryString with no special characters allowed, except -, _, and . The maximum length of string allowed 128 characters.
descriptionStringDescription to capture any additional details of the group and its purpose.OptionalThe maximum length of string allowed 512 characters.
criteriaString / RSQL formatCriteria in RSQL format that should be applied to group conversations under this group.MandatoryValid RSQL string. For more information on how to write RSQL queries, click here.

Response Body#

{
"group": {
"id": 4931769134481408,
"name": "Calls made by John",
"description": "All the conversations made by agent John Doe are captured in this Group.",
"criteria": "conversation.metadata.agentId==johndoe"
}
}

The id returned is the Group ID which is a unique identifier of the Conversation Group.

Step 2: Add metadata to Conversation#


The Conversation metadata is what defines the grouping criteria. Metadata can be important information such as the unique identifiers of internal entities like agentId, customerId, userId, etc., or custom tags such as sales call, support call, internal discussion, etc. that you’d like to maintain on a conversation.

Metadata Key-value Pairs Requirement
  • The value of the metadata field must be of type string.
  • The maximum length of the string value allowed is 128 characters.
  • Duplicate fields are not allowed in metadata.

To add metadata, modify an already processed conversation using Conversation API PUT request given below:

PUT https://api.symbl.ai/v1/conversations/{conversationId}

Request Body#

# This is an optional payload. You can pass only the metadata to receive similar results.
{
"type": "meeting",
"name": "My Business Meeting",
"startTime": "2021-02-24T15:53:05.594Z",
"endTime": "2021-02-24T16:18:05.048Z",
"members": [
{
"name": "John",
"email": "john@example.com"
},
{
"name": "Mary",
"email": "mary@example.com"
}
],
# This adds the metadata for Conversation Groups
"metadata": {
"key": "value",
"agentId": "johndoe"
}
}

Response Body#

{
"id": "4931769134481408",
"type": "meeting",
"name": "My Business Meeting",
"startTime": "2021-02-24T15:53:05.594Z",
"endTime": "2021-02-24T16:18:05.048Z",
"members": [
{
"name": "John",
"email": "john@example.com"
},
{
"name": "Mary",
"email": "mary@example.com"
}
],
"metadata": {
"key": "value",
"agentId": "johndoe"
}
}

The id returned in the Response is the Group ID which is a unique identifier of the Conversation Group.

Step 3: Fetch Grouped Results#


Now that your groups are created, you can fetch the data associated with the Conversations that match the criteria of any Conversation Group.

Additional operations like filtering, sorting, or aggregate can be performed while fetching this data.

GET https://api.symbl.ai/v1/groups/{groupId}/conversations

Path Parameters#

ParameterRequiredDescription
groupIdMandatoryUnique ID of the group created using Management API’s Create Group API endpoint.

Query Parameters#

ParameterData TypeDescriptionRequiredDefault Value
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.Optional20.
Value accepted is between 0 to 65536
offsetInteger (int16)Specifies a non-negative number of items to skip before applying limit.Optional0
orderString / enumSpecifies the order in which the results should be sorted. The order is applied on the startTime field of the associated Conversation entity.Optionalasc. Values accepted 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 entity. If startTime is not mentioned, then startTime is calculated as - startTime = endTime - duration('7 days').OptionalstartTime = endTime - duration('7 days'). Values accepted are ISO 8601 formatted strings with value less than current timestamp and less than endTime.
endTimeString / ISO 8601 date formatSpecifies the end of the date time range for the results to be returned. This endTime is associated with the endTime field of the associated Conversation entity. If endTime is not mentioned, then the current timestamp is considered as endTime automatically.OptionalendTime = currentDatetime(). Values accepted 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.Optionalconversation.startTime
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 it's filters. There is no limit on filters though, so user can add any number of filters using maximum of two parameters.
Optionalconversation.startDate <= {currentTimestamp - 7 days}.
note

When no filter is provided, it falls back to the default criteria of startTime and endTime.

Response#

The list of conversation objects is returned in the response body.

{
"conversations": [
{
"id": "4866329603473408",
"type": "meeting",
"name": "John / Mary Brainstorming",
"startTime": "2021-02-27T15:53:05.594Z",
"endTime": "2021-02-27T16:18:05.048Z",
"members": [
{
"name": "John",
"email": "john@example.com"
},
{
"name": "Mary",
"email": "mary@example.com"
}
],
"metadata": {
"key": "value",
"agentId": "johndoe"
}
},
{
"id": "4931769134481408",
"type": "meeting",
"name": "John / Mary Catch up",
"startTime": "2021-02-24T15:53:05.594Z",
"endTime": "2021-02-24T16:18:05.048Z",
"members": [],
"metadata": {
"agentId": "johndoe"
}
},
{
"id": "6866329803473407",
"type": "meeting",
"name": "John / Acme Corp Meeting",
"startTime": "2021-02-27T15:53:05.594Z",
"endTime": "2021-02-27T16:18:05.048Z",
"members": [],
"metadata": {
"customerId": "889988999",
"agentId": "johndoe"
}
},
...
]
}

Managing Conversation Groups#

You can perform CRUD operations on the Conversation Groups using the Management APIs.

For more details on these operations, go to the Conversation Groups API section.

Following are the operations you can perform with Management API for Conversation Groups:

OperationEndpoint
Create Conversation GroupPOST /v1/manage/group
Create Multiple Conversation GroupsPOST /v1/manage/groups
Get Conversation Group with IDGET /v1/manage/group/{groupId}
Get Multiple Conversation GroupsGET /v1/manage/groups
Update Conversation GroupPUT /v1/manage/group/{groupId}
Delete GroupDELETE /v1/manage/group/{groupId}
info

While working with multiple Conversation Groups, notice the use of plural groups versus group used in singular Conversation Group operations.