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


Bookmarks - Async API

This section provides basic examples of how to create a bookmark and how to create 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 bookmark, use the POST /v1/conversations/{conversationId}/bookmarks operation. 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 be 30.
  • 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.

Bookmark using time offset (Node.js)

import fetch from 'node-fetch';

const accessToken = '<ACCESS_TOKEN>';
const conversationId = '<CONVERSATION_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`, {
  method: 'post',
  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.
  • <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 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`, {
  method: 'post',
  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.
  • <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.

Create multiple bookmarks

To create multiple bookmarks at the same time, use the POST /v1/conversations/{conversationId}/bookmarks/bulk operation. You can include both bookmarks that use a time offset to determine the content of the bookmark, and bookmarks that provide a list of message refs (the ID of a message from a conversation).

import fetch from 'node-fetch';

const accessToken = '<ACCESS_TOKEN>';
const conversationId = '<CONVERSATION_ID>';
const bookmarks = [
  {
    'label': '<LABEL>',
    'description': '<DESCRIPTION>',
    'user': {
      'name': '<NAME>',
      'userId': '<USER_ID>',
      'email': '<EMAIL>'
    },
    'beginTimeOffset': <OFFSET>,
    'duration': <DURATION>
  },
  {
    '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/bulk`, {
  method: 'post',
  body: JSON.stringify(bookmarks),
  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.
  • <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_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.

FieldDescription
idThe unique identifier of the bookmark. You can use the ID to get, 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 - one bookmark

{
  "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"}
  ]
}

Example response - multiple bookmarks

{
  "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"}
      ]
    }
  ]
}

Bookmarks - Streaming API

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

ParameterRequiredDescription
typeYesValue must be bookmark_request.
operationYesValue must be create.
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 create.
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": "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
}

Did this page help you?