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:

• 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

Response

The following table describes the response body that is returned by this 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

Response

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

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.

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.

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.

Response

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

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

Response

The following table describes the response body that is returned by this 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.

Example response

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