Update bookmarks
This page describes how to update a bookmark using the Async API, and the message format for updating a bookmark with the Streaming API.
For more information about the Bookmarks feature, see Bookmarks.
Bookmarks - Async API
This section provides a basic example of how to update a bookmark 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.
Update a bookmark
To update a bookmark, use the PUT /v1/conversations/{conversationId}/bookmarks/{bookmarkId}
operation. You can update the following bookmark properties:
label
description
user.name
,user.id
, anduser.email
beginTimeOffset
duration
messageRefs
To determine the content of the bookmark, you must provide either a combination of time offset and duration, or a list of message IDs:
- When you use a time offset from the beginning of the conversation and a duration, messages that occur during the duration are included in the bookmark. For example, if you wanted to bookmark a 30-second period that starts 5 minutes into a conversation, the time offset would be
300
(5 minutes in seconds), and the duration would be30
. - When you use a list of message IDs, the list must be a group of sequential messages that occur in the conversation. Message IDs can be retrieved using Get messages.
If you want to keep an existing value for a property, such as the current bookmark label or the list of message IDs in messageRefs
, you must include that existing value when you make the request. For example, if you do not provide a value for description
when you update a bookmark, any existing description is removed rather than preserved.
Bookmark using time offset (Node.js)
import fetch from 'node-fetch';
const accessToken = '<ACCESS_TOKEN>';
const conversationId = '<CONVERSATION_ID>';
const bookmarkId = '<BOOKMARK_ID>';
const bookmarkParams = {
'label': '<LABEL>',
'description': '<DESCRIPTION>',
'user': {
'name': '<NAME>',
'userId': '<USER_ID>',
'email': '<EMAIL>'
},
'beginTimeOffset': <OFFSET>,
'duration': <DURATION>
}
const fetchResponse = await fetch(`https://api.symbl.ai/v1/conversations/${conversationId}/bookmarks/${bookmarkId}`, {
method: 'put',
body: JSON.stringify(bookmarkParams),
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.<LABEL>
is a short label for the bookmark.<DESCRIPTION>
is a description of the bookmark.<NAME>
is the name of the user that creates the bookmark.<USER_ID>
is a unique ID for the user that creates the bookmark. For example, the user’s email address.<EMAIL>
is the email address of the user that creates the bookmark.<OFFSET>
is the number of seconds from the beginning of the conversation. The bookmark starts capturing messages at the offset.<DURATION>
is the number of seconds from the offset. The bookmark captures messages that occur during the duration.
For additional details about the request body parameters for this request, see Request body parameters.
Bookmark using message IDs (Node.js)
import fetch from 'node-fetch';
const accessToken = '<ACCESS_TOKEN>';
const conversationId = '<CONVERSATION_ID>';
const bookmarkId = '<BOOKMARK_ID>';
const bookmarkParams = {
'label': '<LABEL>',
'description': '<DESCRIPTION>',
'user': {
'name': '<NAME>',
'userId': '<USER_ID>',
'email': '<EMAIL>'
},
'messageRefs': [
{'id': '<MESSAGE_ID>'},
{'id': '<MESSAGE_ID>'},
...
]
}
const fetchResponse = await fetch(`https://api.symbl.ai/v1/conversations/${conversationId}/bookmarks/${bookmarkId}`, {
method: 'put',
body: JSON.stringify(bookmarkParams),
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.<LABEL>
is a short label for the bookmark.<DESCRIPTION>
is a description of the bookmark.<NAME>
is the name of the user that creates the bookmark.<USER_ID>
is a unique ID for the user that creates the bookmark. For example, the user’s email address.<EMAIL>
is the email address of the user that creates the bookmark.<MESSAGE_ID>
is the ID of a message from your conversation. You can provide one or more message IDs. You can obtain message IDs from speech-to-text transcripts.
For additional details about the request body parameters for this request, see Request body parameters.
Request body parameters
The following table describes the body parameters that can be used with this request.
Parameter | Required | Description |
---|---|---|
label | Yes | Short label for a bookmark. Can be the same value as other bookmarks. |
description | No | Description of the contents of the bookmark. |
user | Yes | Describes the user that creates the bookmark. |
user.name | Yes | Name of the user that creates the bookmark. |
user.userId | Yes | Unique ID for the user that creates the bookmark. For example, the user’s email address. |
user.email | Yes | Email address of the user that creates the bookmark. |
beginTimeOffset | Yes | In seconds, an amount of time from the beginning of the conversation before the bookmark starts including messages. Only messages that fall after the offset are included in the bookmark. Required if duration is included. |
duration | Yes | In seconds, an amount of time from the offset. Messages that occur during the duration are included in the bookmark. Required if beginTimeOffset is included. |
messageRefs | Yes | List of objects. Each object represents an individual message from the conversation. Message objects must use the following format: "id": "<MESSAGE_ID>" . |
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 get, 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"}
]
}
Bookmarks - Streaming API
This section provides the message format for updating a bookmark using WebSockets and the Streaming API.
Update a bookmark
To update a bookmark with the Streaming API during a conversation, send the following WebSocket message:
ws.send(JSON.stringify({
'type': 'bookmark_request',
'operation': 'update',
'id': '<BOOKMARK_ID>',
'label': '<LABEL>',
'description': '<DESCRIPTION>',
'user': {
'name': '<NAME>',
'userId': '<USER_ID>',
'email': '<EMAIL>'
},
'beginTimeOffset': <OFFSET>,
'duration': <DURATION>
}));
Where:
<BOOKMARK_ID>
is the ID of a bookmark that you created during the conversation.<LABEL>
is a short label for the bookmark.<DESCRIPTION>
is a description of the bookmark.<NAME>
is the name of the user that creates the bookmark.<USER_ID>
is a unique ID for the user that creates the bookmark. For example, the user’s email address.<EMAIL>
is the email address of the user that creates the bookmark.<OFFSET>
is the number of seconds from the beginning of the conversation. The bookmark starts capturing messages at the offset.<DURATION>
is the number of seconds from the offset. The bookmark captures messages that occur during the duration.
Message parameters
The following table describes the parameters that can be used with this message.
Parameter | Required | Description |
---|---|---|
type | Yes | Value must be bookmark_request . |
operation | Yes | Value must be update . |
label | Yes | Short label for a bookmark. Can be the same value as other bookmarks. |
description | No | Description of the contents of the bookmark. |
user | Yes | Describes the user that creates the bookmark. |
user.name | Yes | Name of the user that creates the bookmark. |
user.userId | Yes | Unique ID for the user that creates the bookmark. For example, the user’s email address. |
user.email | Yes | Email address of the user that creates the bookmark. |
beginTimeOffset | Yes | In seconds, an amount of time from the beginning of the conversation before the bookmark starts including messages. Only messages that fall after the offset are included in the bookmark. |
duration | Yes | In seconds, an amount of time from the offset. Messages that occur during the duration are included in the bookmark. |
Response
The following table describes the response body that is returned by this request.
Field | Description |
---|---|
type | The value is bookmark_response . |
operation | The value is update . |
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
{
"type": "bookmark_response",
"operation": "update",
"id": "6428584355823616",
"label": "pain point",
"description": "Customer found the interface difficult to use.",
"user": {
"name": "natalie",
"userId": "[email protected]",
"email": "[email protected]"
},
"beginTimeOffset": 10,
"duration": 15
}
Updated 4 months ago