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

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