Get bookmarks
This page describes how to get bookmarks from a conversation.
For more information about the Bookmarks feature, see Bookmarks.
Bookmarks - Async API
This section provides basic examples of how to get one bookmark or all of your bookmarks using the Async API. This request requires a conversation ID. You receive a conversation ID when you process a conversation with the Symbl.ai APIs.
Authentication
These requests require an access token, as described in Authenticate.
Get a bookmark
To get a bookmark in a conversation, use the GET /v1/conversations/{conversationId}/bookmarks/{bookmarkId}
operation.
import fetch from 'node-fetch';
const accessToken = '<ACCESS_TOKEN>';
const conversationId = '<CONVERSATION_ID>';
const bookmarkId = '<BOOKMARK_ID>';
const fetchResponse = await fetch(`https://api.symbl.ai/v1/conversations/${conversationId}/bookmarks/${bookmarkId}`, {
method: 'get',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
const responseBody = await fetchResponse.json();
console.log(responseBody);
Where:
<ACCESS_TOKEN>
is a valid API access token.<CONVERSATION_ID>
is the ID of a conversation that you previously processed.<BOOKMARK_ID>
is the ID of a bookmark that you previously created.
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
id | The unique identifier of the bookmark. You can use the ID to update and delete the bookmark. |
label | A short label for the bookmark. |
description | A description of the bookmark. |
user | An object that contains details about the user that created the bookmark. |
user.name | The name of the user that created the bookmark. |
user.userId | The unique ID of the user that created the bookmark. |
user.email | The email address of the user that created the bookmark. |
beginTimeOffset | In seconds from the beginning of the conversation, when the bookmark starts capturing messages. |
duration | In seconds, how long the bookmark captures messages. |
messageRefs | A list of the messages that occurred during the duration of the bookmark. |
Example Response
{
"id": "6428584355823616",
"label": "pain point",
"description": "Customer found the interface difficult to use.",
"user": {
"name": "natalie",
"userId": "[email protected]",
"email": "[email protected]"
},
"beginTimeOffset": 20,
"duration": 30,
"messageRefs": [
{"id": "4808748496322560"},
{"id": "5939064753618944"}
]
}
Get multiple bookmarks
To get multiple bookmarks at one time in a conversation, use the GET /v1/conversations/{conversationId}/bookmarks
operation.
import fetch from 'node-fetch';
const accessToken = '<ACCESS_TOKEN>';
const conversationId = '<CONVERSATION_ID>';
const fetchResponse = await fetch(`https://api.symbl.ai/v1/conversations/${conversationId}/bookmarks`, {
method: 'get',
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json'
}
});
const responseBody = await fetchResponse.json();
console.log(responseBody);
Where:
<ACCESS_TOKEN>
is a valid API access token.<CONVERSATION_ID>
is the ID of a conversation that you previously processed.
Optional query parameters
The following table describes the optional query parameters that can be used with this request.
Parameter | Description |
---|---|
filter | Specified in RSQL format, bookmarks are only returned if they match the filter. You can filter bookmarks by any combination of bookmark properties. See the following example filters: Filter by label: filter=bookmark.label=="pain point" Filter by user property: filter=bookmark.user.userId=="[email protected]" Filter by label and user property: filter=bookmark.label=="pain point";bookmark.user.userId=="[email protected]" Filter by time offset: filter=bookmark.beginTimeOffset>30 |
Example URL with query parameters
https://api.symbl.ai/v1/conversations/${conversationId}/bookmarks?filter=bookmark.label%3D%3D%22pain%20point%22
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
bookmarks | A list of bookmarks. For the response fields specific to an individual bookmark, see Get a Bookmark. |
Example response
{
"bookmarks": [
{
"id": "6428584355823616",
"label": "pain point",
"description": "Customer found the interface difficult to use.",
"user": {
"name": "natalie",
"userId": "[email protected]",
"email": "[email protected]"
},
"beginTimeOffset": 20,
"duration": 30,
"messageRefs": [
{"id": "4808748496322560"},
{"id": "5939064753618944"}
]
},
{
"id": "5128574352833111",
"label": "pain point",
"description": "Customer couldn’t find the start button.",
"user": {
"name": "natalie",
"userId": "[email protected]",
"email": "[email protected]"
},
"beginTimeOffset": 60,
"duration": 15,
"messageRefs": [
{"id": "1458484963311473"},
{"id": "2535034753613139"}
]
}
]
}
Updated 4 months ago