Manage Conversations
As you work with the Symbl.ai APIs, you may need to perform various operations to manage your conversations. This page describes how to:
- Get a list of your conversations.
- Get information about a specific conversation.
- Update the metadata for a conversation.
- Delete a conversation.
Authentication
These requests require an access token, as described in Authenticate.
Get all conversations
This request returns a list of your conversations. By default, up to 20 conversations are returned. You can use the optional query parameters to filter and change the number of results.
To get a list of your conversations, use the GET https://api.symbl.ai/v1/conversations
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/conversations" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json"
Where:
<ACCESS_TOKEN>
is a valid API access token.
For additional reference information, see Get all Conversations.
Optional query parameters
The following table describes the optional query parameters that can be used with this request.
Parameter | Data Type | Description | Default Value |
---|---|---|---|
| Integer (int16) | Specifies a non-negative integer Value must be between | 20 |
| Integer (int16) | Specifies a non-negative number of items to skip before applying the | 0 |
| 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 |
---|---|
| A list of conversations. For the response fields specific to conversations, see Get Conversation. |
Example response
{
"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": "[email protected]"
},
{
"name": "Mary",
"email": "[email protected]"
}
],
"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"
}
}
]
}
Get conversation
This request returns conversation data such as the meeting name, member names and emails, start and end time of the meeting, meeting type, meeting ID, and any custom conversation metadata that you added.
To get information about a specific conversation, use the GET https://api.symbl.ai/v1/conversations/{conversationId}
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>"
CONVERSATION_ID="<CONVERSATION_ID>"
curl --request GET \
--url "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json"
Where:
<ACCESS_TOKEN>
is a valid API access token.<CONVERSATION_ID>
is the ID of a conversation that you previously processed.
For additional reference information, see Get Conversation by ID.
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
| The unique conversation identifier. |
| The conversation type. Default value is |
| The name of the conversation. |
| DateTime value of when the conversation started. |
| DateTime value of when the conversation ended. |
| A list of member objects containing ID, name and email (if detected). |
| Contains user-defined metadata key-value pairs which are used for labeling conversations and including conversations in conversation groups. |
Example response
{
"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": "[email protected]"
},
{
"name": "Mary",
"email": "[email protected]"
}
],
"metadata": {
"key": "value",
"agentId": "johndoe"
}
}
Update conversation metadata
This request adds or updates conversation metadata. Conversation metadata is a collection of custom key-value pairs that you can use to label the conversation. Conversation metadata is also used to include conversations in Conversation Groups (Beta).
To get update the metadata for a conversation, use the PUT https://api.symbl.ai/v1/conversations/{conversationId}
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>"
CONVERSATION_ID="<CONVERSATION_ID>"
curl --request PUT \
--url "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"metadata": {
"exampleKey": "exampleValue",
"exampleKey2": "exampleValue2"
}
}'
Where:
<ACCESS_TOKEN>
is a valid API access token.<CONVERSATION_ID>
is the ID of a conversation that you previously processed.- The
metadata
object is a collection of key-value pairs that you specify. Metadata must meet the following criteria:- 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.
For additional reference information, see Update a Conversation.
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
| The unique conversation identifier. |
| An object that contains the custom key-value pairs that you specified in the request. |
Example response
{
"id":"4931769134481408",
"metadata":{
"key":"value",
"agentId":"johndoe"
}
}
Delete conversation
This request deletes a conversation and all data directly associated with the conversation ID, such as messages, action items, topics, the summary, and more. When you delete a conversation, it cannot be recovered and the conversation ID will no longer work with requests.
To delete a conversation, use the DELETE https://api.symbl.ai/v1/conversations/{conversationId}
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>"
CONVERSATION_ID="<CONVERSATION_ID>"
curl --request DELETE \
--url "https://api.symbl.ai/v1/conversations/$CONVERSATION_ID" \
--header "Authorization: Bearer $ACCESS_TOKEN" \
--header "Content-Type: application/json"
Where:
<ACCESS_TOKEN>
is a valid API access token.<CONVERSATION_ID>
is the ID of a conversation that you previously processed.
For additional reference information, see Delete a Conversation by ID.
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
| Specifies if the conversation was successfully deleted. |
Example response
{
"message": "successfully deleted the conversation"
}
Updated 5 days ago