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 this feature, see Bookmarks.


Bookmarks - Async API

This section describes 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 following operation:

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

To make this request from the API reference, see Update bookmark.


Bookmarks - Streaming API

This section provides the message format for updating a bookmark using WebSocket 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.

ParameterRequiredDescription
typeYesValue must be bookmark_request.
operationYesValue must be update.
labelYesShort label for a bookmark. Can be the same value as other bookmarks.
descriptionNoDescription of the contents of the bookmark.
userYesDescribes the user that creates the bookmark.
user.nameYesName of the user that creates the bookmark.
user.userIdYesUnique ID for the user that creates the bookmark. For example, the user’s email address.
user.emailYesEmail address of the user that creates the bookmark.
beginTimeOffsetYesIn 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.
durationYesIn 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.

FieldDescription
typeThe value is bookmark_response.
operationThe value is update.
idThe unique identifier of the bookmark. You can use the ID to update and delete the bookmark.
labelA short label for the bookmark.
descriptionA description of the bookmark.
userAn object that contains details about the user that created the bookmark.
user.nameThe name of the user that created the bookmark.
user.userIdThe unique ID of the user that created the bookmark.
user.emailThe email address of the user that created the bookmark.
beginTimeOffsetIn seconds from the beginning of the conversation, when the bookmark starts capturing messages.
durationIn seconds, how long the bookmark captures messages.
messageRefsA 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
}