Create bookmarks

This page describes how to create individual bookmarks and bookmarks in bulk using the Async API, and the message format for creating bookmarks with the Streaming API.

For more information about this feature, see Bookmarks.

Bookmarks - Async API

This section describes how to create a single bookmark or multiple bookmarks at one time 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.

Create a bookmark

To create a single bookmark, use the following operation:

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

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

Create multiple bookmarks

To create multiple bookmarks at the same time, use the following operation:

POST https://api.symbl.ai/v1/conversations/{conversationId}/bookmarks/bulk

To make this request from the API reference, see Create bookmarks.

Bookmarks - Streaming API

This section provides the message format for creating a bookmark using WebSocket and the Streaming API.

Create a bookmark

To create a bookmark with the Streaming API, start a streaming conversation, and then send the following WebSocket message:

ws.send(JSON.stringify({
  'type': 'bookmark_request',
  'operation': 'create',
  'label': '<LABEL>',
  'description': '<DESCRIPTION>',
  'user': {
    'name': '<NAME>',
    'userId': '<USER_ID>',
    'email': '<EMAIL>'
  },
  'beginTimeOffset': <OFFSET>,
  'duration': <DURATION>
}));

Where:

<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 `create`.
`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 `create`.
`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.

Example response

{
  "type": "bookmark_response",
  "operation": "create",
  "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
}