# CLAUDE
Source: https://docs.velt.dev/CLAUDE
# Rewriter
Source: https://docs.velt.dev/ai-copilot/design/overview
Let AI suggest improvements to your website text
Import the `useVeltClient` React hook.
You can use this hook within your component to fetch the Velt client.
```js React theme={null}
let { client } = useVeltClient();
```
Create a `useEffect` hook with the client as dependency.
```js React theme={null}
useEffect(() => {
//code to enable Rewriter
}, [client]);
```
`Rewriter` is not enabled by default.
Within the `useEffect` hook, call `client.getRewriterElement()` and then `enableRewriter()` on the returned object to enable `Rewriter`.
Now when a user highlights text on your website, the `Rewriter` tool will pop up.
```js React theme={null}
const rewriterElement = client.getRewriterElement();
rewriterElement.enableRewriter();
rewriterElement.disableRewriter(); //to disable
```
Test out `Rewriter` by highlighting some text.
`Rewriter` is not enabled by default.
Call `Velt.getRewriterElement()` and then `enableRewriter()` on the returned object to enable `Rewriter`.
Now when a user highlights text on your website, the `Rewriter` tool will pop up.
```js theme={null}
if (Velt) {
const rewriterElement = Velt.getRewriterElement();
rewriterElement.enableRewriter();
rewriterElement.disableRewriter(); //to disable
}
```
Test out `Rewriter` by highlighting some text.
```js React / Next.js theme={null}
import { useEffect } from "react";
import { useVeltClient } from "@veltdev/react";
export default function App() {
let { client } = useVeltClient();
useEffect(() => {
if (client) {
//Enable Rewriter
const rewriterElement = client.getRewriterElement();
rewriterElement.enableRewriter();
rewriterElement.disableRewriter(); //to disable
}
}, [client]);
return (
// your app template
);
}
```
```html HTML theme={null}
Collaboration App
```
# Generate Token
Source: https://docs.velt.dev/api-reference/rest-apis/v1/auth/generate-token
POST https://api.velt.dev/v1/auth/token/get
Use this API to generate a JWT token used by your client to authenticate with Velt. The token encodes user information and optional properties such as organization and admin status.
* JWT token expires in 48 hours.
* For v1, `apiKey` and `authToken` are provided in the request body (not headers).
# Endpoint
`POST https://api.velt.dev/v1/auth/token/get`
# Headers
application/json
# Body
#### Params
Your Velt API Key.
Your Auth Token from the Velt console. See Auth Tokens .
Unique identifier for the user.
Organization ID. Should match the `organizationId` used in the `identify` call.
Whether the user has admin privileges. This is the only supported way to set a user as admin. Do not set this in the `identify` call.
User email. If provided, it is validated against the email used in the `identify` call.
## **Example Requests**
#### Generate token with organization and admin
```JSON theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY",
"authToken": "YOUR_AUTH_TOKEN",
"userId": "yourUserId",
"userProperties": {
"isAdmin": true,
"organizationId": "YOUR_ORGANIZATION_ID",
"email": "user@example.com"
}
}
}
```
#### Minimal token request
```JSON theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY",
"authToken": "YOUR_AUTH_TOKEN",
"userId": "yourUserId",
"userProperties": {
"organizationId": "YOUR_ORGANIZATION_ID"
}
}
}
```
# Response
Generate the JWT token on your server, not your client, to keep your secrets secure.
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Token generated successfully.",
"data": {
"token": "YOUR_JWT_TOKEN"
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "Auth token not found.",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Token generated successfully.",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
}
```
# Add Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comment-annotations/add-comment-annotations
POST https://api.velt.dev/v1/commentannotations/add
Use this API to add comment annotations to a document within an organization.
* You can add comments on an elemement, text or page.
* You can provide HTML or text content.
* Additional filters can be applied using location IDs.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Custom Annotation ID. If not provided, Velt will generate a unique ID for the annotation.
Location ID
Location Name
Target Element
Element DOM Id
Target Text. Provide this if you want to add comment annotation on the provided text content.
Occurrence. Provide this if you want to add comment annotation on a text content.
Select All Content. Provide this if you want to select and add comment annotation on the entire text content of the target elementId.
Array of Comment Data
Custom Comment ID. If not provided, Velt will generate a unique ID for the comment.
Comment content in plain text string
Comment content in HTML string
Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.
Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.
User object from whom the comment is added
Created At timestamp (in milliseconds since epoch).
Last Updated timestamp (in milliseconds since epoch).
Array of tagged user contacts
Display text of the tagged user (e.g. "@Username")
User ID of the tagged user
Email of the tagged user
Name of the tagged user
User ID of the tagged user
Status
Status ID
Status Name
Type.
Text and comment pin color
Background color on the status indicator
Raw SVG of the icon. Either `svg` or `iconUrl` is required.
Icon URL. Either `svg` or `iconUrl` is required.
User object to whom the comment is assigned
Custom key/value metadata object
Created At timestamp (in milliseconds since epoch).
Last Updated timestamp (in milliseconds since epoch).
Priority
Priority ID
Priority Color
Priority Name
Priority Light Color
## **Example Requests**
#### Add comment annotation by organizationId, documentId and location
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"commentAnnotations": [
{
"location": {
"id": "yourLocationId",
"locationName": "yourLocationName"
},
"targetElement": {
"elementId": "yourElementId",
"targetText": "Your Target Text",
"occurrence": 1,
"selectAllContent": false
},
"commentData": [
{
"commentText": "Sample Comment",
"commentHtml": "Sample Comment
",
"from": {
"userId": "yourUserId",
"name": "yourUserName",
"email": "yourUserEmail",
}
}
]
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
```
# Delete Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comment-annotations/delete-comment-annotations
POST https://api.velt.dev/v1/commentannotations/delete
Use this API to delete comment annotations from a document within an organization.
Additional filters can be applied using location IDs, annotation IDs, or user IDs.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Array of Location IDs
Array of Annotation IDs
Array of User IDs
## **Example Requests**
#### 1. Delete annotations by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId"
}
}
```
#### 2. Delete annotations by organizationId, documentId and locationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
]
}
}
```
#### 3. Delete annotations by organizationId, documentId, locationIds and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
]
}
}
```
#### 4. Delete annotations by organizationId, documentId and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
]
}
}
```
#### 5. Delete annotations by organizationId, documentId and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
#### 6. Delete annotations by organizationId, documentId, locationIds and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
#### 7. Delete annotations by documentId. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId"
}
}
```
#### 8. Delete annotations by documentId and locationIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
]
}
}
```
#### 9. Delete annotations by documentId and userIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
]
}
}
```
#### 10. Delete annotations by documentId and annotationIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
#### 11. Delete annotations by documentId, locationIds, and userIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
]
}
}
```
#### 12. Delete annotations by documentId, locationIds, and annotationIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Annotations deleted successfully.",
"data": {
"yourAnnotationId1": {
"success": true,
"id": "yourAnnotationId",
"message": "Deleted Successfully"
},
"yourAnnotationId2": {
"success": false,
"id": "yourAnnotationId2",
"message": "Annotation not found."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Annotations deleted successfully.",
"data": {
"yourAnnotationId": {
"success": true,
"id": "yourAnnotationId",
"message": "Deleted Successfully"
}
}
}
}
```
# Get Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comment-annotations/get-comment-annotations
POST https://api.velt.dev/v1/commentannotations/get
Use this API to retrieve comment annotations from a document within an organization.
Additional filters can be applied using location IDs, annotation IDs, or user IDs.
Use this for SDK v3 or prior versions.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Array of Location IDs. Limit: Only 30 IDs can be passed at a time.
Array of Annotation IDs. Limit: Only 30 IDs can be passed at a time.
Array of User IDs. Limit: Only 30 IDs can be passed at a time.
## **Example Requests**
#### 1. Get annotations by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
}
}
```
#### 2. Get annotations by organizationId, documentId, and locationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
}
}
```
#### 3. Get annotations by organizationId, documentId, locationIds, and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
],
}
}
```
#### 4. Get annotations by organizationId, documentId, and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
],
}
}
```
#### 5. Get annotations by organizationId, documentId, and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
}
}
```
#### 6. Get annotations by organizationId, documentId, locationIds, and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Annotations fetched successfully.",
"data": [
{
"annotationId": "yourAnnotationId",
"comments": [
{
"commentId": 123456,
"commentText": "This is a sample comment text.",
"commentHtml": "This is a sample comment text.
",
"from": {
"userId": "user123",
"name": "John Doe",
"email": "john.doe@example.com"
},
"lastUpdated": "2023-06-15T10:30:00Z"
}
],
"from": {
"userId": "user123",
"name": "John Doe",
"email": "john.doe@example.com"
},
"color": "#00FF00",
"createdAt": "2023-06-15T10:30:00Z",
"lastUpdated": "2023-06-15T10:30:00Z",
"status": {
"id": "OPEN",
"name": "Open",
"color": "#0000FF",
"type": "default"
}
},
null // null is returned only if you provided an annotationId that doesn't exist
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Annotations fetched successfully.",
"data": [
{
"annotationId": "yourAnnotationId",
"comments": [
{
"commentId": 123456,
"commentText": "This is a sample comment text.",
"commentHtml": "This is a sample comment text.
",
"from": {
"userId": "user123",
"name": "John Doe",
"email": "john.doe@example.com"
},
"lastUpdated": "2023-06-15T10:30:00Z",
"type": "text",
}
],
"from": {
"userId": "user123",
"name": "John Doe",
"email": "john.doe@example.com"
},
"color": "#00FF00",
"createdAt": "2023-06-15T10:30:00Z",
"lastUpdated": "2023-06-15T10:30:00Z",
"status": {
"id": "OPEN",
"name": "Open",
"color": "#0000FF",
"type": "default"
}
},
null // null is returned only if you provided an annotationId that doesn't exist
]
}
}
```
# Get Comment Annotations Count
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comment-annotations/get-comment-annotations-count
POST https://api.velt.dev/v1/commentannotations/count/get
Use this API to retrieve the count of comment annotations for specified documents, including both total and unread counts.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/count/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of document IDs to get comment annotation counts for. Limit: Only 30 IDs can be passed at a time.
ID of the user requesting the counts
Array of status IDs to filter comments by (e.g., "OPEN", "IN\_PROGRESS")
#### **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "ORG_ID",
"documentIds": ["DOC_1", "DOC_2"],
"userId": "1.1",
"statusIds": ["OPEN", "IN_PROGRESS"]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment count retrieved successfully.",
"data": {
"DOC_1": {
"total": 4,
"unread": 2
},
"DOC_2": {
"total": 2,
"unread": 0
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment count retrieved successfully.",
"data": {
"DOC_1": {
"total": 4,
"unread": 2
},
"DOC_2": {
"total": 2,
"unread": 0
}
}
}
}
```
# Update Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comment-annotations/update-comment-annotations
POST https://api.velt.dev/v1/commentannotations/update
Use this API to update comment annotations in a document within an organization.
Additional filters can be applied using location IDs, annotation IDs, or user IDs.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Array of Location IDs
Array of User IDs. These are the users who created the comment annotation.
Array of Annotation IDs
Location ID
Location Name
Target Element
Element DOM Id
Target Text. Provide this if you want to add comment annotation on the provided text content.
Occurrence. Provide this if you want to add comment annotation on a text content.
Select All Content. Provide this if you want to select and add comment annotation on the entire text content of the target elementId.
User object from whom the Comment Annotation is added
Status
Status ID
Status Name
Type.
Text and comment pin color
Background color on the status indicator
Raw SVG of the icon.
Icon URL.
User object to whom the comment is assigned
Custom key/value metadata object
Priority
Priority ID
Priority Name
Priority Color
Priority Light Color
Old user's ID
Old user's name
Old user's email
New user's ID
New user's name
New user's email
## **Example Requests**
#### 1. Update all comment annotations by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"updatedData" : {
"status": {
"type": "ongoing"
}
}
}
}
```
#### 2. Update comment annotations by organizationId, documentId and locationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"updatedData" : {
"status": {
"type": "ongoing"
}
}
}
}
```
#### 3. Update annotations by organizationId, documentId, locationIds and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
],
"updatedData" : {
"status": {
"type": "ongoing"
}
}
}
}
```
#### 4. Update comment annotations by organizationId, documentId and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
],
"updatedData" : {
"status": {
"type": "ongoing"
}
}
}
}
```
#### 5. Update comment annotations by organizationId, documentId and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"type": "ongoing"
}
}
}
}
```
#### 6. Update comment annotations by organizationId, documentId, locationIds and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"type": "ongoing"
}
}
}
}
```
#### 7. Update Users in existing comment annotations
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updateUsers" : [
{
"oldUser": {
"userId": "oldUserId",
},
"newUser": {
"userId": "newUserId",
"name": "newUserName",
"email": "newUserEmail"
}
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Annotations updated successfully.",
"data": {
"yourAnnotationId1": {
"success": true,
"id": "yourAnnotationId1",
"message": "Annotations updated successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Annotations updated successfully.",
"data": {
"yourAnnotationId1": {
"success": true,
"id": "yourAnnotationId1",
"message": "Annotations updated successfully"
}
}
}
}
```
# Add Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comments/add-comments
POST https://api.velt.dev/v1/commentannotations/comments/add
Use this API to add comments within a specific CommentAnnotation.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/comments/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Comment Annotation ID
Array of Comment Data
Custom Comment ID. If not provided, Velt will generate a unique ID for the comment.
Comment content in plain text string
Comment content in HTML string
Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.
Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.
User object from whom the comment is added
Created At timestamp (in milliseconds since epoch).
Last Updated timestamp (in milliseconds since epoch).
Array of tagged user contacts
Display text of the tagged user (e.g. "@Username")
User ID of the tagged user
Email of the tagged user
Name of the tagged user
User ID of the tagged user
## **Example Requests**
#### 1. Add comment in a CommentAnnotation by organizationId, documentId, and annotationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentData": [
{
"commentText": "Sample Comment",
"commentHtml": "Hello
",
"from": {
"userId": "yourUserId"
}
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment(s) added successfully.",
"data": [
778115
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comment(s) added successfully.",
"data": [
778115
]
}
}
```
# Delete Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comments/delete-comments
POST https://api.velt.dev/v1/commentannotations/comments/delete
Use this API to delete comments within a specific CommentAnnotation.
Additional filters can be applied using comment IDs.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/comments/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Comment Annotation ID
Array of Comment IDs
## **Example Requests**
#### 1. Delete all comments of a CommentAnnotation by organizationId, documentId, and annotationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId"
}
}
```
#### 2. Delete specific comments of a CommentAnnotation by organizationId, documentId, annotationId and commentIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentIds": [
153783,
607395
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) deleted successfully.",
"data": {
"153783": {
"success": true,
"id": 153783,
"message": "Deleted successfully"
},
"607395": {
"success": false,
"id": 607395,
"message": "Not found"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) deleted successfully.",
"data": {
"153783": {
"success": true,
"id": 153783,
"message": "Deleted successfully"
}
}
}
}
```
# Get Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comments/get-comments
POST https://api.velt.dev/v1/commentannotations/comments/get
Use this API to retrieve comments in a specific CommentAnnotation.
Additional filters can be applied using comment IDs.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/comments/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Comment Annotation ID
User IDs
Array of Comment IDs
## **Example Requests**
#### 1. Get all comments with a CommentAnnotation by organizationId, documentId, and annotationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId"
}
}
```
#### 2. Get specific comments of a CommentAnnotation by organizationId, documentId, annotationId and commentIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentIds": [
153783,
607395
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) retrieved successfully.",
"data": [
{
"commentHtml": "Hello Updated 2
",
"commentId": 153783,
"commentText": "Sample Comment Text",
"from": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"lastUpdated": "2024-06-20T09:53:42.258Z",
"status": "added",
"type": "text"
},
null // If comment not found
]
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) retrieved successfully.",
"data": [
{
"commentHtml": "Hello Updated 2
",
"commentId": 153783,
"commentText": "Sample Comment Text",
"from": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"lastUpdated": "2024-06-20T09:53:42.258Z",
"status": "added",
"type": "text"
}
]
}
}
```
# Update Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v1/comments-feature/comments/update-comments
POST https://api.velt.dev/v1/commentannotations/comments/update
Use this API to update comments within a specific CommentAnnotation.
# Endpoint
`POST https://api.velt.dev/v1/commentannotations/comments/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Comment Annotation ID
Comment IDs
Comment data
Comment content in plain text string
Comment content in HTML string
Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.
Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.
User object from whom the comment is added
Array of tagged user contacts
Display text of the tagged user (e.g. "@Username")
User ID of the tagged user
Email of the tagged user
Name of the tagged user
User ID of the tagged user
## **Example Requests**
#### Update comment in a CommentAnnotation by organizationId, documentId, annotationId and commentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentIds": [
153783,
607395
],
"updatedData": {
"commentText": "Sample Updated Comment",
"commentHtml": "Hello Updated
"
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment updated successfully.",
"data": {
"607395": {
"success": true,
"id": 607395,
"message": "Updated successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comment updated successfully.",
"data": {
"607395": {
"success": true,
"id": 607395,
"message": "Updated successfully"
}
}
}
}
```
# Add Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v1/documents/add-documents
POST https://api.velt.dev/v1/organizations/documents/add
Use this API to add documents with metadata to an organization.
# Endpoint
`POST https://api.velt.dev/v1/organizations/documents/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document objects
Folder ID to add the documents to.
## **Example Requests**
#### 1. Create new documents
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documents": [
{
"documentId": "yourDocumentId",
"documentName": "Your Document Name"
}
]
}
}
```
#### 2. Create new documents in a specific folder
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documents": [
{
"documentId": "yourDocumentId",
"documentName": "Your Document Name"
}
],
"folderId": "yourFolderId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) added successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Added Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) added successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Added Successfully"
}
}
}
}
```
# Delete Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v1/documents/delete-documents
POST https://api.velt.dev/v1/organizations/documents/delete
Use this API to delete specific documents from an organization.
# Endpoint
`POST https://api.velt.dev/v1/organizations/documents/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) deleted successfully.",
"data": {
"yourDocumentId1": {
"success": true,
"id": "6737987049068973",
"message": "Deleted Successfully"
},
"yourDocumentId2": {
"success": true,
"id": "2131443384150904",
"message": "Document does not exist"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) deleted successfully.",
"data": {
"yourDocumentId1": {
"success": true,
"id": "6737987049068973",
"message": "Deleted Successfully"
}
}
}
}
```
# Get Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v1/documents/get-documents
POST https://api.velt.dev/v1/organizations/documents/get
Use this API to retrieve specific documents or all documents from an organization.
Use this for SDK v3 or prior versions.
# Endpoint
`POST https://api.velt.dev/v1/organizations/documents/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs. Limit: Only 30 IDs can be passed at a time.
## **Example Requests**
#### 1. Get all documents from organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
}
}
```
#### 2. Get specific documents from organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"],
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) retrieved successfully.",
"data": [
{
"documentName": "yourDocumentName",
"disabled": false,
"accessType": "public",
"id": "yourDocumentId",
}
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) retrieved successfully.",
"data": [
{
"documentName": "yourDocumentName",
"disabled": false,
"accessType": "public",
"id": "yourDocumentId",
}
]
}
}
```
# Move Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v1/documents/move-documents
POST https://api.velt.dev/v1/organizations/documents/move
Use this API to move documents to a different folder within an organization.
# Endpoint
`POST https://api.velt.dev/v1/organizations/documents/move`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs. Limit: Only 30 IDs can be passed at a time.
ID of the folder where documents will be moved
## **Example Requests**
#### Move documents to a folder
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"],
"folderId": "targetFolderId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Documents moved successfully."
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Documents moved successfully."
}
}
```
# Update Access for Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v1/documents/update-document-access
POST https://api.velt.dev/v1/organizations/documents/access/update
Use this API to update the access type for a single or multiple documents at once.
You can update the default access type for all the documents associated with your API Key in [console](https://console.velt.dev/dashboard/config/appconfig).
# Endpoint
`https://api.velt.dev/v1/organizations/documents/access/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs
Access type for the documents. Allowed values: `organizationPrivate`, `restricted`, `public`.
[Learn more](/key-concepts/overview#access-control).
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1, yourDocumentId2"],
"accessType": "organizationPrivate"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated access for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Document access type updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated access for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Document access type updated."
}
}
}
}
```
# Update Disabled State for Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v1/documents/update-document-disable-state
POST https://api.velt.dev/v1/organizations/documents/access/disablestate/update
Use this API to enable or disable both read and write access for all users.
Let's say your customer's trial or subscription has ended and you want to disable their access to the Velt data, you could use this to diable access to specific documents.
# Endpoint
`https://api.velt.dev/v1/organizations/documents/access/disablestate/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs
Whether to disable read and write access to the specified documents. Allowed values: `true`, `false`
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId"],
"disabled": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"disabled": true,
"message": "Document disabled state updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"disabled": true,
"message": "Document disabled state updated."
}
}
}
}
```
# Update Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v1/documents/update-documents
POST https://api.velt.dev/v1/organizations/documents/update
Use this API to update metadata of documents within an organization.
# Endpoint
`POST https://api.velt.dev/v1/organizations/documents/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document objects
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documents": [
{
"documentId": "yourDocumentId",
"documentName": "Your Document Name"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) updated successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Updated Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) updated successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Updated Successfully"
}
}
}
}
```
# Add Folder
Source: https://docs.velt.dev/api-reference/rest-apis/v1/folders/add-folder
POST https://api.velt.dev/v1/organizations/folders/add
Use this API to create a new folder in an organization.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v1/organizations/folders/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Unique identifier for the new folder
Name of the folder
ID of the parent folder
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folders": [
{
"folderId": "yourFolderId",
"folderName": "yourFolderName",
"parentFolderId": "yourParentFolderId"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder created successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder added."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Folder created successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder added."
}
}
}
}
```
# Get Folders
Source: https://docs.velt.dev/api-reference/rest-apis/v1/folders/get-folders
POST https://api.velt.dev/v1/organizations/folders/get
Use this API to retrieve the given folder's metadata and its subfolders.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v1/organizations/folders/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Folder ID to retrieve a specific folder and its subfolders. If not provided, all folders in the organization will be retrieved.
## **Example Requests**
#### 1. Get all folders in organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId"
}
}
```
#### 2. Get specific folder in an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId"
}
}
```
# Response
#### Success Response for All Folders
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folders retrieved successfully.",
"data": [
{
"folderId": "folderId1",
"folderName": "Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "root",
"createdAt": 1738695615706,
"lastUpdated": 1738696287859
},
{
"folderId": "folderId2",
"folderName": "Folder 2",
"organizationId": "yourOrganizationId",
"parentFolderId": "root",
"createdAt": 1738695077691,
"lastUpdated": 1738695077691
}
]
}
}
```
#### Success Response for Specific Folder
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folders retrieved successfully.",
"data": [
{
"folderId": "folderId1",
"folderName": "Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "root",
"createdAt": 1738695077691,
"lastUpdated": 1738695077691,
"subFolders": [
{
"folderId": "childFolderId1",
"folderName": "Child Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "folderId1",
"createdAt": 1738695615706,
"lastUpdated": 1738698727591
}
]
}
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Folders retrieved successfully.",
"data": [
{
"folderId": "folderId1",
"folderName": "Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "root",
"createdAt": 1738695077691,
"lastUpdated": 1738695077691,
"subFolders": [
{
"folderId": "childFolderId1",
"folderName": "Child Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "folderId1",
"createdAt": 1738695615706,
"lastUpdated": 1738698727591
}
]
}
]
}
}
```
# Update Folder
Source: https://docs.velt.dev/api-reference/rest-apis/v1/folders/update-folder
POST https://api.velt.dev/v1/organizations/folders/update
Use this API to:
1. update metadata of a folder within an organization.
2. move a folder and its contents to a different parent folder.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v1/organizations/folders/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Unique identifier for the new folder
Name of the folder
ID of the parent folder
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folders": [
{
"folderId": "yourFolderId",
"folderName": "yourFolderName",
"parentFolderId": "yourParentFolderId"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder Updated successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder Updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Folder Updated successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder Updated."
}
}
}
}
```
# Update Access for Folders
Source: https://docs.velt.dev/api-reference/rest-apis/v1/folders/update-folder-access
POST https://api.velt.dev/v1/organizations/folders/access/update
Use this API to update the access type for a single or multiple folders at once.
You can update the default access type for all the folders associated with your API Key in [console](https://console.velt.dev/dashboard/config/appconfig).
# Endpoint
`https://api.velt.dev/v1/organizations/folders/access/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Folder IDs
Access type for the folders. Allowed values: `organizationPrivate`, `restricted`, `public`.
[Learn more](/key-concepts/overview#access-control).
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderIds": ["yourFolderId1, yourFolderId2"],
"accessType": "organizationPrivate"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated access for folders successfully.",
"data": {
"yourFolderId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Folder access type updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated access for folders successfully.",
"data": {
"yourFolderId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Folder access type updated."
}
}
}
}
```
# Delete All User Data
Source: https://docs.velt.dev/api-reference/rest-apis/v1/gdpr/delete-all-user-data-gdpr
POST https://api.velt.dev/v1/users/data/delete
Remove All User data from Velt.
Use this API to remove all user data from Velt. This will:
* remove their access from all the documents and data in the organization.
* remove them from @mention contact dropdown list.
* remove them from @mentions where they were tagged.
* remove all feature data created by the user. eg: comments, reactions etc.
- This API may take up to 5 minutes to return a 202 response since it runs an asynchronous job to delete user data across the system.
- To speed up this process, you can optionally provide the organizationIds where the user belongs.
- The actual deletion of data can take upto 24 hours to complete.
# Endpoint
`POST https://api.velt.dev/v1/users/data/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of user Ids.
Array of organization Ids. These are the organizations that the user is part of.
## **Example Request**
```JSON theme={null}
{
"data": {
"userIds": [
"yourUserId1",
"yourUserId2"
],
"organizationIds": [
"yourOrganizationId1",
"yourOrganizationId2"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"status": "success",
"message": "Data deletion process has been initiated.",
"data": {
"jobId": "dsQuvPmIynANgPLLEhCm",
"tasksCount": 5
},
"statusCode": 202
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"status": "success",
"message": "Data deletion process has been initiated.",
"data": {
"jobId": "dsQuvPmIynANgPLLEhCm",
"tasksCount": 5
},
"statusCode": 202
}
```
# Get All User Data
Source: https://docs.velt.dev/api-reference/rest-apis/v1/gdpr/get-all-user-data-gdpr
POST https://api.velt.dev/v1/users/data/get
Get all feature data for a user stored in Velt.
Use this API to get all feature data for a user stored in Velt.
* The data will be paginated and returned in chunks of 100 items per feature data.
* You can use the `nextPageToken` returned in the response to fetch the next chunk of data.
* If there are no more items to fetch, the `nextPageToken` will not be returned.
* Here is the data that will be included:
* **User profile data:** If they were added to any organization, document or folder.
* **Comments data:** All the comments created by the user or where they were involved in.
* **Reactions data:** All the reactions created by the user.
* **Notifications data:** All the notifications where the user was involved in.
* **Recordings data:** All the recordings created by the user.
This API may take a few seconds to return a response depending on the dataset size.
# Endpoint
`POST https://api.velt.dev/v1/users/data/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The organization Id of the organization that the user is part of.
The user Id of the user you want to get the data for.
Page token retrieved from previous API call.
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"pageToken": "yourPageToken"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"comments": [..], //Upto 100 items. Empty array if no items are found.
"reactions": [..], //Upto 100 items. Empty array if no items are found.
"recordings": [..], //Upto 100 items. Empty array if no items are found.
"notifications": [..] //Upto 100 items. Empty array if no items are found.
},
"nextPageToken": "bhdwdqwjs298e39e479ddkeuw==329" // This will be null if there are no more items to fetch.
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT",
"code": 500
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"comments": [..], //Upto 100 items. Empty array if no items are found.
"reactions": [..], //Upto 100 items. Empty array if no items are found.
"recordings": [..], //Upto 100 items. Empty array if no items are found.
"notifications": [..] //Upto 100 items. Empty array if no items are found.
},
"nextPageToken": "bhdwdqwjs298e39e479ddkeuw==329" //This will be null if there are no more items to fetch.
}
}
```
# Get Delete All User Data Status
Source: https://docs.velt.dev/api-reference/rest-apis/v1/gdpr/get-delete-user-data-status-gdpr
POST https://api.velt.dev/v1/users/data/delete/status
Get the status of the data deletion process for a user.
Use this API to get the status of the data deletion process for a user.
This API may take a few seconds to return a response depending on the dataset size.
# Endpoint
`POST https://api.velt.dev/v1/users/data/delete/status`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The job Id of the data deletion process.
## **Example Request**
```JSON theme={null}
{
"data": {
"jobId": "yourJobId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"isDeleteCompleted": true,
"tasksLeft": 0,
"lastTaskCompletedTime": 1748972106739
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT",
"code": 500
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"isDeleteCompleted": true,
"tasksLeft": 0,
"lastTaskCompletedTime": 1748972106739
}
}
}
```
# Broadcast Event
Source: https://docs.velt.dev/api-reference/rest-apis/v1/livestate/broadcast-event
POST https://api.velt.dev/v1/livestate/broadcast
Use this API to broadcast live state events to any document. Use it with the [Live State](/realtime-collaboration/live-state-sync/setup#get-live-data) feature.
# Endpoint
`POST https://api.velt.dev/v1/livestate/broadcast`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body Parameters
Organization ID where the document belongs
Document ID to broadcast the event to
Unique identifier for the live state data
The data to broadcast. Can be any valid serializable JSON object.
If true, merges the new data with existing data instead of replacing it
## Example Request
```JSON theme={null}
{
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"liveStateDataId": "sample_live_state_data_id",
"data": {
"status": "active",
"message": "Hello World",
"customField": "custom value"
},
"merge": true
}
```
# Response
## Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Event broadcasted successfully.",
"data": {
"success": true
}
}
}
```
## Error Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "ERROR_CODE"
}
}
```
```json theme={null}
{
"result": {
"status": "success",
"message": "Event broadcasted successfully.",
"data": {
"success": true
}
}
}
```
# Delete Data by Location
Source: https://docs.velt.dev/api-reference/rest-apis/v1/locations/delete-data-by-location
POST https://api.velt.dev/v1/organizations/documents/locations/data/delete
Delete all data associated with a specific location
Use this API to delete all data (comments, recordings, or any other feature data) associated with a specific location.
# Endpoint
`POST https://api.velt.dev/v1/organizations/documents/locations/data/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Your API key
Your Auth Token
Document ID
The location object containing the data to be deleted
## **Example Request**
```JSON theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY",
"authToken": "YOUR_AUTH_TOKEN",
"documentId": "YOUR_DOCUMENT_ID",
"location": {
"id": "scene_1",
"locationName": "White scene"
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Data deleted successfully.",
"data": null
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Data deleted successfully.",
"data": null
}
}
```
# Update Location
Source: https://docs.velt.dev/api-reference/rest-apis/v1/locations/update-location
POST https://api.velt.dev/v1/organizations/documents/locations/update
Update a Location's metadata
Use this API to update a Location's metadata.
# Endpoint
`POST https://api.velt.dev/v1/organizations/documents/locations/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Your API key
Your Auth Token
Organization ID. Provide the organizationId if you are using Organizations feature.
Document ID
The current location object
The updated location object
When true, merges new location fields with existing ones. When false, completely replaces the old location object.
Default: false
## **Example Request**
```JSON theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY",
"authToken": "YOUR_AUTH_TOKEN",
"documentId": "YOUR_DOCUMENT_ID",
"migrate": {
"oldLocation": {
"id": "scene_1",
"locationName": "Untitled scene"
},
"newLocation": {
"id": "scene_1",
"locationName": "White scene"
}
},
"merge": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Location updated.",
"data": null
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Location updated.",
"data": null
}
}
```
# Add Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v1/notifications/add-notifications
POST https://api.velt.dev/v1/notifications/add
Use this API to add notifications.
# Endpoint
`POST https://api.velt.dev/v1/notifications/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
User who took the action
Notification ID. If not provided, Velt will generate a random ID.
Use this if you want more control on the ID being set and prevent duplicate notifications.
Only the special characters `_`, `-` are allowed.
Display Headline Message Template
Display Headline Message Template Data (Optional)
User who took the action
User who was directly affected by the action
Any custom field with string value
Display Body Message
Array of Notify Users
Default is true.
If set to true, the notification will be sent to all users in the organization.
If set to false, the notification will be sent to only the users specified in the `notifyUsers` array.
Any custom object to be stored with the notification.
When the user clicks on the notification, this data will be sent in the callback.
If set to true, a new document will be created before the notification is created.
If set to true, a new organization will be created (if it doesn't exist) before the notification is created.
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"actionUser": {
"userId": "yourUserId",
"name": "User Name",
"email": "user@example.com"
},
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"userId": "yourUserId",
"name": "User Name",
"email": "user@example.com"
},
"recipientUser": {
"userId": "recipientUserId",
"name": "Recipient Name",
"email": "recipient@example.com"
},
"yourCustomField": "Variable will be replaced with this text"
},
"displayBodyMessage": "This is body message (Secondary message)",
"notifyUsers": [
{
"email": "test@example.com",
"userId": "testingUserId"
},
{
"userId": "yourUserId",
"name": "User Name",
"email": "user@example.com"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification added successfully.",
"data": {
"success": true,
"message": "Notification added successfully."
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification added successfully.",
"data": {
"success": true,
"message": "Notification added successfully."
}
}
}
```
# Delete Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v1/notifications/delete-notifications
POST https://api.velt.dev/v1/notifications/delete
Use this API to delete notifications.
# Endpoint
`POST https://api.velt.dev/v1/notifications/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID (Optional)
Location ID (Optional)
User ID (Optional)
Array of Notification IDs (Optional)
## **Example Requests**
#### 1. Delete by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId"
}
}
```
#### 2. Delete by organizationId, documentId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 3. Delete by organizationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId"
}
}
```
#### 4. Delete by organizationId, userId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 5. Delete by organizationId, documentId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId"
}
}
```
#### 6. Delete by organizationId, documentId, userId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 7.Delete by organizationId, documentId and locationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId"
}
}
```
#### 8. Delete by organizationId, documentId, locationId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 9. Delete by organizationId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"locationId": "yourLocationId",
"userId": "yourUserId",
}
}
```
#### 10. Delete by organizationId, locationId, userId, and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"locationId": "yourLocationId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 11. Delete by organizationId, documentId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"userId": "yourUserId",
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) deleted successfully.",
"data": {
"8955243231506071": {
"success": true,
"message": "Notification deleted."
}
}
}
}
```
#### When some notifications are not found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) deleted successfully.",
"data": {
"89552432315060712": {
"success": false,
"message": "Failed to delete notification."
},
"8955243231506071": {
"success": true,
"message": "Notification deleted."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) deleted successfully.",
"data": {
"8955243231506071": {
"success": true,
"message": "Notification deleted."
}
}
}
}
```
# Get Config
Source: https://docs.velt.dev/api-reference/rest-apis/v1/notifications/get-config
POST https://api.velt.dev/v1/notifications/config/get
To use this API, you must have the this feature enabled in [Velt console](https://console.velt.dev/dashboard/config/notification)
Use this API to set the notifications config for users.
# Endpoint
`POST https://api.velt.dev/v1/notifications/config/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The ID of the organization.
An array of document IDs. The notification configuration will be fetched for these documents for the specified user. Max 30 documents can be fetched at a time.
The ID of the user.
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"documentIds": ["doc1"],
"userId":"USER_ID1"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User config fetched successfully.",
"data": [
{
"config": {
"inbox": "ALL",
"email": "ALL"
},
"metadata": {
"organizationId": "org1",
"apiKey": "API_KEY",
"documentId": "doc1",
"userId": "USER_ID1"
}
}
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User config fetched successfully.",
"data": [
{
"config": {
"inbox": "ALL",
"email": "ALL"
},
"metadata": {
"organizationId": "org1",
"apiKey": "API_KEY",
"documentId": "doc1",
"userId": "USER_ID1"
}
}
]
}
}
```
# Get Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v1/notifications/get-notifications
POST https://api.velt.dev/v1/notifications/get
Use this API to retrieve notifications.
Use this for SDK v3 or prior versions.
# Endpoint
`POST https://api.velt.dev/v1/notifications/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Location ID
User ID
Array of Notification IDs. Limit: Only 30 items can be passed at a time.
## **Example Requests**
#### 1. Get by organizationId, documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId"
}
}
```
#### 2. Get by organizationId, documentId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 3. Get by organizationId, documentId and locationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId"
}
}
```
#### 4. Get by organizationId, documentId, locationId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 5. Get by organizationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId"
}
}
```
#### 6. Get by organizationId, userId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 7. Get by organizationId, documentId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId"
}
}
```
#### 8. Get by organizationId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"locationId": "yourLocationId"
}
}
```
#### 9. Get by organizationId, documentId, locationId, and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"locationId": "yourLocationId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) retrieved successfully.",
"data": [
{
"id": "notificationId",
"notificationSource": "custom",
"notificationSourceData": {}, //The data of the notification source. e.g., CommentAnnotation
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"displayBodyMessage": "This is body message (Secondary message)",
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"recipientUser": {
"email": "recipient@example.com",
"name": "Recipient Name",
"userId": "recipientUserId"
},
"yourCustomVariableWithStringValue": "Variable will be replaced with this text"
},
"metadata": {
"apiKey": "yourApiKey",
"documentId": "yourDocumentId",
"organizationId": "yourOrganizationId"
},
"notifyUsers": {
"yourNotifyUserId": true
},
"notifyUsersByUserId": {
"yourNotifyUserById": true
},
"timestamp": 1722409519944
}
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) retrieved successfully.",
"data": [
{
"id": "notificationId",
"notificationSource": "custom",
"notificationSourceData": {}, //The data of the notification source. e.g., CommentAnnotation
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"displayBodyMessage": "This is body message (Secondary message)",
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"recipientUser": {
"email": "recipient@example.com",
"name": "Recipient Name",
"userId": "recipientUserId"
},
"yourCustomVariableWithStringValue": "Variable will be replaced with this text"
},
"metadata": {
"apiKey": "yourApiKey",
"documentId": "yourDocumentId",
"organizationId": "yourOrganizationId"
},
"notifyUsers": {
"yourNotifyUserId": true
},
"notifyUsersByUserId": {
"yourNotifyUserById": true
},
"timestamp": 1722409519944
}
]
}
}
```
# Set Config
Source: https://docs.velt.dev/api-reference/rest-apis/v1/notifications/set-config
POST https://api.velt.dev/v1/notifications/config/set
To use this API, you must have the this feature enabled in [Velt console](https://console.velt.dev/dashboard/config/notification)
Use this API to set the notifications config for users.
# Endpoint
`POST https://api.velt.dev/v1/notifications/config/set`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The ID of the organization.
An array of document IDs. The notification configuration will be applied to these documents for the specified users.
An array of user IDs. The notification configuration will be set for these users.
Object containing the notification preferences.
In-app inbox notification preference. Valid values:
`ALL`: User receives all notifications in their inbox.
`MINE`: User receives notifications in their inbox only for activities directly involving them (e.g., mentions, replies).
`NONE`: User receives no notifications in their inbox.
Optional.
Email notification preference. Valid values:
`ALL`: User receives email notifications for all activities.
`MINE`: User receives email notifications only for activities directly involving them.
`NONE`: User receives no email notifications.
Optional.
Slack notification preference (requires Slack integration to be effective). Valid values:
`ALL`: User receives Slack notifications for all activities.
`MINE`: User receives Slack notifications only for activities directly involving them.
`NONE`: User receives no Slack notifications.
Optional.
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"documentIds": ["doc1"],
"userIds":["USER_ID1"],
"config":{
"inbox": "ALL", // ALL | MINE | NONE
"email": "ALL" // ALL | MINE | NONE
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User config set successfully.",
"data": {
"USER_ID1": {
"success": true,
"userId": "USER_ID1",
"documentId": "doc1",
"message": "User config set successfully."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User config set successfully.",
"data": {
"USER_ID1": {
"success": true,
"userId": "USER_ID1",
"documentId": "doc1",
"message": "User config set successfully."
}
}
}
}
```
# Update Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v1/notifications/update-notifications
POST https://api.velt.dev/v1/notifications/update
Use this API to update notifications.
# Endpoint
`POST https://api.velt.dev/v1/notifications/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID (Optional)
Location ID
User ID (Optional)
Notifications object
Notification ID
User who took the action
Display Headline Message Template
Display Headline Message Template Data
User who took the action
User who was directly affected by the action
Any custom field with string value
Display Body Message
Any custom object to be stored with the notification.
When the user clicks on the notification, this data will be sent to in the callback.
Array of user ids that you want to mark the notification as read.
Use this with the `readByUserIds` param. If `true`, the read notifications will be not be removed from the "For You" tab.
## **Example Requests**
#### 1. Update by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 2. Update by organizationId, documentId and locationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 3. Update by organizationId, documentId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 4. Update by organizationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 5. Update by organizationId, documentId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"locationId": "yourLocationId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) updated successfully.",
"data": {
"5471488637912692": {
"success": true,
"message": "Notification updated."
}
}
}
}
```
#### When some notifications are not found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) updated successfully.",
"data": {
"5471488637912692": {
"success": false,
"message": "Failed to update notification."
},
"5471488637912693": {
"success": true,
"message": "Notification updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) updated successfully.",
"data": {
"5471488637912692": {
"success": true,
"message": "Notification updated."
}
}
}
}
```
# Add Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/organizations/add-organizations
POST https://api.velt.dev/v1/organizations/add
Use this API to add new organizations and its metadata.
# Endpoint
`POST https://api.velt.dev/v1/organizations/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization objects
## **Example Requests**
#### Add organization
```JSON theme={null}
{
"data": {
"organizations": [
{
"organizationId": "yourOrganizationId",
"organizationName": "Your Organization Name"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) added successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Added Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) added successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Added Successfully"
}
}
}
}
```
# Delete Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/organizations/delete-organizations
POST https://api.velt.dev/v1/organizations/delete
Use this API to delete specific organization(s) data by their IDs.
# Endpoint
`POST https://api.velt.dev/v1/organizations/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization IDs
## **Example Requests**
#### Delete specific organization
```JSON theme={null}
{
"data": {
"organizationIds": [
"yourOrganizationId1",
"yourOrganizationId2"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) deleted successfully.",
"data": {
"yourOrganizationId1": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Deleted Successfully"
},
{
"yourOrganizationId2": {
"success": false,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Organization does not exist"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) deleted successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Deleted Successfully"
}
}
}
}
```
# Get Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/organizations/get-organizations
POST https://api.velt.dev/v1/organizations/get
Use this API to retrieve specific organizations by organization IDs.
Use this for SDK v3 or prior versions.
# Endpoint
`POST https://api.velt.dev/v1/organizations/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization IDs (Optional).
Limit: Only 30 IDs can be passed at a time.
If this is not provided, all organizations will be returned.
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationIds": [
"yourOrganizationId"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) retrieved successfully.",
"data": [
{
"id": "yourOrganizationId",
"organizationName": "Your Organization Name",
"disabled": false,
// other metadata fields may be included here
}
// ... more organizations if multiple were retrieved
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) retrieved successfully.",
"data": [
{
"id": "yourOrganizationId",
"organizationName": "Your Organization Name",
"disabled": false,
// other metadata fields may be included here
}
// ... more organizations if multiple were retrieved
]
}
}
```
# Update Disabled State for Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/organizations/update-organization-disable-state
POST https://api.velt.dev/v1/organizations/access/disablestate/update
Use this API to enable or disable both read and write access for all documents for all users.
Let's say your customer's trial or subscription has ended and you want to disable their access to the Velt data, you could use this to disable access to the entire organization data.
If organization does not exist, it will be created.
# Endpoint
`POST https://api.velt.dev/v1/organizations/access/disablestate/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization IDs
Whether to disable read and write access to the specified organizations. Allowed values: `true`, `false`.
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationIds": ["yourOrganizationId1","yourOrganizationId2"],
"disabled": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for Organization(s) successfully.",
"data": {
"yourOrganizationId1": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated disable state for organization Successfully"
},
"yourOrganizationId2": {
"success": false,
"id": "44e0132f4c6b0d453f18df42d2263b4e",
"message": "Organization does not exist"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for Organization(s) successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated disable state for organization Successfully"
}
}
}
}
```
# Update Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v1/organizations/update-organizations
POST https://api.velt.dev/v1/organizations/update
Use this API to update existing organization(s) metadata.
# Endpoint
`POST https://api.velt.dev/v1/organizations/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization objects
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizations": [
{
"organizationId": "yourOrganizationId",
"organizationName": "Your Updated Organization Name"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) updated successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) updated successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated Successfully"
}
}
}
}
```
# Add User Groups
Source: https://docs.velt.dev/api-reference/rest-apis/v1/user-groups/add-groups
POST https://api.velt.dev/v1/organizations/usergroups/add
Use this API to add organization user groups to a specific organization.
# Endpoint
`POST https://api.velt.dev/v1/organizations/usergroups/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Organization User Group objects
## **Example Request**
#### Add organization user group in a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroups": [
{
"groupId": "engineering",
"groupName": "Engineering"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization User Groups added successfully.",
"data": {
"yourGroupId": {
"success": true,
"id": "77ab6767b022ad0323ba39c24f12cc95",
"message": "Organization user group added."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization User Groups added successfully.",
"data": {
"yourGroupId": {
"success": true,
"id": "77ab6767b022ad0323ba39c24f12cc95",
"message": "Organization user group added."
}
}
}
}
```
# Add Users to Groups
Source: https://docs.velt.dev/api-reference/rest-apis/v1/user-groups/add-users-to-group
POST https://api.velt.dev/v1/organizations/usergroups/users/add
Use this API to add users to a specific organization user group.
# Endpoint
`POST https://api.velt.dev/v1/organizations/usergroups/users/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Organization User Group ID
Array of User IDs
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupId": "yourGroupId",
"userIds": ["yourUserId1"]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Added organization users to group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User added to organization user group."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Added organization users to group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User added to organization user group."
}
}
}
}
```
# Delete Users from Groups
Source: https://docs.velt.dev/api-reference/rest-apis/v1/user-groups/delete-users-from-group
POST https://api.velt.dev/v1/organizations/usergroups/users/delete
Use this API to delete users from a specific organization user group.
# Endpoint
`POST https://api.velt.dev/v1/organizations/usergroups/users/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Organization User Group ID
Array of User IDs
If true, all users in the group will be deleted.
## **Example Requests**
#### Delete specific users from group
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupId": "yourGroupId",
"userIds": ["yourUserId1"]
}
}
```
#### Delete all users from group
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupId": "yourGroupId",
"deleteAll": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Deleted users from group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User deleted from organization user group."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Deleted users from group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User deleted from organization user group."
}
}
}
}
```
# Add Users
Source: https://docs.velt.dev/api-reference/rest-apis/v1/users/add-users
POST https://api.velt.dev/v1/users/add
Use this API to add Users to:
1. **Organization:** This will provide them access to all the documents in the organization unless the document has `restricted` access type. It will also show users in the contact list of the organization.
2. **Folder:** This will provide them access to all the documents in the folder. If you pass the `folderId`, then the users will be added to the folder and not the organization.
3. **Document:** This will provide them access to the specified document. It will also show users in the contact list of the document. If you pass the `documentId`, then the users will be added to the document and not the organization or folder.
* If organization does not exist, it will be created.
* If you provide documentId or folderId, then the users will only be added at that level and not at the organization level. To also add users at the organization level, you will need to call this API again with only the organizationId.
* If User's `initial` is not provided in the User object, then it will be automatically created using the name field.
# Endpoint
`POST https://api.velt.dev/v1/users/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID. Provide this if you want to add users to a specific document.
Folder ID. Provide this if you want to add users to a specific folder. Either provide `documentId` or `folderId`.
Array of [User](/api-reference/sdk/models/data-models#user) objects.
## **Example Requests**
#### 1. Add users to a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com"
}
]
}
}
```
#### 2. Add users to a specific document within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com"
}
]
}
}
```
#### 3. Add users to a specific folder within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "4c250058149d6c9fb8c894c9ef29c790",
"message": "User added."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "4c250058149d6c9fb8c894c9ef29c790",
"message": "User added."
}
}
}
}
```
# Delete Users
Source: https://docs.velt.dev/api-reference/rest-apis/v1/users/delete-users
POST https://api.velt.dev/v1/users/delete
Remove Users from an Organization or a Document.
Use this API to remove Users from:
1. **Organization:** This will remove their access from all the documents and data in the organization. It will also remove these users from the contact list of the organization.
2. **Document:** This will remove their access from the specified document. It will also remove these users from the contact list of the document. If you pass the `documentId`, then the users will be removed from the document.
# Endpoint
`POST https://api.velt.dev/v1/users/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document IDs. Provide this if you want to delete users from a specific document.
Folder ID. Either provide `documentId` or `folderId`.
Array of user Ids.
## **Example Requests**
#### 1. Delete users in a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userIds": [
"yourUserId1"
]
}
}
```
#### 2. Delete users in a specific document within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId1"
]
}
}
```
#### 3. Delete users in a specific folder within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"userIds": [
"yourUserId1"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) deleted successfully.",
"data": {
"yourUserId1": {
"success": true,
"message": "User removed."
}
}
}
}
```
#### User(s) Not Found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) deleted successfully.",
"data": {
"yourUserId1": {
"success": true,
"message": "User removed."
},
{
"yourUserId2": {
"success": false,
"message": "User does not exist."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) deleted successfully.",
"data": {
"yourUserId1": {
"success": true,
"message": "User removed."
}
}
}
}
```
# Get Users
Source: https://docs.velt.dev/api-reference/rest-apis/v1/users/get-users
POST https://api.velt.dev/v1/users/get
Use this API to retrieve users based on various filters such as organization ID, document ID, organization user group IDs or user IDs. You can use these filters in various combinations to get the desired users. Some examples are shown below.
Use this for SDK v3 or prior versions.
# Endpoint
`POST https://api.velt.dev/v1/users/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### **Params**
Organization ID
Document ID
Array of User IDs. Limit: Only 30 items can be passed at a time.
Array of Organization User Group IDs. Only 30 items can be passed at a time.
## **Example Requests**
#### 1. Get users by organizationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId"
}
}
```
#### 2. Get users by documentId within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId"
}
}
```
#### 3. Get users by specific user IDs in an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userIds": [
"yourUserId1",
"yourUserId2"
]
}
}
```
#### 4. Get users by specific user IDs in the given organization and document
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId1",
"yourUserId2"
]
}
}
```
#### 5. Get users by organization and organization user group IDs
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupIds": [
"yourOrganizationUserGroupId"
]
}
}
```
#### 6. Get users by organization, organization user group IDs and user IDs
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userIds": [
"yourUserId1",
"yourUserId2"
],
"organizationUserGroupIds": [
"yourOrganizationUserGroupId"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) retrieved successfully.",
"data": [
{
"email": "userEmail@domain.com",
"name": "userName",
"userId": "yourUserId"
}
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "Error retrieving user(s).",
"status": "ERROR_CODE"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) retrieved successfully.",
"data": [
{
"email": "userEmail@domain.com",
"name": "userName",
"userId": "yourUserId"
}
]
}
}
```
# Update Users
Source: https://docs.velt.dev/api-reference/rest-apis/v1/users/update-users
POST https://api.velt.dev/v1/users/update
Use this API to update user metadata based on various filters such as organization ID, document ID, folder ID and user IDs.
You can use these filters in various combinations to get the desired results.
The user metadata such as name, email etc can be updated.
# Endpoint
`POST https://api.velt.dev/v1/users/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### **Params**
Organization ID
Document ID
Folder ID. Either provide `documentId` or `folderId`.
Array of [User](/api-reference/sdk/models/data-models#user) objects.
## **Example Requests**
#### 1. Update users in a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com"
}
]
}
}
```
#### 2. Update users in a specific document within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com"
}
]
}
}
```
#### 3. Update users in a specific folder within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "7d87015b055a168b098cf05b870e40ff",
"message": "User updated."
}
}
}
}
```
#### Some User(s) Not Found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "7d87015b055a168b098cf05b870e40ff",
"message": "User updated."
},
"yourUserId2": {
"success": false,
"id": "ad22d93b49ad990d2b3d582d08d7768a",
"message": "User does not exist."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "7d87015b055a168b098cf05b870e40ff",
"message": "User updated."
}
}
}
}
```
# Add Domains
Source: https://docs.velt.dev/api-reference/rest-apis/v1/workspace/add-domain
POST https://api.velt.dev/v1/workspace/domains/add
Use this API to add new organizations and its metadata.
# Endpoint
`POST https://api.velt.dev/v1/workspace/domains/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of domains
# Example Request
```JSON theme={null}
{
"data": {
"domains" : [
"https://www.google.com",
"https://*.firebase.com"
]
}
}
```
# Example Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) added successfully to allowed domains.",
"data": {
"domainsAdded": [
"google.com",
"*.firebase.com"
]
}
}
}
```
#### Failure Response
##### If some domains are already in the allowed domains
```JSON theme={null}
{
"error": {
"details": {
"domainsAdded": [
"velt.dev"
],
"skippedDomains": [
"google.com"
]
},
"message": "Domain(s) added successfully to allowed domains. Skipped existing domains.",
"status": "INTERNAL"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) added successfully to allowed domains.",
"data": {
"domainsAdded": [
"google.com",
"*.firebase.com"
]
}
}
}
```
# Delete Domains
Source: https://docs.velt.dev/api-reference/rest-apis/v1/workspace/delete-domain
POST https://api.velt.dev/v1/workspace/domains/delete
Use this API to add new organizations and its metadata.
# Endpoint
`POST https://api.velt.dev/v1/workspace/domains/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of domains
# Example Request
```JSON theme={null}
{
"data": {
"domains" : [
"https://www.google.com",
"https://*.firebase.com"
]
}
}
```
# Example Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) removed successfully from allowed domains.",
"data": {
"domainsRemoved": [
"google.com",
"*.firebase.com"
]
}
}
}
```
#### Failure Response
##### If some domains are not in the allowed domains
```JSON theme={null}
{
"error": {
"details": {
"domainsRemoved": [
"velt.dev"
],
"skippedDomains": [
"google.com"
]
},
"message": "Domain(s) removed successfully from allowed domains. Skipped non-existing domains.",
"status": "INTERNAL"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) removed successfully from allowed domains.",
"data": {
"domainsRemoved": [
"google.com",
"*.firebase.com"
]
}
}
}
```
# Add Activity Logs
Source: https://docs.velt.dev/api-reference/rest-apis/v2/activities/add-activities
POST https://api.velt.dev/v2/activities/add
Use this API to create activity log records for a document within an organization.
Adding activity logs via the REST API requires `activityServiceConfig` to be enabled at the workspace level in the [Velt Console](https://console.velt.dev).
# Endpoint
`POST https://api.velt.dev/v2/activities/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Array of activity log objects to create.
Feature that generated the activity log (e.g., `"comment"`).
Specific action performed (e.g., `"comment.add"`).
User who performed the action.
ID of the primary entity the activity log targets (e.g., annotation ID).
ID of a sub-entity within the target (e.g., a specific comment ID).
Map of field names to `{ from, to }` objects describing what changed.
Snapshot of the entity at the time of the action.
Snapshot of the target entity at the time of the action.
Message template string. Use `{{variable}}` syntax for dynamic values.
Key-value data to populate `displayMessageTemplate` variables.
URL or identifier for the icon representing this action.
## **Example Requests**
#### Add a single activity log
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"documentId": "doc-456",
"activities": [
{
"featureType": "comment",
"actionType": "comment.add",
"actionUser": {
"userId": "user-1",
"email": "user@example.com",
"name": "User Name"
},
"targetEntityId": "annotation-789",
"displayMessageTemplate": "{{user}} added a comment"
}
]
}
}
```
#### Add an activity log with changes and template data
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"documentId": "doc-456",
"activities": [
{
"featureType": "comment",
"actionType": "comment.update",
"actionUser": {
"userId": "user-1",
"email": "user@example.com",
"name": "User Name"
},
"targetEntityId": "annotation-789",
"targetSubEntityId": "comment-001",
"changes": {
"commentText": {
"from": "Original text",
"to": "Updated text"
}
},
"displayMessageTemplate": "{{user}} updated a comment",
"displayMessageTemplateData": {
"user": {
"userId": "user-1",
"name": "User Name"
}
}
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) added successfully.",
"data": {
"success": true,
"message": "Activity(s) added successfully."
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) added successfully.",
"data": {
"success": true,
"message": "Activity(s) added successfully."
}
}
}
```
# Delete Activity Logs
Source: https://docs.velt.dev/api-reference/rest-apis/v2/activities/delete-activities
POST https://api.velt.dev/v2/activities/delete
Use this API to delete activity log records. At least one of `documentId`, `targetEntityId`, or `activityIds` is required.
# Endpoint
`POST https://api.velt.dev/v2/activities/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Delete all activity logs associated with this document ID.
Delete specific activity logs by ID.
Delete all activity logs associated with this entity ID.
At least one of `documentId`, `targetEntityId`, or `activityIds` must be provided.
## **Example Requests**
#### 1. Delete by activityIds
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"activityIds": ["activity-001", "activity-002"]
}
}
```
#### 2. Delete all activities for a document
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"documentId": "doc-456"
}
}
```
#### 3. Delete all activities for a target entity
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"targetEntityId": "annotation-789"
}
}
```
#### 4. Delete by documentId and targetEntityId
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"documentId": "doc-456",
"targetEntityId": "annotation-789"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) deleted successfully.",
"data": {
"activity-001": {
"success": true,
"message": "Activity deleted."
}
}
}
}
```
#### When some activities are not found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) deleted successfully.",
"data": {
"activity-001": {
"success": false,
"message": "Failed to delete activity."
},
"activity-002": {
"success": true,
"message": "Activity deleted."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) deleted successfully.",
"data": {
"activity-001": {
"success": true,
"message": "Activity deleted."
}
}
}
}
```
# Get Activity Logs
Source: https://docs.velt.dev/api-reference/rest-apis/v2/activities/get-activities
POST https://api.velt.dev/v2/activities/get
Use this API to retrieve activity log records for a document or organization.
# Endpoint
`POST https://api.velt.dev/v2/activities/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID. Filter activities to a specific document.
Target entity ID. Filter activities to a specific entity (e.g., annotation ID).
Filter by feature type (e.g., `["comment"]`).
Filter by action type (e.g., `["comment.add"]`).
Filter activities by the acting user's ID.
Fetch specific activities by ID.
Order results by timestamp. Must be `asc` or `desc`. Default: `desc`.
Number of items to retrieve per page. Default: 1000. Minimum: 1.
Encrypted pagination token retrieved from a previous API response.
## **Example Requests**
#### 1. Get by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"documentId": "doc-456",
"order": "desc",
"pageSize": 50
}
}
```
#### 2. Get by organizationId, documentId and featureTypes
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"documentId": "doc-456",
"featureTypes": ["comment"],
"order": "desc",
"pageSize": 50
}
}
```
#### 3. Get specific activity logs by activityIds
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"activityIds": ["activity-001", "activity-002"]
}
}
```
#### 4. Get by targetEntityId with pagination
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"documentId": "doc-456",
"targetEntityId": "annotation-789",
"pageSize": 20,
"pageToken": "encryptedPageToken"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) retrieved successfully.",
"data": [
{
"id": "activity-001",
"featureType": "comment",
"actionType": "comment.add",
"actionUser": {
"userId": "user-1",
"email": "user@example.com",
"name": "User Name"
},
"targetEntityId": "annotation-789",
"displayMessageTemplate": "{{user}} added a comment",
"displayMessageTemplateData": {
"user": {
"userId": "user-1",
"name": "User Name"
}
},
"metadata": {
"apiKey": "yourApiKey",
"documentId": "doc-456",
"organizationId": "org-123"
},
"timestamp": 1722409519944
}
],
"pageToken": "nextPageToken"
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) retrieved successfully.",
"data": [
{
"id": "activity-001",
"featureType": "comment",
"actionType": "comment.add",
"actionUser": {
"userId": "user-1",
"email": "user@example.com",
"name": "User Name"
},
"targetEntityId": "annotation-789",
"displayMessageTemplate": "{{user}} added a comment",
"displayMessageTemplateData": {
"user": {
"userId": "user-1",
"name": "User Name"
}
},
"metadata": {
"apiKey": "yourApiKey",
"documentId": "doc-456",
"organizationId": "org-123"
},
"timestamp": 1722409519944
}
],
"pageToken": "nextPageToken"
}
}
```
# Update Activity Logs
Source: https://docs.velt.dev/api-reference/rest-apis/v2/activities/update-activities
POST https://api.velt.dev/v2/activities/update
Use this API to update existing activity log records within an organization.
# Endpoint
`POST https://api.velt.dev/v2/activities/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of activity log objects to update. Each must include the activity log `id`.
Activity log ID to update.
Map of field names to `{ from, to }` objects describing what changed.
Updated snapshot of the entity.
Updated snapshot of the target entity.
Updated message template string. Use `{{variable}}` syntax for dynamic values.
Updated key-value data to populate `displayMessageTemplate` variables.
Updated URL or identifier for the action icon.
## **Example Requests**
#### Update a single activity log's display message
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"activities": [
{
"id": "activity-001",
"displayMessageTemplate": "{{user}} updated the comment"
}
]
}
}
```
#### Update multiple activities
```JSON theme={null}
{
"data": {
"organizationId": "org-123",
"activities": [
{
"id": "activity-001",
"displayMessageTemplate": "{{user}} updated the comment",
"displayMessageTemplateData": {
"user": {
"userId": "user-1",
"name": "User Name"
}
}
},
{
"id": "activity-002",
"actionIcon": "https://example.com/icons/edit.svg"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) updated successfully.",
"data": {
"activity-001": {
"success": true,
"message": "Activity updated."
}
}
}
}
```
#### When some activities are not found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) updated successfully.",
"data": {
"activity-001": {
"success": false,
"message": "Failed to update activity."
},
"activity-002": {
"success": true,
"message": "Activity updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Activity(s) updated successfully.",
"data": {
"activity-001": {
"success": true,
"message": "Activity updated."
}
}
}
}
```
# Add Permissions
Source: https://docs.velt.dev/api-reference/rest-apis/v2/auth/add-permissions
POST https://api.velt.dev/v2/auth/permissions/add
Use this API to add permissions to a user for various resources like organizations, folders, documents, etc.
* You can add permissions for multiple resources in a single API call.
* The `expiresAt` field is optional. If provided, the permission will expire at the given timestamp.
**Access Control**
* Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource.
* `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`.
* Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`.
* See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
# Endpoint
`POST https://api.velt.dev/v2/auth/permissions/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
The ID of the user to add permissions to.
Array of resource objects to grant permissions for.
The type of resource. Can be `organization`, `document` or `folder`.
The ID of the resource.
The ID of the organization. Required if `type` is `document` or `folder`.
Optional access role for this resource. Allowed values: “viewer” | “editor”. Default: "editor".
A Unix timestamp (in seconds) that specifies when the permission should expire. This is optional.
## **Example Requests**
#### 1. Add permissions to a specific organization
```json theme={null}
{
"data": {
"user": {
"userId": "some-user-id"
},
"permissions": {
"resources": [
{
"type": "organization",
"id": "YOUR_ORGANIZATION_ID",
"accessRole": "editor"
}
]
}
}
}
```
```json theme={null}
{
"data": {
"user": {
"userId": "some-user-id"
},
"permissions": {
"resources": [
{
"type": "organization",
"id": "YOUR_ORGANIZATION_ID",
"accessRole": "viewer"
}
]
}
}
}
```
#### 2. Add permissions to a specific document within an organization
```json theme={null}
{
"data": {
"user": {
"userId": "some-user-id"
},
"permissions": {
"resources": [
{
"type": "document",
"id": "YOUR_DOCUMENT_ID",
"organizationId": "YOUR_ORGANIZATION_ID",
"accessRole": "editor",
"expiresAt": 1728902400
}
]
}
}
}
```
```json theme={null}
{
"data": {
"user": {
"userId": "some-user-id"
},
"permissions": {
"resources": [
{
"type": "document",
"id": "YOUR_DOCUMENT_ID",
"organizationId": "YOUR_ORGANIZATION_ID",
"accessRole": "viewer",
"expiresAt": 1728902400
}
]
}
}
}
```
#### 3. Add permissions to a specific folder within an organization
```json theme={null}
{
"data": {
"user": {
"userId": "some-user-id"
},
"permissions": {
"resources": [
{
"type": "folder",
"id": "YOUR_FOLDER_ID",
"organizationId": "YOUR_ORGANIZATION_ID",
"accessRole": "editor"
}
]
}
}
}
```
```json theme={null}
{
"data": {
"user": {
"userId": "some-user-id"
},
"permissions": {
"resources": [
{
"type": "folder",
"id": "YOUR_FOLDER_ID",
"organizationId": "YOUR_ORGANIZATION_ID",
"accessRole": "viewer"
}
]
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Permissions added successfully."
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Permissions added successfully."
}
}
```
# Generate Signature
Source: https://docs.velt.dev/api-reference/rest-apis/v2/auth/generate-signature
POST https://api.velt.dev/v2/auth/generate_signature
Use this API to generate a secure signature for Permission Provider responses. The signature validates the integrity of permission decisions returned from your authorization service.
**Security Critical:** This endpoint must be called from your backend server, never from client-side code. The signature ensures that permission responses haven't been tampered with.
**Permission Provider Integration**
This API is used in conjunction with the [Permission Provider configuration mode](/key-concepts/overview#c-real-time-permission-provider). When implementing your backend Permission Provider endpoint, use this endpoint to generate a secure signature for your permission response.
# Endpoint
`POST https://api.velt.dev/v2/auth/generate_signature`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of permission decisions to sign. Each object must include user ID, resource information, access decision, and optional role/expiration.
ID of the user this permission applies to.
ID of the resource (document, folder, or organization).
Type of the resource. Allowed values: `"document"` | `"folder"` | `"organization"`.
Whether the user has access to the resource.
Access role for the user. Only applicable for document resources. Allowed values: `"viewer"` | `"editor"`. `viewer` can view and comment, `editor` can edit content.
UTC timestamp in milliseconds when this permission expires. Velt will revalidate access after expiration.
## **Example Requests**
#### 1. Generate signature for document access with viewer role and expiration
```JSON theme={null}
{
"data": {
"permissions": [
{
"userId": "user123",
"resourceId": "document456",
"type": "document",
"hasAccess": true,
"accessRole": "viewer",
"expiresAt": 1759745729823
}
]
}
}
```
#### 2. Generate signature for multiple resources (organization and folder)
```JSON theme={null}
{
"data": {
"permissions": [
{
"userId": "user123",
"resourceId": "org789",
"type": "organization",
"hasAccess": true
},
{
"userId": "user123",
"resourceId": "folder101",
"type": "folder",
"hasAccess": true
}
]
}
}
```
#### 3. Generate signature denying access
```JSON theme={null}
{
"data": {
"permissions": [
{
"userId": "user456",
"resourceId": "document789",
"type": "document",
"hasAccess": false
}
]
}
}
```
#### 4. Generate signature for document with editor role
```JSON theme={null}
{
"data": {
"permissions": [
{
"userId": "user789",
"resourceId": "document123",
"type": "document",
"hasAccess": true,
"accessRole": "editor"
}
]
}
}
```
#### 5. Generate signature for document with viewer role
```JSON theme={null}
{
"data": {
"permissions": [
{
"userId": "user456",
"resourceId": "document123",
"type": "document",
"hasAccess": true,
"accessRole": "viewer"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Signature generated successfully.",
"data": {
"signature": "a1b2c3d4e5f6..."
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Signature generated successfully.",
"data": {
"signature": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890"
}
}
}
```
# Generate Token
Source: https://docs.velt.dev/api-reference/rest-apis/v2/auth/generate-token
POST https://api.velt.dev/v2/auth/generate_token
Use this API to generate authentication JWT token for users to access Velt features. The token contains user information and permissions for specific resources like organizations, folders and documents.
Within `permissions.resources[]`, use `accessRole` to assign `viewer` (read-only) or `editor` (read/write) for each resource.
**Access Control**
* Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource.
* `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`.
* Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`.
* See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
* JWT token expires in 48 hours.
* You can specify permissions for different resource types (organization, folder, document)
# Endpoint
`POST https://api.velt.dev/v2/auth/generate_token`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Unique identifier for the user.
Whether the user has admin privileges. Defaults to false.
Display name of the user.
Email address of the user.
Array of resource permission objects.
Type of resource. Can be "organization", "document", or "folder".
ID of the resource.
Organization ID. Required when type is "document" or "folder".
Optional access role for this resource. Allowed values: “viewer” | “editor”. Default: "editor".
Unix timestamp when the permission expires. Optional.
## **Example Requests**
#### 1. Generate token with organization and document permissions (viewer on org, editor on document)
```JSON theme={null}
{
"userId": "user123",
"userProperties": {
"isAdmin": false,
"name": "John Doe",
"email": "john@example.com"
},
"permissions": {
"resources": [
{
"type": "organization",
"id": "org_123",
"accessRole": "viewer"
},
{
"type": "document",
"id": "doc_456",
"organizationId": "org_123",
"accessRole": "editor",
"expiresAt": 1640995200
}
]
}
}
```
#### 2. Generate token with only organization access (viewer)
```JSON theme={null}
{
"userId": "user456",
"userProperties": {
"isAdmin": true,
"name": "Jane Smith",
"email": "jane@example.com"
},
"permissions": {
"resources": [
{
"type": "organization",
"id": "org_789",
"accessRole": "viewer"
}
]
}
}
```
#### 3. Generate token with folder permissions (editor)
```JSON theme={null}
{
"userId": "user789",
"userProperties": {
"isAdmin": false,
"name": "Bob Wilson",
"email": "bob@example.com"
},
"permissions": {
"resources": [
{
"type": "organization",
"id": "org_123"
},
{
"type": "folder",
"id": "folder_001",
"organizationId": "org_123",
"accessRole": "editor"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Token generated successfully.",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Token generated successfully.",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJ1c2VyMTIzIiwiaWF0IjoxNjQwOTk1MjAwfQ.signature"
}
}
}
```
# Get Permissions
Source: https://docs.velt.dev/api-reference/rest-apis/v2/auth/get-permissions
POST https://api.velt.dev/v2/auth/permissions/get
Use this API to get a user's permissions for various resources like organizations, folders, documents, etc.
* Returns permissions per user and resource. Temporary permissions include an `expiresAt` (Unix seconds) value.
* See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
# Endpoint
`POST https://api.velt.dev/v2/auth/permissions/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
The ID of the organization to query.
Array of user IDs to fetch permissions for.
Optional array of folder IDs to include in the result.
Optional array of document IDs to include in the result.
## Example Request
```json theme={null}
{
"data": {
"organizationId": "org1",
"documentIds": ["freestyle-comments1"],
"userIds": ["samarth"]
}
}
```
```bash cURL theme={null}
curl --location 'https://api.velt.dev/v2/auth/permissions/get' \
--header 'x-velt-api-key: apiKey' \
--header 'x-velt-auth-token: authToken' \
--header 'Content-Type: application/json' \
--data '{
"data": {
"organizationId": "org1",
"documentIds": [
"freestyle-comments1"
],
"userIds": [
"samarth"
]
}
}'
```
# Response
Error responses include an `errorCode` field with structured error codes from the [UserPermissionAccessRoleResult](/api-reference/sdk/models/data-models#userpermissionaccessroleresult) enum. This helps you handle permission resolution failures programmatically.
## Response Schema
The response returns a nested structure with permissions per user and resource type. Each resource permission can include:
| Field | Type | Description |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `accessRole` | `string` | The user's access role (`"editor"` or `"viewer"`) |
| `expiresAt` | `number` | Unix timestamp (seconds) when temporary access expires |
| `error` | `string` | Human-readable error message if permission resolution failed |
| `errorCode` | `string` | Error code from [UserPermissionAccessRoleResult](/api-reference/sdk/models/data-models#userpermissionaccessroleresult) enum (v4.5.4+) |
#### Success Response
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"1.1": {
"documents": {
"document1-26-may-2025-folder2": {
"accessRole": "viewer"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
}
}
}
```
#### Success Response with Context Access Info
When using [Access Context](/key-concepts/overview#set-feature-level-permissions-using-access-context-custom-metadata) for feature-level permissions, the response includes a `context` object with `accessFields` showing which context values the user has access to:
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"user_123": {
"documents": {
"document1": {
"accessRole": "editor"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
},
"context": {
"accessFields": ["widgetId:1", "widgetId:2", "widgetId:3"]
}
}
}
}
}
```
The `accessFields` array contains strings in the format `"fieldName:value"` representing each context field and value combination the user has access to.
#### Permission Denied
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"1.1": {
"documents": {
"document5": {
"error": "User does not have access to document",
"errorCode": "permission_denied"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
}
}
}
```
#### Error Response Examples
When a resource does not exist, is denied, or encounters an error, the response includes both an `error` message and an `errorCode`:
**Resource Not Found:**
```json theme={null}
{
"error": {
"details": {
"1.1": {
"documents": {
"document1-26-may-2025-folder222": {
"error": "Document does not exist",
"errorCode": "does_not_exist"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
},
"message": "Folder or document does not exist",
"status": "NOT_FOUND"
}
}
```
#### API Failure Response
```json theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"1.1": {
"documents": {
"document1-26-may-2025-folder2": {
"accessRole": "viewer"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
}
}
}
}
}
```
# Remove Permissions
Source: https://docs.velt.dev/api-reference/rest-apis/v2/auth/remove-permissions
POST https://api.velt.dev/v2/auth/permissions/remove
Use this API to remove permissions from a user for specific resources like organizations or documents.
This endpoint allows you to revoke access for a user from one or more resources.
# Endpoint
`POST https://api.velt.dev/v2/auth/permissions/remove`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The ID of the user from whom to remove permissions.
An array of resource objects from which to remove user permissions.
The type of resource. Must be one of: `organization`, `document`, or `folder`.
The ID of the resource.
The ID of the organization. Required if `type` is `document`.
## **Example Requests**
#### Remove permissions from an organization and a document
```JSON theme={null}
{
"data": {
"userId": "USER_ID",
"permissions": {
"resources": [
{
"type": "organization",
"id": "ORGANIZATION_ID"
},
{
"type": "document",
"id": "DOCUMENT_ID",
"organizationId": "ORGANIZATION_ID"
}
]
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Permissions removed successfully."
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Permissions removed successfully."
}
}
```
# Add Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations
POST https://api.velt.dev/v2/commentannotations/add
Use this API to add comment annotations to a document within an organization.
* You can add comments on an elemement, text or page.
* You can provide HTML or text content.
* Additional filters can be applied using location IDs.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
When enabled, verifies the user has access to the document before creating comment annotations.
This ensures annotations respect document access permissions configured via Access Control or Permission Provider.
Default: `false`
Custom Annotation ID. If not provided, Velt will generate a unique ID for the annotation.
Location ID
Location Name
Target Element
Element DOM Id. When used with `targetText`, defines the text search boundaries for locating text comments within the specified element.
Target Text. Provide this if you want to add comment annotation on the provided text content.
Occurrence. Provide this if you want to add comment annotation on a text content.
Select All Content. Provide this if you want to select and add comment annotation on the entire text content of the target elementId.
Array of Comment Data
Custom Comment ID. If not provided, Velt will generate a unique ID for the comment.
Comment content in plain text string. To tag users, wrap their userId in double curly braces like `{{userId}}`. The frontend will replace this with the user's name.
Comment content in HTML string. To tag users, wrap their userId in double curly braces like `{{userId}}`. The frontend will replace this with the user's name.
Custom key/value metadata object. This is used to store any additional information about the comment.
Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.
Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.
When enabled, adding comments via the REST API will trigger in-app notifications, email notifications to relevant users and also trigger webhooks matching the SDK’s native notification behavior. Default: false.
When enabled, adding comments via the REST API will create activity log records matching the SDK’s native activity log behavior. Default: false.
User object from whom the comment is added
Created At timestamp (in milliseconds since epoch).
Last Updated timestamp (in milliseconds since epoch).
Array of tagged user contacts. Use this field to provide information about users tagged in the comment. Each userId wrapped in `{{userId}}` in commentText or commentHtml should have a corresponding entry here so the frontend can replace it with the user's name.
User ID of the tagged user. This should match the userId used in `{{userId}}` syntax within commentText or commentHtml.
Contact information for the tagged user
User ID of the tagged user
Name of the tagged user
Email of the tagged user
Status
Status ID
Status Name
Type. Must be one of: `default`, `ongoing`, or `terminal`.
Text and comment pin color
Background color on the status indicator
Raw SVG of the icon. Either `svg` or `iconUrl` is required.
Icon URL. Either `svg` or `iconUrl` is required.
User object to whom the comment is assigned
Custom key/value metadata object
Created At timestamp (in milliseconds since epoch).
Last Updated timestamp (in milliseconds since epoch).
Priority
Priority ID
Priority Color
Priority Name
Priority Light Color
## **Example Requests**
#### Add comment annotation by organizationId, documentId and location
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"commentAnnotations": [
{
"location": {
"id": "yourLocationId",
"locationName": "yourLocationName"
},
"targetElement": {
"elementId": "yourElementId",
"targetText": "Your Target Text",
"occurrence": 1,
"selectAllContent": false
},
"commentData": [
{
"commentText": "Sample Comment",
"commentHtml": "Sample Comment
",
"from": {
"userId": "yourUserId",
"name": "yourUserName",
"email": "yourUserEmail",
}
}
]
}
]
}
}
```
#### Add comment annotation with user tagging
```JSON theme={null}
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"commentData": [
{
"triggerNotification": true,
"commentText": "Hey {{user_sarah_chen}}, can you review this color scheme? I think we should use a darker shade for better contrast.",
"commentHtml": "Hey {{user_sarah_chen}}, can you review this color scheme? I think we should use a darker shade for better contrast.
",
"from": {
"userId": "user_john_smith",
"name": "John Smith",
"email": "john.smith@acme-corp.com"
},
"taggedUserContacts": [
{
"userId": "user_sarah_chen",
"contact": {
"userId": "user_sarah_chen",
"name": "Sarah Chen",
"email": "sarah.chen@acme-corp.com"
}
}
]
}
]
}
]
}
}
```
In this example, `{{user_sarah_chen}}` in the commentText will be replaced with "Sarah Chen" on the frontend, displaying as "Hey Sarah Chen, can you review this color scheme? I think we should use a darker shade for better contrast."
#### Add comment annotation with permission verification
```JSON theme={null}
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"verifyUserPermissions": true,
"commentAnnotations": [
{
"commentData": [
{
"commentText": "Please review this section",
"from": {
"userId": "user_john_smith",
"name": "John Smith",
"email": "john.smith@acme-corp.com"
}
}
]
}
]
}
}
```
When `verifyUserPermissions` is enabled, the API verifies the user has access to the document before creating the comment annotation. If verification fails, the request will be rejected.
#### Add comment annotation with activity tracking
```JSON theme={null}
{
"data": {
"organizationId": "acme-corp",
"documentId": "design-mockup-v2",
"commentAnnotations": [
{
"commentData": [
{
"commentText": "This needs review",
"triggerNotification": true,
"triggerActivities": true,
"from": {
"userId": "user-1",
"email": "user@example.com",
"name": "User Name"
}
}
]
}
]
}
}
```
#### Add comment annotation with access context
```JSON theme={null}
{
"data": {
"organizationId": "acme-corp",
"documentId": "analytics-dashboard",
"commentAnnotations": [
{
"context": {
"access": {
"entityId": "numberOfVisitors",
"dashboardId": "myDashboard"
}
},
"commentData": [
{
"commentText": "Traffic numbers look unusual today",
"from": {
"userId": "user_john_smith",
"name": "John Smith",
"email": "john.smith@acme-corp.com"
}
}
]
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comment Annotation(s) added successfully.",
"data": {
"-O0mpUziLcBwzREvZKs6": {
"success": true,
"annotationId": "-O0mpUziLcBwzREvZKs6",
"commentIds": [
126535
],
"message": "Added Successfully"
}
}
}
}
```
# Delete Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comment-annotations/delete-comment-annotations
POST https://api.velt.dev/v2/commentannotations/delete
Use this API to delete comment annotations from a document within an organization.
Additional filters can be applied using location IDs, annotation IDs, or user IDs.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Array of Location IDs
Array of Annotation IDs
Array of User IDs
## **Example Requests**
#### 1. Delete annotations by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId"
}
}
```
#### 2. Delete annotations by organizationId, documentId and locationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
]
}
}
```
#### 3. Delete annotations by organizationId, documentId, locationIds and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
]
}
}
```
#### 4. Delete annotations by organizationId, documentId and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
]
}
}
```
#### 5. Delete annotations by organizationId, documentId and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
#### 6. Delete annotations by organizationId, documentId, locationIds and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
#### 7. Delete annotations by documentId. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId"
}
}
```
#### 8. Delete annotations by documentId and locationIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
]
}
}
```
#### 9. Delete annotations by documentId and userIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
]
}
}
```
#### 10. Delete annotations by documentId and annotationIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
#### 11. Delete annotations by documentId, locationIds, and userIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
]
}
}
```
#### 12. Delete annotations by documentId, locationIds, and annotationIds. This will work if the document was created without an organization.
```JSON theme={null}
{
"data": {
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Annotations deleted successfully.",
"data": {
"yourAnnotationId1": {
"success": true,
"id": "yourAnnotationId",
"message": "Deleted Successfully"
},
"yourAnnotationId2": {
"success": false,
"id": "yourAnnotationId2",
"message": "Annotation not found."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Annotations deleted successfully.",
"data": {
"yourAnnotationId": {
"success": true,
"id": "yourAnnotationId",
"message": "Deleted Successfully"
}
}
}
}
```
# Get Comment Annotations Count
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-count
POST https://api.velt.dev/v2/commentannotations/count/get
Use this API to retrieve the count of comment annotations for specified documents, including both total and unread counts.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/count/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of document IDs to get comment annotation counts for. Limit: Only 30 IDs can be passed at a time.
ID of the user requesting the counts
Array of status IDs to filter comments by (e.g., "OPEN", "IN\_PROGRESS")
#### **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "ORG_ID",
"documentIds": ["DOC_1", "DOC_2"],
"userId": "1.1",
"statusIds": ["OPEN", "IN_PROGRESS"]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment count retrieved successfully.",
"data": {
"DOC_1": {
"total": 4,
"unread": 2
},
"DOC_2": {
"total": 2,
"unread": 0
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment count retrieved successfully.",
"data": {
"DOC_1": {
"total": 4,
"unread": 2
},
"DOC_2": {
"total": 2,
"unread": 0
}
}
}
}
```
# Get Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2
POST https://api.velt.dev/v2/commentannotations/get
Use this API to retrieve comment annotations from a document within an organization.
Additional filters can be applied using location IDs, annotation IDs, or user IDs.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID. Pass a single document Id or use the documentIds field to pass multiple document Ids.
Array of Document IDs. Limit: Only 30 IDs can be passed at a time.
If you don't provide this, data for all documents will be fetched.
Data will be grouped by document ID.
Array of Location IDs. Limit: Only 30 IDs can be passed at a time.
Folder ID. Filters annotations by the folder.
Array of Annotation IDs. Limit: Only 30 IDs can be passed at a time.
Array of User IDs. Limit: Only 30 IDs can be passed at a time.
Status IDs of the annotations to filter on.
Filter annotations updated after the given lastUpdated timestamp (in milliseconds since epoch).
Filter annotations updated before the given lastUpdated timestamp (in milliseconds since epoch).
Filter annotations created after the given createdAt timestamp (in milliseconds since epoch).
Filter annotations created before the given createdAt timestamp (in milliseconds since epoch).
Number of items to be retrieved per page. Default: 1000.
Page token retrieved from previous API call.
## **Example Requests**
#### 1. Get annotations by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 2. Get annotations by organizationId and documentIds grouped by documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"],
"groupByDocumentId": true
}
}
```
#### 3. Get annotations by organizationId, documentId, and locationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 4. Get annotations by organizationId, documentId, locationIds, and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 5. Get annotations by organizationId, documentId, and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 6. Get annotations by organizationId, documentId, and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 7. Get annotations by organizationId, documentId, locationIds, and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"pageSize": 10,
"pageToken": "1720441573192",
"statusId": "OPEN"
}
}
```
#### 8. Get annotations by organizationId, statusIds, updatedAfter, and updatedBefore
```JSON theme={null}
{
"data": {
"organizationId": "myorg1",
"statusIds": ["OPEN"],
"updatedAfter": 1720441573192,
"updatedBefore": 1720441573192,
}
}
```
#### 9. Get annotations by organizationId, folderId
```JSON theme={null}
{
"data": {
"organizationId": "myorg1",
"folderId": "folderId1"
}
}
```
# Response
**Response Field Notes:**
* `reactionAnnotationIds`: Returns an array of reaction annotation IDs (strings), not full reaction objects
* `viewedBy`: This field is not currently returned by this endpoint
* `createdAt` and `lastUpdated`: Timestamps are returned in milliseconds since epoch for annotations and in ISO 8601 format for comments
#### Success Response with single documentId
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Annotations fetched successfully.",
"data": [
{
"comments": [
{
"commentId": 123456,
"type": "text",
"to": [],
"status": "updated",
"attachments": [],
"recorders": [],
"reactionAnnotationIds": [
"TPVIZ7VH6rgh4nKm2xjs",
"REgRT9CY852tr12m3kto"
],
"taggedUserContacts": [],
"customList": [],
"toOrganizationUserGroup": [],
"commentText": "This is a sample comment text.",
"commentHtml": "This is a sample comment text.
",
"lastUpdated": "2023-06-15T10:30:00Z",
"createdAt": 1687344600000,
"from": {
"userId": "user123",
"organizationId": "d448b95936703db7d0923122172fb13c",
"userSnippylyId": "1174701858709696",
"photoUrl": "",
"initial": "J",
"clientUserName": "John Doe",
"name": "John Doe",
"clientOrganizationId": "yourOrganizationId",
"plan": "trial",
"email": "john.doe@example.com",
"color": "#a259fe",
"textColor": "#FFFFFF",
"isAdmin": true
},
"isDraft": false,
"isCommentTextAvailable": true
}
],
"type": "comment",
"status": {
"id": "OPEN",
"name": "Open",
"color": "var(--velt-accent, #625DF5)",
"lightColor": "var(--velt-accent-light, #E7E8FA)",
"type": "default",
"svg": "\n \n
```JSON Single Document theme={null}
{
"result": {
"status": "success",
"message": "Annotations fetched successfully.",
"data": [
{
"comments": [
{
"commentId": 123456,
"type": "text",
"to": [],
"status": "updated",
"attachments": [],
"recorders": [],
"reactionAnnotationIds": [
"TPVIZ7VH6rgh4nKm2xjs",
"REgRT9CY852tr12m3kto"
],
"taggedUserContacts": [],
"customList": [],
"toOrganizationUserGroup": [],
"commentText": "This is a sample comment text.",
"commentHtml": "This is a sample comment text.
",
"lastUpdated": "2023-06-15T10:30:00Z",
"createdAt": 1687344600000,
"from": {
"userId": "user123",
"organizationId": "d448b95936703db7d0923122172fb13c",
"userSnippylyId": "1174701858709696",
"photoUrl": "",
"initial": "J",
"clientUserName": "John Doe",
"name": "John Doe",
"clientOrganizationId": "yourOrganizationId",
"plan": "trial",
"email": "john.doe@example.com",
"color": "#a259fe",
"textColor": "#FFFFFF",
"isAdmin": true
},
"isDraft": false,
"isCommentTextAvailable": true
}
],
"type": "comment",
"status": {
"id": "OPEN",
"name": "Open",
"color": "var(--velt-accent, #625DF5)",
"lightColor": "var(--velt-accent-light, #E7E8FA)",
"type": "default",
"svg": "\n \n
# Update Comment Annotations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations
POST https://api.velt.dev/v2/commentannotations/update
Use this API to update comment annotations in a document within an organization.
Additional filters can be applied using location IDs, annotation IDs, or user IDs.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Array of Location IDs
Array of User IDs. These are the users who created the comment annotation.
Array of Annotation IDs
Location ID
Location Name
Target Element
Element DOM Id
Target Text. Provide this if you want to add comment annotation on the provided text content.
Occurrence. Provide this if you want to add comment annotation on a text content.
Select All Content. Provide this if you want to select and add comment annotation on the entire text content of the target elementId.
User object from whom the Comment Annotation is added
Status
Status ID
Status Name
Type. Must be one of: `default`, `ongoing`, or `terminal`.
Text and comment pin color
Background color on the status indicator
Raw SVG of the icon.
Icon URL.
User object to whom the comment is assigned
Custom key/value metadata object
Priority
Priority ID
Priority Name
Priority Color
Priority Light Color
Old user's ID
Old user's name
Old user's email
New user's ID
New user's name
New user's email
## **Example Requests**
#### 1. Update all comment annotations by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"id": "inprogress",
"name": "In Progress",
"type": "ongoing"
}
}
}
}
```
#### 2. Update comment annotations by organizationId, documentId and locationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"id": "inprogress",
"name": "In Progress",
"type": "ongoing"
}
}
}
}
```
#### 3. Update annotations by organizationId, documentId, locationIds and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"userIds": [
"yourUserId"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"id": "inprogress",
"name": "In Progress",
"type": "ongoing"
}
}
}
}
```
#### 4. Update comment annotations by organizationId, documentId and userIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"id": "inprogress",
"name": "In Progress",
"type": "ongoing"
}
}
}
}
```
#### 5. Update comment annotations by organizationId, documentId and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"id": "inprogress",
"name": "In Progress",
"type": "ongoing"
}
}
}
}
```
#### 6. Update comment annotations by organizationId, documentId, locationIds and annotationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationIds": [
"locationx"
],
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updatedData" : {
"status": {
"id": "inprogress",
"name": "In Progress",
"type": "ongoing"
}
}
}
}
```
#### 7. Update Users in existing comment annotations
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1",
"yourAnnotationId2"
],
"updateUsers" : [
{
"oldUser": {
"userId": "oldUserId",
},
"newUser": {
"userId": "newUserId",
"name": "newUserName",
"email": "newUserEmail"
}
}
]
}
}
```
#### 8. Update comment annotations with access context
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationIds": [
"yourAnnotationId1"
],
"updatedData": {
"context": {
"access": {
"entityId": "numberOfAccounts",
"dashboardId": "salesDashboard"
}
}
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Annotations updated successfully.",
"data": {
"yourAnnotationId1": {
"success": true,
"id": "yourAnnotationId1",
"message": "Annotations updated successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Annotations updated successfully.",
"data": {
"yourAnnotationId1": {
"success": true,
"id": "yourAnnotationId1",
"message": "Annotations updated successfully"
}
}
}
}
```
# Add Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comments/add-comments
POST https://api.velt.dev/v2/commentannotations/comments/add
Use this API to add comments within a specific CommentAnnotation.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/comments/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
If set to true, a new organization will be created (if it doesn't exist) before the comment is added.
Document ID
If set to true, a new document will be created (if it doesn't exist) before the comment is added.
Comment Annotation ID
When enabled, verifies the user has access to the document before adding comments.
This ensures comments respect document access permissions configured via Access Control or Permission Provider.
Default: `false`
Array of Comment Data
Custom Comment ID. If not provided, Velt will generate a unique ID for the comment.
Comment content in plain text string
Comment content in HTML string
Custom key/value metadata object. This is used to store any additional information about the comment.
Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.
Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.
User object from whom the comment is added
Created At timestamp (in milliseconds since epoch).
Last Updated timestamp (in milliseconds since epoch).
Array of tagged user contacts
Display text of the tagged user (e.g. "@Username")
User ID of the tagged user
Email of the tagged user
Name of the tagged user
User ID of the tagged user
Array of attachments to include with the comment. See [Attachment](/api-reference/sdk/models/data-models#attachment) for full schema details.
Unique identifier for the attachment
File name of the attachment
Path to the file in storage bucket
File size in bytes
File type (e.g., "image", "video", "document")
Download URL of the attachment
Thumbnail URL of the attachment
MIME type of the attachment (e.g., "image/png", "video/mp4")
Custom metadata for the attachment (e.g., dimensions, timestamps, etc.)
## **Example Requests**
#### 1. Add comment in a CommentAnnotation by organizationId, documentId, and annotationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentData": [
{
"commentText": "Sample Comment",
"commentHtml": "Hello
",
"from": {
"userId": "yourUserId"
}
}
]
}
}
```
#### 2. Add comment with permission verification
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"verifyUserPermissions": true,
"commentData": [
{
"commentText": "Sample Comment",
"commentHtml": "Hello
",
"from": {
"userId": "yourUserId"
}
}
]
}
}
```
When `verifyUserPermissions` is enabled, the API verifies the user has access to the document before adding the comment. If verification fails, the request will be rejected.
#### 3. Add comment with attachments
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"createOrganization": true,
"documentId": "yourDocumentId",
"createDocument": true,
"annotationId": "yourAnnotationId",
"commentData": [
{
"commentId": 123,
"commentText": "Please review this screenshot",
"commentHtml": "Please review this screenshot
",
"context": {},
"attachments": [
{
"attachmentId": 100001,
"name": "screenshot.png",
"bucketPath": "attachments/org-123/doc-456/screenshot.png",
"size": 1024000,
"type": "image",
"url": "https://storage.googleapis.com/bucket/screenshot.png",
"thumbnail": "https://storage.googleapis.com/bucket/screenshot_thumb.png",
"mimeType": "image/png",
"metadata": {
"width": 1920,
"height": 1080,
"uploadedAt": 1696118400000
}
}
],
"from": {
"userId": "yourUserId"
}
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment(s) added successfully.",
"data": [
778115
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comment(s) added successfully.",
"data": [
778115
]
}
}
```
# Delete Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comments/delete-comments
POST https://api.velt.dev/v2/commentannotations/comments/delete
Use this API to delete comments within a specific CommentAnnotation.
Additional filters can be applied using comment IDs.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/comments/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Comment Annotation ID
Array of Comment IDs
## **Example Requests**
#### 1. Delete all comments of a CommentAnnotation by organizationId, documentId, and annotationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId"
}
}
```
#### 2. Delete specific comments of a CommentAnnotation by organizationId, documentId, annotationId and commentIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentIds": [
153783,
607395
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) deleted successfully.",
"data": {
"153783": {
"success": true,
"id": 153783,
"message": "Deleted successfully"
},
"607395": {
"success": false,
"id": 607395,
"message": "Not found"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) deleted successfully.",
"data": {
"153783": {
"success": true,
"id": 153783,
"message": "Deleted successfully"
}
}
}
}
```
# Get Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comments/get-comments
POST https://api.velt.dev/v2/commentannotations/comments/get
Use this API to retrieve comments in a specific CommentAnnotation.
Additional filters can be applied using comment IDs.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/comments/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Comment Annotation ID
User IDs
Array of Comment IDs
## **Example Requests**
#### 1. Get all comments with a CommentAnnotation by organizationId, documentId, and annotationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId"
}
}
```
#### 2. Get specific comments of a CommentAnnotation by organizationId, documentId, annotationId and commentIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentIds": [
153783,
607395
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) retrieved successfully.",
"data": [
{
"commentHtml": "Hello Updated 2
",
"commentId": 153783,
"commentText": "Sample Comment Text",
"from": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"lastUpdated": "2024-06-20T09:53:42.258Z",
"status": "added",
"type": "text",
"reactionAnnotations": [
{
"reactionId": "reaction_001",
"emoji": "👍",
"from": {
"userId": "user456",
"name": "Jane Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2024-06-20T09:55:00Z"
}
]
},
null // If comment not found
]
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comments(s) retrieved successfully.",
"data": [
{
"commentHtml": "Hello Updated 2
",
"commentId": 153783,
"commentText": "Sample Comment Text",
"from": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"lastUpdated": "2024-06-20T09:53:42.258Z",
"status": "added",
"type": "text",
"reactionAnnotations": [
{
"reactionId": "reaction_001",
"emoji": "👍",
"from": {
"userId": "user456",
"name": "Jane Smith",
"email": "jane.smith@example.com"
},
"createdAt": "2024-06-20T09:55:00Z"
}
]
}
]
}
}
```
# Update Comments
Source: https://docs.velt.dev/api-reference/rest-apis/v2/comments-feature/comments/update-comments
POST https://api.velt.dev/v2/commentannotations/comments/update
Use this API to update comments within a specific CommentAnnotation.
# Endpoint
`POST https://api.velt.dev/v2/commentannotations/comments/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID
Comment Annotation ID
Comment IDs
Comment data
Comment content in plain text string
Comment content in HTML string
Custom key/value metadata object. This is used to store any additional information about the comment.
Use this for self-hosting comments data. Set this as true if you are comments resolver data provider in the SDK.
Use this for self-hosting comments data. Set this as true if this comment will have text content. Sometimes, comments might only have attachments and in that case, set this as false.
User object from whom the comment is added
Array of tagged user contacts
Display text of the tagged user (e.g. "@Username")
User ID of the tagged user
Email of the tagged user
Name of the tagged user
User ID of the tagged user
Array of attachments to include with the comment. See [Attachment](/api-reference/sdk/models/data-models#attachment) for full schema details.
Unique identifier for the attachment
File name of the attachment
Path to the file in storage bucket
File size in bytes
File type (e.g., "image", "video", "document")
Download URL of the attachment
Thumbnail URL of the attachment
MIME type of the attachment (e.g., "image/png", "video/mp4")
Custom metadata for the attachment (e.g., dimensions, timestamps, etc.)
## **Example Requests**
#### 1. Update comment in a CommentAnnotation by organizationId, documentId, annotationId and commentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentIds": [
153783,
607395
],
"updatedData": {
"commentText": "Sample Updated Comment",
"commentHtml": "Hello Updated
"
}
}
}
```
#### 2. Update comment with attachments
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"annotationId": "yourAnnotationId",
"commentIds": [
123456
],
"updatedData": {
"commentText": "Updated comment text with new attachments",
"commentHtml": "Updated comment text with new attachments
",
"attachments": [
{
"attachmentId": 100001,
"name": "updated-screenshot.png",
"bucketPath": "attachments/org-123/doc-456/updated-screenshot.png",
"size": 1536000,
"type": "image",
"url": "https://storage.googleapis.com/bucket/updated-screenshot.png",
"thumbnail": "https://storage.googleapis.com/bucket/updated-screenshot_thumb.png",
"mimeType": "image/png",
"metadata": {
"width": 1920,
"height": 1080,
"updatedAt": 1696122000000
}
}
]
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Comment updated successfully.",
"data": {
"607395": {
"success": true,
"id": 607395,
"message": "Updated successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Comment updated successfully.",
"data": {
"607395": {
"success": true,
"id": 607395,
"message": "Updated successfully"
}
}
}
}
```
# Add CRDT Data
Source: https://docs.velt.dev/api-reference/rest-apis/v2/crdt/add-crdt-data
POST https://api.velt.dev/v2/crdt/add
Use this API to create new CRDT editor data on the backend. Use it with the [Multiplayer Editing (Yjs)](/realtime-collaboration/crdt/setup/core) feature.
# Endpoint
`POST https://api.velt.dev/v2/crdt/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body Parameters
Organization ID where the document belongs
Document ID containing the CRDT editor data
Unique identifier for the specific CRDT editor instance
The CRDT content to store. Must match the specified `type`: string for `text`/`xml`, object for `map`, array for `array`.
The CRDT data type. One of: `text`, `map`, `array`, `xml`.
Yjs content key name. Defaults to `content`. Use `default` for TipTap.
## Example Requests
**Text (e.g., CodeMirror):**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-collab-note",
"data": "Hello, collaborative world!",
"type": "text"
}
}
```
**Map (e.g., ReactFlow):**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-flow-editor",
"data": { "nodes": {}, "edges": {} },
"type": "map"
}
}
```
**Array:**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-list-editor",
"data": [{ "id": "1", "text": "Item 1" }, { "id": "2", "text": "Item 2" }],
"type": "array"
}
}
```
**XML (e.g., TipTap):**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-rich-text-editor",
"data": "Hello World ",
"type": "xml",
"contentKey": "default"
}
}
```
# Response
## Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "CRDT data added successfully."
}
}
```
## Error Responses
**CRDT data already exists for the given editor ID:**
```JSON theme={null}
{
"error": {
"message": "CRDT data already exists for this editor ID.",
"status": "ALREADY_EXISTS"
}
}
```
**Invalid arguments:**
```JSON theme={null}
{
"error": {
"message": "Editor ID is required.",
"status": "INVALID_ARGUMENT"
}
}
```
```json theme={null}
{
"result": {
"status": "success",
"message": "CRDT data added successfully."
}
}
```
# Get CRDT Data
Source: https://docs.velt.dev/api-reference/rest-apis/v2/crdt/get-crdt-data
POST https://api.velt.dev/v2/crdt/get
Use this API to retrieve CRDT editor data from the backend. Use it with the [Multiplayer Editing (Yjs)](/realtime-collaboration/crdt/setup/core) feature.
# Endpoint
`POST https://api.velt.dev/v2/crdt/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body Parameters
Organization ID where the document belongs
Document ID containing the CRDT editor data
Optional unique identifier for the specific CRDT editor instance. If omitted, returns all CRDT data for the document.
## Example Request
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-collab-note"
}
}
```
# Response
## Success Response
The response contains an array of CRDT data objects. Each object includes the editor data and metadata.
```JSON theme={null}
{
"result": {
"status": "success",
"message": "CRDT data retrieved successfully.",
"data": [
{
"data": "Hello, collaborative world!",
"id": "my-collab-note",
"lastUpdate": "2025-01-20T10:30:00.000Z",
"lastUpdatedBy": "user-123",
"sessionId": "session-abc-456"
}
]
}
}
```
### Response Fields
| Field | Type | Description |
| --------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
| `data` | `text` \| `map` \| `array` \| `xml` | The CRDT editor data. Type depends on the store type configured in the frontend. |
| `id` | `string` | Store identifier (editorId) |
| `lastUpdate` | `string` | ISO timestamp of last update |
| `lastUpdatedBy` | `string` | User ID who made the last update |
| `sessionId` | `string \| null` | Session ID or null |
## Error Response
```JSON theme={null}
{
"error": {
"message": "Organization ID is required",
"status": "INVALID_ARGUMENT"
}
}
```
```json theme={null}
{
"result": {
"status": "success",
"message": "CRDT data retrieved successfully.",
"data": [
{
"data": "Hello, collaborative world!",
"id": "my-collab-note",
"lastUpdate": "2025-01-20T10:30:00.000Z",
"lastUpdatedBy": "user-123",
"sessionId": "session-abc-456"
}
]
}
}
```
# Update CRDT Data
Source: https://docs.velt.dev/api-reference/rest-apis/v2/crdt/update-crdt-data
POST https://api.velt.dev/v2/crdt/update
Use this API to replace existing CRDT editor data on the backend. The update creates proper CRDT operations on the existing document state so connected clients can pick up the change. Use it with the [Multiplayer Editing (Yjs)](/realtime-collaboration/crdt/setup/core) feature.
# Endpoint
`POST https://api.velt.dev/v2/crdt/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body Parameters
Organization ID where the document belongs
Document ID containing the CRDT editor data
Unique identifier for the specific CRDT editor instance
The new CRDT content to replace existing data with. Must match the specified `type`: string for `text`/`xml`, object for `map`, array for `array`.
The CRDT data type. One of: `text`, `map`, `array`, `xml`.
Yjs content key name. Defaults to `content`. Use `default` for TipTap.
## Example Requests
**Text (e.g., CodeMirror):**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-collab-note",
"data": "Updated collaborative content!",
"type": "text"
}
}
```
**Map (e.g., ReactFlow):**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-flow-editor",
"data": { "nodes": { "node-1": { "label": "Updated" } }, "edges": {} },
"type": "map"
}
}
```
**Array:**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-list-editor",
"data": [{ "id": "1", "text": "Updated Item 1" }, { "id": "3", "text": "New Item 3" }],
"type": "array"
}
}
```
**XML (e.g., TipTap):**
```JSON theme={null}
{
"data": {
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"editorId": "my-rich-text-editor",
"data": "Updated content New heading ",
"type": "xml",
"contentKey": "default"
}
}
```
# Response
## Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "CRDT data updated successfully."
}
}
```
## Error Responses
**No CRDT data found for the given editor ID:**
```JSON theme={null}
{
"error": {
"message": "No CRDT data found for this editor ID.",
"status": "NOT_FOUND"
}
}
```
**Invalid arguments:**
```JSON theme={null}
{
"error": {
"message": "Data must be a string for type text.",
"status": "INVALID_ARGUMENT"
}
}
```
```json theme={null}
{
"result": {
"status": "success",
"message": "CRDT data updated successfully."
}
}
```
# Add Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v2/documents/add-documents
POST https://api.velt.dev/v2/organizations/documents/add
Use this API to add documents with metadata to an organization.
# Endpoint
`POST https://api.velt.dev/v2/organizations/documents/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
If set to true, a new organization will be created (if it doesn't exist) before the document(s) are created.
Array of Document objects
Folder ID to add the documents to.
If set to true and `folderId` is provided but doesn't exist, a new folder will be created before the document(s) are created.
## **Example Requests**
#### 1. Create new documents
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documents": [
{
"documentId": "yourDocumentId",
"documentName": "Your Document Name"
}
]
}
}
```
#### 2. Create new documents in a specific folder
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documents": [
{
"documentId": "yourDocumentId",
"documentName": "Your Document Name"
}
],
"folderId": "yourFolderId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) added successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Added Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) added successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Added Successfully"
}
}
}
}
```
# Delete Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v2/documents/delete-documents
POST https://api.velt.dev/v2/organizations/documents/delete
Use this API to delete specific documents from an organization.
# Endpoint
`POST https://api.velt.dev/v2/organizations/documents/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) deleted successfully.",
"data": {
"yourDocumentId1": {
"success": true,
"id": "6737987049068973",
"message": "Deleted Successfully"
},
"yourDocumentId2": {
"success": true,
"id": "2131443384150904",
"message": "Document does not exist"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) deleted successfully.",
"data": {
"yourDocumentId1": {
"success": true,
"id": "6737987049068973",
"message": "Deleted Successfully"
}
}
}
}
```
# Get Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v2/documents/get-documents-v2
POST https://api.velt.dev/v2/organizations/documents/get
Use this API to retrieve specific documents or all documents from an organization.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/organizations/documents/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs. Limit: Only 30 IDs can be passed at a time.
Folder ID. Filters documents by the given folder ID.
Number of items to be retrieved per page. Default: 1000.
Page token retrieved from previous API call.
## **Example Requests**
#### 1. Get all documents from organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"pageSize": 20,
"pageToken": "8740648311207869"
}
}
```
#### 2. Get specific documents from organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"],
}
}
```
#### 3. Get documents by organizationId, folderId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) retrieved successfully.",
"data": [
{
"documentName": "yourDocumentName",
"disabled": false,
"accessType": "public",
"id": "yourDocumentId",
}
],
"pageToken": "nextPageToken"
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) retrieved successfully.",
"data": [
{
"documentName": "yourDocumentName",
"disabled": false,
"accessType": "public",
"id": "yourDocumentId",
}
],
"pageToken": "nextPageToken"
}
}
```
# Move Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v2/documents/move-documents
POST https://api.velt.dev/v2/organizations/documents/move
Use this API to move documents to a different folder within an organization.
# Endpoint
`POST https://api.velt.dev/v2/organizations/documents/move`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs. Limit: Only 30 IDs can be passed at a time.
ID of the folder where documents will be moved
## **Example Requests**
#### Move documents to a folder
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1", "yourDocumentId2"],
"folderId": "targetFolderId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Documents moved successfully."
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Documents moved successfully."
}
}
```
# Update Access for Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v2/documents/update-document-access
POST https://api.velt.dev/v2/organizations/documents/access/update
Use this API to update the access type for a single or multiple documents at once.
You can update the default access type for all the documents associated with your API Key in [console](https://console.velt.dev/dashboard/config/appconfig).
# Endpoint
`https://api.velt.dev/v2/organizations/documents/access/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs
Access type for the documents. Allowed values: `organizationPrivate`, `restricted`, `public`.
[Learn more](/key-concepts/overview#access-control).
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId1, yourDocumentId2"],
"accessType": "organizationPrivate"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated access for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Document access type updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated access for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Document access type updated."
}
}
}
}
```
# Update Disabled State for Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v2/documents/update-document-disable-state
POST https://api.velt.dev/v2/organizations/documents/access/disablestate/update
Use this API to enable or disable both read and write access for all users.
Let's say your customer's trial or subscription has ended and you want to disable their access to the Velt data, you could use this to diable access to specific documents.
# Endpoint
`https://api.velt.dev/v2/organizations/documents/access/disablestate/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document IDs
Whether to disable read and write access to the specified documents. Allowed values: `true`, `false`
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentIds": ["yourDocumentId"],
"disabled": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"disabled": true,
"message": "Document disabled state updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for documents successfully.",
"data": {
"yourDocumentId": {
"success": true,
"disabled": true,
"message": "Document disabled state updated."
}
}
}
}
```
# Update Documents
Source: https://docs.velt.dev/api-reference/rest-apis/v2/documents/update-documents
POST https://api.velt.dev/v2/organizations/documents/update
Use this API to update metadata of documents within an organization.
# Endpoint
`POST https://api.velt.dev/v2/organizations/documents/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Document objects
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documents": [
{
"documentId": "yourDocumentId",
"documentName": "Your Document Name"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Document(s) updated successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Updated Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Document(s) updated successfully.",
"data": {
"yourDocumentId": {
"success": true,
"id": "8121657101517513",
"message": "Updated Successfully"
}
}
}
}
```
# Add Folder
Source: https://docs.velt.dev/api-reference/rest-apis/v2/folders/add-folder
POST https://api.velt.dev/v2/organizations/folders/add
Use this API to create a new folder in an organization.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/organizations/folders/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
If set to true, a new organization will be created (if it doesn't exist) before the folder is created.
Unique identifier for the new folder
Name of the folder
ID of the parent folder
Access type for the folder. Allowed values: `organizationPrivate`, `restricted`, `public`. [Learn more](/key-concepts/overview#access-control).
## **Example Requests**
#### 1. Create folder without access type
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folders": [
{
"folderId": "yourFolderId",
"folderName": "yourFolderName",
"parentFolderId": "yourParentFolderId"
}
]
}
}
```
#### 2. Create folder with restricted access type
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folders": [
{
"folderId": "folder2025",
"folderName": "folder2025",
"accessType": "restricted"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder created successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder added."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Folder created successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder added."
}
}
}
}
```
# Delete Folder
Source: https://docs.velt.dev/api-reference/rest-apis/v2/folders/delete-folder
POST https://api.velt.dev/v2/organizations/folders/delete
Delete a folder and all its contents (documents and subfolders).
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/organizations/folders/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
Organization ID
ID of the folder to delete.
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "org10",
"folderId": "folderId2"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder deletion initiated successfully.",
"data": null
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"code": "not-found",
"message": "Folder not found."
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Folder deletion initiated successfully.",
"data": null
}
}
```
# Get Folders
Source: https://docs.velt.dev/api-reference/rest-apis/v2/folders/get-folders
POST https://api.velt.dev/v2/organizations/folders/get
Use this API to retrieve the given folder's metadata and its subfolders. You can retrieve nested subfolders at any depth level using the `maxDepth` parameter. The response includes an `ancestors` array showing the parent hierarchy and an `inheritAccessFromParent` field indicating whether access is inherited.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/organizations/folders/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Folder ID to retrieve a specific folder and its subfolders. If not provided, all folders in the organization will be retrieved.
Maximum depth level for retrieving nested subfolders. Allows you to retrieve subfolders at any depth level. If not provided, only immediate subfolders are retrieved.
## **Example Requests**
#### 1. Get all folders in organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId"
}
}
```
#### 2. Get specific folder in an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId"
}
}
```
#### 3. Get folder with nested subfolders at specific depth
Use the `maxDepth` parameter to retrieve nested subfolders at any depth level. The response includes an `ancestors` array showing the parent hierarchy and an `inheritAccessFromParent` field indicating whether access is inherited.
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"maxDepth": 3
}
}
```
# Response
#### Success Response for All Folders
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folders retrieved successfully.",
"data": [
{
"folderId": "folderId1",
"folderName": "Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "root",
"apiKey": "yourApiKey",
"createdAt": 1738695615706,
"lastUpdated": 1738696287859,
"ancestors": ["root"],
"accessType": "public",
"inheritAccessFromParent": false
},
{
"folderId": "folderId2",
"folderName": "Folder 2",
"organizationId": "yourOrganizationId",
"parentFolderId": "root",
"apiKey": "yourApiKey",
"createdAt": 1738695077691,
"lastUpdated": 1738695077691,
"ancestors": ["root"],
"accessType": "restricted",
"inheritAccessFromParent": true
}
]
}
}
```
#### Success Response for Specific Folder
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder(s) retrieved successfully.",
"data": [
{
"folderId": "folderId1",
"folderName": "Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "root",
"apiKey": "yourApiKey",
"createdAt": 1738695077691,
"lastUpdated": 1738695077691,
"ancestors": ["root"],
"accessType": "public",
"inheritAccessFromParent": false,
"subFolders": [
{
"folderId": "childFolderId1",
"folderName": "Child Folder 1",
"organizationId": "yourOrganizationId",
"parentFolderId": "folderId1",
"apiKey": "yourApiKey",
"createdAt": 1738695615706,
"lastUpdated": 1738698727591,
"ancestors": ["root", "folderId1"],
"accessType": "public",
"inheritAccessFromParent": true
}
]
}
]
}
}
```
#### Success Response with maxDepth
When using `maxDepth`, the response includes deeply nested subfolders. Each folder includes an `ancestors` array showing its full parent hierarchy and an `inheritAccessFromParent` field indicating whether it inherits access permissions from its parent.
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder(s) retrieved successfully.",
"data": [
{
"folderId": "folder1",
"folderName": "folder1",
"parentFolderId": "root",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"createdAt": 1758876118035,
"lastUpdated": 1758876118035,
"ancestors": ["root"],
"accessType": "public",
"inheritAccessFromParent": false,
"subFolders": [
{
"folderId": "folder1.1",
"folderName": "folder1.1",
"parentFolderId": "folder1",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"createdAt": 1758876239180,
"lastUpdated": 1758876239180,
"ancestors": ["root", "folder1"],
"accessType": "public",
"inheritAccessFromParent": true,
"subFolders": [
{
"folderId": "folder1.1.1",
"folderName": "folder1.1.1",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"parentFolderId": "folder1.1",
"createdAt": 1758883072416,
"lastUpdated": 1758883072416,
"ancestors": ["root", "folder1", "folder1.1"],
"accessType": "public",
"inheritAccessFromParent": false,
"subFolders": [
{
"folderId": "folder1.1.1.1",
"folderName": "folder1.1.1.1",
"parentFolderId": "folder1.1.1",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"createdAt": 1758906266851,
"lastUpdated": 1758906266851,
"ancestors": ["root", "folder1", "folder1.1", "folder1.1.1"],
"accessType": "public",
"inheritAccessFromParent": true
}
]
}
]
}
]
}
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Folder(s) retrieved successfully.",
"data": [
{
"folderId": "folder1",
"folderName": "folder1",
"parentFolderId": "root",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"createdAt": 1758876118035,
"lastUpdated": 1758876118035,
"ancestors": ["root"],
"accessType": "public",
"inheritAccessFromParent": false,
"subFolders": [
{
"folderId": "folder1.1",
"folderName": "folder1.1",
"parentFolderId": "folder1",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"createdAt": 1758876239180,
"lastUpdated": 1758876239180,
"ancestors": ["root", "folder1"],
"accessType": "public",
"inheritAccessFromParent": true,
"subFolders": [
{
"folderId": "folder1.1.1",
"folderName": "folder1.1.1",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"parentFolderId": "folder1.1",
"createdAt": 1758883072416,
"lastUpdated": 1758883072416,
"ancestors": ["root", "folder1", "folder1.1"],
"accessType": "public",
"inheritAccessFromParent": false,
"subFolders": [
{
"folderId": "folder1.1.1.1",
"folderName": "folder1.1.1.1",
"parentFolderId": "folder1.1.1",
"apiKey": "yourApiKey",
"organizationId": "yourOrganizationId",
"createdAt": 1758906266851,
"lastUpdated": 1758906266851,
"ancestors": ["root", "folder1", "folder1.1", "folder1.1.1"],
"accessType": "public",
"inheritAccessFromParent": true
}
]
}
]
}
]
}
]
}
}
```
# Update Folder
Source: https://docs.velt.dev/api-reference/rest-apis/v2/folders/update-folder
POST https://api.velt.dev/v2/organizations/folders/update
Use this API to:
1. update metadata of a folder within an organization.
2. move a folder and its contents to a different parent folder.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
**Automatic Folder Move Handling:** When moving a folder to a different parent by updating the `parentFolderId`, the API automatically updates the folder's `ancestors` array and `accessType`, and propagates these changes to all subfolders within the moved folder.
# Endpoint
`POST https://api.velt.dev/v2/organizations/folders/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Unique identifier for the new folder
Name of the folder
ID of the parent folder
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folders": [
{
"folderId": "yourFolderId",
"folderName": "yourFolderName",
"parentFolderId": "yourParentFolderId"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder Updated successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder Updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Folder Updated successfully.",
"data": {
"yourFolderId": {
"success": true,
"id": "yourFolderId",
"message": "Folder Updated."
}
}
}
}
```
# Update Access for Folders
Source: https://docs.velt.dev/api-reference/rest-apis/v2/folders/update-folder-access
POST https://api.velt.dev/v2/organizations/folders/access/update
Use this API to update the access type for a single or multiple folders at once.
You can update the default access type for all the folders associated with your API Key in [console](https://console.velt.dev/dashboard/config/appconfig).
# Endpoint
`https://api.velt.dev/v2/organizations/folders/access/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Array of Folder IDs
Access type for the folders. Allowed values: `organizationPrivate`, `restricted`, `public`.
[Learn more](/key-concepts/overview#access-control).
Configure the folder to inherit access permissions from its parent folder. When set to `true`, the folder automatically inherits all access settings from its parent.
## **Example Requests**
#### 1. Update folder access type
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderIds": ["yourFolderId1, yourFolderId2"],
"accessType": "organizationPrivate"
}
}
```
#### 2. Configure folder to inherit access from parent
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderIds": ["yourFolderId1"],
"inheritFromParent": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated access for folders successfully.",
"data": {
"yourFolderId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Folder access type updated."
}
}
}
}
```
#### Success Inherit Access From Parent Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Folder access type updated.",
"data": {
"folder1": {
"success": true,
"accessType": null,
"inheritFromParent": true,
"message": "Folder access type updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated access for folders successfully.",
"data": {
"yourFolderId": {
"success": true,
"accessType": "organizationPrivate",
"message": "Folder access type updated."
}
}
}
}
```
# Delete All User Data
Source: https://docs.velt.dev/api-reference/rest-apis/v2/gdpr/delete-all-user-data-gdpr
POST https://api.velt.dev/v2/users/data/delete
Remove All User data from Velt.
Use this API to remove all user data from Velt. This will:
* remove their access from all the documents and data in the organization.
* remove them from @mention contact dropdown list.
* remove them from @mentions where they were tagged.
* remove all feature data created by the user. eg: comments, reactions etc.
- This API may take up to 5 minutes to return a 202 response since it runs an asynchronous job to delete user data across the system.
- To speed up this process, you can optionally provide the organizationIds where the user belongs.
- The actual deletion of data can take upto 24 hours to complete.
# Endpoint
`POST https://api.velt.dev/v2/users/data/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of user Ids.
Array of organization Ids. These are the organizations that the user is part of.
## **Example Request**
```JSON theme={null}
{
"data": {
"userIds": [
"yourUserId1",
"yourUserId2"
],
"organizationIds": [
"yourOrganizationId1",
"yourOrganizationId2"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"status": "success",
"message": "Data deletion process has been initiated.",
"data": {
"jobId": "dsQuvPmIynANgPLLEhCm",
"tasksCount": 5
},
"statusCode": 202
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"status": "success",
"message": "Data deletion process has been initiated.",
"data": {
"jobId": "dsQuvPmIynANgPLLEhCm",
"tasksCount": 5
},
"statusCode": 202
}
```
# Get All User Data
Source: https://docs.velt.dev/api-reference/rest-apis/v2/gdpr/get-all-user-data-gdpr
POST https://api.velt.dev/v2/users/data/get
Get all feature data for a user stored in Velt.
Use this API to get all feature data for a user stored in Velt.
* The data will be paginated and returned in chunks of 100 items per feature data.
* You can use the `nextPageToken` returned in the response to fetch the next chunk of data.
* If there are no more items to fetch, the `nextPageToken` will not be returned.
* Here is the data that will be included:
* **User profile data:** If they were added to any organization, document or folder.
* **Comments data:** All the comments created by the user or where they were involved in.
* **Reactions data:** All the reactions created by the user.
* **Notifications data:** All the notifications where the user was involved in.
* **Recordings data:** All the recordings created by the user.
This API may take a few seconds to return a response depending on the dataset size.
# Endpoint
`POST https://api.velt.dev/v2/users/data/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The organization Id of the organization that the user is part of.
The user Id of the user you want to get the data for.
Page token retrieved from previous API call.
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"pageToken": "yourPageToken"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"comments": [..], //Upto 100 items. Empty array if no items are found.
"reactions": [..], //Upto 100 items. Empty array if no items are found.
"recordings": [..], //Upto 100 items. Empty array if no items are found.
"notifications": [..] //Upto 100 items. Empty array if no items are found.
},
"nextPageToken": "bhdwdqwjs298e39e479ddkeuw==329" // This will be null if there are no more items to fetch.
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT",
"code": 500
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"comments": [..], //Upto 100 items. Empty array if no items are found.
"reactions": [..], //Upto 100 items. Empty array if no items are found.
"recordings": [..], //Upto 100 items. Empty array if no items are found.
"notifications": [..] //Upto 100 items. Empty array if no items are found.
},
"nextPageToken": "bhdwdqwjs298e39e479ddkeuw==329" //This will be null if there are no more items to fetch.
}
}
```
# Get Delete All User Data Status
Source: https://docs.velt.dev/api-reference/rest-apis/v2/gdpr/get-delete-user-data-status-gdpr
POST https://api.velt.dev/v2/users/data/delete/status
Get the status of the data deletion process for a user.
Use this API to get the status of the data deletion process for a user.
This API may take a few seconds to return a response depending on the dataset size.
# Endpoint
`POST https://api.velt.dev/v2/users/data/delete/status`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The job Id of the data deletion process.
## **Example Request**
```JSON theme={null}
{
"data": {
"jobId": "yourJobId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"isDeleteCompleted": true,
"tasksLeft": 0,
"lastTaskCompletedTime": 1748972106739
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT",
"code": 500
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Data fetched successfully.",
"data": {
"isDeleteCompleted": true,
"tasksLeft": 0,
"lastTaskCompletedTime": 1748972106739
}
}
}
```
# Broadcast Event
Source: https://docs.velt.dev/api-reference/rest-apis/v2/livestate/broadcast-event
POST https://api.velt.dev/v2/livestate/broadcast
Use this API to broadcast live state events to any document. Use it with the [Live State](/realtime-collaboration/live-state-sync/setup#get-live-data) feature.
# Endpoint
`POST https://api.velt.dev/v2/livestate/broadcast`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body Parameters
Organization ID where the document belongs
Document ID to broadcast the event to
Unique identifier for the live state data
The data to broadcast. Can be any valid serializable JSON object.
If true, merges the new data with existing data instead of replacing it
## Example Request
```JSON theme={null}
{
"organizationId": "YOUR_ORGANIZATION_ID",
"documentId": "YOUR_DOCUMENT_ID",
"liveStateDataId": "sample_live_state_data_id",
"data": {
"status": "active",
"message": "Hello World",
"customField": "custom value"
},
"merge": true
}
```
# Response
## Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Event broadcasted successfully.",
"data": {
"success": true
}
}
}
```
## Error Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "ERROR_CODE"
}
}
```
```json theme={null}
{
"result": {
"status": "success",
"message": "Event broadcasted successfully.",
"data": {
"success": true
}
}
}
```
# Add Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v2/notifications/add-notifications
POST https://api.velt.dev/v2/notifications/add
Use this API to add notifications.
# Endpoint
`POST https://api.velt.dev/v2/notifications/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
If set to true, a new organization will be created (if it doesn't exist) before the notification is created.
Document ID
If set to true, a new document will be created before the notification is created.
User who took the action
When enabled, notifications are only created for users who have access to the specified document.
This ensures notifications respect document access permissions configured via Access Control or Permission Provider.
Default: `false`
Notification ID. If not provided, Velt will generate a random ID.
Use this if you want more control on the ID being set and prevent duplicate notifications.
Only the special characters `_`, `-` are allowed.
Display Headline Message Template
Display Headline Message Template Data (Optional)
User who took the action
User who was directly affected by the action
Any custom field with string value
Display Body Message
Array of Notify Users
Default is true.
If set to true, the notification will be sent to all users in the organization.
If set to false, the notification will be sent to only the users specified in the `notifyUsers` array.
Any custom object to be stored with the notification.
When the user clicks on the notification, this data will be sent in the callback.
Context for filtering notifications. Use this to enable context-based filtering of notifications.
Key-value pairs for filtering. Keys are custom field names, values are strings or numbers.
```json theme={null}
{
"entityId": "numberOfVisitors",
"dashboardId": "myDashboard"
}
```
## **Example Request**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"actionUser": {
"userId": "yourUserId",
"name": "User Name",
"email": "user@example.com"
},
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"userId": "yourUserId",
"name": "User Name",
"email": "user@example.com"
},
"recipientUser": {
"userId": "recipientUserId",
"name": "Recipient Name",
"email": "recipient@example.com"
},
"yourCustomField": "Variable will be replaced with this text"
},
"displayBodyMessage": "This is body message (Secondary message)",
"notifyUsers": [
{
"email": "test@example.com",
"userId": "testingUserId"
},
{
"userId": "yourUserId",
"name": "User Name",
"email": "user@example.com"
}
]
}
}
```
## **Example Request with Permission Verification**
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"documentId": "document3",
"actionUser": {
"userId": "1.1"
},
"verifyUserPermissions": true,
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"userId": "1.1"
},
"recipientUser": {
"userId": "2.2"
}
},
"displayBodyMessage": "This is body message (Secondary message)",
"notifyUsers": [
{
"userId": "2.2"
}
],
"notifyAll": false
}
}
```
When `verifyUserPermissions` is enabled, the API checks document access for each user before creating notifications. Only users with access to the document will receive notifications.
## **Example Request with Context**
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"documentId": "document3",
"actionUser": {
"userId": "1.1",
"name": "User One",
"email": "user1@example.com"
},
"context": {
"access": {
"entityId": "numberOfVisitors",
"dashboardId": "myDashboard"
}
},
"displayHeadlineMessageTemplate": "New comment on {entityName}",
"displayHeadlineMessageTemplateData": {
"entityName": "Visitor Analytics"
},
"displayBodyMessage": "A new comment has been added to the visitor analytics dashboard",
"notifyUsers": [
{
"userId": "2.2"
}
],
"notifyAll": false
}
}
```
When context is provided, notifications will be filtered based on the specified context fields. Users will only receive notifications that match their context permissions.
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification added successfully.",
"data": {
"success": true,
"message": "Notification added successfully."
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification added successfully.",
"data": {
"success": true,
"message": "Notification added successfully."
}
}
}
```
# Delete Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v2/notifications/delete-notifications
POST https://api.velt.dev/v2/notifications/delete
Use this API to delete notifications.
# Endpoint
`POST https://api.velt.dev/v2/notifications/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID (Optional)
Location ID (Optional)
User ID (Optional)
Array of Notification IDs (Optional)
## **Example Requests**
#### 1. Delete by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId"
}
}
```
#### 2. Delete by organizationId, documentId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 3. Delete by organizationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId"
}
}
```
#### 4. Delete by organizationId, userId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 5. Delete by organizationId, documentId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId"
}
}
```
#### 6. Delete by organizationId, documentId, userId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 7.Delete by organizationId, documentId and locationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId"
}
}
```
#### 8. Delete by organizationId, documentId, locationId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 9. Delete by organizationId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"locationId": "yourLocationId",
"userId": "yourUserId",
}
}
```
#### 10. Delete by organizationId, locationId, userId, and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"locationId": "yourLocationId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 11. Delete by organizationId, documentId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"userId": "yourUserId",
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) deleted successfully.",
"data": {
"8955243231506071": {
"success": true,
"message": "Notification deleted."
}
}
}
}
```
#### When some notifications are not found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) deleted successfully.",
"data": {
"89552432315060712": {
"success": false,
"message": "Failed to delete notification."
},
"8955243231506071": {
"success": true,
"message": "Notification deleted."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) deleted successfully.",
"data": {
"8955243231506071": {
"success": true,
"message": "Notification deleted."
}
}
}
}
```
# Get Config
Source: https://docs.velt.dev/api-reference/rest-apis/v2/notifications/get-config
POST https://api.velt.dev/v2/notifications/config/get
To use this API, you must have the this feature enabled in [Velt console](https://console.velt.dev/dashboard/config/notification)
Use this API to get the notifications config for users.
# Endpoint
`POST https://api.velt.dev/v2/notifications/config/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The ID of the organization.
An array of document IDs. The notification configuration will be fetched for these documents for the specified user. Max 30 documents can be fetched at a time. Optional when `getOrganizationConfig` is `true`.
The ID of the user.
When `true`, fetches the org-level notification config for the user. `documentIds` is not required in this mode.
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"documentIds": ["doc1"],
"userId":"USER_ID1"
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"userId": "USER_ID1",
"getOrganizationConfig": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User config fetched successfully.",
"data": [
{
"config": {
"inbox": "ALL",
"email": "ALL"
},
"metadata": {
"organizationId": "org1",
"apiKey": "API_KEY",
"documentId": "doc1",
"userId": "USER_ID1"
}
}
]
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User config fetched successfully.",
"data": [
{
"config": {
"inbox": "ALL",
"email": "ALL"
},
"metadata": {
"organizationId": "org1",
"apiKey": "API_KEY",
"documentId": "doc1",
"userId": "USER_ID1"
}
}
]
}
}
```
# Get Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v2/notifications/get-notifications-v2
POST https://api.velt.dev/v2/notifications/get
Use this API to retrieve notifications.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/notifications/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID. Either pass this or userId.
Location ID
User ID. Either pass this or documentId.
Array of Notification IDs. Limit: Only 30 items can be passed at a time.
Number of items to be retrieved per page. Default: 1000.
Page token retrieved from previous API call.
Order of the notifications based on timestamp. Must be either `asc` or `desc`. Default: `desc`.
## **Example Requests**
#### 1. Get by organizationId, documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"pageSize": 20,
"pageToken": "8740648311207869"
}
}
```
#### 2. Get by organizationId, documentId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 3. Get by organizationId, documentId and locationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"pageSize": 20,
"pageToken": "8740648311207869"
}
}
```
#### 4. Get by organizationId, documentId, locationId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 5. Get by organizationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"pageSize": 20,
"pageToken": "8740648311207869"
}
}
```
#### 6. Get by organizationId, userId and notificationIds
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"notificationIds": [
"yourNotificationId"
]
}
}
```
#### 7. Get by organizationId, documentId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"pageSize": 20,
"pageToken": "8740648311207869"
}
}
```
#### 8. Get by organizationId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"locationId": "yourLocationId",
"pageSize": 20,
"pageToken": "8740648311207869"
}
}
```
#### 9. Get by organizationId, documentId, locationId, and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"locationId": "yourLocationId",
"pageSize": 20,
"pageToken": "8740648311207869"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) retrieved successfully.",
"data": [
{
"id": "notificationId",
"notificationSource": "custom",
"notificationSourceData": {}, //The data of the notification source. e.g., CommentAnnotation
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"displayBodyMessage": "This is body message (Secondary message)",
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"recipientUser": {
"email": "recipient@example.com",
"name": "Recipient Name",
"userId": "recipientUserId"
},
"yourCustomVariableWithStringValue": "Variable will be replaced with this text"
},
"metadata": {
"apiKey": "yourApiKey",
"documentId": "yourDocumentId",
"organizationId": "yourOrganizationId"
},
"notifyUsers": {
"yourNotifyUserId": true
},
"notifyUsersByUserId": {
"yourNotifyUserById": true
},
"timestamp": 1722409519944
}
],
"pageToken": "nextPageToken"
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) retrieved successfully.",
"data": [
{
"id": "notificationId",
"notificationSource": "custom",
"notificationSourceData": {}, //The data of the notification source. e.g., CommentAnnotation
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"displayBodyMessage": "This is body message (Secondary message)",
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"email": "user@example.com",
"name": "User Name",
"userId": "yourUserId"
},
"recipientUser": {
"email": "recipient@example.com",
"name": "Recipient Name",
"userId": "recipientUserId"
},
"yourCustomVariableWithStringValue": "Variable will be replaced with this text"
},
"metadata": {
"apiKey": "yourApiKey",
"documentId": "yourDocumentId",
"organizationId": "yourOrganizationId"
},
"notifyUsers": {
"yourNotifyUserId": true
},
"notifyUsersByUserId": {
"yourNotifyUserById": true
},
"timestamp": 1722409519944
}
],
"pageToken": "nextPageToken"
}
}
```
# Set Config
Source: https://docs.velt.dev/api-reference/rest-apis/v2/notifications/set-config
POST https://api.velt.dev/v2/notifications/config/set
To use this API, you must have the this feature enabled in [Velt console](https://console.velt.dev/dashboard/config/notification)
Use this API to set the notifications config for users.
# Endpoint
`POST https://api.velt.dev/v2/notifications/config/set`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
The ID of the organization.
An array of document IDs. The notification configuration will be applied to these documents for the specified users. When omitted, the config is applied at the organization level and stored as the user's default for all documents.
An array of user IDs. The notification configuration will be set for these users.
Object containing the notification preferences.
In-app inbox notification preference. Valid values:
`ALL`: User receives all notifications in their inbox.
`MINE`: User receives notifications in their inbox only for activities directly involving them (e.g., mentions, replies).
`NONE`: User receives no notifications in their inbox.
Optional.
Email notification preference. Valid values:
`ALL`: User receives email notifications for all activities.
`MINE`: User receives email notifications only for activities directly involving them.
`NONE`: User receives no email notifications.
Optional.
Slack notification preference (requires Slack integration to be effective). Valid values:
`ALL`: User receives Slack notifications for all activities.
`MINE`: User receives Slack notifications only for activities directly involving them.
`NONE`: User receives no Slack notifications.
Optional.
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"documentIds": ["doc1"],
"userIds": ["USER_ID1"],
"config": {
"inbox": "ALL",
"email": "ALL"
}
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "org1",
"userIds": ["USER_ID1"],
"config": {
"inbox": "ALL",
"email": "ALL"
}
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User config set successfully.",
"data": {
"USER_ID1": {
"success": true,
"userId": "USER_ID1",
"documentId": "doc1",
"message": "User config set successfully."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User config set successfully.",
"data": {
"USER_ID1": {
"success": true,
"userId": "USER_ID1",
"documentId": "doc1",
"message": "User config set successfully."
}
}
}
}
```
# Update Notifications
Source: https://docs.velt.dev/api-reference/rest-apis/v2/notifications/update-notifications
POST https://api.velt.dev/v2/notifications/update
Use this API to update notifications.
# Endpoint
`POST https://api.velt.dev/v2/notifications/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document ID (Optional)
Location ID
User ID (Optional)
When enabled, notifications are only updated for users who have access to the specified document.
This ensures notification updates respect document access permissions configured via Access Control or Permission Provider.
Default: `false`
Notifications object
Notification ID
User who took the action
Display Headline Message Template
Display Headline Message Template Data
User who took the action
User who was directly affected by the action
Any custom field with string value
Display Body Message
Any custom object to be stored with the notification.
When the user clicks on the notification, this data will be sent to in the callback.
Array of user ids that you want to mark the notification as read.
Use this with the `readByUserIds` param. If `true`, the read notifications will be not be removed from the "For You" tab.
## **Example Requests**
#### 1. Update by organizationId and documentId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 2. Update by organizationId, documentId and locationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"locationId": "yourLocationId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 3. Update by organizationId, documentId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 4. Update by organizationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userId": "yourUserId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 5. Update by organizationId, documentId, locationId and userId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userId": "yourUserId",
"locationId": "yourLocationId",
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is body message (Secondary message)",
}
]
}
}
```
#### 6. Update with Permission Verification
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"verifyUserPermissions": true,
"notifications": [
{
"id": "yourNotificationId",
"displayBodyMessage": "This is updated body message (Secondary message)"
}
]
}
}
```
When `verifyUserPermissions` is enabled, the API checks document access for each user before updating their notifications. Updates are only applied to users with access to the document.
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) updated successfully.",
"data": {
"5471488637912692": {
"success": true,
"message": "Notification updated."
}
}
}
}
```
#### When some notifications are not found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) updated successfully.",
"data": {
"5471488637912692": {
"success": false,
"message": "Failed to update notification."
},
"5471488637912693": {
"success": true,
"message": "Notification updated."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Notification(s) updated successfully.",
"data": {
"5471488637912692": {
"success": true,
"message": "Notification updated."
}
}
}
}
```
# Add Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/organizations/add-organizations
POST https://api.velt.dev/v2/organizations/add
Use this API to add new organizations and its metadata.
# Endpoint
`POST https://api.velt.dev/v2/organizations/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization objects
## **Example Requests**
#### Add organization
```JSON theme={null}
{
"data": {
"organizations": [
{
"organizationId": "yourOrganizationId",
"organizationName": "Your Organization Name"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) added successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Added Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) added successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Added Successfully"
}
}
}
}
```
# Delete Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/organizations/delete-organizations
POST https://api.velt.dev/v2/organizations/delete
Use this API to delete specific organization(s) data by their IDs.
# Endpoint
`POST https://api.velt.dev/v2/organizations/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization IDs
## **Example Requests**
#### Delete specific organization
```JSON theme={null}
{
"data": {
"organizationIds": [
"yourOrganizationId1",
"yourOrganizationId2"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) deleted successfully.",
"data": {
"yourOrganizationId1": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Deleted Successfully"
},
{
"yourOrganizationId2": {
"success": false,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Organization does not exist"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) deleted successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Deleted Successfully"
}
}
}
}
```
# Get Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/organizations/get-organizations-v2
POST https://api.velt.dev/v2/organizations/get
Use this API to retrieve specific organizations by organization IDs.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/organizations/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization IDs (Optional).
Limit: Only 30 IDs can be passed at a time.
If this is not provided, all organizations will be returned.
Number of items to be retrieved per page (Optional). Default: 1000.
Page token retrieved from previous API call. (Optional)
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationIds": [
"yourOrganizationId"
],
"pageSize": 1000,
"pageToken": "pageToken"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) retrieved successfully.",
"data": [
{
"id": "yourOrganizationId",
"organizationName": "Your Organization Name",
"disabled": false,
// other metadata fields may be included here
}
// ... more organizations if multiple were retrieved
],
"nextPageToken": "pageToken"
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) retrieved successfully.",
"data": [
{
"id": "yourOrganizationId",
"organizationName": "Your Organization Name",
"disabled": false,
// other metadata fields may be included here
}
// ... more organizations if multiple were retrieved
],
"nextPageToken": "pageToken"
}
}
```
# Update Disabled State for Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/organizations/update-organization-disable-state
POST https://api.velt.dev/v2/organizations/access/disablestate/update
Use this API to enable or disable both read and write access for all documents for all users.
Let's say your customer's trial or subscription has ended and you want to disable their access to the Velt data, you could use this to disable access to the entire organization data.
If organization does not exist, it will be created.
# Endpoint
`POST https://api.velt.dev/v2/organizations/access/disablestate/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization IDs
Whether to disable read and write access to the specified organizations. Allowed values: `true`, `false`.
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationIds": ["yourOrganizationId1","yourOrganizationId2"],
"disabled": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for Organization(s) successfully.",
"data": {
"yourOrganizationId1": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated disable state for organization Successfully"
},
"yourOrganizationId2": {
"success": false,
"id": "44e0132f4c6b0d453f18df42d2263b4e",
"message": "Organization does not exist"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Updated disable state for Organization(s) successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated disable state for organization Successfully"
}
}
}
}
```
# Update Organizations
Source: https://docs.velt.dev/api-reference/rest-apis/v2/organizations/update-organizations
POST https://api.velt.dev/v2/organizations/update
Use this API to update existing organization(s) metadata.
# Endpoint
`POST https://api.velt.dev/v2/organizations/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of Organization objects
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizations": [
{
"organizationId": "yourOrganizationId",
"organizationName": "Your Updated Organization Name"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) updated successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated Successfully"
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization(s) updated successfully.",
"data": {
"yourOrganizationId": {
"success": true,
"id": "02cf91e5e7a5f4c0b600c84cf248384b",
"message": "Updated Successfully"
}
}
}
}
```
# Add User Groups
Source: https://docs.velt.dev/api-reference/rest-apis/v2/user-groups/add-groups
POST https://api.velt.dev/v2/organizations/usergroups/add
Use this API to add organization user groups to a specific organization.
# Endpoint
`POST https://api.velt.dev/v2/organizations/usergroups/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
If set to true, a new organization will be created (if it doesn't exist) before the group(s) are created.
Array of Organization User Group objects
## **Example Request**
#### Add organization user group in a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroups": [
{
"groupId": "engineering",
"groupName": "Engineering"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Organization User Groups added successfully.",
"data": {
"yourGroupId": {
"success": true,
"id": "77ab6767b022ad0323ba39c24f12cc95",
"message": "Organization user group added."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Organization User Groups added successfully.",
"data": {
"yourGroupId": {
"success": true,
"id": "77ab6767b022ad0323ba39c24f12cc95",
"message": "Organization user group added."
}
}
}
}
```
# Add Users to Groups
Source: https://docs.velt.dev/api-reference/rest-apis/v2/user-groups/add-users-to-group
POST https://api.velt.dev/v2/organizations/usergroups/users/add
Use this API to add users to a specific organization user group.
# Endpoint
`POST https://api.velt.dev/v2/organizations/usergroups/users/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Organization User Group ID
Array of User IDs
## **Example Requests**
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupId": "yourGroupId",
"userIds": ["yourUserId1"]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Added organization users to group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User added to organization user group."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Added organization users to group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User added to organization user group."
}
}
}
}
```
# Delete Users from Groups
Source: https://docs.velt.dev/api-reference/rest-apis/v2/user-groups/delete-users-from-group
POST https://api.velt.dev/v2/organizations/usergroups/users/delete
Use this API to delete users from a specific organization user group.
# Endpoint
`POST https://api.velt.dev/v2/organizations/usergroups/users/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Organization User Group ID
Array of User IDs
If true, all users in the group will be deleted.
## **Example Requests**
#### Delete specific users from group
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupId": "yourGroupId",
"userIds": ["yourUserId1"]
}
}
```
#### Delete all users from group
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupId": "yourGroupId",
"deleteAll": true
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Deleted users from group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User deleted from organization user group."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Deleted users from group successfully.",
"data": {
"yourUserId1": {
"success": true,
"organizationUserGroupId": "yourGroupId",
"message": "User deleted from organization user group."
}
}
}
}
```
# Add Users
Source: https://docs.velt.dev/api-reference/rest-apis/v2/users/add-users
POST https://api.velt.dev/v2/users/add
Use this API to add Users to:
1. **Organization:** This will provide them access to all the documents in the organization unless the document has `restricted` access type. It will also show users in the contact list of the organization.
2. **Folder:** This will provide them access to all the documents in the folder. If you pass the `folderId`, then the users will be added to the folder and not the organization.
3. **Document:** This will provide them access to the specified document. It will also show users in the contact list of the document. If you pass the `documentId`, then the users will be added to the document and not the organization or folder.
* If organization does not exist, it will be created.
* If you provide documentId or folderId, then the users will only be added at that level and not at the organization level. To also add users at the organization level, you will need to call this API again with only the organizationId.
* If User's `initial` is not provided in the User object, then it will be automatically created using the name field.
**Access Control**
* Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource.
* `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`.
* Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`.
* See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
# Endpoint
`POST https://api.velt.dev/v2/users/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
If set to true, a new organization will be created (if it doesn't exist) before users are added.
Document ID. Provide this if you want to add users to a specific document.
If set to true and `documentId` is provided but doesn't exist, a new document will be created before users are added.
Folder ID. Provide this if you want to add users to a specific folder. Either provide `documentId` or `folderId`.
If set to true and `folderId` is provided but doesn't exist, a new folder will be created before users are added.
Array of [User](/api-reference/sdk/models/data-models#user) objects.
## **Example Requests**
#### 1. Add users to a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "editor"
}
]
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "viewer"
}
]
}
}
```
#### 2. Add users to a specific document within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "editor"
}
]
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "viewer"
}
]
}
}
```
#### 3. Add users to a specific folder within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "editor"
}
]
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "viewer"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "4c250058149d6c9fb8c894c9ef29c790",
"message": "User added."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "4c250058149d6c9fb8c894c9ef29c790",
"message": "User added."
}
}
}
}
```
# Delete Users
Source: https://docs.velt.dev/api-reference/rest-apis/v2/users/delete-users
POST https://api.velt.dev/v2/users/delete
Remove Users from an Organization or a Document.
Use this API to remove Users from:
1. **Organization:** This will remove their access from all the documents and data in the organization. It will also remove these users from the contact list of the organization.
2. **Document:** This will remove their access from the specified document. It will also remove these users from the contact list of the document. If you pass the `documentId`, then the users will be removed from the document.
# Endpoint
`POST https://api.velt.dev/v2/users/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Organization ID
Document IDs. Provide this if you want to delete users from a specific document.
Folder ID. Either provide `documentId` or `folderId`.
Array of user Ids.
## **Example Requests**
#### 1. Delete users in a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userIds": [
"yourUserId1"
]
}
}
```
#### 2. Delete users in a specific document within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId1"
]
}
}
```
#### 3. Delete users in a specific folder within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"userIds": [
"yourUserId1"
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) deleted successfully.",
"data": {
"yourUserId1": {
"success": true,
"message": "User removed."
}
}
}
}
```
#### User(s) Not Found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) deleted successfully.",
"data": {
"yourUserId1": {
"success": true,
"message": "User removed."
},
{
"yourUserId2": {
"success": false,
"message": "User does not exist."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) deleted successfully.",
"data": {
"yourUserId1": {
"success": true,
"message": "User removed."
}
}
}
}
```
# Get Users
Source: https://docs.velt.dev/api-reference/rest-apis/v2/users/get-users-v2
POST https://api.velt.dev/v2/users/get
Use this API to retrieve users based on various filters such as organization ID, document ID, organization user group IDs or user IDs. You can use these filters in various combinations to get the desired users. Some examples are shown below.
Prior to using this API, you must:
* Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
* Deploy v4 series of the Velt SDK.
# Endpoint
`POST https://api.velt.dev/v2/users/get`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### **Params**
Organization ID
Document ID
Folder ID. Either provide `documentId` or `folderId`.
Array of User IDs. Limit: Only 30 items can be passed at a time.
Array of Organization User Group IDs. Only 30 items can be passed at a time.
If true, all document users within the organization will be retrieved. You need not pass `documentId` in this case. This will not fetch organization-level users.
If true, the response will be grouped by document ID. This works when `allDocuments` is set to true.
Number of items to be retrieved per page. Default: 1000.
Page token retrieved from previous API call.
## **Example Requests**
#### 1. Get users by organizationId
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"pageSize": 1000,
"pageToken": "pageToken"
}
}
```
#### 2. Get users by documentId within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId"
}
}
```
#### 3. Get Users from all documents within an organization.
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"allDocuments": true,
"groupByDocumentId": true
}
}
```
#### 4. Get users by specific user IDs in an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userIds": [
"yourUserId1",
"yourUserId2"
]
}
}
```
#### 5. Get users by specific user IDs in the given organization and document
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"userIds": [
"yourUserId1",
"yourUserId2"
]
}
}
```
#### 6. Get users by organization and organization user group IDs
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"organizationUserGroupIds": [
"yourOrganizationUserGroupId"
]
}
}
```
#### 7. Get users by organization, organization user group IDs and user IDs
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"userIds": [
"yourUserId1",
"yourUserId2"
],
"organizationUserGroupIds": [
"yourOrganizationUserGroupId"
]
}
}
```
#### 8. Get users by folderId within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId"
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) retrieved successfully.",
"data": [
{
"email": "userEmail@domain.com",
"name": "userName",
"userId": "yourUserId"
}
],
"nextPageToken": "pageToken"
}
}
```
#### Success Response with allDocuments and groupByDocumentId
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) retrieved successfully.",
"data": {
"documentId1": [
{
"email": "userEmail@domain.com",
"name": "userName",
"userId": "yourUserId"
}
]
},
"nextPageToken": "pageToken"
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "Error retrieving user(s).",
"status": "ERROR_CODE"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) retrieved successfully.",
"data": [
{
"email": "userEmail@domain.com",
"name": "userName",
"userId": "yourUserId"
}
],
"pageToken": "pageToken"
}
}
```
# Update Users
Source: https://docs.velt.dev/api-reference/rest-apis/v2/users/update-users
POST https://api.velt.dev/v2/users/update
Use this API to update user metadata based on various filters such as organization ID, document ID, folder ID and user IDs.
You can use these filters in various combinations to get the desired results.
The user metadata such as name, email etc can be updated.
**Access Control**
* Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource.
* `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`.
* Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`.
* See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
# Endpoint
`POST https://api.velt.dev/v2/users/update`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### **Params**
Organization ID
Document ID
Folder ID. Either provide `documentId` or `folderId`.
Array of [User](/api-reference/sdk/models/data-models#user) objects.
## **Example Requests**
#### 1. Update users in a specific organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "editor"
}
]
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "viewer"
}
]
}
}
```
#### 2. Update users in a specific document within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "editor"
}
]
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "viewer"
}
]
}
}
```
#### 3. Update users in a specific folder within an organization
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "editor"
}
]
}
}
```
```JSON theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"folderId": "yourFolderId",
"users": [
{
"userId": "yourUserId1",
"name": "User Name",
"email": "user@email.com",
"accessRole": "viewer"
}
]
}
}
```
# Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "7d87015b055a168b098cf05b870e40ff",
"message": "User updated."
}
}
}
}
```
#### Some User(s) Not Found
```JSON theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "7d87015b055a168b098cf05b870e40ff",
"message": "User updated."
},
"yourUserId2": {
"success": false,
"id": "ad22d93b49ad990d2b3d582d08d7768a",
"message": "User does not exist."
}
}
}
}
```
#### Failure Response
```JSON theme={null}
{
"error": {
"message": "ERROR_MESSAGE",
"status": "INVALID_ARGUMENT"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "User(s) processed successfully.",
"data": {
"yourUserId1": {
"success": true,
"id": "7d87015b055a168b098cf05b870e40ff",
"message": "User updated."
}
}
}
}
```
# Add Domains
Source: https://docs.velt.dev/api-reference/rest-apis/v2/workspace/add-domain
POST https://api.velt.dev/v2/workspace/domains/add
Use this API to add new organizations and its metadata.
# Endpoint
`POST https://api.velt.dev/v2/workspace/domains/add`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of domains
# Example Request
```JSON theme={null}
{
"data": {
"domains" : [
"https://www.google.com",
"https://*.firebase.com"
]
}
}
```
# Example Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) added successfully to allowed domains.",
"data": {
"domainsAdded": [
"google.com",
"*.firebase.com"
]
}
}
}
```
#### Failure Response
##### If some domains are already in the allowed domains
```JSON theme={null}
{
"error": {
"details": {
"domainsAdded": [
"velt.dev"
],
"skippedDomains": [
"google.com"
]
},
"message": "Domain(s) added successfully to allowed domains. Skipped existing domains.",
"status": "INTERNAL"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) added successfully to allowed domains.",
"data": {
"domainsAdded": [
"google.com",
"*.firebase.com"
]
}
}
}
```
# Delete Domains
Source: https://docs.velt.dev/api-reference/rest-apis/v2/workspace/delete-domain
POST https://api.velt.dev/v2/workspace/domains/delete
Use this API to add new organizations and its metadata.
# Endpoint
`POST https://api.velt.dev/v2/workspace/domains/delete`
# Headers
Your API key.
Your [Auth Token](/security/auth-tokens).
# Body
#### Params
Array of domains
# Example Request
```JSON theme={null}
{
"data": {
"domains" : [
"https://www.google.com",
"https://*.firebase.com"
]
}
}
```
# Example Response
#### Success Response
```JSON theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) removed successfully from allowed domains.",
"data": {
"domainsRemoved": [
"google.com",
"*.firebase.com"
]
}
}
}
```
#### Failure Response
##### If some domains are not in the allowed domains
```JSON theme={null}
{
"error": {
"details": {
"domainsRemoved": [
"velt.dev"
],
"skippedDomains": [
"google.com"
]
},
"message": "Domain(s) removed successfully from allowed domains. Skipped non-existing domains.",
"status": "INTERNAL"
}
}
```
```js theme={null}
{
"result": {
"status": "success",
"message": "Domain(s) removed successfully from allowed domains.",
"data": {
"domainsRemoved": [
"google.com",
"*.firebase.com"
]
}
}
}
```
# API Methods Index
Source: https://docs.velt.dev/api-reference/sdk/api/api-methods
# Comments
### Threads
#### addCommentAnnotation()
Add a new comment annotation.
* Params: [AddCommentAnnotationRequest](/api-reference/sdk/models/data-models#addcommentannotationrequest)
* Returns: [AddCommentAnnotationEvent](/api-reference/sdk/models/data-models#addcommentannotationevent)
* React Hook: `useAddCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addcommentannotation)
#### addCommentOnSelectedText()
Add a comment on selected text.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addcommentonselectedtext)
#### addCommentOnElement()
Add a comment on a specific element.
* Params: `{ targetElement: object, commentData: array, status?: string }`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addcommentonelement)
#### addManualComment()
Add a comment with custom positioning.
* Params: `ManualCommentAnnotationConfig`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addmanualcomment)
#### deleteCommentAnnotation()
Delete a comment annotation.
* Params: [DeleteCommentAnnotationRequest](/api-reference/sdk/models/data-models#deletecommentannotationrequest)
* Returns: [DeleteCommentAnnotationEvent](/api-reference/sdk/models/data-models#deletecommentannotationevent)
* React Hook: `useDeleteCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deletecommentannotation)
#### deleteSelectedComment()
Delete the currently selected comment.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deleteselectedcomment)
#### getCommentAnnotationsCount()
Get the total and unread comment annotations count for specified documents.
* Params: [CommentRequestQuery](/api-reference/sdk/models/data-models#commentrequestquery) (optional)
* Returns: [`Observable`](/api-reference/sdk/models/data-models#getcommentannotationscountresponse)
* React Hook: `useCommentAnnotationsCount()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcommentannotationscount)
#### getUnreadCommentAnnotationCountByLocationId()
Get count of unread comment annotations by location ID.
* Params: `locationId: string`
* Returns: `Observable`
* React Hook: `useUnreadCommentAnnotationCountByLocationId()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentannotationcountbylocationid)
#### getCommentAnnotations()
Get all the comment annotations for all the specified documents.
* Params: [CommentRequestQuery](/api-reference/sdk/models/data-models#commentrequestquery) (optional)
* Returns: [`Observable`](/api-reference/sdk/models/data-models#getcommentannotationsresponse)
* React Hook: `useGetCommentAnnotations()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcommentannotations)
#### getSelectedComments()
Get currently selected comment annotations.
* Params: none
* Returns: `Observable`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getselectedcomments)
#### getCommentAnnotationById()
Get a specific comment annotation by ID.
* Params: `{ annotationId: string, documentId?: string }`
* Returns: `Observable`
* React Hook: `useCommentAnnotationById()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcommentannotationbyid)
#### getElementRefByAnnotationId()
Get the DOM element reference for a comment annotation.
* Params: `annotationId: string`
* Returns: `string`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getelementrefbyannotationid)
#### submitComment()
Programmatically submit a comment from a composer.
* Params: [`SubmitCommentRequest`](/api-reference/sdk/models/data-models#submitcommentrequest)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#submitcomment)
#### enableDraftMode()
Enable Draft Mode to save partial comments as drafts.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#draftmode)
#### disableDraftMode()
Disable Draft Mode to prevent saving partial comments as drafts.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#draftmode)
#### clearComposer()
Reset composer state including text, attachments, recordings, tagged users, assignments, custom lists.
* Params: [`ClearComposerRequest`](/api-reference/sdk/models/data-models#clearcomposerrequest)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#clearcomposer)
#### getComposerData()
Fetch current composer state on-demand. Returns same data structure as composerTextChange event.
* Params: [`GetComposerDataRequest`](/api-reference/sdk/models/data-models#getcomposerdatarequest)
* Returns: [`ComposerTextChangeEvent`](/api-reference/sdk/models/data-models#composertextchangeevent) | `null`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcomposerdata)
#### setContextProvider()
Set a function to provide context dynamically for comment annotations.
* Params: [`CommentContextProvider`](/api-reference/sdk/models/data-models#commentcontextprovider) | `null`
* Returns: `void`
* React Hook: `useSetContextProvider()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcontextprovider)
#### updateVisibility()
Programmatically set comment visibility to `public`, `organizationPrivate`, or `restricted`. When setting `restricted` type, the current user's `userId` is automatically appended to `userIds` if not already present.
* Params: `annotationId: string`, [`config: CommentVisibilityConfig`](/api-reference/sdk/models/data-models#commentvisibilityconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatevisibility)
#### enablePrivateMode()
Enable private mode so new comments are created with restricted visibility by default.
* Params: [`PrivateModeConfig`](/api-reference/sdk/models/data-models#privatemodeconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableprivatemode)
#### disablePrivateMode()
Disable private mode, reverting new comments to default visibility.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#disableprivatemode)
#### enableVisibilityOptions()
Enable the visibility banner in the comment composer, letting users set visibility before submitting.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#visibilityoptions)
#### disableVisibilityOptions()
Disable the visibility banner in the comment composer.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#visibilityoptions)
#### setAssignToType()
Configure assignment UI mode.
* Params: [`AssignToConfig`](/api-reference/sdk/models/data-models#assigntoconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setassigntotype)
#### enableContextInPageModeComposer()
Enable passing context data to page mode composer when opening via comment tool.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#contextinpagemodecomposer)
#### disableContextInPageModeComposer()
Disable passing context data to page mode composer.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#contextinpagemodecomposer)
#### clearPageModeComposerContext()
Clear context data from page mode composer.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#contextinpagemodecomposer)
#### enableFormatOptions()
Enable text formatting toolbar in comment composers.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableformatoptions)
#### disableFormatOptions()
Disable text formatting toolbar in comment composers.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableformatoptions)
#### setFormatConfig()
Configure individual text formatting options (bold, italic, underline, strikethrough).
* Params: [`FormatConfig`](/api-reference/sdk/models/data-models#formatconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setformatconfig)
### Slate
#### withVeltComments()
Higher-order function that enhances a Slate editor with Velt comments capabilities.
* Params:
* `editor: Editor`
* `options?: VeltCommentsEditorOptions`
* Returns: `VeltCommentsEditor`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/slatejs#withveltcomments)
#### addComment()
Creates a comment annotation for the currently selected text in the editor.
* Signature: `async (request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)`) => Promise`
* Params: `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/slatejs#addcomment)
#### renderComments()
Renders and highlights comment annotations in the editor.
* Signature: `(request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest)`) => void`
* Params: `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/slatejs#rendercomments)
#### SlateVeltComment
React component that renders a Velt comment text element with annotation ID.
* Params:
* `props: RenderElementProps`
* `element:` [VeltCommentsElement](/api-reference/sdk/models/data-models#veltcommentselement)
* Returns: `N/A`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/slatejs#slateveltcomment)
### Tiptap
#### TiptapVeltComments.configure()
A custom Tiptap extension for Velt comments.
* Params: `options?:` [TiptapVeltCommentsOptions](/api-reference/sdk/models/data-models#tiptapveltcommentsoptions)
* Returns: `TiptapVeltComments`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/tiptap#tiptapveltcomments)
#### addComment()
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)
* `editor: Editor`
* `editorId?: string`
* `context?: unknown`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/tiptap#addcomment)
#### renderComments()
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest)
* `editor: Editor`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/tiptap#rendercomments)
### Lexical
#### addComment()
Creates a comment annotation for the currently selected text in the editor.
* Signature: `addComment: async (request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-3)) `=> Promise`
* Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-3)
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/lexical#addcomment)
#### renderComments()
Renders and highlights comment annotations in the editor.
* Signature: `renderComments: (request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-3)`) => void`
* Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-3)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/lexical#rendercomments)
#### exportJSONWithoutComments()
Export the editor state JSON while stripping comment nodes and normalizing adjacent text nodes.
* Signature: `exportJSONWithoutComments(editor: LexicalEditor): SerializedEditorState`
* Params: `editor:` [`LexicalEditor`](https://lexical.dev/docs/api/classes/lexical.LexicalEditor)
* Returns: `SerializedEditorState`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/lexical#exportjsonwithoutcomments)
### Plate
#### VeltCommentsPlugin.configure()
A Plate.js plugin for Velt comments.
* Params: `options?:` [VeltCommentsPluginConfig](/api-reference/sdk/models/data-models#veltcommentspluginconfig)
* Returns: `Plate Plugin`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/plate#veltcommentsplugin)
#### addComment()
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-4)
* `editor: PlateEditor`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/plate#addcomment)
#### renderComments()
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-4)
* `editor: PlateEditor`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/plate#rendercomments)
#### exportJSONWithoutComments()
Exports the editor content as JSON with Velt comment elements removed.
* Params: `content: Descendant[]`
* Returns: `Descendant[]`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/plate#exportjsonwithoutcomments)
#### PlateVeltComment
React component that renders a Velt comment element in the editor.
* Params:
* `props: PlateRenderElementProps`
* `element:` [VeltCommentsElement](/api-reference/sdk/models/data-models#veltcommentselement-2)
* Returns: `N/A`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/plate#plateveltcomment)
### CodeMirror
#### CodemirrorVeltComments()
Creates the Velt Comments extension for CodeMirror.
* Params: `config?:` [CodemirrorVeltCommentsConfig](/api-reference/sdk/models/data-models#codemirrorveltcommentsconfig)
* Returns: CodeMirror `Extension`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/codemirror#codemirrorveltcomments)
#### addComment()
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-4)
* `editor: EditorView`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/codemirror#addcomment)
#### renderComments()
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-4)
* `editor: EditorView`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/codemirror#rendercomments)
### Ace
#### AceVeltComments()
Initializes the Velt Comments extension for an Ace Editor instance.
* Params: `editor: Ace.Editor`, `config?:` [AceVeltCommentsConfig](/api-reference/sdk/models/data-models#aceveltcommentsconfig)
* Returns: `() => void` - Cleanup function to remove event listeners
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/ace#aceveltcomments)
#### addComment()
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-5)
* `editor: Ace.Editor`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/ace#addcomment)
#### renderComments()
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-5)
* `editor: Ace.Editor`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/ace#rendercomments)
### Quill
#### QuillVeltComments
The Velt Comments module for Quill. Register it with Quill before creating the editor.
* Params: `config?:` [QuillVeltCommentsConfig](/api-reference/sdk/models/data-models#quillveltcommentsconfig)
* Returns: `Quill Module`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/quill#quillveltcomments)
#### addComment()
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-6)
* `editor: Quill`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/quill#addcomment)
#### renderComments()
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-6)
* `editor: Quill`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/setup/quill#rendercomments)
### Messages
#### addComment()
Add a comment to a specific comment annotation.
* Params: [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)
* Returns: [AddCommentEvent](/api-reference/sdk/models/data-models#addcommentevent)
* React Hook: `useAddComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addcomment)
#### updateComment()
Update a comment in a specific comment annotation.
* Params: [UpdateCommentRequest](/api-reference/sdk/models/data-models#updatecommentrequest)
* Returns: [UpdateCommentEvent](/api-reference/sdk/models/data-models#updatecommentevent)
* React Hook: `useUpdateComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecomment)
#### deleteComment()
Delete a comment from a specific comment annotation.
* Params: [DeleteCommentRequest](/api-reference/sdk/models/data-models#deletecommentrequest)
* Returns: [DeleteCommentEvent](/api-reference/sdk/models/data-models#deletecommentevent)
* React Hook: `useDeleteComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deletecomment)
#### getComment()
Get comments from a specific comment annotation.
* Params: [GetCommentRequest](/api-reference/sdk/models/data-models#getcommentrequest)
* Returns: [Comment\[\]](/api-reference/sdk/models/data-models#comment)
* React Hook: `useGetComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcomment)
#### getUnreadCommentCountOnCurrentDocument()
Get the number of unread comments on the current document.
* Params: none
* Returns: `Observable`
* React Hook: `useUnreadCommentCountOnCurrentDocument()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentcountoncurrentdocument)
#### getUnreadCommentCountByLocationId()
Get the number of unread comments by location ID.
* Params: `locationId: string`
* Returns: `Observable`
* React Hook: `useUnreadCommentCountByLocationId()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentcountbylocationid)
#### getUnreadCommentCountByAnnotationId()
Get the number of unread comments by annotation ID.
* Params: `annotationId: string`
* Returns: `Observable`
* React Hook: `useUnreadCommentCountByAnnotationId()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentcountbyannotationid)
#### markAsRead()
Mark a comment annotation as read for the current user.
* Params: `annotationId: string`
* Returns: `Promise`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#markasread)
#### markAsUnread()
Mark a comment annotation as unread for the current user.
* Params: `annotationId: string`
* Returns: `Promise`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#markasunread)
### @Mentions
#### assignUser()
Assign a user to a comment annotation.
* Params: [AssignUserRequest](/api-reference/sdk/models/data-models#assignuserrequest)
* Returns: [AssignUserEvent](/api-reference/sdk/models/data-models#assignuserevent)
* React Hook: `useAssignUser()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#assignuser)
#### disableCustomAutocompleteSearch()
Disable custom autocomplete search for contact list.
* Params: `none`
* Returns: `void`
* React Hook: `useContactUtils()` or `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecustomautocompletesearch)
#### enableAtHere()
Enable or disable @here mentions.
* Params: none
* Returns: `void`
* React Hook: `useContactUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableathere)
#### enableUserMentions()
Enable or disable user @mentions.
* Params: none
* Returns: `void`
* React Hook: `useContactUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableusermentions)
#### enablePaginatedContactList()
Enable paginated loading of contact list.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablepaginatedcontactlist)
#### disablePaginatedContactList()
Disable paginated loading of contact list.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablepaginatedcontactlist)
#### enableCustomAutocompleteSearch()
Enable custom autocomplete search for contact list.
* Params: `none`
* Returns: `void`
* React Hook: `useContactUtils()` or `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecustomautocompletesearch)
#### getContactList()
Subscribe to the list of users added to organization, folder, document, user groups or the ones overwritten using the `updateContactList` API.
* Params: none
* Returns: [`Observable`](/api-reference/sdk/models/data-models#getcontactlistresponse)
* React Hook: `useContactList()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcontactlist)
#### onContactSelected()
Listen for when a contact is selected from the dropdown.
* Params: none
* Returns: [`Observable`](/api-reference/sdk/models/data-models#usercontactselectedpayload)
* React Hook: `useContactSelected()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#oncontactselected)
#### setAtHereLabel()
Customize the @here label text.
* Params: `label: string`
* Returns: `void`
* React Hook: `useContactUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setatherelabel)
#### setAtHereDescription()
Customize the @here description text.
* Params: `description: string`
* Returns: `void`
* React Hook: `useContactUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setatheredescription)
#### subscribeCommentAnnotation()
Subscribe to a comment annotation.
* Params: [SubscribeCommentAnnotationRequest](/api-reference/sdk/models/data-models#subscribecommentannotationrequest)
* Returns: [SubscribeCommentAnnotationEvent](/api-reference/sdk/models/data-models#subscribecommentannotationevent)
* React Hook: `useSubscribeCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#subscribecommentannotation)
#### unsubscribeCommentAnnotation()
Unsubscribe from a comment annotation.
* Params: [UnsubscribeCommentAnnotationRequest](/api-reference/sdk/models/data-models#unsubscribecommentannotationrequest)
* Returns: [UnsubscribeCommentAnnotationEvent](/api-reference/sdk/models/data-models#unsubscribecommentannotationevent)
* React Hook: `useUnsubscribeCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#unsubscribecommentannotation)
#### updateContactList()
Update the contact list for the current user session.
* Params: `contacts: Array<{userId: string, name: string, email: string}>, options?: {merge: boolean}`
* Returns: `void`
* React Hook: `useContactUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecontactlist)
#### updateContactListScopeForOrganizationUsers()
Restrict which contacts are shown in the dropdown for organization users.
* Params: `scopes: Array<'all' | 'organization' | 'organizationUserGroup' | 'document'>`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecontactlistscopefororganizationusers)
### Metadata
#### addContext()
Add custom metadata to a comment annotation.
* Params: `{ [key: string]: any }`
* Returns: `void`
* React Hook: `useCommentEventCallback('addCommentAnnotation')`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addcontext)
#### updateContext()
Update custom metadata on a comment annotation.
* Params: `annotationId: string, context: { [key: string]: any }, config?: { merge: boolean }`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecontext)
### Custom Lists
#### addCustomListDataOnAnnotation()
Add a custom dropdown list at the Comment Annotation level.
* Params: `{ type: 'multi' | 'single', placeholder: string, data: Array<{ id: string, label: string }> }`
* Returns: `void`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#createcustomlistdataoncomment)
#### addCustomListDataOnComment()
Add a custom dropdown list that appears when a hotkey is pressed in the comment composer.
* Params: `{ hotkey: string, type: 'custom', data: Array }`
* Returns: `void`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#createcustomlistdataoncomment)
#### onAutocompleteChipClick()
Listen for clicks on autocomplete chips in comments.
* Params: none
* Returns: `Observable`
* React Hook: `useAutocompleteChipClick()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#createcustomlistdataoncomment)
#### enableCustomAutocompleteSearch()
Enable custom autocomplete search for custom list.
* Params: `none`
* Returns: `void`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecustomautocompletesearch)
#### disableCustomAutocompleteSearch()
Disable custom autocomplete search for custom list.
* Params: `none`
* Returns: `void`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecustomautocompletesearch)
### Event Subscription
#### on()
Subscribe to comment events.
* Params: `CommentEventType`. [Here](/async-collaboration/comments/customize-behavior#on) is the list of event types you can subscribe to.
* Returns: `Observable`. [Here](/api-reference/sdk/models/data-models#comment) is the list of events object types you can expect to receive.
* React Hook: `useCommentEventCallback(CommentEventType)`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#on)
### Attachments
#### enableAttachments()
Enable file attachments in comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableattachments)
#### enableAttachmentDownload()
Allow clicking an attachment to trigger a file download.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableattachmentdownload)
#### disableAttachmentDownload()
Prevent clicking an attachment from triggering a file download; `attachmentDownloadClicked` still fires.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableattachmentdownload)
#### enableScreenshot()
Enable screenshot option in comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablescreenshot)
#### disableScreenshot()
Disable screenshot option in comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablescreenshot)
#### addAttachment()
Add an attachment to a specific comment annotation.
* Params: [AddAttachmentRequest](/api-reference/sdk/models/data-models#addattachmentrequest)
* Returns: `Promise`
* React Hook: `useAddAttachment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addattachment)
#### deleteAttachment()
Delete an attachment from a specific comment annotation.
* Params: [DeleteAttachmentRequest](/api-reference/sdk/models/data-models#deleteattachmentrequest)
* Returns: `Promise`
* React Hook: `useDeleteAttachment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deleteattachment)
#### getAttachment()
Get attachments from a specific comment annotation.
* Params: [GetAttachmentRequest](/api-reference/sdk/models/data-models#getattachmentrequest)
* Returns: `Promise`
* React Hook: `useGetAttachment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getattachment)
#### setAllowedFileTypes()
Limit file types in comment attachments by specifying allowed file extensions.
* Params: `string[]` (array of file extensions)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#allowedfiletypes)
#### setComposerFileAttachments()
Programmatically add file attachments to the comment composer from your application instead of requiring users to select files from the file system.
* Params: [UploadFileData](/api-reference/sdk/models/data-models#uploadfiledata)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcomposerfileattachments)
#### enableAttachmentDownload()
Enable automatic file downloads when clicking the download button on attachments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#attachmentdownload)
#### disableAttachmentDownload()
Disable automatic file downloads. The `attachmentDownloadClicked` event still fires, allowing custom download logic.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#attachmentdownload)
### Reactions
#### enableReactions()
Enable emoji reactions in comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablereactions)
#### setCustomReactions()
Set custom reactions by passing a map containing reaction information.
* Params: `{[reactionId: string]: {url?: string, emoji?: string}}`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcustomreactions)
#### addReaction()
Add a reaction to a specific comment annotation.
* Params: [AddReactionRequest](/api-reference/sdk/models/data-models#addreactionrequest)
* Returns: `Promise`
* React Hook: `useAddReaction()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addreaction)
#### deleteReaction()
Delete a reaction from a specific comment annotation.
* Params: [DeleteReactionRequest](/api-reference/sdk/models/data-models#deletereactionrequest)
* Returns: `Promise`
* React Hook: `useDeleteReaction()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deletereaction)
#### toggleReaction()
Toggle a reaction for a specific comment annotation.
* Params: [ToggleReactionRequest](/api-reference/sdk/models/data-models#togglereactionrequest)
* Returns: `Promise`
* React Hook: `useToggleReaction()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#togglereaction)
### Status & Priority
#### enableStatus()
Enable status dropdown & filters in comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablestatus)
#### setCustomStatus()
Set custom statuses by passing an array of status objects.
* Params: `StatusConfig[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcustomstatus)
#### enableResolveButton()
Enable resolve button on comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableresolvebutton)
#### updateStatus()
Update the status of a comment annotation.
* Params: [UpdateStatusRequest](/api-reference/sdk/models/data-models#updatestatusrequest)
* Returns: `Promise`
* React Hook: `useUpdateStatus()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatestatus)
#### resolveCommentAnnotation()
Resolve a comment annotation.
* Params: [ResolveCommentAnnotationRequest](/api-reference/sdk/models/data-models#resolvecommentannotationrequest)
* Returns: `Promise`
* React Hook: `useResolveCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#resolvecommentannotation)
#### enablePriority()
Enable priority settings in comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablepriority)
#### setCustomPriority()
Set custom priorities by passing an array of priority objects.
* Params: `PriorityConfig[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcustompriority)
#### updatePriority()
Update the priority of a comment annotation.
* Params: [UpdatePriorityRequest](/api-reference/sdk/models/data-models#updatepriorityrequest)
* Returns: `Promise`
* React Hook: `useUpdatePriority()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatepriority)
### Recordings
#### deleteRecording()
Delete a recording from a comment.
* Params: [DeleteRecordingRequest](/api-reference/sdk/models/data-models#deleterecordingrequest)
* Returns: `Promise`
* React Hook: `useDeleteRecording()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deleterecording)
#### getRecording()
Get recordings from a comment.
* Params: [GetRecordingRequest](/api-reference/sdk/models/data-models#getrecordingrequest)
* Returns: `Promise`
* React Hook: `useGetRecording()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getrecording)
#### setAllowedRecordings()
Set allowed recording types (audio, video, screen).
* Params: `string`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setallowedrecordings)
#### enableRecordingCountdown()
Enable countdown before recording starts.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablerecordingcountdown)
#### enableRecordingTranscription()
Enable AI transcription for recordings.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablerecordingtranscription)
### Deep Link
#### getLink()
Get a link to a specific comment annotation.
* Params: [GetLinkRequest](/api-reference/sdk/models/data-models#getlinkrequest)
* Returns: [GetLinkResponse](/api-reference/sdk/models/data-models#getlinkresponse)
* React Hook: `useGetLink()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getlink)
#### copyLink()
Copy a link to a specific comment annotation to clipboard.
* Params: [CopyLinkRequest](/api-reference/sdk/models/data-models#copylinkrequest)
* Returns: [CopyLinkEvent](/api-reference/sdk/models/data-models#copylinkevent)
* React Hook: `useCopyLink()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#copylink)
### Navigation
#### scrollToCommentByAnnotationId()
Scroll the page to a comment's location.
* Params: `annotationId: string`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#scrolltocommentbyannotationid)
#### selectCommentByAnnotationId()
Programmatically select a comment annotation. When called without arguments or with an invalid ID, it will close the currently selected annotation.
* Params: `annotationId?: string` (optional)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#selectcommentbyannotationid)
#### onCommentSelectionChange()
Subscribe to comment selection changes.
* Params: none
* Returns: `Observable`
* React Hook: `useCommentSelectionChangeHandler()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#oncommentselectionchange)
#### enablescrollToComment()
Enable automatic scrolling to comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablescrolltocomment)
### DOM Controls
#### allowedElementIds()
Set allowed element IDs for commenting.
* Params: `elementIds: string[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#allowedelementids)
#### allowedElementClassNames()
Set allowed element class names for commenting.
* Params: `classNames: string[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#allowedelementclassnames)
#### allowedElementQuerySelectors()
Set allowed element query selectors for commenting.
* Params: `selectors: string[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#allowedelementqueryselectors)
#### setContextInPageModeComposer()
Set context data and optional target element for page mode composer.
* Params: [`PageModeComposerConfig`](/api-reference/sdk/models/data-models#pagemodecomposerconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcontextinpagemodecomposer)
#### focusPageModeComposer()
Focus the page mode composer input field.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#focuspagemodecomposer)
### AI Categorization
#### enableAutoCategorize()
Enable AI auto-categorization of comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableautocategorize)
#### setCustomCategory()
Set custom categories for comment categorization.
* Params: `categories: Array<{id: string, name: string, color: string}>`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcustomcategory)
### UI
#### updateCommentDialogPosition()
Update position of comment dialog relative to pin.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecommentdialogposition)
#### enableSidebarButtonOnCommentDialog()
Enable sidebar button on comment dialogs.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablesidebarbuttononcommentdialog)
#### onSidebarButtonOnCommentDialogClick()
Subscribe to clicks on comment dialog sidebar button.
* Params: none
* Returns: `Observable`
* React Hook: `useCommentDialogSidebarClickHandler()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#onsidebarbuttononcommentdialogclick)
#### enableDeleteReplyConfirmation()
Enable confirmation dialog before deleting replies.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enabledeletereplyconfirmation)
#### enableMobileMode()
Enable mobile-optimized comment UI.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablemobilemode)
#### enableCommentPinHighlighter()
Enable highlighting outline around comment pins.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecommentpinhighlighter)
#### showCommentsOnDom()
Show comments on the DOM.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#showCommentsOnDom)
#### enableDialogOnHover()
Enable showing comment dialog on hover.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enabledialogonhover)
#### enableFloatingCommentDialog()
Enable floating comment dialog next to pins.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablefloatingcommentdialog)
#### showResolvedCommentsOnDom()
Show resolved comments on the DOM.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#showresolvedcommentsondom)
#### enableCollapsedComments()
Enable collapsing of comments in annotations.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecollapsedcomments)
#### enableShortUserName()
Enable shortening of long user names.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableshortusername)
#### enableSignInButton()
Enable sign in button on comment dialog when user is anonymous or signed out.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablesigninbutton)
#### onSignIn()
Handle sign in button click event.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#onsignin)
### Comment Dialog Primitives
79 primitive components for building custom comment interfaces. See [Data Models](/api-reference/sdk/models/data-models#comment-dialog-primitives) for type definitions.
#### VeltCommentDialogContextWrapper
Context wrapper that provides shared annotation context to child primitives.
* Params: [`CommentDialogContextWrapperProps`](/api-reference/sdk/models/data-models#commentdialogcontextwrapperprops)
* Returns: `N/A`
* React Hook: `n/a`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcontextwrapper)
#### VeltCommentDialogHeader
Header component for the comment dialog.
* Params: [`CommentDialogCommonProps`](/api-reference/sdk/models/data-models#commentdialogcommonprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogheader)
#### VeltCommentDialogBody
Body container for the comment dialog thread content.
* Params: [`CommentDialogCommonProps`](/api-reference/sdk/models/data-models#commentdialogcommonprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogbody)
#### VeltCommentDialogThreadCard
Complete thread card with comment metadata and content.
* Params: [`ThreadCardProps`](/api-reference/sdk/models/data-models#threadcardprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogthreadcard)
#### VeltCommentDialogThreadCardAvatar
User avatar for the comment author.
* Params: [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogthreadcardavatar)
#### VeltCommentDialogComposer
Complete composer with input, attachments, and action buttons.
* Params: [`ComposerProps`](/api-reference/sdk/models/data-models#composerprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcomposer)
#### VeltCommentDialogComposerInput
Text input field for composing comments.
* Params: [`ComposerInputProps`](/api-reference/sdk/models/data-models#composerinputprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcomposerinput)
#### VeltCommentDialogStatusDropdownContentItem
Individual status item in the dropdown.
* Params: [`StatusDropdownItemProps`](/api-reference/sdk/models/data-models#statusdropdownitemprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogstatusdropdowncontentitem)
#### VeltCommentDialogPriorityDropdownContentItem
Individual priority item in the dropdown.
* Params: [`PriorityDropdownItemProps`](/api-reference/sdk/models/data-models#prioritydropdownitemprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogprioritydropdowncontentitem)
#### VeltCommentDialogOptionsDropdown
Options menu for actions like assignment, editing, and notifications.
* Params: [`OptionsDropdownProps`](/api-reference/sdk/models/data-models#optionsdropdownprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogoptionsdropdown)
#### VeltCommentDialogCustomAnnotationDropdownTriggerListItem
Individual item in the custom annotation dropdown trigger list.
* Params: [`CustomAnnotationItemProps`](/api-reference/sdk/models/data-models#customannotationitemprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcustomannotationdropdowntriggerlistitem)
#### VeltCommentDialogCustomAnnotationDropdownContentItem
Individual item in the custom annotation dropdown content.
* Params: [`CustomAnnotationItemProps`](/api-reference/sdk/models/data-models#customannotationitemprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcustomannotationdropdowncontentitem)
#### VeltCommentDialogReplyAvatarsListItem
Individual avatar item in the reply avatars list.
* Params: [`ReplyAvatarsListItemProps`](/api-reference/sdk/models/data-models#replyavatarslistitemprops)
* Returns: `N/A`
* [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogreplyavatarslistitem)
### Extra Information
#### enableCommentIndex()
Enable comment index indicators on pins and sidebar.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecommentindex)
#### enableDeviceInfo()
Enable device type indicators in comment threads.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enabledeviceinfo)
#### enableDeviceIndicatorOnCommentPins()
Enable device type indicators on comment pins.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enabledeviceindicatoroncommentpins)
#### enableGhostComments()
Enable showing ghost comments on the DOM.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableghostcomments)
#### enableGhostCommentsIndicator()
Enable ghost comment labels in the sidebar.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableghostcommentsindicator)
### Special File Type Support
#### enableSvgAsImg()
Treat SVGs as flat images instead of layered elements.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#svgAsImg)
### Keyboard Controls
#### enableHotkey()
Enable hotkeys for comments (e.g. 'c' to enable comment mode).
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablehotkey)
#### enableEnterKeyToSubmit()
Enable using Enter key to submit comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableentertosubmit)
#### enableDeleteOnBackspace()
Enable deleting comments with backspace key.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enabledeleteonbackspace)
### Moderation
#### enableModeratorMode()
Enable moderator mode for comments requiring approval.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablemoderatormode)
#### enableResolveStatusAccessAdminOnly()
Restrict resolve action to admin users and comment authors.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableresolvestatusaccessadminonly)
#### approveCommentAnnotation()
Approve a comment annotation in moderator mode.
* Params: `ApproveCommentAnnotationRequest`
* Returns: `Promise`
* React Hook: `useApproveCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#approvecommentannotation)
#### acceptCommentAnnotation()
Accept a comment annotation in suggestion mode.
* Params: `AcceptCommentAnnotationRequest`
* Returns: `Promise`
* React Hook: `useAcceptCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#acceptcommentannotation)
#### rejectCommentAnnotation()
Reject a comment annotation in suggestion mode.
* Params: `RejectCommentAnnotationRequest`
* Returns: `Promise`
* React Hook: `useRejectCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#rejectcommentannotation)
#### enableSuggestionMode()
Enable suggestion mode for accepting/rejecting comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablesuggestionmode)
### Comment Read Status
#### enableSeenByUsers()
Enable "Seen By" feature to show which users have seen each comment.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableseenbyusers)
#### setUnreadIndicatorMode()
Set unread indicator mode to either minimal (dot) or verbose (badge).
* Params: `mode: "minimal" | "verbose"`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setunreadindicatormode)
### Toggle Comment Types
#### enableAreaComment()
Enable area comments that allow drawing rectangles with comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableareacomment)
#### enableInboxMode()
Enable inbox mode for comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableinboxmode)
#### enablePopoverMode()
Enable popover mode for comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablepopovermode)
#### enableStreamMode()
Enable stream mode for comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablestreammode)
#### enableTextMode()
Enable text mode for comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enabletextmode)
#### enableInlineCommentMode()
Enable inline comment mode to show comments under associated text.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableinlinecommentmode)
#### enableMultithread()
Enable multithreaded comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablemultithread)
### Comment Bubble
#### enableGroupMatchedComments()
Enable grouping of multiple comment annotations in Comment Bubble component when multiple annotations match the provided `context` or `targetElementId`.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#groupMatchedComments)
### Comment Tool
#### enableCommentMode()
Enable comment mode to allow attaching comments to DOM elements.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecommentmode)
#### onCommentModeChange()
Subscribe to changes in comment mode state.
* Params: none
* Returns: `Observable`
* React Hook: `useCommentModeState()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#oncommentmodechange)
#### enableCommentTool()
Enable/disable the comment tool button.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablecommenttool)
#### enableChangeDetectionInCommentMode()
Enable DOM change detection while in comment mode.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablechangedetectionincommentmode)
#### enablePersistentCommentMode()
Enable persistent comment mode to continue leaving comments after finishing one.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablepersistentcommentmode)
#### enableForceCloseAllOnEsc()
Force close persistent comment mode when ESC key is pressed, even if a comment thread is active.
* Params: none
* Returns: `void`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#forcecloseallonesc)
#### disableForceCloseAllOnEsc()
Disable force close behavior for persistent comment mode when ESC key is pressed.
* Params: none
* Returns: `void`
* React Hook: `useCommentUtils()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#forcecloseallonesc)
#### setPinCursorImage()
Set custom cursor image for comment mode.
* Params: `base64ImageString: string`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setpincursorimage)
### Minimap
#### enableMinimap()
Enable minimap showing comment locations on screen edge.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enableminimap)
### Popover Comments
#### enableDialogOnTargetElementClick()
Enable opening comment dialog on target element click in popover mode.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enabledialogontargetelementclick)
#### enablePopoverTriangleComponent()
Enable triangle indicator on popover comments.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablepoovertrianglecomponent)
### Video Timeline Comments
#### setTotalMediaLength()
Set the total length of media (in frames or seconds) for the timeline.
* Params: `length: number`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#settotalmediallength)
### Comment Pin
#### enableBubbleOnPin()
Show a Comment Bubble when hovering/clicking on Comment Pin instead of Comment Dialog.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablebubbleonpin)
#### enableBubbleOnPinHover()
Show Comment Bubble on hover vs click for Comment Pins.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#enablebubbleonpinhover)
# Comments Sidebar
### Custom filtering, sorting and grouping
#### enableSidebarCustomActions()
Enable custom filtering, sorting and grouping actions in the comments sidebar.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#custom-filtering-sorting-and-grouping)
#### setCommentSidebarData()
Set filtered/sorted/grouped data in the comments sidebar.
* Params: `data: CommentSidebarData[], options?: {grouping?: boolean}`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#custom-filtering-sorting-and-grouping)
### Navigation
#### onCommentClick()
Listen for comment click events in the sidebar.
* Params: `(event: {documentId: string, location: Object, targetElementId: string, context: Object, annotation: CommentAnnotation}) => void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#oncommentclick)
#### enableSidebarUrlNavigation()
Enable automatic URL navigation when clicking comments in the sidebar.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#enablesidebarurlnavigation)
### UI
#### openCommentSidebar()
Open the comments sidebar.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#opencommentsidebar)
#### closeCommentSidebar()
Close the comments sidebar.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#openCommentSidebar)
#### toggleCommentSidebar()
Toggle the comments sidebar open/closed state.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#togglecommentsidebar)
#### enableFullScreenInSidebar()
Enable full-screen mode for the Comments Sidebar (only works in default mode).
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#fullscreen)
#### disableFullScreenInSidebar()
Disable full-screen mode for the Comments Sidebar.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#fullscreen)
#### excludeLocationIdsFromSidebar()
Filter out comments from specified locations in the sidebar.
* Params: `locationIds: string[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#excludelocationidsfromsidebar)
### System Filters, Sorting and Grouping
#### setCommentSidebarFilters()
Set filters for the comments sidebar programmatically.
* Params: `filters: {location?: {id: string}[], people?: ({userId: string} | {email: string})[], priority?: string[], status?: string[], category?: string[]}`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments-sidebar/customize-behavior#setcommentsidebarfilters)
# Notifications
### Data
#### getNotificationsData()
Get the notifications data for the current user.
* Params:
* query: Optional. [`GetNotificationsDataQuery`](/api-reference/sdk/models/data-models#getnotificationsdataquery)
* `type`: Filter for notification type: all, for you, or documents.
* `forYou`: returns notifications where the current user is involved.
* `all` / `documents`: returns all notifications from the documents the user has access to.
* Returns: `Observable`
* React Hook: `useNotificationsData()`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#getnotificationsdata)
#### getUnreadNotificationsCount()
Get count of unread notifications by tab.
* Params: none
* Returns: `Observable<{forYou: number, all: number}>`
* React Hook: `useUnreadNotificationsCount()`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#getunreadnotificationscount)
### Event Subscription
#### on()
Subscribe to Notification events.
* Params: `NotificationEventType`. [Here](/api-reference/sdk/models/data-models#notification) is the list of events you can subscribe to.
* Returns: `Observable`. [Here](/api-reference/sdk/models/data-models#notification) is the list of events object types you can expect to receive.
* React Hook: `useNotificationEventCallback(NotificationEventType)`
#### onNotificationClick()
Listen for notification click events in the Notifications Panel.
* Params: `(notification: Notification) => void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#onnotificationclick)
### Configuration
#### setTabConfig()
Customize notification tab names and visibility.
* Params: `tabConfig: TabConfig`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#settabconfig)
#### setMaxDays()
Set maximum age in days for displayed notifications.
* Params: `days: number`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#setmaxdays)
#### enableReadNotificationsOnForYouTab()
Show read notifications in the "For You" tab.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#enablereadnotificationsontheforyoutab)
### Actions
#### setAllNotificationsAsRead()
Mark all notifications as read globally or by tab.
* Params: `options?: {tabId?: string}`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#setallnotificationsasread)
#### markNotificationAsReadById()
Mark a specific notification as read.
* Params: `notificationId: string`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#marknotificationasreadbyid)
### Notification Settings
#### enableSettings()
Enable or disable the settings feature for notifications.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#enablesettings)
#### disableSettings()
Disable the settings feature for notifications.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#enablesettings)
#### enableSettingsAtOrganizationLevel()
Enable organization-level notification settings. Settings apply to all documents in the organization instead of per-document.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#enablesettingsatorganizationlevel)
#### disableSettingsAtOrganizationLevel()
Disable organization-level notification settings. Settings revert to per-document configuration.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#disablesettingsatorganizationlevel)
#### setSettingsInitialConfig()
Set the initial default configuration for notification settings.
* Params: [`NotificationInitialSettingsConfig[]`](/api-reference/sdk/models/data-models#notificationinitialsettingsconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#setsettingsinitialconfig)
#### muteAllNotifications()
Mute all notifications across all channels for the current user.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#muteallnotifications)
#### setSettings()
Update notification settings configuration for the current user.
* Params: [`NotificationSettingsConfig`](/api-reference/sdk/models/data-models#notificationsettingsconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#setsettings)
#### getSettings()
Get the current notification settings configuration for the user.
* Params: none
* Returns: [`Observable`](/api-reference/sdk/models/data-models#notificationsettingsconfig)
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#getsettings)
#### enableCurrentDocumentOnly()
Filters notifications to show only those from the current document.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#enablecurrentdocumentonly)
#### disableCurrentDocumentOnly()
Shows notifications from all documents, not just the current document.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#disablecurrentdocumentonly)
# Activity Logs
### Data
#### getAllActivities()
Subscribe to the real-time activity log feed, optionally filtered by document, feature type, or action type.
* Params: `config?:` [`ActivitySubscribeConfig`](/api-reference/sdk/models/data-models#activitysubscribeconfig)
* Returns: `Observable`
* React Hook: `useAllActivities(config?)`
* [Full Documentation →](/async-collaboration/activity/customize-behavior#getallactivities)
### Actions
#### createActivity()
Create a custom activity log record for non-Velt events.
* Params: `data:` [`CreateActivityData`](/api-reference/sdk/models/data-models#createactivitydata)
* Returns: `Promise`
* React Hook: `useActivityUtils()` (access via `activityElement?.createActivity(data)`)
* [Full Documentation →](/async-collaboration/activity/customize-behavior#createactivity)
### Element Access
#### getActivityElement()
Get the ActivityElement instance from the Velt client.
* Params: none
* Returns: `ActivityElement`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/activity/setup)
### React Hooks
#### useAllActivities()
React Hook to subscribe to the activity log feed with optional filtering.
* Params: `config?:` [`ActivitySubscribeConfig`](/api-reference/sdk/models/data-models#activitysubscribeconfig)
* Returns: [`ActivityRecord[]`](/api-reference/sdk/models/data-models#activityrecord) `| null`
* React Hook: Yes
* [Full Documentation →](/async-collaboration/activity/customize-behavior#getallactivities)
#### useActivityUtils()
React Hook to access ActivityElement utility methods such as `createActivity()`.
* Params: none
* Returns: `ActivityElement | null`
* React Hook: Yes
* [Full Documentation →](/async-collaboration/activity/customize-behavior#createactivity)
# Recorder
#### downloadLatestVideo()
Downloads the latest version of a recording.
* Params: `recorderId: string`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#downloadlatestvideo)
#### enableRecordingCountdown()
Controls whether to display a countdown timer before a recording starts.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#enablerecordingcountdown)
#### enableRecordingTranscription()
Controls whether to enable AI transcription for recordings.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#enablerecordingtranscription)
#### fetchRecordings()
Fetches recording data.
* Params: [RecorderRequestQuery](/api-reference/sdk/models/data-models#recorderrequestquery)
* Returns: [`Promise`](/api-reference/sdk/models/data-models#getrecordingdataresponse)
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#getrecordingdata)
### RecorderElement Methods
#### setMaxLength()
Sets the maximum recording duration in seconds.
* Params: `value: number`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#setmaxlength)
#### enablePictureInPicture()
Enables Picture-in-Picture mode for recordings.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#enablepictureinpicture)
#### disablePictureInPicture()
Disables Picture-in-Picture mode for recordings.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#disablepictureinpicture)
#### openPictureInPicture()
Opens the Picture-in-Picture window for the current recording.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#openpictureinpicture)
#### exitPictureInPicture()
Exits the Picture-in-Picture window.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#exitpictureinpicture)
#### requestScreenPermission()
Requests screen capture permissions for recording preview.
* Params: none
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#requestscreenpermission)
#### enablePlaybackOnPreviewClick()
Enables click-to-play/pause functionality on recording preview thumbnails.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#playbackonpreviewclick)
#### disablePlaybackOnPreviewClick()
Disables click-to-play/pause functionality on recording preview thumbnails.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#playbackonpreviewclick)
### Event Subscription
#### on()
Subscribe to Recorder events.
* Params: `RecorderEventType`. [Here](/api-reference/sdk/models/data-models#recorder) is the list of events you can subscribe to.
* Returns: `Observable`. [Here](/api-reference/sdk/models/data-models#recorder) is the list of events object types you can expect to receive.
* React Hook: `useRecorderEventCallback(RecorderEventType)`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#on)
# Inline Reactions
#### setCustomReactions()
Set custom reaction emojis for inline reactions.
* Params: `customReactions: { [reactionId: string]: { url?: string, emoji?: string } }`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/reactions/customize-behavior#setcustomreactions)
# View Analytics
#### getUniqueViewsByUser()
Get unique views by user, optionally filtered by location.
* Params: `locationId?: string`
* Returns: `Observable`
* React Hook: `useUniqueViewsByUser()`
* [Full Documentation →](/async-collaboration/view-analytics/customize-behavior#getuniqueviewsbyuser)
#### getUniqueViewsByDate()
Get unique views by date, optionally filtered by location.
* Params: `locationId?: string`
* Returns: `Observable`
* React Hook: `useUniqueViewsByDate()`
* [Full Documentation →](/async-collaboration/view-analytics/customize-behavior#getuniqueviewsbydate)
# Live State Sync
#### getLiveStateData()
Retrieves live state data as an observable based on the provided ID.
* Params: `liveStateDataId?: string`
* Returns: `Observable`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup)
#### setLiveStateData()
Sets live state data for the provided ID and data.
* Params:
* `liveStateDataId`: `string`
* `liveStateData`: `any`
* `config`: `SetLiveStateDataConfig`
* Returns: `any`
* React Hook: `useSetLiveStateData()`
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup)
#### fetchLiveStateData()
Fetches live state data as a Promise. Use this when you need to retrieve the current state once, rather than subscribing to ongoing changes.
* Params: `request?:` [FetchLiveStateDataRequest](/api-reference/sdk/models/data-models#fetchlivestatedatarequest) - Optional. If not provided or if liveStateDataId is not specified, all live state data will be returned.
* Returns: `Promise` - Generic type support allows you to specify the expected data type
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup#fetch-live-data)
# Single Editor Mode
#### enableSingleEditorMode()
Enables the single editor mode with an optional configuration.
* Params: `config?: SingleEditorConfig`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### disableSingleEditorMode()
Disables the single editor mode.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### isUserEditor()
Checks if the current user is an editor. Returns an observable.
* Params: none
* Returns: `Observable`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### getEditor()
Retrieves the current editor information.
* Params: none
* Returns: `Observable`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### setUserAsEditor()
Sets the current user as an editor.
* Params: none
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/customize-behavior#setuseraseditor)
Possible error codes returned in `SetUserAsEditorResponse.error`:
* `same_user_editor_current_tab`
* `same_user_editor_different_tab`
* `another_user_editor`
See types: [SetUserAsEditorResponse](/api-reference/sdk/models/data-models#setuseraseditorresponse), [ErrorEvent](/api-reference/sdk/models/data-models#errorevent)
#### resetUserAccess()
Resets the user access.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### singleEditorModeContainerIds()
Disables elements inside specific elements only when single editor mode is on.
* Params: `elementIds: string[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### enableAutoSyncState()
Enables the autosync state feature.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### requestEditorAccess()
Initiates a request for editor access.
* Params: none
* Returns: `Observable`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### isEditorAccessRequested()
Checks if editor access has been requested.
* Params: none
* Returns: `Observable<{ requestStatus: string, requestedBy: User } | null>`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### acceptEditorAccessRequest()
Accepts an editor access request.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### rejectEditorAccessRequest()
Rejects an editor access request.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### cancelEditorAccessRequest()
Cancels an editor access request.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### editCurrentTab()
Edits the current tab.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### setEditorAccessTimeout()
Sets a timeout for editor access. (in milliseconds)
* Params: `timeout: number`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### enableEditorAccessTransferOnTimeOut()
Enables the transfer of editor access on timeout.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### enableDefaultSingleEditorUI()
Enables the default UI for single editor mode.
* Params: none
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### enableHeartbeat()
Enables the heartbeat mechanism for Single Editor Mode presence detection. This feature is enabled by default when single editor mode is enabled.
* Params: `void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/customize-behavior#heartbeat)
#### disableHeartbeat()
Disables the heartbeat mechanism for Single Editor Mode presence detection. Must be called before enabling single editor mode if you don't want to use the heartbeat functionality.
* Params: `void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/customize-behavior#heartbeat)
# Cursors
#### setInactivityTime()
Set the time it takes for a user's cursor to be marked as inactive.
* Params: `milliseconds: number`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/cursors/customize-behavior#setinactivitytime)
#### allowedElementIds()
Set specific element IDs where cursors should be shown.
* Params: `elementIds: string[]`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/cursors/customize-behavior#allowedelementids)
#### onCursorUserChange()
Subscribe to cursor position changes for all users.
* Params: `callback: (cursorUsers: CursorUser[]) => void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/cursors/customize-behavior#oncursoruserchange)
# Presence
#### updateUserPresence()
Send a lightweight heartbeat from your host app to Velt. Velt will use that as a fallback in rare edge cases if it fails to detect multi‑tab/device presence. Most apps don’t need this; use only if you see ambiguity in who’s the active editor.
* Params: `userPresence: LiveStateSingleEditorExternalUserPresence`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/single-editor-mode/customize-behavior#updateuserpresence)
See types: [LiveStateSingleEditorExternalUserPresence](/api-reference/sdk/models/data-models#livestatesingleeditorexternaluserpresence)
Set the time it takes for a user to be marked as inactive.
* Params: `milliseconds: number`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#setinactivitytime)
#### enableSelf()
Include the current user in the list of presence users.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#self)
#### on()
Subscribe to Presence events.
* Params: `PresenceEventType`. [Here](/api-reference/sdk/models/data-models#presence) is the list of events you can subscribe to.
* Returns: `Observable`. [Here](/api-reference/sdk/models/data-models#presence) is the list of events object types you can expect to receive.
* React Hook: `usePresenceEventCallback(PresenceEventType)`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#on)
#### onPresenceUserChange()
Subscribe to presence changes for all users.
* Params: `callback: (presenceUsers: PresenceUser[]) => void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#onpresenceuserchange)
#### onPresenceUserClick()
Handle click events on presence avatar circles.
* Params: `callback: (user: User) => void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#onpresenceuserclick)
#### getData()
Subscribe to presence data.
* Params: `PresenceRequestQuery`
* Returns: `Observable`
* React Hook: `usePresenceData()`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#getdata)
# Follow Mode
#### enableFlockMode()
Enable Follow Me mode globally wherever Presence is shown.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#flockmode)
#### startFollowingUser()
Start following a specific user.
* Params: `userId: string`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/flock-mode/customize-behavior#startfollowinguser)
#### stopFollowingUser()
Stop following the current user.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/flock-mode/customize-behavior#stopfollowinguser)
#### onNavigate()
Handle navigation events during Follow Me sessions.
* Params: `callback: (pageInfo: PageInfo) => void`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/flock-mode/customize-behavior#onnavigate)
# Huddle
#### enableChat()
Enable the ephemeral chat feature in Huddle.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/huddle/customize-behavior#chat)
#### enableFlockModeOnAvatarClick()
Enable Follow Me mode when clicking on a user's avatar in Huddle.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/huddle/customize-behavior#flockmodedonavatarclick)
# Live Selection
#### enableDefaultElementsTracking()
Enable automatic tracking of user presence on default element types (input, textarea, button, contenteditable).
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#enabledefaultelementstracking)
#### enableUserIndicator()
Enable the user indicator (avatar/name label) that appears near selected elements.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#enableuserindicator)
#### setUserIndicatorPosition()
Set the position of the user indicator globally.
* Params: `position: 'start' | 'end'`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#setuserindicatorposition)
#### setUserIndicatorType()
Set the type of user indicator globally.
* Params: `type: 'avatar' | 'label'`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#setuserindicatortype)
#### getLiveSelectionData()
Get the live selection data for the current document.
* Params: `none`
* Returns: `Observable`
* React Hook: `useLiveSelectionDataHandler()`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#getliveselectiondata)
#### setInactivityTime()
Set inactivity duration before hiding inactive selections.
* Params: `milliseconds: number`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#setinactivitytime)
# AI
#### enableRewriter()
Enable the rewriter.
* **Signature**: `enableRewriter()`
* **Params**: `n/a`
* **Returns**: `void`
* **React Hook**: `n/a`
# ReactFlow
#### [useVeltReactFlowCrdtExtension()](/api-reference/sdk/api/api-methods#useveltreactflowcrdtextension)
Provides real-time collaborative ReactFlow editor functionality with Yjs and Velt SDK synchronization.
* Signature: useVeltReactFlowCrdtExtension(config: VeltReactFlowCrdtExtensionConfig)
* Params: [VeltReactFlowCrdtExtensionConfig](/api-reference/sdk/models/data-models#veltreactflowcrdtextensionconfig)
* Returns: [VeltReactFlowCrdtExtensionResponse](/api-reference/sdk/models/data-models#veltreactflowcrdtextensionresponse)
* React Hook: `useVeltReactFlowCrdtExtension()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/reactflow#useveltreactflowcrdtextension)
#### veltReactFlowStore
Create and initialize a collaborative React Flow Zustand store.
* Params: [VeltReactFlowStoreConfig](/api-reference/sdk/models/data-models#veltreactflowstoreconfig)
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/reactflow#apis)
#### onNodesChange
CRDT-aware handler to apply node changes (add/update/remove) that sync across collaborators.
* Params: [NodeChange\[\]](/api-reference/sdk/models/data-models#nodechange)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/reactflow#apis)
#### onEdgesChange
CRDT-aware handler to apply edge changes (add/update/remove) that sync across collaborators.
* Params: [EdgeChange\[\]](/api-reference/sdk/models/data-models#edgechange)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/reactflow#apis)
#### onConnect
CRDT-aware connect handler compatible with React Flow’s `onConnect` prop.
* Params: [Connection](/api-reference/sdk/models/data-models#connection)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/reactflow#apis)
#### setNodes
Imperative setter for nodes (useful for non-event updates). Synced via the store.
* Params: [Node\[\]](/api-reference/sdk/models/data-models#node-react-flow) | ((prev: [Node\[\]](/api-reference/sdk/models/data-models#node-react-flow)) => [Node\[\]](/api-reference/sdk/models/data-models#node-react-flow))
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/reactflow#apis)
#### setEdges
Imperative setter for edges (useful for non-event updates). Synced via the store.
* Params: [Edge\[\]](/api-reference/sdk/models/data-models#edge-react-flow) | ((prev: [Edge\[\]](/api-reference/sdk/models/data-models#edge-react-flow)) => [Edge\[\]](/api-reference/sdk/models/data-models#edge-react-flow))
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/reactflow#apis)
# Encryption
#### setEncryptionProvider(encryptionProvider)
Register a custom encrypt/decrypt provider used by CRDT features.
* Params: `VeltEncryptionProvider`
* Returns: `void`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#encryption)
# CodeMirror
#### [useVeltCodeMirrorCrdtExtension()](/api-reference/sdk/api/api-methods#useveltcodemirrorcrdtextension)
Provides real-time collaborative CodeMirror editor functionality with Yjs and Velt SDK synchronization.
* Signature: useVeltCodeMirrorCrdtExtension(config: VeltCodeMirrorCrdtExtensionConfig)
* Params: [VeltCodeMirrorCrdtExtensionConfig](/api-reference/sdk/models/data-models#veltcodemirrorcrdtextensionconfig)
* Returns: Extension | null
* React Hook: `useVeltCodeMirrorCrdtExtension()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#useveltcodemirrorcrdtextension)
#### createVeltCodeMirrorStore
Create and initialize a collaborative CodeMirror store instance.
* Params: `VeltCodeMirrorStoreConfig`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#createveltcodemirrorstore)
#### getStore()
Get the underlying Store that manages state and synchronization.
* Params: `none`
* Returns: `Store`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#getstore)
#### getYDoc()
Access the Yjs document used for collaborative editing.
* Params: `none`
* Returns: `Y.Doc`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#getydoc)
#### getYText()
Get the shared Y.Text bound to the current CodeMirror document.
* Params: `none`
* Returns: `Y.Text | null`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#getytext)
#### getAwareness()
Access the Yjs Awareness instance associated with the store.
* Params: `none`
* Returns: `Awareness`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#getawareness)
#### getUndoManager()
Access the Yjs UndoManager for collaborative undo/redo.
* Params: `none`
* Returns: `Y.UndoManager`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#getundomanager)
#### destroy()
Clean up listeners and release resources.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/codemirror#destroy)
# BlockNote
#### useVeltBlockNoteCrdtExtension()
Provides real-time collaborative BlockNote editor functionality with Yjs and Velt SDK synchronization.
* Signature: useVeltBlockNoteCrdtExtension(config: VeltBlockNoteCrdtExtensionConfig)
* Params: [VeltBlockNoteCrdtExtensionConfig](/api-reference/sdk/models/data-models#veltblocknotecrdtextensionconfig)
* Returns: [VeltCodeMirrorCrdtExtensionResponse](/api-reference/sdk/models/data-models#veltcodemirrorcrdtextensionresponse)
* React Hook: `useVeltBlockNoteCrdtExtension()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/blocknote#useveltblocknotecrdtextension)
#### createVeltBlockNoteStore()
Create and initialize a collaborative BlockNote store instance.
* Params: `VeltBlockNoteStoreConfig`
* Returns: `VeltBlockNoteStore | null`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/blocknote#createveltblocknotestore)
#### initialize()
Start syncing the collaborative document (usually auto-called by the factory).
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/blocknote#initialize)
#### destroy()
Tear down the store and clean listeners/resources.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/blocknote#destroy)
#### getStore()
Access the underlying CRDT store (yjs doc + provider).
* Params: `none`
* Returns: `Store`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/blocknote#getstore)
#### getYDoc()
Accessor for the underlying Yjs document.
* Params: `none`
* Returns: `Y.Doc`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/blocknote#getydoc)
#### getYXml()
Get the Y.XmlFragment representing the BlockNote document tree.
* Params: `none`
* Returns: `Y.XmlFragment | null`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/blocknote#getyxml)
# Tiptap
#### [useVeltTiptapCrdtExtension()](/api-reference/sdk/api/api-methods#usevelttiptapcrdtextension)
Provides real-time collaborative Tiptap editor functionality with Yjs and Velt SDK synchronization.
* Signature: useVeltTiptapCrdtExtension(config: VeltTiptapCrdtExtensionConfig)
* Params: [VeltTiptapCrdtExtensionConfig](/api-reference/sdk/models/data-models#velttiptapcrdtextensionconfig)
* Returns: [VeltTiptapCrdtExtensionResponse](/api-reference/sdk/models/data-models#velttiptapcrdtextensionresponse)
* React Hook: `useVeltTiptapCrdtExtension()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#usevelttiptapcrdtextension)
#### createVeltTipTapStore()
Create and initialize a collaborative Tiptap store instance.
* Params: `config`
* Returns: `VeltTipTapStore | null`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#apis)
#### initialize()
Initialize the store and start syncing the collaborative document.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#initialize)
#### getCollabExtension()
Get the Tiptap collaboration extension bound to the current Yjs document.
* Params: `none`
* Returns: `Extension`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#getcollabextension)
#### destroy()
Tear down the store and clean up listeners/resources.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#destroy)
#### getStore()
Access the underlying CRDT store managing document state.
* Params: `none`
* Returns: `Store`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#getstore)
#### getYDoc()
Accessor for the underlying Yjs document.
* Params: `none`
* Returns: `Y.Doc`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#apis)
#### getYXml()
Accessor for the XML fragment in the Yjs document.
* Params: `none`
* Returns: `Y.XmlFragment | null`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/tiptap#apis)
# Core
### Client
#### initConfig()
Set up initial configurations for the Velt SDK.
* Params: `apiKey: string, config?:` [`Config`](/api-reference/sdk/models/data-models#config)
* Returns: `void`
* React Hook: `n/a`
#### getVeltInitState()
Subscribe to detect whether Velt is initialized.
* Params: `void`
* Returns: `Observable`
* React Hook: `useVeltInitState()`
* [Full Documentation →](/key-concepts/client#getveltinitstate)
#### get Velt Client
Access the core Velt client instance to call SDK APIs and subscribe to core events.
* Signature:
* React: `const { client } = useVeltClient()`
* Other frameworks: `const client = await initVelt(apiKey)`
* HTML: `await Velt.init(apiKey)` then use `Velt`
* Params: `none` [Here](/get-started/advanced#client-event-subscriptions) is the list of events you can subscribe to.
* Returns: `Velt` [Here](/api-reference/sdk/models/data-models#client-events) is the list of events object types you can expect to receive.
* React Hook: `useVeltClient()`
* See event payloads: [Core data model](/api-reference/sdk/models/data-models##core-events)
* Overview: [Client Event Subscriptions](/get-started/advanced#client-event-subscriptions)
#### getMetadata()
Get the currently set organization, document and location objects.
* Params: none
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/client#getmetadata)
#### getUserPermissions()
Get the current user's access roles across organization, folder, and document scopes.
* Params: [GetUserPermissionsRequest](/api-reference/sdk/models/data-models#getuserpermissionsrequest)
* Returns: [`Promise`](/api-reference/sdk/models/data-models#getuserpermissionsresponse)
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/overview#configuration-modes)
**Error handling:** On failure, the response includes an `errorCode` from the [UserPermissionAccessRoleResult](/api-reference/sdk/models/data-models#userpermissionaccessroleresult) enum:
* `does_not_exist`: Resource not found
* `permission_denied`: User lacks access to the resource
* `something_went_wrong`: Unexpected error
#### getCurrentUserPermissions()
Subscribe to current user permissions updates. Returns real-time permission changes for the authenticated user across organization, folder, and document scopes. Useful for debugging and developer tools integration.
* Params: `void`
* Returns: [`Observable`](/api-reference/sdk/models/data-models#getuserpermissionsresponse)
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/overview#getcurrentuserpermissions)
#### getHeartbeat()
Subscribe to user-specific heartbeat data. Retrieve heartbeat data for the current user or specify a userId to monitor heartbeats for any user.
* Params: [`HeartbeatConfig`](/api-reference/sdk/models/data-models#heartbeatconfig) (optional)
* Returns: [`Observable`](/api-reference/sdk/models/data-models#getheartbeatresponse)
* React Hook: `useHeartbeat()`
* [Full Documentation →](/key-concepts/client#getheartbeat)
### Authentication
#### identify()
Authenticate the client's user with the Velt SDK. When called with organization change, previous document is set unless `setDocuments()` is explicitly called.
* Params: `user: User, userOptions?: UserOptions`
* Returns: `Promise`
* React Hook: `useIdentify()`
#### setPermissionProvider()
Configure Permission Provider for real-time access validation.
* Params: [`VeltPermissionProvider`](/api-reference/sdk/models/data-models#veltpermissionprovider)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/overview#c-real-time-permission-provider)
#### signOutUser()
To sign out a user.
* Params: `void`
* Returns: `any`
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/client#client-events)
#### getUser()
Get the current authenticated user in Velt.
* Params: `void`
* Returns: `User`
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/client#client-events)
#### getCurrentUser()
Subscribe to changes in the current user object.
* Params: `void`
* Returns: `Observable`
* React Hook: `useCurrentUser()`
* [Full Documentation →](/key-concepts/overview#get-current-user)
### Collaboration
#### createVeltStore()
Create and initialize a collaborative CRDT store instance.
* Params: `StoreConfig`
* Returns: `Promise | null>`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#apis)
#### getDoc()
Get the underlying Yjs document.
* Params: `none`
* Returns: `Y.Doc`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#apis)
#### getProvider()
Get the provider instance for the store.
* Params: `none`
* Returns: `Provider`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#apis)
#### getText()
Get the Y.Text instance if store type is 'text'.
* Params: `none`
* Returns: `Y.Text | null`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#apis)
#### getXml()
Get the Y.XmlFragment instance if store type is 'xml'.
* Params: `none`
* Returns: `Y.XmlFragment | null`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#apis)
#### useVeltCrdtStore()
React Hook to create and sync a CRDT store.
* Params: `VeltCrdtStoreConfig`
* Returns: `Store`
* React Hook: `Yes`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#apis)
#### update()
Update the store value.
* Params: `newValue: T`
* Returns: `void`
* React Hook: `update()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#update)
#### saveVersion()
Save the current state as a named version.
* Params: `versionName: string`
* Returns: `Promise`
* React Hook: `saveVersion()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#saveversion)
#### getVersions()
Retrieve all saved versions.
* Params: `none`
* Returns: `Promise`
* React Hook: `getVersions()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#getversions)
#### getVersionById()
Fetch a specific version by ID.
* Params: `versionId: string`
* Returns: `Promise`
* React Hook: `getVersionById()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#getversionbyid)
#### setStateFromVersion()
Restore the state from a given version.
* Params: `version: Version`
* Returns: `Promise`
* React Hook: `setStateFromVersion()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#setstatefromversion)
#### destroy()
Destroy the store, cleaning up resources and listeners.
* Params: `none`
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#destroy)
#### subscribe()
Subscribe to store updates.
* Params: `(newValue: T) => void`
* Returns: `() => void` (unsubscribe)
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#subscribe)
#### getValue()
Get the current store value.
* Params: `none`
* Returns: `T`
* React Hook: `value`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#getvalue)
#### value
Current value of the store.
* Params: `none`
* Returns: `T | null`
* React Hook: `value`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#value)
#### versions
List of all stored versions.
* Params: `none`
* Returns: `Version[]`
* React Hook: `versions`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#versions)
#### store
Underlying Velt Store instance.
* Params: `none`
* Returns: `Store | null`
* React Hook: `store`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#store)
#### restoreVersion()
Restore the store to a specific version by ID.
* Params: `versionId: string`
* Returns: `Promise`
* React Hook: `restoreVersion()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#restoreversion)
#### enableWebhook()
Enable webhook notifications for CRDT data changes.
* Params: `none`
* Returns: `void`
* React Hook: `crdtUtils.enableWebhook()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#step-7-configure-webhooks-optional)
#### disableWebhook()
Disable webhook notifications for CRDT data changes.
* Params: `none`
* Returns: `void`
* React Hook: `crdtUtils.disableWebhook()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#step-7-configure-webhooks-optional)
#### setWebhookDebounceTime()
Configure webhook debounce interval (minimum 5000ms).
* Params: `debounceTime: number`
* Returns: `void`
* React Hook: `crdtUtils.setWebhookDebounceTime()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#step-7-configure-webhooks-optional)
#### setActivityDebounceTime()
Set how long CRDT editor keystrokes are batched before a single activity log record is flushed. Default: 10 minutes. Minimum: 10 seconds (10,000 ms).
* Params: `time: number` (milliseconds)
* Returns: `void`
* React Hook: `crdtUtils.setActivityDebounceTime()`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#activity-log-debounce)
#### getCrdtElement()
Get the CRDT element instance from the client.
* Params: `none`
* Returns: `CrdtElement`
* React Hook: `n/a`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#step-7-configure-webhooks-optional)
#### useCrdtUtils()
React Hook to access CRDT utility methods.
* Params: `none`
* Returns: `CrdtUtils`
* React Hook: `Yes`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#step-7-configure-webhooks-optional)
#### useCrdtEventCallback()
React Hook to subscribe to CRDT events.
* Params: `eventName: 'updateData'`
* Returns: [`CrdtUpdateDataEvent`](/api-reference/sdk/models/data-models#crdtupdatedataevent) `| null`
* React Hook: `Yes`
* [Full Documentation →](/realtime-collaboration/crdt/setup/core#step-7-configure-webhooks-optional)
### Debug Info
#### fetchDebugInfo()
Retrieve debug information about the current Velt SDK state as a one-time fetch. Returns a Promise that resolves with comprehensive debug data including SDK version, API key, and server/client state metadata.
* Params: `none`
* Returns: [`Promise`](/api-reference/sdk/models/data-models#veltdebuginfo)
* React Hook: `n/a`
* [Full Documentation →](/get-started/advanced#debug-info)
#### getDebugInfo()
Subscribe to debug information updates about the current Velt SDK state. Returns an Observable that emits debug data whenever the SDK state changes.
* Params: `none`
* Returns: [`Observable`](/api-reference/sdk/models/data-models#veltdebuginfo)
* React Hook: `n/a`
* [Full Documentation →](/get-started/advanced#debug-info)
### Folders
#### fetchFolders()
Fetch folder metadata and subfolders by organizationId, folderId with pagination.
* Params: `fetchFoldersRequest: FetchFoldersRequest`
* Returns: `Observable`
* React Hook: `n/a`
* [Full Documentation →](/api-reference/sdk/api/api-methods#client)
### Documents
#### setDocuments()
Initialize and subscribe to multiple Documents at once.
* Params:
* `documents`: [Document\[\]](/api-reference/sdk/models/data-models#document)
* `options?`: [SetDocumentsRequestOptions](/api-reference/sdk/models/data-models#setdocumentsrequestoptions)
* Returns: `Promise`
* React Hook: `useSetDocuments()`
* [Full Documentation →](/key-concepts/overview#set-multiple-documents)
**Behavior Update:** This method now filters out documents the user doesn't have access to instead of failing the entire operation. When using the `allDocuments` flag with a folder, only the first 50 documents are retrieved, and any inaccessible documents are automatically filtered out.
#### setDocument()
Initialize and subscribe to a single Document.
* Params:
* `documentId`: string
* `metadata?`: [DocumentMetadata](/api-reference/sdk/models/data-models#documentmetadata)
* Returns: `Promise`
* React Hook: `useSetDocument()`
* [Full Documentation →](/key-concepts/overview#set-a-single-document)
#### setRootDocument()
Set a different document as the root document when multiple documents are active.
* Params: `document:` [Document](/api-reference/sdk/models/data-models#document)
* Returns: `Promise`
* React Hook: `n/a`
#### unsetDocuments()
Use this to unsubscribe from all documents at once.
* Params: `void`
* Returns: `void`
* React Hook: `useUnsetDocuments()`
* [Full Documentation →](/key-concepts/overview#unset-multiple-documents)
#### fetchDocuments()
Fetch document metadata by `organizationId`, `folderId`, or specific `documentIds`. Supports pagination.
* Params: [FetchDocumentsRequest](/api-reference/sdk/models/data-models#fetchdocumentsrequest)
* Returns: [`Promise`](/api-reference/sdk/models/data-models#fetchdocumentsresponse)
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/overview#fetch-documents)
#### updateDocuments()
Update document metadata by organizationId, folderId or documentIds.
* Params: `UpdateDocumentsRequest`
* Returns: `Promise`
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/overview#update-document-metadata)
### Location
#### setLocation()
Set the current location context. Used to define specific areas within a document.
* Params: `location: Location, isAdditional?: boolean`
* `location`: Location object with:
* `id`: Required unique identifier
* `locationName?`: Optional display name for UI components
* `version?`: Optional version object with:
* `id`: Version identifier
* `name`: Version display name
* Additional custom key/value pairs
* `isAdditional?`: Boolean to add additional locations
* `false` (default): Set this as the root location
* `true`: Add as additional location
* Returns: `Promise`
* React Hook: `useSetLocation()`
* [Full Documentation →](/key-concepts/overview#set-location)
#### setLocations()
Initialize and/or append multiple locations at once.
* Params:
* `locations`: [Location\[\]](/api-reference/sdk/models/data-models#location)
* `options?`: [SetLocationsRequestOptions](/api-reference/sdk/models/data-models#setlocationsrequestoptions)
* Returns: `Promise`
* React Hook: `n/a`
#### setRootLocation()
Set a different location as the root location when multiple locations are active.
* Params: `location:` [Location](/api-reference/sdk/models/data-models#location)
* Returns: `Promise`
* React Hook: `n/a`
#### removeLocations()
Remove multiple locations.
* Params: `...locations:` [Location\[\]](/api-reference/sdk/models/data-models#location)
* Returns: `void`
* React Hook: `n/a`
#### unsetLocationsIds()
Unset locations by ids or all of them if you don't specify any parameters.
* Params: `ids?: string[]`
* If no ids provided, removes all locations
* If ids provided, removes that specific location
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/key-concepts/overview#unset-locations)
### Event Subscription
#### on()
Subscribe to Velt core events
* Params: `eventType: string`. [Here](/api-reference/sdk/models/data-models#client) is the list of events you can subscribe to.
* Returns: `Observable`. It will return one of the objects from [here](/api-reference/sdk/models/data-models#client)
* React Hook: `useVeltEventCallback()`
### Self Hosting
#### setDataProviders()
Set the data providers for self hosting data.
* Params: [`VeltDataProvider`](/api-reference/sdk/models/data-models#veltdataprovider)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/self-host-data/overview)
#### setAnonymousUserDataProvider()
Register a provider to resolve email → userId mappings for anonymous users tagged by email in comments.
* Params: [`AnonymousUserDataProvider`](/api-reference/sdk/models/data-models#anonymoususerdataprovider)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setanonymoususerdataprovider)
### UI
#### setUiState()
Set custom state data that can be used in Velt wireframes, Velt if and Velt data components.
* Params: `Record`
* Object containing key-value pairs of custom state data
* Returns: `void`
* React Hook: `n/a`
#### getUiState()
Get the custom UI state data.
* Params: `void`
* Returns: `Observable>`
* Observable that emits the current UI state object
* React Hook: `n/a`
#### injectCustomCss()
To inject custom CSS within Components with Shadow DOM enabled.
* Params: `customCss: CustomCss`
* Returns: `void`
* React Hook: `n/a`
#### removeVeltContent()
To remove Velt specific content from provided html content. This is useful when using Velt on a text editor or editable element.
* Params: `htmlContent: string`
* Returns: `string`
* React Hook: `n/a`
#### resetVeltButtonState()
Reset the state of Velt Button components.
* Params: (optional) [VeltResetButtonStateConfig](/api-reference/sdk/models/data-models#veltresetbuttonstateconfig)
* Returns: `void`
* React Hook: `n/a`
* [Full Documentation →](/ui-customization/custom-action-component#reset-velt-button-state)
### Feature Utilities
#### getPresenceElement()
Get the Presence Element Object to access the raw presence data.
* Params: `void`
* Returns: `PresenceElement`
* React Hook: `n/a`
#### getCursorElement()
Get the Cursor Element Object to access the raw cursor data.
* Params: `void`
* Returns: `CursorElement`
* React Hook: `n/a`
#### getCommentElement()
Get the Comment Element Object to access the raw comment data.
* Params: `void`
* Returns: `CommentElement`
* React Hook: `useCommentUtils()`
#### getSelectionElement()
Get the Selection Object to enable/disable the feature.
* Params: `void`
* Returns: `SelectionElement`
* React Hook: `n/a`
#### getRecorderElement()
Get the Recorder Object.
* Params: `void`
* Returns: [`RecorderElement`](/api-reference/sdk/models/data-models#recorderelement)
* React Hook: `n/a`
#### getContactElement()
Get the Contact Object.
* Params: `void`
* Returns: `ContactElement`
* React Hook: `n/a`
#### getRewriterElement()
Get the Rewriter Object.
* Params: `void`
* Returns: `RewriterElement`
* React Hook: `n/a`
#### getLiveStateSyncElement()
Get the LiveStateSync Object.
* Params: `void`
* Returns: `LiveStateSyncElement`
* React Hook: `n/a`
#### getArrowElement()
Get the Arrow Object.
* Params: `void`
* Returns: `ArrowElement`
* React Hook: `n/a`
### Feature Gating
#### isUserAllowed\$()
To check if user is allowed in provided document or not.
* Params: `void`
* Returns: `Observable`
* React Hook: `n/a`
#### disableFeatures()
Provide a list of features to disable. Provide an empty array to enable all the features.
* Params: `features: Array`
* Returns: `void`
* React Hook: `n/a`
#### isPlanExpired\$()
To check if plan is expired or not.
* Params: `void`
* Returns: `Observable`
* React Hook: `n/a`
### Localization
#### setLanguage()
To set the language.
* Params: `language: string`
* Returns: `void`
* React Hook: `n/a`
#### setTranslations()
To set the translations for the language.
* Params: `language: string, translations: { [key: string]: string }`
* Returns: `void`
* React Hook: `n/a`
#### enableAutoTranslation()
To enable automatic translation of text in Velt Components based on User's language preference.
* Params: `void`
* Returns: `void`
* React Hook: `n/a`
### DOM Control
#### setScrollableElementsIds()
Tell us about the scrollable document ids to keep track on its scroll changes.
* Params: `ids: string[]`
* Returns: `void`
* React Hook: `n/a`
#### removeScrollableElementsIds()
To remove document params from a User.
* Params: `void`
* Returns: `void`
* React Hook: `n/a`
# React Hooks Index
Source: https://docs.velt.dev/api-reference/sdk/api/react-hooks
# Comments
#### useCommentUtils()
Hook to access comment utilities
* Params: `void`
* Returns: `CommentElement`
* Related API Method: `client.getCommentElement()`
* [Full Documentation →](/api-reference/sdk/api/api-methods#client)
### Threads
#### useAddCommentAnnotation()
Hook to add a comment annotation
* Params: [AddCommentAnnotationRequest](/api-reference/sdk/models/data-models#addcommentannotationrequest)
* Returns: `addCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addcommentannotation)
#### useDeleteCommentAnnotation()
Hook to delete a comment annotation
* Params: [DeleteCommentAnnotationRequest](/api-reference/sdk/models/data-models#deletecommentannotationrequest)
* Returns: `deleteCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deletecommentannotation)
#### useCommentAnnotationsCount()
Hook to get total and unread comment annotations count
* Params: [CommentRequestQuery](/api-reference/sdk/models/data-models#commentrequestquery) (optional)
* Returns: [GetCommentAnnotationsCountResponse](/api-reference/sdk/models/data-models#getcommentannotationscountresponse)
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcommentannotationscount)
#### useUnreadCommentAnnotationCountByLocationId()
Hook to get unread comment annotation count by location
* Params: `locationId: string`
* Returns: `UnreadCommentsCount | null`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentannotationcountbylocationid)
#### useGetCommentAnnotations()
Hook to get all the comment annotations for all the specified documents
* Params: [CommentRequestQuery](/api-reference/sdk/models/data-models#commentrequestquery) (optional)
* Returns: [GetCommentAnnotationsResponse](/api-reference/sdk/models/data-models#getcommentannotationsresponse)
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcommentannotations)
#### useCommentAnnotationById()
Hook to get a specific comment annotation
* Params: `{ annotationId: string, documentId?: string }`
* Returns: `CommentAnnotation`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcommentannotationbyid)
#### useSetContextProvider()
Hook to set a context provider function for comment annotations
* Returns: `{ setContextProvider: (provider:` [`CommentContextProvider`](/api-reference/sdk/models/data-models#commentcontextprovider) `| null) => void }`
* Related API Method: `commentElement.setContextProvider()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#setcontextprovider)
### Messages
#### useAddComment()
Hook to add a comment to a specific annotation
* Params: [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)
* Returns: `addComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addcomment)
#### useUpdateComment()
Hook to update a comment in a specific annotation
* Params: [UpdateCommentRequest](/api-reference/sdk/models/data-models#updatecommentrequest)
* Returns: `updateComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecomment)
#### useDeleteComment()
Hook to delete a comment from a specific annotation
* Params: [DeleteCommentRequest](/api-reference/sdk/models/data-models#deletecommentrequest)
* Returns: `deleteComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deletecomment)
#### useGetComment()
Hook to get comments from a specific annotation
* Params: [GetCommentRequest](/api-reference/sdk/models/data-models#getcommentrequest)
* Returns: `getComment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcomment)
#### useUnreadCommentCountOnCurrentDocument()
Hook to get number of unread comments on current document
* Params: `void`
* Returns: `UnreadCommentsCount | null`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentcountoncurrentdocument)
#### useUnreadCommentCountByLocationId()
Hook to get number of unread comments by location
* Params: `locationId: string`
* Returns: `UnreadCommentsCount | null`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentcountbylocationid)
#### useUnreadCommentCountByAnnotationId()
Hook to get number of unread comments by annotation
* Params: `annotationId: string`
* Returns: `number`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getunreadcommentcountbyannotationid)
### @Mentions
#### useContactUtils()
Hook to access contact utility methods
* Returns: `ContactElement` with methods for managing contacts
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatecontactlist)
#### useAssignUser()
Hook to assign a user to a comment annotation
* Params: [AssignUserRequest](/api-reference/sdk/models/data-models#assignuserrequest)
* Returns: `assignUser()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#assignuser)
#### useContactSelected()
Hook to handle contact selection events
* Returns: `User`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#oncontactselected)
#### useContactList()
Hook to subscribe to the list of users added to organization, folder, document, user groups or the ones overwritten using the `updateContactList` API.
* Returns: [GetContactListResponse](/api-reference/sdk/models/data-models#getcontactlistresponse)
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getcontactlist)
#### useSubscribeCommentAnnotation()
Hook to subscribe to a comment annotation
* Params: [SubscribeCommentAnnotationRequest](/api-reference/sdk/models/data-models#subscribecommentannotationrequest)
* Returns: `subscribeCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#subscribecommentannotation)
#### useUnsubscribeCommentAnnotation()
Hook to unsubscribe from a comment annotation
* Params: [UnsubscribeCommentAnnotationRequest](/api-reference/sdk/models/data-models#unsubscribecommentannotationrequest)
* Returns: `unsubscribeCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#unsubscribecommentannotation)
### Custom Lists
#### useAutocompleteUtils()
Hook to access autocomplete utilities for custom lists in comments
* Returns: `AutocompleteElement`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#createcustomlistdataoncomment)
#### useAutocompleteChipClick()
Hook to handle clicks on autocomplete chips in comments
* Returns: `AutocompleteItem` data when a chip is clicked
* [Full Documentation →](/async-collaboration/comments/customize-behavior#createcustomlistdataoncomment)
### Event Subscription
#### useCommentEventCallback()
Hook to subscribe to comment events
* Params: `eventType: string`. [Here](/async-collaboration/comments/customize-behavior#on) is the list of events you can subscribe to.
* Returns: Comment Event Object. It will return one of the objects from [here](/api-reference/sdk/models/data-models#comments)
* [Full Documentation →](/async-collaboration/comments/customize-behavior#on)
### Attachments
#### useAddAttachment()
Hook to add an attachment to a comment annotation
* Params: [AddAttachmentRequest](/api-reference/sdk/models/data-models#addattachmentrequest)
* Returns: `addAttachment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addattachment)
#### useDeleteAttachment()
Hook to delete an attachment from a comment annotation
* Params: [DeleteAttachmentRequest](/api-reference/sdk/models/data-models#deleteattachmentrequest)
* Returns: `deleteAttachment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deleteattachment)
#### useGetAttachment()
Hook to get attachments from a comment annotation
* Params: [GetAttachmentRequest](/api-reference/sdk/models/data-models#getattachmentrequest)
* Returns: `getAttachment()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getattachment)
### Reactions
#### useAddReaction()
Hook to add a reaction to a comment
* Params: [AddReactionRequest](/api-reference/sdk/models/data-models#addreactionrequest)
* Returns: `addReaction()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#addreaction)
#### useDeleteReaction()
Hook to delete a reaction from a comment
* Params: [DeleteReactionRequest](/api-reference/sdk/models/data-models#deletereactionrequest)
* Returns: `deleteReaction()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deletereaction)
#### useToggleReaction()
Hook to toggle a reaction on a comment
* Params: [ToggleReactionRequest](/api-reference/sdk/models/data-models#togglereactionrequest)
* Returns: `toggleReaction()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#togglereaction)
### Status & Priority
#### useUpdateStatus()
Hook to update the status of a comment annotation
* Params: [UpdateStatusRequest](/api-reference/sdk/models/data-models#updatestatusrequest)
* Returns: `updateStatus()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatestatus)
#### useResolveCommentAnnotation()
Hook to resolve a comment annotation
* Params: [ResolveCommentAnnotationRequest](/api-reference/sdk/models/data-models#resolvecommentannotationrequest)
* Returns: `resolveCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#resolvecommentannotation)
#### useUpdatePriority()
Hook to update the priority of a comment annotation
* Params: [UpdatePriorityRequest](/api-reference/sdk/models/data-models#updatepriorityrequest)
* Returns: `updatePriority()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#updatepriority)
### Recording
#### useDeleteRecording()
Hook to delete a recording from a comment annotation
* Params: [DeleteRecordingRequest](/api-reference/sdk/models/data-models#deleterecordingrequest)
* Returns: `deleteRecording()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#deleterecording)
#### useGetRecording()
Hook to get recordings from a comment annotation
* Params: [GetRecordingRequest](/api-reference/sdk/models/data-models#getrecordingrequest)
* Returns: `getRecording()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getrecording)
### Deep Link
#### useGetLink()
Hook to get a link to a specific comment annotation
* Params: [GetLinkRequest](/api-reference/sdk/models/data-models#getlinkrequest)
* Returns: `getLink()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#getlink)
#### useCopyLink()
Hook to copy a comment annotation link to clipboard
* Params: [CopyLinkRequest](/api-reference/sdk/models/data-models#copylinkrequest)
* Returns: `copyLink()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#copylink)
### Navigation
#### useCommentSelectionChangeHandler()
Hook to subscribe to comment selection changes
* Returns: `CommentSelectionChangeData` with:
* `selected: boolean`
* `annotation: CommentAnnotation`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#oncommentselectionchange)
### UI
#### useUiState()
Hook to read and update UI state for use in wireframes, `VeltIf`, and `VeltData`.
* Returns: `{ uiState: Record | null, setUiState: (data: Record) => void }`
* [Full Documentation →](/ui-customization/template-variables)
```jsx theme={null}
const { uiState, setUiState } = useUiState();
useEffect(() => {
console.log('uiState: ', uiState);
}, [uiState]);
// Update values
setUiState({ a: 1, b: 2 });
// Reset fields to null
setUiState({ a: null, b: null });
```
#### useCommentDialogSidebarClickHandler()
Hook to handle clicks on the sidebar button in the comment dialog
* Returns: Event data
* [Full Documentation →](/async-collaboration/comments/customize-behavior#onsidebarbuttononcommentdialogclick)
### Moderation
#### useApproveCommentAnnotation()
Hook to approve comment annotations in moderator mode
* Params: [ApproveCommentAnnotationRequest](/api-reference/sdk/models/data-models#approvecommentannotationrequest)
* Returns: `approveCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#approvecommentannotation)
#### useAcceptCommentAnnotation()
Hook to accept comment annotations in suggestion mode
* Params: [AcceptCommentAnnotationRequest](/api-reference/sdk/models/data-models#acceptcommentannotationrequest)
* Returns: `acceptCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#acceptcommentannotation)
#### useRejectCommentAnnotation()
Hook to reject comment annotations in suggestion mode
* Params: [RejectCommentAnnotationRequest](/api-reference/sdk/models/data-models#rejectcommentannotationrequest)
* Returns: `rejectCommentAnnotation()`
* [Full Documentation →](/async-collaboration/comments/customize-behavior#rejectcommentannotation)
### Comment Tool
#### useCommentModeState()
Hook to track the current state of comment mode
* Returns: `boolean` indicating if comment mode is active
* Automatically updates when comment mode changes
* [Full Documentation →](/async-collaboration/comments/customize-behavior#oncommentmodechange)
# Notifications
#### useNotificationSettings()
Hook to get and update notification settings for the current user
* Returns: `{ setSettingsInitialConfig, setSettings, settings }`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#setsettingsinitialconfig)
#### useNotificationUtils()
Hook to access notification element for utility methods
* Returns: `NotificationElement`
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#settabconfig)
#### useNotificationsData()
Hook to access notifications data for the current user
* Params:
* query: Optional. [`GetNotificationsDataQuery`](/api-reference/sdk/models/data-models#getnotificationsdataquery)
* `type`: Filter for notification type: all, for you, or documents.
* `forYou`: returns notifications where the current user is involved.
* `all` / `documents`: returns all notifications from the documents the user has access to.
* Returns: Array of [`Notification`](/api-reference/sdk/models/data-models#notification) objects
* Automatically updates when notifications change
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#getnotificationsdata)
#### useUnreadNotificationsCount()
Hook to get count of unread notifications
* Returns: Object with counts by tab
```typescript theme={null}
{
forYou: number, // Unread in "For You" tab
all: number // Unread in "All" tab
}
```
* Automatically updates when unread status changes
* [Full Documentation →](/async-collaboration/notifications/customize-behavior#getunreadnotificationscount)
# Inline Reactions
#### useReactionElement()
Hook to access reaction element for utility methods
* Returns: `ReactionElement`
* [Full Documentation →](/async-collaboration/reactions/customize-behavior#setcustomreactions)
# Recorder
#### useRecorderUtils()
Hook to access recorder element for utility methods
* Returns: `RecorderElement`
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#enablerecordingcountdown)
#### useRecorderEventCallback()
Hook to subscribe to recorder events
* Params: `eventType: string`. [Here](/api-reference/sdk/models/data-models#recorder) is the list of events you can subscribe to.
* Returns: Recorder Event Object. It will return one of the objects from [here](/api-reference/sdk/models/data-models#recorder)
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#on)
#### useRecordings()
Subscribe to all recording data from either the current document or specified recorder IDs.
* Params: [RecorderRequestQuery](/api-reference/sdk/models/data-models#recorderrequestquery) (optional)
* Returns: [`Observable`](/api-reference/sdk/models/data-models#getrecordingsresponse)
* [Full Documentation →](/async-collaboration/recorder/customize-behavior#getrecordings)
# View Analytics
#### useViewsElement()
Hook to access views element for utility methods
* Returns: `ViewsElement`
* [Full Documentation →](/async-collaboration/view-analytics/customize-behavior)
#### useUniqueViewsByUser()
Hook to get unique views grouped by user
* Params: `locationId: string`
* Returns: Array of view analytics data by user
* [Full Documentation →](/async-collaboration/view-analytics/customize-behavior#getuniqueviewsbyuser)
#### useUniqueViewsByDate()
Hook to get unique views grouped by date
* Params: `locationId: string`
* Returns: Array of view analytics data by date
* [Full Documentation →](/async-collaboration/view-analytics/customize-behavior#getuniqueviewsbydate)
# Live State Sync
#### useLiveStateSyncUtils()
Hook to access live state sync utilities
* Params: `void`
* Returns: `LiveStateSyncElement`
* Related API Method: `client.getLiveStateSyncElement()`
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup)
#### useLiveStateData()
Hook to get live state data
* Params: `string`
* Returns: `any`
* Related API Method: `liveStateSyncElement.getLiveStateData()`
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup)
#### useSetLiveStateData()
Hook to set live state data
* Params:
* `liveStateDataId`: `string`
* `liveStateData`: `any`
* `config`: `SetLiveStateDataConfig`
* Returns: `void`
* Related API Method: `liveStateSyncElement.setLiveStateData()`
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup)
#### useLiveState()
Hook to sync state variables across clients in real-time (similar to React's useState)
* Params:
* `uniqueId`: string - Unique identifier to sync across screens
* `initialValue`: any - Initial value of the state
* `options?`: object
* `syncDuration`: number - Debounce duration in ms (default: 50)
* `resetLiveState`: boolean - Reset state on init (default: false)
* `listenToNewChangesOnly`: boolean - Only listen to new changes (default: false)
* Returns: `[value, setValue, serverConnectionState]`
* `value`: Current state value
* `setValue`: Function to update state
* `serverConnectionState`: Current server connection state
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup)
#### useServerConnectionStateChangeHandler()
Hook to listen to server connection state changes
* Params: none
* Returns: `ServerConnectionState` - One of:
* `'online'` - Server connection is active
* `'offline'` - Server connection is lost
* `'pendingInit'` - Connection initialization pending
* `'pendingData'` - Waiting for data from server
* Related API Method: `liveStateSyncElement.onServerConnectionStateChange()`
* [Full Documentation →](/realtime-collaboration/live-state-sync/setup)
# Single Editor Mode
#### useUserEditorState()
Hook to check if current user is the editor
* Returns: `UserEditorAccess` object with:
* `isEditor`: boolean indicating if user is editor
* `isEditorOnCurrentTab`: boolean indicating if user is editor on current tab
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### useEditor()
Hook to get the current editor
* Returns: `User` object with editor details (email, name, photoUrl, userId)
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### useEditorAccessRequestHandler()
Hook to handle editor access requests
* Returns: Object with:
* `requestStatus`: 'requested' when access is requested
* `requestedBy`: User object of requester
* Returns `null` if user is not editor or request is canceled
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
#### useEditorAccessTimer()
Hook to track editor access request timer state
* Returns: Object with:
* `state`: 'idle' | 'inProgress' | 'completed'
* `durationLeft`: number of seconds remaining
* Useful for building custom UI for access requests
* [Full Documentation →](/realtime-collaboration/single-editor-mode/setup)
# Presence
#### usePresenceEventCallback()
Hook to subscribe to presence events
* Params: `eventType: string`. [Here](/api-reference/sdk/models/data-models#presence) is the list of events you can subscribe to.
* Returns: Presence Event Object. It will return one of the objects from [here](/api-reference/sdk/models/data-models#presence)
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#on)
#### usePresenceUtils()
Hook to access presence element for presence control methods
* Returns: `PresenceElement`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#setinactivitytime)
#### usePresenceData()
Hook to subscribe to presence data
* Params: `PresenceRequestQuery`
* Returns: `Observable`
* [Full Documentation →](/realtime-collaboration/presence/customize-behavior#getdata)
# Cursor
#### useCursorUtils()
Hook to access cursor element for cursor utility methods
* Returns: `CursorElement`
#### useCursorUsers()
Hook to get online users with cursors activated
* Params: `void`
* Returns: `User[]`
* Related API Method: `cursorElement.getOnlineUsersOnCurrentDocument()`
* [Full Documentation →](/realtime-collaboration/cursors/customize-behavior#getonlineusersoncurrentdocument)
# Live Selection
#### useLiveSelectionUtils()
Hook to access live selection element for control methods
* Returns: `LiveSelectionElement`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#enabledefaultelementsTracking)
#### useLiveSelectionDataHandler()
Hook to get live selection data for the current document
* Returns: `LiveSelectionData`
* Related API Method: `liveSelectionElement.getLiveSelectionData()`
* [Full Documentation →](/realtime-collaboration/live-selection/customize-behavior#getliveselectiondata)
# Huddle
#### useHuddleUtils()
Hook to access huddle utilities
* Params: `void`
* Returns: `HuddleElement`
* Related API Method: `client.getHuddleElement()`
* [Full Documentation →](/realtime-collaboration/huddle/customize-behavior)
# AI
#### useAIRewriterUtils()
Hook to access AI rewriter utilities
* Params: `void`
* Returns: `RewriterElement`
* Related API Method: `client.getRewriterElement()`
# Core
### Client
#### useVeltClient()
Hook to access the Velt client instance
* Returns: Object with:
* `client`: Velt
#### useVeltInitState()
Hook to get Velt initialization state
* Params: `void`
* Returns: `boolean`
* Related API Method: `client.getVeltInitState()`
* [Full Documentation →](/get-started/advanced)
#### useHeartbeat()
Hook to subscribe to user-specific heartbeat data
* Params: [`HeartbeatConfig`](/api-reference/sdk/models/data-models#heartbeatconfig) (optional)
* Returns: [`Observable`](/api-reference/sdk/models/data-models#getheartbeatresponse)
* [Full Documentation →](/realtime-collaboration/presence/heartbeat)
### Authentication
#### useIdentify()
Hook to authenticate a user with Velt
* Params:
* `user`: `User`
* `options?`: Object:
* `authToken?`: JWT token for additional security
* `forceReset?`: Force re-login (default: false)
* Must be called within a child component of VeltProvider
* Asynchronous operation
* [Full Documentation →](/get-started/advanced)
#### useCurrentUser()
Hook to subscribe to changes in the current user object
* Params: `void`
* Returns: `User | null`
* Related API Method: `client.getCurrentUser()`
* [Full Documentation →](/key-concepts/overview#get-current-user)
### Document
#### useSetDocuments()
Hook to initialize multiple documents at once
* Params:
* `documents`: [Document\[\]](/api-reference/sdk/models/data-models#document)
* `options?`: [SetDocumentsRequestOptions](/api-reference/sdk/models/data-models#setdocumentsrequestoptions)
* [Full Documentation →](/key-concepts/overview#set-multiple-documents)
#### useSetDocument()
Hook to initialize a document for collaboration
* Params:
* `documentId`: string
* `metadata?`: [DocumentMetadata](/api-reference/sdk/models/data-models#documentmetadata)
* [Full Documentation →](/key-concepts/overview#set-a-single-document)
#### useUnsetDocuments()
Hook to unsubscribe from all documents at once.
* Use when Velt features are not needed
* Cleans up document-specific resources
* [Full Documentation →](/key-concepts/overview#unset-multiple-documents)
### Location
#### useSetLocation()
Hook to set the current location context. Used to define specific areas within a document.
* Params:
* `location`: Location object with:
* `id`: Required unique identifier
* `locationName?`: Optional display name for UI components
* `version?`: Optional version object with:
* `id`: Version identifier
* `name`: Version display name
* Additional custom key/value pairs
* `isAdditional?`: Boolean to add additional locations
* `false` (default): Set this as the root location
* `true`: Add as additional location
* [Full Documentation →](/key-concepts/overview#set-location)
### Event Subscription
#### useVeltEventCallback()
Hook to subscribe to Velt core events
* Params: `eventType: string`. [Here](/api-reference/sdk/models/data-models#client) is the list of events you can subscribe to.
* Returns: `VeltEventTypesMap[T]`. It will return one of the objects from [here](/api-reference/sdk/models/data-models#client)
# Data models
Source: https://docs.velt.dev/api-reference/sdk/models/data-models
# Comments
### Threads
#### CommentAnnotation
***
| Property | Type | Required | Description |
| ------------------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `annotationId` | `string` | Yes | Unique identifier for the comment pin annotation. Auto generated |
| `comments` | `Comment[]` | Yes | The list of all comments part of this annotation |
| `commentCategories` | `CustomCategory[]` | Yes | The list of categories that this comment pin annotation belongs to |
| `from` | `User` | Yes | The user who created this comment pin annotation |
| `color` | `string` | No | Color used for the comment pin annotation |
| `resolved` | `boolean` | No | Whether the comment annotation is marked resolved. Deprecated |
| `inProgress` | `boolean` | No | Whether the comment annotation is marked as in progress. Deprecated |
| `lastUpdated` | `any` | No | Timestamp when the comment annotation was last updated. Auto generated |
| `createdAt` | `any` | No | Timestamp when the comment annotation was created. Auto generated |
| `position` | `CursorPosition \| null` | No | Cursor position relative to the comment annotation |
| `locationId` | `number \| null` | No | Unique location id generated from provided location |
| `location` | `Location \| null` | No | Set location to identify user on sub document |
| `type` | `string` | No | Type of the comment annotation |
| `selectAllContent` | `boolean` | No | If true, sets text comment annotation on all the text content |
| `approved` | `boolean` | No | Whether the comment annotation is approved |
| `status` | `CustomStatus` | Yes | Status of the comment annotation. Default: CommentAnnotationStatusMap.OPEN |
| `annotationIndex` | `number` | No | Index of current annotation in the list |
| `annotationNumber` | `number` | No | Fixed annotation number that persists across sessions. Used for referencing specific comments |
| `pageInfo` | `PageInfo` | No | Page information related to the comment annotation |
| `assignedTo` | `User` | No | User to whom the comment annotation is assigned |
| `priority` | `CustomPriority` | No | Priority level of the comment annotation |
| `ghostComment` | `GhostComment \| null` | No | Placeholder for a non-existing comment |
| `context` | `any` | No | Custom context data provided by the user |
| `resolvedByUserId` | `string` | No | ID of the user who resolved the comment |
| `resolvedByUser` | [`User`](#user) | No | User object who resolved the comment annotation |
| `subscribedUsers` | `CommentAnnotationSubscribedUsers` | No | Users who explicitly subscribe to the comment |
| `unsubscribedUsers` | `CommentAnnotationUnsubscribedUsers` | No | Users who explicitly unsubscribe to the comment |
| `multiThreadAnnotationId` | `string` | No | ID of the multithread annotation group it belongs to, if created in multithread mode |
| `isDraft` | `boolean` | No | Indicates if the comment annotation is in draft state |
| `customList` | `CustomAnnotationDropdownItem[]` | No | Custom list of items for the comment annotation |
| `targetElementId` | `string` | No | ID of the target element for the comment annotation if available |
| `viewedBy` | [`Users[]`](#user) | No | List of users who have viewed/read this comment annotation |
| `unread` | `boolean` | No | Whether the annotation is unread by current user |
| `visibilityConfig` | [`CommentAnnotationVisibilityConfig`](#commentannotationvisibilityconfig) | No | Human-readable visibility configuration for the annotation. Contains type, organizationId, and userIds. Defaults to `{ type: 'public' }` for new annotations without explicit visibility. |
#### Enum
| Enum Name | Event Type | Description |
| ------------------------------ | --------------------------- | --------------------------------------------------------------- |
| `ADD_COMMENT_ANNOTATION` | `addCommentAnnotation` | Add a new comment annotation |
| `ADD_COMMENT_ANNOTATION_DRAFT` | `addCommentAnnotationDraft` | Triggered when comment annotation draft is created |
| `DELETE_COMMENT_ANNOTATION` | `deleteCommentAnnotation` | Delete a comment annotation |
| `VISIBILITY_OPTION_CLICKED` | `visibilityOptionClicked` | Triggered when user selects a visibility option from the banner |
| `COMMENT_SAVE_TRIGGERED` | `commentSaveTriggered` | Triggered when comment save is initiated |
#### AddCommentAnnotationEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------------ | -------- | ----------------------------------------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
| `addContext` | `(context: any) => void` | Yes | Function to add custom metadata |
| `elementRef` | `{ xpath: string }` | No | Reference to DOM element where comment annotation was added |
#### AddCommentAnnotationDraftEvent
***
| Property | Type | Required | Description |
| ------------ | ---------------------------------------------------------- | -------- | --------------------------------------------- |
| `addContext` | `(context:` [`CommentContext`](#commentcontext)`) => void` | No | Function to add context during draft creation |
#### DeleteCommentAnnotationEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### CommentBubbleClickedEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
#### CommentSavedEvent
***
| Property | Type | Required | Description |
| ------------------- | ----------------------------------------- | -------- | ----------------------------------- |
| `annotationId` | `string` | Yes | ID of the saved annotation |
| `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | The saved comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### VisibilityOptionClickedEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation whose visibility was changed |
| `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full annotation at the time of the visibility selection |
| `visibility` | [`CommentVisibilityOptionType`](#commentvisibilityoptiontype) | Yes | Selected visibility level |
| `users` | `any[]` | No | Populated only when `visibility === 'restricted'` |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
#### CommentSaveTriggeredEvent
***
| Property | Type | Required | Description |
| ------------------- | ----------------------------------------- | -------- | -------------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation being saved |
| `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full annotation at save time |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### CommentContext
***
Custom context data for comment annotations.
```typescript theme={null}
type CommentContext = any;
```
#### CommentContextProviderResponse
***
Return type for context provider function. Can return context synchronously or asynchronously.
```typescript theme={null}
type CommentContextProviderResponse = CommentContext | null | undefined;
```
#### CommentContextProvider
***
Function type for providing context based on document and location.
```typescript theme={null}
type CommentContextProvider = (documentId: string, location?: Location) => CommentContextProviderResponse | Promise;
```
#### CommentVisibilityType
***
Visibility level used by **API methods** such as [`updateVisibility()`](/api-reference/sdk/api/api-methods#updatevisibility) and [`enablePrivateMode()`](/api-reference/sdk/api/api-methods#enableprivatemode) via [`CommentVisibilityConfig`](#commentvisibilityconfig).
```typescript theme={null}
type CommentVisibilityType = 'public' | 'organizationPrivate' | 'restricted';
```
| Value | Description |
| ----------------------- | ----------------------------------------------------------- |
| `'public'` | Comment visible to all users |
| `'organizationPrivate'` | Comment visible only to users in the specified organization |
| `'restricted'` | Comment visible only to specified users (private) |
The visibility system uses two separate sets of values:
* **API methods** use [`CommentVisibilityConfig`](#commentvisibilityconfig) with [`CommentVisibilityType`](#commentvisibilitytype) values: `'public'`, `'organizationPrivate'`, `'restricted'` (3 values — `'restricted'` covers both self-only and selected-people, distinguished by whether `userIds` is provided).
* **UI wireframes** use the [`CommentVisibilityOption`](#commentvisibilityoption) enum with 4 values: `'restrictedSelf'`, `'restrictedSelectedPeople'`, `'organizationPrivate'`, `'public'`. These are the `type` prop values on visibility banner dropdown wireframe items.
#### CommentVisibilityOption
***
Enum for **UI wireframe** visibility levels, used as the `type` prop on visibility banner dropdown content items. These are more granular than the API-level [`CommentVisibilityType`](#commentvisibilitytype) — the API's single `'restricted'` value maps to two UI options (`'restrictedSelf'` and `'restrictedSelectedPeople'`).
```typescript theme={null}
export declare enum CommentVisibilityOption {
RESTRICTED_SELF = "restrictedSelf",
RESTRICTED_SELECTED_PEOPLE = "restrictedSelectedPeople",
ORGANIZATION_PRIVATE = "organizationPrivate",
PUBLIC = "public"
}
```
| Value | Description | API Equivalent |
| ---------------------------- | ------------------------------------------- | ---------------------------------------------- |
| `RESTRICTED_SELF` | Visible only to the comment author | `'restricted'` with `userIds: [currentUserId]` |
| `RESTRICTED_SELECTED_PEOPLE` | Visible only to specifically selected users | `'restricted'` with `userIds: [...]` |
| `ORGANIZATION_PRIVATE` | Visible to users in the organization | `'organizationPrivate'` |
| `PUBLIC` | Visible to all users | `'public'` |
#### CommentVisibilityOptionType
***
String union type derived from [`CommentVisibilityOption`](#commentvisibilityoption) enum values. Used in UI wireframe components.
```typescript theme={null}
export type CommentVisibilityOptionType = `${CommentVisibilityOption}`;
// = 'restrictedSelf' | 'restrictedSelectedPeople' | 'organizationPrivate' | 'public'
```
#### CommentVisibilityConfig
***
Configuration object for **API methods** that update comment visibility. Uses [`CommentVisibilityType`](#commentvisibilitytype) values — not [`CommentVisibilityOption`](#commentvisibilityoption) values.
| Property | Type | Required | Description |
| ---------------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | Visibility level: `'public'`, `'organizationPrivate'`, or `'restricted'`. |
| `annotationId` | `string` | Yes | Annotation ID of the comment to update visibility. |
| `organizationId` | `string` | No | Organization ID. Required when `type` is `'organizationPrivate'`. |
| `userIds` | `string[]` | No | User IDs who can see the comment. Used when `type` is `'restricted'`. The current user is automatically appended if not present. |
#### PrivateModeConfig
***
Configuration for enabling private mode via **API methods**. Subset of [`CommentVisibilityConfig`](#commentvisibilityconfig) — excludes `annotationId` and `organizationId`. Uses [`CommentVisibilityType`](#commentvisibilitytype) values.
```typescript theme={null}
type PrivateModeConfig = Omit;
```
| Property | Type | Required | Description |
| --------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | Visibility level applied when private mode is active. |
| `userIds` | `string[]` | No | User IDs who can see comments. Used when `type` is `'restricted'`. The current user is automatically appended if not present. |
#### CommentAnnotationVisibilityConfig
***
Human-readable visibility configuration stored on a comment annotation.
| Property | Type | Required | Description |
| ---------------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | The visibility type for the comment annotation. |
| `organizationId` | `string` | No | The organization ID for organization-private visibility. |
| `userIds` | `string[]` | No | The user IDs for restricted visibility. Always includes the current user when type is `'restricted'`. |
#### CommentAnnotationSubscribedUsers
***
| Property | Type | Required | Description |
| ------------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userIdHash` | `string` | Yes | The user ID of the subscribed user |
| `user` | `User` | Yes | The user object of the subscribed user |
| `type` | `'manual' \| 'auto'` | Yes | Manual: if the user used the UI option to subscribe; Auto: When the system automatically adds the user to the subscribed list. eg: when the user creates a comment annotation |
#### CommentAnnotationUnsubscribedUsers
***
| Property | Type | Required | Description |
| ------------ | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userIdHash` | `string` | Yes | The user ID of the unsubscribed user |
| `user` | `User` | Yes | The user object of the unsubscribed user |
| `type` | `'manual' \| 'auto'` | Yes | Manual: if the user used the UI option to unsubscribe; Auto: When the system automatically removes the user from the unsubscribed list. eg: when the comment where user was tagged is deleted |
#### AddCommentAnnotationRequest
***
| Property | Type | Required | Description |
| ------------ | ------------------- | -------- | ------------------ |
| `annotation` | `CommentAnnotation` | Yes | Comment annotation |
| `options` | `RequestOptions` | No | Request options |
#### DeleteCommentAnnotationRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### SubmitCommentRequest
***
| Property | Type | Required | Description |
| ------------------------- | -------- | -------- | ------------------------------------------- |
| `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to submit |
#### ClearComposerRequest
***
| Property | Type | Required | Description |
| ------------------------- | -------- | -------- | ------------------------------------------ |
| `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to clear |
#### GetComposerDataRequest
***
| Property | Type | Required | Description |
| ------------------------- | -------- | -------- | ------------------------------------------ |
| `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to query |
#### PageModeComposerConfig
***
| Property | Type | Required | Description |
| ----------------- | -------------------------------- | -------- | --------------------------------------------------------------------- |
| `context` | `{ [key: string]: any } \| null` | No | Custom context data for page mode composer |
| `targetElementId` | `string \| null` | No | Target element ID to bind with comment annotation |
| `clearContext` | `boolean` | No | When `false`, preserves context after submission. Defaults to `true`. |
#### AssignToConfig
***
| Property | Type | Required | Description |
| -------- | -------------------------- | -------- | ------------------------------------------------------------------- |
| `type` | `'dropdown' \| 'checkbox'` | Yes | Assignment UI mode: dropdown for menu, checkbox for self-assignment |
#### FormatConfig
***
Configuration for text formatting toolbar options in comment composers.
| Property | Type | Required | Description |
| --------------- | --------------------- | -------- | ------------------------------------------------- |
| `bold` | `{ enable: boolean }` | No | Enable or disable bold formatting option |
| `italic` | `{ enable: boolean }` | No | Enable or disable italic formatting option |
| `underline` | `{ enable: boolean }` | No | Enable or disable underline formatting option |
| `strikethrough` | `{ enable: boolean }` | No | Enable or disable strikethrough formatting option |
#### CommentRequestQuery
***
| Property | Type | Required | Description |
| --------------------- | ---------- | -------- | -------------------------------------------------------------------------- |
| `organizationId` | `string` | No | Organization ID to filter comment annotations by organization |
| `documentIds` | `string[]` | No | Array of document IDs to query. |
| `locationIds` | `string[]` | No | Array of location IDs to filter by |
| `statusIds` | `string[]` | No | Array of status IDs to filter by |
| `folderId` | `string` | No | Folder ID to filter comment annotations by folder |
| `allDocuments` | `boolean` | No | If true, includes all documents in the query |
| `locationId` | `string` | No | Single location ID to filter by (alternative to `locationIds`) |
| `aggregateDocuments` | `boolean` | No | If true, aggregates comment annotation counts across multiple documents |
| `filterGhostComments` | `boolean` | No | If true, excludes ghost (deleted or orphaned) comments from the results |
| `batchedPerDocument` | `boolean` | No | Enable batched listener for large document lists (50+ docs) |
| `debounceMs` | `number` | No | Debounce delay for auto-batching updates in milliseconds (default: 5000ms) |
#### GetCommentAnnotationsCountResponse
***
| Property | Type | Required | Description |
| -------- | ------------------------------------------------- | -------- | --------------------------------------------------------------- |
| `data` | `Record \| null` | Yes | Map of document IDs to their comment counts. Null while loading |
#### GetCommentAnnotationsResponse
***
| Property | Type | Required | Description |
| -------- | --------------------------------------------- | -------- | ------------------------------------------------------------ |
| `data` | `Record \| null` | Yes | Map of document IDs to their annotations. Null while loading |
#### FetchCommentAnnotationsRequest
***
| Property | Type | Required | Description |
| ------------------ | ----------------- | -------- | -------------------------------------------------------------- |
| `createdAfter` | `number` | No | Filter annotations created after this timestamp |
| `createdBefore` | `number` | No | Filter annotations created before this timestamp |
| `updatedAfter` | `number` | No | Filter annotations updated after this timestamp |
| `updatedBefore` | `number` | No | Filter annotations updated before this timestamp |
| `statusIds` | `string[]` | No | Filter annotations by status IDs |
| `order` | `'asc' \| 'desc'` | No | Sort order for annotations |
| `pageToken` | `string` | No | Token for fetching next page of results |
| `allDocuments` | `boolean` | No | Whether to fetch annotations from all documents |
| `pageSize` | `number` | No | Number of results per page |
| `organizationId` | `string` | No | Organization ID to fetch annotations from |
| `locationId` | `string` | No | Location ID to filter annotations by |
| `documentIds` | `string[]` | No | Array of specific document IDs to fetch from |
| `folderId` | `string` | No | Folder ID to fetch annotations from |
| `resolvedBy` | `string` | No | Filter comments by user who resolved the comment |
| `userIds` | `string[]` | No | Filter comments by comment annotation author |
| `mentionedUserIds` | `string[]` | No | Filter comments where provided users are tagged in the comment |
#### FetchCommentAnnotationsResponse
***
| Property | Type | Required | Description |
| --------------- | --------------------------------------------- | -------- | -------------------------------------------------------------- |
| `data` | `Record \| null` | Yes | Map of document IDs to their annotations. `Null` while loading |
| `nextPageToken` | `string` | Yes | Token for fetching next page of results |
#### GetCommentResolverRequest
***
| Property | Type | Required | Description |
| ---------------------- | ---------- | -------- | -------------------------------------------------------------------- |
| `organizationId` | `string` | Yes | Organization ID to fetch comments from |
| `commentAnnotationIds` | `string[]` | No | Array of comment annotation IDs to fetch comments from |
| `documentIds` | `string[]` | No | Array of document IDs to fetch comments from |
| `folderId` | `string` | No | Folder ID to fetch comments from |
| `allDocuments` | `boolean` | No | Whether to fetch comments from all documents within the given folder |
#### SaveCommentResolverRequest
***
| Property | Type | Required | Description |
| ------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
| `commentAnnotation` | `{ [key: string]: PartialCommentAnnotation }` | Yes | Map of comment annotation data to save |
| `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. |
| `event` | `ResolverActions` | No | Event name that caused the save request |
| `commentId` | `string` | No | ID of the comment to save |
#### DeleteCommentResolverRequest
***
| Property | Type | Required | Description |
| --------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- |
| `commentAnnotationId` | `string` | Yes | ID of the comment annotation to delete |
| `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. |
| `event` | `ResolverActions` | No | Event name that caused the delete request |
#### CustomAnnotationDropdownData
***
| Property | Type | Required | Description |
| ------------- | -------------------------------- | -------- | ----------------------------------------------------------- |
| `type` | `'multi' \| 'single'` | Yes | The type of the custom annotation dropdown |
| `placeholder` | `string` | Yes | The placeholder text for the dropdown. Defaults to 'Select' |
| `data` | `CustomAnnotationDropdownItem[]` | Yes | An array of dropdown items |
#### CustomAnnotationDropdownItem
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ------------------------------------------- |
| `id` | `string` | Yes | The unique identifier for the dropdown item |
| `label` | `string` | Yes | The display text for the dropdown item |
#### GetCommentAnnotationsResponse
***
| Property | Type | Required | Description |
| -------- | ------------------------------------- | -------- | ------------------------------------------------ |
| `data` | `Record` | Yes | Map of document IDs to their comment annotations |
#### CommentAnnotationsCount
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ------------------------- |
| `unread` | `number` | Yes | Number of unread comments |
| `total` | `number` | Yes | Total number of comments |
#### GetCommentAnnotationsCountResponse
***
| Property | Type | Required | Description |
| -------- | ----------------------------------------- | -------- | ------------------------------------------- |
| `data` | `Record` | Yes | Map of document IDs to their comment counts |
### Slate
#### AddCommentRequest
***
| Property | Type | Required | Description |
| ---------- | --------- | -------- | ---------------------------------------------------- |
| `editor` | `Editor` | Yes | Slate editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `context` | `unknown` | No | Optional custom context to attach to the annotation. |
#### RenderCommentsRequest
***
| Property | Type | Required | Description |
| -------------------- | --------------------- | -------- | -------------------------------------------- |
| `editor` | `Editor` | Yes | Slate editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. |
For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation).
#### VeltCommentsElement
***
Slate element type representing a comment with optional annotation ID.
| Property | Type | Required | Description |
| -------------- | --------------- | -------- | ---------------------------------------- |
| `type` | `'veltComment'` | Yes | Discriminator for Velt comment elements. |
| `children` | `Descendant[]` | Yes | Slate child nodes. |
| `annotationId` | `string` | No | Associated CommentAnnotation ID. |
### Tiptap
#### AddCommentRequest
***
| Property | Type | Required | Description |
| ---------- | -------------------------- | -------- | ---------------------------------------------------- |
| `editor` | `Editor` | Yes | Tiptap editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. |
#### RenderCommentsRequest
***
| Property | Type | Required | Description |
| -------------------- | --------------------- | -------- | -------------------------------------------- |
| `editor` | `Editor` | Yes | Tiptap editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. |
For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation).
#### TiptapVeltCommentsOptions
***
| Property | Type | Required | Description |
| ------------------ | --------------------- | -------- | ------------------------------------------------------------ |
| `HTMLAttributes` | `Record` | No | Attributes applied to rendered comment nodes/marks. |
| `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks across edits. Default: `true`. |
| `editorId` | `string` | No | ID to scope Velt operations to a specific editor instance. |
#### CommentAnnotationContext
***
Context object for comment annotations. Contains text editor configuration and any additional custom metadata.
| Property | Type | Required | Description |
| ------------------ | ------------------ | -------- | ---------------------------------------------------------- |
| `textEditorConfig` | `TextEditorConfig` | No | Text editor configuration (auto-generated by the library). |
| `[key: string]` | `unknown` | No | Any additional custom properties you want to attach. |
#### TextEditorConfig
***
Nested in `CommentAnnotationContext`.
| Property | Type | Required | Description |
| ------------------ | -------- | -------- | ------------------------------------------------- |
| `text` | `string` | Yes | The selected text content. |
| `occurrence` | `number` | Yes | The occurrence index of the text in the document. |
| `editorId` | `string` | No | The editor ID associated with this comment. |
| `targetTextNodeId` | `string` | No | ID of the target text node container. |
### Lexical
#### AddCommentRequest
***
| Property | Type | Required | Description |
| ---------- | --------- | -------- | ---------------------------------------------------- |
| `editor` | `Editor` | Yes | Lexical editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `context` | `unknown` | No | Optional custom context to attach to the annotation. |
#### RenderCommentsRequest
***
| Property | Type | Required | Description |
| -------------------- | --------------------- | -------- | -------------------------------------------- |
| `editor` | `Editor` | Yes | Lexical editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. |
For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation).
#### CommentNode
***
Inline Lexical element representing a comment with optional annotation IDs.
| Property | Type | Required | Description |
| ------------------------- | ------------------------- | -------- | --------------------------------------------------- |
| `type` | `'comment'` | Yes | Discriminator for Velt comment nodes. |
| `children` | `SerializedLexicalNode[]` | Yes | Lexical child nodes (from `SerializedElementNode`). |
| `annotationId` | `string` | No | Associated `CommentAnnotation` ID. |
| `multiThreadAnnotationId` | `string` | No | Associated multi-thread annotation ID. |
### Plate
#### AddCommentRequest
***
| Property | Type | Required | Description |
| ---------- | -------------------------- | -------- | ---------------------------------------------------- |
| `editor` | `PlateEditor` | Yes | Plate editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. |
#### RenderCommentsRequest
***
| Property | Type | Required | Description |
| -------------------- | --------------------- | -------- | -------------------------------------------- |
| `editor` | `PlateEditor` | Yes | Plate editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. |
For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation).
#### VeltCommentsPluginConfig
***
| Property | Type | Required | Description |
| ------------------ | --------- | -------- | ------------------------------------------------------------------------ |
| `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). |
| `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. |
#### VeltCommentsElement
***
Plate element type representing a comment with optional annotation IDs.
| Property | Type | Required | Description |
| ------------------------- | --------------- | -------- | ----------------------------------------- |
| `type` | `'veltComment'` | Yes | Element type identifier. |
| `children` | `Descendant[]` | Yes | Child nodes (text content). |
| `annotationId` | `string` | No | The Velt annotation ID. |
| `multiThreadAnnotationId` | `string` | No | Multi-thread annotation ID if applicable. |
### CodeMirror
#### AddCommentRequest
***
| Property | Type | Required | Description |
| ---------- | -------------------------- | -------- | ---------------------------------------------------- |
| `editor` | `EditorView` | Yes | CodeMirror EditorView instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. |
#### RenderCommentsRequest
***
| Property | Type | Required | Description |
| -------------------- | --------------------- | -------- | -------------------------------------------- |
| `editor` | `EditorView` | Yes | CodeMirror EditorView instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. |
For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation).
#### CodemirrorVeltCommentsConfig
***
Configuration options for the `CodemirrorVeltComments()` extension.
| Property | Type | Required | Description |
| ------------------ | --------- | -------- | ------------------------------------------------------------------------ |
| `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). |
| `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. |
### Ace
#### AddCommentRequest
***
| Property | Type | Required | Description |
| ---------- | -------------------------- | -------- | ---------------------------------------------------- |
| `editor` | `Ace.Editor` | Yes | Ace Editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. |
#### RenderCommentsRequest
***
| Property | Type | Required | Description |
| -------------------- | --------------------- | -------- | -------------------------------------------- |
| `editor` | `Ace.Editor` | Yes | Ace Editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. |
For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation).
#### AceVeltCommentsConfig
***
Configuration options for the `AceVeltComments()` function.
| Property | Type | Required | Description |
| ------------------ | --------- | -------- | ------------------------------------------------------------------------ |
| `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). |
| `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. |
### Quill
#### AddCommentRequest
***
| Property | Type | Required | Description |
| ---------- | -------------------------- | -------- | ---------------------------------------------------- |
| `editor` | `Quill` | Yes | Quill editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. |
#### RenderCommentsRequest
***
| Property | Type | Required | Description |
| -------------------- | --------------------- | -------- | -------------------------------------------- |
| `editor` | `Quill` | Yes | Quill editor instance. |
| `editorId` | `string` | No | Optional editor ID used to scope operations. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. |
For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation).
#### QuillVeltCommentsConfig
***
Configuration options for the `QuillVeltComments` module.
| Property | Type | Required | Description |
| ------------------ | --------- | -------- | ------------------------------------------------------------------------ |
| `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). |
| `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. |
### Messages
#### ENUMs
| Enum Name | Event Type | Description |
| ---------------- | --------------- | -------------------------- |
| `ADD_COMMENT` | `addComment` | Add a new comment |
| `UPDATE_COMMENT` | `updateComment` | Update an existing comment |
| `DELETE_COMMENT` | `deleteComment` | Delete a comment |
#### Comment
***
| Property | Type | Required | Description |
| ----------------------- | -------------------------------------- | -------- | ----------------------------------------------------------------------- |
| `commentId` | `number` | Yes | Unique identifier for the comment pin annotation. Auto generated. |
| `type` | `'text' \| 'voice'` | Yes | This determines the comment content type. Default is 'text'. |
| `commentText` | `string` | Yes | The actual text content of the comment. |
| `commentHtml` | `string` | No | Same comment text but formatted in HTML. |
| `replaceContentHtml` | `string` | No | HTML content to replace the comment text when user accepts the comment. |
| `replaceContentText` | `string` | No | Text content to replace the comment text when user accepts the comment. |
| `commentVoiceUrl` | `string` | No | URL of the voice recording for the comment, if available. |
| `from` | `User` | Yes | The user who created this comment. |
| `to` | `User[]` | No | List of users that were @mentioned in this comment. |
| `lastUpdated` | `Date` | No | Timestamp of when this comment was last updated. Auto generated. |
| `editedAt` | `any` | No | Timestamp of when this comment was edited. Auto generated. |
| `createdAt` | `any` | No | Timestamp of when this comment was created. Auto generated. |
| `isEdited` | `boolean` | No | Whether the comment has been edited. Auto generated. |
| `status` | `'added' \| 'updated'` | Yes | Status of the comment indicating whether it was newly added or updated. |
| `attachments` | `Attachment[]` | Yes | List of attachments associated with the comment. |
| `recorders` | `RecordedData[]` | Yes | List of recorded data associated with the comment. |
| `reactionAnnotationIds` | `string[]` | Yes | List of annotation IDs for reactions to the comment. |
| `reactionAnnotations` | \[`ReactionAnnotation[]`] | No | List of reaction annotations associated with the comment. |
| `taggedUserContacts` | `AutocompleteUserContactReplaceData[]` | Yes | List of users that were @mentioned in this comment with UI metadata. |
| `customList` | `AutocompleteReplaceData[]` | Yes | List of custom list items added to the comment. |
| `isDraft` | `boolean` | Yes | Whether the comment is in draft state. |
#### AddCommentEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `commentId` | `number` | Yes | ID of the comment |
| `comment` | `Comment` | Yes | Comment Object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### UpdateCommentEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `commentId` | `number` | Yes | ID of the comment |
| `comment` | `Comment` | Yes | Comment Object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### DeleteCommentEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `commentId` | `number` | Yes | ID of the comment |
| `comment` | `Comment` | Yes | Comment Object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### AddCommentRequest
***
| Property | Type | Required | Description |
| -------------- | ----------------------------------------------------- | -------- | --------------------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `comment` | `Comment` | Yes | Comment object |
| `assignedTo` | `User` | No | Assigned user |
| `assigned` | `boolean` | No | Whether the comment is assigned |
| `visibility` | [`CommentVisibilityConfig`](#commentvisibilityconfig) | No | Set visibility at comment creation time |
| `options` | `RequestOptions` | No | Request options |
#### UpdateCommentRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `comment` | `Comment` | Yes | Comment object |
| `merge` | `boolean` | No | Merge comments |
| `options` | `RequestOptions` | No | Request options |
#### DeleteCommentRequest
***
| Property | Type | Required | Description |
| ------------------------------ | ---------------- | -------- | ------------------------ |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `skipDeleteThreadConfirmation` | `boolean` | No | Skip delete confirmation |
| `options` | `RequestOptions` | No | Request options |
#### GetCommentRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
### @Mentions
#### ENUMs
| Enum Name | Event Type | Description |
| -------------------------------- | ------------------------------ | ------------------------------------------------------------------ |
| `ASSIGN_USER` | `assignUser` | Assign a user to a comment |
| `SUBSCRIBE_COMMENT_ANNOTATION` | `subscribeCommentAnnotation` | Subscribe to a comment annotation |
| `UNSUBSCRIBE_COMMENT_ANNOTATION` | `unsubscribeCommentAnnotation` | Unsubscribe from a comment annotation |
| `AUTOCOMPLETE_SEARCH` | `autocompleteSearch` | When user starts searching for a contact in the @mentions dropdown |
#### AssignUserRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `assignedTo` | `UserContact` | Yes | User to assign |
| `options` | `RequestOptions` | No | Request options |
#### GetContactListResponse
***
| Property | Type | Required | Description |
| -------------------- | ------------- | -------- | -------------------------------------------------- |
| `organizationUsers` | `User[]` | No | List of users in the organization |
| `folderUsers` | `User[]` | No | List of users added to the folder |
| `documentUsers` | `User[]` | No | List of users added to the document |
| `userGroups` | `UserGroup[]` | No | List of user groups in the organization |
| `updatedContactList` | `User[]` | No | List of contacts updated via updateContactList API |
#### SubscribeCommentAnnotationRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### UnsubscribeCommentAnnotationRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### AutocompleteItem
***
| Property | Type | Required | Description |
| ------------- | -------- | -------- | ------------------------- |
| `id` | `string` | Yes | Unique identifier |
| `name` | `string` | Yes | Name of the item |
| `description` | `string` | No | Optional description |
| `icon` | `object` | No | Optional icon information |
| `icon.url` | `string` | No | URL of the icon |
| `link` | `string` | No | Link associated with item |
#### AutocompleteUserContactReplaceData
***
| Property | Type | Required | Description |
| --------- | -------- | -------- | ----------------------------------------------------------------- |
| `text` | `string` | Yes | The text displayed in the comment that represents the tagged user |
| `userId` | `string` | Yes | The user ID of the tagged user |
| `contact` | `User` | No | The user object of the tagged user |
#### AutocompleteReplaceData
***
| Property | Type | Required | Description |
| -------- | ------------------ | -------- | ----------------------------------------------------------------- |
| `text` | `string` | Yes | The text displayed in the comment that represents the custom item |
| `custom` | `AutocompleteItem` | Yes | The custom item object associated with this text |
#### AutocompleteItem
***
| Property | Type | Required | Description |
| ------------- | -------------------------------- | -------- | -------------------------------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the autocomplete item |
| `name` | `string` | Yes | Name or label of the autocomplete item |
| `description` | `string` | No | Additional description of the autocomplete item |
| `icon` | `{ url?: string, svg?: string }` | No | Icon associated with the autocomplete item (URL or inline SVG) |
| `groupId` | `string` | No | Optional group id to categorize this item |
| `link` | `string` | No | Optional link associated with the autocomplete item |
#### AutocompleteData
***
| Property | Type | Required | Description |
| ------------- | ---------------------------------- | -------- | -------------------------------------------------- |
| `hotkey` | `string` | Yes | The hotkey or trigger for this autocomplete data |
| `description` | `string` | No | Optional description of the autocomplete data |
| `type` | `'custom' \| 'contact' \| 'group'` | Yes | The type of autocomplete data. Default is 'custom' |
| `groups` | `AutocompleteGroup[]` | No | Optional groups used to categorize items |
| `data` | `AutocompleteItem[]` | Yes | An array of AutocompleteItem objects |
#### AutocompleteGroup
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | --------------------- |
| `id` | `string` | Yes | Unique group id |
| `name` | `string` | Yes | Display name of group |
#### AutoCompleteScrollConfig
***
Configuration for virtual scroll behavior in autocomplete dropdown.
| Property | Type | Required | Description |
| ------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `itemSize` | `number` | No | Specifies the fixed height of each item in pixels |
| `minBufferPx` | `number` | No | The minimum amount of content buffer (in pixels) that must be rendered beyond the visible viewport. If the buffer falls below this amount, the viewport will render more items |
| `maxBufferPx` | `number` | No | The maximum amount of content buffer (in pixels) to render when the `minBufferPx` threshold is crossed. The viewport renders items until the buffer reaches this size |
| `templateCacheSize` | `number` | No | Adjusts the size of the view cache. By default, previously created views are cached for reuse; setting this to `0` disables caching, which can be useful if your templates are memory-intensive |
#### AssignUserEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `assignedTo` | `UserContact` | Yes | User being assigned |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
#### SubscribeCommentAnnotationEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### UnsubscribeCommentAnnotationEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### AutocompleteSearchEvent
***
| Property | Type | Required | Description |
| ------------ | -------------------------------------- | -------- | -------------------------------------------------------------------- |
| `event` | `KeyboardEvent \| InputEvent \| Event` | Yes | The triggering event |
| `searchText` | `string` | Yes | The search text entered |
| `type` | `'contact' \| 'custom'` | No | Type of autocomplete search. Whether is the @mentions or custom list |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
#### LinkClickedEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | -------------------------------- |
| `text` | `string` | Yes | The clicked link text |
| `link` | `string` | Yes | The clicked URL |
| `commentAnnotation` | `CommentAnnotation` | Yes | Related comment annotation |
| `commentId` | `number` | Yes | The comment id within the thread |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
### Custom List
#### ENUMs
| Enum Name | Event Type | Description |
| --------------------- | -------------------- | ---------------------------------------------------------------------- |
| `AUTOCOMPLETE_SEARCH` | `autocompleteSearch` | When user starts searching for a list item in the custom list dropdown |
#### AutocompleteSearchEvent
***
| Property | Type | Required | Description |
| ------------ | -------------------------------------- | -------- | -------------------------------------------------------------------- |
| `event` | `KeyboardEvent \| InputEvent \| Event` | Yes | The triggering event |
| `searchText` | `string` | Yes | The search text entered |
| `type` | `'contact' \| 'custom'` | No | Type of autocomplete search. Whether is the @mentions or custom list |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
### Attachments
#### ENUMs
| Enum Name | Event Type | Description |
| ----------------------------- | --------------------------- | ---------------------------------------------------- |
| `ADD_ATTACHMENT` | `addAttachment` | Add an attachment to a comment |
| `DELETE_ATTACHMENT` | `deleteAttachment` | Delete an attachment from a comment |
| `ATTACHMENT_DOWNLOAD_CLICKED` | `attachmentDownloadClicked` | Triggered when attachment download button is clicked |
#### Attachment
***
| Property | Type | Required | Description |
| -------------------------- | -------- | -------- | ---------------------------------------------------- |
| `attachmentId` | `number` | Yes | Unique identifier for the attachment. Auto-generated |
| `name` | `string` | No | File name of the attachment |
| `bucketPath` | `string` | No | Path to the file in storage bucket |
| `size` | `number` | No | File size of the attachment |
| `type` | `string` | No | File type of the attachment |
| `url` | `string` | No | Download URL of the attachment |
| `thumbnail` | `string` | No | Thumbnail image in base64 format |
| `thumbnailWithPlayIconUrl` | `string` | No | URL of the thumbnail with a play icon overlay |
| `metadata` | `any` | No | Additional metadata of the attachment |
| `mimeType` | `any` | No | MIME type of the attachment |
#### AddAttachmentRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `files` | `File[]` | Yes | Array of files |
| `options` | `RequestOptions` | No | Request options |
#### DeleteAttachmentRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `attachmentId` | `number` | Yes | ID of the attachment |
| `options` | `RequestOptions` | No | Request options |
#### GetAttachmentRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `options` | `RequestOptions` | No | Request options |
#### UploadFileData
***
Configuration object for programmatically adding file attachments to the comment composer.
| Property | Type | Required | Description |
| ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `files` | `File[]` | Yes | Array of File objects to attach to the comment composer |
| `annotationId` | `string` | No | ID of the target comment annotation. Use this to add attachments to an existing comment thread |
| `targetElementId` | `string` | No | ID of the target element where the comment composer is attached. Use this to add attachments to a specific element |
#### AddAttachmentResponse
***
| Property | Type | Required | Description |
| ---------------- | ------------ | -------- | ----------------- |
| `valid` | `boolean` | Yes | Validity status |
| `file` | `File` | No | File object |
| `maxAllowedSize` | `number` | Yes | Max allowed size |
| `error` | `string` | No | Error message |
| `attachment` | `Attachment` | No | Attachment object |
#### DeleteAttachmentResolverRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------------------- | -------- | --------------------------------------------------------------------------------- |
| `attachmentId` | `number` | Yes | ID of the attachment |
| `metadata` | `AttachmentResolverMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. |
| `event` | `ResolverActions` | No | Event that triggered the delete |
#### SaveAttachmentResolverRequest
***
| Property | Type | Required | Description |
| ------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------- |
| `attachment` | `ResolverAttachment` | Yes | Attachment object to save |
| `metadata` | `AttachmentResolverMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. |
| `event` | `ResolverActions` | No | Event that triggered the save |
#### AddAttachmentEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------------- | -------- | ----------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `attachments` | `AddAttachmentResponse[]` | Yes | Array of attachment responses |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### AddAttachmentResponse
***
| Property | Type | Required | Description |
| ---------------- | ------------ | -------- | --------------------------- |
| `valid` | `boolean` | Yes | Whether attachment is valid |
| `file` | `File` | No | File object |
| `maxAllowedSize` | `number` | Yes | Maximum allowed file size |
| `error` | `string` | No | Error message if invalid |
| `attachment` | `Attachment` | No | Attachment object |
#### DeleteAttachmentEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `attachment` | `Attachment` | Yes | Attachment Object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### AttachmentDownloadClickedEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------------- |
| `annotationId` | `string` | Yes | ID of the comment annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Full comment annotation object |
| `attachment` | `Attachment` | Yes | The attachment that was clicked |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
### Reactions
#### ENUMs
| Enum Name | Event Type | Description |
| ----------------- | ---------------- | -------------------------------- |
| `ADD_REACTION` | `addReaction` | Add a reaction to a comment |
| `DELETE_REACTION` | `deleteReaction` | Delete a reaction from a comment |
| `TOGGLE_REACTION` | `toggleReaction` | Toggle a reaction on a comment |
#### AddReactionRequest
***
| Property | Type | Required | Description |
| -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction |
| `options` | `RequestOptions` | No | Request options |
#### DeleteReactionRequest
***
| Property | Type | Required | Description |
| -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction |
| `options` | `RequestOptions` | No | Request options |
#### ToggleReactionRequest
***
| Property | Type | Required | Description |
| -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction |
| `options` | `RequestOptions` | No | Request options |
#### ReactionItem
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ------------------------- |
| `url` | `string` | No | URL of the reaction image |
| `emoji` | `string` | No | Emoji character |
#### GetReactionResolverRequest
***
| Property | Type | Required | Description |
| ----------------------- | ---------- | -------- | ------------------------------------------------------------------- |
| `organizationId` | `string` | Yes | ID of the organization to fetch reactions from |
| `reactionAnnotationIds` | `string[]` | No | Array of reaction annotation IDs to fetch reactions from |
| `documentIds` | `string[]` | No | Array of document IDs to fetch reactions from |
| `folderId` | `string` | No | ID of the folder to fetch reactions from |
| `allDocuments` | `boolean` | No | Whether to get reactions from all documents within the given folder |
#### SaveReactionResolverRequest
***
| Property | Type | Required | Description |
| -------------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
| `reactionAnnotation` | `{ [key: string]: PartialReactionAnnotation }` | Yes | Map of reaction annotation id to reaction annotation data |
| `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. |
| `event` | `ResolverActions` | No | Event name that caused the save request |
#### DeleteReactionResolverRequest
***
| Property | Type | Required | Description |
| ---------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- |
| `reactionAnnotationId` | `string` | Yes | ID of the reaction annotation |
| `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. |
| `event` | `ResolverActions` | No | Event name that caused the delete request |
#### AddReactionEvent
***
| Property | Type | Required | Description |
| ------------------- | -------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `commentId` | `number` | Yes | ID of the comment |
| `reaction` | `ReactionAnnotation` | Yes | Reaction Object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### DeleteReactionEvent
***
| Property | Type | Required | Description |
| ------------------- | -------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `commentId` | `number` | Yes | ID of the comment |
| `reaction` | `ReactionAnnotation` | Yes | Reaction Object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### ToggleReactionEvent
***
| Property | Type | Required | Description |
| ------------------- | -------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `commentId` | `number` | Yes | ID of the comment |
| `reaction` | `ReactionAnnotation` | Yes | Reaction Object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### ReactionPinType
***
Display location for pinned reactions.
```typescript theme={null}
type ReactionPinType = 'timeline' | 'comment' | 'standalone';
```
* `'timeline'`: Pin reaction to timeline view
* `'comment'`: Pin reaction to comment context
* `'standalone'`: Display reaction independently
### Status & Priority
#### ENUMs
| Enum Name | Event Type | Description |
| ---------------------------- | -------------------------- | -------------------------------- |
| `UPDATE_STATUS` | `updateStatus` | Update the status of a comment |
| `RESOLVE_COMMENT` | `resolveComment` | Resolve a comment |
| `UPDATE_PRIORITY` | `updatePriority` | Update the priority of a comment |
| `APPROVE_COMMENT_ANNOTATION` | `approveCommentAnnotation` | Approve a comment annotation |
| `ACCEPT_COMMENT_ANNOTATION` | `acceptCommentAnnotation` | Accept a comment annotation |
| `REJECT_COMMENT_ANNOTATION` | `rejectCommentAnnotation` | Reject a comment annotation |
#### UpdateStatusRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `status` | `CustomStatus` | Yes | Status value |
| `options` | `RequestOptions` | No | Request options |
#### ResolveCommentAnnotationRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### UpdatePriorityRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `priority` | `CustomPriority` | No | Priority object |
| `options` | `RequestOptions` | No | Request options |
#### ApproveCommentAnnotationRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### AcceptCommentAnnotationRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### RejectCommentAnnotationRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### CustomPriority
***
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the custom priority |
| `color` | `string` | Yes | Color associated with the custom priority |
| `name` | `string` | Yes | Name or label of the custom priority |
| `lightColor` | `string` | No | Light color variant for the custom priority |
#### CustomStatus
***
| Property | Type | Required | Description |
| ------------ | ------------ | -------- | -------------------------------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the custom status |
| `color` | `string` | Yes | Text and comment pin color associated with the custom status |
| `name` | `string` | Yes | Name or label of the custom status |
| `type` | `StatusType` | Yes | Type of the status (`default`, `ongoing`, or `terminal`) |
| `lightColor` | `string` | No | Background color on the status indicator for the custom status |
| `iconUrl` | `string` | No | URL to an icon image for the custom status |
#### UpdateStatusEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `newStatus` | `CustomStatus` | Yes | New status object |
| `oldStatus` | `CustomStatus` | Yes | Previous status object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### ResolveCommentEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### UpdatePriorityEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `newPriority` | `CustomPriority` | No | New Priority object |
| `oldPriority` | `CustomPriority` | No | Previous Priority object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### ApproveCommentAnnotationEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### AcceptCommentAnnotationEvent
***
| Property | Type | Required | Description |
| -------------------- | ------------------- | -------- | ----------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
| `actionUser` | `User` | Yes | User who performed the action |
| `replaceContentHtml` | `string` | No | HTML content to replace with |
| `replaceContentText` | `string` | No | Text content to replace with |
#### RejectCommentAnnotationEvent
***
| Property | Type | Required | Description |
| -------------------- | ------------------- | -------- | ----------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
| `actionUser` | `User` | Yes | User who performed the action |
| `replaceContentHtml` | `string` | No | HTML content to replace with |
| `replaceContentText` | `string` | No | Text content to replace with |
### Comment Dialog Primitives
Types for the 79 primitive components used to build custom comment dialog interfaces. See [Comment Dialog Primitives Overview](/ui-customization/features/async/comments/comment-dialog-primitives/overview) for usage examples and [API Methods](/api-reference/sdk/api/api-methods#comment-dialog-primitives) for component documentation.
#### CommentDialogCommonProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#common-inputs)
Base props inherited by all Comment Dialog primitive components.
| Property | Type | Required | Description |
| -------------------------- | --------- | -------- | -------------------------------------------------- |
| `annotationId` | `string` | No | Annotation ID (required in standalone mode) |
| `defaultCondition` | `boolean` | No | When false, always shows component (default: true) |
| `inlineCommentSectionMode` | `boolean` | No | Enables inline comment section mode |
| `commentPinSelected` | `boolean` | No | Comment pin selection state |
| `fullExpanded` | `boolean` | No | Full expansion state |
#### CommentDialogContextWrapperProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcontextwrapper)
Props for the VeltCommentDialogContextWrapper component.
| Property | Type | Required | Description |
| -------------------- | --------- | -------- | ------------------------------------ |
| `annotationId` | `string` | Yes | Annotation ID for children |
| `commentId` | `string` | No | Comment ID for children |
| `attachmentId` | `string` | No | Attachment ID for children |
| `commentPinSelected` | `boolean` | No | Selection state for children |
| `[key: string]` | `any` | No | Custom attributes passed via context |
#### ThreadCardProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogthreadcard)
Props for VeltCommentDialogThreadCard with priority-based comment lookup.
| Property | Type | Required | Description |
| -------------- | -------- | -------- | ------------------------------------ |
| `commentObj` | `object` | No | Direct comment object (Priority 1) |
| `commentId` | `number` | No | Comment ID for lookup (Priority 2) |
| `commentIndex` | `number` | No | Index in comments array (Priority 3) |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### CommentIndexProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogthreadcardavatar)
Props for thread card sub-components that require a comment index.
| Property | Type | Required | Description |
| -------------- | -------- | -------- | ------------------------- |
| `commentIndex` | `number` | No | Index of comment in array |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### ComposerProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcomposer)
Props for VeltCommentDialogComposer with placeholder and edit mode options.
| Property | Type | Required | Description |
| ------------------------- | --------- | -------- | ----------------------------------------------------------------- |
| `placeholder` | `string` | No | Primary placeholder (Priority 1) |
| `commentPlaceholder` | `string` | No | Placeholder for new comment |
| `replyPlaceholder` | `string` | No | Placeholder for reply |
| `editPlaceholder` | `string` | No | Placeholder for edit mode |
| `editMode` | `boolean` | No | Enables edit mode |
| `commentObj` | `object` | No | Comment object for edit mode |
| `commentIndex` | `number` | No | Index of comment being edited |
| `targetComposerElementId` | `string` | No | Unique identifier for programmatic submission via submitComment() |
| `context` | `object` | No | Custom context data to attach to comment |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### ComposerInputProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcomposerinput)
Props for VeltCommentDialogComposerInput.
| Property | Type | Required | Description |
| ------------- | -------- | -------- | ---------------------- |
| `placeholder` | `string` | No | Input placeholder text |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### StatusDropdownItemProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogstatusdropdowncontentitem)
Props for VeltCommentDialogStatusDropdownContentItem with priority-based status lookup.
| Property | Type | Required | Description |
| ------------- | -------- | -------- | ------------------------------------ |
| `statusObj` | `object` | No | Direct status object (Priority 1) |
| `statusId` | `string` | No | Status ID for lookup (Priority 2) |
| `statusIndex` | `number` | No | Index in statuses array (Priority 3) |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### PriorityDropdownItemProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogprioritydropdowncontentitem)
Props for VeltCommentDialogPriorityDropdownContentItem with priority-based priority lookup.
| Property | Type | Required | Description |
| --------------- | -------- | -------- | -------------------------------------- |
| `priorityObj` | `object` | No | Direct priority object (Priority 1) |
| `priorityId` | `string` | No | Priority ID for lookup (Priority 2) |
| `priorityIndex` | `number` | No | Index in priorities array (Priority 3) |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### OptionsDropdownProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogoptionsdropdown)
Props for VeltCommentDialogOptionsDropdown with feature enable flags.
| Property | Type | Required | Description |
| ------------------------------ | --------- | -------- | -------------------------------- |
| `commentIndex` | `number` | No | Index of comment for options |
| `enableAssignment` | `boolean` | No | Enable assignment option |
| `allowAssignment` | `boolean` | No | V4 alias for enableAssignment |
| `enableEdit` | `boolean` | No | Enable edit option |
| `allowEdit` | `boolean` | No | V4 alias for enableEdit |
| `enableNotifications` | `boolean` | No | Enable notifications option |
| `allowNotifications` | `boolean` | No | V4 alias for enableNotifications |
| `allowToggleNotification` | `boolean` | No | V4 alias for enableNotifications |
| `enablePrivateMode` | `boolean` | No | Enable private mode option |
| `allowPrivateMode` | `boolean` | No | V4 alias for enablePrivateMode |
| `allowChangeCommentAccessMode` | `boolean` | No | V4 alias for enablePrivateMode |
| `enableMarkAsRead` | `boolean` | No | Enable mark as read option |
| `allowMarkAsRead` | `boolean` | No | V4 alias for enableMarkAsRead |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### CustomAnnotationItemProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogcustomannotationdropdowntriggerlistitem)
Props for custom annotation dropdown items.
| Property | Type | Required | Description |
| -------- | -------- | -------- | ---------------- |
| `item` | `object` | No | Item data object |
| `index` | `number` | No | Item index |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### ReplyAvatarsListItemProps
## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltcommentdialogreplyavatarslistitem)
Props for VeltCommentDialogReplyAvatarsListItem.
| Property | Type | Required | Description |
| -------- | --------------- | -------- | --------------------- |
| `user` | [`User`](#user) | Yes | User data object |
| `index` | `number` | Yes | Index of user in list |
Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops).
#### IVeltCommentDialogThreadCardReactionPinProps
***
Props for VeltCommentDialogThreadCard.ReactionPin to display specific pinned reactions.
| Property | Type | Required | Description |
| ------------ | -------- | -------- | --------------------------------------------- |
| `reactionId` | `string` | No | Unique reaction identifier to pin and display |
#### IVeltCommentDialogThreadCardReactionsProps
***
Props for VeltCommentDialogThreadCard.Reactions to filter displayed reactions.
| Property | Type | Required | Description |
| -------------------- | ---------- | -------- | ------------------------------------ |
| `excludeReactionIds` | `string[]` | No | Reaction IDs to exclude from display |
#### IVeltCommentDialogThreadCardReactionToolProps
***
Props for VeltCommentDialogThreadCard.ReactionTool to filter reaction picker options.
| Property | Type | Required | Description |
| -------------------- | ---------- | -------- | ----------------------------------- |
| `excludeReactionIds` | `string[]` | No | Reaction IDs to exclude from picker |
### Recordings
#### ENUMs
| Enum Name | Event Type | Description |
| ------------------ | ----------------- | --------------------------------- |
| `DELETE_RECORDING` | `deleteRecording` | Delete a recording from a comment |
#### GetRecordingRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `options` | `RequestOptions` | No | Request options |
#### DeleteRecordingRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentId` | `number` | Yes | ID of the comment |
| `recorderId` | `string` | Yes | ID of the recorder |
| `options` | `RequestOptions` | No | Request options |
#### DeleteRecordingEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `commentId` | `number` | Yes | ID of the comment |
| `recording` | `RecordedData` | Yes | Recording data |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
### Deep Links
#### ENUMs
| Enum Name | Event Type | Description |
| ----------- | ---------- | ----------------------------- |
| `COPY_LINK` | `copyLink` | Copy a deep link to a comment |
#### GetLinkRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### CopyLinkRequest
***
| Property | Type | Required | Description |
| -------------- | ---------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `options` | `RequestOptions` | No | Request options |
#### CopyLinkEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `link` | `string` | Yes | Copied link |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### GetLinkResponse
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `link` | `string \| null` | Yes | Generated link |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
### Access
#### ENUMs
| Enum Name | Event Type | Description |
| --------------- | -------------- | ------------------------------------ |
| `UPDATE_ACCESS` | `updateAccess` | Update access settings for a comment |
#### UpdateAccessRequest
***
| Property | Type | Required | Description |
| -------------- | ------------------- | -------- | -------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `accessMode` | `CommentAccessMode` | Yes | Access mode |
| `options` | `RequestOptions` | No | Request options |
#### UpdateAccessEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `newAccessMode` | `CommentAccessMode` | No | New access mode |
| `oldAccessMode` | `CommentAccessMode` | No | Previous access mode |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### UserPermissionAccessRole
***
Type: `'editor' | 'viewer'`
* editor: Write access
* viewer: Read-only access
#### UserPermissionAccessRoleResult
***
Type: `'does_not_exist' | 'permission_denied' | 'something_went_wrong'`
Error codes returned when permission resolution fails:
* `does_not_exist`: The requested resource (organization, folder, or document) does not exist
* `permission_denied`: The user does not have permission to access the requested resource
* `something_went_wrong`: An unexpected error occurred during permission resolution
#### GetUserPermissionsRequest
***
| Property | Type | Required | Description |
| ---------------- | ---------- | -------- | -------------------------------------------- |
| `organizationId` | `string` | No | Organization to scope the permission lookup. |
| `folderIds` | `string[]` | No | Folder IDs to include in the lookup. |
| `documentIds` | `string[]` | No | Document IDs to include in the lookup. |
#### UserPermissionInfo
***
| Property | Type | Required | Description |
| ------------ | -------------------------------- | -------- | ---------------------------------------------------------------- |
| `accessRole` | `UserPermissionAccessRole` | No | Access role for the resource. |
| `expiresAt` | `number` | No | Expiry (Unix ms) for temporary access, if applicable. |
| `error` | `string` | No | Error message if permission resolution failed. |
| `errorCode` | `UserPermissionAccessRoleResult` | No | Error code indicating the type of permission resolution failure. |
| `context` | `{ accessFields?: string[] }` | No | Context access information with accessFields array. |
#### GetUserPermissionsResponse
***
Map of user IDs to their resolved permissions across organization, folders, and documents.
| Property | Type | Required | Description |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------- |
| `[userId: string]` | `{ folders?: Record; organization?: Record; documents?: Record; }` | Yes | Permissions for a user, keyed by resource scope and ID. |
### UI
#### AssignToType
***
UI mode for assignment functionality.
```typescript theme={null}
type AssignToType = 'dropdown' | 'checkbox';
```
* `'dropdown'`: Default assignment menu with team member selection
* `'checkbox'`: Quick self-assignment toggle mode
#### ENUMs
| Enum Name | Event Type | Description |
| ------------------------ | ---------------------- | -------------------------------------------------------------------- |
| `COMPOSER_CLICKED` | `composerClicked` | Triggered when comment composer is clicked |
| `COMMENT_PIN_CLICKED` | `commentPinClicked` | Triggered when a comment pin is clicked |
| `COMPOSER_TEXT_CHANGE` | `composerTextChange` | Triggered when text changes in a comment composer |
| `COMMENT_TOOL_CLICKED` | `commentToolClicked` | Past-tense alias for `commentToolClick` |
| `SIDEBAR_BUTTON_CLICKED` | `sidebarButtonClicked` | Past-tense alias for `sidebarButtonClick` |
| `COMMENT_SAVE_TRIGGERED` | `commentSaveTriggered` | Triggered immediately when save button is clicked, before async save |
#### ComposerClickedEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | --------------------------------------------------------------------------------------- |
| `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object. This is `undefined` if it's a new comment annotation object. |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
#### ComposerTextChangeEvent
***
| Property | Type | Required | Description |
| ------------------------- | ----------------------------------------- | -------- | ---------------------------------------------------------------- |
| `text` | `string` | Yes | Current text content in the composer |
| `annotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full draft annotation with attachments, recordings, tagged users |
| `targetComposerElementId` | `string` | Yes | Unique identifier of the composer that triggered the event |
| `metadata` | [`VeltEventMetadata`](#velteventmetadata) | No | Event metadata including document and location context |
#### CommentPinClickedEvent
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------- |
| `annotationId` | `string` | Yes | ID of the annotation |
| `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
#### CommentToolClickedEvent
***
| Property | Type | Required | Description |
| ----------------- | -------------------------------- | -------- | ------------------------------------------------ |
| `context` | `{ [key: string]: any } \| null` | No | Custom context data when comment tool is clicked |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
| `targetElementId` | `string` | No | ID of the target element if available |
#### SidebarButtonClickedEvent
***
| Property | Type | Required | Description |
| ---------- | ------------------- | -------- | -------------- |
| `metadata` | `VeltEventMetadata` | No | Event metadata |
### Comment Sidebar
#### CommentCountType
***
Union type for specifying comment count display mode.
```typescript theme={null}
type CommentCountType = 'total' | 'unread';
```
* `'total'`: Shows total count of all comments
* `'unread'`: Shows count of unread comments only
#### SidebarFilterCriteria
***
Filter criteria for minimal filter dropdown in sidebar.
```typescript theme={null}
type SidebarFilterCriteria = 'status' | 'priority' | 'category' | 'people' | 'assignedToMe';
```
Available filter criteria for sidebar filtering.
#### ENUMs
| Enum Name | Event Type | Description |
| ----------------------------- | -------------------------- | --------------------------------------------------- |
| `COMMENT_SIDEBAR_DATA_INIT` | `commentSidebarDataInit` | Triggered when comment sidebar data is first loaded |
| `COMMENT_SIDEBAR_DATA_UPDATE` | `commentSidebarDataUpdate` | Triggered when comment sidebar data is updated |
#### CommentStatus
***
| Property | Type | Required | Description |
| ------------ | -------- | -------- | -------------------------------------------- |
| `color` | `string` | Yes | Primary color for the status. |
| `id` | `string` | Yes | Unique identifier for the status. |
| `lightColor` | `string` | Yes | Light variant of the status color. |
| `name` | `string` | Yes | Display name of the status. |
| `svg` | `string` | Yes | SVG icon for the status. |
| `type` | `string` | No | Optional type classification for the status. |
#### CommentPriority
***
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------ |
| `color` | `string` | Yes | Primary color for the priority. |
| `id` | `string` | Yes | Unique identifier for the priority. |
| `lightColor` | `string` | Yes | Light variant of the priority color. |
| `name` | `string` | Yes | Display name of the priority. |
#### CustomFilter
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | --------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the custom filter |
| `color` | `string` | Yes | Color associated with the custom filter |
| `name` | `string` | Yes | Name or label of the custom filter |
#### CustomCategory
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ----------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the custom category |
| `color` | `string` | Yes | Color associated with the custom category |
| `name` | `string` | Yes | Name or label of the custom category |
#### CommentSidebarDataInitEvent
***
| Property | Type | Required | Description |
| ----------------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `buttonContext` | `VeltButtonContext` | Yes | Button context |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
| `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object |
| `comment` | `Comment` | No | Comment object |
| `index` | `number` | No | Index value |
| `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations |
| `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations |
| `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts |
| `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used. |
#### CommentSidebarDataUpdateEvent
***
| Property | Type | Required | Description |
| ----------------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `buttonContext` | `VeltButtonContext` | Yes | Button context |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
| `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object |
| `comment` | `Comment` | No | Comment object |
| `index` | `number` | No | Index value |
| `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations |
| `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations |
| `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts |
| `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used. |
#### CommentSidebarFilterConfig
***
| Property | Type | Required | Description |
| --------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `location` | `FilterTypeConfig` | No | Configuration for the location filter type. |
| `document` | `FilterTypeConfig` | No | Configuration for the document filter type. Only use it if you are using multiple documents or folders |
| `people` | `FilterTypeConfig` | No | Configuration for the author filter type. |
| `tagged` | `FilterTypeConfig` | No | Configuration for the tagged/mentioned filter type. |
| `assigned` | `FilterTypeConfig` | No | Configuration for the assigned filter type. |
| `involved` | `FilterTypeConfig` | No | Configuration for the involved filter type (author, mentioned, assigned). |
| `priority` | `FilterTypeConfig` | No | Configuration for the priority filter type. |
| `category` | `FilterTypeConfig` | No | Configuration for the category filter type. |
| `commentType` | `FilterTypeConfig` | No | Configuration for the comment type filter. |
| `version` | `FilterTypeConfig` | No | Configuration for the version filter type. |
| `status` | `FilterTypeConfig` | No | Configuration for the status filter type. |
| `[key: string]` | `FilterTypeConfig \| undefined` | No | Custom filter type configurations. |
#### FilterTypeConfig
***
| Property | Type | Required | Description |
| ---------------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `name` | `string` | No | The name of the filter type |
| `enable` | `boolean` | No | Enables or disables the filter type |
| `multiSelection` | `boolean` | No | Allows multiple selections if set to true |
| `enableGrouping` | `boolean` | No | Enables grouping within the filter type if set to true |
| `placeholder` | `string` | No | The placeholder text for the filter type. Used when `filterOptionLayout` is set to `dropdown` |
| `id` | `string` | No | The unique identifier for the filter type |
| `type` | `'custom' \| 'system'` | No | The type of filter - custom or system |
| `options` | `FilterOption[]` | No | Array of filter options available for this filter type |
#### CommentSidebarGroupConfig
***
| Property | Type | Required | Description |
| --------------- | ----------------------------------------------------------- | -------- | ---------------------------- |
| `enable` | `boolean` | No | Enables or disables grouping |
| `name` | `string` | No | The name of the group |
| `[key: string]` | `{ id?: string, name?: string }[] \| string[] \| undefined` | No | Custom filter configurations |
#### CommentSidebarFilters
***
| Property | Type | Required | Description |
| ---------- | -------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `location` | `{id: string}[]` | No | Filter by location Ids |
| `document` | `{id: string}[]` | No | Filter by document Ids |
| `people` | `{userId: string}[]` | No | Filter by author of comment annotation |
| `tagged` | `{userId: string}[]` | No | Filter by users who were tagged/mentioned in the comment |
| `assigned` | `{userId: string}[]` | No | Filter by users who were assigned to the comment annotation |
| `involved` | `{userId: string}[]` | No | Filter by users who are involved in the comment annotation (author, mentioned, assigned) |
| `priority` | `string[]` | No | Filter by priority ids |
| `status` | `string[]` | No | Filter by status ids |
| `category` | `string[]` | No | Filter by category ids |
| `version` | `{id: string}[]` | No | Filter by version Ids |
#### CommentSidebarData
***
| Property | Type | Required | Description |
| ------------- | --------------------- | -------- | ----------------------------------------------- |
| `groupId` | `string` | No | ID of the group. Defaults to 'others' |
| `groupName` | `string` | No | Name of the group. Defaults to 'Others' |
| `isExpanded` | `boolean` | No | Whether the group is expanded. Defaults to true |
| `annotations` | `CommentAnnotation[]` | Yes | List of CommentAnnotations in the group |
#### Options
***
| Property | Type | Required | Description |
| ---------- | --------- | -------- | ------------------------------------------- |
| `grouping` | `boolean` | No | Whether to group the data. Defaults to true |
#### CustomFilterOption
***
| Property | Type | Required | Description |
| ---------- | --------- | -------- | ----------------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the filter option |
| `name` | `string` | Yes | Display name for the filter option |
| `selected` | `boolean` | Yes | Whether the filter option is currently selected |
#### CustomFilters
***
| Property | Type | Required | Description |
| --------------- | ---------------------- | -------- | ------------------------------------------------- |
| `[key: string]` | `CustomFilterOption[]` | No | Custom filter configurations mapped by filter key |
#### FilterOption
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | --------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the filter option |
| `name` | `string` | Yes | Display name for the filter option |
#### CustomFilter
***
| Property | Type | Required | Description |
| -------- | ------ | -------- | ---------------------------------------- |
| `id` | string | Yes | Unique identifier for the custom filter. |
| `color` | string | Yes | Color associated with the custom filter. |
| `name` | string | Yes | Name or label of the custom filter. |
#### CustomPriority
***
| Property | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------------- |
| `id` | string | Yes | Unique identifier for the custom priority. |
| `color` | string | Yes | Color associated with the custom priority. |
| `name` | string | Yes | Name or label of the custom priority. |
| `lightColor` | string | No | Light color variant for the custom priority. |
#### CustomStatus
***
| Property | Type | Required | Description |
| ------------ | ---------- | -------- | --------------------------------------------------------- |
| `id` | string | Yes | Unique identifier for the custom status. |
| `color` | string | Yes | Color associated with the custom status. |
| `name` | string | Yes | Name or label of the custom status. |
| `type` | StatusType | Yes | Type of the status (`default`, `ongoing`, or `terminal`). |
| `lightColor` | string | No | Light color for the custom status. |
| `iconUrl` | string | No | URL to an icon image for the custom status. |
#### CustomCategory
***
| Property | Type | Required | Description |
| -------- | ------ | -------- | ------------------------------------------ |
| `id` | string | Yes | Unique identifier for the custom category. |
| `color` | string | Yes | Color associated with the custom category. |
| `name` | string | Yes | Name or label of the custom category. |
### Component Props
#### VeltCommentsProps
***
| Property | Type | Required | Description |
| -------------- | ------------------------------- | -------- | ------------------------------------------------------ |
| `assignToType` | [`AssignToType`](#assigntotype) | No | Assignment UI mode: 'dropdown' (default) or 'checkbox' |
#### VeltCommentToolProps
***
| Property | Type | Required | Description |
| --------------------------- | --------- | -------- | -------------------------------------------- |
| `contextInPageModeComposer` | `boolean` | No | Enable passing context to page mode composer |
| `context` | `any` | No | Context data to pass when sidebar opens |
#### VeltCommentComposerProps
***
| Property | Type | Required | Description |
| ------------------------- | --------- | -------- | ----------------------------------------------------------------- |
| `context` | `any` | No | Custom context data for the comment composer |
| `locationId` | `string` | No | Location identifier for the comment |
| `documentId` | `string` | No | Document identifier for the comment |
| `folderId` | `string` | No | Folder identifier for the comment |
| `placeholder` | `string` | No | Custom placeholder text for composer input |
| `targetComposerElementId` | `string` | No | Unique identifier for programmatic submission via submitComment() |
| `readOnly` | `boolean` | No | Enable read-only mode for composer |
#### VeltCommentsSidebarProps
***
| Property | Type | Required | Description |
| --------------------------- | --------- | -------- | --------------------------------------------------------------------------------------- |
| `openAnnotationInFocusMode` | `boolean` | No | Opens annotation in focus mode when enabled. Requires `focusedThreadMode` to be enabled |
| `commentPlaceholder` | `string` | No | Custom placeholder text for comment input field |
| `replyPlaceholder` | `string` | No | Custom placeholder text for reply input field |
| `pageModePlaceholder` | `string` | No | Custom placeholder text for page mode input |
#### VeltInlineCommentsSectionProps
***
| Property | Type | Required | Description |
| --------------------- | --------- | -------- | ------------------------------------------------- |
| `commentPlaceholder` | `string` | No | Custom placeholder text for comment input field |
| `replyPlaceholder` | `string` | No | Custom placeholder text for reply input field |
| `composerPlaceholder` | `string` | No | Custom placeholder text for composer input field |
| `readOnly` | `boolean` | No | Enable read-only mode for inline comments section |
# Recorder
| Enum Name | Event Type | Description |
| -------------------------- | ------------------------ | ---------------------------------------------------------- |
| `TRANSCRIPTION_DONE` | `transcriptionDone` | Triggered when a transcription is generated and ready |
| `RECORDING_DONE` | `recordingDone` | Triggered when a recording is completed |
| `RECORDING_DELETE` | `deleteRecording` | Triggered when a recording is deleted |
| `RECORDING_EDIT_DONE` | `recordingEditDone` | Triggered when a recording is edited and saved |
| `RECORDING_SAVE_INITIATED` | `recordingSaveInitiated` | Triggered when a recording saved is initiated |
| `ERROR` | `error` | Triggered when an error occurs during recording operations |
### Recorder Data
#### RecorderRequestQuery
***
| Property | Type | Required | Description |
| ------------- | ---------- | -------- | ------------------------------ |
| `recorderIds` | `string[]` | Yes | Array of recorder IDs to query |
#### DeleteRecordingsRequest
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ---------------------------------------------------------- |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording |
#### GetRecordingDataResponse
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ---------------------------------------------------------- |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording |
### DeleteRecordingsResponse
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ---------------------------------------------------------- |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording |
### Recorder Configuration
#### RecorderQualityConstraints
***
| Property | Type | Required | Description |
| -------- | ----------------------------------- | -------- | ------------------------------------------------------------- |
| `safari` | `RecorderQualityConstraintsOptions` | No | Constraints specific to the Safari browser. |
| `other` | `RecorderQualityConstraintsOptions` | No | Constraints for other browsers (e.g., Chrome, Firefox, Edge). |
#### RecorderEncodingOptions
***
| Property | Type | Required | Description |
| -------- | ---------------------- | -------- | ------------------------------------------------------------------ |
| `safari` | `MediaRecorderOptions` | No | Encoding options specific to the Safari browser. |
| `other` | `MediaRecorderOptions` | No | Encoding options for other browsers (e.g., Chrome, Firefox, Edge). |
#### RecordingDoneEvent
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ------------------------------------------------ |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording |
#### RecordingDeleteEvent
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ------------------------------------------------ |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording |
#### RecordingEditDoneEvent
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ------------------------------------------------ |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording |
#### RecordingSaveInitiatedEvent
***
| Property | Type | Required | Description |
| -------------- | -------------------- | -------- | ---------------------------------------------------------------------------- |
| `annotationId` | `string` | No | ID of the annotation. This property is only available when `type` is 'edit'. |
| `message` | `string` | Yes | A descriptive message about the save initiation. |
| `type` | `'edit' \| 'record'` | Yes | Specifies whether the save was initiated for an 'edit' or a new 'recording'. |
#### RecordingStartedEvent
***
| Property | Type | Required | Description |
| -------- | -------------------------------- | -------- | ----------------------------------- |
| `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that started. |
#### RecordingPausedEvent
***
| Property | Type | Required | Description |
| -------- | -------------------------------- | -------- | -------------------------------------- |
| `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was paused. |
#### RecordingResumedEvent
***
| Property | Type | Required | Description |
| -------- | -------------------------------- | -------- | --------------------------------------- |
| `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was resumed. |
#### RecordingCancelledEvent
***
| Property | Type | Required | Description |
| -------- | -------------------------------- | -------- | ----------------------------------------- |
| `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was cancelled. |
#### RecordingStoppedEvent
***
| Property | Type | Required | Description |
| -------- | -------------------------------- | -------- | --------------------------------------- |
| `type` | `'audio' \| 'video' \| 'screen'` | Yes | The type of recording that was stopped. |
#### TranscriptionDoneEvent
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ------------------------------------------------ |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording |
#### RecordingErrorEvent
***
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------------------------------------------------------- |
| `type` | `string` | Yes | The type of error that occurred. eg: `editFailed`, `recordingFailed`, `transcriptionFailed` |
| `message` | `string` | Yes | A descriptive message about the error. |
| `recorderId` | `string` | No | ID of the recorder, if the error is specific to one. |
#### RecorderConfig
***
| Property | Type | Required | Description |
| ----------------- | -------------------------------------------------------- | -------- | ------------------------------ |
| `type` | `{ audio?: boolean, video?: boolean, screen?: boolean }` | Yes | Types of media to be recorded |
| `recorderOptions` | `MediaRecorderOptions` | No | Options for the media recorder |
#### RecordedData
***
| Property | Type | Required | Description |
| -------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------- |
| `id` | `string` | Yes | Annotation ID of recorder annotation |
| `tag` | `string` | Yes | Recorder player tag containing recorder annotation id which can be added anywhere on the DOM |
| `type` | `string` | Yes | Type of recorded data. Possible values are 'audio', 'video', and 'screen' |
| `thumbnailUrl` | `string` | No | URL of the thumbnail image for the recorded data |
| `thumbnailWithPlayIconUrl` | `string` | No | URL of the thumbnail image with a play icon overlay |
| `videoUrl` | `string` | No | URL of the recorded video |
| `audioUrl` | `string` | No | URL of the recorded audio |
| `videoPlayerUrl` | `string` | No | URL of the hosted website to open video in a new tab |
| `getThumbnailTag` | `function` | Yes | A method that returns an HTML string for displaying the thumbnail with a link to the video player |
#### RecorderAnnotation
***
| Property | Type | Required | Description | |
| ----------------- | ------------- | -------- | ----------------------------------------------------------------------- | - |
| `annotationId` | String | Yes | Unique identifier for the recorder annotation, automatically generated. | |
| `from` | `User` | Yes | The user who created the recorder annotation. | |
| `color` | String | No | Color used for the annotation. | |
| `lastUpdated` | Any | No | Timestamp of the last update, automatically generated. | |
| `locationId` | Number | No | Unique location ID from provided location. | |
| `location` | `Location` | No | Location to identify user on sub document. | |
| `type` | String | No | Type of annotation. | |
| `recordingType` | String | Yes | Type of recording for the annotation. | |
| `mode` | String | Yes | Mode of the recorder annotation, 'floating' or 'thread'. | |
| `approved` | Boolean | No | Indicates if the annotation is approved. | |
| `attachment` | Attachment | No | Attachment for recorded media. Deprecated. | |
| `attachments` | Attachment\[] | Yes | List of attachments for the annotation. | |
| `annotationIndex` | Number | No | Index of the annotation in a list. | |
| `pageInfo` | PageInfo | No | Information about the page where the annotation is made. | |
| `recordedTime` | Object | No | Recorded time details. | |
| `transcription` | Transcription | No | Transcription of the recorded media. | |
#### RecorderDataTranscriptSegment
***
| Property | Type | Required | Description |
| -------------------- | ------ | -------- | --------------------------------------- |
| `startTime` | String | Yes | Start time of the transcription segment |
| `endTime` | String | Yes | End time of the transcription segment |
| `startTimeInSeconds` | Number | Yes | Start time of the segment in seconds |
| `endTimeInSeconds` | Number | Yes | End time of the segment in seconds |
| `text` | String | Yes | Transcribed text content of the segment |
#### RecorderDataTranscription
***
| Property | Type | Required | Description |
| -------------------- | --------------------------------- | -------- | ---------------------------------------- |
| `transcriptSegments` | `RecorderDataTranscriptSegment[]` | No | Array of transcription segments |
| `vttFileUrl` | String | No | URL to the VTT format transcription file |
| `contentSummary` | String | No | Summary of the transcribed content |
#### RecorderDataAsset
***
| Property | Type | Required | Description |
| ----------------- | --------------------------- | -------- | --------------------------------------------------------------- |
| `version` | `number` | No | Version of the asset. |
| `url` | `string` | Yes | URL to the recorded media |
| `mimeType` | `string` | No | MIME type of the recorded media |
| `fileName` | `string` | No | Name of the recorded file |
| `fileSizeInBytes` | `number` | No | File size in bytes |
| `fileFormat` | `RecorderFileFormat` | No | The format/extension of the file. Example: 'mp3', 'mp4', 'webm' |
| `thumbnailUrl` | `string` | No | URL to the thumbnail image |
| `transcription` | `RecorderDataTranscription` | No | Transcription data for the recording |
#### RecorderData
***
| Property | Type | Required | Description |
| ------------------- | --------------------------- | -------- | ---------------------------------------------------------- |
| `recorderId` | `string` | Yes | ID of the recorder |
| `from` | `User \| null` | No | The user who created the recorder |
| `metadata` | `RecorderMetadata` | No | Metadata for the recording |
| `assets` | `RecorderDataAsset[]` | Yes | Array of recording assets for the latest version |
| `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets |
| `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the latest version of the recording |
#### MediaPreviewConfig
***
| Property | Type | Required | Description |
| ---------------- | ----------- | -------- | --------------------------------- |
| `audio` | Object | No | Configuration for audio preview |
| `audio.enabled` | boolean | No | Whether audio preview is enabled |
| `audio.deviceId` | string | No | Device ID for audio input |
| `video` | Object | No | Configuration for video preview |
| `video.enabled` | boolean | No | Whether video preview is enabled |
| `video.deviceId` | string | No | Device ID for video input |
| `screen` | Object | No | Configuration for screen preview |
| `screen.enabled` | boolean | No | Whether screen preview is enabled |
| `screen.stream` | MediaStream | No | MediaStream for screen sharing |
#### MediaRecorderOptions
***
| Property | Type | Required | Description |
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------- |
| `audioBitsPerSecond` | `number` | No | Controls the audio encoding quality by setting the number of bits used per second for audio. |
| `videoBitsPerSecond` | `number` | No | Controls the video encoding quality by setting the number of bits used per second for video. |
#### RecorderQualityConstraintsOptions
***
| Property | Type | Required | Description |
| -------- | ----------------------- | -------- | ---------------------------------------------- |
| `video` | `MediaTrackConstraints` | No | Specifies the constraints for the video track. |
| `audio` | `MediaTrackConstraints` | No | Specifies the constraints for the audio track. |
#### MediaTrackConstraints
***
| Property | Type | Required | Description |
| ------------------ | ------------------ | -------- | ---------------------------------------------------------------- |
| `aspectRatio` | `ConstrainDouble` | No | Controls the width-to-height ratio of the captured video stream. |
| `frameRate` | `ConstrainDouble` | No | Determines the number of frames per second for the video stream. |
| `height` | `ConstrainULong` | No | Sets the vertical resolution (in pixels) of the video stream. |
| `width` | `ConstrainULong` | No | Sets the horizontal resolution (in pixels) of the video stream. |
| `autoGainControl` | `ConstrainBoolean` | No | Enables/disables automatic volume adjustment for audio input. |
| `echoCancellation` | `ConstrainBoolean` | No | Enables/disables the removal of audio echo effects. |
| `noiseSuppression` | `ConstrainBoolean` | No | Enables/disables the filtering of background noise from audio. |
| `sampleRate` | `ConstrainULong` | No | Controls the number of audio samples taken per second. |
#### ConstrainDouble
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | -------------------------------------------------------------------- |
| `min` | `number` | No | The minimum acceptable value. |
| `max` | `number` | No | The maximum acceptable value. |
| `ideal` | `number` | No | The preferred value that the browser will try to match if possible. |
| `exact` | `number` | No | A mandatory value that must be matched exactly or the request fails. |
#### ConstrainULong
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | -------------------------------------------------------------------- |
| `min` | `number` | No | The minimum acceptable value. |
| `max` | `number` | No | The maximum acceptable value. |
| `ideal` | `number` | No | The preferred value that the browser will try to match if possible. |
| `exact` | `number` | No | A mandatory value that must be matched exactly or the request fails. |
#### ConstrainBoolean
***
| Property | Type | Required | Description |
| -------- | --------- | -------- | -------------------------------------------------------------------- |
| `ideal` | `boolean` | No | The preferred value that the browser will try to match if possible. |
| `exact` | `boolean` | No | A mandatory value that must be matched exactly or the request fails. |
#### RecorderDevicePermissionOptions
***
| Property | Type | Required | Description |
| -------- | ------- | -------- | ------------------------------------------------------ |
| `audio` | boolean | No | Whether to request permission for audio input devices. |
| `video` | boolean | No | Whether to request permission for video input devices. |
### RecorderElement Interface
#### RecorderElement
***
Interface representing the Recorder element object that provides methods for controlling recording behavior, Picture-in-Picture mode, and permissions.
| Method | Parameters | Returns | Description |
| ------------------------- | --------------- | --------------- | ------------------------------------------------------------- |
| `setMaxLength` | `value: number` | `void` | Sets the maximum recording duration in seconds |
| `enablePictureInPicture` | None | `void` | Enables Picture-in-Picture mode for recordings |
| `disablePictureInPicture` | None | `void` | Disables Picture-in-Picture mode for recordings |
| `openPictureInPicture` | None | `void` | Opens the Picture-in-Picture window for the current recording |
| `exitPictureInPicture` | None | `void` | Exits the Picture-in-Picture window |
| `requestScreenPermission` | None | `Promise` | Requests screen capture permissions for recording preview |
# Notifications
#### Notification
***
| Property | Type | Required | Description |
| ------------------------------------ | ----------------------------------- | -------- | ----------------------------------------------------------------------------- |
| `id` | `string` | Yes | Notification ID |
| `notificationSource` | `string` | Yes | Notification source. e.g., 'comment', 'custom', etc. |
| `actionType` | `string` | No | Action that triggered the notification. e.g., 'added' |
| `isUnread` | `boolean` | No | Whether the notification is unread for the user |
| `actionUser` | `User` | No | The user who triggered the action |
| `timestamp` | `number` | No | Timestamp of the notification |
| `displayHeadlineMessage` | `string` | No | The headline message of the notification |
| `displayBodyMessage` | `string` | No | The body message of the notification |
| `displayHeadlineMessageTemplate` | `string` | No | The template of the headline message |
| `displayHeadlineMessageTemplateData` | `object` | No | The data used to fill the headline message template |
| `forYou` | `boolean` | No | Whether the notification is for the current logged-in user |
| `targetAnnotationId` | `string` | No | ID of the annotation that triggered the notification |
| `notificationSourceData` | `any` | No | The data of the notification source. e.g., `CommentAnnotation` |
| `metadata` | `NotificationMetadata` | No | Metadata for the current notification. e.g., `documentId` |
| `notifyUsers` | `{ [emailHash: string]: boolean }` | No | Map of email hashes to boolean values indicating whether to notify the user |
| `notifyUsersByUserId` | `{ [userIdHash: string]: boolean }` | No | Map of user ID hashes to boolean values indicating whether to notify the user |
#### NotificationMetadata
***
| Property | Type | Required | Description |
| ---------------------- | ---------- | -------- | -------------------------------------------------- |
| `apiKey` | `string` | No | Your API key |
| `clientOrganizationId` | `string` | No | The organization ID that you set |
| `organizationId` | `string` | No | The organization ID generated by us |
| `clientDocumentId` | `string` | No | The document ID that you set |
| `documentId` | `string` | No | The document ID generated by us |
| `locationId` | `number` | No | The unique location ID |
| `location` | `Location` | No | The location object |
| `documentMetadata` | `Object` | No | Contains the complete document metadata object |
| `organizationMetadata` | `Object` | No | Contains the complete organization metadata object |
#### SettingsUpdatedEvent
***
| Property | Type | Required | Description |
| ------------ | ---------------------------- | -------- | ------------------------------------------------ |
| `settings` | `NotificationSettingsConfig` | Yes | The updated notification settings configuration. |
| `isMutedAll` | `boolean` | Yes | Whether all notifications are muted. |
| Enum Name | Event Type | Description |
| ------------------ | ----------------- | ---------------------------------------------------- |
| `SETTINGS_UPDATED` | `settingsUpdated` | Triggered when the notification settings are updated |
#### NotificationSettingsConfig
***
Sets what notifications the user will receive on the provided channel.
| Property | Type | Required | Description |
| --------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `[key: string]` | `NotificationSettingsItemType` | No | Dynamic key-value pairs for notification settings configuration. The key represents the channel ID and the value represents the one of the NotificationSettingsItemType. |
#### NotificationSettingsItemType
***
Decides what notifications the user will receive on the current channel.
Type: `'ALL' | 'MINE' | 'NONE' | string`
**Description:**
* `ALL`: Subscribes the user to all notifications whether or not the user is involved in the notification on the current document.
* `MINE`: Subscribes the user to notifications that are related to the current user on the current document.
* `NONE`: Subscribes the user to no notifications on this channel on the current document.
#### NotificationInitialSettingsConfig
***
| Property | Type | Required | Description |
| --------- | --------------------------- | -------- | ------------------------------------------------------ |
| `name` | `string` | No | Display name for the notification channel. |
| `id` | `string` | Yes | Unique channel ID for the notification channel. |
| `default` | `string` | No | Default value for the notification channel. |
| `enable` | `boolean` | No | Whether the notification channel is enabled. |
| `values` | `NotificationConfigValue[]` | No | Array of possible values for the notification channel. |
#### NotificationConfigValue
***
| Property | Type | Required | Description |
| -------- | ------------------------------ | -------- | ----------------------------------------- |
| `id` | `NotificationSettingsItemType` | Yes | Unique id for the configuration value. |
| `name` | `string` | No | Display name for the configuration value. |
#### GetNotificationsDataQuery
***
| Property | Type | Required | Description |
| -------- | ---------------------------------- | -------- | --------------------------------------------------------- |
| `type` | `'all' \| 'forYou' \| 'documents'` | No | Filter for notification type: all, for you, or documents. |
#### NotificationSettingsLayout
***
Layout mode for notification settings UI.
Type: `'accordion' | 'dropdown'`
**Description:**
* `accordion`: Settings displayed in expandable accordion (default)
* `dropdown`: Settings displayed in dropdown menu
#### NotificationServiceConfig
***
Top-level org-scoped config for notification delay and batching. Set in the Velt Console under workspace notification settings.
| Property | Type | Required | Description |
| ------------- | ----------------------------- | -------- | -------------------------------------------------------- |
| `delayConfig` | [`DelayConfig`](#delayconfig) | No | Controls whether notifications are held before delivery. |
| `batchConfig` | [`BatchConfig`](#batchconfig) | No | Controls grouping of notifications into batched digests. |
#### DelayConfig
***
Controls the hold period applied to notifications before they are evaluated for batching or delivery.
| Property | Type | Required | Default | Description |
| -------------- | --------- | -------- | ------- | ------------------------------------------------------------------ |
| `isEnabled` | `boolean` | No | `false` | Enables the delay pipeline for this organization. |
| `delaySeconds` | `number` | No | — | Seconds to hold a notification before proceeding to batch or send. |
#### BatchConfig
***
Configures batching windows per grouping scope. Each scope is independently configured via [`BatchWindowConfig`](#batchwindowconfig).
| Property | Type | Required | Description |
| ---------- | ----------------------------------------- | -------- | ------------------------------------------------------ |
| `document` | [`BatchWindowConfig`](#batchwindowconfig) | No | Batching window applied per document. |
| `user` | [`BatchWindowConfig`](#batchwindowconfig) | No | Batching window applied per user across all documents. |
#### BatchWindowConfig
***
Defines the time window and activity cap for a single batching scope.
| Property | Type | Required | Description |
| -------------------- | --------- | -------- | ------------------------------------------------------------------------------ |
| `isEnabled` | `boolean` | No | Enables batching for this scope. |
| `batchWindowSeconds` | `number` | No | Duration in seconds to collect activities before flushing the batch. |
| `maxActivities` | `number` | No | Maximum activities per batch; flush triggers early when this count is reached. |
# Activity Logs
#### ActivityFeatureType
***
Feature area that generated an activity log record.
```typescript theme={null}
type ActivityFeatureType = 'comment' | 'reaction' | 'recorder' | 'crdt' | 'custom';
```
| Value | Description |
| ------------ | --------------------------------------------------------- |
| `'comment'` | Activity log from the Comments feature |
| `'reaction'` | Activity log from the Reactions feature |
| `'recorder'` | Activity log from the Recorder feature |
| `'crdt'` | Activity log from the CRDT (collaborative editor) feature |
| `'custom'` | Activity log created by the host application |
#### ActivitySubscribeConfig
***
Filter config passed to `getAllActivities()` to scope the activity log feed.
| Property | Type | Required | Description |
| --------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `organizationId` | `string` | No | Scope feed to a specific organization ID |
| `documentIds` | `string[]` | No | Filter to specific document IDs |
| `currentDocumentOnly` | `boolean` | No | When `true`, limits feed to the current document. Auto-switches when `setDocument()` is called |
| `maxDays` | `number` | No | Maximum age in days for returned activity logs (default: 30) |
| `featureTypes` | [`ActivityFeatureType[]`](#activityfeaturetype) | No | Filter by feature area |
| `excludeFeatureTypes` | [`ActivityFeatureType[]`](#activityfeaturetype) | No | Exclude specific feature areas |
| `actionTypes` | `string[]` | No | Filter by action type; use the exported action type constants |
| `excludeActionTypes` | `string[]` | No | Exclude specific action types |
| `userIds` | `string[]` | No | Filter to activity logs by specific user IDs |
| `excludeUserIds` | `string[]` | No | Exclude activity logs by specific user IDs |
#### ActivityRecord
***
Core activity log object returned from the activity log feed. Generic params: `TEntity` (entity data shape), `TTarget` (target entity data shape).
| Property | Type | Required | Description |
| ---------------------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------- |
| `id` | `string` | Yes | Unique activity log ID |
| `featureType` | [`ActivityFeatureType`](#activityfeaturetype) | Yes | Feature area that generated this activity log |
| `actionType` | `string` | Yes | Specific action that occurred |
| `eventType` | `string` | No | Sub-event type within the action |
| `actionUser` | [`User`](#user) | Yes | User who performed the action |
| `timestamp` | `number` | Yes | Unix timestamp of the activity log |
| `metadata` | [`ActivityMetadata`](#activitymetadata) | Yes | Feature-specific extensible metadata |
| `targetEntityId` | `string` | Yes | ID of the entity this activity log targets |
| `targetSubEntityId` | `string \| null` | No | ID of a sub-entity within the target |
| `changes` | [`ActivityChanges`](#activitychanges) | No | Before/after field changes |
| `entityData` | `TEntity` | No | Full entity object at time of action |
| `entityTargetData` | `TTarget` | No | Full target entity object at time of action |
| `displayMessageTemplate` | `string` | No | Template string with `{{variable}}` placeholders |
| `displayMessageTemplateData` | `Record` | No | Data to resolve the display message template |
| `displayMessage` | `string` | No | Resolved human-readable display message. Computed client-side — never stored in Firestore |
| `actionIcon` | `string` | No | Icon URL or identifier for the action |
| `immutable` | `boolean` | No | When `true`, the record cannot be updated or deleted via REST API |
#### ActivityChanges
***
Map of field names to their before/after change values.
```typescript theme={null}
interface ActivityChanges {
[key: string]: ActivityChange | undefined;
}
```
#### ActivityChange
***
Before/after values for a single changed field. Generic param `T` is the field value type.
| Property | Type | Required | Description |
| -------- | ----------- | -------- | ----------------------------- |
| `from` | `T \| null` | No | Field value before the action |
| `to` | `T \| null` | No | Field value after the action |
#### ActivityMetadata
***
Extensible metadata attached to an activity log record. Extends `BaseMetadata` with open index signature for feature-specific fields.
| Property | Type | Required | Description |
| ---------------------- | ------------------ | -------- | --------------------------------- |
| `apiKey` | `string` | No | Inherited from `BaseMetadata` |
| `documentId` | `string` | No | Inherited from `BaseMetadata` |
| `organizationId` | `string` | No | Inherited from `BaseMetadata` |
| `clientOrganizationId` | `string` | No | Inherited from `BaseMetadata` |
| `folderId` | `string` | No | Inherited from `BaseMetadata` |
| `veltFolderId` | `string` | No | Inherited from `BaseMetadata` |
| `documentMetadata` | `DocumentMetadata` | No | Inherited from `BaseMetadata` |
| `sdkVersion` | `string \| null` | No | Inherited from `BaseMetadata` |
| `[key: string]` | `any` | No | Feature-specific extension fields |
#### CreateActivityData
***
Payload for `createActivity()`. Use `featureType: 'custom'` and `actionType: 'custom'` for non-Velt events. Generic params: `TEntity` (entity data shape), `TTarget` (target entity data shape).
| Property | Type | Required | Description |
| ---------------------------- | --------------------------------------------- | -------- | ----------------------------------------------------------------------------- |
| `featureType` | [`ActivityFeatureType`](#activityfeaturetype) | Yes | Feature type; use `'custom'` for non-Velt events |
| `actionType` | `string` | Yes | Action identifier; use `'custom'` for non-Velt events |
| `eventType` | `string` | No | Sub-event type within the action |
| `targetEntityId` | `string` | Yes | ID of the entity this activity log targets |
| `targetSubEntityId` | `string \| null` | No | ID of a sub-entity within the target |
| `changes` | [`ActivityChanges`](#activitychanges) | No | Before/after field changes to record |
| `entityData` | `TEntity` | No | Full entity object at time of action |
| `entityTargetData` | `TTarget` | No | Full target entity object at time of action |
| `actionIcon` | `string` | No | Icon URL or identifier — typically for custom activities |
| `displayMessageTemplate` | `string` | No | Template string with `{{variable}}` placeholders — only for custom activities |
| `displayMessageTemplateData` | `Record` | No | Template variable values — only for custom activities |
### Activity Log Action Type Constants
Pre-defined `actionType` string constants for each feature's activity log records. Import these to build type-safe `actionTypes` filters in [`ActivitySubscribeConfig`](#activitysubscribeconfig).
#### CommentActivityActionTypes
***
Action type constants for Comment feature activity logs. Union type: `CommentActivityActionType`.
| Constant | Value | Description |
| -------------------- | ----------------------------------------- | ------------------------------------------- |
| `ANNOTATION_ADD` | `'comment_annotation.add'` | A comment annotation was added |
| `ANNOTATION_DELETE` | `'comment_annotation.delete'` | A comment annotation was deleted |
| `COMMENT_ADD` | `'comment.add'` | A comment was added |
| `COMMENT_UPDATE` | `'comment.update'` | A comment was updated |
| `COMMENT_DELETE` | `'comment.delete'` | A comment was deleted |
| `STATUS_CHANGE` | `'comment_annotation.status_change'` | Comment annotation status changed |
| `PRIORITY_CHANGE` | `'comment_annotation.priority_change'` | Comment annotation priority changed |
| `ASSIGN` | `'comment_annotation.assign'` | Comment annotation was assigned |
| `ACCESS_MODE_CHANGE` | `'comment_annotation.access_mode_change'` | Comment annotation access mode changed |
| `CUSTOM_LIST_CHANGE` | `'comment_annotation.custom_list_change'` | Comment annotation custom list changed |
| `APPROVE` | `'comment_annotation.approve'` | Comment annotation was approved |
| `ACCEPT` | `'comment.accept'` | A comment was accepted |
| `REJECT` | `'comment.reject'` | A comment was rejected |
| `REACTION_ADD` | `'comment.reaction_add'` | A reaction was added to a comment |
| `REACTION_DELETE` | `'comment.reaction_delete'` | A reaction was removed from a comment |
| `SUBSCRIBE` | `'comment_annotation.subscribe'` | User subscribed to a comment annotation |
| `UNSUBSCRIBE` | `'comment_annotation.unsubscribe'` | User unsubscribed from a comment annotation |
#### RecorderActivityActionTypes
***
Action type constants for Recorder feature activity logs. Union type: `RecorderActivityActionType`.
| Constant | Value | Description |
| ------------------ | -------------------- | ----------------------- |
| `RECORDING_ADD` | `'recording.add'` | A recording was added |
| `RECORDING_DELETE` | `'recording.delete'` | A recording was deleted |
#### ReactionActivityActionTypes
***
Action type constants for Reaction feature activity logs. Union type: `ReactionActivityActionType`.
| Constant | Value | Description |
| ----------------- | ------------------- | ---------------------- |
| `REACTION_ADD` | `'reaction.add'` | A reaction was added |
| `REACTION_DELETE` | `'reaction.delete'` | A reaction was deleted |
#### CrdtActivityActionTypes
***
Action type constants for CRDT feature activity logs. Union type: `CrdtActivityActionType`.
| Constant | Value | Description |
| ------------- | -------------------- | --------------------------- |
| `EDITOR_EDIT` | `'crdt.editor_edit'` | A CRDT editor edit occurred |
# Single Editor Mode
#### AccessRequestEvent
***
This event object is related to requests for editor access. It is emitted for `accessRequested`, `accessRequestCanceled`, `accessAccepted`, and `accessRejected` events.
| Property | Type | Required | Description |
| ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------ |
| `viewer` | `User` | No | The user who is the current viewer and is involved in the access request. |
| `editor` | `User` | No | The user who is the current editor at the time of the event. |
| `timestamp` | `number` | No | UNIX timestamp (in milliseconds) of when the event occurred. |
| `status` | `string` | No | The status of the access request (e.g., "requested", "canceled", "accepted", "rejected" ). |
| `totalUsers` | `number` | No | Total number of users currently present on the document. |
| `presenceSnippylyUserIds` | `string[]` | No | Velt internal user IDs of currently present users. |
| `presenceClientUserIds` | `string[]` | No | Client-provided user IDs of currently present users. |
#### SEMEvent
***
This event object is related to editor/viewer assignments and editor status changes. It is emitted for `editorAssigned`, `viewerAssigned`, and `editorOnDifferentTabDetected` events.
| Property | Type | Required | Description |
| ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- |
| `viewer` | `User` | No | The user who is the current viewer at the time of the event. |
| `editor` | `User` | No | The user who is the current editor at the time of the event. |
| `timestamp` | `number` | No | UNIX timestamp (in milliseconds) of when the event occurred. |
| `role` | `string` | No | The role relevant to the event, typically "editor" or "viewer" for assignment events. |
| `totalUsers` | `number` | No | Total number of users currently present on the document. |
| `presenceSnippylyUserIds` | `string[]` | No | Velt internal user IDs of currently present users. |
| `presenceClientUserIds` | `string[]` | No | Client-provided user IDs of currently present users. |
#### SingleEditorLiveStateData
***
| Property | Type | Required | Description |
| --------------------- | ---------------- | -------- | ----------------------------------------- |
| `editor` | `User \| null` | No | The user who is currently editing, if any |
| `requestEditorAccess` | `Object \| null` | No | Details about a request for editor access |
| `tabId` | `string \| null` | No | The identifier of the tab, if applicable |
#### RequestEditorAccess
***
| Property | Type | Required | Description |
| --------------------- | ------------------------------------------------------ | -------- | ------------------------------------------------------- |
| `user` | `User` | Yes | The user requesting editor access |
| `requestedAt` | `any` | Yes | The timestamp when the access was requested |
| `status` | `'pending' \| 'accepted' \| 'rejected' \| 'cancelled'` | Yes | The status of the access request |
| `editorAccessTimeout` | `number` | Yes | Timeout duration for the editor access |
| `tabId` | `string \| null` | No | The identifier of the tab related to the access request |
#### SingleEditorConfig
***
| Property | Type | Required | Description |
| ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------- |
| `customMode` | `boolean` | No | Enables/disables custom mode. In custom mode, input elements are not disabled for the viewer |
| `singleTabEditor` | `boolean` | Yes | Enables/disables editor mode on a single tab only |
#### UserEditorAccess
***
| Property | Type | Required | Description |
| ---------------------- | --------- | -------- | ---------------------------------------------------------- |
| `isEditor` | `boolean` | No | Indicates whether the user has editor privileges |
| `isEditorOnCurrentTab` | `boolean` | No | Indicates whether the user is an editor on the current tab |
#### EditorAccessTimer
***
| Property | Type | Required | Description |
| -------------- | --------------------------------------- | -------- | ---------------------------------------------------------- |
| `state` | `'idle' \| 'inProgress' \| 'completed'` | Yes | The state of the Editor Access Request timer |
| `durationLeft` | `number` | No | Duration left for the editor access timer to be completed. |
# Live State Data
#### LiveStateData
***
| Property | Type | Required | Description |
| ----------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `id` | `string` | Yes | A unique identifier likely used for quick reference and indexing. It's an MD5 hash of `liveStateDataId` |
| `liveStateDataId` | `string` | Yes | A unique identifier for the state data being synced |
| `data` | `string \| number \| boolean \| JSON` | Yes | The actual data you want to synchronize across clients |
| `lastUpdated` | `any` | Yes | A timestamp or similar data indicating the last time the state data was updated |
| `updatedBy` | `User` | Yes | The user who last updated the state data |
| `tabId` | `string \| null` | No | An identifier that could be used to associate the state data with a specific tab or instance |
#### LiveStateDataMap
***
| Property | Type | Required | Description |
| ------------------------------- | ----------------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| `custom` | `{ [liveStateDataId: string]: LiveStateData; }` | No | Map of all unique LiveStateData set by you on the given document. |
| `default` | Object | No | Map of all unique LiveStateData set by the default editor on the given document. |
| `default.singleEditor` | `SingleEditorLiveStateData` | No | Part of `default`, representing single editor live state data. |
| `default.autoSyncState` | Object | | Part of `default`, representing auto synchronization state. |
| `default.autoSyncState.current` | `LiveStateData` | No | Part of `autoSyncState`, current live state data. |
| `default.autoSyncState.history` | `[liveStateDataId: string]: LiveStateData` | No | Part of `autoSyncState`, map of historical live state data keyed by live state data ID. |
#### LiveStateData
***
| Property | Type | Required | Description |
| --------------- | ------- | -------- | ----------------------------------------- |
| `id` | string | Yes | Unique identifier for the live state data |
| `locationName` | string | Yes | Name of the location |
| `version` | Version | Yes | Version information |
| `[key: string]` | any | Yes | Additional dynamic properties |
#### SetLiveStateDataConfig
***
| Property | Type | Required | Description |
| -------- | --------- | -------- | ------------------------------------------------------------- |
| `merge` | `boolean` | No | Whether to merge data with existing data. Default is `false`. |
#### FetchLiveStateDataRequest
***
| Property | Type | Required | Description |
| ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `liveStateDataId` | `string` | No | Unique identifier for the specific live state data to fetch. If not provided, all live state data will be fetched. |
#### ServerConnectionState
***
| Property | Type | Required | Description |
| -------------- | ------ | -------- | ----------------------------------------------------------------- |
| `ONLINE` | string | Yes | Server connection is online and active. Value: 'online' |
| `OFFLINE` | string | Yes | Server connection is offline. Value: 'offline' |
| `PENDING_INIT` | string | Yes | Server connection initialization is pending. Value: 'pendingInit' |
| `PENDING_DATA` | string | Yes | Server is waiting for data. Value: 'pendingData' |
# Client
#### Client Events
| Event Type | Event Name | Description | Event Object |
| --------------------- | -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- |
| `USER_UPDATE` | `userUpdate` | Fired when the Velt user logs in, logs out, or changes. | [UserUpdateEvent](#userupdateevent) |
| `INIT_UPDATE` | `initUpdate` | Initialization lifecycle updates (documents/locations set/unset, user init). | [InitUpdateEvent](#initupdateevent) |
| `DOCUMENT_INIT` | `documentInit` | Document initialization status changes. | [DocumentInitEvent](#documentinitevent) |
| `ERROR` | `error` | Error events emitted by the SDK (e.g., token issues, retry limits). | [ErrorEvent](#errorevent) |
| `VELT_BUTTON_CLICK` | `veltButtonClick` | Fired when a Velt Button is clicked. | [VeltButtonClickEvent](#veltbuttonclickevent) |
| `PERMISSION_PROVIDER` | `permissionProvider` | Permission Provider events for access requests, results, and errors. | [PermissionProviderEvent](#permissionproviderevent) |
| `DATA_PROVIDER` | `dataProvider` | Data Provider events for debugging get, save, and delete operations. | [DataProviderEvent](#dataproviderevent) |
#### InitUpdateEvent
***
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------------------------------------ |
| `event` | `string` | Yes | The event name (see sub-events table below) |
| `methodName` | `string` | No | The method that triggered this event (see `InitUpdateMethodNames` below) |
| `source` | `string` | No | Source of the event |
| `payload` | `any` | No | Additional event payload data |
**InitUpdateMethodNames:**
| Method Name | Description |
| ------------------------ | ----------------------------------- |
| `setDocuments` | `setDocuments()` was called |
| `setRootDocument` | `setRootDocument()` was called |
| `setDocumentId` | `setDocumentId()` was called |
| `unsetDocumentId` | `unsetDocumentId()` was called |
| `unsetDocuments` | `unsetDocuments()` was called |
| `setLocation` | `setLocation()` was called |
| `setLocations` | `setLocations()` was called |
| `setRootLocation` | `setRootLocation()` was called |
| `addLocation` | `addLocation()` was called |
| `removeLocation` | `removeLocation()` was called |
| `removeLocations` | `removeLocations()` was called |
| `unsetLocationIds` | `unsetLocationIds()` was called |
| `removeLocationsSuccess` | Locations were successfully removed |
**Sub-events (event field values):**
| Sub-event (string) | Description |
| -------------------------- | --------------------------------------------------------------------------------------- |
| `userUpdate` | User initialized or updated as part of init |
| `setDocumentsTriggered` | A document(s) set action was triggered (`setDocument`, `setDocuments`, `setDocumentId`) |
| `setRootDocumentTriggered` | Root document set was triggered (`setRootDocument`) |
| `setDocumentsSuccess` | Documents successfully set |
| `unsetDocumentsTriggered` | Unset document(s) was triggered (`unsetDocumentId`, `unsetDocuments`) |
| `unsetDocumentsSuccess` | Documents successfully unset |
| `setLocationsTriggered` | A location(s) set action was triggered (`setLocation`, `setLocations`) |
| `setRootLocationTriggered` | Root location set was triggered (`setRootLocation`) |
| `setLocationsSuccess` | Locations successfully set |
| `unsetLocationsTriggered` | Unsetting location IDs was triggered (`unsetLocationIds`) |
#### PermissionProviderEvent
***
This event follows the `BaseResolverEvent` structure (see [DataProviderEvent](#dataproviderevent) for the base structure).
| Event Type | Description |
| -------------------------------------- | ------------------------------------------------------------------------------------------ |
| `resourceAccessRequestFormed` | Triggered when a permission request is formed internally before being sent |
| `resourceAccessRequestTriggered` | Triggered when a permission request is actually triggered and sent |
| `resourceAccessResult` | Triggered when a permission check result is received from your server |
| `resourceAccessError` | Triggered when an error occurs during permission checking |
| `resourceAccessResultFromCache` | Triggered when a permission result is retrieved from cache instead of making a new request |
| `revokeAccessOnDocumentUnsetTriggered` | Triggered when permissions are automatically revoked due to document unset trigger |
| `revokeAccessOnDocumentUnsetFormed` | Triggered when a revoke access on document unset request is formed |
| `revokeAccessOnDocumentUnsetResult` | Triggered when revoke access on document unset completes successfully |
| `revokeAccessOnDocumentUnsetError` | Triggered when an error occurs during revoke access on document unset |
| `revokeAccessOnUserLogoutTriggered` | Triggered when permissions are automatically revoked due to user logout trigger |
| `revokeAccessOnUserLogoutFormed` | Triggered when a revoke access on user logout request is formed |
| `revokeAccessOnUserLogoutResult` | Triggered when revoke access on user logout completes successfully |
| `revokeAccessOnUserLogoutError` | Triggered when an error occurs during revoke access on user logout |
#### DataProviderEvent
***
The `dataProvider` event emits different resolver event types depending on the data provider being used. All resolver events share a common base structure:
**BaseResolverEvent Structure:**
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ------------------------------------------ |
| `event` | `object` | Yes | The event type object (varies by resolver) |
| `methodName` | `string` | No | The method that triggered this event |
| `moduleName` | `string` | No | The module that triggered this event |
| `source` | `string` | No | `'internal'` or `'external'` |
| `timestamp` | `number` | No | Timestamp of the event |
| `uniqueId` | `string` | No | Unique identifier for the event |
| `payload` | `any` | No | Additional event payload data |
***
#### UserResolverEvent
| Event Type | Description |
| -------------------------------- | --------------------------------------------------------------- |
| `userResolutionRequestFormed` | Triggered when a user resolution request is formed internally |
| `userResolutionRequestTriggered` | Triggered when a user resolution request is sent |
| `userResolutionResult` | Triggered when user resolution completes successfully |
| `userResolutionError` | Triggered when an error occurs during user resolution |
| `userResolutionResultFromCache` | Triggered when a user resolution result is retrieved from cache |
**UserResolverModuleName:**
| Module Name | Description |
| ----------------------- | -------------------------------- |
| `identify/authProvider` | From identify or auth provider |
| `getTemporaryUsers` | From getting temporary users |
| `getUsers` | From getting users |
| `getHuddleUsers` | From getting huddle users |
| `getSingleEditorUsers` | From getting single editor users |
***
#### CommentResolverEvent
| Event Type | Description |
| ----------------------------------- | ------------------------------------------------------------------ |
| `commentResolutionRequestFormed` | Triggered when a comment resolution request is formed internally |
| `commentResolutionRequestTriggered` | Triggered when a comment resolution request is sent |
| `commentResolutionResult` | Triggered when comment resolution completes successfully |
| `commentResolutionError` | Triggered when an error occurs during comment resolution |
| `commentResolutionResultFromCache` | Triggered when a comment resolution result is retrieved from cache |
| `commentSaveRequestFormed` | Triggered when a comment save request is formed internally |
| `commentSaveRequestTriggered` | Triggered when a comment save request is sent |
| `commentSaveResult` | Triggered when comment save completes successfully |
| `commentSaveError` | Triggered when an error occurs during comment save |
| `commentDeleteRequestFormed` | Triggered when a comment delete request is formed internally |
| `commentDeleteRequestTriggered` | Triggered when a comment delete request is sent |
| `commentDeleteResult` | Triggered when comment delete completes successfully |
| `commentDeleteError` | Triggered when an error occurs during comment delete |
**CommentResolverModuleName:**
| Module Name | Description |
| ----------------------- | -------------------------------- |
| `setDocuments` | From setDocuments call |
| `getCommentAnnotations` | From getting comment annotations |
| `getNotifications` | From getting notifications |
***
#### AttachmentResolverEvent
| Event Type | Description |
| ---------------------------------- | ---------------------------------------------------------------- |
| `attachmentSaveRequestFormed` | Triggered when an attachment save request is formed internally |
| `attachmentSaveRequestTriggered` | Triggered when an attachment save request is sent |
| `attachmentSaveResult` | Triggered when attachment save completes successfully |
| `attachmentSaveError` | Triggered when an error occurs during attachment save |
| `attachmentDeleteRequestFormed` | Triggered when an attachment delete request is formed internally |
| `attachmentDeleteRequestTriggered` | Triggered when an attachment delete request is sent |
| `attachmentDeleteResult` | Triggered when attachment delete completes successfully |
| `attachmentDeleteError` | Triggered when an error occurs during attachment delete |
***
#### ReactionResolverEvent
| Event Type | Description |
| ------------------------------------ | ------------------------------------------------------------------- |
| `reactionResolutionRequestFormed` | Triggered when a reaction resolution request is formed internally |
| `reactionResolutionRequestTriggered` | Triggered when a reaction resolution request is sent |
| `reactionResolutionResult` | Triggered when reaction resolution completes successfully |
| `reactionResolutionError` | Triggered when an error occurs during reaction resolution |
| `reactionResolutionResultFromCache` | Triggered when a reaction resolution result is retrieved from cache |
| `reactionSaveRequestFormed` | Triggered when a reaction save request is formed internally |
| `reactionSaveRequestTriggered` | Triggered when a reaction save request is sent |
| `reactionSaveResult` | Triggered when reaction save completes successfully |
| `reactionSaveError` | Triggered when an error occurs during reaction save |
| `reactionDeleteRequestFormed` | Triggered when a reaction delete request is formed internally |
| `reactionDeleteRequestTriggered` | Triggered when a reaction delete request is sent |
| `reactionDeleteResult` | Triggered when reaction delete completes successfully |
| `reactionDeleteError` | Triggered when an error occurs during reaction delete |
**ReactionResolverModuleName:**
| Module Name | Description |
| ------------------------ | --------------------------------- |
| `setDocuments` | From setDocuments call |
| `getReactionAnnotations` | From getting reaction annotations |
#### Error Codes
| Code | Meaning (summary) |
| ------------------ | ---------------------------------- |
| `token_expired` | The auth token is no longer valid. |
| `too_many_retries` | Retried and hit the retry limit. |
#### DocumentMetadata
***
| Property | Type | Required | Description |
| ---------------- | -------------------------------------------- | -------- | ---------------------------------------------------- |
| `documentId` | `string` | Yes | Unique document id generated from client document id |
| `documentName` | `string` | No | Display name of the document |
| `folderId` | `string` | No | ID of the folder containing this document |
| `apiKey` | `string` | No | API key associated with the document |
| `organizationId` | `string` | Yes | Organization ID that owns this document |
| `locations` | `{ [locationId: number]: LocationMetadata }` | No | Location metadata for this document |
### Folders
#### FetchFoldersRequest
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | -------------------------------------------- |
| `organizationId` | `string` | Yes | Organization ID to fetch folders from |
| `folderId` | `string` | No | Parent folder ID to fetch child folders from |
#### FetchFoldersResponse
***
| Property | Type | Required | Description |
| --------------- | ---------------------------------------- | -------- | --------------------------------------------------------- |
| `data` | `Record \| null` | Yes | Map of folder IDs to their metadata. `Null` while loading |
| `nextPageToken` | `string` | Yes | Token for fetching next page of results |
### Documents
#### FetchDocumentsRequest
***
| Property | Type | Required | Description |
| ---------------- | ---------- | -------- | ------------------------------------------------------------------------ |
| `organizationId` | `string` | No | Organization ID to fetch documents from |
| `documentIds` | `string[]` | No | Array of specific document IDs to fetch |
| `folderId` | `string` | No | Folder ID to fetch documents from |
| `allDocuments` | `boolean` | No | Whether to fetch all documents. Use with `organizationId` or `folderId`. |
#### FetchDocumentsResponse
***
| Property | Type | Required | Description |
| --------------- | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `data` | `Record \| null` | Yes | Map of document groups to arrays of [DocumentMetadata](/api-reference/sdk/models/data-models#documentmetadata). `null` while loading. |
| `nextPageToken` | `string` | Yes | Token for fetching next page of results. Default page size is 1000. |
#### DocumentInitEvent
***
* `DocumentInitEvent` can be of type: `boolean | undefined`
* This represents the document initialization status.
#### ErrorEvent
***
| Property | Type | Required | Description |
| -------------- | ---------- | -------- | -------------------------------------- |
| `event` | `string` | No | The error event name |
| `sourceMethod` | `string` | No | The method that triggered the error |
| `documentIds` | `string[]` | No | Document IDs associated with the error |
| `userId` | `string` | No | User ID associated with the error |
| `timestamp` | `number` | No | Timestamp of the error |
| `error` | `string` | No | Error details |
| `code` | `string` | No | Error code |
| `message` | `string` | No | Error message |
| `source` | `string` | No | Source of the error |
#### List of error codes:
| Code | Description |
| -------------------------------- | -------------------------------------------- |
| `token_expired` | The JWT token has expired |
| `same_user_editor_current_tab` | Same user is already editor in current tab |
| `same_user_editor_different_tab` | Same user is already editor in different tab |
| `another_user_editor` | Another user is already editor |
#### SetUserAsEditorResponse
***
| Property | Type | Required | Description |
| -------- | ------------ | -------- | ----------------------------------------- |
| `error` | `ErrorEvent` | No | Present when the action cannot be applied |
#### LiveStateSingleEditorExternalUserPresence
***
| Property | Type | Required | Description |
| --------------------------- | ---------- | -------- | ------------------------------------------------------ |
| `sameUserPresentOnTab` | `boolean` | No | True if the same user is present on a different tab |
| `differentUserPresentOnTab` | `boolean` | No | True if a different user is present on a different tab |
| `userIds` | `string[]` | No | User IDs of users present on a different tab |
#### UserUpdateEvent
***
* `UserUpdateEvent` will return data of type: `User | null`
* If there is no user, it will return `null` else it will return the user object.
#### VeltButtonClickEvent
***
| Property | Type | Required | Description |
| ----------------------------- | ------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `buttonContext` | `VeltButtonContext` | Yes | Button context |
| `metadata` | `VeltEventMetadata` | Yes | Event metadata |
| `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object |
| `comment` | `Comment` | No | Comment object |
| `index` | `number` | No | Index of the repeated component the button is in. eg: Comment, Notification component. |
| `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations |
| `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations |
| `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts |
| `notification` | `Notification` | No | Notification object |
| `notifications` | `Notification[]` | No | Array of notifications |
| `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used and when the button is in the sidebar. |
#### PermissionProviderEvent
***
| Property | Type | Required | Description |
| ---------- | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `type` | `string` | Yes | Event type: `'request'`, `'result'`, or `'error'` |
| `userId` | `string` | Yes | User ID making the permission request |
| `resource` | `{ id: string; type: string; context?: { access: { [key: string]: string \| number } } }` | Yes | Resource being accessed. Includes optional `context` field with access information set during setDocuments. |
| `result` | `boolean` | No | Permission result (present when type is `'result'`) |
| `error` | `string` | No | Error message (present when type is `'error'`) |
#### RevokeAccessEvent
***
| Property | Type | Required | Description |
| -------------- | -------- | -------- | --------------------------------------------------------------- |
| `userId` | `string` | Yes | User ID whose access is being revoked |
| `resourceType` | `string` | Yes | Type of resource: `'document'`, `'folder'`, or `'organization'` |
| `resourceId` | `string` | Yes | ID of the resource |
| `trigger` | `string` | Yes | Trigger type: `'documentUnset'` or `'userLogout'` |
| `timestamp` | `number` | Yes | Unix timestamp when revocation occurred |
#### Config
| Property | Type | Required | Description |
| ----------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `urlAllowList` | string\[] | No | Restricts Velt features to specific pages by specifying partial URL strings. |
| `featureAllowList` | FeatureType\[] | No | Only allows the provided Velt features to run. |
| `userPlanAllowList` | string\[] | No | Restricts Velt features to specific user plans. |
| `userIdAllowList` | string\[] | No | Restricts Velt features to specific users. |
| `usePrefersColorScheme` | boolean | No | If set to true, listens to changes on the `prefers-color-scheme` media query to set the global theme of Velt components. |
| `globalStyles` | boolean | No | Controls whether Velt's global CSS styles are loaded. Default: true |
#### Features
***
| Property | Type | Required | Description |
| ----------------- | ----------------- | -------- | -------------------------------------------------- |
| `AREA` | `'area'` | No | Area feature for drawing areas/rectangles |
| `ARROW` | `'arrow'` | No | Arrow feature for drawing arrows |
| `AUDIO_HUDDLE` | `'audioHuddle'` | No | Audio huddle feature for voice conversations |
| `COMMENT` | `'comment'` | No | Comment feature for adding comments |
| `CURSOR` | `'cursor'` | No | Cursor feature for showing user cursors |
| `HUDDLE` | `'huddle'` | No | Huddle feature for video conversations |
| `LIVE_STATE_SYNC` | `'liveStateSync'` | No | Live state sync feature |
| `PRESENCE` | `'presence'` | No | Presence feature for showing online users |
| `TAG` | `'tag'` | No | Tag feature for adding tags |
| `RECORDER` | `'recorder'` | No | Recorder feature for recording sessions |
| `REWRITER` | `'rewriter'` | No | Rewriter feature for text rewriting |
| `LIVE_SELECTION` | `'liveSelection'` | No | Live selection feature for showing user selections |
#### VeltEventMetadata
***
| Property | Type | Required | Description |
| ---------------------- | -------------------------------- | -------- | --------------------- |
| `organizationMetadata` | `OrganizationMetadata` \| `null` | No | Organization metadata |
| `documentMetadata` | `DocumentMetadata` \| `null` | No | Document metadata |
| `location` | `Location` \| `null` | No | Location information |
#### VeltButtonContext
***
| Property | Type | Required | Description |
| ----------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `type` | `'button' \| 'button-toggle' \| 'multi-select' \| 'single-select'` | No | Type of button (default: 'button') |
| `groupId` | `string` | No | ID of the button group |
| `selections` | `VeltButtonSelectionMap` | No | Map of button selections grouped by button groupIds. For buttons without a group, the groupdId will be 'ungrouped' |
| `clickedButtonId` | `string` | No | ID of the clicked button |
#### VeltButtonSelectionMap
***
| Property | Type | Required | Description |
| ------------------- | --------------------------------- | -------- | ------------------------------------ |
| `[groupId: string]` | `{ [buttonId: string]: boolean }` | No | Map of button selections for a group |
#### UpdateDocumentsRequest
***
| Property | Type | Required | Description |
| ---------------- | ----------------------------- | -------- | --------------------------------------------- |
| `organizationId` | `string` | No | Unique identifier for the organization. |
| `folderId` | `string` | No | Unique identifier for the folder. |
| `documents` | `UpdateDocumentMetadata[]` | No | Array of document metadata objects to update. |
#### UpdateDocumentMetadata
***
| Property | Type | Required | Description | |
| --------------- | -------- | -------- | ----------------------------------- | ------------------------------------------------------- |
| `documentId` | `string` | Yes | Unique identifier for the document. | |
| `[key: string]` | \`T | string\` | No | Additional custom properties for the document metadata. |
#### Metadata
***
| Property | Type | Required | Description |
| --------------- | ---------------------- | -------- | ------------------------------------------------------- |
| `apiKey` | `string` | Yes | API key associated with the event. |
| `pageInfo` | `PageInfo` | No | Information about the page where the event occurred. |
| `folderId` | `string` | No | Unique identifier for the folder. |
| `locations` | `object` | No | Object containing location data indexed by location ID. |
| `document` | `DocumentMetadata` | No | Document metadata associated with the event. |
| `organization` | `OrganizationMetadata` | No | Organization metadata associated with the event. |
| `[key: string]` | `any` | No | Additional custom properties. |
#### DocumentMetadata
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | --------------------------------------- |
| `documentId` | `string` | Yes | Unique identifier for the document. |
| `documentName` | `string` | No | Name of the document. |
| `organizationId` | `string` | No | Unique identifier for the organization. |
| `folderId` | `string` | No | Unique identifier for the folder. |
| `[key: string]` | `any` | No | Additional custom properties. |
#### OrganizationMetadata
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | --------------------------------------- |
| `organizationId` | `string` | Yes | Unique identifier for the organization. |
| `[key: string]` | `any` | No | Additional custom properties. |
#### PageInfo
***
| Property | Type | Required | Description |
| ------------- | -------- | -------- | --------------------------------- |
| `baseUrl` | `string` | Yes | Base URL of the page. |
| `path` | `string` | Yes | Path of the page. |
| `queryParams` | `string` | No | Query parameters of the page URL. |
| `title` | `string` | Yes | Title of the page. |
| `url` | `string` | Yes | Full URL of the page. |
#### VeltAuthTokenRequest
***
| Property | Type | Required | Description |
| ---------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey` | `string` | Yes | **API Key**. Must be provided, cannot be empty or whitespace only. |
| `userId` | `string` | Yes | **User ID**. Must be provided, cannot be empty or whitespace only. |
| `userProperties` | `UserProperties` | No | Additional user information to embed in the auth token. See below for details. |
| `permissions` | `{ resources: Resource[] }` | No | Permissions configuration. Defines what resources the user can access and their access levels. If not provided, defaults to no resource access. |
#### UserProperties
***
| Property | Type | Required | Description |
| --------------- | --------- | -------- | ------------------------------------------------------------------------------------ |
| `isAdmin` | `boolean` | No | Whether the user is an admin. |
| `name` | `string` | No | User's display name. If provided, cannot be empty or whitespace only. |
| `email` | `string` | No | User's email address. If provided, cannot be empty and must be a valid email format. |
| `[key: string]` | `any` | No | Allows flexibility for custom user attributes. |
#### Permissions
***
| Property | Type | Required | Description |
| ----------- | ------------ | -------- | ----------------------------------------------------------------------------------------- |
| `resources` | `Resource[]` | No | Array of resources the user has permission to access. Defaults to empty array if not set. |
#### Resource
***
Each resource represents something the user can access (organization, folder, or document).
| Property | Type | Required | Description |
| ---------------- | ------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `'organization' \| 'folder' \| 'document'` | Yes | Resource type. Must be one of: 'organization', 'folder', or 'document'. Determines the scope and level of access. |
| `id` | `string` | Yes | Unique identifier for the specific resource. Cannot be whitespace only. For organization: the organization ID. For folder: the folder ID. For document: the document ID. |
| `organizationId` | `string` | Conditionally | Organization ID. **Required** for `folder` and `document` types. Optional for `organization` type. Must be provided and non-empty for folder/document resources. Links the resource to a specific organization. |
| `expiresAt` | `number` | No | Expiration timestamp (Unix timestamp). If provided, must be a positive integer, greater than the current time, and a valid number. Used for temporary access grants. |
#### BaseMetadata
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | --------------------------------------- |
| `apiKey` | `string` | No | API key associated with the request. |
| `documentId` | `string` | No | Unique identifier for the document. |
| `organizationId` | `string` | No | Unique identifier for the organization. |
| `folderId` | `string` | No | Unique identifier for the folder. |
#### Document
***
| Property | Type | Required | Description |
| ---------- | ------------------ | -------- | ------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the document |
| `metadata` | `DocumentMetadata` | Yes | Metadata associated with the document |
#### SetDocumentsRequestOptions
***
| Property | Type | Required | Description |
| ---------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `organizationId` | `string` | No | Organization ID for the documents |
| `folderId` | `string` | No | Subscribe to all or provided documents in the given folder |
| `locationId` | `string` | No | Filter and subscribe to document data for a specific location |
| `allDocuments` | `boolean` | No | Subscribe to all documents in the folder. Use this when folderId is provided |
| `rootDocumentId` | `string` | No | The unique identifier of the root document. Used to specify the root document when multiple documents are subscribed. |
| `context` | [`SetDocumentsContext`](#setdocumentscontext) | No | Filter comments by custom context fields. Fetches comments matching all provided field values (AND logic across fields). When Permission Provider is enabled with `isContextEnabled: true`, each context value triggers a separate permission request. |
#### FolderMetadata
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | ------------------------------------------ |
| `folderId` | `string` | No | Unique identifier for the folder |
| `parentFolderId` | `string` | No | ID of the parent folder |
| `folderName` | `string` | No | Display name of the folder |
| `createdAt` | `number` | No | Timestamp when folder was created |
| `lastUpdated` | `number` | No | Timestamp when folder was last updated |
| `apiKey` | `string` | No | API key associated with the folder |
| `organizationId` | `string` | No | Organization ID that the folder belongs to |
#### CustomCss
***
| Property | Type | Required | Description |
| -------- | ------------------ | -------- | --------------------------------------------------------------------- |
| `type` | 'link' \| 'styles' | Yes | The type of custom CSS, either a link to a CSS file or inline styles. |
| `value` | string | Yes | The value of the custom CSS, either a URL or CSS styles. |
### Debug Info
#### VeltDebugInfo
***
| Property | Type | Required | Description |
| ------------- | -------------------------------------------------------------------- | -------- | ---------------------------------------------- |
| `veltVersion` | `string` | No | The version of the Velt SDK currently running |
| `apiKey` | `string` | No | The API key used to initialize the Velt client |
| `serverMap` | [`DebugInfoMap`](/api-reference/sdk/models/data-models#debuginfomap) | No | Debug information from the server-side state |
| `clientMap` | [`DebugInfoMap`](/api-reference/sdk/models/data-models#debuginfomap) | No | Debug information from the client-side state |
#### DebugInfoMap
***
| Property | Type | Required | Description |
| -------------- | ------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------ |
| `organization` | [`OrganizationMetadata`](/api-reference/sdk/models/data-models#organizationmetadata) | No | Metadata about the current organization |
| `documents` | [`DocumentMetadata[]`](/api-reference/sdk/models/data-models#documentmetadata) | No | Array of document metadata for all active documents |
| `locations` | [`Location[]`](/api-reference/sdk/models/data-models#location) | No | Array of location information for all active locations |
| `folder` | [`FolderMetadata`](/api-reference/sdk/models/data-models#foldermetadata) | No | Metadata about the current folder |
| `user` | [`User`](/api-reference/sdk/models/data-models#user) | No | The currently authenticated user |
## Location
#### Location
| Property | Type | Required | Description |
| --------------- | --------- | -------- | ----------------------------------------------- |
| `id` | `string` | No | Unique identifier for the location. |
| `locationName` | `string` | No | Name of the location. |
| `version` | `Version` | No | Version information provided by the user. |
| `[key: string]` | `any` | No | Additional dynamic properties for the location. |
#### UpdateLocationsRequest
***
| Property | Type | Required | Description |
| ---------------- | ----------------------------- | -------- | ---------------------------------------------- |
| `organizationId` | `string` | No | Unique identifier for the organization. |
| `documentIds` | `string[]` | No | Array of document IDs to update locations for. |
| `locations` | `UpdateLocationMetadata[]` | No | Array of location metadata objects to update. |
#### UpdateLocationMetadata
***
| Property | Type | Required | Description | |
| --------------- | -------- | -------- | ----------------------------------- | ------------------------------------------------------- |
| `id` | `string` | Yes | Unique identifier for the location. | |
| `[key: string]` | \`T | string\` | No | Additional custom properties for the location metadata. |
#### LocationMetadata
***
| Property | Type | Required | Description |
| ------------ | ------------------ | -------- | ------------------------------------------------------------- |
| `locationId` | number | No | Unique location id generated from client location information |
| `location` | `Location` \| null | No | Location object provided by a client |
#### SetLocationsRequestOptions
***
| Property | Type | Required | Description |
| ---------------- | --------- | -------- | ---------------- |
| `rootLocationId` | `string` | No | Root location. |
| `appendLocation` | `boolean` | No | Merge locations. |
# Self Hosting
#### PartialUser
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ------------------------------ |
| `userId` | `string` | Yes | Unique identifier for the user |
#### PartialReactionAnnotation
***
| Property | Type | Required | Description |
| -------------- | -------------- | -------- | ---------------------------------------- |
| `annotationId` | `string` | Yes | ID of the reaction annotation |
| `metadata` | `BaseMetadata` | No | Additional metadata |
| `icon` | `string` | No | Icon for the reaction |
| `from` | `PartialUser` | No | User who created the reaction annotation |
#### ResolverActions
***
An enum that defines the different types of actions that can trigger resolver events.
| Name | Value | Description |
| --------------------------- | ----------------------------- | ------------------------------------------------------ |
| `COMMENT_ANNOTATION_ADD` | `'comment_annotation.add'` | Triggered when a new comment annotation is added |
| `COMMENT_ANNOTATION_DELETE` | `'comment_annotation.delete'` | Triggered when a comment annotation is deleted |
| `COMMENT_ADD` | `'comment.add'` | Triggered when a new comment is added to an annotation |
| `COMMENT_DELETE` | `'comment.delete'` | Triggered when a comment is deleted from an annotation |
| `COMMENT_UPDATE` | `'comment.update'` | Triggered when a comment is updated |
| `REACTION_ADD` | `'reaction.add'` | Triggered when a reaction is added to a comment |
| `REACTION_DELETE` | `'reaction.delete'` | Triggered when a reaction is removed from a comment |
| `ATTACHMENT_ADD` | `'attachment.add'` | Triggered when an attachment is added to a comment |
| `ATTACHMENT_DELETE` | `'attachment.delete'` | Triggered when an attachment is deleted from a comment |
#### UserResolverModuleName
***
Enum defining module names for user-related resolver operations. Used in data provider events to identify which module triggered the resolver call.
[Self-Host User Data →](/self-host-data/users#debugging)
| Name | Value | Description |
| ------------------------- | ------------------------- | -------------------------------------------------------- |
| `IDENTIFY` | `'identify/authProvider'` | Resolver module for identifying and authenticating users |
| `GET_TEMPORARY_USERS` | `'getTemporaryUsers'` | Resolver module for fetching temporary user data |
| `GET_USERS` | `'getUsers'` | Resolver module for fetching user data |
| `GET_HUDDLE_USERS` | `'getHuddleUsers'` | Resolver module for fetching huddle participant data |
| `GET_SINGLE_EDITOR_USERS` | `'getSingleEditorUsers'` | Resolver module for fetching single editor user data |
#### CommentResolverModuleName
***
Enum defining module names for comment-related resolver operations. Used in data provider events to identify which module triggered the resolver call.
[Self-Host Comment Data →](/self-host-data/comments#debugging)
| Name | Value | Description |
| ------------------------- | ------------------------- | -------------------------------------------------- |
| `SET_DOCUMENTS` | `'setDocuments'` | Resolver module for setting comment documents |
| `GET_COMMENT_ANNOTATIONS` | `'getCommentAnnotations'` | Resolver module for fetching comment annotations |
| `GET_NOTIFICATIONS` | `'getNotifications'` | Resolver module for fetching comment notifications |
#### ReactionResolverModuleName
***
Enum defining module names for reaction-related resolver operations. Used in data provider events to identify which module triggered the resolver call.
[Self-Host Reaction Data →](/self-host-data/reactions#debugging)
| Name | Value | Description |
| -------------------------- | -------------------------- | ------------------------------------------------- |
| `SET_DOCUMENTS` | `'setDocuments'` | Resolver module for setting reaction documents |
| `GET_REACTION_ANNOTATIONS` | `'getReactionAnnotations'` | Resolver module for fetching reaction annotations |
#### PartialComment
***
| Property | Type | Required | Description |
| -------------------- | ----------------------------------------------- | -------- | ------------------------------------------------ |
| `commentId` | `string \| number` | Yes | Unique identifier for the comment |
| `commentHtml` | `string` | No | HTML content of the comment |
| `commentText` | `string` | No | Plain text content of the comment |
| `attachments` | `{ [attachmentId: number]: PartialAttachment }` | No | Map of attachment IDs to partial attachment data |
| `from` | `PartialUser` | No | User who created the comment |
| `to` | `PartialUser[]` | No | Users the comment is directed to |
| `taggedUserContacts` | `PartialTaggedUserContacts[]` | No | Tagged user contacts in the comment |
#### PartialTaggedUserContacts
***
| Property | Type | Required | Description |
| --------- | ------------- | -------- | ------------------------------------- |
| `userId` | `string` | Yes | Unique identifier for the tagged user |
| `contact` | `PartialUser` | No | Contact details of the tagged user |
| `text` | `string` | No | Display text for the tagged user |
#### PartialCommentAnnotation
***
| Property | Type | Required | Description |
| -------------- | -------------------------------- | -------- | ------------------------------------------- |
| `annotationId` | `string` | Yes | ID of the comment annotation |
| `metadata` | `BaseMetadata` | No | Additional metadata |
| `comments` | `Record` | Yes | Map of comment IDs to partial comments data |
#### PartialAttachment
***
| Property | Type | Required | Description |
| -------------- | -------- | -------- | -------------------------------- |
| `url` | `string` | Yes | URL of the attachment |
| `name` | `string` | Yes | Name of the attachment |
| `attachmentId` | `number` | Yes | Unique identifier for attachment |
#### ResolverAttachment
***
| Property | Type | Required | Description |
| -------------- | ---------------------------- | -------- | -------------------------------- |
| `attachmentId` | `number` | Yes | Unique identifier for attachment |
| `file` | `File` | Yes | File to be uploaded |
| `name` | `string` | No | File name |
| `metadata` | `AttachmentResolverMetadata` | No | Metadata of the attachment |
| `mimeType` | `string` | No | Mime type of the attachment |
#### AttachmentResolverMetadata
***
| Property | Type | Required | Description |
| --------------------- | ---------------- | -------- | ---------------------------- |
| `organizationId` | `string \| null` | Yes | ID of the organization |
| `documentId` | `string \| null` | Yes | ID of the document |
| `folderId` | `string \| null` | No | ID of the folder |
| `attachmentId` | `number \| null` | Yes | ID of the attachment |
| `commentAnnotationId` | `string \| null` | Yes | ID of the comment annotation |
| `apiKey` | `string \| null` | Yes | API key for authentication |
#### VeltDataProvider
***
| Property | Type | Required | Description |
| --------------- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------- |
| `comment` | `CommentAnnotationDataProvider` | No | Provider for comment annotation data |
| `user` | `UserDataProvider` | No | Provider for user data |
| `reaction` | `ReactionAnnotationDataProvider` | No | Provider for reaction annotation data |
| `attachment` | `AttachmentDataProvider` | No | Provider for file attachment data |
| `anonymousUser` | [`AnonymousUserDataProvider`](#anonymoususerdataprovider) | No | Provider to resolve email → userId mappings for anonymous users tagged by email in comments. |
#### ResolverEndpointConfig
***
Config-based resolver endpoint configuration. SDK handles HTTP requests, headers, and response formatting automatically.
| Property | Type | Required | Description |
| --------- | ------------------------ | -------- | ------------------------------------------- |
| `url` | `string` | Yes | Backend endpoint URL for resolver operation |
| `headers` | `Record` | No | Custom HTTP headers for the request |
#### ResolverConfig
***
| Property | Type | Required | Description |
| -------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------- |
| `resolveTimeout` | `number` | No | Timeout duration (in milliseconds) for resolver operations |
| `saveRetryConfig` | `RetryConfig` | No | Retry configuration for save operations |
| `deleteRetryConfig` | `RetryConfig` | No | Retry configuration for delete operations |
| `getRetryConfig` | `RetryConfig` | No | Retry configuration for get operations. Currently not supported for UserDataProvider. |
| `resolveUsersConfig` | `ResolveUsersConfig` | No | Configuration for resolving users |
| `getConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for fetch operations |
| `saveConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for save operations |
| `deleteConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for delete operations |
#### ResolverResponse
***
Generic response format for backend endpoints and data providers.
**Permission Provider Update (v4.5.8-beta.2)**: For Permission Provider backend endpoints, the `signature` field is no longer required. The SDK now handles validation internally.
| Property | Type | Required | Description |
| ------------ | --------- | -------- | -------------------------------------------------------------------------------- |
| `data` | `T` | No | Response data of generic type T |
| `success` | `boolean` | Yes | Whether the operation was successful. Must be `true` for successful responses |
| `message` | `string` | No | Optional message describing the result |
| `timestamp` | `number` | No | Optional timestamp of the response |
| `statusCode` | `number` | Yes | HTTP status code. Must be `200` for Velt to accept the response |
| `signature` | `string` | No | Cryptographic signature (deprecated for Permission Provider as of v4.5.8-beta.2) |
#### RetryConfig
***
| Property | Type | Required | Description |
| ----------------- | --------- | -------- | -------------------------------------------- |
| `retryCount` | `number` | No | Number of retry attempts |
| `retryDelay` | `number` | No | Delay between retry attempts in milliseconds |
| `revertOnFailure` | `boolean` | No | Whether to revert changes on failure |
#### ResolveUsersConfig
***
| Property | Type | Required | Description |
| -------------- | --------- | -------- | ------------------------------------- |
| `organization` | `boolean` | No | Whether to resolve organization users |
| `folder` | `boolean` | No | Whether to resolve folder users |
| `document` | `boolean` | No | Whether to resolve document users |
#### CommentAnnotationDataProvider
***
| Property | Type | Required | Description |
| -------- | ------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------- |
| `get` | `(request: GetCommentResolverRequest) => Promise>>` | Yes | Function to fetch comment annotations |
| `save` | `(request: SaveCommentResolverRequest) => Promise>` | Yes | Function to save comment annotations |
| `delete` | `(request: DeleteCommentResolverRequest) => Promise>` | Yes | Function to delete comment annotations |
| `config` | `ResolverConfig` | No | Configuration for the data provider |
#### ReactionAnnotationDataProvider
***
| Property | Type | Required | Description |
| -------- | --------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------- |
| `get` | `(request: GetReactionResolverRequest) => Promise>>` | Yes | Function to fetch reaction annotations |
| `save` | `(request: SaveReactionResolverRequest) => Promise>` | Yes | Function to save reaction annotations |
| `delete` | `(request: DeleteReactionResolverRequest) => Promise>` | Yes | Function to delete reaction annotations |
| `config` | `ResolverConfig` | No | Configuration for the data provider |
#### UserDataProvider
***
| Property | Type | Required | Description |
| -------- | ------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `get` | `(userIds: string[]) => Promise \| ResolverResponse>>` | No | Function to fetch user data by user IDs. Both response formats are supported for backward compatibility. |
| `config` | `ResolverConfig` | No | Configuration for the data provider. Use `getConfig` for config-based approach. |
#### GetUserResolverRequest
***
Request format used by config-based user resolver endpoints.
| Property | Type | Required | Description |
| ---------------- | ---------- | -------- | -------------------------- |
| `organizationId` | `string` | Yes | ID of the organization |
| `userIds` | `string[]` | Yes | Array of user IDs to fetch |
#### AttachmentDataProvider
***
| Property | Type | Required | Description |
| -------- | --------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- |
| `save` | `(request: SaveAttachmentResolverRequest) => Promise>` | Yes | Function to save attachment data |
| `delete` | `(request: DeleteAttachmentResolverRequest) => Promise>` | Yes | Function to delete attachment data |
| `config` | `ResolverConfig` | No | Configuration for the data provider |
#### SaveAttachmentResolverData
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | --------------------------- |
| `url` | `string` | Yes | URL of the saved attachment |
#### AnonymousUserDataProvider
***
| Property | Type | Required | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ |
| `resolveUserIdsByEmail` | `(request:` [`ResolveUserIdsByEmailRequest`](#resolveuseridsbyemailrequest)`) => Promise>>` | Yes | Callback to resolve email addresses to user IDs. |
| `config` | [`AnonymousUserDataProviderConfig`](#anonymoususerdataproviderconfig) | No | Optional configuration for timeout and retry. |
#### AnonymousUserDataProviderConfig
***
| Property | Type | Required | Description |
| ---------------- | ----------------------------- | -------- | ------------------------------------------------------- |
| `resolveTimeout` | `number` | No | Timeout in milliseconds for the resolve call. |
| `getRetryConfig` | [`RetryConfig`](#retryconfig) | No | Retry configuration with `retryCount` and `retryDelay`. |
#### ResolveUserIdsByEmailRequest
***
| Property | Type | Required | Description |
| ---------------- | ---------- | -------- | ------------------------------------ |
| `organizationId` | `string` | Yes | The organization ID. |
| `documentId` | `string` | No | The document ID. |
| `folderId` | `string` | No | The folder ID. |
| `emails` | `string[]` | Yes | Array of email addresses to resolve. |
# Presence
#### PresenceUser
***
| Property | Type | Required | Description |
| ------------------ | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `userId` | `string` | Yes | Unique user identifier |
| `name` | `string` | No | User's full name (Default: Random avatar name) |
| `email` | `string` | No | User's email address |
| `photoUrl` | `string` | No | User's display picture URL (Default: Random avatar image) |
| `onlineStatus` | `string` | Yes | Online status (active, away, offline) (Auto generated) |
| `color` | `string` | No | Assigned color for the user (Auto generated) |
| `timestamp` | `any` | Yes | Server Timestamp |
| `type` | `string` | No | User type |
| `selections` | `any` | No | User selections |
| `documentParamsId` | `number \| null` | No | Deprecated unique document params ID |
| `documentParams` | `object \| null` | No | Deprecated document params |
| `locationId` | `number \| null` | No | Unique location ID |
| `location` | `Location \| null` | No | Location of user on sub document |
| `isReadOnly` | `boolean` | No | Indicates if user is readonly |
| `isAnonymous` | `boolean` | No | If user can only view comments (Anonymous) |
| `pageInfo` | `PageInfo` | Yes | Information about the page |
| `isUserIdle` | `boolean` | No | Indicates if user is idle. This is based on the `inactivityTime` configured in the Presence feature. (Auto generated) |
| `isTabAway` | `boolean` | No | Indicates if user's tab is unfocused. (Auto generated) |
#### PresenceUserStateChangeEvent
***
This event object is emitted when a user's online status changes to online.
| Property | Type | Required | Description |
| -------- | -------------- | -------- | ----------------------------------------------------------------------- |
| `user` | `PresenceUser` | Yes | The current user's Presence object. |
| `state` | `string` | Yes | The new presence state of the user (e.g., `online`, `offline`, `away`). |
#### ENUMs
| Enum Name | Event Type | Description |
| ------------------- | ----------------- | ------------------------------------------------------------------------- |
| `USER_STATE_CHANGE` | `userStateChange` | Triggered when a user's online status changes to online, offline, or away |
#### PresenceRequestQuery
***
| Property | Type | Required | Description |
| ---------------- | ---------- | -------- | ---------------------------------------------------------------------------- |
| `documentId` | `string` | No | ID of the document to query presence for. |
| `organizationId` | `string` | No | ID of the organization to query presence for. |
| `statuses` | `string[]` | No | Array of user statuses to filter by (e.g., `['online', 'away', 'offline']`). |
#### GetPresenceDataResponse
***
| Property | Type | Required | Description |
| -------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------- |
| `data` | `PresenceUser[] \| null` | Yes | Array of [PresenceUser](/api-reference/sdk/models/data-models#presenceuser) objects. `null` while loading. |
#### HeartbeatConfig
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `userId` | `string` | No | User ID to retrieve heartbeat data for. If not provided, returns heartbeat data for the current user. |
#### GetHeartbeatResponse
***
| Property | Type | Required | Description |
| -------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------- |
| `data` | `Heartbeat[] \| null` | Yes | Array of heartbeat data for the specified user. Returns null if no heartbeat data is available. |
# Webhooks
#### WebhookV2Payload
***
| Property | Type | Required | Description |
| -------------------------------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- |
| `event` | `string` | Yes | The event type that triggered the webhook. |
| `actionType` | `string` | Yes | The specific action that occurred. |
| `source` | `string` | Yes | The source of the event. |
| `data` | `CommentPayload \| HuddlePayload \| CRDTPayload` | Yes | The payload data containing event-specific information. |
| `webhookId` | `string` | Yes | Unique identifier for the webhook. |
| `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences keyed by userId. |
| `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences keyed by userId. |
#### WebhookV2PayloadEncoded
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | ------------------------------- |
| `encodedPayload` | `string` | Yes | Base64 encoded webhook payload. |
#### WebhookV2PayloadEncrypted
***
| Property | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------------------- |
| `encryptedData` | `string` | Yes | Encrypted webhook data. |
| `encryptedKey` | `string` | Yes | Encrypted encryption key. |
| `iv` | `string` | Yes | Initialization vector for decryption. |
#### CommentPayload
***
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ---------------------------------------------------------- |
| `commentAnnotation` | `CommentAnnotation` | No | The comment annotation associated with the event. |
| `targetComment` | `Comment` | No | The target comment for the event. |
| `actionUser` | `User` | No | The user who performed the action. |
| `metadata` | `Metadata` | No | Additional metadata about the event context. |
| `oldStatus` | `CommentStatus` | No | Previous status of the comment (for status change events). |
| `newStatus` | `CommentStatus` | No | New status of the comment (for status change events). |
| `newPriority` | `CommentPriority` | No | New priority of the comment (for priority change events). |
#### HuddlePayload
***
| Property | Type | Required | Description |
| ------------ | ---------- | -------- | -------------------------------------------- |
| `actionUser` | `User` | No | The user who performed the action. |
| `metadata` | `Metadata` | No | Additional metadata about the event context. |
#### CRDTPayload
***
| Property | Type | Required | Description |
| ------------------------ | ---------------- | -------- | ---------------------------------------------------------------------------- |
| `actionUser` | `User` | No | The user who performed the action. |
| `metadata` | `Metadata` | No | Additional metadata about the event context. |
| `crdtData` | `object` | Yes | Contains the CRDT data and update information. |
| `crdtData.id` | `string` | Yes | The editor/store ID for the CRDT instance. |
| `crdtData.data` | `unknown` | Yes | The CRDT data. Can be any supported type: array, map, text, xml, or xmltext. |
| `crdtData.lastUpdatedBy` | `string` | Yes | User ID who made the update. |
| `crdtData.sessionId` | `string \| null` | No | Session ID if available. |
| `crdtData.lastUpdate` | `string` | Yes | Timestamp of the last update. |
#### WebhookV1Payload
***
All basic webhook payloads share these common fields:
| Property | Type | Required | Description |
| -------------------------------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- |
| `webhookId` | `string` | Yes | Unique identifier for the webhook. |
| `actionType` | `string` | Yes | The specific action that occurred in the event. |
| `notificationSource` | `string` | Yes | Source of the notification: `comment`, `huddle`, or `crdt`. |
| `actionUser` | `User` | No | The user who performed the action. |
| `metadata` | `Metadata` | No | Additional metadata providing context for the event. |
| `platform` | `'sdk'` | No | Set to `'sdk'` if the event originated from SDK actions. |
| `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences keyed by userId. |
| `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences keyed by userId. |
#### WebhookV1PayloadEncoded
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | ------------------------------- |
| `encodedPayload` | `string` | Yes | Base64 encoded webhook payload. |
#### WebhookV1PayloadEncrypted
***
| Property | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------------------- |
| `encryptedData` | `string` | Yes | Encrypted webhook data. |
| `encryptedKey` | `string` | Yes | Encrypted encryption key. |
| `iv` | `string` | Yes | Initialization vector for decryption. |
**Comment Basic Webhook Payload**
Additional fields present when `notificationSource` is `comment`:
| Property | Type | Required | Description |
| ------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `commentAnnotation` | `CommentAnnotation` | Yes | The comment annotation associated with the event. |
| `targetComment` | `Comment` | No | The target comment. Not present for annotation-level events (e.g., resolve, delete thread). |
| `newPriority` | `CommentPriority` | No | New priority. Present on `priorityChanged` events. |
| `oldStatus` | `CommentStatus` | No | Previous status. Present on `statusChanged` events. |
| `newStatus` | `CommentStatus` | No | New status. Present on `statusChanged` events. |
| `assigned` | `boolean` | No | Whether the comment is assigned. Present on `assigned` events. |
**Huddle Basic Webhook Payload**
No additional fields beyond the common fields when `notificationSource` is `huddle`.
**CRDT Basic Webhook Payload**
Additional fields present when `notificationSource` is `crdt`:
| Property | Type | Required | Description |
| ------------------------ | ---------------- | -------- | ---------------------------------------------------------------------------- |
| `crdtData` | `object` | Yes | Contains the CRDT data and update information. |
| `crdtData.id` | `string` | Yes | The editor/store ID for the CRDT instance. |
| `crdtData.data` | `unknown` | Yes | The CRDT data. Can be any supported type: array, map, text, xml, or xmltext. |
| `crdtData.lastUpdatedBy` | `string` | Yes | User ID who made the update. |
| `crdtData.sessionId` | `string \| null` | No | Session ID if available. |
| `crdtData.lastUpdate` | `string` | Yes | Timestamp of the last update. |
| `accessDeniedUsers` | `array` | No | List of users denied access. |
#### UserNotificationsConfig
***
Per-user notification preferences included in webhook payloads when a notification config scope is active. Exactly one of the two fields is present per payload depending on whether org-level or document-level config is in use.
| Property | Type | Required | Description |
| -------------------------------------- | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------ |
| `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences, keyed by userId. |
| `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences, keyed by userId. |
#### NotificationChannelConfig
***
Per-channel notification preference map for a single user. Keys are channel identifiers; values are the preference level for that channel.
```typescript theme={null}
type NotificationChannelConfig = Record;
```
| Key (channel) | Value | Description |
| ------------- | --------------------------- | ------------------------------------- |
| `inbox` | `'ALL' \| 'MINE' \| 'NONE'` | In-app inbox notification preference. |
| `email` | `'ALL' \| 'MINE' \| 'NONE'` | Email notification preference. |
| Value | Description |
| ------ | -------------------------------------------------------------------- |
| `ALL` | Receive notifications for all activity. |
| `MINE` | Receive notifications only for activity directly involving the user. |
| `NONE` | Receive no notifications for this channel. |
# Misc
#### RequestOptions
***
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ----------- |
| `documentId` | `string` | No | Document ID |
#### CommentSelectionChangeData
***
| Property | Type | Required | Description |
| ------------ | ------------------- | -------- | -------------------------------------- |
| `selected` | `boolean` | Yes | Whether a comment is selected |
| `annotation` | `CommentAnnotation` | Yes | Object data of the selected annotation |
#### ContactListScopeForOrganizationUsers Enum
***
| Enum Name | Event Type | Description |
| ------------------------- | ----------------------- | ------------------------------ |
| `ALL` | `all` | Show all the contacts |
| `ORGANIZATION` | `organization` | Show organization contacts. |
| `ORGANIZATION_USER_GROUP` | `organizationUserGroup` | Show organization user groups. |
| `DOCUMENT` | `document` | Show document contacts. |
#### CursorUser
***
| Property | Type | Required | Description |
| -------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------- |
| `userId` | `string` | Yes | Unique user identifier that you use to identify your user. |
| `name` | `string` | No | Your user's full name. Default: Random avatar name. |
| `email` | `string` | No | Your user's email address. |
| `photoUrl` | `string` | No | Your user's display picture URL. Default: Random avatar image. |
| `comment` | `string` | No | Short comment that user can add to their live cursor. |
| `onlineStatus` | `string` | Yes | User's online status (active, inactive, offline). Auto generated. |
| `color` | `string` | No | A random color assigned to the user for the session, used on avatar border/live cursor. |
| `timestamp` | `any` | Yes | Server Timestamp. |
| `type` | `string` | No | User type. |
| `locationId` | `number \| null` | No | Unique location id from provided location. |
| `location` | `Location \| null` | No | Location to identify user on sub document. |
| `position` | `CursorPosition \| null` | No | User's cursor position on their screen. |
| `isReadOnly` | `boolean` | No | Indicates if user is readonly. |
| `isAnonymous` | `boolean` | No | Indicates if user is anonymous and can only view comments. |
#### FlockOptions
***
| Property | Type | Required | Description |
| -------------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useHistoryAPI` | `boolean` | Yes | Indicates whether the application should use the HTML5 History API for navigation |
| `onNavigate` | `(url: PageInfo) => void` | No | A callback function that is called when navigation occurs. It takes a `PageInfo` object as its argument, which contains details about the new page |
| `disableDefaultNavigation` | `boolean` | Yes | If `true`, the application's default navigation handling is disabled, perhaps to be managed manually or by another system |
| `darkMode` | `boolean` | Yes | A flag indicating whether the application should display in dark mode, a display preference that may be more comfortable for users in low-light conditions |
#### Version
***
| Property | Type | Required | Description |
| -------- | ------ | -------- | --------------------------------- |
| `id` | string | Yes | Unique identifier for the version |
| `name` | string | Yes | Name of the version |
#### displayHeadlineMessageTemplateData
***
| Property | Type | Required | Description |
| --------------- | -------- | -------- | --------------------------------------- |
| `actionUser` | `User` | No | The user who performed the action |
| `recipientUser` | `User` | No | The user receiving the notification |
| `actionMessage` | `string` | No | The message describing the action |
| `project` | `string` | No | The project related to the notification |
| `[key: string]` | `any` | No | Any additional custom properties |
#### PageInfo
***
| Property | Type | Required | Description |
| ------------- | -------- | -------- | -------------------------------------- |
| `url` | `string` | No | URL of the webpage |
| `path` | `string` | No | Path of the webpage excluding base url |
| `baseUrl` | `string` | No | Base URL (domain) of a webpage |
| `title` | `string` | No | Title of the webpage |
| `commentUrl` | `string` | No | Reference url of a comment annotation |
| `recorderUrl` | `string` | No | Reference url of a recorder annotation |
| `screenWidth` | `number` | No | User's screen width. Auto generated. |
#### `getThumbnailTag` Method
The `getThumbnailTag` method takes an optional `url` parameter and returns an HTML string. It creates an anchor tag linking to the `videoPlayerUrl` and embeds an image tag using either the provided `url`, `thumbnailWithPlayIconUrl`, or `thumbnailUrl` (in that order of preference).
#### RewriterAnnotation
***
| Property | Type | Required | Description |
| ------------------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------- |
| `annotationId` | String | Yes | Unique identifier for the rewriter annotation, automatically generated. |
| `from` | `User` | Yes | The user who created this rewriter annotation. |
| `color` | String | No | Color used for the rewriter annotation. |
| `lastUpdated` | Any | No | Timestamp when the rewriter annotation was last updated, automatically generated. |
| `documentParamsId` | Number \| null | No | Unique document params ID, deprecated, use `locationId` instead. |
| `documentParams` | `Location` \| null | No | Document params to identify user on sub document, deprecated, use `location` instead. |
| `locationId` | Number \| null | No | Unique location ID generated from provided location. |
| `location` | Location \| null | No | Set location to identify user on sub document. |
| `type` | String | No | Type of annotation. |
| `rewriterType` | String | Yes | Type of rewriter for the annotation, either 'generic' or 'copywriter'. |
| `targetTextRange` | TargetTextRange \| null | No | Selected text range of rewriter annotation. |
| `annotationIndex` | Number | No | Index of the current annotation in the list of annotations. |
| `pageInfo` | `PageInfo` | No | Information about the page where the annotation is made. |
| `selectedRewriterOption` | String | No | Selected rewriter option used in the annotation. |
#### SyncVideoPlayer
***
| Property | Type | Required | Description |
| ------------------ | -------------------- | -------- | ----------------------------------------------------- |
| `playerId` | String | No | The identifier for the video player instance. |
| `src` | String | No | The source URL of the video. |
| `sources` | String\[] | No | An array of source URLs for the video. |
| `lastUpdated` | Number | No | The timestamp of when the player was last updated. |
| `lastUpdatedBy` | `User` | No | The user who last updated the player. |
| `lastUpdatedEvent` | String | No | The name of the event that triggered the last update. |
| `playerState` | SyncVideoPlayerState | Yes | The state object of the video player. |
#### SyncVideoPlayerState
***
| Property | Type | Required | Description |
| ------------- | ------- | -------- | -------------------------------------------- |
| `playing` | Boolean | No | Indicates if the video is currently playing. |
| `currentTime` | Number | No | The current playback time of the video. |
| `muted` | Boolean | No | Indicates if the video is muted. |
| `volume` | Number | No | The volume level of the video. |
| `speed` | Number | No | The playback rate of the video. |
#### Toast
***
| Property | Type | Required | Default Value | Description |
| ---------- | -------------------- | -------- | ------------- | ------------------------------------------------------------------------ |
| `id` | Number | No | None | A unique identifier for the toast notification. |
| `message` | String | Yes | None | The message content displayed in the toast notification. |
| `type` | 'success' \| 'error' | Yes | None | The type of toast notification, indicating success or error. |
| `duration` | Number | No | 3000 | The length of time the toast notification is displayed, in milliseconds. |
#### Transcription
***
| Property | Type | Required | Description |
| ------------------ | ------ | -------- | ----------------------------------------------------- |
| `from` | User | Yes | The user who created the transcription. |
| `lastUpdated` | Number | No | Timestamp of when the transcription was last updated. |
| `transcriptedText` | String | No | The text that has been transcribed. |
#### User
***
| Property | Type | Required | Description |
| ---------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `userId` | string | Yes | Unique user identifier used to identify your user. |
| `name` | string | No | The full name of your user. Defaults to a random avatar name if not provided. |
| `photoUrl` | string | No | The display picture URL of your user. Defaults to a random avatar image if not provided. |
| `email` | string | No | Required for sending email or Slack notifications to users about comments and mentions. |
| `plan` | string | No | The product plan the user is on. |
| `organizationId` | string | Yes | organizationId to which the user belongs. |
| `color` | string | No | A color assigned to the user for the current session, used for avatar border, live cursor, selection etc. |
| `textColor` | string | No | Used in the text color of the user's intial when photoUrl is not present. |
| `type` | string | No | The type of user. |
| `isReadOnly` | boolean | No | Indicates if the user has read-only access. |
| `isAnonymous` | boolean | No | Indicates if the user is anonymous and can only view comments. |
| `isGuest` | boolean | No | Indicates if the user is a guest. |
| `isAdmin` | boolean | No | Use this to set the user as an admin. You also need to ensure that the jwt token you generate also has this property set to true. |
| `groupId` | string | No | \[DEPRECATED] A domain name or identifier used to cluster a group of users who work together. |
| `clientGroupId` | string | No | \[DEPRECATED] The original groupId provided by the user. |
| `initial` | string | No | First letter of the user's first name. |
| `accessRole` | "viewer" \| "editor" | No | Optional access role for this resource. Allowed values: “viewer” \| “editor”. Default: "editor". |
**Access Control**
* Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource.
* `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`.
* Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`.
* See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
#### UserOptions
***
| Property | Type | Required | Description |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `replaceContacts` | boolean | No | If set to true, it will replace the user's personal and group contacts with the ones provided. |
| `authToken` | string | No | The authentication token of the user. |
| `throwError` | boolean | No | If true, throws error if user authentication fails. Default: false. |
#### UserContact
***
A user object in a contact-selection context, such as autocomplete panels and assignment pickers. Shares the same shape as [`User`](#user).
#### UserContactSelectedPayload
***
| Property | Type | Required | Description |
| ----------------------- | ----------------------------- | -------- | ------------------------------------- |
| `contact` | [`UserContact`](#usercontact) | Yes | Selected user contact details. |
| `isOrganizationContact` | boolean | Yes | Is user part of organization contact. |
| `isDocumentContact` | boolean | Yes | Is user part of document contact. |
| `documentAccessType` | string | Yes | Document access type. |
#### UserContactUs
***
| Property | Type | Required | Description |
| ------------- | ------------------------ | -------- | ------------------------------------------------ |
| `id` | string | No | Unique identifier of the feedback. |
| `apiKey` | string \| null | No | API key of the client. |
| `emailId` | string | No | Email address of the feedback provider. |
| `message` | string | No | Content of the user's feedback message. |
| `from` | User \| null | No | User who submitted the feedback. |
| `lastUpdated` | any | No | Timestamp of when the feedback was last updated. |
| `metadata` | DocumentMetadata \| null | No | Metadata associated with the document. |
| `pageInfo` | PageInfo | No | Information about the user's current page. |
#### UserFeedback
***
| Property | Type | Required | Description |
| ------------- | ------------------------ | -------- | ------------------------------------------------ |
| `id` | string | No | Unique identifier of the feedback. |
| `apiKey` | string \| null | No | API key of the client. |
| `emailId` | string | No | Email address of the feedback provider. |
| `message` | string | No | Content of the user's feedback message. |
| `from` | User \| null | No | User who submitted the feedback. |
| `lastUpdated` | any | No | Timestamp of when the feedback was last updated. |
| `metadata` | DocumentMetadata \| null | No | Metadata associated with the document. |
| `pageInfo` | PageInfo | No | Information about the user's current page. |
#### UnreadCommentsCount
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ----------------------------------------- |
| `count` | `number` | Yes | The number of unread comments or threads. |
#### UserGroup
***
| Property | Type | Required | Description |
| ----------- | -------- | -------- | ---------------------------------------- |
| `groupId` | `string` | Yes | Unique identifier for the user group |
| `groupName` | `string` | Yes | Display name of the user group |
| `users` | `User[]` | No | Array of users that belong to this group |
#### VeltResetButtonStateConfig
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ------------------------------------------------------------------------------- |
| `id` | `string` | No | The ID of the button to reset. If not provided, resets all buttons |
| `group` | `string` | No | The group ID of buttons to reset. If not provided, resets buttons in all groups |
#### VeltAuthProvider
***
| Property | Type | Required | Description |
| --------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `user` | `User` | Yes | The user object to authenticate. |
| `options` | `Options` | No | Additional options for authentication (e.g., `authToken`, `forceReset`). |
| `retryConfig` | `{ retryCount?: number; retryDelay?: number; }` | No | Configuration for retrying token generation (number of retries and delay in ms). |
| `generateToken` | `() => Promise` | No | Async function to generate a Velt JWT token. Called automatically when a token is required. |
#### AuthRetryConfig
***
| Property | Type | Required | Description |
| ------------ | -------- | -------- | ----------------------------------------------------- |
| `retryCount` | `number` | No | Number of times to retry token generation on failure. |
| `retryDelay` | `number` | No | Delay in milliseconds between retry attempts. |
#### RevokeAccessOn
***
Configuration for automatic access revocation triggers.
| Property | Type | Required | Description |
| -------------------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `type` | [RevokeAccessOnType](#revokeaccessontype) | Yes | Type of trigger that will revoke access. Options: `document_unset` or `user_logout` |
| `revokeOrganizationAccess` | `boolean` | No | Whether to also revoke organization-level permissions when triggered. Default: `false` |
#### RevokeAccessOnType
***
Enum specifying when to automatically revoke permissions.
| Value | Description |
| ---------------- | ---------------------------------------------------- |
| `DOCUMENT_UNSET` | Revoke access when user unsets or leaves a document |
| `USER_LOGOUT` | Revoke access when user logs out of the organization |
#### PermissionSource
***
Enum identifying which SDK method triggered the permission check. This helps debug and trace permission request origins.
| Value | Description |
| ------------------- | ----------------------------------------------------- |
| `SET_DOCUMENTS` | Permission check triggered by `setDocuments()` method |
| `IDENTIFY` | Permission check triggered by `identify()` method |
| `GET_NOTIFICATIONS` | Permission check triggered by notifications fetching |
| `SET_NOTIFICATIONS` | Permission check triggered by notifications setting |
#### PermissionResourceType
***
Enum defining the types of resources that can be validated through Permission Provider. Used in permission queries to identify the resource type being accessed.
| Value | Description |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `ORGANIZATION` | `organization`: Organization-level resource permissions |
| `DOCUMENT` | `document`: Document-level resource permissions |
| `LOCATION` | `location`: Location-specific resource permissions within a document |
| `CONTEXT` | `context`: Context-based resource permissions. Added in v4.5.8-beta.4 for granular context-level access control when `isContextEnabled: true` |
#### VeltPermissionProvider
***
Configuration interface for Permission Provider. Velt validates access requests in real-time by querying your backend endpoint configured in the [Velt Console](https://console.velt.dev). The SDK automatically handles permission caching, validation, and synchronization.
| Property | Type | Required | Description |
| ------------------ | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `isContextEnabled` | `boolean` | No | Enable context-based permission requests. When enabled, the backend receives individual permission requests for each context value when using context filtering. Default: `false`. Added in v4.5.8-beta.4. |
| `retryConfig` | [AuthRetryConfig](#authretryconfig) | No | Configuration for retrying failed permission requests. Defaults to 3 retries with 2000ms delay. |
| `forceRefresh` | `boolean` | No | Set to `true` if access control changes frequently. Forces re-validation on each access check in the current session. Default: `false` |
| `revokeAccessOn` | [RevokeAccessOn\[\]](#revokeaccesson) | No | Configure automatic access revocation triggers. Revokes permissions when specified events occur (e.g., document unset or user logout). |
#### PermissionQuery
***
Request structure for permission queries sent to the Permission Provider.
| Property | Type | Required | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `userId` | `string` | Yes | ID of the user requesting access to the resource. |
| `resource` | `{ type:` [PermissionResourceType](#permissionresourcetype)`; id: string; source:` [PermissionSource](#permissionsource)`; organizationId: string; context?:` [Context](#context) `}` | Yes | Resource the user is requesting access to. The `type` uses [`PermissionResourceType`](#permissionresourcetype) enum. The `source` field identifies which SDK method triggered the permission check. The optional `context` field is present only when `isContextEnabled: true` and contains context values set during setDocuments. Includes `organizationId` for context. |
#### PermissionResult
***
Individual permission decision for a user's access to a specific resource.
| Property | Type | Required | Description |
| ---------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `userId` | `string` | Yes | Unique identifier of the user requesting access. |
| `resourceId` | `string` | Yes | Unique identifier of the resource being accessed. |
| `type` | [PermissionResourceType](#permissionresourcetype) | Yes | Type of resource being accessed. Can be `organization`, `document`, `location`, or `context`. |
| `organizationId` | `string` | Yes | Organization ID associated with the resource. |
| `accessRole` | [UserPermissionAccessRole](#userpermissionaccessrole) | No | Access role granted to the user for this resource. |
| `expiresAt` | `number` | No | Unix timestamp (in milliseconds) when the permission expires. |
| `hasAccess` | `boolean` | Yes | Whether the user has access to the requested resource. |
#### SignatureResult
***
Response structure returned from the [Generate Signature API](/api-reference/rest-apis/v2/auth/generate-signature).
| Property | Type | Required | Description |
| ----------------------- | -------- | -------- | ------------------------------------------- |
| `result.status` | `string` | Yes | Status of the response. Always `"success"`. |
| `result.message` | `string` | Yes | Success message. |
| `result.data.signature` | `string` | Yes | Generated authorization signature string. |
**Example:**
```json theme={null}
{
"result": {
"status": "success",
"message": "Signature generated successfully.",
"data": {
"signature": "03638f2191bf59c0e536e5b31cbde86df5f44b03fc8e82ee9a8bed7eb324f252"
}
}
}
```
#### PermissionData
***
Individual permission decision for a user-resource pair.
| Property | Type | Required | Description |
| ------------ | ------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `userId` | `string` | Yes | ID of the user this permission applies to. |
| `resourceId` | `string` | Yes | ID of the resource (document, folder, or organization). |
| `type` | `'document' \| 'folder' \| 'organization'` | Yes | Type of the resource. |
| `hasAccess` | `boolean` | Yes | Whether the user has access to the resource. |
| `accessRole` | `'viewer' \| 'editor'` | No | Access role for the user. Only applicable for document resources. `viewer` can view and comment, `editor` can edit content. |
| `expiresAt` | `number` | No | UTC timestamp in milliseconds when this permission expires. Velt will revalidate access after expiration. |
#### Context
***
The `Context` interface is used in Permission Provider backend requests for context-based permission validation. Each context value is sent as an individual permission request.
| Property | Type | Required | Description |
| -------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access` | `{ [key: string]: string \| number }` | Yes | Key-value pairs for context-based permissions. Keys are custom field names, values are single strings or numbers representing the specific context value being validated. |
**Usage:** The `Context` interface is used in:
* Backend Permission Provider requests when `isContextEnabled: true`
* Each context value from frontend methods triggers a separate permission request with this format
**Integration with Permission Provider:**
When you enable context-based permissions (`isContextEnabled: true`), Velt automatically converts array values from [`SetDocumentsContext`](#setdocumentscontext) into individual permission requests using the `Context` interface format.
#### SetDocumentsContext
***
The `SetDocumentsContext` interface is used for filtering comments and notifications based on custom context fields when calling frontend SDK methods. This enables precise filtering based on your application's data model.
| Property | Type | Required | Description |
| -------- | -------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access` | `{ [key: string]: Array }` | Yes | Key-value pairs for filtering. Keys are custom field names, values are arrays of strings or numbers to filter by. Multiple values in an array use OR logic. |
**Usage:** The `SetDocumentsContext` interface is used in:
* `setDocuments()` method to fetch comments filtered by context
* `identify()` method to filter notifications by context
* Frontend SDK methods that require context filtering
**Filtering Logic:**
* **Within a field (OR logic)**: When multiple values are provided for a single field, comments/notifications matching any value are returned
* **Across fields (AND logic)**: When multiple fields are provided, comments/notifications must match all field values
**Permission Provider Integration:**
When Permission Provider is enabled with `isContextEnabled: true`, each value in the arrays is sent as a separate permission request to your backend using the [`Context`](#context) interface format. This allows granular access control at the context value level.
#### Options
***
| Property | Type | Required | Description |
| ------------ | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `authToken` | `string` | No | The authentication token for the user. |
| `forceReset` | `boolean` | No | If true, forces the user to re-login. |
| `throwError` | `boolean` | No | If true, throws error if user authentication fails. Default: false. |
| `context` | [`SetDocumentsContext`](#setdocumentscontext) | No | Filter notifications by custom context fields. Fetches notifications matching any of the provided values (OR logic within a field). When Permission Provider is enabled with `isContextEnabled: true`, each context value triggers a separate permission request. |
# React Flow Collaboration
#### VeltReactFlowCrdtExtensionConfig
***
Configuration for the `useVeltReactFlowCrdtExtension` React hook.
| Property | Type | Required | Description |
| -------------- | -------- | -------- | ------------------------------------------------------------------- |
| `editorId` | `string` | Yes | Unique document identifier for synchronization. |
| `initialNodes` | `Node[]` | Yes | Initial set of nodes. Applied only when no server-side data exists. |
| `initialEdges` | `Edge[]` | Yes | Initial set of edges. Applied only when no server-side data exists. |
| `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. |
#### VeltReactFlowCrdtExtensionResponse
***
Interface extending [`VeltReactFlowAppState`](#appstate).
| Property | Type | Description |
| --------------- | ------------------------- | -------------------------------------- |
| `store` | `Store` | ReactFlow CRDT store instance. |
| `nodes` | `Node[]` | Array of nodes in the flow diagram. |
| `edges` | `Edge[]` | Array of edges connecting the nodes. |
| `onNodesChange` | `OnNodesChange` | Callback for handling node changes. |
| `onEdgesChange` | `OnEdgesChange` | Callback for handling edge changes. |
| `onConnect` | `OnConnect` | Callback for handling new connections. |
| `setNodes` | `(nodes: Node[]) => void` | Function to set all nodes at once. |
| `setEdges` | `(edges: Edge[]) => void` | Function to set all edges at once. |
#### VeltReactFlowStoreConfig
***
| Property | Type | Required | Description |
| -------------- | -------- | -------- | ------------------------------------------------------------------- |
| `editorId` | `string` | Yes | Unique ID for this collaborative React Flow instance. |
| `veltClient` | `Velt` | Yes | Client from `useVeltClient()` for auth/session and syncing. |
| `initialNodes` | `Node[]` | Yes | Initial set of nodes. Applied only when no server-side data exists. |
| `initialEdges` | `Edge[]` | Yes | Initial set of edges. Applied only when no server-side data exists. |
| `debounceMs` | `number` | No | Debounce time for updates (milliseconds). |
#### AppState
***
| Property | Type | Description |
| --------------- | ------------------------- | -------------------------------------- |
| `nodes` | `Node[]` | Array of nodes in the flow diagram. |
| `edges` | `Edge[]` | Array of edges connecting the nodes. |
| `onNodesChange` | `OnNodesChange` | Callback for handling node changes. |
| `onEdgesChange` | `OnEdgesChange` | Callback for handling edge changes. |
| `onConnect` | `OnConnect` | Callback for handling new connections. |
| `setNodes` | `(nodes: Node[]) => void` | Function to set all nodes at once. |
| `setEdges` | `(edges: Edge[]) => void` | Function to set all edges at once. |
#### Node (React Flow)
***
| Property | Type | Required | Description |
| ---------- | -------------------------- | -------- | -------------------------------------------- |
| `id` | `string` | Yes | Unique node identifier. |
| `type` | `string` | No | React Flow node type (e.g., `"input"`). |
| `data` | `{ label?: string }` | No | Freeform node data (label used in examples). |
| `position` | `{ x: number; y: number }` | Yes | Canvas position in px. |
| `origin` | `[number, number]` | No | Optional anchor origin used in examples. |
#### Edge (React Flow)
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | --------------- |
| `id` | `string` | Yes | Unique edge id. |
| `source` | `string` | Yes | Source node id. |
| `target` | `string` | Yes | Target node id. |
#### NodeChange
***
| Property | Type | Required | Description |
| -------- | ------------------------------- | --------------- | ----------------------------- |
| `type` | `'add' \| 'update' \| 'remove'` | Yes | Kind of change. |
| `item` | `Node` | Yes (for `add`) | Node to add (as in examples). |
#### EdgeChange
***
| Property | Type | Required | Description |
| -------- | ------------------------------- | --------------- | ----------------------------- |
| `type` | `'add' \| 'update' \| 'remove'` | Yes | Kind of change. |
| `item` | `Edge` | Yes (for `add`) | Edge to add (as in examples). |
#### Connection
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | -------------------------------------- |
| `source` | `string` | Yes | Source node id. |
| `target` | `string` | Yes | Target node id. |
| *…* | *varies* | No | Other React Flow fields as applicable. |
#### ConnectionState (used in onConnectEnd)
***
| Property | Type | Required | Description |
| ---------- | ---------------- | -------- | -------------------------------------------- |
| `isValid` | `boolean` | Yes | Whether the provisional connection is valid. |
| `fromNode` | `{ id: string }` | Yes | Node the drag originated from. |
# CodeMirror Collaboration
#### VeltCodeMirrorCrdtExtensionConfig
***
Configuration for the `useVeltCodeMirrorCrdtExtension` React hook.
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | -------------------------------------------------------------------------- |
| `editorId` | `string` | Yes | Unique document identifier for synchronization. |
| `initialContent` | `string` | No | Initial CodeMirror document. Applied only when no server-side data exists. |
| `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. |
#### VeltCodeMirrorCrdtExtensionResponse
***
Response returned by `useVeltCodeMirrorCrdtExtension`.
| Property | Type | Description |
| ----------- | ----------------------------- | ----------------------------------------------------- |
| `store` | `VeltCodeMirrorStore \| null` | CodeMirror CRDT store instance. |
| `isLoading` | `boolean` | `false` once store is initialized, `true` by default. |
#### VeltCodeMirrorStoreConfig
***
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | --------------------------------------------------------------------- |
| `editorId` | `string` | Yes | Unique document identifier for synchronization. |
| `veltClient` | `Velt` | Yes | Velt client for Velt SDK integration. |
| `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. |
| `debounceMs` | `number` | No | Debounce time for updates (milliseconds). |
# BlockNote Collaboration
#### VeltBlockNoteCrdtExtensionConfig
***
Configuration for the `useVeltBlockNoteCrdtExtension` React hook.
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | ----------------------------------------------------- |
| `editorId` | `string` | Yes | Unique document identifier for synchronization. |
| `initialContent` | `string` | No | Initial BlockNote document (JSON string of blocks). |
| `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. |
#### VeltBlockNoteCrdtExtensionResponse
***
Response returned by `useVeltBlockNoteCrdtExtension`.
| Property | Type | Description |
| --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `collaborationConfig` | `{ fragment: any; provider: any; user: { name: string; color: string } } \| null` | Configuration object to pass into BlockNote’s `useCreateBlockNote({ collaboration })`. |
| `store` | `VeltBlockNoteStore \| null` | BlockNote CRDT store instance. |
| `isLoading` | `boolean` | `false` once store is initialized, `true` by default. |
#### VeltBlockNoteStoreConfig
***
Configuration for creating a BlockNote collaboration store.
| Property | Type | Required | Description |
| ------------------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------- |
| `editorId` | string | Yes | Unique document identifier used for syncing. |
| `initialContent` | string | No | JSON string representing an array of blocks to seed the doc (parsed into Y.XmlFragment). |
| `collection` | string | No | Backend collection name (e.g., Firestore). Defaults internally. |
| `debounceMs` | number | No | Debounce (ms) for update batching. |
| `onSynced` | `(doc?: Y.Doc) => void` | No | Called after initial sync completes. |
| `onConnectionError` | `(error: Error) => void` | No | Called if a connection error occurs. |
| `veltClient` | `Velt` | No | Velt client used for auth/session context and user resolution. |
# Tiptap Collaboration
#### VeltTiptapCrdtExtensionConfig
***
Configuration for the Tiptap CRDT extension that enables real-time collaborative editing.
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | --------------------------------------------------------------------- |
| `editorId` | `string` | Yes | Unique document identifier for synchronization. |
| `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. |
| `debounceMs` | `number` | No | Debounce time for update propagation (ms). |
#### VeltTiptapCrdtExtensionResponse
***
| Property | Type | Description |
| ----------- | ---------------------------- | ----------------------------------------------------- |
| `VeltCrdt` | `Extension \| null` | Tiptap Velt CRDT Extension. |
| `store` | `VeltTipTapStore \| null` | Tiptap CRDT store instance. |
| `isLoading` | `boolean` | `false` once store is initialized, `true` by default. |
#### VeltTipTapStoreConfig
***
Configuration for creating a Tiptap collaboration store.
| Property | Type | Required | Description |
| ---------------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `editorId` | `string` | Yes | Unique document identifier for synchronization. Use a different ID per editor. |
| `veltClient` | `Velt` | Yes | Velt client for velt sdk integration |
| `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. |
| `debounceMs` | `number` | No | Debounce time for updates in milliseconds |
#### VeltTipTapStore
***
Represents the Tiptap collaboration store instance. Public API surface only; all other fields are private.
| Method / Property | Type / Signature | Description |
| ------------------------- | ------------------------------------- | --------------------------------------------------------- |
| `constructor` | `(config: VeltTipTapStoreConfig)` | Creates a new store wrapper over Yjs + persistence. |
| `initialize()` | `Promise` | Initializes the underlying Store and triggers callbacks. |
| `getStore()` | `Store` | Returns the underlying CRDT store instance. |
| `getYText()` (deprecated) | `Y.Text \| null` | Legacy text accessor; usually returns null (XML is used). |
| `getYXml()` | `Y.XmlFragment \| null` | Accessor for XML fragment in the Yjs document. |
| `getYDoc()` | `Y.Doc` | Accessor for the Yjs document. |
| `isConnected()` | `boolean` | Collaboration readiness flag (initialized). |
| `setStateFromVersion()` | `(version: Version) => Promise` | Restores document to a specific version. |
| `destroy()` | `void` | Cleans up resources and marks instance uninitialized. |
| `getCollabExtension()` | `Extension` | Tiptap Extension configured with current Yjs doc. |
#### createVeltTipTapStore
***
Factory method that constructs a `VeltTipTapStore`, calls `initialize()`, and returns it.
| Parameter | Type | Required | Description |
| --------- | ----------------------- | -------- | ------------------------------------ |
| `config` | `VeltTipTapStoreConfig` | Yes | Configuration options for the store. |
| Returns | Type | Description |
| ------- | ---------------------------------- | --------------------------------------- |
| result | `Promise` | Initialized store or `null` on failure. |
# Core Collaboration
#### StoreConfig``;
***
| Property | Type | Required | Description |
| ---------------- | ------------------------------------- | -------- | ------------------------------------------------------------------ |
| `id` | `string` | Yes | Unique identifier for the collaborative store (e.g., document ID). |
| `veltClient` | `Velt` | Yes | Velt client for SDK integration. |
| `type` | `'array' \| 'map' \| 'text' \| 'xml'` | Yes | Backing CRDT data type for the store. |
| `initialValue` | `T` | No | Optional initial value (e.g., `''` for text, `[]` for array). |
| `enablePresence` | `boolean` | No | Enable realtime presence tracking (default: `true`). |
| `debounceMs` | `number` | No | Debounce interval in ms for batching local updates before syncing. |
#### YjsType
***
`'array' | 'map' | 'text' | 'xml'`
#### useVeltCrdtStore
***
| Property | Type | Description |
| --------------------- | ------------------------------------------ | ------------------------------------------- |
| `value` | `T \| null` | Current value of the store. |
| `versions` | `Version[]` | List of all stored versions. |
| `store` | `Store \| null` | The underlying Velt Store instance. |
| `update` | `(newValue: T) => void` | Updates the store value. |
| `saveVersion` | `(name: string) => Promise` | Saves a new version and returns its ID. |
| `getVersions` | `() => Promise` | Fetches all versions. |
| `getVersionById` | `(id: string) => Promise` | Fetches a specific version by ID. |
| `restoreVersion` | `(id: string) => Promise` | Restores the store to a specific version. |
| `setStateFromVersion` | `(version: Version) => Promise` | Sets the store state from a version object. |
# Encryption
#### EncryptConfig
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | ---------------------------------------------------- |
| `data` | `T` | Yes | The payload to encrypt. |
| `type` | `string` | No | Optional type hint to select an encryption strategy. |
#### DecryptConfig
***
| Property | Type | Required | Description |
| -------- | -------- | -------- | --------------------------------------------------- |
| `data` | `R` | Yes | The payload to decrypt. |
| `type` | `string` | No | Optional type hint to select a decryption strategy. |
#### VeltEncryptionProvider
***
| Property | Type | Required | Description |
| --------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------- |
| `encrypt` | `(config: EncryptConfig) => Promise` | Yes | Asynchronous function that encrypts data and returns the encrypted result. |
| `decrypt` | `(config: DecryptConfig) => Promise` | Yes | Asynchronous function that decrypts data and returns the original value. |
#### CrdtUpdateDataEvent
***
Event emitted when CRDT data changes occur, triggered by webhook notifications.
| Property | Type | Required | Description |
| ------------ | ------------------------------------------------- | -------- | -------------------------------- |
| `methodName` | `string` | Yes | Method that triggered the update |
| `uniqueId` | `string` | Yes | Unique identifier for the event |
| `timestamp` | `number` | Yes | Unix timestamp of the event |
| `source` | `string` | Yes | Source of the data change |
| `payload` | [`CrdtUpdateDataPayload`](#crdtupdatedatapayload) | Yes | Data change payload |
#### CrdtUpdateDataPayload
***
Payload containing details of the CRDT data update.
| Property | Type | Required | Description |
| --------------- | ---------------- | -------- | -------------------------------- |
| `id` | `string` | Yes | Store identifier |
| `data` | `unknown` | Yes | Updated data value |
| `lastUpdatedBy` | `string` | Yes | User ID who made the last update |
| `sessionId` | `string \| null` | Yes | Session ID or null |
| `lastUpdate` | `string` | Yes | ISO timestamp of last update |
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/activity/customize-behavior
#### getAllActivities
Subscribe to the real-time activity log feed. Emits the full list of ActivityRecord objects whenever the feed changes.
* Params: `config?:` [`ActivitySubscribeConfig`](/api-reference/sdk/models/data-models#activitysubscribeconfig)
* `documentIds` (`string[]`) — Filter activity logs to specific document IDs.
* `featureTypes` (`ActivityFeatureType[]`) — Filter by feature type: `'comment'`, `'reaction'`, `'recorder'`, `'crdt'`, `'custom'`.
* `actionTypes` (`string[]`) — Filter by action type; use exported action type constants for type-safe values.
* Returns: [`Observable`](/api-reference/sdk/models/data-models#activityrecord)
**Using Hook — org-wide feed:**
```jsx theme={null}
import { useAllActivities } from '@veltdev/react';
function ActivityFeed() {
const activities = useAllActivities();
if (activities === null) return Loading...
;
if (activities.length === 0) return No activities yet.
;
return (
{activities.map((activity) => (
{activity.displayMessage}
))}
);
}
```
**Using Hook — document-scoped feed:**
```jsx theme={null}
import { useAllActivities } from '@veltdev/react';
function DocumentActivityFeed({ documentId }: { documentId: string }) {
const activities = useAllActivities({
documentIds: [documentId],
featureTypes: ['comment', 'reaction'],
});
if (activities === null) return Loading...
;
return (
{activities?.map((activity) => (
{activity.displayMessage}
))}
);
}
```
**Using API:**
```jsx theme={null}
import { useVeltClient } from '@veltdev/react';
import { useEffect } from 'react';
function YourComponent() {
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const activityElement = client.getActivityElement();
// Org-wide subscription
const subscription = activityElement.getAllActivities().subscribe((activities) => {
if (activities === null) return;
console.log(activities);
});
// Document-scoped subscription
const docSubscription = activityElement.getAllActivities({
documentIds: ['my-document-id'],
featureTypes: ['comment'],
}).subscribe((activities) => {
console.log(activities);
});
return () => {
subscription?.unsubscribe();
docSubscription?.unsubscribe();
};
}, [client]);
}
```
```javascript theme={null}
const activityElement = Velt.getActivityElement();
// Org-wide subscription
const subscription = activityElement.getAllActivities().subscribe((activities) => {
if (activities === null) return;
console.log(activities.map((a) => a.displayMessage));
});
// Document-scoped subscription
const docSubscription = activityElement.getAllActivities({
documentIds: ['my-document-id'],
featureTypes: ['comment'],
}).subscribe((activities) => {
console.log(activities);
});
// To unsubscribe:
// subscription?.unsubscribe();
// docSubscription?.unsubscribe();
```
#### createActivity
Create a custom activity log record for non-Velt events. Use `displayMessageTemplate` with `{{variable}}` placeholders and supply values in `displayMessageTemplateData`.
* Params: [`CreateActivityData`](/api-reference/sdk/models/data-models#createactivitydata)
* Returns: `Promise`
**Using Hook:**
```jsx theme={null}
import { useActivityUtils } from '@veltdev/react';
function CustomActivityButton() {
const activityElement = useActivityUtils();
const handleClick = async () => {
await activityElement?.createActivity({
featureType: 'custom',
actionType: 'custom',
targetEntityId: 'my-entity-id',
displayMessageTemplate: '{{actionUser.name}} deployed version {{version}}',
displayMessageTemplateData: { version: 'v2.3.1' },
});
};
return Create Activity ;
}
```
**Using API:**
```jsx theme={null}
import { useVeltClient } from '@veltdev/react';
function YourComponent() {
const { client } = useVeltClient();
const createCustomActivity = async () => {
if (!client) return;
const activityElement = client.getActivityElement();
await activityElement.createActivity({
featureType: 'custom',
actionType: 'custom',
targetEntityId: 'annotation-id',
displayMessageTemplate: '{{actionUser.name}} escalated this to {{assignee.name}}',
displayMessageTemplateData: { assignee: { name: 'Alice' } },
});
};
}
```
```javascript theme={null}
const activityElement = Velt.getActivityElement();
await activityElement.createActivity({
featureType: 'custom',
actionType: 'custom',
targetEntityId: 'annotation-id',
displayMessageTemplate: '{{actionUser.name}} escalated this to {{assignee.name}}',
displayMessageTemplateData: { assignee: { name: 'Alice' } },
});
```
# Activity Logs
Source: https://docs.velt.dev/async-collaboration/activity/overview
Every collaboration event in your app, every comment, approval, edit, and review, generates a question someone eventually asks: "Who did what, and when?" Activity Logs gives you a complete, real-time record of everything that happens across your product.
Velt automatically generates activity log records for Comments, Reactions, Recorder, and CRDT features. You can also emit custom records for non-Velt events (deployments, status changes, escalations) using the SDK or REST API, so your users get one unified timeline. [Learn more about the Activity Logs REST API →](/api-reference/rest-apis/v2/activities/get-activities)
## Architecture
Activity Logs use a 2-layer trigger-listener architecture:
1. **Feature layer (record creation):** A record is generated whenever a user interacts with a Velt feature, such as adding a comment, changing a comment status, reacting, or editing a CRDT document. Each record includes the user, action type, target object, timestamp, and document context.
2. **Subscription layer (record delivery):** `getAllActivities()` opens a real-time subscription that pushes records to your UI as they're created. You can scope the subscription org-wide or filter by `documentId`, `userId`, or feature type.
## Automatic Activity Logging
Velt generates records for the following features out of the box:
* **Comments:** Record created on add, edit, delete, status change, and @mention.
* **Reactions:** Record created when a reaction is added or removed.
* **Recorder:** Record created on recording start, stop, and playback events.
* **CRDT edits:** Record created per edit batch. Use `setActivityDebounceTime(ms)` to control how keystrokes are grouped into a single record. For example, `setActivityDebounceTime(5000)` batches all edits within a 5-second window into one activity log entry, keeping the feed meaningful rather than noisy.
## Custom Activity Logs
Use `createActivity()` to push your own events into the same feed:
```javascript theme={null}
createActivity({
type: 'deployment',
action: 'deployed_to_production',
message: 'v2.4.1 deployed by CI pipeline',
documentId: 'doc_abc123',
userId: 'user_xyz'
});
```
This lets you merge application-level events (deployments, escalations, status transitions) into the same stream as collaboration events, giving your users a single source of truth.
## Querying and Filtering
`getAllActivities()` returns a real-time subscription. You can scope it to fit different UI patterns:
* **Org-wide feed:** No filters. Returns all activity across every document in the organization. Useful for admin dashboards and team lead overviews.
* **Per-document timeline:** Filter by `documentId` to show the full history of a single document, from first draft to final approval. Useful for inline review panels and document sidebars.
* **Feature-scoped feed:** Filter by feature type (e.g., only Comments or only CRDT edits) to reduce noise for specific views.
## Immutability
Activity log records can be made immutable by turning on the config in Velt Console. When immutability is enabled, records cannot be edited or deleted after creation, giving you a tamper-evident audit trail that holds up under compliance scrutiny.
This is critical for regulated workflows (SOX, SOC 2, HIPAA) where auditors need to verify that the record of who approved what, and when, has not been altered after the fact. When immutability is off (the default), records can be updated or removed through the SDK and REST API as needed.
## Common Patterns
* **Audit trail for regulated workflows:** Surface a "who approved what, when" log for processes like invoice sign-offs, legal reviews, or budget approvals. Enable the Immutability config in Velt Console to ensure records cannot be altered after creation, with full user attribution and timestamps suitable for SOX, SOC 2, or any compliance context requiring a tamper-evident record.
* **Unified event stream:** Combine Velt activity with your app's own events using `createActivity()` so reviewers see one timeline instead of checking multiple systems.
* **AI agent traceability:** When AI agents post comments or trigger approvals via the API, each action generates an activity log record, giving human reviewers a clear trail of what the agent did and when.
## Activity Log Action Types
Use the exported constant objects for type-safe `actionTypes` filtering. Each constant's values are string literals that correspond to the actions generated by that feature. See the [Activity Log Action Type Constants](/api-reference/sdk/models/data-models#activity-log-action-type-constants) reference for the full list of values.
* `CommentActivityActionTypes` / `CommentActivityActionType` — Comment annotations
* `RecorderActivityActionTypes` / `RecorderActivityActionType` — Recorder clips
* `ReactionActivityActionTypes` / `ReactionActivityActionType` — Inline reactions
* `CrdtActivityActionTypes` / `CrdtActivityActionType` — CRDT edits
# Setup
Source: https://docs.velt.dev/async-collaboration/activity/setup
## 1. Enable Activity Logs in the Velt Console
* Go to the [Activity Logs section](https://console.velt.dev/dashboard/config/activity) in the Configurations section of the Velt Console and enable Activity Logs.
Activity Logs will not work if you do not enable this first.
## 2. Create a Custom Activity
Use `createActivity()` to push your own events into the activity feed. Supply a `displayMessageTemplate` with `{{variable}}` placeholders and provide values in `displayMessageTemplateData`.
* Params: [`CreateActivityData`](/api-reference/sdk/models/data-models#createactivitydata)
* Returns: `Promise`
**Using Hook:**
```jsx theme={null}
import { useActivityUtils } from '@veltdev/react';
function CustomActivityButton() {
const activityElement = useActivityUtils();
const handleClick = async () => {
await activityElement?.createActivity({
featureType: 'custom',
actionType: 'custom',
targetEntityId: 'my-entity-id',
displayMessageTemplate: '{{actionUser.name}} deployed version {{version}}',
displayMessageTemplateData: { version: 'v2.3.1' },
});
};
return Create Activity ;
}
```
**Using API:**
```jsx theme={null}
const activityElement = client.getActivityElement();
await activityElement.createActivity({
featureType: 'custom',
actionType: 'custom',
targetEntityId: 'annotation-id',
displayMessageTemplate: '{{actionUser.name}} escalated this to {{assignee.name}}',
displayMessageTemplateData: { assignee: { name: 'Alice' } },
});
```
```javascript theme={null}
const activityElement = Velt.getActivityElement();
await activityElement.createActivity({
featureType: 'custom',
actionType: 'custom',
targetEntityId: 'annotation-id',
displayMessageTemplate: '{{actionUser.name}} escalated this to {{assignee.name}}',
displayMessageTemplateData: { assignee: { name: 'Alice' } },
});
```
## 3. Subscribe to Activities
Call `getAllActivities()` to receive a real-time stream of activity records. The observable emits the full list whenever the feed changes.
* Params: [`ActivitySubscribeConfig`](/api-reference/sdk/models/data-models#activitysubscribeconfig) (optional)
* Returns: [`Observable`](/api-reference/sdk/models/data-models#activityrecord)
**Using Hook:**
```jsx theme={null}
import { useAllActivities } from '@veltdev/react';
function ActivityFeed() {
const activities = useAllActivities();
if (activities === null) return Loading...
;
if (activities.length === 0) return No activities yet.
;
return (
{activities.map((activity) => (
{activity.displayMessage}
))}
);
}
```
**With filters:**
```jsx theme={null}
import { useAllActivities } from '@veltdev/react';
function DocumentActivityFeed({ documentId }: { documentId: string }) {
const activities = useAllActivities({
documentIds: [documentId],
featureTypes: ['comment', 'reaction'],
});
// ...
}
```
**Using API:**
```jsx theme={null}
const activityElement = client.getActivityElement();
const subscription = activityElement.getAllActivities().subscribe((activities) => {
if (activities === null) return;
console.log(activities);
});
// Clean up when done
subscription?.unsubscribe();
```
```javascript theme={null}
const activityElement = Velt.getActivityElement();
const subscription = activityElement.getAllActivities().subscribe((activities) => {
if (activities === null) return;
console.log(activities.map((a) => a.displayMessage));
});
// Document-scoped with filters
const docSubscription = activityElement.getAllActivities({
documentIds: ['my-document-id'],
featureTypes: ['comment'],
}).subscribe((activities) => {
console.log(activities);
});
```
## REST APIs
You can also manage activities server-side using the REST API:
* [Get Activities](/api-reference/rest-apis/v2/activities/get-activities) — Retrieve activity records filtered by document, feature type, action type, or user.
* [Add Activities](/api-reference/rest-apis/v2/activities/add-activities) — Create new activity records for custom or application-level events.
* [Update Activities](/api-reference/rest-apis/v2/activities/update-activities) — Update existing activity records by ID.
* [Delete Activities](/api-reference/rest-apis/v2/activities/delete-activities) — Delete activity records by document, target entity, or specific IDs.
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/arrows/customize-behavior
## 1. Getting the Arrow Element
To get access to the Arrow Element APIs, you will first need to get the Arrow Element object from the client.
```jsx theme={null}
const arrowElement = client.getArrowElement();
```
```jsx theme={null}
const arrowElement = Velt.getArrowElement();
```
## 2. Set which elements Arrows can be added to
You can use the `allowedElementIds()` property to set an allowed list of elements the `Arrows` feature can be added to.
```jsx theme={null}
```jsx theme={null}
API Methods:
You can use the `arrowElement.allowedElementIds()` method to set an allowed list of elements the `Arrows` feature can be added to.
```jsx theme={null}
arrowElement.allowedElementIds(['ALLOWED_ID_1', 'ALLOWED_ID_2']);
```
```jsx theme={null}
arrowElement.allowedElementIds(['ALLOWED_ID_1', 'ALLOWED_ID_2']);
```
## 3. Dark Mode
Whether dark mode is enabled.
`Default: false`
```js theme={null}
```js theme={null}
# Arrows
Source: https://docs.velt.dev/async-collaboration/arrows/overview
Import the `Arrow` components
```js theme={null}
import { VeltArrows, VeltArrowTool } from '@veltdev/react';
```
Place the `VeltArrows` component at the root of your app.
```js theme={null}
```
Place the `VeltArrowsTool` component wherever you want the invite button to appear.
```js theme={null}
```
Place the `` component at the root of your app.
```html theme={null}
```
Place the component wherever you want the invite button to appear.
```html theme={null}
```
```js React / Next.js theme={null}
import { VeltArrows, VeltArrowTool } from '@veltdev/react';
function YourComponent() {
return (
)
}
```
```html HTML theme={null}
Collaboration App
```
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/comments-sidebar/customize-behavior
# Custom filtering, sorting and grouping
* Here is the overview on how it works:
* Enable custom actions in the comments sidebar.
* Add [Velt Button Wireframe](/ui-customization/custom-action-component) to the sidebar wireframe.
* Handle click events and lifecycle events to apply custom filtering, sorting, and grouping logic.
* Update sidebar data.
* Here are the steps to implement it:
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
* Learn more about how to setup [Velt Button Wireframe](/ui-customization/custom-action-component).
* Set default state using the `active` prop.
* Handle `veltButtonClick` event to implement custom filtering, sorting, and grouping logic. It returns [VeltButtonClickEvent](/api-reference/sdk/models/data-models#veltbuttonclickevent).
```jsx {6-12} theme={null}
```
**Handle the button click event:**
```jsx theme={null}
const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
useEffect(() => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selections?.unread) {
// show unread comments
}
if (selections?.mentions) {
// show comments with mentions
}
}
}
}, [veltButtonClickEventData]);
```
```html {6-12} theme={null}
```
**Handle the button click event:**
```js theme={null}
Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selections?.unread) {
// Custom Filtering | Sorting | Grouping Logic
}
if (selections?.mentions) {
// Custom Filtering | Sorting | Grouping Logic
}
}
}
});
```
* There are two lifecycle events you need to handle to implement custom filtering, sorting, and grouping logic:
* `commentSidebarDataInit`: Triggered when comment sidebar data is first loaded. It returns [CommentSidebarDataInitEvent](/api-reference/sdk/models/data-models#commentsidebardatainitevent)
* `commentSidebarDataUpdate`: Triggered when comment sidebar data is updated. It returns [CommentSidebarDataUpdateEvent](/api-reference/sdk/models/data-models#commentsidebardataupdateevent)
* This event can trigger multiple times when either the comment data or unread comment count changes.
```jsx theme={null}
const commentSidebarDataInitEvent: CommentSidebarDataInitEvent = useCommentEventCallback('commentSidebarDataInit');
const commentSidebarDataUpdateEvent: CommentSidebarDataUpdateEvent = useCommentEventCallback('commentSidebarDataUpdate');
useEffect(() => {
if (commentSidebarDataInitEvent) {
// Custom Filtering | Sorting | Grouping Logic
}
}, [commentSidebarDataInitEvent]);
useEffect(() => {
if (commentSidebarDataUpdateEvent) {
// Custom Filtering | Sorting | Grouping Logic
}
}, [commentSidebarDataUpdateEvent]);
```
```javascript theme={null}
const commentElement = Velt.getCommentElement();
commentElement.on('commentSidebarDataInit').subscribe((data) => {
// Custom Filtering | Sorting | Grouping Logic
});
commentElement.on('commentSidebarDataUpdate').subscribe((data) => {
// Custom Filtering | Sorting | Grouping Logic
});
```
* Once you have applied your custom filtering, sorting, and grouping logic, create the data an **array** of [CommentSidebarData](/api-reference/sdk/models/data-models#commentsidebardata) objects and set it in the comments sidebar.
* Use the `options` parameter to control if you want to group the comments or not.
```jsx theme={null}
const options = {
grouping: false
};
const customFilterData = [
{
"groupId": "group1",
"groupName": "Group 1",
"isExpanded": true,
"annotations": [
{
...annotation1
},
{
...annotation2
},
]
}
];
const commentElement = client.getCommentElement();
commentElement.setCommentSidebarData(customFilterData, options);
```
```javascript theme={null}
const options = {
grouping: false
};
const customFilterData = [
{
"groupId": "group1",
"groupName": "Group 1",
"isExpanded": true,
"annotations": [
{
...annotation1
},
{
...annotation2
},
]
}
];
const commentElement = Velt.getCommentElement();
commentElement.setCommentSidebarData(customFilterData, options);
```
# Navigation
#### onCommentClick
* Listen for click events on comments in the sidebar to trigger actions like navigation.
* The event callback provides access to the clicked comment's annotation object, which includes `location` and `context` data.
* Use this data to update your app's state and navigate to the comment's location.
The event handler receives an object with the following properties:
| Property | Type | Description |
| ----------------- | ----------------- | ------------------------------------------------ |
| `documentId` | string | ID of the document containing the comment |
| `location` | Object | Location details of the comment |
| `targetElementId` | string | DOM ID of the element the comment is attached to |
| `context` | Object | Custom context data associated with the comment |
| `annotation` | CommentAnnotation | The full comment annotation object |
```js theme={null}
```js theme={null}
// event handler for when a comment is clicked on
const onCommentClick = (event) => {
console.log('onCommentClick', event.detail);
//handle custom navigation by getting location if you have set custom locations
const { pageId } = event.detail.location;
//handle custom navigation by getting context if you have added metadata using addContext()
const { pageId } = event.detail.context;
yourNavigateToPageMethod(pageId);
};
const commentElement = document.querySelector('velt-comments-sidebar');
commentElement.addEventListener('onCommentClick', onCommentClick);
```
#### onCommentNavigationButtonClick
* This event is triggered when the navigation button in the comment dialog in the Sidebar is clicked.
* Use this event to implement custom navigation logic.
```jsx theme={null}
```javascript theme={null}
const commentSidebarElement = document.querySelector('velt-comments-sidebar');
commentSidebarElement.addEventListener('onCommentNavigationButtonClick', (event) => {
console.log('onCommentNavigationButtonClick', event.detail);
});
```
#### enableSidebarUrlNavigation
* By default, clicking a comment in the sidebar doesn't automatically update the page URL where the comment was added.
* Use this to enable automatic URL navigation when clicking comments in the sidebar.
* If your app's state is more complex, you might need to listen for `onCommentClick` events and implement custom navigation logic.
Default: `false`
Using Props:
```jsx theme={null}
Using Props:
```js theme={null}
# UI
#### currentLocationSuffix
* Adds "(this page)" suffix to the group name when the current location matches the group's location.
Default: `false`
```jsx theme={null}
```
```jsx theme={null}
#### embedMode
* By default, the sidebar will open up from the right corner of the page.
* With embed mode, you can add the sidebar in your component and it will take up the full width and height of its container.
* When in embed mode, the sidebar will not have the close button. You need to implement your own open and close functionality on the host component.
```jsx theme={null}
```
```jsx theme={null}
```
#### excludeLocationIdsFromSidebar
* Use this to filter out comments from certain locations. These comments will not be displayed in the sidebar.
Using Props:
```jsx theme={null}
Using Props:
```jsx theme={null}
#### filterGhostCommentsInSidebar
* Fileter out and hide ghost comments from the Sidebar.
**Using Props:**
```jsx theme={null}
// Use either of the following
**Using Props:**
```html theme={null}
#### filterPanelLayout
* Change the layout of the filter panel in the sidebar.
* Options: `menu` or `bottomSheet`
`Default: bottomSheet`
```jsx theme={null}
```jsx theme={null}
#### filterOptionLayout
* Change the layout of the filter options in the sidebar filter panel.
* Options:
* `checkbox`: (default) to show the filter options in a checkbox list
* `dropdown`: to show the filter options in a searchable dropdown with checklist
```jsx theme={null}
```jsx theme={null}
#### filterCount
* Disable comment count on filter options. This leads to better performance.
```jsx theme={null}
```
```html theme={null}
#### dialogSelection
* When disabled, clicking a comment in the sidebar triggers a click event instead of opening the dialog inline. When combined with custom UX, this allows you to create a Figma-style sidebar experience where comments open at their location on the DOM rather than within the sidebar itself.
Default: `true`
```jsx theme={null}
```
```html theme={null}
#### expandOnSelection
* Controls whether comment dialogs automatically expand when selected in the sidebar.
Default: `true`
```jsx theme={null}
```
```html theme={null}
#### floatingMode
* This makes the sidebar open in an overlay panel over the sidebar button float over the page content.
* If you use this mode make sure you do not add Velt Sidebar Component in your app.
```jsx theme={null}
```jsx theme={null}
#### focusedThreadMode
* In this mode, when you click on a comment in the sidebar, it opens the thread in an expanded view within the sidebar itself.
* Other threads and actions like filters, search etc. are hidden behind a back button.
* Enabling this mode also adds a navigation button in the comment dialog. Clicking it will navigate to the comment and trigger a callback. Learn more about it [here](#oncommentnavigationbuttonclick).
If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog-components#header) and the [focused thread wireframe](/ui-customization/features/async/comments/comment-sidebar-componentscomment-sidebar-components#focusedthread).
```jsx theme={null}
```html theme={null}
#### openAnnotationInFocusMode
* When enabled, opens the comment dialog in focus mode when `focusedThreadMode` is enabled and either:
* The 'reply' button inside the comment dialog is clicked, or
* A comment is selected via the `selectCommentByAnnotationId(ANNOTATION_ID)` API method
* This requires `focusedThreadMode` to be enabled.
* Type: [`VeltCommentsSidebarProps`](/api-reference/sdk/models/data-models#veltcommentssidebarprops)
```jsx theme={null}
```html theme={null}
#### fullScreen
* Enable full-screen mode for the Comments Sidebar to maximize the viewing area for large volumes of feedback or detailed comment reviews.
* In full-screen mode, the sidebar expands to fill the entire viewport, providing more space to read and manage comments.
* A full-screen button appears in the sidebar header, allowing users to toggle between normal and full-screen modes.
* This feature is particularly useful when working with complex discussions, long comment threads, or when you need to focus exclusively on feedback.
Default: `false`
Full-screen mode only works in default mode. It is not supported in floating mode or embed mode.
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
#### pageMode
* This adds a composer in the sidebar where users can add comments without attaching them to any specific element.
`Default: false`
```jsx theme={null}
```jsx theme={null}
#### readOnly
* Make comment dialogs in the sidebar read-only to prevent users from editing comments.
Default: `false`
```jsx theme={null}
```html theme={null}
#### position
* Change the default direction where the sidebar opens from.
* Options: `left` or `right`
* Default: `right`
```jsx theme={null}
```jsx theme={null}
#### openCommentSidebar
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.openCommentSidebar(); // opens the comments side bar
commentElement.closeCommentSidebar(); // closes the comments side bar
commentElement.toggleCommentSidebar(); // toggles the comments side bar
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.openCommentSidebar(); // opens the comments side bar
commentElement.closeCommentSidebar(); // closes the comments side bar
commentElement.toggleCommentSidebar(); // toggles the comments side bar
```
#### forceClose
Force the sidebar to close on outside click, even when opened programmatically via API.
When the sidebar is opened dynamically through the API, outside clicks are normally ignored (expecting you to handle the close yourself). Setting `forceClose={true}` ensures outside clicks will always close the sidebar.
This does not affect embed mode sidebar.
```jsx theme={null}
```html theme={null}
#### searchPlaceholder
* Customize the placeholder text shown in the search input of the comments sidebar.
```jsx theme={null}
```html theme={null}
#### commentPlaceholder
Customize the placeholder text for the dialog composer (the comment input that appears in comment dialogs/threads).
```jsx theme={null}
```html theme={null}
#### replyPlaceholder
Customize the placeholder text for reply input fields in the sidebar.
```jsx theme={null}
```html theme={null}
#### pageModePlaceholder
Customize the placeholder text for the page mode composer (the comment input used for creating page-level comments).
```jsx theme={null}
```html theme={null}
#### sidebarButtonCountType
* Change the count shown on the sidebar button.
* `default`: Shows the total count of comments in open and in progress states. (default)
* `filter`: Shows the count of filtered comments.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### commentCountType
Control whether the sidebar button shows total or unread comment count.
Type: [`CommentCountType`](/api-reference/sdk/models/data-models#commentcounttype)
* `total`: Shows the total number of comments. (default)
* `unread`: Shows only the count of unread comments.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### context
Pass custom context data to page mode composer comments in the sidebar. This will add the provided context object to any comment added via the page mode composer in the sidebar, allowing you to associate additional metadata (such as job IDs, statuses, or other application-specific data) with the comment annotation.
```jsx theme={null}
```javascript theme={null}
const commentSidebarElement = document.querySelector('velt-comments-sidebar');
commentSidebarElement?.setAttribute("context", JSON.stringify({ jobId: `job-page-mode`, jobStatus: 'page comment' }));
```
# System Filters, Sorting and Grouping
#### filterConfig
* Customize the available system filters:
* `location`: Filter comments by location.
* `document`: Filter comments by document.
* `people`: Filter comments by author of comment annotation.
* `involved`: Filter comments by users who are involved in the comment annotation (author, mentioned, assigned).
* `tagged`: Filter comments by users who were tagged/mentioned in the comment. Only available in the latest SDK version.
* `assigned`: Filter comments by users who were assigned to the comment. Only available in the latest SDK version.
* `priority`: Filter comments by priority.
* `category`: Filter comments by category.
* `status`: Filter comments by status.
* You can rename, disable, configure grouping, and multi-select behavior of the filters as needed.
```jsx theme={null}
const filterConfig = {
location: {
enable: true,
name: "Pages",
enableGrouping: true,
multiSelection: true,
placeholder: "Filter by location",
order: ['locationId1', 'locationId2', 'locationId3']
},
document: {
enable: true,
name: "Documents",
enableGrouping: true,
placeholder: "Filter by document",
multiSelection: true,
},
people: {
enable: true,
name: "Author",
enableGrouping: true,
placeholder: "Filter by author",
multiSelection: true,
},
involved: {
enable: true,
name: "Involved",
enableGrouping: false,
placeholder: "Filter by involved",
multiSelection: true,
},
tagged: {
enable: true,
name: "Tagged",
enableGrouping: false,
placeholder: "Filter by tagged",
multiSelection: true,
},
assigned: {
enable: true,
name: "Assigned",
enableGrouping: false,
placeholder: "Filter by assigned",
multiSelection: true,
},
priority: {
enable: true,
name: "Priority",
enableGrouping: false,
placeholder: "Filter by priority",
multiSelection: true,
},
category: {
enable: true,
name: "Category",
enableGrouping: true,
placeholder: "Filter by category",
multiSelection: true,
},
status: {
enable: true,
name: "Status",
placeholder: "Filter by status",
multiSelection: true,
}
};
```jsx theme={null}
const filterConfig = {
location: {
enable: true,
name: "Pages",
enableGrouping: true,
multiSelection: true,
order: ['locationId1', 'locationId2', 'locationId3']
},
document: {
enable: true,
name: "Documents",
enableGrouping: true,
multiSelection: true,
},
people: {
enable: true,
name: "Author",
enableGrouping: true,
multiSelection: true,
},
involved: {
enable: true,
name: "Involved",
enableGrouping: false,
multiSelection: true,
},
tagged: {
enable: true,
name: "Tagged",
enableGrouping: false,
multiSelection: true,
},
assigned: {
enable: true,
name: "Assigned",
enableGrouping: false,
multiSelection: true,
},
priority: {
enable: true,
name: "Priority",
enableGrouping: false,
multiSelection: true,
},
category: {
enable: true,
name: "Category",
enableGrouping: true,
multiSelection: true,
},
status: {
enable: true,
name: "Status",
multiSelection: true,
}
};
const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
commentsSidebar?.setAttribute("filter-config", JSON.stringify(filterConfig));
```
#### groupConfig
* Enable/disable the option to group comments in the sidebar with the `group config` attribute.
* If you use floating mode, you can pass this config in Sidebar Button Component.
```jsx theme={null}
const groupConfig = {
enable: true,
name: "Custom Group By",
};
```jsx theme={null}
const groupConfig = {
enable: true,
name: "Custom Group By",
};
const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
commentsSidebar?.setAttribute("group-config", JSON.stringify(groupConfig));
```
#### sortOrder
Set default sort order for comments in the sidebar.
Options: `asc` or `desc`
```jsx theme={null}
```html theme={null}
#### sortBy
Set default sort field for comments in the sidebar.
Options: `createdAt` or `lastUpdated`
```jsx theme={null}
```html theme={null}
#### setCommentSidebarFilters
* Programmatically set the system filters on the sidebar:
```jsx theme={null}
const filters = {
location: [
{ id: 'location1Id' },
{ id: 'location2Id' },
],
document: [
{ id: 'document1Id' },
{ id: 'document2Id' },
],
people: [ // author of comment annotation
{ userId: 'userIdToFilter' },
],
involved: [ // user is author or mentioned or assigned
{ userId: 'userIdToFilter' },
],
tagged: [
{ userId: 'userIdToFilter' },
],
assigned: [
{ userId: 'userIdToFilter' },
],
priority: ['P0', 'P1', 'P2'],
category: ['bug', 'feedback', 'question'],
status: ['OPEN', 'IN_PROGRESS', 'RESOLVED'],
};
```jsx theme={null}
const filters = {
location: [
{ id: 'location1Id' },
{ id: 'location2Id' },
],
document: [
{ id: 'document1Id' },
{ id: 'document2Id' },
],
people: [ // author of comment annotation
{ userId: 'userIdToFilter' },
],
involved: [ // user is author or mentioned or assigned
{ userId: 'userIdToFilter' },
],
tagged: [
{ userId: 'userIdToFilter' }
],
assigned: [
{ userId: 'userIdToFilter' },
],
priority: ['P0', 'P1', 'P2'],
category: ['bug', 'feedback', 'question'],
status: ['OPEN', 'IN_PROGRESS', 'RESOLVED'],
};
const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
commentsSidebar?.setAttribute("filters", JSON.stringify(filters));
```
API Methods:
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setCommentSidebarFilters(filters);
```
#### systemFiltersOperator
* Specify whether the system filters (e.g., "me", "this page") should be combined with an `and` or `or` operator.
* Default: `and`
**Using Props:**
```tsx theme={null}
```html theme={null}
#### defaultMinimalFilter
Set the default minimal filter setting for the sidebar. This controls how resolved comments are handled in relation to other filters.
Type: `'all' | 'read' | 'unread' | 'resolved' | 'open' | 'reset' | null`
| Value | Description |
| ------------ | --------------------------------------------------------------------------------------- |
| `'all'` | (Default) Respects other filters; excludes resolved comments unless explicitly included |
| `'read'` | Shows only comments that have been read by the current user |
| `'unread'` | Shows only comments that have not been read by the current user |
| `'resolved'` | Shows only resolved comments |
| `'open'` | Shows only open (unresolved) comments |
| `'reset'` | Ignores all filters; shows all comments including resolved |
| `null` | Respects other filters; includes resolved comments (no minimal filter exclusion) |
```jsx theme={null}
```html theme={null}
# Comments Sidebar
Source: https://docs.velt.dev/async-collaboration/comments-sidebar/overview
Provide a toggleable sidebar to view and filter comments.
The Velt SDK contains 4 components that can be used to control the Comments Sidebar functionality:
* `VeltComments` - Used to enable the Comments feature site wide
* `VeltCommentsSidebar` - The Sidebar that holds all existing comments
* `VeltSidebarButton` - A button that toggles the `VeltCommentsSidebar`on and off
* `VeltCommentTool` - A button that turns on the Comments functionality
Import the Comments Sidebar Components.
```jsx theme={null}
import {
VeltProvider,
VeltCommentsSidebar,
VeltSidebarButton,
VeltCommentTool
} from '@veltdev/react';
```
Add the `VeltComments` and `VeltCommentsSidebar` components to the root of your app.
```jsx theme={null}
```
Add the Sidebar button to toggle the sidebar. Add the `VeltCommentTool` component to leave comments.
```jsx theme={null}
```
This is completely optional and you can toggle the sidebar in the comment dialog as well.
Test it out by opening the sidebar.
You should be able to click the `All comments` link in a comment dialog box on the bottom.
Place the `` component at the root of your app.
```html theme={null}
Place the `` component wherever you want the toggle button to appear.
```html theme={null}
```jsx React / Next.js theme={null}
import {
VeltProvider,
VeltCommentsSidebar,
VeltSidebarButton,
VeltCommentTool
} from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Collaboration App
```
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/comments/customize-behavior
# Threads
#### addCommentAnnotation
* Adds a new comment annotation.
* Params: [AddCommentAnnotationRequest](/api-reference/sdk/models/data-models#addcommentannotationrequest)
* Returns: [AddCommentAnnotationEvent](/api-reference/sdk/models/data-models#addcommentannotationevent)
```jsx theme={null}
const commentAnnotation = {
comments: [
{
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
}
]
};
const addCommentAnnotationRequest = {
annotation: commentAnnotation
};
// Hook
const { addCommentAnnotation } = useAddCommentAnnotation();
const addCommentAnnotationEventData = await addCommentAnnotation(addCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const addCommentAnnotationEventData = await commentElement.addCommentAnnotation(addCommentAnnotationRequest);
```
```js theme={null}
const commentAnnotation = {
comments: [
{
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
}
]
};
const addCommentAnnotationRequest = {
annotation: commentAnnotation
};
const commentElement = Velt.getCommentElement();
const addCommentAnnotationEventData = await commentElement.addCommentAnnotation(addCommentAnnotationRequest);
```
#### addCommentOnSelectedText
```jsx theme={null}
const commentElement = client.getCommentElement();
// to add comment on selected text
commentElement.addCommentOnSelectedText();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
// to add comment on selected text
commentElement.addCommentOnSelectedText();
```
#### addCommentOnElement
```jsx theme={null}
const element = {
"targetElement": {
"elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element)
"targetText": "target_text", // optional (pass targetText if you want to add comment on a specific text)
"occurrence": 1, // optional (default: 1) This is relevant for text comment. By default, we will attach comment to the first occurence of the target text in your document. You can change this to attach your comment on a more specific text.
"selectAllContent": true, // Set to `true` if you want to select all the text content of the target element.
},
"commentData": [
{
"commentText": "This is awesome! Well done.", // To set plain text content
"commentHtml": "This is test comment.", // To set HTML formatted content
"replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with
"replaceContentHtml": "This is new comment. ", // If replacement text contains html formatted text, then provide it here
}
],
"status": "open", // optional (default: open)
}
const commentElement = client.getCommentElement();
commentElement.addCommentOnElement(element);
```
```jsx theme={null}
const element = {
"targetElement": {
"elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element)
"targetText": "target_text", // optional (pass targetText if you want to add comment on a specific text)
"occurrence": 1, // optional (default: 1) This is relevant for text comment. By default, we will attach comment to the first occurence of the target text in your document. You can change this to attach your comment on a more specific text.
"selectAllContent": true, // Set to `true` if you want to select all the text content of the target element.
},
"commentData": [
{
"commentText": "This is awesome! Well done.", // To set plain text content
"commentHtml": "This is test comment.", // To set HTML formatted content
"replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with
"replaceContentHtml": "This is new comment. ", // If replacement text contains html formatted text, then provide it here
}
],
"status": "open", // optional (default: open)
}
const commentElement = Velt.getCommentElement();
commentElement.addCommentOnElement(element);
```
#### addManualComment
* This feature is particularly useful for complex UIs where you need precise control over the placement of Comment Pins.
* Using this you can manually set the position of Comment Annotations.
* Handle click events on your canvas/document and use the this method to create a comment with custom metadata.
```jsx theme={null}
const context = {
position: {x: 200, y: 100},
};
const commentElement = client.getCommentElement();
const config: ManualCommentAnnotationConfig = {
context: context, // your context here
};
commentElement.addManualComment(config);
```
```jsx theme={null}
const context = {
position: {x: 200, y: 100},
};
const commentElement = Velt.getCommentElement();
const config: ManualCommentAnnotationConfig = {
context: context, // your context here
};
commentElement.addManualComment(config);
```
#### Comment and Reply Placeholders
Customize the placeholder text shown in the Comments dialog inputs to match your product voice and guide first-time users.
```jsx theme={null}
// Using props on VeltComments
```html theme={null}
#### deleteCommentAnnotation
* Deletes a comment annotation
* Params: [DeleteCommentAnnotationRequest](/api-reference/sdk/models/data-models#deletecommentannotationrequest)
* Returns: [DeleteCommentAnnotationEvent](/api-reference/sdk/models/data-models#deletecommentannotationevent)
```jsx theme={null}
const deleteCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { deleteCommentAnnotation } = useDeleteCommentAnnotation();
const deleteCommentAnnotationEvent = await deleteCommentAnnotation(deleteCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const deleteCommentAnnotationEvent = await commentElement.deleteCommentAnnotation(deleteCommentAnnotationRequest);
```
```js theme={null}
const deleteCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const deleteCommentAnnotationEvent = await commentElement.deleteCommentAnnotation(deleteCommentAnnotationRequest);
```
#### deleteSelectedComment
To delete a comment using an API method, use the `deleteSelectedComment()` method.
```jsx theme={null}
if (client) {
const commentElement = client.getCommentElement();
commentElement.deleteSelectedComment();
}
```
```jsx theme={null}
if (Velt) {
const commentElement = Velt.getCommentElement();
commentElement.deleteSelectedComment();
}
```
### [getCommentAnnotationsCount](/api-reference/sdk/api/api-methods#getcommentannotationscount)
* Get the total and unread comment annotations count of all the comment annotations across specified Organization, Folder, Document and Multiple Documents levels.
* If you don't specify any query, it will return data from the folder/documents specified in the `setDocuments` method.
* You can also use this api without setting the document.
* **Auto-batching:** When 2+ `documentIds` are provided, requests are automatically batched to reduce Firestore listeners. Use `debounceMs` to control batching delay (default: 5000ms).
* **Params:** (optional) [CommentRequestQuery](/api-reference/sdk/models/data-models#commentrequestquery)
* Set `aggregateDocuments` to `true` to aggregate comment counts across all documents set in the `setDocuments` method, returning a single combined count instead of per-document counts.
* Set `batchedPerDocument` to `true` if you want to display comment count for a large number of documents (e.g., 100 documents) on the same page. This is now automatically enabled when 2+ `documentIds` are provided.
* Refer to [CommentRequestQuery](/api-reference/sdk/models/data-models#commentrequestquery) for more parameters you can use.
* **Returns:** [GetCommentAnnotationsCountResponse](/api-reference/sdk/models/data-models#getcommentannotationscountresponse)
```jsx Organization Level theme={null}
const { data } = useCommentAnnotationsCount({ organizationId: 'org1' });
useEffect(() => {
if (data) {
console.log('Comment annotations count for org1:', data);
}
}, [data]);
```
```jsx Folder Level theme={null}
const { data } = useCommentAnnotationsCount({
organizationId: 'org1',
folderId: 'folder2',
allDocuments: true
});
useEffect(() => {
if (data) {
console.log('Comment annotations count for folder2:', data);
}
}, [data]);
```
```jsx Document Level (Default) theme={null}
const { data } = useCommentAnnotationsCount();
useEffect(() => {
if (data) {
console.log('Comment annotations count:', data);
}
}, [data]);
```
```jsx Multiple Documents (auto-batched) theme={null}
const { data } = useCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3']
});
useEffect(() => {
if (data) {
// Auto-batching reduces listeners from 3 to 1 for this example
console.log('Comment annotations count for multiple documents:', data);
}
}, [data]);
```
```jsx Aggregate Documents theme={null}
const { data } = useCommentAnnotationsCount({ aggregateDocuments: true });
useEffect(() => {
if (data) {
console.log('Aggregated comment annotations count:', data);
}
}, [data]);
```
```jsx Aggregate Multiple Documents (auto-batched) theme={null}
const { data } = useCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3'],
aggregateDocuments: true
});
useEffect(() => {
if (data) {
// Auto-batching reduces listeners from 3 to 1 for this example
console.log('Aggregated comment annotations count for multiple documents:', data);
}
}, [data]);
```
```jsx Filter out Ghost Comments theme={null}
const { data } = useCommentAnnotationsCount({ filterGhostComments: true });
useEffect(() => {
if (data) {
console.log('Filtered comment annotations count:', data);
}
}, [data]);
```
```jsx Custom Debounce for Auto-batching theme={null}
const { data } = useCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3'],
debounceMs: 3000 // customize debounce (default is 5000ms)
});
useEffect(() => {
if (data) {
// Auto-batching reduces listeners from 3 to 1 for this example
// Custom debounce triggers updates faster (3s instead of default 5s)
console.log('Comment annotations count with custom debounce:', data);
}
}, [data]);
```
**Using API:**
```jsx Organization Level theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({ organizationId: 'org1' }).subscribe((response) => {
console.log('getCommentAnnotationsCount with organizationId', response.data);
});
```
```jsx Folder Level theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({
organizationId: 'org1',
folderId: 'folder2',
allDocuments: true
}).subscribe((response) => {
console.log('getCommentAnnotationsCount with organizationId and folderId and allDocuments', response.data);
});
```
```jsx Document Level (Default) theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount().subscribe((response) => {
console.log('getCommentAnnotationsCount', response.data);
});
```
```jsx Multiple Documents (auto-batched) theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3']
}).subscribe((response) => {
// Auto-batching reduces listeners from 3 to 1 for this example
console.log('getCommentAnnotationsCount for multiple documents', response.data);
});
```
```jsx Aggregate Documents theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({ aggregateDocuments: true }).subscribe((response) => {
console.log('getCommentAnnotationsCount with aggregateDocuments', response.data);
});
```
```jsx Aggregate Multiple Documents (auto-batched) theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3'],
aggregateDocuments: true
}).subscribe((response) => {
// Auto-batching reduces listeners from 3 to 1 for this example
console.log('getCommentAnnotationsCount for aggregated multiple documents', response.data);
});
```
```jsx Filter out Ghost Comments theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({ filterGhostComments: true }).subscribe((response) => {
console.log('getCommentAnnotationsCount with filterGhostComments', response.data);
});
```
```jsx Custom Debounce for Auto-batching theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3'],
debounceMs: 3000 // customize debounce (default is 5000ms)
}).subscribe((response) => {
// Auto-batching reduces listeners from 3 to 1 for this example
// Custom debounce triggers updates faster (3s instead of default 5s)
console.log('Comment annotations count with custom debounce:', response.data);
});
```
```js Organization Level theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({ organizationId: 'org1' }).subscribe((response) => {
console.log('getCommentAnnotationsCount with organizationId', response.data);
});
```
```js Folder Level theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({
organizationId: 'org1',
folderId: 'folder2',
allDocuments: true
}).subscribe((response) => {
console.log('getCommentAnnotationsCount with organizationId and folderId and allDocuments', response.data);
});
```
```js Document Level (Default) theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount().subscribe((response) => {
console.log('getCommentAnnotationsCount', response.data);
});
```
```js Multiple Documents (auto-batched) theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3']
}).subscribe((response) => {
// Auto-batching reduces listeners from 3 to 1 for this example
console.log('getCommentAnnotationsCount for multiple documents', response.data);
});
```
```js Aggregate Documents theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({ aggregateDocuments: true }).subscribe((response) => {
console.log('getCommentAnnotationsCount with aggregateDocuments', response.data);
});
```
```js Filter Ghost Comments theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({ filterGhostComments: true }).subscribe((response) => {
console.log('getCommentAnnotationsCount with filterGhostComments', response.data);
});
```
```js Custom Debounce for Auto-batching theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({
documentIds: ['doc1', 'doc2', 'doc3'],
debounceMs: 3000 // customize debounce (default is 5000ms)
}).subscribe((response) => {
// Auto-batching reduces listeners from 3 to 1 for this example
// Custom debounce triggers updates faster (3s instead of default 5s)
console.log('Comment annotations count with custom debounce:', response.data);
});
```
#### getUnreadCommentAnnotationCountByLocationId
* Get the number of `CommentAnnotations` with at least 1 unread Comment by Location Id.
**Using Hooks:**
```jsx theme={null}
const count = useUnreadCommentAnnotationCountByLocationId(locationId);
useEffect(() => {
console.log(count, 'countObj')
}, [count])
```
**Using API:**
```jsx theme={null}
if (client) {
const commentElement = client.getCommentElement();
let subscription = commentElement.getUnreadCommentAnnotationCountByLocationId(locationId).subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
if (Velt) {
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getUnreadCommentAnnotationCountByLocationId(locationId).subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
#### getCommentAnnotations
* Subscribe to the comment annotations for all the specified documents.
* If you don't specify any query, it will return data from the currently set `documents` and `locations`.
* You can specify 30 documents at a time.
* **Params:** (optional) [CommentRequestQuery](/api-reference/sdk/models/data-models#commentrequestquery)
* **Returns:** [GetCommentAnnotationsResponse](/api-reference/sdk/models/data-models#getcommentannotationsresponse)
Avaiable on SDK version 4.0.0 and above.
**Using Hooks:**
```jsx theme={null}
const { data } = useGetCommentAnnotations(query);
useEffect(() => {
if (data) {
// initial data value will be null while the request is in progress
console.log("Comment Annotations:", data);
}
}, [data]);
```
**Using API:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotations(query).subscribe((response) => {
// initial data value will be null while the request is in progress
console.log("Comment Annotations:", response.data);
});
```
**Using API:**
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotations(query).subscribe((response) => {
// initial data value will be null while the request is in progress
console.log("Comment Annotations:", response.data);
});
```
#### fetchCommentAnnotations
* Fetches comment annotations based on various criteria such as organizationId, folderId, or specific documentIds.
* It supports pagination and filtering options.
* This is different from the existing subscription API which susbcribes to realtime changes to the comments data.
* Params: [FetchCommentAnnotationsRequest](/api-reference/sdk/models/data-models#fetchcommentannotationsrequest)
* Returns: [FetchCommentAnnotationsResponse](/api-reference/sdk/models/data-models#fetchcommentannotationsresponse)
```jsx theme={null}
// Get all annotations for a specific folder
const commentElement = client.getCommentElement();
const response = await commentElement.fetchCommentAnnotations({
organizationId: 'org1',
folderId: 'folder1',
allDocuments: true
});
// Get annotations for specific documents
const response = await commentElement.fetchCommentAnnotations({
organizationId: 'org1',
documentIds: ['doc1', 'doc2']
});
// Get annotations with filters
const response = await commentElement.fetchCommentAnnotations({
organizationId: 'org1',
documentIds: ['doc1', 'doc2'],
createdAfter: 1234567890,
statusIds: ['open'],
pageSize: 20
});
```
```js theme={null}
// Get all annotations for a specific folder
const commentElement = Velt.getCommentElement();
const response = await commentElement.fetchCommentAnnotations({
organizationId: 'org1',
folderId: 'folder1',
allDocuments: true
});
// Get annotations for specific documents
const response = await commentElement.fetchCommentAnnotations({
organizationId: 'org1',
documentIds: ['doc1', 'doc2']
});
// Get annotations with filters
const response = await commentElement.fetchCommentAnnotations({
organizationId: 'org1',
documentIds: ['doc1', 'doc2'],
createdAfter: 1234567890,
statusIds: ['open'],
pageSize: 20
});
```
#### getSelectedComments
* Get the currently selected comment annotations.
* Returns: [`CommentAnnotation[]`](/api-reference/sdk/models/data-models#commentannotation).
```jsx theme={null}
const commentElement = client.getCommentElement();
const subscription = commentElement.getSelectedComments().subscribe((selectedComments) => {
console.log('Selected comments:', selectedComments);
});
```
Unsubscribe from the subscription when you're done:
```jsx theme={null}
subscription?.unsubscribe()
```
```js theme={null}
const commentElement = Velt.getCommentElement();
const subscription = commentElement.getSelectedComments().subscribe((selectedComments) => {
console.log('Selected comments:', selectedComments);
});
```
Unsubscribe from the subscription when you're done:
```js theme={null}
subscription?.unsubscribe()
```
#### getCommentAnnotationById
* Retrieve a specific comment annotation by its ID.
* By default, it will return the comment annotation for the current `documentId`.
* If you pass in a `documentId`, it will return the comment annotation for the given `documentId`.
* Returns: [CommentAnnotation](/api-reference/sdk/models/data-models#commentannotation)
**Using Hooks:**
```jsx theme={null}
const annotation = useCommentAnnotationById({
annotationId: '-O6W3jD0Lz3rxuDuqQFx', // AnnotationID
documentId: 'document-id' // DocumentId (Optional)
});
useEffect(() => {
console.log('annotation', annotation);
}, [annotation]);
```
**Using API:**
```javascript theme={null}
const commentElement = client.getCommentElement();
let subscription = commentElement.getCommentAnnotationById({
annotationId: '-O6W3jD0Lz3rxuDuqQFx', // AnnotationID
documentId: 'document-id' // DocumentId (Optional)
}).subscribe((annotation) => {
console.log('annotation', annotation);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
**Using API:**
```javascript theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getCommentAnnotationById({
annotationId: '-O6W3jD0Lz3rxuDuqQFx', // AnnotationID
documentId: 'document-id' // DocumentId (Optional)
}).subscribe((annotation) => {
console.log('annotation', annotation);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
#### getElementRefByAnnotationId
This will return the Xpath of the DOM element on which the comment was added.
```jsx theme={null}
const commentElement = client.getCommentElement();
let elementRef = commentElement.getElementRefByAnnotationId('annotationId')
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
let elementRef = commentElement.getElementRefByAnnotationId('annotationId')
```
#### submitComment
Programmatically submit a comment from a composer. Enables custom buttons or keyboard shortcuts for submitting comments. The composer must have a `targetComposerElementId` set for this method to work.
* Params: [`SubmitCommentRequest`](/api-reference/sdk/models/data-models#submitcommentrequest)
* Returns: `void`
* See also: [Comment Composer targetComposerElementId](/ui-customization/features/async/comments/standalone-components/comment-composer#target-composer-element-id)
```jsx theme={null}
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.submitComment({ targetComposerElementId: 'composer-1' });
```
#### clearComposer
Reset composer state including text, attachments, recordings, tagged users, assignments, and custom lists.
* Params: [`ClearComposerRequest`](/api-reference/sdk/models/data-models#clearcomposerrequest)
* Returns: `void`
```jsx theme={null}
// Hook
const commentElement = useCommentUtils();
commentElement.clearComposer({ targetComposerElementId: 'composer-1' });
// API Method
const commentElement = client.getCommentElement();
commentElement.clearComposer({ targetComposerElementId: 'composer-1' });
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.clearComposer({ targetComposerElementId: 'composer-1' });
```
#### getComposerData
Fetch current composer state on-demand. Returns same data structure as composerTextChange event.
* Params: [`GetComposerDataRequest`](/api-reference/sdk/models/data-models#getcomposerdatarequest)
* Returns: [`ComposerTextChangeEvent`](/api-reference/sdk/models/data-models#composertextchangeevent)
```jsx theme={null}
// Hook
const commentElement = useCommentUtils();
const composerData = commentElement.getComposerData({
targetComposerElementId: 'composer-1'
});
// API Method
const commentElement = client.getCommentElement();
const composerData = commentElement.getComposerData({
targetComposerElementId: 'composer-1'
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
const composerData = commentElement.getComposerData({
targetComposerElementId: 'composer-1'
});
```
#### markAsRead
* Mark a comment annotation as read for the current user. This updates the `viewedBy` field of the comment annotation to include the current user.
* Params: `annotationId: string`
* Returns: `Promise`
```jsx theme={null}
const markAsReadRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { markAsRead } = useCommentUtils();
await markAsRead(markAsReadRequest);
// API Method
const commentElement = client.getCommentElement();
await commentElement.markAsRead(markAsReadRequest);
```
```js theme={null}
const markAsReadRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
await commentElement.markAsRead(markAsReadRequest);
```
#### markAsUnread
* Mark a comment annotation as unread for the current user. This removes the current user from the `viewedBy` field of the comment annotation.
* Params: `annotationId: string`
* Returns: `Promise`
```jsx theme={null}
const markAsUnreadRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { markAsUnread } = useCommentUtils();
await markAsUnread(markAsUnreadRequest);
// API Method
const commentElement = client.getCommentElement();
await commentElement.markAsUnread(markAsUnreadRequest);
```
```js theme={null}
const markAsUnreadRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
await commentElement.markAsUnread(markAsUnreadRequest);
```
# Messages
#### addComment
* Add a comment to a specific comment annotation
* Params: [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)
* Returns: [AddCommentEvent](/api-reference/sdk/models/data-models#addcommentevent)
```jsx theme={null}
const comment = {
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
};
const addCommentRequest = {
annotationId: 'ANNOTATION_ID',
comment: comment
};
// Hook
const { addComment } = useAddComment();
const addCommentEventData = await addComment(addCommentRequest);
// API Method
const commentElement = client.getCommentElement();
const addCommentEventData = await commentElement.addComment(addCommentRequest);
```
```js theme={null}
const comment = {
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
};
const addCommentRequest = {
annotationId: 'ANNOTATION_ID',
comment: comment
};
const commentElement = Velt.getCommentElement();
const addCommentEventData = await commentElement.addComment(addCommentRequest);
```
#### updateComment
* Update a comment in a specific comment annotation
* Params: [UpdateCommentRequest](/api-reference/sdk/models/data-models#updatecommentrequest)
* Returns: [UpdateCommentEvent](/api-reference/sdk/models/data-models#updatecommentevent)
```jsx theme={null}
const comment = {
commentId: 'COMMENT_ID',
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
};
const updateCommentRequest = {
annotationId: 'ANNOTATION_ID',
comment: comment
};
// Hook
const { updateComment } = useUpdateComment();
const updateCommentEvent = await updateComment(updateCommentRequest);
// API Method
const commentElement = client.getCommentElement();
const updateCommentEvent = await commentElement.updateComment(updateCommentRequest);
```
```js theme={null}
const comment = {
commentId: 'COMMENT_ID',
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
};
const updateCommentRequest = {
annotationId: 'ANNOTATION_ID',
comment: comment
};
const commentElement = Velt.getCommentElement();
const updateCommentEvent = await commentElement.updateComment(updateCommentRequest);
```
#### deleteComment
* Delete a comment from a specific comment annotation
* Params: [DeleteCommentRequest](/api-reference/sdk/models/data-models#deletecommentrequest)
* Returns: [DeleteCommentEvent](/api-reference/sdk/models/data-models#deletecommentevent)
```jsx theme={null}
const deleteCommentRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID
};
// Hook
const { deleteComment } = useDeleteComment();
const deleteCommentEvent = await deleteComment(deleteCommentRequest);
// API Method
const commentElement = client.getCommentElement();
const deleteCommentEvent = await commentElement.deleteComment(deleteCommentRequest);
```
```js theme={null}
const deleteCommentRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID
};
const commentElement = Velt.getCommentElement();
const deleteCommentEvent = await commentElement.deleteComment(deleteCommentRequest);
```
#### getComment
* Get comments from a specific comment annotation
* Params: [GetCommentRequest](/api-reference/sdk/models/data-models#getcommentrequest)
* Returns: [Comment\[\]](/api-reference/sdk/models/data-models#comment)
```jsx theme={null}
const getCommentRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { getComment } = useGetComment();
const comments = await getComment(getCommentRequest);
// API Method
const commentElement = client.getCommentElement();
const comments = await commentElement.getComment(getCommentRequest);
```
```js theme={null}
const getCommentRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const comments = await commentElement.getComment(getCommentRequest);
```
#### getUnreadCommentCountOnCurrentDocument
You can get the number of unread `Comments` on the current `Document` by using the `useUnreadCommentCountOnCurrentDocument()` hook:
```jsx theme={null}
const count = useUnreadCommentCountOnCurrentDocument();
useEffect(() => {
console.log(count, 'countObj')
}, [count])
```
You can get the number of unread `Comments` on the current `Document` by using the `getUnreadCommentCountOnCurrentDocument()` method:
```jsx theme={null}
if (client) {
const commentElement = client.getCommentElement();
let subscription = commentElement.getUnreadCommentCountOnCurrentDocument().subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
You can get the number of unread `Comments` on the current `Document` by using the `getUnreadCommentCountOnCurrentDocument()` method:
```jsx theme={null}
if (Velt) {
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getUnreadCommentCountOnCurrentDocument().subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
#### getUnreadCommentCountByLocationId
You can get the number of unread `Comments` by `Location Id` by using the `useUnreadCommentCountByLocationId()` hook:
```jsx theme={null}
const count = useUnreadCommentCountByLocationId(locationId);
useEffect(() => {
console.log(count, 'countObj')
}, [count])
```
You can get the number of unread `Comments` by `Location Id` by using the `getUnreadCommentCountByLocationId()` method:
```jsx theme={null}
if (client) {
const commentElement = client.getCommentElement();
let subscription = commentElement.getUnreadCommentCountByLocationId(locationId).subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
You can get the number of unread `Comments` by `Location Id` by using the `getUnreadCommentCountByLocationId()` method:
```jsx theme={null}
if (Velt) {
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getUnreadCommentCountByLocationId(locationId).subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
#### getUnreadCommentCountByAnnotationId
You can get the number of unread `Comments` by annotation id by using the `useUnreadCommentCountByAnnotationId()` hook:
```jsx theme={null}
const count = useUnreadCommentCountByAnnotationId(annotationId);
useEffect(() => {
console.log(count, 'countObj')
}, [count])
```
You can get the number of unread `Comments` by annotation id by subscribing to the `getUnreadCommentCountByAnnotationId()` method:
```jsx theme={null}
if (client) {
const commentElement = client.getCommentElement();
let subscription = commentElement.getUnreadCommentCountByAnnotationId(annotationId).subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
You can get the number of unread `Comments` by annotation id by subscribing to the `getUnreadCommentCountByAnnotationId()` method:
```jsx theme={null}
if (Velt) {
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getUnreadCommentCountByAnnotationId(annotationId).subscribe((countObj) => {
console.log(countObj);
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
# @Mentions
#### assignUser
* Assigns a user to a comment annotation
* Params: [AssignUserRequest](/api-reference/sdk/models/data-models#assignuserrequest)
* Returns: [AssignUserEvent](/api-reference/sdk/models/data-models#assignuserevent)
```jsx theme={null}
const assignUserRequest = {
annotationId: 'ANNOTATION_ID',
assignedTo: {
userId: 'USER_ID',
name: 'USER_NAME',
email: 'USER_EMAIL'
}
};
// Hook
const { assignUser } = useAssignUser();
const assignUserEventData = await assignUser(assignUserRequest);
// API Method
const commentElement = client.getCommentElement();
const assignUserEventData = await commentElement.assignUser(assignUserRequest);
```
```js theme={null}
const assignUserRequest = {
annotationId: 'ANNOTATION_ID',
assignedTo: {
userId: 'USER_ID',
name: 'USER_NAME',
email: 'USER_EMAIL'
}
};
const commentElement = Velt.getCommentElement();
const assignUserEventData = await commentElement.assignUser(assignUserRequest);
```
#### setAssignToType
Configure the assign-to UI mode as dropdown or checkbox.
API Method: [`setAssignToType()`](/api-reference/sdk/api/api-methods#setassigntotype)
* Params: [`AssignToConfig`](/api-reference/sdk/models/data-models#assigntoconfig)
* Returns: `void`
```jsx theme={null}
// Using props
```html theme={null}
#### customAutocompleteSearch
* Handle autocomplete search for @mentions. You should use this if you have a large contact list that you want to plug into the autocomplete dropdown, and search directly your own data source.
* Event: [`AutocompleteSearchEvent`](/api-reference/sdk/models/data-models#autocompletesearchevent)
```jsx theme={null}
// Enable via props
```jsx theme={null}
contactElement.updateContactList(users);
```
```jsx theme={null}
commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
const searchText = inputData.searchText;
if (inputData.type === 'contact') {
const filteredUsersData = await __your_api_call__(searchText);
contactElement.updateContactList(filteredUsersData, { merge: false });
}
});
```
```js theme={null}
// Enable via attribute
```js theme={null}
contactElement.updateContactList(users);
```
```js theme={null}
commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
const searchText = inputData.searchText;
if (inputData.type === 'contact') {
const filteredUsersData = await __your_api_call__(searchText);
contactElement.updateContactList(filteredUsersData, { merge: false });
}
});
```
#### enableAtHere
* This allows you to notify all the users explicitly added to the current document.
* It won't notify users in the organization who are not explicitly added to the document.
Default: Disabled.
**Hooks:**
```jsx theme={null}
const contactElement = useContactUtils();
useEffect(() => {
contactElement.enableAtHere();
contactElement.disableAtHere();
}, [contactElement]);
```
**API:**
```jsx theme={null}
const contactElement = client.getContactElement();
contactElement.enableAtHere();
contactElement.disableAtHere();
```
```jsx theme={null}
const contactElement = Velt.getContactElement();
contactElement.enableAtHere();
contactElement.disableAtHere();
```
#### enableUserMentions
* This allows you to enable or disable user @mentions.
Whether user @mentions are enabled.
`Default: true`
Using Props:
```jsx theme={null}
**Using props:**
```jsx theme={null}
#### enablePaginatedContactList
* Limits users downloaded for customers with thousands of users.
* Performance optimization that reduces initial download.
`Default: false`
**Using Props:**
```jsx theme={null}
**Using HTML Attribute:**
```html theme={null}
#### expandMentionGroups
* Expand the user groups and show individual users inside the groups in the @mentions dropdown menu.
```jsx theme={null}
```html theme={null}
#### getContactList
* Subscribe to the list of users added to organization, folder, document, user groups or the ones overwritten using the `updateContactList` API.
* **Params:** none
* **Returns:** [GetContactListResponse](/api-reference/sdk/models/data-models#getcontactlistresponse)
**Using Hooks:**
```jsx theme={null}
const contactList = useContactList();
console.log(contactList); // initial value will be null
```
**Using API:**
```jsx theme={null}
const contactElement = useContactUtils();
contactElement.getContactList().subscribe((response) => {
console.log(response); // initial value will be null
});
```
```js theme={null}
const contactElement = Velt.getContactElement();
contactElement.getContactList().subscribe((response) => {
console.log(response); // initial value will be null
});
```
#### onContactSelected
* This event is triggered when a contact is selected from the contact dropdown in the Comment Dialog.
* Use the event object to determine if the selected contact has access to the document using fields like `isOrganizationContact`, `isDocumentContact` and `documentAccessType`.
* If the selected contact doesn't have access to the document, you can show an invite dialog to the user to invite the contact to the document.
The returned data will be in the following schema:
```jsx theme={null}
export class UserContactSelectedPayload {
contact!: UserContact; // Selected Contact.
isOrganizationContact!: boolean; // Is user part of organization contact.
isDocumentContact!: boolean; // Is user part of document contact.
documentAccessType!: string; // Document access type.
}
```
**Using Hooks:**
```jsx theme={null}
const selectedContact = useContactSelected();
useEffect(() => {
console.log('selectedContact: ', selectedContact);
}, [selectedContact]);
```
**Using API:**
```jsx theme={null}
const contactElement = client.getContactElement();
contactElement.onContactSelected().subscribe((selectedContact: any) => {
console.log('selectedContact : ', selectedContact);
});
```
```jsx theme={null}
const contactElement = Velt.getContactElement();
contactElement.onContactSelected().subscribe((selectedContact: any) => {
console.log('selectedContact: ', selectedContact);
});
```
#### setAtHereLabel
* This allows you to modify the default text of the @here feature. eg: @all, @everyone, @team, etc.
**Using Props:**
```jsx theme={null}
```
**Using Hooks:**
```jsx theme={null}
const contactElement = useContactUtils();
useEffect(() => {
contactElement.setAtHereLabel('@all');
}, [contactElement]);
```
**Using API Method:**
```jsx theme={null}
const contactElement = client.getContactElement();
contactElement.setAtHereLabel('@all');
```
**Using Props:**
```jsx theme={null}
```
**Using API Method:**
```jsx theme={null}
const contactElement = Velt.getContactElement();
contactElement.setAtHereLabel('@all');
```
#### setAtHereDescription
* Customize the description that appears for the @here mention.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### showMentionGroupsFirst
* Show the user groups in the @mentions dropdown menu before the non-group users.
```jsx theme={null}
```html theme={null}
#### showMentionGroupsOnly
* Show only the user groups in the @mentions dropdown menu and not the non-group users.
```jsx theme={null}
```html theme={null}
#### subscribeCommentAnnotation
* Subscribes to a comment annotation
* Params: [SubscribeCommentAnnotationRequest](/api-reference/sdk/models/data-models#subscribecommentannotationrequest)
* Returns: [SubscribeCommentAnnotationEvent](/api-reference/sdk/models/data-models#subscribecommentannotationevent)
```jsx theme={null}
const subscribeCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { subscribeCommentAnnotation } = useSubscribeCommentAnnotation();
const subscribeCommentAnnotationEvent = await subscribeCommentAnnotation(subscribeCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const subscribeCommentAnnotationEvent = await commentElement.subscribeCommentAnnotation(subscribeCommentAnnotationRequest);
```
```js theme={null}
const subscribeCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const subscribeCommentAnnotationEvent = await commentElement.subscribeCommentAnnotation(subscribeCommentAnnotationRequest);
```
#### unsubscribeCommentAnnotation
* Unsubscribes from a comment annotation
* Params: [UnsubscribeCommentAnnotationRequest](/api-reference/sdk/models/data-models#unsubscribecommentannotationrequest)
* Returns: [UnsubscribeCommentAnnotationEvent](/api-reference/sdk/models/data-models#unsubscribecommentannotationevent)
```jsx theme={null}
const unsubscribeCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { unsubscribeCommentAnnotation } = useUnsubscribeCommentAnnotation();
const unsubscribeCommentAnnotationEvent = await unsubscribeCommentAnnotation(unsubscribeCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const unsubscribeCommentAnnotationEvent = await commentElement.unsubscribeCommentAnnotation(unsubscribeCommentAnnotationRequest);
```
```js theme={null}
const unsubscribeCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const unsubscribeCommentAnnotationEvent = await commentElement.unsubscribeCommentAnnotation(unsubscribeCommentAnnotationRequest);
```
#### updateContactList
* By default, the contact list is generated using the users in the organization and the document.
* However, if you do not want to use that feature or want to provide a custom list of contacts, you can use this method.
* By default, it will overwrite the current contact list. You can merge the provided contacts with the existing list by passing the merge flag as `{merge:true}`.
* This method will only update the contact list in the current user session. It doens't update the user contacts in the database or change the access control.
**Using Hooks:**
```jsx theme={null}
const contactElement = useContactUtils();
useEffect(() => {
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: false});
}, [contactElement]);
```
**Using API:**
```jsx theme={null}
const contactElement = client.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: false});
```
```jsx theme={null}
const contactElement = Velt.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: false});
```
#### updateContactListScopeForOrganizationUsers
* Sometimes you may want to show only certain types of contacts in the contact dropdown.
* By default, organization users will see all contacts in the organization, any user groups and any contacts added to the document.
* Using this method, you can restrict the contacts shown in the dropdown to only certain types.
* This only affects the Organization Users and not the Document Users. Document Users will always only see contacts added to the document.
Here are the available options:
* `all`: Show all the contacts
* `organization`: Show organization contacts.
* `organizationUserGroup`: Show organization user groups.
* `document`: Show document contacts.
```jsx theme={null}
const contactElement = client.getContactElement();
contactElement.updateContactListScopeForOrganizationUsers(['all', 'organization', 'organizationUserGroup', 'document']);
```
```jsx theme={null}
const contactElement = Velt.getContactElement();
contactElement.updateContactListScopeForOrganizationUsers(['all', 'organization', 'organizationUserGroup', 'document']);
```
#### [setAnonymousUserDataProvider](/api-reference/sdk/api/api-methods#setanonymoususerdataprovider)
Register a provider to resolve email → `userId` mappings for users who are tagged by email in comments but are not part of the contact list. When a comment is saved and a tagged contact or `to` recipient has an email but no `userId`, the SDK calls the provider to look up the `userId` and backfills it into the comment data before persisting.
[Full implementation guide →](/self-host-data/users#anonymous-user-resolution)
#### autoCompleteScrollConfig
Customize virtual scroll behavior in autocomplete dropdown for @mentions.
Type: [`AutoCompleteScrollConfig`](/api-reference/sdk/models/data-models#autocompletescrollconfig)
```jsx theme={null}
```html theme={null}
# Metadata
#### addContext
Custom metadata allows you to add extra information to comments, enhancing their functionality. Here's what you can do with it:
* Render additional data on comments
* Position comment pins manually
* Create custom UI components
* Enable comment filtering on custom data
To add custom metadata, use one of the following events which has the `addContext` method. This method accepts an object with key-value pairs.
* `addCommentAnnotationDraft`
* `addCommentAnnotation`
Alternatively, you can pass `context` as a prop to most components that helps with creating new comment annotations. Eg:
* `VeltCommentTool`
* `VeltCommentComposer`
* `VeltCommentDialogComposer`
* `VeltInlineCommentsSection`
```jsx theme={null}
// Hook
const commentEventCallbackData = useCommentEventCallback('addCommentAnnotation');
useEffect(() => {
if (commentEventCallbackData) {
commentEventCallbackData.addContext({ customKey: 'customValue' });
}
}, [commentEventCallbackData]);
// API Method
const commentElement = client.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
event.addContext({ customKey: 'customValue' });
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
event.addContext({ customKey: 'customValue' });
});
```
#### updateContext
* Update the custom metadata associated with a comment annotation using the `updateContext` method.
* Utilize this method to update the context of a comment annotation at any time. For example, you might use this when the name of the dashboard containing the comment annotation changes.
The `commentElement.updateContext()` method accepts three parameters:
* The Comment Annotation ID
* The new metadata object
* An optional `updateContextConfig` object. Specify how the new metadata should be applied:
* `{ merge: true }`: Merges the new metadata with the existing metadata
* `{ merge: false }` or omitted: Replaces the existing metadata entirely (default behavior)
Using API:
```js theme={null}
const updatedContext = { customKey: 'customValue' };
const updateContextConfig = { merge: true };
const commentElement = client.getCommentElement();
commentElement.updateContext(COMMENT_ANNOTATION_ID, updatedContext, updateContextConfig);
```
Using API method:
```js theme={null}
const updatedContext = { customKey: 'customValue' };
const updateContextConfig = { merge: true };
const commentElement = client.getCommentElement();
commentElement.updateContext(COMMENT_ANNOTATION_ID, updatedContext, updateContextConfig);
```
#### setContextProvider
Provide custom context (metadata) dynamically for comments using a provider function. This method allows you to return context based on the document and location where a comment is being added.
The SDK will call this function whenever a new comment annotation is created so you can provide dynamic values for the context.
The provider function receives `documentId` and optional `location` parameters and can return a [`CommentContext`](/api-reference/sdk/models/data-models#commentcontext) object, `null`, `undefined`, or a Promise resolving to any of these values.
```jsx theme={null}
// Hook
import { useCallback, useEffect } from 'react';
import { useSetContextProvider } from '@veltdev/react';
const contextProvider = useCallback((documentId, location) => {
return {
customKey: 'customValue'
};
}, []);
const { setContextProvider } = useSetContextProvider();
useEffect(() => {
if (setContextProvider && contextProvider) {
setContextProvider(contextProvider);
}
}, []);
// API Method
const commentElement = client.getCommentElement();
commentElement.setContextProvider((documentId, location) => {
return {
customKey: 'customValue'
};
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setContextProvider((documentId, location) => {
return {
customKey: 'customValue'
};
});
```
#### setContextInPageModeComposer
Set context data for the page mode composer programmatically.
Accepts a [`PageModeComposerConfig`](/api-reference/sdk/models/data-models#pagemodecomposerconfig) object. Pass custom context data that will be included when a comment is created through the page mode composer.
API Method: [`setContextInPageModeComposer()`](/api-reference/sdk/api/api-methods#setcontextinpagemodecomposer)
For automatic context passing when opening the comment sidebar via the comment tool, see [contextInPageModeComposer](#contextinpagemodecomposer).
```jsx theme={null}
// Using Hook
const commentElement = useCommentUtils();
// Set context with optional target element
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1'
});
// Using API Method
const commentElement = client.getCommentElement();
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1'
});
// Set only context without target element
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123' }
});
// Clear the context and target element
commentElement.setContextInPageModeComposer({
context: null,
targetElementId: null
});
// Preserve context after submission
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1',
clearContext: false
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
// Set context with optional target element
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1'
});
// Set only context without target element
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123' }
});
// Clear the context and target element
commentElement.setContextInPageModeComposer({
context: null,
targetElementId: null
});
// Preserve context after submission
commentElement.setContextInPageModeComposer({
context: { documentId: 'doc-123', section: 'intro' },
targetElementId: 'element-1',
clearContext: false
});
```
#### clearPageModeComposerContext
Clear context data from page mode composer. This is useful when you are using sidebar in embed mode and have to clear the context from page mode composer manually.
API Method: [`clearPageModeComposerContext()`](/api-reference/sdk/api/api-methods#clearpagemodecomposercontext)
* Params: none
* Returns: `void`
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.clearPageModeComposerContext();
```
```html theme={null}
```
# Aggregation
### Overview
**Aggregation** lets you filter, group, and render comments that match specific criteria — without writing any custom logic.\
It's especially powerful when comments are tied to structured data such as products, categories, or financial entities.
You can group comments by:
* Metadata (`context`)
* Element IDs (`targetElementId`)
* Resource identifiers (`documentId`, `folderId`, `locationId`)
In short: aggregation helps you **query comments like data**.
***
### When to Use Aggregation
Use aggregation when your app involves complex relationships or taxonomy-based filtering.
#### 🧩 Tables & Dashboards
**Supply Chain Example**\
A product can belong to multiple categories. When viewing data by category, you may want to display all comments made on products within that category — or even across product variants.
**Financial Planning Example**\
A budget item (e.g., *Marketing Q1*) can have multiple subcategories (e.g., *Paid Ads*, *Sponsorships*).\
Aggregation allows you to show all comments related to a specific period, department, or account group — even if those comments live across different documents or views.
***
### How It Works
#### Comment Metadata Fields
Each comment can include one or more of the following identifiers or metadata fields:
| Field | Description |
| ----------------- | ------------------------------------------------ |
| `folderId` | Target folder ID |
| `documentId` | Target document ID |
| `locationId` | Target location ID |
| `targetElementId` | Target DOM element ID |
| `context` | Custom metadata object for grouping or filtering |
***
#### Comment Creation
When you use any of the above identifiers or metadata fields in the following supported components, they automatically get **attached to the comment** at the time it's created.\
This ensures that each comment carries the correct folder, document, element, or context metadata — so it can later be filtered or grouped accurately.
**Supported Components**
* Inline Comments Section
* Comment Tool
```jsx theme={null}
// Comment Tool with context metadata
```html theme={null}
```
***
#### Comment Rendering
When the above identifiers or metadata fields are passed to the following rendering components, they determine **which comments are displayed**.\
Only comments that match the provided folder, document, element, or context values will be rendered in that component.
**Supported Components**
* Comment Bubble
* Inline Comments Section
* Comment Pin (Standalone) — *does not support* `targetElementId`
```jsx theme={null}
// Comment Bubble - filter by context
```html theme={null}
```
***
### Filtering Behavior
When filtering comments, only annotations matching **all provided fields** will be shown:
```
folderId
documentId
locationId
targetElementId
context
```
***
### `Context` Matching
You can choose between two matching modes for the `context` field: **Full Match** (default) or **Partial Match**.
***
#### 🔒 Full Match (Default)
A comment matches **only if all fields** in its context exactly match your filter criteria.
**Example:**
```js theme={null}
// Comment context
{ month: "jan", product: "cheese", location: "zurich" }
// Filters
{ month: "jan", product: "cheese", location: "zurich" } ✅ Matches
{ month: "jan", product: "cheese" } ❌ No match (missing field)
{ month: "jan", product: "cheese", year: "2024" } ❌ No match (extra field)
```
```jsx theme={null}
// Full match (default)
```html theme={null}
```
***
#### 🔍 Partial Match
Enable partial matching with `contextOptions={{ partialMatch: true }}`.
A comment matches if **all fields in your filter exist in the comment's context**.\
Extra fields in the comment context don't prevent a match.
**Example:**
```js theme={null}
// Comment context
{ day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }
// Filters
{ product: "cheese" } ✅ Matches
{ day: "01", product: "cheese" } ✅ Matches
{ product: "cheese", category: "dairy"} ❌ No match (missing field)
```
**Example**
```jsx theme={null}
{/* Comment Bubble with Partial Match */}
```html theme={null}
```
***
### Grouping Matched Comment Annotations
When multiple comments match your filter criteria, you can **group them** into a single visual element — such as a Comment Bubble, Comment Pin, or Inline Comments Section — for a cleaner, multi-threaded UI.
**How it works:**
* Enable grouping globally with `groupMatchedComments`
* All matching annotations are shown as one grouped thread
* The comment count shows total grouped annotations
* Users can expand to view and interact with all related threads
**Example**
If there are three comments for `"product: cheese"` across different months, they can all appear in one Comment Bubble when you filter by `{ product: "cheese" }`.
```jsx theme={null}
// Enable grouping globally
```html theme={null}
```
***
# Private Comments
The visibility system uses two separate sets of values:
* **API methods** (on this page) use [`CommentVisibilityConfig`](/api-reference/sdk/models/data-models#commentvisibilityconfig) with 3 values: `'public'`, `'organizationPrivate'`, `'restricted'`.
* **UI wireframes** use the [`CommentVisibilityOption`](/api-reference/sdk/models/data-models#commentvisibilityoption) enum with 4 values: `'restrictedSelf'`, `'restrictedSelectedPeople'`, `'organizationPrivate'`, `'public'`.
The API's single `'restricted'` value covers both "self-only" and "selected people" — distinguished by whether `userIds` is provided.
#### [updateVisibility](/api-reference/sdk/api/api-methods#updatevisibility)
Manage who can view a comment annotation by updating its visibility settings. Use this method to control whether a comment is public, restricted to your organization, or visible only to specific users. The resulting setting is stored on the annotation as [`visibilityConfig`](/api-reference/sdk/models/data-models#commentannotationvisibilityconfig).
* To use this feature, you need to first enable it in [Velt Console](https://console.velt.dev/dashboard/config/appconfig)
* Params: [CommentVisibilityConfig](/api-reference/sdk/models/data-models#commentvisibilityconfig)
* `type`:
* `'public'`: Comment visible to all users
* `'organizationPrivate'`: Comment visible only to users in the specified organization. Even if someone is added to the document but not to the organization, they will not be able to view the comment.
* `'restricted'`: Comment visible only to the specified users; the current user is always included
* `organizationId`: string; required if `type` is `organizationPrivate`
* `userIds`: string\[]; optional when `type` is `'restricted'` — current user is always appended
* Returns: `void`
When `type` is `'restricted'`, the SDK automatically appends the current user's `userId` to `userIds` if it is not already present. This applies whether `userIds` is empty or contains an explicit list that excludes the author.
```jsx theme={null}
const commentElement = client.getCommentElement();
// Set comment to be visible only to the organization
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'organizationPrivate',
organizationId: 'org-123'
});
// Set comment to be private (current user always included in restricted access)
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'restricted'
});
// Set comment to be private (visible only to specific users)
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'restricted',
userIds: ['user-1', 'user-2']
});
// Set comment to be public
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'public'
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
// Set comment to be visible only to the organization
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'organizationPrivate',
organizationId: 'org-123'
});
// Set comment to be private (current user always included in restricted access)
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'restricted'
});
// Set comment to be private (visible only to specific users)
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'restricted',
userIds: ['user-1', 'user-2']
});
// Set comment to be public
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'public'
});
```
#### [enablePrivateMode](/api-reference/sdk/api/api-methods#enableprivatemode)
Set the default visibility for all new comments created by the current user.
* Params: [PrivateModeConfig](/api-reference/sdk/models/data-models#privatemodeconfig)
* `type`:
* `'restricted'`: New comments visible only to the specified users; the current user is always included
* `'organizationPrivate'`: New comments visible only to users in the current organization
* `userIds`: string\[]; optional when `type` is `'restricted'` — current user is always appended
* Returns: `void`
When `type` is `'restricted'`, the SDK automatically appends the current user's `userId` to `userIds` if it is not already present. This applies whether `userIds` is empty or contains an explicit list that excludes the author.
```jsx theme={null}
const commentElement = client.getCommentElement();
// Restrict all new comments to specific users
commentElement.enablePrivateMode({ type: 'restricted', userIds: ['user-1', 'user-2'] });
// Restrict all new comments to the current organization
commentElement.enablePrivateMode({ type: 'organizationPrivate' });
```
```js theme={null}
const commentElement = Velt.getCommentElement();
// Restrict all new comments to specific users
commentElement.enablePrivateMode({ type: 'restricted', userIds: ['user-1', 'user-2'] });
// Restrict all new comments to the current organization
commentElement.enablePrivateMode({ type: 'organizationPrivate' });
```
#### [disablePrivateMode](/api-reference/sdk/api/api-methods#disableprivatemode)
Revert new comment visibility to default public visibility.
* Returns: `void`
```jsx theme={null}
const commentElement = client.getCommentElement();
// Revert to default public visibility
commentElement.disablePrivateMode();
```
```js theme={null}
const commentElement = Velt.getCommentElement();
// Revert to default public visibility
commentElement.disablePrivateMode();
```
#### visibilityOptions
Show a visibility banner on the comment composer that lets users set a comment's visibility to `public`, `organization-private`, `restricted-self`, or `restricted` before submitting. Users can also change visibility after submission from the thread options menu.
Default: `false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### visibilityOptionClicked
Subscribe to this event to be notified when a user selects a visibility option. Emits a [`VisibilityOptionClickedEvent`](/api-reference/sdk/models/data-models#visibilityoptionclickedevent).
#### Setting visibility at comment creation time
If you are creating comments using API, then pass a [`CommentVisibilityConfig`](/api-reference/sdk/models/data-models#commentvisibilityconfig) as the optional `visibility` field on [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest) to pre-set visibility when programmatically adding a comment.
**Using Hooks:**
```jsx theme={null}
const addCommentRequest = {
annotationId: 'ANNOTATION_ID',
comment: {
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
},
visibility: {
type: 'restricted',
userIds: ['user-1', 'user-2']
}
};
const { addComment } = useAddComment();
const addCommentEventData = await addComment(addCommentRequest);
```
**Using API:**
```jsx theme={null}
const addCommentRequest = {
annotationId: 'ANNOTATION_ID',
comment: {
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
},
visibility: {
type: 'restricted',
userIds: ['user-1', 'user-2']
}
};
const commentElement = client.getCommentElement();
const addCommentEventData = await commentElement.addComment(addCommentRequest);
```
```jsx theme={null}
const addCommentRequest = {
annotationId: 'ANNOTATION_ID',
comment: {
commentText: 'This is a comment',
commentHtml: 'This is a comment
',
},
visibility: {
type: 'restricted',
userIds: ['user-1', 'user-2']
}
};
const commentElement = Velt.getCommentElement();
const addCommentEventData = await commentElement.addComment(addCommentRequest);
```
# Custom Lists
#### createCustomListDataOnAnnotation
* Add a custom dropdown list at the Comment Annotation level.
* Use this to add custom tags or categories to the comment.
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.createCustomListDataOnAnnotation(customListDataOnCommentAnnotation);
```
#### createCustomListDataOnComment
You can have custom dropdown lists appear when certain `hotkeys` are pressed.
When you press a hotkey inside the Comment Dialog composer, it will open a dropdown list of items that you can select.
Grouped lists: Useful for workflows like issue trackers (e.g., group by "Priority" or "Status"), allowing users to quickly refer and insert custom entities from your app. With this feature, you can combine multiple entity types into one drop down just like Linear.
Make sure the hotkey is a single character such as `#` or `/`.
The items in the list must be in the following schema:
Use `AutocompleteGroup` only for grouped lists. For flat lists, do not include `groups` on the config object or `groupId` on items.
```jsx theme={null}
export class AutocompleteGroup {
id!: string;
name!: string;
}
export class AutocompleteItem {
id!: string; // Unique identifier
name!: string; // Item name. This appears as the main item text in the UI.
description?: string; // Item description. This appears as the secondary item text in the UI.
icon?: { url?: string; svg?: string }; // Item icon. Either URL or inline SVG.
link?: string; // Item link. You can use this to open a link when the item is clicked. Check the event listener below for more details.
groupId?: string; // Optional: assigns item to a group (by AutocompleteGroup.id)
}
```
##### **Flat List Implementation**
```jsx theme={null}
let customList = [
{ id: '1', name: 'File 1', description: 'File Description 1', icon: { url: 'https://cdn-icons-png.flaticon.com/512/9496/9496432.png' } },
{ id: '2', name: 'File 2', description: 'File Description 2', icon: { url: 'https://cdn-icons-png.flaticon.com/512/11471/11471469.png' } },
{ id: '3', name: 'File 3', description: 'File Description 3', icon: { url: 'https://cdn-icons-png.flaticon.com/512/2656/2656402.png' } }
];
const customListDataOnComment = {
hotkey: 'UNIQUE_HOTKEY', // only single charater is allowed. eg: '#'
type: 'custom',
data: customList, // your customList data here
};
```
```jsx theme={null}
// Using Props
```jsx theme={null}
// Using Props
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.createCustomListDataOnComment(customListDataOnComment);
```
##### **Grouped List Implementation**
```ts theme={null}
const customListWithGroups = {
hotkey: '$',
type: 'custom',
groups: [
{ id: 'categories', name: 'Categories' },
{ id: 'priorities', name: 'Priorities' }
],
data: [
// Categories group
{ id: 'bug_1', name: 'Bug 1', description: 'Bug report 1', groupId: 'categories', icon: { svg: '
```ts theme={null}
// Using Props
```ts theme={null}
const commentElement = client.getCommentElement();
commentElement.createCustomListDataOnComment(customListWithGroups);
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.createCustomListDataOnComment(customListWithGroups);
```
##### **Listen to click events on chips**
After the comment is saved, the item will be rendered as a chip on the comment content. When the user clicks on it, you will get an event callback with the data of the clicked chip (`AutocompleteItem`).
This event will also be triggered when the user clicks on the contact chips added via the @mentions feature.
```jsx theme={null}
let autocompleteChipData = useAutocompleteChipClick();
```
```jsx theme={null}
const autocompleteElement = client.getAutocompleteElement();
const subscription = autocompleteElement.onAutocompleteChipClick().subscribe((_data) => {
console.log(_data);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const autocompleteElement = Velt.getAutocompleteElement();
const subscription = autocompleteElement.onAutocompleteChipClick().subscribe((_data) => {
console.log(_data);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
#### customAutocompleteSearch
* Handle autocomplete search for custom list. You should use this if you have a large list that you want to plug into the autocomplete dropdown, and search directly your own data source.
* Event: [`AutocompleteSearchEvent`](/api-reference/sdk/models/data-models#autocompletesearchevent)
```jsx theme={null}
// Enable via props
```jsx theme={null}
// For @mentions feature
contactElement.updateContactList(users);
// For custom list feature
commentElement.createCustomListDataOnComment({
hotkey: "#",
type: "custom",
data: customListData,
});
```
```jsx theme={null}
commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
const searchText = inputData.searchText;
// For @mentions feature
if (inputData.type === 'contact') {
const filteredUsersData = await __your_api_call__(searchText);
contactElement.updateContactList(filteredUsersData, { merge: false });
}
// For custom list feature
if (inputData.type === 'custom') {
const filteredListData = await __your_api_call__(searchText, autocompleteData);
commentElement.createCustomListDataOnComment({
hotkey: "#",
type: "custom",
data: filteredListData,
});
}
});
```
```js theme={null}
// Enable via attribute
```js theme={null}
commentElement.createCustomListDataOnComment({
hotkey: "#",
type: "custom",
data: customListData,
});
```
```js theme={null}
commentElement.on('autocompleteSearch').subscribe(async (inputData) => {
const searchText = inputData.searchText;
if (inputData.type === 'custom') {
const filteredListData = await __your_api_call__(searchText, autocompleteData);
commentElement.createCustomListDataOnComment({
hotkey: "#",
type: "custom",
data: filteredListData,
});
}
});
```
# Event Subscription
### [on](/api-reference/sdk/api/api-methods#on)
Subscribe to Comment Events. Here is the list of events you can subscribe to and the event objects you will receive.
| Category | Event Type | Description | Event Object |
| ----------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Threads | `addCommentAnnotationDraft` | Triggered before `addCommentAnnotation` event clicks on the comment tool and the composer is rendered. | [AddCommentAnnotationDraftEvent](/api-reference/sdk/models/data-models#addcommentannotationdraftevent) |
| Threads | `addCommentAnnotation` | Add a new comment annotation | [AddCommentAnnotationEvent](/api-reference/sdk/models/data-models#addcommentannotationevent) |
| Threads | `deleteCommentAnnotation` | Delete a comment annotation | [DeleteCommentAnnotationEvent](/api-reference/sdk/models/data-models#deletecommentannotationevent) |
| Messages | `addComment` | Add a new comment | [AddCommentEvent](/api-reference/sdk/models/data-models#addcommentevent) |
| Messages | `updateComment` | Update an existing comment | [UpdateCommentEvent](/api-reference/sdk/models/data-models#updatecommentevent) |
| Messages | `deleteComment` | Delete a comment | [DeleteCommentEvent](/api-reference/sdk/models/data-models#deletecommentevent) |
| @Mentions | `assignUser` | Assign a user to a comment | [AssignUserEvent](/api-reference/sdk/models/data-models#assignuserevent) |
| @Mentions | `subscribeCommentAnnotation` | Subscribe to a comment annotation | [SubscribeCommentAnnotationEvent](/api-reference/sdk/models/data-models#subscribecommentannotationevent) |
| @Mentions | `unsubscribeCommentAnnotation` | Unsubscribe from a comment annotation | [UnsubscribeCommentAnnotationEvent](/api-reference/sdk/models/data-models#unsubscribecommentannotationevent) |
| @Mentions | `autocompleteSearch` | When user starts searching for a contact in the @mentions dropdown or for a list item in the custom list dropdown | [AutocompleteSearchEvent](/api-reference/sdk/models/data-models#autocompletesearchevent) |
| Attachments | `addAttachment` | Add an attachment to a comment | [AddAttachmentEvent](/api-reference/sdk/models/data-models#addattachmentevent) |
| Attachments | `deleteAttachment` | Delete an attachment from a comment | [DeleteAttachmentEvent](/api-reference/sdk/models/data-models#deleteattachmentevent) |
| Attachments | `attachmentDownloadClicked` | Triggered when attachment download button is clicked | [AttachmentDownloadClickedEvent](/api-reference/sdk/models/data-models#attachmentdownloadclickedevent) |
| Reactions | `addReaction` | Add a reaction to a comment | [AddReactionEvent](/api-reference/sdk/models/data-models#addreactionevent) |
| Reactions | `deleteReaction` | Delete a reaction from a comment | [DeleteReactionEvent](/api-reference/sdk/models/data-models#deletereactionevent) |
| Reactions | `toggleReaction` | Toggle a reaction on a comment | [ToggleReactionEvent](/api-reference/sdk/models/data-models#togglereactionevent) |
| Status & Priority | `updateStatus` | Update the status of a comment | [UpdateStatusEvent](/api-reference/sdk/models/data-models#updatestatusevent) |
| Status & Priority | `resolveComment` | Resolve a comment | [ResolveCommentEvent](/api-reference/sdk/models/data-models#resolvecommentevent) |
| Status & Priority | `updatePriority` | Update the priority of a comment | [UpdatePriorityEvent](/api-reference/sdk/models/data-models#updatepriorityevent) |
| Status & Priority | `approveCommentAnnotation` | Approve a comment annotation | [ApproveCommentAnnotationEvent](/api-reference/sdk/models/data-models#approvecommentannotationevent) |
| Status & Priority | `acceptCommentAnnotation` | Accept a comment annotation | [AcceptCommentAnnotationEvent](/api-reference/sdk/models/data-models#acceptcommentannotationevent) |
| Status & Priority | `rejectCommentAnnotation` | Reject a comment annotation | [RejectCommentAnnotationEvent](/api-reference/sdk/models/data-models#rejectcommentannotationevent) |
| Recordings | `deleteRecording` | Delete a recording from a comment | [DeleteRecordingEvent](/api-reference/sdk/models/data-models#deleterecordingevent) |
| Deep Links | `copyLink` | Copy a deep link to a comment | [CopyLinkEvent](/api-reference/sdk/models/data-models#copylinkevent) |
| Comment Sidebar | `commentSidebarDataInit` | Triggered when comment sidebar data is first loaded | [CommentSidebarDataInitEvent](/api-reference/sdk/models/data-models#commentsidebardatainitevent) |
| Comment Sidebar | `commentSidebarDataUpdate` | Triggered when comment sidebar data is updated | [CommentSidebarDataUpdateEvent](/api-reference/sdk/models/data-models#commentsidebardataupdateevent) |
| UI | `composerClicked` | Triggered when comment composer is clicked | [ComposerClickedEvent](/api-reference/sdk/models/data-models#composerclickedevent) |
| UI | `composerTextChange` | Triggered when text changes in any comment composer. Includes full draft annotation object and composer ID. | [ComposerTextChangeEvent](/api-reference/sdk/models/data-models#composertextchangeevent) |
| UI | `commentPinClicked` | Triggered when a comment pin is clicked | [CommentPinClickedEvent](/api-reference/sdk/models/data-models#commentpinclickedevent) |
| UI | `commentBubbleClicked` | Triggered when a comment bubble is clicked | [CommentBubbleClickedEvent](/api-reference/sdk/models/data-models#commentbubbleclickedevent) |
| UI | `linkClicked` | Triggered when a clickable link in comment content is clicked | [LinkClickedEvent](/api-reference/sdk/models/data-models#linkclickedevent) |
| UI | `commentToolClicked` | Past-tense alias for `commentToolClick`, identical payload | [CommentToolClickedEvent](/api-reference/sdk/models/data-models#commenttoolclickedevent) |
| UI | `sidebarButtonClicked` | Past-tense alias for `sidebarButtonClick`, identical payload | [SidebarButtonClickedEvent](/api-reference/sdk/models/data-models#sidebarbuttonclickedevent) |
| Recorder | `transcriptionDone` | Triggered when a transcription is generated and ready | [TranscriptionDoneEvent](/api-reference/sdk/models/data-models#transcriptiondoneevent) |
| Threads | `commentSaved` | Triggered when a comment annotation is saved to the database | [CommentSavedEvent](/api-reference/sdk/models/data-models#commentsavedevent) |
| Threads | `commentSaveTriggered` | Triggered immediately when the save button is clicked, before async save completes | [CommentSaveTriggeredEvent](/api-reference/sdk/models/data-models#commentsavetriggeredevent) |
| Visibility | `visibilityOptionClicked` | Triggered when a user selects a visibility option | [VisibilityOptionClickedEvent](/api-reference/sdk/models/data-models#visibilityoptionclickedevent) |
```jsx theme={null}
// Hook
const commentEventCallbackData = useCommentEventCallback('addCommentAnnotation');
useEffect(() => {
if (commentEventCallbackData) {
// Handle comment action callback event response
}
}, [commentEventCallbackData]);
// API Method
const commentElement = client.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
// Handle the event response
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
// Handle the event response
});
```
# Attachments
#### enableAttachments
```js theme={null}
```js theme={null}
#### enableAttachmentDownload
Controls whether clicking an attachment triggers a file download.
Default: `true`
When disabled, users can still click attachments but no download is triggered. The `attachmentDownloadClicked` event fires on every attachment click regardless of this setting.
```jsx theme={null}
// Using Component Props
```html theme={null}
#### enableScreenshot
Whether screenshot option is enabled in comments.
Default: `false`
When enabled, users can attach screenshots when adding comments. This provides a quick way to capture and share visual context.
```jsx theme={null}
// Using Component Props
```html theme={null}
#### addAttachment
* Add an attachment to a specific comment annotation
* Params: [AddAttachmentRequest](/api-reference/sdk/models/data-models#addattachmentrequest)
* Returns: Promise\<[AddAttachmentResponse\[\]](/api-reference/sdk/models/data-models#addattachmentresponse)>
```jsx theme={null}
const addAttachmentRequest = {
annotationId: 'ANNOTATION_ID',
files: ''
};
// Hook
const { addAttachment } = useAddAttachment();
const attachmentResponses = await addAttachment(addAttachmentRequest);
// API Method
const commentElement = client.getCommentElement();
const attachmentResponses = await commentElement.addAttachment(addAttachmentRequest);
```
```js theme={null}
const addAttachmentRequest = {
annotationId: 'ANNOTATION_ID',
files: ''
};
const commentElement = Velt.getCommentElement();
const attachmentResponses = await commentElement.addAttachment(addAttachmentRequest);
```
#### deleteAttachment
* Delete an attachment from a specific comment annotation
* Params: [DeleteAttachmentRequest](/api-reference/sdk/models/data-models#deleteattachmentrequest)
* Returns: Promise\<[DeleteAttachmentEvent](/api-reference/sdk/models/data-models#deleteattachmentevent) | null>
```jsx theme={null}
const deleteAttachmentRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID,
attachmentId: 'ATTACHMENT_ID'
};
// Hook
const { deleteAttachment } = useDeleteAttachment();
const deleteAttachmentEvent = await deleteAttachment(deleteAttachmentRequest);
// API Method
const commentElement = client.getCommentElement();
const deleteAttachmentEvent = await commentElement.deleteAttachment(deleteAttachmentRequest);
```
```js theme={null}
const deleteAttachmentRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID,
attachmentId: 'ATTACHMENT_ID'
};
const commentElement = Velt.getCommentElement();
const deleteAttachmentEvent = await commentElement.deleteAttachment(deleteAttachmentRequest);
```
#### getAttachment
* Get attachments from a specific comment annotation
* Params: [GetAttachmentRequest](/api-reference/sdk/models/data-models#getattachmentrequest)
* Returns: Promise\<[Attachment\[\]](/api-reference/sdk/models/data-models#attachment)>
```jsx theme={null}
const getAttachmentRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID,
};
// Hook
const { getAttachment } = useGetAttachment();
const attachments = await getAttachment(getAttachmentRequest);
// API Method
const commentElement = client.getCommentElement();
const attachments = await commentElement.getAttachment(getAttachmentRequest);
```
```js theme={null}
const getAttachmentRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID,
};
const commentElement = Velt.getCommentElement();
const attachments = await commentElement.getAttachment(getAttachmentRequest);
```
#### allowedFileTypes
Limit file types in comment attachments by specifying allowed file extensions.
Default: Not specified (all supported file types allowed)
When this property is set, users can only attach files with the specified extensions. This helps you maintain security standards and ensure only approved file types are shared in collaborative discussions.
By default, Velt supports `.png`, `.jpg`, `.gif` (static & animated), `.svg` file types up to 15MB per file. With `allowedFileTypes`, you can restrict to a subset of these or any other file extensions your application requires.
```jsx theme={null}
// Using component prop
```html theme={null}
#### attachmentNameInMessage
Display the attachment filename in the message when a file is attached.
Default: `false`
When this property is enabled, the attachment filename will appear in the message text when a user selects a file to attach. This provides immediate visual confirmation of which file they've attached to their comment, improving clarity before submitting.
```jsx theme={null}
```html theme={null}
#### setComposerFileAttachments
Programmatically add file attachments to the comment composer from your application instead of requiring users to select files from the file system.
This method enables workflows where you want to attach files programmatically, such as:
* Attaching screenshots captured within your application
* Including generated reports or documents
* Adding files from your own storage system
* Pre-populating attachments based on user context
Params: [UploadFileData](/api-reference/sdk/models/data-models#uploadfiledata)
The `UploadFileData` object accepts the following properties:
* `files` (required): Array of File objects to attach to the comment composer
* `annotationId` (optional): ID of the target comment annotation. Use this to add attachments to an existing comment thread
* `targetElementId` (optional): ID of the target element where the comment composer is attached. Use this to add attachments to a specific element
```jsx theme={null}
const commentElement = client.getCommentElement();
// Add attachments to a new comment composer
commentElement.setComposerFileAttachments({
files: [file1, file2],
});
// Add attachments to an existing comment annotation
commentElement.setComposerFileAttachments({
files: [file1, file2],
annotationId: 'annotation-123',
});
// Add attachments to a comment composer on a specific element
commentElement.setComposerFileAttachments({
files: [file1, file2],
targetElementId: 'element-456',
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
// Add attachments to a new comment composer
commentElement.setComposerFileAttachments({
files: [file1, file2],
});
// Add attachments to an existing comment annotation
commentElement.setComposerFileAttachments({
files: [file1, file2],
annotationId: 'annotation-123',
});
// Add attachments to a comment composer on a specific element
commentElement.setComposerFileAttachments({
files: [file1, file2],
targetElementId: 'element-456',
});
```
#### attachmentDownload
Control whether attachment downloads happen automatically when users click the download button.
Default: `true`
When enabled, clicking the download button on an attachment will automatically download the file. When disabled, the automatic download is prevented, and you can handle the download action with custom logic by subscribing to the `attachmentDownloadClicked` event.
This is useful for:
* Tracking download analytics before initiating the download
* Implementing custom download URLs or CDN routes
* Adding access control checks before allowing downloads
```jsx theme={null}
// Using component prop
```html theme={null}
# Text Formatting
#### enableFormatOptions
Enable rich text formatting toolbar in comment composers. Users can apply bold, italic, underline, and strikethrough formatting.
Default: `false`
```jsx theme={null}
// Using Component Props
```html theme={null}
#### setFormatConfig
Configure which format types are available in the formatting toolbar.
Params: [`FormatConfig`](/api-reference/sdk/models/data-models#formatconfig)
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
commentElement.setFormatConfig({
bold: { enable: true },
italic: { enable: true },
underline: { enable: false },
strikethrough: { enable: false }
});
// Using API methods
const commentElement = client.getCommentElement();
commentElement.setFormatConfig({
bold: { enable: true },
italic: { enable: true },
underline: { enable: false },
strikethrough: { enable: false }
});
```
```html theme={null}
```
# Reactions
#### enableReactions
```jsx theme={null}
```jsx theme={null}
#### setCustomReactions
* You can set custom reactions by passing a map that contains information about the reactions you want to add.
* The map keys should be the reaction ID, and the map value should contain an object with either an `url` or `emoji` field to represent the reaction icon you want to use.
```jsx theme={null}
const commentElement = client.getCommentElement();
const customReactions = {
"reactionId1": {
"emoji": "🤣" // This will default to system emoji
},
"reactionId2": {
"emoji": "🎉" // This will default to system emoji
},
"reactionId3": {
"emoji": "🚀" // This will default to system emoji
}
}
commentElement.setCustomReactions(customReactions);
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
const customReactions = {
"reactionId1": {
"emoji": "🤣" // This will default to system emoji
},
"reactionId2": {
"emoji": "🎉" // This will default to system emoji
},
"reactionId3": {
"emoji": "🚀" // This will default to system emoji
}
}
commentElement.setCustomReactions(customReactions);
```
#### addReaction
* Add a reaction to a specific comment annotation
* Params: [AddReactionRequest](/api-reference/sdk/models/data-models#addreactionrequest)
* Returns: Promise\<[AddReactionEvent](/api-reference/sdk/models/data-models#addreactionevent) | null>
```jsx theme={null}
const addReactionRequest = {
annotationId: '-OCWolieeXVOfPqTa0G-',
commentId: 384399,
reaction: {
reactionId: 'fire',
customReaction: {
"emoji": "🔥"
}
}
};
// Hook
const { addReaction } = useAddReaction();
const addReactionEvent = await addReaction(addReactionRequest);
// API Method
const commentElement = client.getCommentElement();
const addReactionEvent = await commentElement.addReaction(addReactionRequest);
```
```js theme={null}
const addReactionRequest = {
annotationId: '-OCWolieeXVOfPqTa0G-',
commentId: 384399,
reaction: {
reactionId: 'fire',
customReaction: {
"emoji": "🔥"
}
}
};
const commentElement = Velt.getCommentElement();
const addReactionEvent = await commentElement.addReaction(addReactionRequest);
```
#### deleteReaction
* Delete a reaction from a specific comment annotation
* Params: [DeleteReactionRequest](/api-reference/sdk/models/data-models#deletereactionrequest)
* Returns: Promise\<[DeleteReactionEvent](/api-reference/sdk/models/data-models#deletereactionevent) | null>
```jsx theme={null}
const deleteReactionRequest = {
annotationId: '-OCWolieeXVOfPqTa0G-',
commentId: 384399,
reaction: {
reactionId: 'fire'
}
};
// Hook
const { deleteReaction } = useDeleteReaction();
const deleteReactionEvent = await deleteReaction(deleteReactionRequest);
// API Method
const commentElement = client.getCommentElement();
const deleteReactionEvent = await commentElement.deleteReaction(deleteReactionRequest);
```
```js theme={null}
const deleteReactionRequest = {
annotationId: '-OCWolieeXVOfPqTa0G-',
commentId: 384399,
reaction: {
reactionId: 'fire'
}
};
const commentElement = Velt.getCommentElement();
const deleteReactionEvent = await commentElement.deleteReaction(deleteReactionRequest);
```
#### toggleReaction
* Toggle a reaction for a specific comment annotation
* Params: [ToggleReactionRequest](/api-reference/sdk/models/data-models#togglereactionrequest)
* Returns: Promise\<[ToggleReactionEvent](/api-reference/sdk/models/data-models#togglereactionevent) | null>
```jsx theme={null}
const toggleReactionRequest = {
annotationId: '-OCWolieeXVOfPqTa0G-',
commentId: 384399,
reaction: {
reactionId: 'fire'
}
};
// Hook
const { toggleReaction } = useToggleReaction();
const toggleReactionEvent = await toggleReaction(toggleReactionRequest);
// API Method
const commentElement = client.getCommentElement();
const toggleReactionEvent = await commentElement.toggleReaction(toggleReactionRequest);
```
```js theme={null}
const toggleReactionRequest = {
annotationId: '-OCWolieeXVOfPqTa0G-',
commentId: 384399,
reaction: {
reactionId: 'fire'
}
};
const commentElement = Velt.getCommentElement();
const toggleReactionEvent = await commentElement.toggleReaction(toggleReactionRequest);
```
# Status & Priority
#### enableStatus
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableStatus();
commentElement.disableStatus();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableStatus();
commentElement.disableStatus();
```
#### setCustomStatus
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setCustomStatus([
{
id: 'open',
name: 'Open',
color: '#625df5',
lightColor: '#f2f2fe',
type: 'default',
},
{
id: 'resolved',
name: 'Resolved',
color: '#198f65',
lightColor: '#edf6f3',
type: 'terminal',
},
])
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setCustomStatus([
{
id: 'open',
name: 'Open',
color: '#625df5',
lightColor: '#f2f2fe',
type: 'default',
},
{
id: 'resolved',
name: 'Resolved',
color: '#198f65',
lightColor: '#edf6f3',
type: 'terminal',
},
])
```
#### enableResolveButton
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableResolveButton();
commentElement.disableResolveButton();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableResolveButton();
commentElement.disableResolveButton();
```
#### updateStatus
* Updates the status of a comment annotation.
* Params: [UpdateStatusRequest](/api-reference/sdk/models/data-models#updatestatusrequest)
* Returns: [UpdateStatusEvent](/api-reference/sdk/models/data-models#updatestatusevent)
```jsx theme={null}
const updateStatusRequest = {
annotationId: 'ANNOTATION_ID',
status: {
"id": "open",
"name": "Open",
"color": "white",
"lightColor":"green",
"type": "default"
}
};
// Hook
const { updateStatus } = useUpdateStatus();
const updateStatusEvent = await updateStatus(updateStatusRequest);
// API Method
const commentElement = client.getCommentElement();
const updateStatusEvent = await commentElement.updateStatus(updateStatusRequest);
```
```js theme={null}
const updateStatusRequest = {
annotationId: 'ANNOTATION_ID',
status: {
"id": "open",
"name": "Open",
"color": "white",
"lightColor":"green",
"type": "default"
}
};
const commentElement = Velt.getCommentElement();
const updateStatusEvent = await commentElement.updateStatus(updateStatusRequest);
```
#### resolveCommentAnnotation
* Resolves a comment annotation
* Params: [ResolveCommentAnnotationRequest](/api-reference/sdk/models/data-models#resolvecommentannotationrequest)
* Returns: [ResolveCommentAnnotationEvent](/api-reference/sdk/models/data-models#resolvecommentannotationevent)
```jsx theme={null}
const resolveCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { resolveCommentAnnotation } = useResolveCommentAnnotation();
const resolveCommentAnnotationEvent = await resolveCommentAnnotation(resolveCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const resolveCommentAnnotationEvent = await commentElement.resolveCommentAnnotation(resolveCommentAnnotationRequest);
```
```js theme={null}
const resolveCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const resolveCommentAnnotationEvent = await commentElement.resolveCommentAnnotation(resolveCommentAnnotationRequest);
```
#### enablePriority
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enablePriority();
commentElement.disablePriority();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enablePriority();
commentElement.disablePriority();
```
#### setCustomPriority
Pass custom priorities in the `customPriority` prop.
`Default priorities: P0, P1, P2`
With custom priorities, you can replace the default priorities with your own values. These priorities are also used in the comment sidebar to filter comments by priority.
This will work if you have enabled the priority feature.
The `color` property is used to set the priority pill background color.
The `lightColor` property sets the background color of the filter.
```js theme={null}
Pass custom priorities in the `custom-priority`.
`Default priorities: P0, P1, P2`
With custom priorities, you can replace the default priorities with your own values. These priorities are also used in the comment sidebar to filter comments by priority.
This will work if you have enabled the priority feature.
The `color` property is used to set the priority pill background color.
The `lightColor` property sets the background color of the filter.
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setCustomPriority([
{
"id": "low",
"name": "Low",
"color": "red",
"lightColor": "pink",
},
])
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setCustomPriority([
{
"id": "low",
"name": "Low",
"color": "red",
"lightColor": "pink",
},
])
```
Make sure to have at least 2 categories set.
#### updatePriority
* Updates the priority of a comment annotation
* Params: [UpdatePriorityRequest](/api-reference/sdk/models/data-models#updatepriorityrequest)
* Returns: [UpdatePriorityEvent](/api-reference/sdk/models/data-models#updatepriorityevent)
```jsx theme={null}
const updatePriorityRequest = {
annotationId: 'ANNOTATION_ID',
priority: {
"id": "low",
"name": "Low",
"color": "red",
"lightColor": "pink",
}
};
// Hook
const { updatePriority } = useUpdatePriority();
const updatePriorityEvent = await updatePriority(updatePriorityRequest);
// API Method
const commentElement = client.getCommentElement();
const updatePriorityEvent = await commentElement.updatePriority(updatePriorityRequest);
```
```js theme={null}
const updatePriorityRequest = {
annotationId: 'ANNOTATION_ID',
priority: {
"id": "low",
"name": "Low",
"color": "red",
"lightColor": "pink",
}
};
const commentElement = Velt.getCommentElement();
const updatePriorityEvent = await commentElement.updatePriority(updatePriorityRequest);
```
# Recording
#### deleteRecording
* Delete a recording from a specific comment annotation
* Params: [DeleteRecordingRequest](/api-reference/sdk/models/data-models#deleterecordingrequest)
* Returns: Promise\<[DeleteRecordingEvent](/api-reference/sdk/models/data-models#deleterecordingevent) | null>
```jsx theme={null}
const deleteRecordingRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID,
recordingId: 'RECORDING_ID'
};
// Hook
const { deleteRecording } = useDeleteRecording();
const deleteRecordingEvent = await deleteRecording(deleteRecordingRequest);
// API Method
const commentElement = client.getCommentElement();
const deleteRecordingEvent = await commentElement.deleteRecording(deleteRecordingRequest);
```
```js theme={null}
const deleteRecordingRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID,
recordingId: 'RECORDING_ID'
};
const commentElement = Velt.getCommentElement();
const deleteRecordingEvent = await commentElement.deleteRecording(deleteRecordingRequest);
```
#### getRecording
* Get recordings from a specific comment annotation
* Params: [GetRecordingRequest](/api-reference/sdk/models/data-models#getrecordingrequest)
* Returns: Promise\<[RecordedData\[\]](/api-reference/sdk/models/data-models#recordeddata)>
```jsx theme={null}
const getRecordingRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID
};
// Hook
const { getRecording } = useGetRecording();
const recordings = await getRecording(getRecordingRequest);
// API Method
const commentElement = client.getCommentElement();
const recordings = await commentElement.getRecording(getRecordingRequest);
```
```js theme={null}
const getRecordingRequest = {
annotationId: 'ANNOTATION_ID',
commentId: COMMENT_ID
};
const commentElement = Velt.getCommentElement();
const recordings = await commentElement.getRecording(getRecordingRequest);
```
#### setAllowedRecordings
```jsx theme={null}
**Using Props:**
```jsx theme={null}
#### enableRecordingCountdown
```jsx theme={null}
```jsx theme={null}
#### enableRecordingTranscription
Controls whether to enable AI transcription for recordings.
Default: `enabled`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
# Deep Link
#### getLink
* Get a link to a specific comment annotation
* Params: [GetLinkRequest](/api-reference/sdk/models/data-models#getlinkrequest)
* Returns: [GetLinkResponse](/api-reference/sdk/models/data-models#getlinkresponse)
```jsx theme={null}
const getLinkRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { getLink } = useGetLink();
const getLinkResponse = await getLink(getLinkRequest);
// API Method
const commentElement = client.getCommentElement();
const getLinkResponse = await commentElement.getLink(getLinkRequest);
```
```js theme={null}
const getLinkRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const getLinkResponse = await commentElement.getLink(getLinkRequest);
```
#### copyLink
* Copy a link to a specific comment annotation to clipboard
* Params: [CopyLinkRequest](/api-reference/sdk/models/data-models#copylinkrequest)
* Returns: [CopyLinkEvent](/api-reference/sdk/models/data-models#copylinkevent)
```jsx theme={null}
const copyLinkRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { copyLink } = useCopyLink();
const copyLinkEvent = await copyLink(copyLinkRequest);
// API Method
const commentElement = client.getCommentElement();
const copyLinkEvent = await commentElement.copyLink(copyLinkRequest);
```
```js theme={null}
const copyLinkRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const copyLinkEvent = await commentElement.copyLink(copyLinkRequest);
```
# Navigation
#### scrollToCommentByAnnotationId
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.scrollToCommentByAnnotationId('annotationId')
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.scrollToCommentByAnnotationId('annotationId')
```
#### selectCommentByAnnotationId
* Use this to programmatically select a comment annotation by its ID.
* When called without arguments or with an invalid ID, it will close the currently selected annotation.
* Example: If the user opens a comment URL from an email notification, you can use this to open the comment dialog after your page has finished rendering.
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
// Open a specific annotation
commentElement.selectCommentByAnnotationId('COMMENT_ANNOTATION_ID');
// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');
// Using API methods
const commentElement = client.getCommentElement();
// Open a specific annotation
commentElement.selectCommentByAnnotationId('COMMENT_ANNOTATION_ID');
// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
// Open a specific annotation
commentElement.selectCommentByAnnotationId('COMMENT_ANNOTATION_ID');
// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');
```
#### onCommentSelectionChange
The `useCommentSelectionChangeHandler` hook can be used to subscribe to Comment selection changes.
```jsx theme={null}
import React, { useEffect } from 'react';
import { useCommentSelectionChangeHandler } from '@veltdev/react';
function YourComponent() {
const commentSelectionChange = useCommentSelectionChangeHandler();
useEffect(() => {
console.log('commentSelectionChange', commentSelectionChange);
}, [commentSelectionChange]);
return (
<>
Selected Comment: {commentSelectionChange.annotation.id}
);
}
```
The `onCommentSelectionChange()` method can be used to listen Comment selection changes.
```jsx theme={null}
const onCommentSelectionChange = (data) => {
console.log('onCommentSelectionChange', data);
}
onCommentSelectionChange(data)} />
```
Callback response schema:
```jsx theme={null}
export class CommentSelectionChangeData {
selected!: boolean;
annotation!: CommentAnnotation;
}
```
**API Methods:**
```jsx theme={null}
const commentElement = client.getCommentElement();
let subscription = commentElement.onCommentSelectionChange().subscribe((data) => {
console.log('onCommentSelectionChange: ', data);
});
```
**To unsubscribe from the subscription:**
```jsx theme={null}
subscription?.unsubscribe()
```
The `onCommentSelectionChange()` method can be used to listen Comment selection changes.
```jsx theme={null}
#### enablescrollToComment
To disable the feature, set `scrollToComment` to `false`.
```html theme={null}
```
To disable the feature, set `scroll-to-comment` to `false`.
```html theme={null}
API methods:
```jsx theme={null}
const commentElement = client.getCommentElement();
// To enable scroll to component
commentElement.enablescrollToComment();
// To disable scroll to component
commentElement.disablescrollToComment();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
// To enable scroll to component
commentElement.enablescrollToComment();
// To disable scroll to component
commentElement.disablescrollToComment();
```
# DOM Controls
#### allowedElementIds
#### allowedElementClassNames
#### allowedElementQuerySelectors
**Using Props:**
```js theme={null}
**Using Props:**
```html theme={null}
```
**Using API Method:**
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.allowedElementIds(['some-element']);
commentElement.allowedElementClassNames(["class-name-1", "class-name-2"]);
commentElement.allowedElementQuerySelectors(["#id1.class-name-1"]);
```
#### data-velt-comment-disabled
```
#### sourceId
* When you have multiple elements with the same DOM ID, you can use the `sourceId` attribute to control which element displays the comment dialog when adding a new comment.
* By default, comments appear on all matching elements.
* This is useful in cases where you have multiple instances of the same data component on a page and want the comment to appear on each instance, such as Popover comments on a table.
* You can randomly generate the `sourceId`. It just needs to be unique for each element in the current session.
```jsx theme={null}
```html theme={null}
# AI Categorization
#### enableAutoCategorize
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableAutoCategorize();
commentElement.disableAutoCategorize();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableAutoCategorize();
commentElement.disableAutoCategorize();
```
#### setCustomCategory
Pass custom categories in the `customCategory` prop.
`Default categories: Question, Feedback, Bug, Other.`
With custom categories, you can replace the default categories with your own values.
These categories are used in the `Comments Sidebar` to filter comments by category. The AI `autoCategorize` feature uses the list of categories to determine the closest category to choose from.
The input format to the `customCategory` prop should be an array of objects with an `id`, `name`, and `color`.
The `color` property is used to set the category pill background color.
```js theme={null}
Pass custom categories in the `custom-category`.
`Default categories: Question, Feedback, Bug, Other.`
With custom categories, you can replace the default categories with your own values.
These categories are used in the `Comments Sidebar` to filter comments by category. The AI `auto-categorize` uses the list of categories to determine the closest category to choose from.
The input format to the `custom-category` should be an array of objects with an `id`, `name`, and `color`.
The `color` property is used to set the category pill background color.
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setCustomCategory([
{
"id": "bug",
"name": "Bug",
"color": "red"
}
])
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setCustomCategory([
{
"id": "bug",
"name": "Bug",
"color": "red"
}
])
```
Make sure to have at least 2 categories set.
# UI/UX
#### composerMode
By default, the `Composer` in the `Comments Dialog` only shows the text input box and does not show the actions bar until the `Composer` is clicked on or the user starts typing.
You can modify this behavior by setting the `Composer Mode` prop to `"expanded"`. This will make the actions bar always visible.
To keep the default behavior you can set the property to `"default"`.
`Default: "default"`
```jsx theme={null}
```jsx theme={null}
#### commentToNearestAllowedElement
Attach comment pins to the closest allowed element when clicking on a non-allowed element.
Default: `false`
```jsx theme={null}
```html theme={null}
#### deleteThreadWithFirstComment
Whether deleting the first comment in a thread will delete the entire thread.
Default: `true`
```jsx theme={null}
```html theme={null}
#### draftMode
Whether to store comments in draft if they are not submitted.
When enabled, partial comments are preserved when the dialog closes, including composer text, attachments, and recordings.
Default: `true`
**Behavior:**
* Partial comments are saved with `isDraft: true` when the dialog is closed
* The dialog shows a shake animation on the first click outside if there's unsaved content
* The `data-velt-annotation-draft` attribute is set on dialogs with unsaved content for custom styling
```jsx theme={null}
```html theme={null}
#### enableCollapsedComments
You can control whether comments inside the annotation should be collapsed.
`Default: false`
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
#### enableFullExpanded
* You can control whether comments should be shown in fully expanded state by default.
* Available on all comment-related components and can be controlled via props or API methods.
`Default: false`
Using Props:
```jsx theme={null}
// Apply this change globally to all types of comments
Using Props:
```html theme={null}
#### enableShortUserName
You can control whether long user names should be shortened. For long names, this will first create an initial of the second name and if the name is still long, it will truncate it with ellipses.
Default: `true`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### enableSignInButton
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableSignInButton();
commentElement.disableSignInButton();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableSignInButton();
commentElement.disableSignInButton();
```
#### enableSidebarButtonOnCommentDialog
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
#### enableDeleteReplyConfirmation
You can enable a confirmation dialog before deleting a reply in comment threads. This feature helps prevent accidental deletions and improves user experience.
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
#### enableMobileMode
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableMobileMode();
commentElement.disableMobileMode();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableMobileMode();
commentElement.disableMobileMode();
```
#### enableCommentPinHighlighter
```jsx theme={null}
```jsx theme={null}
API Methods:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableCommentPinHighlighter(); // to enable comment pin highlight
commentElement.disableCommentPinHighlighter(); // to disable comment pin highlight
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableCommentPinHighlighter(); // to enable comment pin highlight
commentElement.disableCommentPinHighlighter(); // to disable comment pin highlight
```
#### enableDialogOnHover
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableDialogOnHover();
commentElement.disableDialogOnHover();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableDialogOnHover();
commentElement.disableDialogOnHover();
```
#### enableFloatingCommentDialog
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableFloatingCommentDialog();
commentElement.disableFloatingCommentDialog();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableFloatingCommentDialog();
commentElement.disableFloatingCommentDialog();
```
#### excludeLocationIds
Use this to filter out Comments at a specific Location for certain Users.
```jsx theme={null}
const locationIds = ['location1', 'location2']; // list of location ids
client.excludeLocationIds(locationIds);
```
To reset it, you can pass an empty array:
```jsx theme={null}
client.excludeLocationIds([]);
```
```jsx theme={null}
const locationIds = ['location1', 'location2']; // list of location ids
Velt.excludeLocationIds(locationIds);
```
To reset it, you can pass an empty array:
```jsx theme={null}
Velt.excludeLocationIds([]);
```
#### enableReplyAvatars
This shows the avatars of unique users who have replied to a comment.
* `replyAvatars`: Whether the reply avatar component is enabled.
* `maxReplyAvatars`: The maximum number of reply avatars to show. It will show the count of remaining unque users as the next avatar.
`Default: false`
**Using props:**
```jsx theme={null}
**Using props:**
```html theme={null}
#### filterCommentsOnDom
* Filter out comments in the DOM when they are filtered in the sidebar.
* When the sidebar is closed (default mode) or unmounted (embed mode), the DOM filter will be removed.
`Default: false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### focusPageModeComposer
Focus the page mode composer input field programmatically.
Use this to direct user attention to the page mode composer.
API Method: \[`focusPageModeComposer()`]\(/api-reference/sdk/api/api-methods#focuspagemode composer)
```jsx theme={null}
// Using Hook
const commentElement = useCommentUtils();
commentElement.focusPageModeComposer();
// Using API Method
const commentElement = client.getCommentElement();
commentElement.focusPageModeComposer();
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.focusPageModeComposer();
```
#### onSidebarButtonOnCommentDialogClick
Use this to act on clicks on the Sidebar Button at the bottom of the Comment Dialog.
**Using Props:**
```jsx theme={null}
yourMethod(event)} />
```
**Using Hooks:**
```jsx theme={null}
const commentDialogSidebarClickEvent = useCommentDialogSidebarClickHandler();
useEffect(() => {
console.log('CommentDialog Sidebar button clicked');
}, [commentDialogSidebarClickEvent]);
```
**Using API methods:**
```jsx theme={null}
const commentElement = client.getCommentElement();
let subscription = commentElement.onSidebarButtonOnCommentDialogClick().subscribe((event) => yourMethod(event));
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
**Using Props:**
```jsx theme={null}
#### onSignIn
When the user clicks on the sign in button, we will emit an `onSignIn` event that you can handle with your own sign in method.
No data is passed with the event.
```js theme={null}
yourSignInMethod()} />
```
```js theme={null}
const veltCommentsTag = document.querySelector('velt-comments');
veltCommentsTag?.addEventListener('onSignIn', (event) => {
console.log('*** onCommentSignIn ***');
console.log(event.detail);
});
```
#### showCommentsOnDom
Whether comments are shown on the DOM.
`Default: true`
By default, all the comments will be visible on DOM whenever we are able to detect to elements for that. But users can hide it from DOM if required.
There are 2 ways to show/hide comments on DOM:
Configuring attributes on the React Component:
```js theme={null}
{/* `true` to show comments, `false` to hide comments */}
```js theme={null}
Using API methods:
```js theme={null}
const commentElement = client.getCommentElement();
// to show comments on DOM
commentElement.showCommentsOnDom();
// to hide comments on DOM
commentElement.hideCommentsOnDom();
```
```js theme={null}
const commentElement = Velt.getCommentElement();
// to show comments on DOM
commentElement.showCommentsOnDom();
// to hide comments on DOM
commentElement.hideCommentsOnDom();
```
#### showResolvedCommentsOnDom
Whether to show resolved comments on the DOM.
`Default: false`
```jsx theme={null}
```html theme={null}
API Methods:
```jsx theme={null}
const commentElement = client.getCommentElement();
// To show resolved comments on dom
commentElement.showResolvedCommentsOnDom();
// To hide resolved comments on dom
commentElement.hideResolvedCommentsOnDom();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
// To show resolved comments on dom
commentElement.showResolvedCommentsOnDom();
// To hide resolved comments on dom
commentElement.hideResolvedCommentsOnDom();
```
#### updateCommentDialogPosition
* Sometimes when you manually set the position of the Comment Pin, the Comment Dialog might not position itself near the pin in certain scenarios like scrolling, zooming the page when the comment dialog is open.
* Use this to manually trigger an update. The dialog will reposition itself near the pin.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.updateCommentDialogPosition();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.updateCommentDialogPosition();
```
You can add custom lists at two levels: a. on the CommentAnnotation and b. on the Comment.
#### Link Callback
Enable a callback when users click on links rendered in comment content. When enabled, links won’t automatically open; instead an event is emitted.
How to use:
* By default `linkCallback` is `false`.
* When `false`, clicking a link opens it directly and no callback is triggered.
* When `true`, clicking a link does not open it; instead a `linkClicked` event is emitted so you can handle navigation.
```jsx theme={null}
// Using Props
```html theme={null}
Types:
```ts theme={null}
export interface LinkClickedEvent {
text: string;
link: string;
commentAnnotation: CommentAnnotation;
commentId: Number;
metadata?: VeltEventMetadata;
}
```
#### commentBubbleClicked
Listen to when a comment bubble is clicked.
This event is triggered whenever a user clicks on a comment bubble. You can use this to implement custom actions like navigation or analytics tracking.
```jsx theme={null}
// Using Hook
const commentBubbleClickedEvent = useCommentEventCallback('commentBubbleClicked');
useEffect(() => {
if (commentBubbleClickedEvent) {
console.log('Comment bubble clicked:', commentBubbleClickedEvent);
}
}, [commentBubbleClickedEvent]);
// Using API
const commentElement = client.getCommentElement();
commentElement.on('commentBubbleClicked').subscribe((eventData) => {
console.log('Comment bubble clicked:', eventData);
});
```
```html theme={null}
```
**Event Type**: [`CommentBubbleClickedEvent`](/api-reference/sdk/models/data-models#commentbubbleclickedevent)
```ts theme={null}
export interface CommentBubbleClickedEvent {
annotationId: string;
commentAnnotation: CommentAnnotation;
metadata?: VeltEventMetadata;
}
```
# Extra Information
#### enableCommentIndex
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableCommentIndex();
commentElement.disableCommentIndex();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableCommentIndex();
commentElement.disableCommentIndex();
```
#### enableDeviceInfo
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableDeviceInfo();
commentElement.disableDeviceInfo();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableDeviceInfo();
commentElement.disableDeviceInfo();
```
#### enableDeviceIndicatorOnCommentPins
```js theme={null}
```jsx theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableDeviceIndicatorOnCommentPins();
commentElement.disableDeviceIndicatorOnCommentPins();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableDeviceIndicatorOnCommentPins();
commentElement.disableDeviceIndicatorOnCommentPins();
```
#### enableGhostComments
```js theme={null}
```js theme={null}
#### enableGhostCommentsIndicator
```js theme={null}
```html theme={null}
# Special File Type Support
#### Iframe Container Support
```
#### data-velt-pdf-viewer
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
# Keyboard Controls
#### enableHotkey
Whether Hotkeys are enabled or not. For now, the only hotkey supported is pressing `c` to enable `comment mode`.
`Default: false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### enableEnterKeyToSubmit
* By default, pressing `enter` will add a new line and pressing `shift` + `enter` will submit a comment.
* You can change this default behavior so that pressing `enter` will submit a comment by setting the `enterKeyToSubmit` property to `true`.
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
#### enableDeleteOnBackspace
* Use this to enable or disable deleting comments when backpsace key is pressed.
Default: `enabled`
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
# Moderation
#### enableModeratorMode
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableModeratorMode();
commentElement.disableModeratorMode();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableModeratorMode();
commentElement.disableModeratorMode();
```
#### enableResolveStatusAccessAdminOnly
* Restrict the resolve action to admin users and the comment author only.
**Using props:**
```jsx theme={null}
**Using props:**
```html theme={null}
#### approveCommentAnnotation
* Approves a comment annotation in moderator mode
* Params: [ApproveCommentAnnotationRequest](/api-reference/sdk/models/data-models#approvecommentannotationrequest)
* Returns: [ApproveCommentAnnotationEvent](/api-reference/sdk/models/data-models#approvecommentannotationevent)
```jsx theme={null}
const approveCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { approveCommentAnnotation } = useApproveCommentAnnotation();
const approveCommentAnnotationEvent = await approveCommentAnnotation(approveCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const approveCommentAnnotationEvent = await commentElement.approveCommentAnnotation(approveCommentAnnotationRequest);
```
```js theme={null}
const approveCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const approveCommentAnnotationEvent = await commentElement.approveCommentAnnotation(approveCommentAnnotationRequest);
```
#### acceptCommentAnnotation
* Accepts a comment annotation in suggestion mode
* Params: [AcceptCommentAnnotationRequest](/api-reference/sdk/models/data-models#acceptcommentannotationrequest)
* Returns: [AcceptCommentAnnotationEvent](/api-reference/sdk/models/data-models#acceptcommentannotationevent)
```jsx theme={null}
const acceptCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { acceptCommentAnnotation } = useAcceptCommentAnnotation();
const acceptCommentAnnotationEventData = await acceptCommentAnnotation(acceptCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const acceptCommentAnnotationEventData = await commentElement.acceptCommentAnnotation(acceptCommentAnnotationRequest);
```
```js theme={null}
const acceptCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const acceptCommentAnnotationEventData = await commentElement.acceptCommentAnnotation(acceptCommentAnnotationRequest);
```
#### rejectCommentAnnotation
* Rejects a comment annotation in suggestion mode
* Params: [RejectCommentAnnotationRequest](/api-reference/sdk/models/data-models#rejectcommentannotationrequest)
* Returns: [RejectCommentAnnotationEvent](/api-reference/sdk/models/data-models#rejectcommentannotationevent)
```jsx theme={null}
const rejectCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
// Hook
const { rejectCommentAnnotation } = useRejectCommentAnnotation();
const rejectCommentAnnotationEventData = await rejectCommentAnnotation(rejectCommentAnnotationRequest);
// API Method
const commentElement = client.getCommentElement();
const rejectCommentAnnotationEventData = await commentElement.rejectCommentAnnotation(rejectCommentAnnotationRequest);
```
```js theme={null}
const rejectCommentAnnotationRequest = {
annotationId: 'ANNOTATION_ID'
};
const commentElement = Velt.getCommentElement();
const rejectCommentAnnotationEventData = await commentElement.rejectCommentAnnotation(rejectCommentAnnotationRequest);
```
#### enableSuggestionMode
To accept comments, set the `suggestionMode` attribute to `true`.
```js theme={null}
To accept comments, set the `suggestion-mode` attribute to `true`.
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableSuggestionMode();
commentElement.disableSuggestionMode();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableSuggestionMode();
commentElement.disableSuggestionMode();
```
#### enableReadOnly
Control whether comments are in read-only mode. When enabled, any features requiring user interaction (e.g., Composer, Reactions, Status) will be removed.
Default: `false`
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
# Comment Read Status
#### enableSeenByUsers
Control whether the "Seen By" feature is enabled for comments. When enabled, it shows which users have seen each comment.
Default: `true`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### setUnreadIndicatorMode
Whether `verbose` mode is enabled for unread `Comments`.
`Default: 'minimal'`
Unread `Comments` can be in `minimal` mode or `verbose` mode.
In `minimal` mode, a small red dot indicator appears for unread `Comments`.
In `verbose` mode, a larger badge with the text "UNREAD" will appear for unread `Comments`.
```jsx theme={null}
```jsx theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setUnreadIndicatorMode("verbose"); // use badge with text UNREAD
commentElement.setUnreadIndicatorMode("minimal"); // use small red dot indicator
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setUnreadIndicatorMode("verbose"); // use badge with text UNREAD
commentElement.setUnreadIndicatorMode("minimal"); // use small red dot indicator
```
# Toggle Comment Types
#### enableAreaComment
Area comments allows users to draw a rectangle and attach a comment to it.
Use this to enable or disable area comments.
Default: `true`
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
#### enablePopoverMode
For a complete setup guide for Popover mode, [read here](/async-collaboration/comments/setup/popover).
Whether Popover Mode is enabled.
Default: `false`
```jsx theme={null}
```
**Using API:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enablePopoverMode();
commentElement.disablePopoverMode();
```
```jsx theme={null}
#### enableStreamMode
For a complete setup guide for Stream mode, [read here](/async-collaboration/comments/setup/stream).
Whether Stream Mode is enabled.
Default: `false`
```jsx theme={null}
```
**Using API:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableStreamMode();
commentElement.disableStreamMode();
```
```jsx theme={null}
#### enableTextMode
For a complete setup guide for Text mode, [read here](/async-collaboration/comments/setup/text).
Whether Text Mode is enabled.
Default: `true`
**Using Props:**
```jsx theme={null}
```
**Using API:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableTextComments();
commentElement.disableTextComments();
```
**Using Props:**
```html theme={null}
#### enableInlineCommentMode
```jsx theme={null}
```
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableInlineCommentMode();
commentElement.disableInlineCommentMode();
```
```jsx theme={null}
#### enableMultithread
* By default comments are single threaded.
* You can make it multithreaded by setting `multiThread` prop to `true`.
* If you had previously used a wireframe for the comment dialog, you will need to add the [multithread wireframe](/ui-customization/features/async/comments/multithread-comment-dialog).
* Default: `false`
```jsx theme={null}
```html theme={null}
```
# Comment Tool
#### context
* Add `context` to the `Velt Comment Tool` component to associate custom metadata with comments created using that tool.
* Predefine context directly within the component itself.
* Currently, this feature is specific to popover comments. This allows you to, for example, assign unique context to each cell in a table if you place a `Velt Comment Tool` in each cell.
* The `context` prop accepts an object with key-value pairs.
```jsx theme={null}
// For popover comments
```html theme={null}
#### contextInPageModeComposer
Pass context data to the page mode composer when opening the comment sidebar via the comment tool. Context automatically clears when the sidebar closes.
API Methods: [`enableContextInPageModeComposer()`](/api-reference/sdk/api/api-methods#enablecontextinpagemodecomposer), [`disableContextInPageModeComposer()`](/api-reference/sdk/api/api-methods#disablecontextinpagemodecomposer)
* Params: `boolean`
* Returns: `void`
For programmatically setting context data, see [`setContextInPageModeComposer()`](#setcontextinpagemodecomposer).
```jsx theme={null}
// Using props
import { VeltCommentTool } from '@veltdev/react';
```html theme={null}
```
#### enableCommentMode
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableCommentMode();
commentElement.disableCommentMode();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableCommentMode();
commentElement.disableCommentMode();
```
#### onCommentModeChange
The `useCommentModeState()` hook can be used to get the Comment mode without having to subscribe to changes. When the Comment mode changes, the hook return value will update.
The subscription is automatically unsubscribed when the component dismounts.
```jsx theme={null}
import { useCommentModeState } from '@veltdev/react';
export default function YourDocument() {
let commentModeState = useCommentModeState()
return (
Comment Mode is turned on: {commentModeState}
)
}
```
To subscribe to changes in the comment mode, use the `onCommentModeChange()` method , as a property on `VeltCommentTool`:
```jsx theme={null}
onCommentModeChange(mode)} />
```
API method:
```jsx theme={null}
let subscription = commentElement.onCommentModeChange().subscribe((mode) => {
//mode contains the state after change
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
API method:
```jsx theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.onCommentModeChange().subscribe((mode) => {
//mode contains the state after change
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
#### enableCommentTool
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### disabled
Disables the comment tool and prevents users from adding new comments.
This is helpful when you want to temporarily or conditionally restrict comment creation while still allowing users to view existing comments.
Default: `false`
This prop disables the specific comment tool instance it is applied to; the `disableCommentTool()` API disables all comment tools globally.
```jsx theme={null}
```html theme={null}
#### enableChangeDetectionInCommentMode
* By default, DOM Change Detection is disabled in Comment Mode for better performance.
* You can enable it to automatically reposition comment pins when the DOM changes while in Comment Mode.
`Default: false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### enablePersistentCommentMode
* When Persistent comment mode is enabled, you can continue leave additional comments after finishing a comment.
* When it is disabled, you will need to reclick the Comment Tool every time when you want to make a comment.
Default: `false`
```jsx theme={null}
```
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enablePersistentCommentMode();
commentElement.disablePersistentCommentMode();
```
```jsx theme={null}
#### forceCloseAllOnEsc
* When enabled, pressing the ESC key will force close persistent comment mode even if a comment thread is currently active.
* When disabled (default), pressing ESC will only close the active comment thread but keep persistent comment mode enabled.
* This provides more control over the ESC key behavior in persistent comment mode.
Default: `false`
```jsx theme={null}
```
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableForceCloseAllOnEsc();
commentElement.disableForceCloseAllOnEsc();
```
```jsx theme={null}
#### setPinCursorImage
You can set custom mouse cursor when the comment mode is on.
The custom cursor image must be **32 x 32 pixels**.
```jsx theme={null}
```jsx theme={null}
API Methods:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setPinCursorImage(BASE64_IMAGE_STRING);
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setPinCursorImage(BASE64_IMAGE_STRING);
```
# Minimap
#### enableMinimap
```jsx theme={null}
```jsx theme={null}
**Option b. Enable using Minimap Component:**
This offers greater flexibility to customize and position the minimap.
```jsx theme={null}
{/* scrollable content */}
```
```jsx theme={null}
```
# Inline Comments Section
#### sortBy and sortOrder
* Change the default sorting order of Comments in the Inline Comments Section.
* Params:
* `sortBy`: The field to sort by. Currently supports `createdAt` and `lastUpdated`. Default: `lastUpdated` for multithread and `createdAt` for single thread.
* `sortOrder`: The order to sort by. It can be `asc` or `desc`. Default: `desc` for multithread and `asc` for single thread.
```jsx theme={null}
```html theme={null}
#### multiThread
* By default [inline comment section](/async-collaboration/comments/setup/inline-comments) is multithreaded.
* You can make it single threaded by setting `multiThread` prop to `false`.
* Default: `true`
```jsx theme={null}
```html theme={null}
```
#### commentPlaceholder, replyPlaceholder, composerPlaceholder
* Customize placeholder text for different input fields in the inline comments section.
* Props:
* `commentPlaceholder`: Placeholder text for the main comment input field.
* `replyPlaceholder`: Placeholder text for the reply input field.
* `composerPlaceholder`: Placeholder text for the composer input field.
```jsx theme={null}
```html theme={null}
#### composerPosition
* Change the position of the comment composer in the inline comments section to `top` or `bottom`.
* Default: `bottom`
```jsx theme={null}
```html theme={null}
```
#### context
* Pass a custom context object to the Inline Comments Section component.
* The provided context will be added to any comments created in the inline comments section, allowing you to associate custom metadata with those comments.
* Additionally, the component will filter and display only the comments that match the provided context object.
* This dual behavior makes it easy to scope comments to specific areas of your application (e.g., specific cells in a table, dashboard widgets, or data segments).
```jsx theme={null}
```html theme={null}
```
#### contextOptions
* Configure the matching behavior for the context object when filtering comments.
* By default, comments must fully match all key-value pairs in the provided context.
* Set `partialMatch: true` to enable flexible matching where comments match if they contain all the specified context fields (extra fields in the comment's context are ignored).
* See [`Context` Matching](#context-matching) for detailed explanation and examples.
```jsx theme={null}
{/* Full match (default) - comment must have exact context */}
```html theme={null}
```
#### readOnly
Control read-only mode at the component level. When enabled, users can view comments but cannot reply, edit, or add new comments in the Inline Comments Section.
The local component prop takes precedence over global settings when explicitly set.
Default: `false`
```jsx theme={null}
```html theme={null}
```
# Popover Comments
#### enableDialogOnTargetElementClick
```js theme={null}
```js theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableDialogOnTargetElementClick();
commentElement.disableDialogOnTargetElementClick();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableDialogOnTargetElementClick();
commentElement.disableDialogOnTargetElementClick();
```
#### enablePopoverTriangleComponent
Whether the popover triangle appears when Popover Mode is enabled.
`Default: true`
```jsx theme={null}
```
```jsx theme={null}
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enablePopoverTriangleComponent();
commentElement.disablePopoverTriangleComponent();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enablePopoverTriangleComponent();
commentElement.disablePopoverTriangleComponent();
```
# Comment Bubble
#### annotationId
* The id of the comment annotation to show the comment bubble on.
* The bubble will be rendered only if there is a comment annotation that matches the provided `annotationId` in the current document.
```jsx theme={null}
```html theme={null}
#### targetElementId
* The DOM ID of the element where comment bubble is added.
* This binds the comment bubble to the element with the provided ID.
* The bubble will be rendered only if there is a comment annotation that was added to the element with the provided ID.
```jsx theme={null}
```html theme={null}
#### context
* The `context` object to filter which comment annotations to show the comment bubble for.
* The bubble will be rendered only if there is a comment annotation that matches the provided `context` in the current document.
* Works only with `popover` mode comments.
* Perfect for complex tables with filtering and segmentation needs.
* Set flexible comment anchoring and filtering logic at the cell level using key-value pairs.
* **Supports aggregate views:** Eg: comments added in day view can appear in week/month views automatically.
* Context commonly has combined use with [context options](#contextoptions) and the [group matched comments](#groupmatchedcomments) feature.
```jsx theme={null}
```html theme={null}
#### contextOptions
* Matching behavior for the context object (default: full match, or set `partialMatch: true` for flexible matching).
* **How Partial Match Works:**
* A comment will match if ALL provided filter criteria exist in the comment's context
* Extra fields in the comment's context don't prevent matching
* Missing fields in the comment's context prevent matching
* Example: Comment has `{ day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }`
* Filter `{ day: "01", product: "cheese" }` → ✅ matches (both fields exist in comment)
* Filter `{ day: "01", category: "dairy" }` → ❌ no match (category doesn't exist in comment)
* **Partial Match Examples:**
* Comment has `{ day: "01", week: "01", month: "jan", product: "cheese" }`
* Filter with `{ day: "01", week: "01", month: "jan", product: "cheese" }` → matches (full)
* Filter with `{ week: "01", month: "jan", product: "cheese" }` → matches (partial)
* Filter with `{ day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }` → no match
#### groupMatchedComments
Whether to group multiple comment annotations in Comment Bubble component when multiple annotations match the provided `context` or `targetElementId`.
Default: `false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### commentCountType
Whether to show unread or total comment replies count on Comment Bubble Component.
Type: [`CommentCountType`](/api-reference/sdk/models/data-models#commentcounttype)
* `total`: Shows the total number of replies. (default)
* `unread`: Shows the number of unread replies.
```jsx theme={null}
```jsx theme={null}
```
#### openDialog
Control whether the comment dialog opens when clicking on the comment bubble.
When disabled, clicking the bubble will not open the comment dialog. This is useful when you want to handle bubble clicks with custom logic using the [`commentBubbleClicked`](#commentbubbleclicked) event.
Default: `true`
```jsx theme={null}
```html theme={null}
#### readOnly
The `readOnly` flag prevents users from replying or editing existing comments in the target bubble while still displaying them.
This is useful when you want to display comments in a read-only mode where users can view but not modify or respond to comments.
Default: `false`
```jsx theme={null}
```html theme={null}
# Video Timeline Comments
#### setTotalMediaLength
Set the total length of media (in frames or seconds) for the timeline.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### offset
* Allows comment bubbles to be positioned relative to both parent and child video clips by specifying an offset value.
* Default: `0`
```jsx theme={null}
```html theme={null}
# Comment Pin
#### enableBubbleOnPin
Show a Comment Bubble when user hovers or clicks on the Comment Pin vs showing the Comment Dialog.
The comment dialog will open only on clicking the comment bubble.
`Default: 'false'`
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
```
**Using API Method:**
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableBubbleOnPin();
commentElement.disableBubbleOnPin();
```
#### enableBubbleOnPinHover
Show a Comment Bubble when user hovers on the Comment Pin vs clicks on it.
`Default: 'true'`
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
# Legacy Methods
#### onCommentAdd
Using Props:
```js theme={null}
yourMethod(event)} />
const yourMethod = (event) => {
event?.addContext({ customKey: 'customValue' });
}
```
Using Hooks:
```jsx theme={null}
import { useCommentAddHandler} from '@veltdev/react';
export default function YourDocument() {
const commentAddEvent = useCommentAddHandler();
useEffect(() => {
console.log('commentAddEvent', commentAddEvent);
}, [commentAddEvent]);
return (
)
}
```
Using API:
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.onCommentAdd().subscribe((event) => {
console.log('commentAddEvent', event);
});
```
Using Event listener:
```js theme={null}
const veltCommentsTag = document.querySelector('velt-comments');
veltCommentsTag?.addEventListener('onCommentAdd', (event) => {
console.log('*** onCommentAdd ***');
console.log(event.detail);
event.detail?.addContext({ customKey: 'customValue' });
});
```
Using API method:
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.onCommentAdd().subscribe((event) => {
event?.addContext({ customKey: 'customValue' });
});
```
**onCommentAdd Event Data Schema**
| Field Name | Type | Description |
| ------------------ | ----------------- | ------------------------------------------------------------------- |
| addContext | Function | Use this to set custom data on the comment |
| annotation | CommentAnnotation | The annotation that is associated with the comment that was updated |
| documentId | string | The document ID where the comment was added |
| location | Object | The location where the comment was added |
| targetAnnotationId | string | The id of the target annotation |
#### onCommentUpdate
Using Props:
```js theme={null}
yourMethod(event)} />
const yourMethod = (event) => {
console.log('commentUpdateEvent', event);
}
```
Using Hooks:
```jsx theme={null}
import { useCommentUpdateHandler} from '@veltdev/react';
export default function YourDocument() {
const commentUpdateEvent = useCommentUpdateHandler();
useEffect(() => {
console.log('commentUpdateEvent', commentUpdateEvent);
}, [commentUpdateEvent]);
return (
)
}
```
Using API:
```js theme={null}
const commentElement = client.getCommentElement();
commentElement.onCommentUpdate().subscribe((event) => {
console.log('commentUpdateEvent', event);
});
```
Using Event Listener:
```js theme={null}
const veltCommentsTag = document.querySelector('velt-comments');
veltCommentsTag?.addEventListener('onCommentUpdate', (event) => {
console.log('*** onCommentUpdate ***');
console.log(event.detail);
});
```
Using API method:
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.onCommentUpdate().subscribe((event) => {
console.log('commentUpdateEvent', event);
});
```
**onCommentUpdate Event Data Schema**
| Field Name | Type | Description |
| ------------------ | ----------------- | -------------------------------------------------------------------------- |
| annotation | CommentAnnotation | The annotation that is associated with the comment that was updated |
| type | string | The type of comment that was updated |
| targetAnnotationId | string | The ID of the target annotation that contains the comment that was updated |
| targetCommentId | number | The ID of the target comment that was updated |
| updateContext | Function | Use this to update the custom metadata on the comment annotation. |
#### getAllCommentAnnotations
* Get all comment annotations for a given document and location.
* By default, it will return data for the current `documentId` and `location`.
* Params (optional):
* `documentId`: string; it will return all comments in the given `documentId`.
* `location`: Object; it will return all comments in the given `location`.
**Using Hooks:**
```jsx theme={null}
const commentAnnotations = useCommentAnnotations();
useEffect(() => {
if (commentAnnotations) {
console.log('commentAnnotations', commentAnnotations);
}
}, [commentAnnotations]);
```
**Using API:**
```js theme={null}
const commentElement = client.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((comments) => {
console.log('commentAnnotations', comments);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```js theme={null}
if (Velt) {
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((comments) => {
// Do something with comments
});
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
# Notifications
Source: https://docs.velt.dev/async-collaboration/comments/notifications
There are several options to send notifications to your users.
There are three ways to send notifications to your users:
Add notifications component within your app.
Send email notifications to your users.
Send notifications to other channels like Slack.
## In-app notifications
Add notifications component within your app. Learn more about [In-app notifications](/async-collaboration/notifications/overview).
## Email notifications
You can enable email notifications to send out emails whenever you `@mention` a user in the Comments feature or when another user replies to your comment.
There are two ways to trigger email notifications: Webhooks and SendGrid.
### Webhooks for non-SendGrid services
To learn how to trigger email notifications via Webhooks please refer [here](/webhooks/basic).
### SendGrid Integration
To enable Email Notifications, go to the Configurations -> Email Service in the Velt Console, or [click here](https://console.velt.dev/dashboard/config/email).
For SendGrid integration, provide the following details:
* SendGrid API Key
* SendGrid Email Template ID for Comments feature
* 'From' Email Address
The 'From' Email Address needs to be whitelisted from your SendGrid account or else it will not work.
#### Email Template Data
The following fields are sent to Sendgrid:
| Field | Type | Description |
| -------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| firstComment | [Comment](/api-reference/sdk/models/data-models#comment) | First message in the thread. **Only Contains** `commentId`, `commentText` and `from` properties derived from Comment class. |
| latestComment | [Comment](/api-reference/sdk/models/data-models#comment) | Latest message in the thread that prompted the email. **Only Contains** `commentId`, `commentText` and `from` properties derived from Comment class. |
| prevComment | [Comment](/api-reference/sdk/models/data-models#comment) | Previous message to the latestMessage. **Only Contains** `commentId`, `commentText` and `from` properties derived from Comment class. |
| commentsCount | string | Total number of comments in the comment annotation |
| commentsCountMoreThanThree | string | Total number of remaining comments in the comment annotation beyond the three that this payload contains |
| fromUser | [User](/api-reference/sdk/models/data-models#user) | Action user's object |
| commentAnnotation | [CommentAnnotation](/api-reference/sdk/models/data-models#commentannotation) | The comment annotation object without the `comments` field |
| actionType | string | The action that resulted in the notification. You can find the list of action types [here](/webhooks/basic#list-of-action-types) |
| documentMetadata | [DocumentMetadata](/api-reference/sdk/models/data-models#documentmetadata) | The document metadata object |
These are the older fields that will be deprecated soon. These are already contained in the fields above:
| Field | Type | Description |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| message | string | the message of the email |
| messageFromName | string | the name of whoever wrote the message that the email is referencing. If name is not found then it will contain the email. |
| name | string | the name of the person who performed the action that triggered the email. If name is not found then it will contain the email. Sometimes a notification can be triggered without a message. For those cases, you can use this. |
| fromEmail | string | email address of the user who performed the action |
| photoUrl | string | avatar URL of user |
| pageUrl | string | url of the page the comment is on |
| pageTitle | string | title of the web page |
| deviceInfo | Object | contains browser, OS and device info |
| subject | string | subject of the email |
#### Sample Payload sent to SendGrid
```json expandable lines theme={null}
{
"fromName": "Tony via ",
"fromEmail": "noreply@example.com",
"replyTo": "tony@example.com",
"templateId": "d-60ba77a7a42a4e55803487b40982b499",
"toEmail": "jess@example.com",
"properties": {
"message": "@Jess",
"messageFromName": "Tony",
"name": "Tony",
"fromName": "Tony via ",
"fromEmail": "tony@trysnippyly.com",
"photoUrl": "PHOTO_URL",
"pageUrl": "https://example.com/?scommentId=4Fnt7zTvPv9ggE7OOTVG",
"pageTitle": "Example Title",
"deviceInfo": {...},
"subject": "added you to a comment on Example Title",
"actionType": "newlyAdded",
"fromUser": {...}, // User Object
"commentAnnotation": {...}, // CommentAnnotation Object
"commentsCount": 1,
"firstComment": {...}, // Comment Object
"prevComment": {...}, // Comment Object
"commentsCountMoreThanThree": 0,
"latestComment": {...}, // Comment Object
"documentMetadata": {...} // DocumentMetadata Object
}
}
```
#### Download Sample Email Template
Email Template
@here testing here functionality
{{messageFromName}} mentioned you on {{pageTitle}}
{{deviceInfo.deviceType}} •
{{deviceInfo.screenWidth}}
x {{deviceInfo.screenHeight}} {{deviceInfo.browserName}}
```
## Webhooks
Send notifications to other channels like Slack. Learn more about [Webhooks](/webhooks/basic).
# Comments
Source: https://docs.velt.dev/async-collaboration/comments/overview
Your users can add comments in context to ask questions, leave feedback, report bugs etc. We handle all complexity to ensure the comments are robust against content changes. We support many types of comment UX patterns as illustrated below.
With `Freestyle` comments, you can pin `Comments` on any elements on the page or draw area comments.
[Open in larger window](https://demo-examples.vercel.app/async/comments/area-comments?background=000\&theme=dark)
[View Setup for Freestyle Comments](/async-collaboration/comments/setup/freestyle)
With `Popover` comments, you can add `Comments` on table cells, like in Google Sheets.
[Open in larger window](https://demo-examples.vercel.app/async/comments/popover-comments?background=000\&theme=dark)
[View Setup for Popover Comments](/async-collaboration/comments/setup/popover)
With `Stream` mode, your `Comments` will appear in a column on the right side.
[Open in larger window](https://demo-examples.vercel.app/async/comments/stream-comments?background=000\&theme=dark)
[View Setup for Stream Comments](/async-collaboration/comments/setup/stream)
With `Text` comments, you can leave `Comments` as text highlights.
[Open in larger window](https://demo-examples.vercel.app/async/comments/text-comments?background=000\&theme=dark)
[View Setup for Text Comments](/async-collaboration/comments/setup/text)
Add comments to your Tiptap editor.
[Open in larger window](https://documentation-app-demo.vercel.app/?focused=true)
[View Setup for Tiptap Comments](/async-collaboration/comments/setup/tiptap)
With `Inline` comments, you can add a more traditional style of comments.
[Open in larger window](https://demo-examples.vercel.app/async/comments/inline-comments?background=000\&theme=dark)
[View Setup for Inline Comments](/async-collaboration/comments/setup/inline-comments)
With `Page` comments, you can leave `Comments` at the page level.
[Open in larger window](https://demo-examples.vercel.app/async/comments/page-comments?background=000\&theme=dark)
[View Setup for Page Comments](/async-collaboration/comments/setup/page)
With `Chart` comments, you can leave `Comments` on popular charting libraries.
[Open in larger window](https://analytics-chartjs-demo.vercel.app/?focused=true)
[View Setup for Chart Comments](/async-collaboration/comments/setup/chart-comments-setup/highcharts)
With `Video` comments, you can leave frame by frame `Comments` on videos.
[Open in larger window](https://demo-examples.vercel.app/async/comments/video-comments?background=000000\&theme=dark)
[View Setup for Video Comments](/async-collaboration/comments/setup/video-player-setup/video-player-setup)
With `Lottie` comments, you can leave frame by frame `Comments` on Lottie animations.
[Open in larger window](https://demo-examples.vercel.app/async/comments/lottie-comments?background=1A1A1A\&theme=dark)
[View Setup for Lottie Comments](/async-collaboration/comments/setup/lottie-player-setup)
There are several customizable components that work as part of the `Comments` feature set.
# Ace Editor Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/ace
```js theme={null}
```
```html theme={null}
#### Step 2: Install the Velt Ace extension
```bash theme={null}
npm i @veltdev/ace-velt-comments
```
#### Step 3: Configure the Ace editor with the Velt Comments extension
```js theme={null}
import { useEffect, useRef, useCallback } from 'react';
import AceEditor from 'react-ace';
import 'ace-builds/src-noconflict/mode-markdown';
import 'ace-builds/src-noconflict/theme-github';
import { AceVeltComments } from '@veltdev/ace-velt-comments';
function AceEditorComponent() {
const editorRef = useRef(null);
const cleanupRef = useRef(null);
const handleLoad = useCallback((editor) => {
editorRef.current = editor;
// Initialize Velt comments - returns a cleanup function
cleanupRef.current = AceVeltComments(editor);
}, []);
useEffect(() => {
return () => {
if (cleanupRef.current) {
cleanupRef.current();
}
};
}, []);
return (
```js theme={null}
import * as ace from 'ace-builds';
import 'ace-builds/src-noconflict/mode-markdown';
import 'ace-builds/src-noconflict/theme-github';
import { AceVeltComments } from '@veltdev/ace-velt-comments';
const editor = ace.edit(document.querySelector('#editor'));
editor.setTheme('ace/theme/github');
editor.session.setMode('ace/mode/markdown');
editor.setValue('Your initial content here', -1);
// Initialize Velt comments - returns a cleanup function
const cleanup = AceVeltComments(editor);
// Call cleanup() when done to remove event listeners
// cleanup();
```
#### Step 4: Add a comment button to your Ace editor
* Add a button that users can click to add comments after selecting text.
```js theme={null}
import { addComment } from '@veltdev/ace-velt-comments';
// Add this button before in your JSX
e.preventDefault()}
onClick={() => {
if (editorRef.current) {
addComment({ editor: editorRef.current });
}
}}
>
Add Comment
```
```html theme={null}
```
```js theme={null}
import { addComment } from '@veltdev/ace-velt-comments';
const addCommentBtn = document.getElementById('add-comment-btn');
addCommentBtn.addEventListener('mousedown', (e) => e.preventDefault());
addCommentBtn.addEventListener('click', () => {
addComment({ editor });
});
```
#### Step 5: Call `addComment` to add a comment
* Call this method to add a comment to selected text in the Ace editor. You can use this when the user clicks on the comment button or presses a keyboard shortcut.
* Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-5). It has the following properties:
* `editor`: instance of the Ace Editor.
* `editorId`: Id of the Ace editor. Use this if you have multiple Ace editors on the same page in your app. (optional)
* `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
```js theme={null}
import { addComment } from '@veltdev/ace-velt-comments';
const addCommentRequest = {
editor: editorRef.current,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
```js theme={null}
import { addComment } from '@veltdev/ace-velt-comments';
const addCommentRequest = {
editor,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
#### Step 6: Render comments in Ace editor
* Get the comment data from Velt SDK and render it in the Ace Editor.
* Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-5). It has the following properties:
* `editor`: Instance of the Ace Editor.
* `editorId`: Id of the Ace editor. Use this if you have multiple Ace editors on the same page in your app. (optional)
* `commentAnnotations`: Array of Comment Annotation objects.
```js theme={null}
import { renderComments } from '@veltdev/ace-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editorRef.current && annotations?.length) {
const renderCommentsRequest = {
editor: editorRef.current,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
}, [annotations]);
```
```js theme={null}
import { renderComments } from '@veltdev/ace-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations?.length) {
const renderCommentsRequest = {
editor,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
});
```
#### Step 7: Persist Velt Comment Marks (optional)
* By default, Velt comment marks (``) are persisted in the Ace editor by Velt SDK. When the editor loads and the Velt SDK initializes, the marks will be automatically added to the editor.
* If you plan to store the contents of the Ace editor on your end with the comment marks already included, you can disable this feature.
* Default: `true`
```js theme={null}
const cleanup = AceVeltComments(editor, {
persistVeltMarks: false,
});
```
#### Step 8: Style the commented text
* You can style the commented text by adding CSS for the `velt-comment-text` element.
```css theme={null}
velt-comment-text {
background-color: rgba(255, 255, 0, 0.3);
border-bottom: 2px solid #ffcc00;
cursor: pointer;
}
velt-comment-text:hover {
background-color: rgba(255, 255, 0, 0.5);
}
velt-comment-text.velt-comment-selected {
background-color: rgba(255, 255, 0, 0.5);
}
```
## APIs
#### [AceVeltComments()](/api-reference/sdk/api/api-methods#aceveltcomments)
Initializes the Velt Comments extension for an Ace Editor instance.
* Params: `editor: Ace.Editor`, `config?:` [AceVeltCommentsConfig](/api-reference/sdk/models/data-models#aceveltcommentsconfig)
* `editorId?: string` - Unique identifier for this editor instance (for multi-editor scenarios)
* `persistVeltMarks?: boolean` - Whether to persist Velt marks. Default: `true`
* Returns: `() => void` - Cleanup function to remove event listeners
```tsx theme={null}
import { useRef, useCallback } from 'react';
import AceEditor from 'react-ace';
import { AceVeltComments } from '@veltdev/ace-velt-comments';
function AceEditorComponent() {
const editorRef = useRef(null);
const cleanupRef = useRef(null);
const handleLoad = useCallback((editor) => {
editorRef.current = editor;
cleanupRef.current = AceVeltComments(editor, {
editorId: 'my-editor',
persistVeltMarks: true,
});
}, []);
return (
```tsx theme={null}
import * as ace from 'ace-builds';
import { AceVeltComments } from '@veltdev/ace-velt-comments';
const editor = ace.edit(document.querySelector('#editor'));
const cleanup = AceVeltComments(editor, {
editorId: 'my-editor',
persistVeltMarks: true,
});
// Later, when done:
cleanup();
```
#### [addComment()](/api-reference/sdk/api/api-methods#addcomment-5)
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-5)
* `editor: Ace.Editor`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
```tsx theme={null}
import { addComment } from '@veltdev/ace-velt-comments';
{
e.preventDefault();
addComment({
editor: editorRef.current,
editorId: 'my-editor',
context: { customData: 'value' }
});
}}
>
Comment
```
```tsx theme={null}
import { addComment } from '@veltdev/ace-velt-comments';
addComment({
editor,
editorId: 'my-editor',
context: { customData: 'value' },
});
```
#### [renderComments()](/api-reference/sdk/api/api-methods#rendercomments-5)
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-5)
* `editor: Ace.Editor`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
```tsx theme={null}
import { useEffect } from 'react';
import { renderComments } from '@veltdev/ace-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editorRef.current && annotations) {
renderComments({
editor: editorRef.current,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
}, [annotations]);
```
```tsx theme={null}
import { renderComments } from '@veltdev/ace-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
});
```
# Comments
Source: https://docs.velt.dev/async-collaboration/comments/setup/canvas
Add comments to an HTML Canvas.
Import the `VeltCommentPin` component and the `useCommentAnnotations()` hook.
```jsx theme={null}
import { VeltCommentPin, useCommentAnnotations } from '@veltdev/react';
```
Use the `onCommentAdd` method to add custom metadata to a comment when a new comment is being added.
This metadata can be used later to set the position of the Comment Pin.
You need to set the mandatory `commentType: 'manual'` property to the metadata object.
```jsx theme={null}
yourMethod(event)} />
const yourMethod = (event) => {
event?.addContext({ customKey: 'customValue', commentType: 'manual' });
}
```
Retrieve all `Comment Annotations` using the `useCommentAnnotations()` hook.
To learn more about the `useCommentAnnotations()` hook, [read here](/api-reference/sdk/api/react-hooks#usegetcommentannotations).
```jsx theme={null}
let commentAnnotations = useCommentAnnotations()
```
Add the `Velt Comment Pin` component and pass in the `Comment Annotation Id`.
Now retrieve the `context` to retrieve the custom metadata you set earlier and use it to set the position of the `Comment Pin`.
```jsx theme={null}
let commentAnnotations = useCommentAnnotations()
return (
{
commentAnnotations.map((commentAnnotation) => {
return (
)
})
}
Use the `onCommentAdd` method to add custom metadata to a comment when a new comment is being added.
This metadata can be used later to set the position of the Comment Pin.
You need to set the mandatory `commentType: 'manual'` property to the metadata object.
```js theme={null}
const veltCommentsTag = document.querySelector('velt-comments');
veltCommentsTag?.addEventListener('onCommentAdd', (event) => {
console.log('*** onCommentAdd ***');
console.log(event.detail);
event.detail?.addContext({ customKey: 'customValue', commentType: 'manual'});
});
```
Retrieve all existing `Comment Annotations` using the `getAllCommentAnnotations()` method.
To learn more about the `getAllCommentAnnotations` method, [read here](/async-collaboration/comments/customize-behavior#getcommentannotations).
```js theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((commentAnnotations) => {
// console.log(commentAnnotations);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
Add the `Velt Comment Pin` component and pass in the `Comment Annotation Id`.
Now retrieve the `context` to retrieve the custom metadata you set earlier and use it to set the position of the `Comment Pin`.
```js theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((commentAnnotations) => {
renderCommentAnnotations(commentAnnotations);
});
const commentsContainer = document.getElementById('comments-container');
function renderCommentAnnotations(commentAnnotations) {
commentAnnotations.forEach((commentAnnotation) => {
if (!document.getElementById(`comment-pin-container-${commentAnnotation.annotationId}`)) {
// Add Comment Pin if it doesn't exist
const { x, y } = commentAnnotation.context.position;
var commentPinContainer = document.createElement('div');
commentPinContainer.className = 'comment-pin-container';
commentPinContainer.id = `comment-pin-container-${commentAnnotation.annotationId}`;
commentPinContainer.style.left = x + 'px';
commentPinContainer.style.top = y + 'px';
commentPinContainer.innerHTML = `
```jsx React / Next.js theme={null}
import { VeltCommentPin, useCommentAnnotations } from '@veltdev/react';
export default function YourDocument() {
const yourMethod = (event) => {
event?.addContext({ customKey: 'customValue', commentType: 'manual' });
}
let commentAnnotations = useCommentAnnotations()
return (
yourMethod(event)} />
{
commentAnnotations.map((commentAnnotation) => {
return (
)
})
}
# Overview
Source: https://docs.velt.dev/async-collaboration/comments/setup/canvas-comments/overview
Within any charts library you have the option to manually set the position of a Comment Annotation using the `Comment Pin` component.
## How to Use
Use `Comment Pin` in combination with the following:
1. `onCommentAdd`: Add custom metadata when adding a comment. This metadata can be used later to set the position of the Comment Pin. [Learn more](/async-collaboration/comments/customize-behavior#event-subscription)
2. `getAllCommentAnnotations`: Get all Comment Annotations with the custom metadata you set using above. Render the Comment Pin component and use the custom metadata to set its position yourself.
Note for react developers hooks are also available. [Learn more](/async-collaboration/comments/customize-behavior#getcommentannotations)
# ChartJS Comments Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/chart-comments-setup/chartjs
```jsx theme={null}
import { Chart as ChartJS, BarElement } from 'chart.js';
import { Bar } from 'react-chartjs-2'
```
* Add `VeltComments` to the root of your app. This component is required to render comments in your app.
* Add the `VeltCommentTool` component wherever you want to show the comment tool button. Clicking on it initiates comment mode & changes your mouse cursor to a comment pin.
* Create a `ref` and pass it into the `ref` property of the `ChartJS` component.
```jsx theme={null}
const chartRef = useRef(null);
1. Apply `position: relative` style to the div. This ensures accurate positioning of Velt Comment Pins.
2. Set `data-velt-manual-comment-container` to `true`. This:
* informs Velt which div to use for positioning
* disables Velt's automatic comment positioning system within this div, allowing for manual positioning of comment pins
3. Give a unique ID to the chart to scope comments to the specific chart, isolating them from other charts.
```jsx theme={null}
const chartId = 'dataAnalyticsChart'; // Unique ID for the chart
```
```jsx theme={null}
return (
);
```
1. Handle chart click to find nearest data point and add a comment. *(Check `handleChartClick() method` on the right)*
2. Create `context` object which contains the information about the series, x-axis value, y-axis value, chartId and anything else that's relevant. This will be used when rendering the comment pin. *(Check `handleChartClick() method` on the right)*
3. Add comment with the `context` data. *(Check `addManualComment() method` on the right)*
* Only add a comment if the Velt `commentModeState` is true and the Velt `client` is available.
1. Get all comment annotations.
2. Loop through it and render the comment pin.
3. Use the `context` data in `CommentAnnotation`, to set the position of the comment pin. *(Check `showCommentPin() method` on the right)*
```jsx theme={null}
const commentAnnotations = useCommentAnnotations(); // Get Velt comment annotations
const [chartCommentAnnotations, setChartCommentAnnotations] = React.useState([]); // Store annotations for this chart
useEffect(() => {
// Filter and store comments for the current chart, using unique chart ID
const chartCommentAnnotations = commentAnnotations?.filter((comment) => comment.context?.chartId === chartId);
setChartCommentAnnotations(chartCommentAnnotations as any || []);
}, [commentAnnotations]);
return (
... {/* Rest of the container code. */}
{/* Loop through comment annotations and render the comment pin. */}
{chartCommentAnnotations.map((comment, index) => showCommentPin(comment))}
... {/* Rest of the container code. */}
);
```
Coming Soon
```js React / Next.js theme={null}
import React, { useEffect, useRef, useMemo } from 'react';
import { Chart as ChartJS, CategoryScale, LinearScale, PointElement, BarElement, Title, Tooltip, Legend, Filler,} from 'chart.js';
import { Bar } from 'react-chartjs-2';
import { useVeltClient, useCommentAnnotations, useCommentModeState, VeltCommentPin } from '@veltdev/react';
// Register the necessary Chart.js components
ChartJS.register(CategoryScale, LinearScale, PointElement, BarElement, Title, Tooltip, Legend, Filler);
// Define the data for the chart
const scores = [6, 5, 5, 5, 3, 4, 6, 4, 5];
const labels = [100, 200, 300, 400, 500, 600, 700];
// Set the options for the chart
const options: any = {
// your chart options
};
const BarChart = () => {
const chartId = 'dataAnalyticsChart'; // Unique ID for the chart
const chartRef = useRef(null); // Reference to the chart instance
const { client } = useVeltClient(); // Get Velt client
const commentModeState = useCommentModeState(); // Get Velt comment mode state
const commentAnnotations = useCommentAnnotations(); // Get Velt comment annotations
const [chartCommentAnnotations, setChartCommentAnnotations] = React.useState([]); // State for chart comments
// Update chart comments when annotations change
useEffect(() => {
// Filter comments for the current chart, using unique chart ID
const chartCommentAnnotations = commentAnnotations?.filter((comment) => comment.context?.chartId === chartId);
setChartCommentAnnotations(chartCommentAnnotations as any || []);
}, [commentAnnotations]);
// Handle chart clicks to find nearest data point and add a comment
const handleChartClick = (event: any) => {
const chart: any = chartRef.current;
if (chart) {
// Get the nearest element to the click event
const elements = chart.getElementsAtEventForMode(event.nativeEvent, 'nearest', { intersect: true }, false);
if (elements.length > 0) {
const element = elements[0];
const datasetIndex = element.datasetIndex;
const index = element.index;
const dataset = chart.data.datasets[datasetIndex];
const xValue = chart.data.labels[index];
const yValue = dataset.data[index];
const context = { seriesId: dataset.label, xValue, yValue, chartId };
addManualComment(context); // Add a comment at the nearest data point with the context data
}
}
};
// Add a manual comment to the chart
const addManualComment = (context: any) => {
try {
if (client && commentModeState) {
const commentElement = client.getCommentElement();
commentElement.addManualComment({ context }); // Add a Velt comment
}
} catch (error) {
console.error('Error adding manual comment', error);
}
};
// Find the exact point on the chart to place a comment pin
const findPoint = (seriesId: any, xValue: any, yValue: any) => {
const chart: any = chartRef.current;
if (chart) {
const dataset = chart.data.datasets.find((dataset: any) => dataset.label === seriesId);
const index = chart.data.labels.indexOf(xValue);
if (dataset && index !== -1) {
const yValueInDataset = dataset.data[index];
if (yValueInDataset === yValue) {
return { x: chart.scales.x.getPixelForValue(index), y: chart.scales.y.getPixelForValue(yValue) }; // Set the x, y position for the comment pin
}
}
}
return null;
};
// Show the comment pin on the chart at the specified point
const showCommentPin = (commentAnnotation: any) => {
const context = commentAnnotation.context || {};
const point = findPoint(context.seriesId, context.xValue, context.yValue);
if (point) {
const { x, y } = point;
return (
);
}
return null;
};
// Memoize the chart data
const data = useMemo(() => {
return {
datasets: [
{
label: 'Mis datos',
tension: 0.3,
data: scores,
borderColor: 'rgb(75, 192, 192)',
backgroundColor: 'rgba(75, 192, 192, 0.3)',
},
],
labels,
};
}, []);
return (
Bar Chart With Comments
{/* Keep the parent div as relative, as comment pin will be placed with absolute position */}
{/* Set "data-velt-manual-comment-container" to true, so that comment pin will know which div to consider while positioning */}
);
};
export default BarChart;
```
# Custom Charts Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/chart-comments-setup/custom-charts
Here we have used ChartJS as an example library, you can follow the approach for any other charting library
```jsx theme={null}
import { Chart as ChartJS, BarElement } from 'chart.js';
import { Bar } from 'react-chartjs-2'
```
* Add `VeltComments` to the root of your app. This component is required to render comments in your app.
* Add the `VeltCommentTool` component wherever you want to show the comment tool button. Clicking on it initiates comment mode & changes your mouse cursor to a comment pin.
* Create a `ref` and pass it into the `ref` property of the `ChartJS` component.
```jsx theme={null}
const chartRef = useRef(null);
1. Apply `position: relative` style to the div. This ensures accurate positioning of Velt Comment Pins.
2. Set `data-velt-manual-comment-container` to `true`. This:
* informs Velt which div to use for positioning
* disables Velt's automatic comment positioning system within this div, allowing for manual positioning of comment pins
3. Give a unique ID to the chart to scope comments to the specific chart, isolating them from other charts.
```jsx theme={null}
const chartId = 'dataAnalyticsChart'; // Unique ID for the chart
```
```jsx theme={null}
return (
);
```
1. Handle chart click to find nearest data point and add a comment. *(Check `handleChartClick() method` on the right)*
2. Create `context` object which contains the information about the series, x-axis value, y-axis value, chartId and anything else that's relevant. This will be used when rendering the comment pin. *(Check `handleChartClick() method` on the right)*
3. Add comment with the `context` data. *(Check `addManualComment() method` on the right)*
* Only add a comment if the Velt `commentModeState` is true and the Velt `client` is available.
1. Get all comment annotations.
2. Loop through it and render the comment pin.
3. Use the `context` data in `CommentAnnotation`, to set the position of the comment pin. *(Check `showCommentPin() method` on the right)*
```jsx theme={null}
const commentAnnotations = useCommentAnnotations(); // Get Velt comment annotations
const [chartCommentAnnotations, setChartCommentAnnotations] = React.useState([]); // Store annotations for this chart
useEffect(() => {
// Filter and store comments for the current chart, using unique chart ID
const chartCommentAnnotations = commentAnnotations?.filter((comment) => comment.context?.chartId === chartId);
setChartCommentAnnotations(chartCommentAnnotations as any || []);
}, [commentAnnotations]);
return (
... {/* Rest of the container code. */}
{/* Loop through comment annotations and render the comment pin. */}
{chartCommentAnnotations.map((comment, index) => showCommentPin(comment))}
... {/* Rest of the container code. */}
);
```
Coming Soon
```js React / Next.js theme={null}
import React, { useEffect, useRef, useMemo } from 'react';
import { Chart as ChartJS, CategoryScale, LinearScale, PointElement, BarElement, Title, Tooltip, Legend, Filler,} from 'chart.js';
import { Bar } from 'react-chartjs-2';
import { useVeltClient, useCommentAnnotations, useCommentModeState, VeltCommentPin } from '@veltdev/react';
// Register the necessary Chart.js components
ChartJS.register(CategoryScale, LinearScale, PointElement, BarElement, Title, Tooltip, Legend, Filler);
// Define the data for the chart
const scores = [6, 5, 5, 5, 3, 4, 6, 4, 5];
const labels = [100, 200, 300, 400, 500, 600, 700];
// Set the options for the chart
const options: any = {
// your chart options
};
const BarChart = () => {
const chartId = 'dataAnalyticsChart'; // Unique ID for the chart
const chartRef = useRef(null); // Reference to the chart instance
const { client } = useVeltClient(); // Get Velt client
const commentModeState = useCommentModeState(); // Get Velt comment mode state
const commentAnnotations = useCommentAnnotations(); // Get Velt comment annotations
const [chartCommentAnnotations, setChartCommentAnnotations] = React.useState([]); // State for chart comments
// Update chart comments when annotations change
useEffect(() => {
// Filter comments for the current chart, using unique chart ID
const chartCommentAnnotations = commentAnnotations?.filter((comment) => comment.context?.chartId === chartId);
setChartCommentAnnotations(chartCommentAnnotations as any || []);
}, [commentAnnotations]);
// Handle chart clicks to find nearest data point and add a comment
const handleChartClick = (event: any) => {
const chart: any = chartRef.current;
if (chart) {
// Get the nearest element to the click event
const elements = chart.getElementsAtEventForMode(event.nativeEvent, 'nearest', { intersect: true }, false);
if (elements.length > 0) {
const element = elements[0];
const datasetIndex = element.datasetIndex;
const index = element.index;
const dataset = chart.data.datasets[datasetIndex];
const xValue = chart.data.labels[index];
const yValue = dataset.data[index];
const context = { seriesId: dataset.label, xValue, yValue, chartId };
addManualComment(context); // Add a comment at the nearest data point with the context data
}
}
};
// Add a manual comment to the chart
const addManualComment = (context: any) => {
try {
if (client && commentModeState) {
const commentElement = client.getCommentElement();
commentElement.addManualComment({ context }); // Add a Velt comment
}
} catch (error) {
console.error('Error adding manual comment', error);
}
};
// Find the exact point on the chart to place a comment pin
const findPoint = (seriesId: any, xValue: any, yValue: any) => {
const chart: any = chartRef.current;
if (chart) {
const dataset = chart.data.datasets.find((dataset: any) => dataset.label === seriesId);
const index = chart.data.labels.indexOf(xValue);
if (dataset && index !== -1) {
const yValueInDataset = dataset.data[index];
if (yValueInDataset === yValue) {
return { x: chart.scales.x.getPixelForValue(index), y: chart.scales.y.getPixelForValue(yValue) }; // Set the x, y position for the comment pin
}
}
}
return null;
};
// Show the comment pin on the chart at the specified point
const showCommentPin = (commentAnnotation: any) => {
const context = commentAnnotation.context || {};
const point = findPoint(context.seriesId, context.xValue, context.yValue);
if (point) {
const { x, y } = point;
return (
);
}
return null;
};
// Memoize the chart data
const data = useMemo(() => {
return {
datasets: [
{
label: 'Mis datos',
tension: 0.3,
data: scores,
borderColor: 'rgb(75, 192, 192)',
backgroundColor: 'rgba(75, 192, 192, 0.3)',
},
],
labels,
};
}, []);
return (
Bar Chart With Comments
{/* Keep the parent div as relative, as comment pin will be placed with absolute position */}
{/* Set "data-velt-manual-comment-container" to true, so that comment pin will know which div to consider while positioning */}
);
};
export default BarChart;
```
# Highcharts Comments Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/chart-comments-setup/highcharts
```jsx theme={null}
import Highcharts from 'highcharts';
import HighchartsReact from 'highcharts-react-official';
```
* Add `VeltComments` once to the root of your app. This component is required to render comments in your app.
```jsx theme={null}
import { VeltHighChartComments, VeltComments } from '@veltdev/react';
```
* Create a `ref` and pass it into the `ref` property of the `HighchartsReact` component.
* This ref object will be used by Velt to get the Chart data and add comment pin to it.
```jsx theme={null}
const chartComponentRef = useRef(null);
* Give it a `position: relative` style. This will help position the Velt Comment Pins accurately.
```jsx theme={null}
```
* Conditionally render `VeltHighChartsComments` in the same container div as the `HighchartsReact` component.
* Set a unique `id` in the VeltHighChartsComments component to scope comments to the specific chart, isolating them from other charts.
* Pass the `chartComputedData` prop with the `ref` you created earlier.
```jsx theme={null}
```
* Pass an array to the `dialogMetadataTemplate` prop in the VeltHighChartsComments component.
* This array determines the chart metadata displayed in the comment dialog, representing the data point (e.g., x-axis and y-axis values) on which the comment was added.
* Customize the order of the keys or remove unnecessary keys to control how the metadata is presented in the comment dialog.
`Default: ['groupId', 'label', 'value']`
For example:
```jsx theme={null}
Coming Soon
```js React / Next.js theme={null}
import React, { useEffect, useRef, useState } from 'react';
import { VeltHighChartComments } from '@veltdev/react';
import Highcharts from 'highcharts';
import HighchartsReact from 'highcharts-react-official';
function HighChartsLineChartExample() {
const [data, setData] = useState(CHART_DATA);
const chartComponentRef = useRef(null);
const options = {
// your chart options
};
return (
);
}
```
# NivoCharts Comments Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/chart-comments-setup/nivo-charts
```jsx theme={null}
import { ResponsiveLine } from '@nivo/line';
```
* Add `VeltComments` once to the root of your app. This component is required to render comments in your app.
```jsx theme={null}
import { VeltNivoChartComments, VeltComments } from '@veltdev/react';
```
* Add a `nivo-chart-container` class to it. This will help us position the Velt Comment Pins accurately.
```jsx theme={null}
```
* Add a custom function as a layer inside your Nivo Chart component and return `VeltNivoChartComments` component.
* Set a unique `id` in the VeltNivoChartComments component to scope comments to the specific chart, isolating them from other charts.
* Pass the `chartComputedData` props to it.
```jsx theme={null}
{
return (
* Pass an array to the `dialogMetadataTemplate` prop in the VeltHighChartsComments component.
* This array determines the chart metadata displayed in the comment dialog, representing the data point (e.g., x-axis and y-axis values) on which the comment was added.
* Customize the order of the keys or remove unnecessary keys to control how the metadata is presented in the comment dialog.
`Default: ['groupId', 'label', 'value']`
For example:
```jsx theme={null}
Coming Soon
```js React / Next.js theme={null}
import { ResponsiveLine } from '@nivo/line';
import { VeltNivoChartComments } from '@veltdev/react';
import { useState } from 'react'
function YourComponent() {
const [data, setData] = useState(CHART_DATA);
return (
// add nivo-chart-container class to the parent element of your NivoChart
{
return (
)
}
```
# CodeMirror Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/codemirror
```js theme={null}
```
```html theme={null}
#### Step 2: Install the Velt CodeMirror extension
```bash theme={null}
npm i @veltdev/codemirror-velt-comments
```
#### Step 3: Configure the CodeMirror editor with the Velt Comments extension
```js theme={null}
import { EditorView, basicSetup } from 'codemirror';
import { CodemirrorVeltComments } from '@veltdev/codemirror-velt-comments';
const view = new EditorView({
doc: 'Your initial content here',
extensions: [
basicSetup,
CodemirrorVeltComments(),
// ... other extensions
],
parent: editorRef.current,
});
```
```js theme={null}
import { EditorView, basicSetup } from 'codemirror';
import { CodemirrorVeltComments } from '@veltdev/codemirror-velt-comments';
const editorView = new EditorView({
doc: 'Your initial content here',
extensions: [
basicSetup,
CodemirrorVeltComments(),
// ... other extensions
],
parent: document.querySelector('#editor'),
});
```
#### Step 4: Add a comment button to your CodeMirror editor
Add a button that users can click to add comments after selecting text.
**Important:** When clicking a button, the browser moves focus to the button which clears the editor selection. You need to save the selection on `mousedown` (before focus changes) and restore it before adding the comment.
```js theme={null}
import { useRef, useState, useEffect } from 'react';
import { EditorView, basicSetup } from 'codemirror';
import { CodemirrorVeltComments, addComment } from '@veltdev/codemirror-velt-comments';
function CodeMirrorEditor() {
const editorRef = useRef(null);
const [editorView, setEditorView] = useState(null);
const savedSelectionRef = useRef(null);
const annotations = useCommentAnnotations();
useEffect(() => {
if (!editorRef.current) return;
const view = new EditorView({
doc: 'Your initial content here',
extensions: [
basicSetup,
CodemirrorVeltComments(),
],
parent: editorRef.current,
});
setEditorView(view);
return () => view.destroy();
}, []);
const saveSelection = () => {
if (editorView) {
const { from, to } = editorView.state.selection.main;
if (from !== to) {
savedSelectionRef.current = { from, to };
}
}
};
const handleAddComment = () => {
if (editorView) {
if (savedSelectionRef.current) {
const { from, to } = savedSelectionRef.current;
if (from !== to) {
editorView.dispatch({
selection: { anchor: from, head: to }
});
}
}
addComment({ editor: editorView });
savedSelectionRef.current = null;
}
};
return (
{
e.preventDefault();
saveSelection();
}}
onClick={handleAddComment}
>
Add Comment
);
}
```
```html theme={null}
```
```js theme={null}
import { EditorView, basicSetup } from 'codemirror';
import { CodemirrorVeltComments, addComment } from '@veltdev/codemirror-velt-comments';
const editorView = new EditorView({
doc: 'Your initial content here',
extensions: [
basicSetup,
CodemirrorVeltComments(),
],
parent: document.querySelector('#editor'),
});
let savedSelection = null;
const saveSelection = () => {
if (editorView) {
const { from, to } = editorView.state.selection.main;
if (from !== to) {
savedSelection = { from, to };
}
}
};
const addCommentToEditor = () => {
if (editorView) {
if (savedSelection && savedSelection.from !== savedSelection.to) {
editorView.dispatch({
selection: { anchor: savedSelection.from, head: savedSelection.to }
});
}
addComment({ editor: editorView });
savedSelection = null;
}
};
const addCommentBtn = document.getElementById('add-comment-btn');
addCommentBtn.addEventListener('mousedown', (e) => {
e.preventDefault();
saveSelection();
});
addCommentBtn.addEventListener('click', addCommentToEditor);
```
#### Step 5: Call `addComment` to add a comment
* Call this method to add a comment to selected text in the CodeMirror editor. You can use this when the user clicks on the comment button or presses a keyboard shortcut.
* Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-4). It has the following properties:
* `editor`: instance of the CodeMirror EditorView.
* `editorId`: Id of the CodeMirror editor. Use this if you have multiple CodeMirror editors on the same page in your app. (optional)
* `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
```js theme={null}
import { addComment } from '@veltdev/codemirror-velt-comments';
const addCommentRequest = {
editor: editorView,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
```js theme={null}
import { addComment } from '@veltdev/codemirror-velt-comments';
const addCommentRequest = {
editor: editorView,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
#### Step 6: Render comments in CodeMirror editor
* Get the comment data from Velt SDK and render it in the CodeMirror editor.
* Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-4). It has the following properties:
* `editor`: Instance of the CodeMirror EditorView.
* `editorId`: Id of the CodeMirror editor. Use this if you have multiple CodeMirror editors on the same page in your app. (optional)
* `commentAnnotations`: Array of Comment Annotation objects.
```js theme={null}
import { renderComments } from '@veltdev/codemirror-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editorView && annotations?.length) {
const renderCommentsRequest = {
editor: editorView,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
}, [editorView, annotations]);
```
```js theme={null}
import { renderComments } from '@veltdev/codemirror-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editorView && annotations?.length) {
const renderCommentsRequest = {
editor: editorView,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
});
```
#### Step 7: Persist Velt Comment Marks (optional)
* By default, Velt comment marks (``) are persisted in the CodeMirror editor by Velt SDK. When the editor loads and the Velt SDK initializes, the marks will be automatically added to the editor.
* If you plan to store the contents of the CodeMirror editor on your end with the comment marks already included, you can disable this feature.
* Default: `true`
```js theme={null}
const editorView = new EditorView({
extensions: [
CodemirrorVeltComments({
persistVeltMarks: false,
}),
// ... other extensions
],
parent: editorRef.current,
});
```
#### Step 8: Style the commented text
* You can style the commented text by adding CSS for the `velt-comment-text` element.
```css theme={null}
velt-comment-text {
background-color: rgba(255, 255, 0, 0.3);
border-bottom: 2px solid #ffcc00;
cursor: pointer;
}
velt-comment-text:hover {
background-color: rgba(255, 255, 0, 0.5);
}
velt-comment-text.velt-comment-selected {
background-color: rgba(255, 255, 0, 0.5);
}
```
## APIs
#### [CodemirrorVeltComments()](/api-reference/sdk/api/api-methods#codemirrorveltcomments)
Creates the Velt Comments extension for CodeMirror.
* Params: `config?:` [CodemirrorVeltCommentsConfig](/api-reference/sdk/models/data-models#codemirrorveltcommentsconfig)
* `editorId?: string` - Unique identifier for this editor instance (for multi-editor scenarios)
* `persistVeltMarks?: boolean` - Whether to persist Velt marks. Default: `true`
* Returns: CodeMirror `Extension`
```tsx theme={null}
import { EditorView } from 'codemirror';
import { CodemirrorVeltComments } from '@veltdev/codemirror-velt-comments';
const view = new EditorView({
extensions: [
CodemirrorVeltComments({
editorId: 'my-editor',
persistVeltMarks: true,
}),
],
parent: editorRef.current,
});
```
```tsx theme={null}
import { EditorView } from 'codemirror';
import { CodemirrorVeltComments } from '@veltdev/codemirror-velt-comments';
const editorView = new EditorView({
extensions: [
CodemirrorVeltComments({
editorId: 'my-editor',
persistVeltMarks: true,
}),
],
parent: document.body,
});
```
#### [addComment()](/api-reference/sdk/api/api-methods#addcomment-4)
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-4)
* `editor: EditorView`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
```tsx theme={null}
import { addComment } from '@veltdev/codemirror-velt-comments';
{
e.preventDefault();
addComment({
editor: editorView,
editorId: 'my-editor',
context: { customData: 'value' }
});
}}
>
Comment
```
```tsx theme={null}
import { addComment } from '@veltdev/codemirror-velt-comments';
addComment({
editor: editorView,
editorId: 'my-editor',
context: { customData: 'value' },
});
```
#### [renderComments()](/api-reference/sdk/api/api-methods#rendercomments-4)
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-4)
* `editor: EditorView`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
```tsx theme={null}
import { useEffect } from 'react';
import { renderComments } from '@veltdev/codemirror-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editorView && annotations) {
renderComments({
editor: editorView,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
}, [editorView, annotations]);
```
```tsx theme={null}
import { renderComments } from '@veltdev/codemirror-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editorView && annotations) {
renderComments({
editor: editorView,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
});
```
# Freestyle Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/freestyle
Import the `VeltComments` component and the `VeltCommentTool` component.
```js theme={null}
import {
VeltProvider,
VeltComments,
VeltCommentTool
} from '@veltdev/react';
```
Add the `VeltComments` component to the root of your app.
This component is required to render comments in your app.
```js theme={null}
```
Add the `VeltCommentTool` component wherever you want to show the comment tool button.
```
Test it out by opening the page with Velt components in your browser.
Click on the `Comment Tool` and click anywhere on the page to add a comment.
Add the comment component to your template. Try to put it as close to the root level of your ``.
This component is required to render comments in your app.
```html theme={null}
Add the `` component wherever you want to show the comment tool button.
```
Test it out by adding a comment.
You should be able to leave comments using the `Comment Tool`.
```jsx React / Next.js theme={null}
import {
VeltProvider,
VeltComments,
VeltCommentTool
} from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Comment documentation
```
# Inline Comments Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/inline-comments
Import the `VeltProvider`, `VeltComments`, and `VeltInlineCommentsSection` component.
```js theme={null}
import { VeltProvider, VeltComments, VeltInlineCommentsSection } from '@veltdev/react';
```
* Add the `VeltComments` component to the root of your app where your `VeltProvider` is.
* This component is required to render comments in your app.
```js theme={null}
```
* Create an element to hold your Inline Comments component, such as a `div` or `section`.
* Add a unique element `id` to it.
```jsx theme={null}
```
* Add `VeltInlineCommentsSection` component inside your container.
* Add `targetElementId` property to the Velt Inline Comments component. This needs to match the id you set to the container. This binds the Inline Comments component with the desired container.
```jsx theme={null}
* Default: `true`
* By default inline comment section is multithreaded.
* You can make it single threaded by setting `multiThread` attribute to `false`.
```jsx theme={null}
Customize the placeholder text for comment, reply, and composer input fields.
```jsx theme={null}
* Add the Velt Comments component to the root of your app.
* This component is required to render comments in your app.
```html theme={null}
* Create an element to hold your Inline Comments component, such as a `div` or `section`.
* Add a unique element `id` to it.
```html theme={null}
```
* Add `velt-inline-comments-section` component inside your container.
* Add `target-element-id` property to the Velt Inline Comments component. This needs to match the id you set to the container. This binds the Inline Comments component with the desired container.
```jsx theme={null}
```
* Default: `true`
* By default inline comments are multithreaded.
* You can make it single threaded by setting `multi-thread` attribute to `false`.
```html theme={null}
```
Customize the placeholder text for comment, reply, and composer input fields.
```html theme={null}
```
```jsx React / Next.js theme={null}
import { VeltProvider, VeltComments } from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Comment documentation
# Lexical Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/lexical
```js theme={null}
```
```html theme={null}
#### Step 2: Install the Velt Lexical extension
```bash theme={null}
npm install @veltdev/lexical-velt-comments @veltdev/client lexical
```
#### Step 3: Configure the Lexical editor with the Velt Comments extension
* Register the `CommentNode` and configure your Lexical editor.
```js theme={null}
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { CommentNode } from '@veltdev/lexical-velt-comments';
const initialConfig = {
namespace: 'MyEditor',
nodes: [CommentNode],
onError: (error) => console.error(error),
};
function App() {
return (
{/* Editor plugins */}
);
}
```
```js theme={null}
import { createEditor } from 'lexical';
import { registerRichText } from '@lexical/rich-text';
import { CommentNode, addComment, renderComments } from '@veltdev/lexical-velt-comments';
const editor = createEditor({
namespace: 'MyEditor',
nodes: [CommentNode],
onError: (error) => {
throw error;
},
});
// Set the root element
editor.setRootElement(document.querySelector('#editor'));
// Register rich text support
registerRichText(editor);
```
#### Step 4: Add a comment button
* Add a button that users can click to add comments after selecting text.
```js theme={null}
import { useCallback } from 'react';
import { useLexicalComposerContext } from '@lexical/react/LexicalComposerContext';
import { addComment } from '@veltdev/lexical-velt-comments';
function AddCommentPlugin() {
const [editor] = useLexicalComposerContext();
const handleAddComment = useCallback(() => {
addComment({ editor });
}, [editor]);
return (
Add Comment
);
}
```
```html theme={null}
```
```js theme={null}
import { addComment } from '@veltdev/lexical-velt-comments';
const addCommentBtn = document.getElementById('add-comment-btn');
addCommentBtn.addEventListener('click', () => {
addComment({ editor });
});
```
#### Step 5: Call `addComment` to add a comment
* Call this method to add a comment to selected text in the Lexical editor. You can use this when the user clicks on a comment button or presses a keyboard shortcut.
* Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-3). It has the following properties:
* `editor`: Instance of the Lexical Editor.
* `editorId`: Id of the editor. Use this if you have multiple Lexical editors on the same page. (optional)
* `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
```js theme={null}
import { addComment } from '@veltdev/lexical-velt-comments';
const addCommentRequest = {
editor,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
```js theme={null}
import { addComment } from '@veltdev/lexical-velt-comments';
const addCommentRequest = {
editor,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
#### Step 6: Render comments in Lexical editor
* Get the comment data from Velt SDK and render it in the Lexical Editor.
* Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-3). It has the following properties:
* `editor`: Instance of the Lexical Editor.
* `editorId`: Id of the editor. Use this if you have multiple Lexical editors on the same page. (optional)
* `commentAnnotations`: Array of Comment Annotation objects.
```js theme={null}
import { renderComments } from '@veltdev/lexical-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
});
}
}, [editor, annotations]);
```
```js theme={null}
import { renderComments } from '@veltdev/lexical-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations?.length) {
const renderCommentsRequest = {
editor,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
});
```
#### Step 7: Persist Editor Content Without Velt Marks (optional)
* When saving editor content to your backend, you may want to exclude Velt comment marks to keep the content clean.
* Use `exportJSONWithoutComments` to export the editor state as JSON without Velt comment nodes.
```js theme={null}
import { exportJSONWithoutComments } from '@veltdev/lexical-velt-comments';
// Get clean editor state JSON without Velt comment marks
const cleanState = exportJSONWithoutComments(editor);
// Save to your backend
localStorage.setItem('editor-content', JSON.stringify(cleanState));
```
#### Step 8: Style the commented text
* Style the commented text by adding CSS for the `velt-comment-text` element.
```css theme={null}
velt-comment-text {
background-color: rgba(255, 255, 0, 0.3);
border-bottom: 2px solid #ffcc00;
cursor: pointer;
}
velt-comment-text:hover {
background-color: rgba(255, 255, 0, 0.5);
}
velt-comment-text.velt-comment-selected {
background-color: rgba(255, 255, 0, 0.5);
}
```
## Complete Example
```tsx theme={null}
import { LexicalComposer } from '@lexical/react/LexicalComposer';
import { CommentNode } from '@veltdev/lexical-velt-comments';
const initialConfig = {
namespace: 'MyEditor',
nodes: [CommentNode],
onError: console.error,
};
export default function Editor() {
return {/* plugins */} ;
}
```
```tsx theme={null}
import { createEditor } from 'lexical';
import { CommentNode } from '@veltdev/lexical-velt-comments';
const editor = createEditor({
namespace: 'MyEditor',
nodes: [CommentNode],
onError: (error) => {
throw error;
},
});
```
#### [addComment()](/api-reference/sdk/api/api-methods#addcomment)
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-3)
* `editor: LexicalEditor`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
```tsx theme={null}
import { addComment } from '@veltdev/lexical-velt-comments';
addComment({ editor, editorId: 'my-editor' })}>
Comment
```
```tsx theme={null}
import { addComment } from '@veltdev/lexical-velt-comments';
addComment({
editor,
editorId: 'my-editor',
context: { customData: 'value' },
});
```
#### [renderComments()](/api-reference/sdk/api/api-methods#rendercomments)
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-3)
* `editor: LexicalEditor`
* `editorId?: string`
* `commentAnnotations?:` [`CommentAnnotation[]`](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
```tsx theme={null}
import { useEffect } from 'react';
import { renderComments } from '@veltdev/lexical-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
}, [editor, annotations]);
```
```tsx theme={null}
import { renderComments } from '@veltdev/lexical-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
});
```
#### [exportJSONWithoutComments()](/api-reference/sdk/api/api-methods#exportjsonwithoutcomments)
Exports the editor state as serialized JSON while stripping out all comment nodes and normalizing adjacent text nodes.
* Params: `editor:` `LexicalEditor`
* Returns: `SerializedEditorState`
```tsx theme={null}
import { exportJSONWithoutComments } from '@veltdev/lexical-velt-comments';
const cleanState = exportJSONWithoutComments(editor);
```
# Lottie Player Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/lottie-player-setup
Make sure you turn React strict mode off.
### a. Add the `VeltComments` component in the root of your app
Add the `VeltComments` component to enable the Comment feature in your app.
Enable the follow attributes to be `true`:
* `priority`: allows user to P0, P1, or P2 as priority. You can customize this list.
* `autoCategorize`: allows AI to categorize comment as Question, Feedback, Bug, Other. You can customize this list.
* `commentIndex`: shows a small icon showing index of the comment in order of creation.
```jsx theme={null}
```
### b. Add the `VeltCommentTool` component wherever you want your render the comment tool.
Note you can also provide your own button to this component.
```jsx theme={null}
{/* your custom button (optional) */}
```
### c. Place the `VeltCommentPlayerTimeline` component as a sibling to your video player.
To show comment bubbles on your player seek bar, add the `` component as a sibling to your video player component.
It will auto adjust to the same width as your video player.
```jsx theme={null}
```
Right now we assume you have a maximum of one `` component and one sibling video player component per `documentID`
Ensure that the parent container of `` doesnt have CSS position value as 'static'.
### d. Add the `` component.
(Optional) To embed the sidebar in your existing component, set `embedMode` prop as `true`.
```jsx theme={null}
```
### e. Add the `` component.
This will open or close the Comment Sidebar.
Note you can also provide your own button to this component.
```jsx theme={null}
{/* your custom button (optional) */}
```
You can pass an integer to `totalMediaLength` using props to represent the total number of frames or seconds in the video:
```jsx theme={null}
Add an event handler on where you originally placed `` to handle `onCommentModeChange` events.
Use this whenever the user clicks on the comment tool, to pause your player and set a new `Location` in the Velt SDK.
Setting a `Location` in the Velt SDK ensures that the comments are tied to that particular media frame or timestamp.
```jsx theme={null}
onCommentModeChange(mode)} />
const onCommentModeChange = (mode) => {
// mode will be `true` if the user has activated the comment tool
// If the comment tool is active, pause the player and set the "location".
if (mode) {
// pause player
// See step 8 below for details
setLocation()
}
});
```
You can pass in a key value pair object that represents the current state of your player. If you are using the `VeltCommentPlayerTimeline` component, ensure to set the current rounded frame or second in the special key `currentMediaPosition`.
`currentMediaPosition` is a protected keyword that is used to arrange the comment bubbles on top of the video player timeline in the correct spot
```jsx theme={null}
const setLocation = (client) => {
// set currentMediaPosition property on a Location object to represent the current frame
let location = {
currentMediaPosition : 120
}
//set the Location using the client
client.setLocation(location)
}
```
Call `removeLocation()` when your player starts playing:
```jsx theme={null}
const removeLocation = () => {
//remove the location, so the video player can play without comments appearing in frames
client.removeLocation()
}
```
Add the `onCommentClick` event handler on the `VeltCommentsSidebar` & `VeltCommentPlayerTimeline` components you added earlier.
The event will give you back the `location` object that you had set earlier.
You can use this object to update your player state and also update the SDK's `location` so that we can start rendering the comments associated with that `location`.
### a. Handle it on the `VeltCommentsSidebar`:
```jsx theme={null}
onCommentClick(event)} />
const onCommentClick = (event) => {
if (event) {
// Get the location object from the event.
const { location } = event;
if (location) {
// Get the media position where the comment was added.
const { currentMediaPosition } = location;
if (currentMediaPosition) {
// Pause the player.
// Seek to the given comment media position.
// Set the Velt Location to the clicked comment location.
client.setLocation(location);
}
}
}
}
```
### b. Handle it on the `VeltCommentPlayerTimeline`:
```jsx theme={null}
onTimelineCommentClick(event)} />
const onTimelineCommentClick = (event) => {
if (event) {
// Get the location object from the event.
const { location } = event;
if (location) {
// Get the media position where the comment was added.
const { currentMediaPosition } = location;
if (currentMediaPosition) {
// Pause the player.
// Seek to the given comment media position.
// Set the Velt Location to the clicked comment location.
client.setLocation(location);
}
}
}
}
```
The clicked Comment data will be in the following format:
| property | type | description |
| ----------------- | ------ | --------------------------------------------------------------- |
| `documentId` | string | The document ID where the comment was added |
| `location` | object | The location where the comment was added |
| `targetElementId` | string | The DOM ID of the target element on which the comment was added |
| `context` | Object | Any context data passed when the comment was added |
# Additional Configurations
## Allow comments only on certain elements
Provide a list of element DOM IDs where commenting should be allowed.
Comments will be disabled for all other elements.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.allowedElementIds(['lottiePlayerContainer']);
```
### a. Add the `VeltComments` component in the root of your app
Add the `VeltComments` component to enable the Comment feature in your app.
Enable the follow attributes to be `true`:
* `priority`: allows user to P0, P1, or P2 as priority. You can customize this list.
* `auto-categorize`: allows AI to categorize comment as Question, Feedback, Bug, Other. You can customize this list.
* `comment-index`: shows a small icon showing index of the comment in order of creation.
```jsx theme={null}
```
### c. Place the `velt-commen-player-timeline` component as a sibling to your video player.
To show comment bubbles on your player seek bar, add the `` component as a sibling to your video player component.
It will auto adjust to the same width as your video player.
```jsx theme={null}
```
Right now we assume you have a maximum of one `` component and one sibling video player component per `documentID`
Ensure that the parent container of `` doesnt have CSS position value as 'static'.
### d. Add the `` component.
(Optional) To embed the sidebar in your existing component, set `embed-mode` prop as `true`.
```jsx theme={null}
` component.
This will open or close the Comment Sidebar.
Note you can also provide your own button to this component.
```jsx theme={null}
```
You can pass an integer to `total-media-length` using props to represent the total number of frames or seconds in the video:
```jsx theme={null}
Add an event handler to handle `onCommentModeChange` events.
Use this whenever the user clicks on the comment tool, to pause your player and set a new `Location` in the Velt SDK.
Setting a `Location` in the Velt SDK ensures that the comments are tied to that particular media frame or timestamp.
```jsx theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.onCommentModeChange().subscribe((mode) => {
// mode will be `true` if the user has activated the comment tool
// If the comment tool is active, pause the player and set the "location".
if (mode) {
// pause player
// See step 8 below for details
setLocation()
}
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
You can pass in a key value pair object that represents the current state of your player. If you are using the `velt-comment-player-timeline` component, ensure to set the current rounded frame or second in the special key `current-media-position`.
`current-media-position` is a protected keyword that is used to arrange the comment bubbles on top of the video player timeline in the correct spot
```jsx theme={null}
const setLocation = (client) => {
// set currentMediaPosition property on a Location object to represent the current frame
let location = {
currentMediaPosition : 120
}
//set the Location using the client
Velt.setLocation(location)
}
```
Call `removeLocation()` when your player starts playing:
```jsx theme={null}
const removeLocation = () => {
//remove the location, so the video player can play without comments appearing in frames
Velt.removeLocation()
}
```
Add the `onCommentClick` event handler on the `VeltCommentsSidebar` & `VeltCommentPlayerTimeline` components you added earlier.
The event will give you back the `location` object that you had set earlier.
You can use this object to update your player state and also update the SDK's `location` so that we can start rendering the comments associated with that `location`.
### a. Handle it on the `velt-comments-sidebar`:
```jsx theme={null}
`:
```html theme={null}
# Additional Configurations
## Allow comments only on certain elements
Provide a list of element DOM IDs where commenting should be allowed.
Comments will be disabled for all other elements.
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.allowedElementIds(['lottiePlayerContainer']);
```
# Page Mode Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/page
Import the Comments Sidebar Components.
```jsx theme={null}
import {
VeltProvider,
VeltCommentsSidebar,
VeltSidebarButton,
} from '@veltdev/react';
```
Add the `VeltComments` and `VeltCommentsSidebar` components to the root of your app.
```jsx theme={null}
```
Set the `pageMode` attribute to true on the `VeltCommentsSidebar` component.
```js App.js theme={null}
```
Add the Sidebar button to toggle the sidebar.
```jsx theme={null}
```
Test Page Mode out by opening the sidebar. You should be able to leave Page Mode comments at the bottom of the Comments Sidebar.
Place the `` component at the root of your app.
```html theme={null}
Enable Page Mode by setting the `page-mode` attribute to `true` on the `` component.
```html theme={null}
Place the `` component wherever you want the toggle button to appear.
```html theme={null}
Test Page Mode out by opening the sidebar. You should be able to leave Page Mode comments at the bottom of the Comments Sidebar.
```jsx React / Next.js theme={null}
import {
VeltProvider,
VeltCommentsSidebar,
VeltSidebarButton,
} from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Collaboration App
```
# Plate Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/plate
Plate.js is a React-only framework. This guide covers the React integration only.
## Setup
#### Step 1: Add Comment components
* Add the `Velt Comments` component to the root of your app.
* This component is required to render comments in your app.
* Set the `text mode` prop to `false` to hide the default text comment tool.
```js theme={null}
```
#### Step 2: Install the Velt Plate extension
```bash theme={null}
npm i @veltdev/plate-comments-react
```
#### Step 3: Configure the Plate editor with the Velt Comments extension
* Import `VeltCommentsPlugin` and add it to your Plate editor's plugins array.
```js theme={null}
import { Plate, PlateContent, usePlateEditor } from '@platejs/core/react';
import { VeltCommentsPlugin } from '@veltdev/plate-comments-react';
function PlateEditor() {
const editor = usePlateEditor({
plugins: [VeltCommentsPlugin],
value: initialValue, // Your initial editor content
});
return (
);
}
```
#### Step 4: Add a comment button to your Plate editor
* Add a button that users can click to add comments after selecting text.
* Use `onMouseDown` with `preventDefault` to preserve the editor selection when clicking the button.
```js theme={null}
import { Plate, PlateContent, usePlateEditor } from '@platejs/core/react';
import { VeltCommentsPlugin, addComment } from '@veltdev/plate-comments-react';
function PlateEditor() {
const editor = usePlateEditor({
plugins: [VeltCommentsPlugin],
value: initialValue,
});
const handleAddComment = () => {
if (editor) {
addComment({ editor });
}
};
return (
{
e.preventDefault();
handleAddComment();
}}
>
Add Comment
);
}
```
#### Step 5: Call `addComment` to add a comment
* Call this method to add a comment to selected text in the Plate editor. You can use this when the user clicks on the comment button or presses a keyboard shortcut.
* Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-4). It has the following properties:
* `editor`: Instance of the Plate editor.
* `editorId`: Id of the Plate editor. Use this if you have multiple Plate editors on the same page in your app. (optional)
* `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
```js theme={null}
import { addComment } from '@veltdev/plate-comments-react';
const addCommentRequest = {
editor,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
#### Step 6: Render comments in Plate editor
* Get the comment data from Velt SDK using the `useCommentAnnotations` hook and render it in the Plate editor.
* Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-4). It has the following properties:
* `editor`: Instance of the Plate editor.
* `editorId`: Id of the Plate editor. Use this if you have multiple Plate editors on the same page in your app. (optional)
* `commentAnnotations`: Array of Comment Annotation objects.
```js theme={null}
import { useEffect } from 'react';
import { renderComments } from '@veltdev/plate-comments-react';
import { useCommentAnnotations } from '@veltdev/react';
function PlateEditor() {
const annotations = useCommentAnnotations();
useEffect(() => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
});
}
}, [editor, annotations]);
// ... rest of component
}
```
#### Step 7: Persist Velt Comment Marks (optional)
* By default, Velt comment marks are persisted by the Velt SDK. When the editor loads and the Velt SDK initializes, the marks will be automatically added to the editor.
* If you plan to store the contents of the Plate editor on your end with the comment marks already included, you can disable this feature.
* Default: `true`
```js theme={null}
const editor = usePlateEditor({
plugins: [
VeltCommentsPlugin.configure({
options: {
persistVeltMarks: false,
},
}),
],
});
```
#### Step 8: Style the commented text
* You can style the commented text by adding CSS for the `velt-comment-text` element.
```css theme={null}
velt-comment-text {
background-color: rgba(255, 255, 0, 0.3);
border-bottom: 2px solid #ffcc00;
cursor: pointer;
}
velt-comment-text:hover {
background-color: rgba(255, 255, 0, 0.5);
}
velt-comment-text.velt-comment-selected {
background-color: rgba(255, 255, 0, 0.5);
}
```
## APIs
#### [VeltCommentsPlugin.configure()](/api-reference/sdk/api/api-methods#veltcommentsplugin-configure)
A Plate.js plugin for Velt Comments integration.
* Params: `options?:` [VeltCommentsPluginConfig](/api-reference/sdk/models/data-models#veltcommentspluginconfig)
* `editorId?: string` - Unique identifier for this editor instance (for multi-editor scenarios).
* `persistVeltMarks?: boolean` - Whether to persist Velt marks. Default: `true`.
* Returns: Plate Plugin
```tsx theme={null}
import { usePlateEditor } from '@platejs/core/react';
import { VeltCommentsPlugin } from '@veltdev/plate-comments-react';
// Basic usage
const editor = usePlateEditor({
plugins: [VeltCommentsPlugin],
});
// With configuration
const editor = usePlateEditor({
plugins: [
VeltCommentsPlugin.configure({
options: {
editorId: 'my-editor',
persistVeltMarks: true,
},
}),
],
});
```
#### [addComment()](/api-reference/sdk/api/api-methods#addcomment-4)
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-4)
* `editor: PlateEditor`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
```tsx theme={null}
import { addComment } from '@veltdev/plate-comments-react';
{
e.preventDefault();
addComment({
editor,
editorId: 'my-editor',
context: { customData: 'value' },
});
}}
>
Comment
```
#### [renderComments()](/api-reference/sdk/api/api-methods#rendercomments-4)
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-4)
* `editor: PlateEditor`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
```tsx theme={null}
import { useEffect } from 'react';
import { renderComments } from '@veltdev/plate-comments-react';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
}, [editor, annotations]);
```
#### [exportJSONWithoutComments()](/api-reference/sdk/api/api-methods#exportjsonwithoutcomments-2)
Exports the editor content as JSON with Velt comment elements removed. Useful when saving content to your backend without comment markup.
* Params: `content: Descendant[]` - The editor content (Slate nodes).
* Returns: `Descendant[]` - Content with comment elements removed.
```tsx theme={null}
import { exportJSONWithoutComments } from '@veltdev/plate-comments-react';
const saveContent = () => {
const cleanContent = exportJSONWithoutComments(editor.children);
// Save cleanContent to your backend
};
```
#### PlateVeltComment
React component for rendering Velt comment elements in the editor. This is automatically used by the plugin, but can be referenced for custom render element implementations.
```tsx theme={null}
import { PlateVeltComment, VeltCommentsElement } from '@veltdev/plate-comments-react';
const renderElement = (props) => {
if (props.element.type === 'veltComment') {
return
# Popover Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/popover
Import the `VeltComments`, `VeltCommentTool`, and `VeltCommentBubble` components.
```js theme={null}
import {
VeltProvider,
VeltComments,
VeltCommentTool,
VeltCommentBubble
} from '@veltdev/react';
```
No imports needed. The Velt SDK is loaded via script tag.
## Step 2: Add Comments component with Popover mode
Add the Comments component to the root of your app and enable Popover mode.
This component is required to render comments in your app. Popover mode means comments can be attached to specific target elements (similar to Google Sheets).
```js theme={null}
```
Add the comment component to your template close to the root level of your ``.
```html theme={null}
## Step 3: Add the Comment Tool component
There are two patterns for adding the Comment Tool:
* Add a Comment Tool next to each element you want to comment on
* Have a single Comment Tool and use it to pin comments on elements
### a. Comment Tool next to each element
Add a Comment Tool near each cell or element you want to comment on. For example, in a table you could add this tool to each cell and show it on hover or right click context menu.
* Add unique DOM ID to each element
* Set the `targetElementId` to match the element's ID
* When users click on the Comment Tool, it attaches a Comment to that element
* If your app is more complex and cannot have unique IDs for each element (e.g., table cell), you could also use `context` to bind the element and comment with custom metadata, which can then be used to filter, group, and render comments that match specific criteria. [Learn more](/async-collaboration/comments/customize-behavior#aggregation)
```jsx theme={null}
```
```html theme={null}
```
### b. Single Comment Tool
If you don't add the `data-velt-target-comment-element-id` attribute, you will be adding multiple Comment Annotations on the same element.
```jsx theme={null}
```
```html theme={null}
```
## Step 4: Add Metadata to the Comment
* Render additional data on comments UI
* Create custom UI components
* Enable comment filtering on custom data
* Use the metadata later when processing notifications
### a. Using Comment Tool
```jsx theme={null}
```html theme={null}
### b. Using Comment Add Event Callback
Learn more about it [here](/async-collaboration/comments/customize-behavior#addcontext).
## Step 5: Add the Comment Bubble component (optional)
Either use this or the default triangle component. Using both could cause visual UX issues. Turn off the triangle by setting `popoverTriangleComponent` to `false` in the Velt Comments component.
The Comment Bubble component:
* Displays a count of replies for a comment thread
* Must have the same `targetElementId` or `context` as its associated element and comment tool
* Can show either total replies or only unread replies
* Can be placed anywhere in your UI
**Props:**
* `commentCountType`: Which count to display
* `total`: Total number of replies (default)
* `unread`: Number of unread replies
```js theme={null}
```
```html theme={null}
```
### Remove Popover Mode Triangle (optional)
```jsx theme={null}
```
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enablePopoverTriangleComponent();
commentElement.disablePopoverTriangleComponent();
```
```html theme={null}
## Step 6: Test Integration
Test it out by opening the page with Velt components in your browser.
Click on the Comment Tool and leave a comment on the target element.
```jsx theme={null}
import {
VeltProvider,
VeltComments,
VeltCommentTool,
VeltCommentBubble
} from '@veltdev/react';
export default function App() {
return (
);
}
```
```html theme={null}
# Quill Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/quill
```js theme={null}
```
```html theme={null}
#### Step 2: Install the Velt Quill extension
```bash theme={null}
npm i @veltdev/quill-velt-comments
```
#### Step 3: Configure the Quill editor with the Velt Comments module
```js theme={null}
import { useEffect, useRef, useState } from 'react';
import Quill from 'quill';
import { QuillVeltComments } from '@veltdev/quill-velt-comments';
// Register the module with Quill (once, outside component)
Quill.register('modules/veltComments', QuillVeltComments);
function QuillEditor() {
const editorRef = useRef(null);
const [quill, setQuill] = useState(null);
useEffect(() => {
if (!editorRef.current) return;
const quillInstance = new Quill(editorRef.current, {
theme: 'snow',
modules: {
veltComments: {
persistVeltMarks: true,
},
},
});
setQuill(quillInstance);
}, []);
return
;
}
```
```js theme={null}
import Quill from 'quill';
import { QuillVeltComments } from '@veltdev/quill-velt-comments';
// Register the module with Quill
Quill.register('modules/veltComments', QuillVeltComments);
// Create editor with the module enabled
const quill = new Quill('#editor', {
theme: 'snow',
modules: {
veltComments: {
persistVeltMarks: true,
},
},
});
```
#### Step 4: Add a comment button to your Quill editor
Add a button that users can click to add comments after selecting text.
When clicking a button, the browser moves focus to the button which clears the editor selection. You must save the selection on `mousedown` (before focus changes) and restore it before adding the comment.
```js theme={null}
import { useCallback, useRef } from 'react';
import { addComment } from '@veltdev/quill-velt-comments';
// Inside your QuillEditor component from Step 3:
const savedSelectionRef = useRef(null);
const handleAddComment = useCallback(() => {
if (quill) {
if (savedSelectionRef.current) {
quill.setSelection(savedSelectionRef.current.index, savedSelectionRef.current.length);
}
addComment({ editor: quill });
savedSelectionRef.current = null;
}
}, [quill]);
// In your JSX:
{
e.preventDefault();
const sel = quill?.getSelection();
if (sel?.length > 0) savedSelectionRef.current = sel;
}}
onClick={handleAddComment}
>
Add Comment
```
```html theme={null}
```
```js theme={null}
import { addComment } from '@veltdev/quill-velt-comments';
let savedSelection = null;
const btn = document.getElementById('add-comment-btn');
btn.addEventListener('mousedown', () => {
const sel = quill.getSelection();
if (sel && sel.length > 0) savedSelection = sel;
});
btn.addEventListener('click', () => {
if (savedSelection) quill.setSelection(savedSelection.index, savedSelection.length);
addComment({ editor: quill });
savedSelection = null;
});
```
Unlike Tiptap, Quill does not have a built-in bubble menu. You will need to create your own comment button or toolbar item.
#### Step 5: Call `addComment` to add a comment
* Call this method to add a comment to selected text in the Quill editor. You can use this when the user clicks on the comment button or presses a keyboard shortcut.
* Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-6). It has the following properties:
* `editor`: Instance of the Quill editor.
* `editorId`: Id of the Quill editor. Use this if you have multiple Quill editors on the same page. (optional)
* `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
```js theme={null}
import { addComment } from '@veltdev/quill-velt-comments';
const addCommentRequest = {
editor: quill,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
```js theme={null}
import { addComment } from '@veltdev/quill-velt-comments';
const addCommentRequest = {
editor: quill,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
#### Step 6: Render comments in Quill editor
* Get the comment data from Velt SDK and render it in the Quill editor.
* Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-6). It has the following properties:
* `editor`: Instance of the Quill editor.
* `editorId`: Id of the Quill editor. Use this if you have multiple Quill editors on the same page. (optional)
* `commentAnnotations`: Array of Comment Annotation objects.
```js theme={null}
import { renderComments } from '@veltdev/quill-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (quill && annotations?.length) {
const renderCommentsRequest = {
editor: quill,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
}, [quill, annotations]);
```
```js theme={null}
import { renderComments } from '@veltdev/quill-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (quill && annotations?.length) {
const renderCommentsRequest = {
editor: quill,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
});
```
#### Step 7: Persist Velt Comment Marks (optional)
* By default, Velt comment marks (``) are persisted by the Velt SDK. When the editor loads and the Velt SDK initializes, the marks will be automatically added to the editor.
* If you plan to store the contents of the Quill editor on your end with the comment marks already included, you can disable this feature.
* Default: `true`
```js theme={null}
const quill = new Quill(editorRef.current, {
theme: 'snow',
modules: {
veltComments: {
persistVeltMarks: false,
},
},
});
```
#### Step 8: Style the commented text
* You can style the commented text by adding CSS for the `velt-comment-text` element.
```css theme={null}
velt-comment-text {
background-color: rgba(255, 255, 0, 0.3);
border-bottom: 2px solid #ffcc00;
cursor: pointer;
}
velt-comment-text:hover {
background-color: rgba(255, 255, 0, 0.5);
}
velt-comment-text.velt-comment-selected {
background-color: rgba(255, 255, 0, 0.5);
}
```
## APIs
#### [QuillVeltComments](/api-reference/sdk/api/api-methods#quillveltcomments)
The Velt Comments module for Quill. Register it with Quill before creating the editor.
* Params: `options?:` [QuillVeltCommentsConfig](/api-reference/sdk/models/data-models#quillveltcommentsconfig)
* `editorId?: string` - Unique identifier for this editor instance (for multi-editor scenarios)
* `persistVeltMarks?: boolean` - Whether to persist Velt marks. Default: `true`
* Returns: `Quill Module`
```tsx theme={null}
import Quill from 'quill';
import { QuillVeltComments } from '@veltdev/quill-velt-comments';
Quill.register('modules/veltComments', QuillVeltComments);
const quillInstance = new Quill(editorRef.current, {
theme: 'snow',
modules: {
veltComments: {
editorId: 'my-editor',
persistVeltMarks: true,
},
},
});
```
```tsx theme={null}
import Quill from 'quill';
import { QuillVeltComments } from '@veltdev/quill-velt-comments';
Quill.register('modules/veltComments', QuillVeltComments);
const quill = new Quill('#editor', {
theme: 'snow',
modules: {
veltComments: {
editorId: 'my-editor',
persistVeltMarks: true,
},
},
});
```
#### [addComment()](/api-reference/sdk/api/api-methods#addcomment-6)
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest-6)
* `editor: Quill`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
```tsx theme={null}
import { addComment } from '@veltdev/quill-velt-comments';
{
e.preventDefault();
addComment({
editor: quill,
editorId: 'my-editor',
context: { customData: 'value' }
});
}}
>
Comment
```
```tsx theme={null}
import { addComment } from '@veltdev/quill-velt-comments';
addComment({
editor: quill,
editorId: 'my-editor',
context: { customData: 'value' },
});
```
#### [renderComments()](/api-reference/sdk/api/api-methods#rendercomments-6)
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest-6)
* `editor: Quill`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
```tsx theme={null}
import { useEffect } from 'react';
import { renderComments } from '@veltdev/quill-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (quill && annotations) {
renderComments({
editor: quill,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
}, [quill, annotations]);
```
```tsx theme={null}
import { renderComments } from '@veltdev/quill-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (quill && annotations) {
renderComments({
editor: quill,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
});
```
# SlateJS Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/slatejs
```js theme={null}
```
#### Step 2: Install the Velt SlateJS extension
```bash theme={null}
npm i @veltdev/slate-velt-comments
```
#### Step 3: Configure the SlateJS editor with the Velt Comments extension
```js theme={null}
import { withVeltComments } from '@veltdev/slate-velt-comments';
import { withReact, withHistory } from 'slate-react';
const editor = withVeltComments(
withReact(withHistory(createEditor())),
{ HistoryEditor: SlateHistoryEditor }
);
```
#### Step 4: Register Velt Component Type in SlateJS
* Register the Velt Comments Element type with your SlateJS editor's custom types.
* This ensures proper type checking for the comments functionality.
```ts theme={null}
import type { VeltCommentsElement } from '@veltdev/slate-velt-comments';
type CustomElement = VeltCommentsElement;
declare module 'slate' {
interface CustomTypes {
Element: CustomElement;
}
}
```
#### Step 5: Add a comment button to your SlateJS editor
* Add a button that appears in the context menu of your SlateJS editor when the user selects text.
* This button will be used to add a comment to the selected text.
```js theme={null}
import { addComment } from '@veltdev/slate-velt-comments';
import { useSlate } from 'slate-react';
const CommentButton = (props) => {
const editor = useSlate();
return (
{
e.preventDefault();
addComment({ editor });
}}
>
Comment
);
};
```
#### Step 6: Call `addComment` to add a comment
* Call this method to add a comment to selected text in the SlateJS editor. You can use this when the user clicks on the comment button in context menu or presses a keyboard shortcut.
* Params: `AddCommentRequest`
* `editorId`: string, the id of the editor. Use this if you have multiple editors in your app.
* `editor`: instance of the SlateJS editor.
* `context`: optional object to set the Comment Annotation's [custom metadata](/async-collaboration/comments/customize-behavior#metadata).
```js theme={null}
import { addComment } from '@veltdev/slate-velt-comments';
import { useSlate } from 'slate-react';
const CommentButton = (props) => {
const editor = useSlate();
return (
{
e.preventDefault();
addComment({ editor });
}}
>
Comment
);
};
```
#### Step 7: Render comments in SlateJS editor
* Get the comment data.
* Render the comments in the SlateJS editor.
* Params: `RenderCommentsRequest`
* `editorId`: string, the id of the editor. Use this if you have multiple editors in your app.
* `editor`: instance of the SlateJS editor.
* `commentAnnotations`: CommentAnnotation\[]
```js theme={null}
import { renderComments } from '@veltdev/slate-velt-comments';
const commentAnnotations = useCommentAnnotations();
useEffect(() => {
if (editor && commentAnnotations) {
renderComments({ editor, commentAnnotations });
}
}, [commentAnnotations, editor]);
```
#### Step 8: Style the commented text
* You can style the commented text by adding a CSS class to the `velt-comment-text` element.
* By using the `comment-available` attribute, you can apply styles only when the comment data has loaded.
```css theme={null}
velt-comment-text[comment-available="true"] {
background-color: #ffff00;
}
```
## Complete Example
```jsx theme={null}
import { withVeltComments } from '@veltdev/slate-velt-comments';
import { withReact, withHistory } from 'slate-react';
const editor = withVeltComments(
withReact(withHistory(createEditor())),
{ HistoryEditor: SlateHistoryEditor }
);
```
#### [addComment()](/api-reference/sdk/api/api-methods#addcomment)
Creates a comment annotation for the currently selected text in the editor.
* Signature: `async (request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)`) => Promise`
* Params: `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)
* Returns: `Promise`
```jsx theme={null}
import { addComment } from '@veltdev/slate-velt-comments';
{ e.preventDefault(); addComment({ editor }); }}>
Comment
```
#### [renderComments()](/api-reference/sdk/api/api-methods#rendercomments)
Renders and highlights comment annotations in the editor.
* Signature: `(request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest)`) => void`
* Params: `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest)
* Returns: `void`
```jsx theme={null}
import { renderComments } from '@veltdev/slate-velt-comments';
import type { CommentAnnotation } from '@veltdev/types';
useEffect(() => {
if (editor && commentAnnotations) {
renderComments({ editor, commentAnnotations });
}
}, [editor, commentAnnotations]);
```
#### [SlateVeltComment](/api-reference/sdk/api/api-methods#slateveltcomment)
React component that renders a Velt comment text element with annotation ID.
* Params:
* `props: RenderElementProps`
* `element:` [VeltCommentsElement](/api-reference/sdk/models/data-models#veltcommentselement)
* Returns: `N/A`
```tsx theme={null}
import { SlateVeltComment } from '@veltdev/slate-velt-comments';
import type { RenderElementProps } from 'slate-react';
import type { VeltCommentsElement } from '@veltdev/slate-velt-comments';
const RenderElement = (props: RenderElementProps) => {
if (props.element.type === 'veltComment') {
return {props.children}
;
};
```
# Stream Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/stream
Import the `VeltComments` component.
```js theme={null}
import {
VeltProvider,
VeltComments,
} from '@veltdev/react';
```
Add the `VeltComments` component inside a scrolling container. Make it a sibling to the element that contains the content you want to be commented.
In the `VeltComments` component, mark the `streamMode` attribute as `true`.
Also set the `streamViewContainerId` attribute to the id of the scrolling container.
Stream mode renders all comment dialog boxes in a column on the right side similar to Google Docs. It works well with Text mode, which is enabled by default.
Setting a reference to the container ID helps us position & scroll the comment stream as the user scrolls more robustly.
```js theme={null}
```
Test it out by adding a comment.
Select any text, a `Comment Tool` button will appear near the highlighted text.
Click on it to add a comment and see the comment appear in the comment stream.
Add the `` component inside a scrolling container. Make it a sibling to the element that contains the content you want to be commented.
In the `` component, mark the `stream-mode` attribute as `true`.
Also set the `stream-view-container-id` attribute to the id of the scrolling container.
Stream mode renders all comment dialog boxes in a column on the right side similar to Google Docs. It works well with Text mode, which is enabled by default.
Setting a reference to the container ID helps us position & scroll the comment stream as the user scrolls more robustly.
```html theme={null}
```
Test it out by adding a comment.
Select any text, a `Comment Tool` button will appear near the highlighted text.
Click on it to add a comment and see the comment appear in the comment stream.
```jsx React / Next.js theme={null}
import { VeltProvider, VeltComments, VeltCommentTool } from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Comment documentation
```
# Text Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/text
Import the `VeltComments` component.
```js theme={null}
import { VeltProvider, VeltComments } from '@veltdev/react';
```
Add the `VeltComments` component to the root of your app.
This component is required to render comments in your app.
Text mode is enabled by default. To disable it, set the `textMode` attribute to `false`.
Text mode allows users to select any text and attach comments to it similar to Google Docs.
```js theme={null}
```
Test it out by opening the page with Velt components in your browser.
Select any text, a `Comment Tool` button will appear near the highlighted text. Click on it to add a comment.
Add the comment component to your template. Try to put it as close to the root level of your ``.
This component is required to render comments in your app. Text mode allows users to attach comments to highlighted text.
```html theme={null}
Test it out by opening the page with Velt components in your browser.
Select any text, a `Comment Tool` button will appear near the highlighted text. Click on it to add a comment.
```jsx React / Next.js theme={null}
import { VeltProvider, VeltComments } from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Comment documentation
# Tiptap Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/tiptap
```js theme={null}
```
```html theme={null}
#### Step 2: Install the Velt Tiptap extension
```bash theme={null}
npm i @veltdev/tiptap-velt-comments
```
#### Step 3: Configure the Tiptap editor with the Velt Comments extension
```js theme={null}
import { TiptapVeltComments } from '@veltdev/tiptap-velt-comments';
const editor = new Editor({
extensions: [
TiptapVeltComments,
// ... other extensions
],
});
```
```js theme={null}
import { TiptapVeltComments } from '@veltdev/tiptap-velt-comments';
const editor = new Editor({
extensions: [
TiptapVeltComments,
// ... other extensions
],
});
```
#### Step 4: Add a comment button to your Tiptap editor
Add a button in your existing bubble menu or create a new bubble menu that appears when users select text in the editor.
```js theme={null}
import { BubbleMenu, EditorContent, useEditor } from '@tiptap/react';
import { addComment } from '@veltdev/tiptap-velt-comments';
export default function TipTapComponent() {
const editor = useEditor({
// ... your editor configuration
});
const addTiptapVeltComment = () => {
if (editor) {
addComment({ editor });
}
};
return (
{/* Bubble Menu for Comments */}
{editor && (
{
e.preventDefault();
e.stopPropagation();
addTiptapVeltComment();
}}
title="Add comment"
>
)}
);
}
```
```html theme={null}
```
```js theme={null}
import { BubbleMenu, Editor } from '@tiptap/core';
import { addComment } from '@veltdev/tiptap-velt-comments';
const editor = new Editor({
element: document.querySelector('#editor'),
// ... your editor configuration
});
const addTiptapVeltComment = () => {
if (editor) {
addComment({ editor });
}
};
// Create bubble menu
const bubbleMenu = new BubbleMenu({
editor,
element: document.querySelector('.bubble-menu'),
tippyOptions: { duration: 100 },
});
// Add click handler to comment button
document.querySelector('.comment-button').addEventListener('click', (e) => {
e.preventDefault();
e.stopPropagation();
addTiptapVeltComment();
});
```
Refer to the [Tiptap BubbleMenu documentation](https://tiptap.dev/docs/editor/extensions/functionality/bubble-menu) to learn more about customizing the bubble menu behavior.
#### Step 5: Call `addComment` to add a comment
* Call this method to add a comment to selected text in the Tiptap editor. You can use this when the user clicks on the comment button in context menu or presses a keyboard shortcut.
* Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest-1). It has the following properties:
* `editor`: instance of the Tiptap editor.
* `editorId`: Id of the tiptap editor. Use this if you have multiple tiptap editors on the same page in your app. (optional)
* `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
```js theme={null}
import { addComment } from '@veltdev/tiptap-velt-comments';
const addCommentRequest = {
editor,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
```js theme={null}
import { addComment } from '@veltdev/tiptap-velt-comments';
const addCommentRequest = {
editor,
editorId: 'EDITOR_ID',
context: {
storyId: 'story-id',
storyName: 'story-name',
},
};
addComment(addCommentRequest);
```
#### Step 6: Render comments in Tiptap editor
* Get the comment data from Velt SDK and render it in the Tiptap Editor.
* Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest-1). It has the following properties:
* `editor`: Instance of the Tiptap editor.
* `editorId`: Id of the tiptap editor. Use this if you have multiple tiptap editors on the same page in your app. (optional)
* `commentAnnotations`: Array of Comment Annotation objects.
```js theme={null}
import { renderComments } from '@veltdev/tiptap-velt-comments';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editor && annotations?.length) {
const renderCommentsRequest = {
editor,
editorId: 'EDITOR_ID',
annotations,
};
renderComments(renderCommentsRequest);
}
}, [editor, annotations]);
```
```js theme={null}
import { renderComments } from '@veltdev/tiptap-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations?.length) {
const renderCommentsRequest = {
editor,
editorId: 'EDITOR_ID',
commentAnnotations: annotations,
};
renderComments(renderCommentsRequest);
}
});
```
#### Step 7: Persist Velt Comment Marks (optional)
* By default, Velt comment marks (``) are persisted in the Tiptap editor by Velt SDK. When the editor loads and the velt sdk initializes, the marks will be automatically added to the editor by us.
* If you plan to store the contents of the tiptap editor as raw html on your end then you should turn off this feature since you will already be storing the Velt comment marks.
* Default: `true`
```js theme={null}
const editor = new Editor({
extensions: [
TiptapVeltComments.configure({
persistVeltMarks: false
}),
// ... other extensions
],
});
```
#### Step 8: Style the commented text
* You can style the commented text by adding a CSS class to the `velt-comment-text` element.
* By using the `comment-available` attribute, you can apply styles only when the comment data has loaded.
```css theme={null}
velt-comment-text[comment-available="true"] {
background-color: #ffff00;
}
```
## Complete Example
```tsx theme={null}
import { useEditor } from '@tiptap/react';
import StarterKit from '@tiptap/starter-kit';
import { TiptapVeltComments } from '@veltdev/tiptap-velt-comments';
const editor = useEditor({
extensions: [
StarterKit,
TiptapVeltComments.configure({
editorId: 'my-editor',
persistVeltMarks: true,
}),
],
content: 'Your content
',
});
```
```tsx theme={null}
import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import { TiptapVeltComments } from '@veltdev/tiptap-velt-comments';
const editor = new Editor({
element: document.querySelector('#editor'),
extensions: [
StarterKit,
TiptapVeltComments.configure({
editorId: 'my-editor',
persistVeltMarks: true,
}),
],
content: 'Your content
',
});
```
#### [addComment()](/api-reference/sdk/api/api-methods#addcomment-2)
Creates a comment annotation for the currently selected text in the editor.
* Params:
* `request:` [AddCommentRequest](/api-reference/sdk/models/data-models#addcommentrequest)
* `editor: Editor`
* `editorId?: string`
* `context?: object`
* Returns: `Promise`
```tsx theme={null}
import { addComment } from '@veltdev/tiptap-velt-comments';
{
e.preventDefault();
addComment({
editor,
editorId: 'my-editor',
context: { customData: 'value' }
});
}}
>
Comment
```
```tsx theme={null}
import { addComment } from '@veltdev/tiptap-velt-comments';
addComment({
editor,
editorId: 'my-editor',
context: { customData: 'value' },
});
```
#### [renderComments()](/api-reference/sdk/api/api-methods#rendercomments-2)
Renders and highlights comment annotations in the editor.
* Params:
* `request:` [RenderCommentsRequest](/api-reference/sdk/models/data-models#rendercommentsrequest)
* `editor: Editor`
* `editorId?: string`
* `commentAnnotations?:` [CommentAnnotation\[\]](/api-reference/sdk/models/data-models#commentannotation)
* Returns: `void`
```tsx theme={null}
import { useEffect } from 'react';
import { renderComments } from '@veltdev/tiptap-velt-comments';
import { useCommentAnnotations } from '@veltdev/react';
const annotations = useCommentAnnotations();
useEffect(() => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
}, [editor, annotations]);
```
```tsx theme={null}
import { renderComments } from '@veltdev/tiptap-velt-comments';
const commentElement = Velt.getCommentElement();
commentElement.getAllCommentAnnotations().subscribe((annotations) => {
if (editor && annotations) {
renderComments({
editor,
editorId: 'my-editor',
commentAnnotations: annotations,
});
}
});
```
# Custom Video Player Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/video-player-setup/custom-video-player-setup
Use this guide to add collaboration into your own custom video player.
```jsx theme={null}
```html theme={null}
#### B) Add the `Velt Comment Tool` component wherever you want your render the comment tool.
Note you can also provide your own button to this component.
```jsx theme={null}
{/* your custom button (optional) */}
```
```jsx theme={null}
```
**Disable Comment Tool**
You can disable the comment tool to temporarily or conditionally restrict comment creation while still allowing users to view existing comments.
```jsx theme={null}
{/* your custom button (optional) */}
```
```html theme={null}
```
#### C) Add the `Velt Reaction Tool` component wherever you want your render the reaction tool.
* Provide the video player ID on which you want the reactions to be added.
* Add an event handler to handle `onReactionToolClick` events.
```jsx theme={null}
onReactionToolClick()}>
```
```html theme={null}
```
```js theme={null}
const reactionToolTag = document.querySelector('velt-reaction-tool');
reactionToolTag.addEventListener('onReactionToolClick', (event) => {
console.log('reaction tool clicked', event.detail);
});
```
#### D) Place the `Velt Comment Player Timeline` component as a sibling to your video player.
* To show comment bubbles on your player seek bar, add the `Velt Comment Player Timeline` component as a sibling to your video player component.
* It will auto adjust to the same width as your video player.
Right now we assume you have a maximum of one `velt comment player timeline` component and one sibling video player component per `documentID`
Ensure that the parent container of `velt comment player timeline` doesnt have CSS position value as 'static'.
`videoPlayerId` is optional and helps support multiple players/timelines on the same page.
* If omitted, the timeline shows all comments for the current document (for the active version).
* If provided, the timeline shows only comments whose `location.videoPlayerId` matches the given `videoPlayerId`.
Tip: Use the same id on your player element and when setting `location.videoPlayerId` so the timeline can correctly associate comments with the player.
```jsx theme={null}
```
```jsx theme={null}
```
#### E) Add `id` to the video player or its parent element.
* If you don't have access to the raw `` player, you can add an `id` to the parent element of the video player.
```jsx theme={null}
```
```jsx theme={null}
```
#### F) Add the `Velt Comments Sidebar` component.
The Comments Sidebar displays all comments with search, filter, and navigation capabilities.
```jsx theme={null}
```jsx theme={null}
**Optional Properties:**
* **`embedMode`**: Embed the sidebar in your existing component instead of floating mode
```jsx theme={null}
{/* With optional properties */}
```html theme={null}
```
#### G) Add the `Velt Sidebar Button` component.
This will open or close the Comment Sidebar.
```jsx theme={null}
```
```jsx theme={null}
```
### Step 2: Set the total media length on the Velt Comment Player Timeline
You can pass an integer to `total media length` using props to represent the total number of frames or seconds in the video:
```jsx theme={null}
```jsx theme={null}
Alternatively, you can set this using API method call.
This is useful if you first need to grab the total frames from another method before setting it.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setTotalMediaLength(120);
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setTotalMediaLength(120);
```
### Step 3: Detect Comment Tool Activation and Set Media Location
* Detect when the user activates the comment tool by adding an event handler to the `onCommentModeChange` event.
* Pause your player and set a new `Location` in the Velt SDK.
* This ensures that the comments are tied to that particular media frame or timestamp.
* You can pass in a key value pair object that represents the current state of your player.
* If you are using the `Velt Comment Player Timeline` component, ensure to set the current media `frame` or `second` in the special key `currentMediaPosition`.
* Use the same id in `location.videoPlayerId` that you used in `VeltCommentPlayerTimeline`.
`currentMediaPosition` is a protected keyword that is used to arrange the comment bubbles on top of the video player timeline in the correct spot
```jsx theme={null}
onCommentModeChange(mode)} />
const onCommentModeChange = (mode) => {
// mode will be `true` if the user has activated the comment tool
// If the comment tool is active, pause the player and set the "location".
if (mode) {
// pause player
setLocation()
}
});
const setLocation = async (client) => {
// set currentMediaPosition property on a Location object to represent the current frame
let location = {
currentMediaPosition : 120,
videoPlayerId : "videoPlayerId"
}
//set the Location using the client
await client.setLocations([location])
}
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.onCommentModeChange().subscribe((mode) => {
// mode will be `true` if the user has activated the comment tool
// If the comment tool is active, pause the player and set the "location".
if (mode) {
// pause player
setLocation()
}
});
const setLocation = async (client) => {
// set currentMediaPosition property on a Location object to represent the current frame
let location = {
currentMediaPosition : 120,
videoPlayerId : "videoPlayerId"
}
//set the Location using the client
await Velt.setLocations([location])
}
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
### Step 4: Detect Reaction Tool Activation and Set Media Location
* Detect when the user activates the reaction tool by adding an event handler to the `onReactionToolClick` event.
* Pause your player and set a new `Location` in the Velt SDK.
* This ensures that the reactions are tied to that particular media frame or timestamp.
* You can pass in a key value pair object that represents the current state of your player.
If you are using the `Velt Comment Player Timeline` component, ensure to set the current rounded frame or second in the special key `currentMediaPosition`.
`currentMediaPosition` is a protected keyword that is used to arrange the comment bubbles on top of the video player timeline in the correct spot
```jsx theme={null}
onReactionToolClick()}>
const onReactionToolClick = () => {
// pause player
setLocation()
});
const setLocation = async () => {
// set currentMediaPosition property on a Location object to represent the current frame
let location = {
currentMediaPosition : 120,
videoPlayerId : "videoPlayerId"
}
//set the Location using the client
await client.setLocations([location])
}
```
```jsx theme={null}
### Step 5: Remove Velt Location when the player is played
Call `unsetLocationsIds()` so the video player can play without comments appearing in frames.
```jsx theme={null}
const clearLocation = async () => {
// Unset all locations, so the video player can play without comments appearing in frames
await client.unsetLocationsIds()
}
```
```jsx theme={null}
const clearLocation = async () => {
// Unset all locations, so the video player can play without comments appearing in frames
await Velt.unsetLocationsIds()
}
```
### Step 6: Navigate to the comment's location in the player from the Sidebar or Timeline
Add the `onCommentClick` event handler on the `Velt Comments Sidebar` & `Velt Comment Player Timeline` components you added earlier.
The event will give you back the `location` object that you had set on the comment.
Use this object to:
* update your player state
* update the SDK's `location` so the comments associated with that `location` are rendered.
#### A) Handle click on the `Velt Comments Sidebar`
```jsx theme={null}
onCommentClick(event)} />
const onCommentClick = async (event) => {
if (event) {
// Get the location object from the event.
const { location } = event;
if (location) {
// Get the media position where the comment was added.
const { currentMediaPosition } = location;
if (currentMediaPosition) {
// Pause the player.
// Seek to the given comment media position.
// Set the Velt Location to the clicked comment location.
await client.setLocations([location]);
}
}
}
}
```
```jsx theme={null}
const commentElement = document.querySelector('velt-comments-sidebar');
commentElement.addEventListener('onCommentClick', onCommentClick);
// event handler for when a comment is clicked on
const onCommentClick = (event) => {
if (event) {
// Get the location object from the event.
const { location } = event;
if (location) {
// Get the media position where the comment was added.
const { currentMediaPosition } = location;
if (currentMediaPosition) {
// Pause the player.
// Seek to the given comment media position.
// Set the Velt Location to the clicked comment location.
await client.setLocations([location]);
}
}
}
};
```
#### B) Handle click on the `Velt Comment Player Timeline`
```jsx theme={null}
onTimelineCommentClick(event)} />
const onTimelineCommentClick = async (event) => {
if (event) {
// Get the location object from the event.
const { location } = event;
if (location) {
// Get the media position where the comment was added.
const { currentMediaPosition } = location;
if (currentMediaPosition) {
// Pause the player.
// Seek to the given comment media position.
// Set the Velt Location to the clicked comment location.
await client.setLocations([location]);
}
}
}
}
```
```js theme={null}
const playerTimelineElement = document.querySelector('velt-comment-player-timeline');
if (playerTimelineElement) {
playerTimelineElement.addEventListener('onCommentClick', (event) => {
console.log("onCommentClick: ", event.detail);
});
}
```
The clicked Comment data will be in the following format:
| property | type | description |
| ----------------- | ------ | --------------------------------------------------------------- |
| `documentId` | string | The document ID where the comment was added |
| `location` | object | The location where the comment was added |
| `targetElementId` | string | The DOM ID of the target element on which the comment was added |
| `context` | Object | Any context data passed when the comment was added |
# Prebuilt Video Player Setup
Source: https://docs.velt.dev/async-collaboration/comments/setup/video-player-setup/video-player-setup
Use this guide if you want to set up a prebuilt video player from our SDK with collaborative features built in.
Import the `VeltVideoPlayer` component.
```jsx theme={null}
import { VeltVideoPlayer} from '@veltdev/react'
```
Add your video src URL to the `src` attribute of the `VeltVideoPlayer` component.
There are a few other properties:
* `darkMode` - boolean to enable dark mode
* `sync` - boolean to enable sync mode
```jsx theme={null}
Add your video src URL to the `src` attribute of the `` component.
There are a few other properties:
* `dark-mode` - boolean to enable dark mode
* `sync` - boolean to enable sync mode
```html theme={null}
```
```jsx React / Next.js theme={null}
import {
VeltVideoPlayer
} from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Video Player documentation
```
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-composer/customize-behavior
For type definitions, see [`VeltCommentComposerProps`](/api-reference/sdk/models/data-models#veltcommentcomposerprops).
## context
Pass custom context data to comments created via the Comment Composer. The provided context object will be added to the comment annotation, allowing you to associate additional metadata with comments.
```jsx theme={null}
```html theme={null}
## documentId
Set a specific document ID for comments created via the Comment Composer. This allows you to associate comments with a particular document.
```jsx theme={null}
```html theme={null}
## folderId
Set a specific folder ID for comments created via the Comment Composer. This allows you to associate comments with a particular folder.
```jsx theme={null}
```html theme={null}
## locationId
Set a specific location ID for comments created via the Comment Composer. This allows you to associate comments with a particular location.
```jsx theme={null}
```html theme={null}
## placeholder
Customize the input placeholder text in the comment composer. Overrides default placeholders.
```jsx theme={null}
```html theme={null}
## targetComposerElementId
Set a unique identifier for the composer to enable programmatic submission via the submitComment() method.
```jsx theme={null}
```html theme={null}
## clearComposer
Reset composer state including text, attachments, recordings, tagged users, assignments, and custom lists. Refer to [`clearComposer()`](/async-collaboration/comments/customize-behavior#clearcomposer) for more details.
## submitComment
Programmatically submit a comment from a composer. Refer to [`submitComment()`](/async-collaboration/comments/customize-behavior#submitcomment) for more details.
## getComposerData
Get the current state of the composer including text, attachments, recordings, tagged users, assignments, and custom lists. Refer to [`getComposerData()`](/async-collaboration/comments/customize-behavior#getcomposerdata) for more details.
## readOnly
Disable comment input at the component level. When set to `true`, the composer will be in read-only mode.
The component-level `readOnly` prop takes precedence over the global read-only setting when explicitly set.
```jsx theme={null}
```html theme={null}
# Comment Standalone Composer
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-composer/overview
The Comment Standalone Composer enables you to add comments anywhere in your application. It's designed to work seamlessly with other Velt components and APIs:
* [Comment Data APIs](/async-collaboration/comments/customize-behavior#getcommentannotations): Fetch and submit comment data.
* [Comment Thread](/async-collaboration/comments/standalone-components/comment-thread/overview): Render comment threads using fetched data.
* [Comment Pin](/async-collaboration/comments/standalone-components/comment-pin/overview): Display and position comment pins based on fetched data.
* [Comment Dialog Primitives](/ui-customization/features/async/comments/comment-dialog-primitives/overview): Use 115+ granular components for maximum customization flexibility.
By combining these components, you can create custom comment interfaces such as sidebars, overlays, popovers, or inline comments. This approach offers greater flexibility and control over your comment system's design and functionality.
# Setup
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-composer/setup
## Add Comment Composer Component
The Comment Composer component allows you to add a comment composer anywhere in your app. You can:
* Display it on a hotkey press
* Embed it in your custom sidebar
* Place it below an article
* Overlay it on an image
* and more...
```jsx theme={null}
```html theme={null}
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-pin/customize-behavior
## `commentPinClicked` Event
* Listen to when a comment pin is clicked.
* Use this to get information about which pin was clicked and implement custom actions like navigation, analytics tracking, or opening a custom comment dialog.
```jsx theme={null}
// Using Hook
const commentPinClickedEvent = useCommentEventCallback('commentPinClicked');
useEffect(() => {
if (commentPinClickedEvent) {
console.log('Comment pin clicked:', commentPinClickedEvent);
}
}, [commentPinClickedEvent]);
// Using API
const commentElement = client.getCommentElement();
commentElement.on('commentPinClicked').subscribe((eventData) => {
console.log('Comment pin clicked:', eventData);
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.on('commentPinClicked').subscribe((eventData) => {
console.log('Comment pin clicked:', eventData);
});
```
**Event Data:** [CommentPinClickedEvent](/api-reference/sdk/models/data-models#commentpinclickedevent)
# Comment Pin
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-pin/overview
The Comment Pin component allows you to manually set the position of Comment Annotations.
This feature is particularly useful for complex UIs where you need precise control over the placement of Comment Pins.
Implementing this feature involves:
**1. Adding comment:** You have two options for adding comments with custom positioning:
* **a. Velt-Managed Click Events:** Use the `onCommentAdd` method to incorporate custom metadata into the comment object. This metadata will be used later to position the Comment Pin. [Learn more](/async-collaboration/comments/customize-behavior#event-subscription#oncommentadd-event-data-schema)
* **b. Custom Click Event Handling:** Handle click events on your canvas and use the `addManualComment` method to create a comment with custom metadata. [Learn more](/async-collaboration/comments/customize-behavior#addmanualcomment)
**2. Retrieving comments data:** Use the `getAllCommentAnnotations` method to fetch all Comment Annotations with their associated custom metadata.
For React developers, we provide hooks for easier integration. [Learn more](/async-collaboration/comments/customize-behavior#getcommentannotations)
**3. Rendering comments Pins:**
Iterate through the retrieved annotations and render the Comment Pin component, using the custom metadata to set each pin's position.
# Setup
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-pin/setup
You have two options for adding comments with custom positioning metadata:
**Option A: Velt-Managed Click Events**
* Use the `onCommentAdd` prop of the VeltComments component to add custom metadata when a comment is added.
* You need to set the mandatory `commentType: 'manual'` property to the metadata object.
```jsx theme={null}
yourMethod(event)} />
const yourMethod = (event) => {
event?.addContext({ position: {x: 200, y: 100}, commentType: 'manual'});
}
```
```js theme={null}
const veltCommentsTag = document.querySelector('velt-comments');
veltCommentsTag?.addEventListener('onCommentAdd', (event) => {
console.log('*** onCommentAdd ***');
console.log(event.detail);
event.detail?.addContext({ position: {x: 200, y: 100}, commentType: 'manual'});
});
```
**Option B: Custom Click Event Handling**
* Handle click events on your canvas and use the `addManualComment` method to create a comment with custom metadata.
```jsx theme={null}
const context = {
position: {x: 200, y: 100},
};
const commentElement = useCommentUtils();
commentElement.addManualComment({ context });
```
```js theme={null}
const context = {
position: {x: 200, y: 100},
};
const commentElement = Velt.getCommentElement();
commentElement.addManualComment({ context: context});
```
Retrieve all `Comment Annotations` using the `useCommentAnnotations()` hook.
To learn more about the `useCommentAnnotations()` hook, [read here](/api-reference/sdk/api/react-hooks#usegetcommentannotations).
```jsx theme={null}
let commentAnnotations = useCommentAnnotations()
```
```js theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((commentAnnotations) => {
// console.log(commentAnnotations);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
Add the `Velt Comment Pin` component and pass in the `Comment Annotation Id`.
Now retrieve the `context` to retrieve the custom metadata you set earlier and use it to set the position of the `Comment Pin`.
```jsx theme={null}
let commentAnnotations = useCommentAnnotations()
return (
{
commentAnnotations.map((commentAnnotation) => {
return (
)
})
}
```js theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((commentAnnotations) => {
renderCommentAnnotations(commentAnnotations);
});
const commentsContainer = document.getElementById('comments-container');
function renderCommentAnnotations(commentAnnotations) {
commentAnnotations.forEach((commentAnnotation) => {
if (!document.getElementById(`comment-pin-container-${commentAnnotation.annotationId}`)) {
// Add Comment Pin if it doesn't exist
const { x, y } = commentAnnotation.context.position;
var commentPinContainer = document.createElement('div');
commentPinContainer.className = 'comment-pin-container';
commentPinContainer.id = `comment-pin-container-${commentAnnotation.annotationId}`;
commentPinContainer.style.left = x + 'px';
commentPinContainer.style.top = y + 'px';
commentPinContainer.innerHTML = `
```jsx React / Next.js theme={null}
import { VeltCommentPin, useCommentAnnotations } from '@veltdev/react';
export default function YourDocument() {
const yourMethod = (event) => {
event?.addContext({ position: {x: 200, y: 100}, commentType: 'manual'});
}
let commentAnnotations = useCommentAnnotations()
return (
yourMethod(event)} />
{
commentAnnotations.map((commentAnnotation) => {
return (
)
})
}
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-thread/customize-behavior
## 1. `onCommentClick` Callback
* When the user clicks on the comment thread, you can listen to it using this method.
* Example: Use this to fetch the context and make the necessary app state changes to navigate to the comment.
```jsx theme={null}
handleOnCommentClick(data)}
/>
```
```jsx theme={null}
## 2. Pass Comment Annotation Object
* You can pass a Comment Annotation object directly to render the comment thread
* When using annotations from other documents:
* Comments will be read-only
* Reactions and recordings will not be rendered
* This enables creating Kanban boards by fetching comment annotations from multiple documents using our REST APIs
```jsx theme={null}
```html theme={null}
# Standalone Comment Thread
Source: https://docs.velt.dev/async-collaboration/comments/standalone-components/comment-thread/overview
* You can use the Standalone Comment Thread component to build things such as:
* a kanban board
* your own version of the `Comments Sidebar` component
* This component does not add any additional functionality. It is just used to render existing comment data.
* This is a thin wrapper around the [Comment Dialog component](/ui-customization/features/async/comments/comment-dialog-components).
* Get the Comment Annotations data using the APIs.
* Use this component to render the Comment Annotations data.
* Retrieve all comment annotations data.
* [Learn more](/async-collaboration/comments/customize-behavior#getcommentannotations).
Using Hooks:
```jsx theme={null}
let commentAnnotations = useCommentAnnotations()
```
Using API:
```js theme={null}
const commentElement = client.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((commentAnnotations) => {
// console.log(commentAnnotations);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```js theme={null}
const commentElement = Velt.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((commentAnnotations) => {
// console.log(commentAnnotations);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
* Iterate over the `Comment Annotations` array and add the `Velt Comment Thread` component.
* Pass the `annotation Id` prop to set the specific Comment Thread data.
Here's an improved example:
```jsx theme={null}
let commentAnnotations = useCommentAnnotations()
return (
{commentAnnotations.map((x,i) => )}
)
```
```html theme={null}
```jsx React / Next.js theme={null}
import { VeltCommentThread, useCommentAnnotations } from '@veltdev/react';
export default function YourDocument() {
let commentAnnotations = useCommentAnnotations()
return (
{commentAnnotations.map((x,i) => )}
)
}
```
```js Other Frameworks theme={null}
const commentElement = client.getCommentElement();
let subscription = commentElement.getAllCommentAnnotations().subscribe((comments) => {
// If you are using pure html, inject
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/notifications/customize-behavior
# Configuration
#### setTabConfig
* Using this config, you can customize the name of the tabs or disable them altogether.
* By default, all the three tabs are enabled.
You can set it on Notifications Tool:
```jsx theme={null}
You can set it on Notifications Tool:
```jsx theme={null}
```js theme={null}
const tabConfig = {
"forYou": {
name: 'Custom For You',
enable: true,
},
"documents": {
name: 'Custom Document',
enable: false,
},
"all": {
name: 'Custom All',
enable: true,
},
};
// Set it using Notifications Tool
const notificationsTool = document.querySelector('velt-notifications-tool');
notificationsTool?.setAttribute("tab-config", JSON.stringify(tabConfig));
// Or, set it using Notifications Panel
const notificationsPanel = document.querySelector('velt-notifications-panel');
notificationsPanel?.setAttribute("tab-config", JSON.stringify(tabConfig));
```
**Using APIs:**
```jsx theme={null}
const notificationElement = Velt.getNotificationElement();
const tabConfig = {
"forYou": {
name: 'Custom For You',
enable: true,
},
"documents": {
name: 'Custom Document',
enable: false,
},
"all": {
name: 'Custom All',
enable: true,
},
};
notificationElement.setTabConfig(tabConfig);
```
#### considerAllNotifications
Controls the notification count and unread indicator for the notification panel. When enabled, the notification count and unread badge include items from all tabs; when disabled (default), they only include items from the “For You” tab.
Default: `false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### enableCurrentDocumentOnly
Programmatically filters notifications to show only those from the current document. By default it shows notifications for the 15 most recently active documents accessible to the current user in the current organization.
**Hooks:**
```jsx theme={null}
const notificationElement = useNotificationUtils();
useEffect(() => {
notificationElement.enableCurrentDocumentOnly();
notificationElement.disableCurrentDocumentOnly();
}, [notificationElement]);
```
**API:**
```jsx theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.enableCurrentDocumentOnly();
notificationElement.disableCurrentDocumentOnly();
```
```jsx theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.enableCurrentDocumentOnly();
notificationElement.disableCurrentDocumentOnly();
```
#### setMaxDays
Notifications older than the specified number of days will not be displayed.
Default: 15 days.
```jsx theme={null}
```jsx theme={null}
```jsx theme={null}
#### panelOpenMode
Notificaitons Panel opens in one of the following ways:
* `popover`: It opens as a popover on the Notification Tool.
* `sidebar`: It opens as a sidebar from the right edge of the screen.
Default: `popover`.
```jsx theme={null}
```jsx theme={null}
#### pageSize
Control initial notification load count.
```jsx theme={null}
```html theme={null}
#### enableReadNotificationsOnForYouTab
* You can control whether read notifications are displayed in the "For You" tab. By default, read notifications are removed from this tab.
* This feature allows you to customize the visibility of read notifications in the "For You" tab, providing more flexibility in how notifications are displayed to users.
Default: `false`.
Using Props:
```jsx theme={null}
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
```
Using API:
```html theme={null}
```
#### enableSelfNotifications
* By default notifications api and components exclude notifications where the current user is the action user.
* This feature allows you to enable self notifications.
Default: `false`.
**Using props:**
```jsx theme={null}
**Using attributes:**
```html theme={null}
# Data
#### getNotificationsData
* Get the notifications data for the current user.
- The returned data includes notifications from up to the number of days specified by [max days](#setmaxdays) configuration.
- "For You" tab: By default only the latest 50 notifications are fetched. This is done to reduce clutter and noise.
- "Document" and "All" tabs: By default, up to 15 notifications are fetched for each of the 15 most recently active documents accessible to the current user. This highlights the most relevant and recent activity.
* Params:
* query: Optional. [`GetNotificationsDataQuery`](/api-reference/sdk/models/data-models#getnotificationsdataquery)
* `type`: Filter for notification type: all, for you, or documents.
* `forYou`: returns notifications where the current user is involved.
* `all` / `documents`: returns all notifications from the documents the user has access to.
* Returns [`Notification[]`](/api-reference/sdk/models/data-models#notification)
**Using Hooks:**
```jsx theme={null}
// Without query
const notificationData = useNotificationsData();
// With query
const notificationsData = useNotificationsData({ type: 'forYou' });
useEffect(() => {
if (notificationsData) {
console.log(notificationsData);
}
}, [notificationsData]);
```
**Using API:**
```jsx theme={null}
const notificationElement = client.getNotificationElement();
// Without query
let subscription = notificationElement.getNotificationsData().subscribe((notifications) => {
console.log("Notifications: ", notifications)
});
// With query
let subscription = notificationElement.getNotificationsData({ type: 'forYou' }).subscribe((notifications) => {
console.log("Notifications: ", notifications)
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const notificationElement = Velt.getNotificationElement();
// Without query
let subscription = notificationElement.getNotificationsData().subscribe((notifications) => {
console.log("Notifications: ", notifications)
});
// With query
let subscription = notificationElement.getNotificationsData({ type: 'forYou' }).subscribe((notifications) => {
console.log("Notifications: ", notifications)
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
#### getUnreadNotificationsCount
* Retrieve the count of unread notifications, which includes a breakdown for different tabs.
* The 'Document' tab is not included in the response because it contains all the notifications present in the 'All' tab.
**Sample response:**
```javascript theme={null}
{
forYou: 4, // # of unread notifications in the "For You" tab
all: 5 // # of unread notifications in the "All" or "Document" tab
}
```
Using Hooks:
```jsx theme={null}
const unreadCount = useUnreadNotificationsCount();
useEffect(() => {
console.log('Unread Count', unreadCount);
}, [unreadCount]);
```
Using API:
```javascript theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.getUnreadNotificationsCount().subscribe((data) => {
console.log('Unread notifications count:', data);
});
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.getUnreadNotificationsCount().subscribe((data) => {
console.log('Unread notifications count:', data);
});
```
# Event Subscription
#### on
* Subscribe to Notification Events. Here is the list of events you can subscribe to and the event objects you will receive.
| Event Type | Description | Event Object |
| ----------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `settingsUpdated` | Triggered when the settings are updated by the user using UI or the API | [SettingsUpdatedEvent](/api-reference/sdk/models/data-models#settingsupdatedevent) |
```jsx theme={null}
// Hook
const settingsUpdatedEvent = useNotificationEventCallback('settingsUpdated')
useEffect(() => {
console.log('settingsUpdatedEvent', settingsUpdatedEvent)
}, [settingsUpdatedEvent])
// API Method
const notificationElement = useNotificationUtils();
notificationElement.on('settingsUpdated').subscribe((event) => {
console.log('settingsUpdatedEvent', event);
});
```
```js theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.on('settingsUpdated').subscribe((event) => {
console.log('settingsUpdatedEvent', event);
});
```
#### onNotificationClick
* The `onNotificationClick` event fires when a notification is clicked in the Notifications Panel.
* It returns a [`Notification`](/api-reference/sdk/models/data-models#notification) object with details about the clicked notification.
* Listen to this event via either the Notification Tool or the Notification Panel, but not both.
* Use this event to implement custom actions in response to notification clicks, such as navigating to a specific part of the app.
```jsx theme={null}
onNotificationClickEvent(notification)} />
onNotificationClickEvent(notification)} />
const onNotificationClickEvent = (notification) => {
console.log('onNotificationClick: ', notification);
}
```
```jsx theme={null}
const notificationsTool = document.querySelector('velt-notifications-tool');
notificationsTool?.addEventListener('onNotificationClick', (event) => {
console.log('onNotificationClick from Tool: ', event.detail);
});
const notificationsPanel = document.querySelector('velt-notifications-panel');
notificationsPanel?.addEventListener('onNotificationClick', (event) => {
console.log('onNotificationClick from Panel: ', event.detail);
});
```
# Actions
#### markNotificationAsReadById
* Mark a single notification as read using its notificationId.
* The notification will be marked as read in all tabs.
```javascript theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.markNotificationAsReadById("notificationId");
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.markNotificationAsReadById("notificationId");
```
#### openNotificationsPanel
* Programmatically open or close the notification panel using the provided APIs.
* This will not work if you have embedded the notification panel in your app.
```jsx theme={null}
const notificationElement = useNotificationUtils()
notificationElement.openNotificationsPanel()
notificationElement.closeNotificationsPanel()
```
```html theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.openNotificationsPanel();
notificationElement.closeNotificationsPanel();
```
#### setAllNotificationsAsRead
* Mark all notifications as read, either globally or for a specific tab.
* Using 'all' or 'document' as the `tabId` marks all notifications as read across all tabs (equivalent to calling `setAllNotificationsAsRead()` without arguments).
* Using 'for-you' as the `tabId` only marks notifications in the 'for-you' tab as read.
```javascript theme={null}
const notificationElement = client.getNotificationElement();
// Mark all notifications as read
notificationElement.setAllNotificationsAsRead();
// Mark all notifications as read for a specific tab
notificationElement.setAllNotificationsAsRead({ tabId: 'for-you' });
notificationElement.setAllNotificationsAsRead({ tabId: 'all' });
notificationElement.setAllNotificationsAsRead({ tabId: 'document' });
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
// Mark all notifications as read
notificationElement.setAllNotificationsAsRead();
// Mark all notifications as read for a specific tab
notificationElement.setAllNotificationsAsRead({ tabId: 'for-you' });
notificationElement.setAllNotificationsAsRead({ tabId: 'all' });
notificationElement.setAllNotificationsAsRead({ tabId: 'document' });
```
# Notification Settings
1. This feature currently only updates the settings for the current user in the current Velt document. If you are using multiple documents or folders, the settings will apply to the root document.
2. Make sure to first enable the settings feature in [Velt Console](https://console.velt.dev/dashboard/config/notification).
#### enableSettings
* Enable or disable the settings feature for notifications. This allows users to configure their notification preferences.
* Params: `none`
* Returns: `void`
**Using Props:**
```jsx theme={null}
// You can enable this on either the tool or the panel
**Using Props:**
```html theme={null}
#### enableSettingsAtOrganizationLevel
Enable organization-level notification settings. When enabled, settings apply to all documents in the organization instead of per-document.
**Params:** `none`
**Returns:** `void`
**Using Props:**
```jsx theme={null}
// Enable organization-level settings on the tool
**Using Props:**
```html theme={null}
```
**Using APIs:**
```js theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.enableSettingsAtOrganizationLevel(); // enable org-level settings
notificationElement.disableSettingsAtOrganizationLevel(); // disable org-level settings
```
#### settingsLayout
Control how notification settings are displayed. Two layout modes are available.
Default: `accordion`
**Type:** [`NotificationSettingsLayout`](/api-reference/sdk/models/data-models#notificationsettingslayout)
**Options:**
* `accordion`: Settings displayed in expandable accordion
* `dropdown`: Settings displayed in dropdown menu
```jsx theme={null}
```html theme={null}
#### setSettingsInitialConfig
* Set the initial default configuration for notification settings. This defines the available settings options and their default values.
* By default we have config added for inbox (in-app notifications) and email.
* You can extend this to add more channels where you intend to send notifications to your users. eg: slack, jira, asana, linear etc.
* If you do extend it to other custom channels, you will need to send the data to those channels yourself using our webhooks. [Learn more](/webhooks/basic)
* This config will automatically generate the settings UI for the user to configure their notification preferences.
* Params: [`NotificationInitialSettingsConfig[]`](/api-reference/sdk/models/data-models#notificationinitialsettingsconfig)
* Here is what the value types mean:
* `ALL`: Subscribes the user to all notifications whether or not the user is involved in the notification on the current document.
* `MINE`: Subscribes the user to notifications that are related to the current user on the current document.
* `NONE`: Subscribes the user to no notifications on this channel on the current document.
* Returns: `void`
Default:
```js theme={null}
[
{
name: 'Inbox',
id: 'inbox',
default: 'ALL',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
{
name: 'Email',
id: 'email',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
]
```
**Using Hook:**
```jsx theme={null}
const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
setSettingsInitialConfig([
{
name: 'Inbox',
id: 'inbox',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
{
name: 'Slack',
id: 'slack',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
{
name: 'Linear',
id: 'linear',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
]);
```
**Using API:**
```javascript theme={null}
const notificationElement = useNotificationUtils();
notificationElement.setSettingsInitialConfig([
{
name: 'Inbox',
id: 'inbox',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
{
name: 'Slack',
id: 'slack',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
{
name: 'Linear',
id: 'linear',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
]);
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.setSettingsInitialConfig([
{
name: 'Inbox',
id: 'inbox',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
{
name: 'Slack',
id: 'slack',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
{
name: 'Linear',
id: 'linear',
default: 'MINE',
enable: true,
values: [
{
name: 'All',
id: 'ALL',
},
{
name: 'Only Involved',
id: 'MINE',
},
{
name: 'None',
id: 'NONE',
}
]
},
]);
```
#### muteAllNotifications
* Mutes all notifications across all the channels for the current user in this current document.
* In case of multiple documents or folders, this will mute all notifications for the user in the root document.
* Params: `none`
* Returns: `void`
```javascript theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.muteAllNotifications();
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.muteAllNotifications();
```
#### setSettings
* Update notification settings configuration for the current user.
* Here you need to provide the id of the channel config and its value id.
* Params: [`NotificationSettingsConfig`](/api-reference/sdk/models/data-models#notificationsettingsconfig)
* Here is what the value types mean:
* `ALL`: Subscribes the user to all notifications whether or not the user is involved in the notification on the current document.
* `MINE`: Subscribes the user to notifications that are related to the current user on the current document.
* `NONE`: Subscribes the user to no notifications on this channel on the current document.
* Returns: `void`
**Using Hook:**
```jsx theme={null}
const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
setSettings({
'email': 'MINE',
'inbox': 'NONE',
'slack': 'ALL',
'linear': 'MINE'
});
```
**Using API:**
```javascript theme={null}
const notificationElement = useNotificationUtils();
notificationElement.setSettings({
'email': 'MINE',
'inbox': 'NONE',
'slack': 'ALL',
'linear': 'MINE'
});
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.setSettings({
'email': 'MINE',
'inbox': 'NONE',
'slack': 'ALL',
'linear': 'MINE'
});
```
#### getSettings
* Get the current notification settings configuration for the user on the current document.
* Params: `none`
* Returns: [`Observable`](/api-reference/sdk/models/data-models#notificationsettingsconfig)
**Using Hook:**
```jsx theme={null}
const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
// setSettingsInitialConfig will set the default settings for the notifications.
// setSettings will update the settings for the notifications in the server.
// settings will return the current settings for the notifications. Initially it will be null and will be updated when the settings are fetched.
```
**Using API:**
```jsx theme={null}
const notificationsElement = useNotificationUtils();
notificationsElement.getSettings().subscribe((settings) => {
console.log('current settings are', settings);
});
```
```javascript theme={null}
const notificationsElement = Velt.getNotificationElement();
notificationsElement.getSettings().subscribe((settings) => {
console.log('current settings are', settings);
});
```
# Notification Delivery
#### Batching and Delay Configuration
Configure a delay-and-batch pipeline for notification delivery. When enabled, notifications pass through a delay hold, a seen check, and optional batching before being delivered.
This configuration is set at the API Key level in the [Velt Console](https://console.velt.dev/dashboard/config/notification). It applies to all documents in the organization.
**Delivery pipeline:**
1. **Delay** — Holds the notification for `delaySeconds` before proceeding.
2. **Seen check** — If the recipient has already seen the triggering activity during the delay window, the notification is suppressed.
3. **Batch** — Collects additional activities within the batch window before flushing as a single digest.
4. **Deliver** — Sends the notification (or batched digest) to the recipient.
Webhooks and workflow triggers always fire immediately and are never subject to delay or batching.
**Document-level and user-level batching operate independently.** A notification can accumulate in both windows simultaneously; whichever window closes first (by time or `maxActivities`) triggers a flush for that scope.
# In-app Notifications
Source: https://docs.velt.dev/async-collaboration/notifications/overview
By default, the in-app notifications component is connected to Velt's Comments feature. All relevant comment notifications automatically show up here.
You can also add custom notifications from your app into Velt's notifications feature using REST APIs. [Learn more about adding notifications via REST API →](/api-reference/rest-apis/v2/notifications/add-notifications)
In-app notifications are only generated and fetched for documents the user has access to.
## Default Configuration
**Max count:**
* **"For You" tab**: By default, only the latest 50 notifications are fetched. This is done to reduce clutter and noise.
* **"Document" and "All" tabs**: By default, up to 15 notifications are fetched for each of the 15 most recently active documents accessible to the current user. This highlights the most relevant and recent activity.
**Max days:** By default, notifications older than 15 days will not be fetched. This is configurable.
## Components
There are two components associated with the In-app Notifications feature:
* **Velt Notifications Tool**: This opens the Notifications Panel.
* **Velt Notifications Panel**: This shows all the Notifications grouped in categories.
* Go to the [Notifications section](https://console.velt.dev/dashboard/config/notification) in the Configurations section of the Velt Console and enable Notifications.
Notifications will not work if you do not enable this first.
* Place the `Velt Notifications Tool` component wherever you want the Notifications button to appear.
```jsx theme={null}
```
```jsx theme={null}
```
* By default, the Velt Notifications Panel is automatically added or removed when you use the `Velt Notifications Tool`.
* However, if you want to create a dedicated page or dedicated section for Notifications, you can embed the Velt Notifications Panel component directly there.
```jsx theme={null}
```
```jsx theme={null}
```
* By default, the user notification settings are disabled.
* You need to first enable this feature in the [Velt Console](https://console.velt.dev/dashboard/config/notification).
* Then enable settings on the notifications tool or panel in the UI. [Learn more](/async-collaboration/notifications/customize-behavior#enablesettings)
* You can then:
* Configure default settings with `setSettingsInitialConfig()` API and extend it to add more channels (eg: slack, jira, asana, linear etc.) where you intend to send notifications to your users. [Learn more](/async-collaboration/notifications/customize-behavior#setsettingsinitialconfig)
* Update settings programmatically with `setSettings()` API. [Learn more](/async-collaboration/notifications/customize-behavior#setsettings)
* Get current settings with `getSettings()` API. [Learn more](/async-collaboration/notifications/customize-behavior#getsettings)
* Subscribe to settings updates with `settingsUpdated` event. [Learn more](/async-collaboration/notifications/customize-behavior#on)
This feature currently only updates the settings for the current user in the current Velt document. If you are using multiple documents or folders, the settings will apply to the root document.
**Using Props:**
```jsx theme={null}
// You can enable this on either the tool or the panel
**Using Props:**
```html theme={null}
* Opt in to a delay-and-batch pipeline that holds notifications, suppresses delivery if the recipient has already seen the activity, and groups notifications into digests before sending.
* Configure Notification Service in the [Velt Console](https://console.velt.dev/dashboard/config/notification) under API Key notification settings. [Learn more](/async-collaboration/notifications/customize-behavior#batching-and-delay-configuration)
```jsx React / Next.js theme={null}
import { VeltNotificationsTool } from '@veltdev/react';
function YourComponent() {
return (
)
}
```
```html HTML theme={null}
```
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/reactions/customize-behavior
## setCustomReactions
* Use this to set custom reactions emojis.
```jsx theme={null}
const customReactions = {
"URL_EMOJI_ID": {
"url": "https://em-content.zobj.net/source/apple/391/fire_1f525.png"
},
"URL_EMOJI_ID_2": {
"iconUrl": "EMOJI_URL"
},
"TEXT_EMOJI_ID": {
"emoji": "🤣" // emoji as a text
}
};
```jsx theme={null}
const reactionElement = Velt.getReactionElement();
const customReactions = {
"URL_EMOJI_ID": {
"url": "https://em-content.zobj.net/source/apple/391/fire_1f525.png"
},
"URL_EMOJI_ID_2": {
"iconUrl": "EMOJI_URL"
},
"TEXT_EMOJI_ID": {
"emoji": "🤣" // emoji as a text
}
};
reactionElement.setCustomReactions(customReactions);
```
# Inline Reactions
Source: https://docs.velt.dev/async-collaboration/reactions/overview
This allows users to add emoji reactions to specific parts of your UI (eg: posts, images etc). This is great for quick emotional responses or feedback.
Add `Velt Inline Reactions Section` component to your app to enable Inline Reactions.
Import the `VeltInlineReactionsSection` component.
```js theme={null}
import { VeltInlineReactionsSection } from '@veltdev/react';
```
* Create an element to hold your Inline Reactions component, such as a `div` or `section`.
* Add a unique element `id` to it.
```jsx theme={null}
```
* Add `VeltInlineReactionsSection` component inside your container.
* Add `targetReactionElementId` property to the Velt Inline Reactions component. This needs to match the id you set to the container. This binds the Inline Reactions component with the desired container.
```jsx theme={null}
```
* Create an element to hold your Inline Reactions component, such as a `div` or `section`.
* Add a unique element `id` to it.
```html theme={null}
```
* Add `velt-inline-reactions-section` component inside your container.
* Add `target-reaction-element-id` property to the Velt Inline Reactions component. This needs to match the id you set to the container. This binds the Inline Reactions component with the desired container.
```jsx theme={null}
```
```jsx React / Next.js theme={null}
import { VeltInlineReactionsSection } from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
```
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/recorder/customize-behavior
# AI
#### recordingTranscription
* Controls whether to enable AI transcription for recordings.
* If this is disabled, then the recording will not be sent to LLMs for transcription.
* You can either use the props or the API method to enable/disable this feature.
Default: `enabled`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### summary
Controls whether to display a summary transcript of the recording. When enabled, an AI-generated summary of the recording's content will be shown.
Default: `true`
```jsx theme={null}
```
```jsx theme={null}
# Recording Configuration
#### setMaxLength
* Sets the maximum duration for recordings in seconds.
* You can either use props on components or API methods to configure this feature.
* Default: No limit
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### enablePictureInPicture
* Enables Picture-in-Picture (PiP) mode for screen recordings when camera is enabled.
* This allows users to continue recording while multitasking, improving workflow efficiency for tutorial creation and documentation.
Picture-in-Picture is only supported in Chrome browsers and only works for screen recordings when the camera is active. This feature is disabled by default.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### disablePictureInPicture
* Disables Picture-in-Picture (PiP) mode for screen recordings.
* This prevents users from using the PiP functionality during recording sessions.
Picture-in-Picture is only supported in Chrome browsers and only works for screen recordings when the camera is active. This feature is disabled by default.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### enableRecordingMic
* Turn on user microphone on the recorder control panel.
**Using API:**
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.enableRecordingMic(); // Enables the microphone.
recorderElement.disableRecordingMic(); // Disables the microphone.
```
**Using API:**
```jsx theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.enableRecordingMic(); // Enables the microphone.
recorderElement.disableRecordingMic(); // Disables the microphone.
```
#### setRecordingQualityConstraints
* Defines quality constraints (e.g., resolution, frame rate) for the raw media input from the user's screen, camera, or microphone, applied before recording begins.
* Higher quality constraints will result in higher upload, download and processing times.
* **Params:** [RecorderQualityConstraints](/api-reference/sdk/models/data-models#recorderqualityconstraints)
* **Returns:** `void`
* **Default:**
```js theme={null}
{
'safari': {
audio: {
sampleRate: 48000,
echoCancellation: true,
noiseSuppression: true,
autoGainControl: true
},
video: {
width: { min: 640, ideal: 1280, max: 1280 },
height: { min: 360, ideal: 720, max: 720 },
frameRate: { min: 15, ideal: 20, max: 30 },
aspectRatio: { ideal: 1.777777778 }
}
},
'other': {
audio: {
sampleRate: 48000,
echoCancellation: true,
noiseSuppression: true,
autoGainControl: true
},
video: {
width: { min: 640, ideal: 1280, max: 1280 },
height: { min: 360, ideal: 720, max: 720 },
frameRate: { min: 15, ideal: 20, max: 30 },
aspectRatio: { ideal: 1.777777778 }
}
}
}
```
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.setRecordingQualityConstraints({
'other': {
'video': {
width: { exact: 3024 },
height: { exact: 1542 },
frameRate: { exact: 20 },
}
}
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.setRecordingQualityConstraints({
'other': {
'video': {
width: { exact: 3024 },
height: { exact: 1542 },
frameRate: { exact: 20 },
}
}
});
```
#### setRecordingEncodingOptions
* Controls the output quality and size of the video or audio file you save after it's been captured.
* Higher quality options will result in higher upload, download and processing times.
* We automatically select the best file format (MIME type) based on the browser and device compatibility. Here is the preferred order in which this is selected:
* `video/mp4;codecs=h264,aac`
* `video/mp4`
* `audio/mp4`
* `video/webm;codecs=vp9,opus`
* `video/webm;codecs=vp8,opus`
* `video/webm;codecs=h264,opus`
* `video/webm`
* **Params:** [RecorderEncodingOptions](/api-reference/sdk/models/data-models#recorderencodingoptions)
* **Returns:** `void`
* **Default:**
```js theme={null}
{
'safari': {
videoBitsPerSecond: 2500000,
audioBitsPerSecond: 128000
},
'other': {
videoBitsPerSecond: 1000000,
audioBitsPerSecond: 128000
}
}
```
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.setRecordingEncodingOptions({
'other': {
videoBitsPerSecond: 2000000,
audioBitsPerSecond: 128000
}
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.setRecordingEncodingOptions({
'other': {
videoBitsPerSecond: 2000000,
audioBitsPerSecond: 128000
}
});
```
# Permissions
#### requestScreenPermission
* Requests screen capture permissions from the user. This is useful for enabling screen preview functionality in the Recording Preview Dialog.
* **Returns:** `Promise`
```jsx theme={null}
const recorderElement = useRecorderUtils();
await recorderElement.requestScreenPermission();
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
await recorderElement.requestScreenPermission();
```
#### askDevicePermission
* Programmatically requests audio and video permissions from the user. This is useful for creating a custom onboarding flow for device permissions.
* **Params:** `RecorderDevicePermissionOptions`
* **Returns:** `Promise`
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.askDevicePermission({
audio: true,
video: true
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.askDevicePermission({
audio: true,
video: true
});
```
# Data
#### deleteRecordings
* Deletes recordings by their recorder IDs.
* **Params:** [RecorderRequestQuery](/api-reference/sdk/models/data-models#recorderrequestquery) (optional)
* **Returns:** [`Promise`](/api-reference/sdk/models/data-models#deleterecordingsresponse)
**Using API:**
```ts theme={null}
const recorderElement = useRecorderUtils();
await recorderElement.deleteRecordings({
recorderIds: ['RECORDER_ID_1']
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
await recorderElement.deleteRecordings({
recorderIds: ['RECORDER_ID_1']
});
```
#### downloadLatestVideo
* Downloads the latest version of a recording.
* **Params:** `recorderId: string`
* **Returns:** `Promise`
```js theme={null}
const recorderElement = client.getRecorderElement();
await recorderElement.downloadLatestVideo('RECORDER_ID');
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
await recorderElement.downloadLatestVideo('RECORDER_ID');
```
#### fetchRecordings
* Fetches all recordings from either the current document or specified recorder IDs.
* **Params:** [RecorderRequestQuery](/api-reference/sdk/models/data-models#recorderrequestquery) (optional)
* **Returns:** [`Promise`](/api-reference/sdk/models/data-models#getrecordingsresponse)
```jsx theme={null}
const recorderElement = useRecorderUtils();
// Fetch all recordings in the current document
const recorderData = await recorderElement.fetchRecordings();
// Fetch recordings for a specific recorder ID
const recorderData = await recorderElement.fetchRecordings({
recorderIds: ['RECORDER_ID']
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
// Fetch all recordings in the current document
const recorderData = await recorderElement.fetchRecordings();
// Fetch recordings for a specific recorder ID
const recorderData = await recorderElement.fetchRecordings({
recorderIds: ['RECORDER_ID']
});
```
#### getRecordings
* Subscribe to all recording data from either the current document or specified recorder IDs.
* **Params:** [RecorderRequestQuery](/api-reference/sdk/models/data-models#recorderrequestquery) (optional)
* **Returns:** [`Observable`](/api-reference/sdk/models/data-models#getrecordingsresponse)
**Using Hook:**
```jsx theme={null}
const recordings = useRecordings();
useEffect(() => {
console.log('recordings', recordings);
}, [recordings]);
```
**Using API:**
```jsx theme={null}
const recorderElement = useRecorderUtils();
// Subscribe to all recordings in the current document
recorderElement.getRecordings().subscribe((data) => {
console.log('recordings', data);
});
// Subscribe to recordings with specific recorder IDs
recorderElement.getRecordings({
recorderIds: ['RECORDER_ID']
}).subscribe((data) => {
console.log('recordings', data);
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
// Subscribe to all recordings in the current document
recorderElement.getRecordings().subscribe((data) => {
console.log('recordings', data);
});
// Subscribe to recordings with specific recorder IDs
recorderElement.getRecordings({
recorderIds: ['RECORDER_ID']
}).subscribe((data) => {
console.log('recordings', data);
});
```
# Event Subscription
#### on
* Subscribe to Recorder Events. Here is the list of events you can subscribe to and the event objects you will receive.
| Event Type | Description | Event Object |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `transcriptionDone` | Triggered when a transcription is generated and ready | [TranscriptionDoneEvent](/api-reference/sdk/models/data-models#transcriptiondoneevent) |
| `recordingDone` | Triggered when a recording is completed | [RecordingDoneEvent](/api-reference/sdk/models/data-models#recordingdoneevent) |
| `deleteRecording` | Triggered when a recording is deleted | [RecordingDeleteEvent](/api-reference/sdk/models/data-models#recordingdeleteevent) |
| `recordingEditDone` | Triggered when the "Done" button is clicked in the recording editor. Fires after edits are saved, or immediately if no edits were made. | [RecordingEditDoneEvent](/api-reference/sdk/models/data-models#recordingeditdoneevent) |
| `recordingStarted` | Triggered when the recording starts. | [RecordingStartedEvent](/api-reference/sdk/models/data-models#recordingstartedevent) |
| `recordingPaused` | Triggered when the recording is paused. | [RecordingPausedEvent](/api-reference/sdk/models/data-models#recordingpausedevent) |
| `recordingResumed` | Triggered when the recording is resumed after being paused. | [RecordingResumedEvent](/api-reference/sdk/models/data-models#recordingresumedevent) |
| `recordingCancelled` | Triggered when the recording is cancelled. | [RecordingCancelledEvent](/api-reference/sdk/models/data-models#recordingcancelledevent) |
| `recordingStopped` | Triggered when the recording is stopped. | [RecordingStoppedEvent](/api-reference/sdk/models/data-models#recordingstoppedevent) |
| `recordingSaveInitiated` | Triggered when a recording saved is initiated | [RecordingSaveInitiatedEvent](/api-reference/sdk/models/data-models#recordingsaveinitiatedevent) |
| `error` | Triggered when an error occurs. eg: `editFailed`, `recordingFailed`, `transcriptionFailed` | [RecordingErrorEvent](/api-reference/sdk/models/data-models#recordingerrorevent) |
```jsx theme={null}
// Hook
const recorderEventCallbackData = useRecorderEventCallback('transcriptionDone');
useEffect(() => {
if (recorderEventCallbackData) {
// Handle recorder action callback event response
}
}, [recorderEventCallbackData]);
// API Method
const recorderElement = client.getRecorderElement();
recorderElement.on('transcriptionDone').subscribe((event) => {
// Handle the event response
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.on('transcriptionDone').subscribe((event) => {
// Handle the event response
});
```
# Editor
#### autoOpenVideoEditor
* Controls whether to open the video editor automatically when the recording is done.
* Available in `Velt Recorder Control Panel` component.
Default: `false`
```jsx theme={null}
```html theme={null}
#### retakeOnVideoEditor
* Controls whether to enable the retake button on video editor. This will take the user back to the control panel to start a new recording.
Default: `false`
**Using Props (use any one of the following):**
```jsx theme={null}
**Using Attributes: (use any one of the following)**
```html theme={null}
#### enableOnboardingTooltip
* Controls whether to enable the onboarding tooltip on video editor.
Default: `false`
**Using APIs:**
```jsx theme={null}
const recorderElement = useRecorderUtils();
// Enable/disable onboarding tooltip
recorderElement.enableOnboardingTooltip();
recorderElement.disableOnboardingTooltip();
```
**Using APIs:**
```jsx theme={null}
const recorderElement = Velt.getRecorderElement();
// Enable/disable onboarding tooltip
recorderElement.enableOnboardingTooltip();
recorderElement.disableOnboardingTooltip();
```
#### videoEditor
* Controls whether to enable the video editor for the `Velt Recorder Player`.
* Works for Video and Screen Recordings.
* Available in `Velt Recorder Notes`, `Velt Recorder Player` and `Velt Recorder Control Panel` components. You could use any of these.
Default: `false`
**Using Props:**
```jsx theme={null}
// Use any one of these.
```
**Using API:**
```jsx theme={null}
const recorderElement = client.getRecorderElement();
recorderElement.enableVideoEditor();
recorderElement.disableVideoEditor();
```
**Using Props:**
```html theme={null}
#### videoEditorTimelinePreview
* Controls whether to display image snapshots of frames in the video editor timeline.
* This helps users quickly navigate to specific scenes without scrubbing through the entire video.
Default: `false`
The timeline preview only works when both `videoEditorTimelinePreview` and `videoEditor` are set to `true`.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
# UI/UX
#### openPictureInPicture
* Opens the Picture-in-Picture window during an active recording session.
* This allows programmatic control to open the PiP window for improved multitasking during recording.
Picture-in-Picture is only supported in Chrome browsers and only works for screen recordings when the camera is active. This feature is disabled by default.
**Using API:**
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.openPictureInPicture();
```
**Using API:**
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.openPictureInPicture();
```
#### exitPictureInPicture
* Closes the Picture-in-Picture window during an active recording session.
* This allows programmatic control to exit the PiP window and return to normal recording view.
Picture-in-Picture is only supported in Chrome browsers and only works for screen recordings when the camera is active. This feature is disabled by default.
**Using API:**
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.exitPictureInPicture();
```
**Using API:**
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.exitPictureInPicture();
```
#### buttonLabel
Sets a custom label for the `Velt Recorder Tool`.
```js theme={null}
```js theme={null}
#### playVideoInFullScreen
* Controls whether to play the recorded video in fullscreen mode.
* You can use this prop on any of the following components:
* `Velt Recorder Notes`
* `Velt Recorder Control Panel`
* `Velt Recorder Player`
Default: `false`
```jsx theme={null}
// Change behaviour globally
```html theme={null}
#### playbackOnPreviewClick
Control playback behavior on preview click. Enable or disable the click-to-play/pause functionality on recording previews.
Default: `true`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### recordingCountdown
* Controls whether to display a countdown timer before a recording starts.
* You can either use the props or the API method to enable/disable this feature.
Default: `enabled`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
#### settingsEmbedded
* Controls whether to embed the settings in the `Velt Recorder Control Panel` component.
* Available in `Velt Recorder Control Panel` component.
* Please use this together with the Control Panel Wireframes so that you can move the settings panel in a different part of the control panel UI.
Default: `false`
```jsx theme={null}
```html theme={null}
#### mode
The `Velt Recorder Control Panel` has two display modes:
* `floating`: Shows a preview in the bottom left corner of the page, regardless of component placement
* `thread`: Displays the component at its placed location in the DOM
Default: `floating`
```js theme={null}
```html theme={null}
#### type
Sets the recording mode for the `Velt Recorder Tool`.
Available modes:
* `all` - Records audio, video and screen
* `audio` - Records audio only
* `video` - Records video only
* `screen` - Records screen only
Default: `audio`
```js theme={null}
```js theme={null}
# Legacy Methods
#### onRecordedData
The `onRecordedData` callback is triggered when a recording is completed.
* Callback returns [RecorderData](/api-reference/sdk/models/data-models#recorderdata) object.
**Using Props:**
```jsx theme={null}
const onRecordedData = (recorderAddEvent) => {
console.log(recorderAddEvent);
}
return (
**Using Event Listener:**
```js theme={null}
const recorderControlPanel = document.querySelector('velt-recorder-control-panel');
recorderControlPanel?.addEventListener('onRecordedData', (s) => {
console.log('onRecordedData', s.detail);
});
```
# Recorder
Source: https://docs.velt.dev/async-collaboration/recorder/overview
The Recorder allows your users to create audio, screen, and video recordings.
The Velt Recorder consists of 4 key components:
* **Velt Recorder Notes**: Enables pinning recordings to specific locations on the screen
* **Velt Recorder Tool**: A button to initiate recordings
* **Velt Recorder Control Panel**: Controls for managing active recordings (start/stop/pause)
* **Velt Recorder Player**: Plays back recordings using their unique ID
* **Velt Video Editor**: An embeddable component for viewing and editing video annotations.
# Setup
Source: https://docs.velt.dev/async-collaboration/recorder/setup
* Add the `Velt Recorder Tool` component wherever you want the recorder button to appear.
* Set the `type` attribute of the `Velt Recorder Tool` component to one of the following:
* `all`
* `audio`
* `video`
* `screen`
```js theme={null}
```
```html theme={null}
```
* Add the `Velt Recorder Control Panel` component wherever you want the control panel to appear.
* When a user clicks on the `Velt Recorder Tool` button, the `Velt Recorder Control Panel` component will show the recording preview with options to save, pause, or delete the recording.
* Set the `mode` attribute on the `VeltRecorderControlPanel` component to either `floating` (default) or `thread`.
To learn more about `floating` or `thread` mode [read here](/async-collaboration/recorder/customize-behavior#mode).
```js theme={null}
```
```html theme={null}
```
* After a user has finished recording, you will receive the recorded data in an event callback.
* Add the `Velt Recorder Player` component with the `recorderId` from the event callback.
* It displays the recorded data with controls such as pause, play, edit and delete.
```js theme={null}
const recorderAddEvent = useRecorderAddHandler();
const [recorderId, setRecorderId] = useState(null);
useEffect(() => {
setRecorderId(recorderAddEvent.id);
}, [recorderAddEvent]);
{recorderId &&
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.onRecordedData().subscribe((recorderAddEvent) => {
setRecorderId(recorderAddEvent.id);
});
```
```html theme={null}
```
* Recording Editor is currently in beta and is not enabled by default.
* It is only available for video and screen recordings.
* It has the following default keyboard shortcuts:
* `s`: Split the video at the selected frame.
* `d`, `delete`, or `backspace`: Delete the selected video section.
* `space`: Toggle video play/pause.
```js theme={null}
const recorderElement = client.getRecorderElement();
recorderElement.enableVideoEditor();
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.enableVideoEditor();
```
* Embed the `Velt Video Editor` standalone component directly into your application.
* It can be used to view and edit video recordings.
* You can initialize the editor with a video from a URL, a Blob, or by using a `recorderId`.
```jsx theme={null}
```html theme={null}
```js React / Next.js theme={null}
import { VeltRecorderTool, VeltRecorderControlPanel, VeltRecorderPlayer } from '@veltdev/react'
function TaskInputBox() {
return (
)
}
```
```html HTML theme={null}
```
# Customize Behavior
Source: https://docs.velt.dev/async-collaboration/view-analytics/customize-behavior
## getUniqueViewsByUser
* Get unique views by user.
* You can optionally filter by location.
Props:
```jsx theme={null}
Props:
```html theme={null}
```
Using Hooks:
```jsx theme={null}
const viewsByUser = useUniqueViewsByUser();
const viewsByUserForLocation = useUniqueViewsByUser('your-location-id');
```
API Methods:
```jsx theme={null}
const viewsElement = client.getViewsElement();
// to get unique views by user
let subscription = viewsElement.getUniqueViewsByUser().subscribe((viewsByUser) => {
console.log('Unique views by user: ', viewsByUser);
});
// you can optionally pass client-location-id to get unique views by users for that location
let subscription = viewsElement.getUniqueViewsByUser('your-location-id').subscribe((viewsByUser) => {
console.log('Unique views by date for location: ', viewsByUser);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
## getUniqueViewsByDate
* Get unique views by date.
* You can optionally filter by location.
Props:
```jsx theme={null}
Props:
```html theme={null}
```
Using Hooks:
```jsx theme={null}
const viewsByDate = useUniqueViewsByDate();
const viewsByDateForLocation = useUniqueViewsByDate('your-location-id');
```
API Methods:
```jsx theme={null}
const viewsElement = client.getViewsElement();
// to get unique views by date
let subscription = viewsElement.getUniqueViewsByDate().subscribe((viewsByDate) => {
console.log('Unique views by date: ', viewsByDate);
});
// you can optionally pass client-location-id to get unique views by date for that location
let subscription = viewsElement.getUniqueViewsByDate('your-location-id').subscribe((viewsByDate) => {
console.log('Unique views by date for location: ', viewsByDate);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
# View Analytics
Source: https://docs.velt.dev/async-collaboration/view-analytics/overview
Import the `VeltViewAnalytics` component
```jsx theme={null}
import { VeltViewAnalytics } from '@veltdev/react';
```
Place the `VeltViewAnalytics` component wherever you want the View Analytics component to appear.
```jsx theme={null}
```
Place the `` component wherever you want the View Analytics component to appear.
```jsx theme={null}
```
```js React / Next.js theme={null}
import { VeltViewAnalytics } from '@veltdev/react';
function YourComponent() {
return (
)
}
```
```html HTML theme={null}
Collaboration App
```
# Python
Source: https://docs.velt.dev/backend-sdks/python
Use the Velt Python SDK to simplify self-hosting backend implementation. Pass your DB and storage configs and let the SDK handle the data operations.
# Overview
The [Velt Python SDK](https://pypi.org/project/velt-py) simplifies self-hosting backend implementation by **90%**. Instead of writing custom database queries and storage logic, you:
1. Pass your DB and storage configs to the SDK
2. Pass the raw request object directly to SDK methods
3. Return the resulting response object straight to the client
No manual processing required.
# Installation
```bash theme={null}
pip install velt-py
```
# Quick Start
## 1. Initialize the SDK
```python theme={null}
from velt_py import VeltSDK
# Initialize with database and AWS config
config = {
'database': {
# Option 1: Connection string (recommended for MongoDB Atlas)
'connection_string': 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',
# Option 2: Individual components
# 'host': 'localhost:27017',
# 'username': 'your_username',
# 'password': 'your_password',
# 'auth_database': 'admin',
# 'database_name': 'velt-db'
},
# Optional: AWS S3 config for attachments
'aws': {
'bucket_name': 'your-bucket',
'region': 'us-east-1',
'access_key_id': 'YOUR_ACCESS_KEY',
'secret_access_key': 'YOUR_SECRET_KEY'
},
# Optional: Custom collection names
'collections': {
'comments': 'comment_annotations',
'reactions': 'reaction_annotations',
'attachments': 'attachments',
'users': 'users'
},
# Optional: Velt API credentials (for token generation)
'apiKey': 'YOUR_VELT_API_KEY',
'authToken': 'YOUR_VELT_AUTH_TOKEN'
}
sdk = VeltSDK.initialize(config)
```
## 2. Create API Endpoints
The SDK provides methods that accept the raw request from the frontend and return the properly formatted response.
### Comments
```python theme={null}
from velt_py import (
GetCommentResolverRequest,
SaveCommentResolverRequest,
DeleteCommentResolverRequest
)
# GET Comments
def get_comments(request):
data = request.json
comment_request = GetCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.getComments(comment_request)
return result # Returns { data, success, statusCode }
# SAVE Comments
def save_comments(request):
data = request.json
save_request = SaveCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.saveComments(save_request)
return result
# DELETE Comment
def delete_comment(request):
data = request.json
delete_request = DeleteCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.deleteComment(delete_request)
return result
```
### Reactions
```python theme={null}
from velt_py import (
GetReactionResolverRequest,
SaveReactionResolverRequest,
DeleteReactionResolverRequest
)
# GET Reactions
def get_reactions(request):
data = request.json
reaction_request = GetReactionResolverRequest.from_dict(data)
result = sdk.selfHosting.reactions.getReactions(reaction_request)
return result
# SAVE Reactions
def save_reactions(request):
data = request.json
save_request = SaveReactionResolverRequest.from_dict(data)
result = sdk.selfHosting.reactions.saveReactions(save_request)
return result
# DELETE Reaction
def delete_reaction(request):
data = request.json
delete_request = DeleteReactionResolverRequest.from_dict(data)
result = sdk.selfHosting.reactions.deleteReaction(delete_request)
return result
```
### Users
```python theme={null}
from velt_py import GetUserResolverRequest
# GET Users
def get_users(request):
data = request.json
user_request = GetUserResolverRequest.from_dict(data)
result = sdk.selfHosting.users.getUsers(user_request)
return result
```
### Attachments
```python theme={null}
import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
from velt_py import SaveAttachmentResolverRequest, DeleteAttachmentResolverRequest
from .velt_sdk import get_velt_sdk
@csrf_exempt
@require_http_methods(["POST"])
def save_attachment(request):
"""Save attachment - accepts multipart/form-data with file and request JSON"""
try:
file = request.FILES.get('file')
request_json_str = request.POST.get('request')
if not file or not request_json_str:
return JsonResponse({
'success': False,
'error': 'File and request JSON are required',
'errorCode': 'INVALID_INPUT',
'statusCode': 400
}, status=400)
request_data = json.loads(request_json_str)
save_request = SaveAttachmentResolverRequest.from_dict(request_data)
sdk = get_velt_sdk()
result = sdk.selfHosting.attachments.saveAttachment(
save_request,
file_data=file.read(),
file_name=file.name,
mime_type=file.content_type
)
return JsonResponse(result, status=result.get('statusCode', 200))
except Exception as e:
return JsonResponse({
'success': False,
'error': str(e),
'errorCode': 'INTERNAL_ERROR',
'statusCode': 500
}, status=500)
@csrf_exempt
@require_http_methods(["POST"])
def delete_attachment(request):
"""Delete attachment - SDK handles S3 deletion internally"""
try:
data = json.loads(request.body)
delete_request = DeleteAttachmentResolverRequest.from_dict(data)
sdk = get_velt_sdk()
result = sdk.selfHosting.attachments.deleteAttachment(delete_request)
return JsonResponse(result, status=result.get('statusCode', 200))
except Exception as e:
return JsonResponse({
'success': False,
'error': str(e),
'errorCode': 'INTERNAL_ERROR',
'statusCode': 500
}, status=500)
```
```python theme={null}
import json
from flask import request, jsonify
from velt_py import SaveAttachmentResolverRequest, DeleteAttachmentResolverRequest
@app.route('/api/velt/attachments/save', methods=['POST'])
def save_attachment():
try:
file = request.files.get('file')
request_json = request.form.get('request')
if not file or not request_json:
return jsonify({
'success': False,
'error': 'File and request JSON are required',
'errorCode': 'INVALID_INPUT',
'statusCode': 400
}), 400
request_data = json.loads(request_json)
save_request = SaveAttachmentResolverRequest.from_dict(request_data)
result = sdk.selfHosting.attachments.saveAttachment(
save_request,
file_data=file.read(),
file_name=file.filename,
mime_type=file.content_type
)
return jsonify(result), result.get('statusCode', 200)
except Exception as e:
return jsonify({'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}), 500
@app.route('/api/velt/attachments/delete', methods=['POST'])
def delete_attachment():
try:
data = request.json
delete_request = DeleteAttachmentResolverRequest.from_dict(data)
result = sdk.selfHosting.attachments.deleteAttachment(delete_request)
return jsonify(result), result.get('statusCode', 200)
except Exception as e:
return jsonify({'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}), 500
```
```python theme={null}
import json
from fastapi import Request, UploadFile, File, Form
from fastapi.responses import JSONResponse
from velt_py import SaveAttachmentResolverRequest, DeleteAttachmentResolverRequest
@app.post('/api/velt/attachments/save')
async def save_attachment(file: UploadFile = File(...), request: str = Form(...)):
try:
request_data = json.loads(request)
save_request = SaveAttachmentResolverRequest.from_dict(request_data)
file_bytes = await file.read()
result = sdk.selfHosting.attachments.saveAttachment(
save_request,
file_data=file_bytes,
file_name=file.filename,
mime_type=file.content_type
)
return JSONResponse(content=result, status_code=result.get('statusCode', 200))
except Exception as e:
return JSONResponse(content={'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}, status_code=500)
@app.post('/api/velt/attachments/delete')
async def delete_attachment(request: Request):
try:
data = await request.json()
delete_request = DeleteAttachmentResolverRequest.from_dict(data)
result = sdk.selfHosting.attachments.deleteAttachment(delete_request)
return JSONResponse(content=result, status_code=result.get('statusCode', 200))
except Exception as e:
return JSONResponse(content={'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}, status_code=500)
```
# Framework Examples
**SDK Initialization (velt\_sdk.py)**
```python theme={null}
from django.conf import settings
from velt_py import VeltSDK
_velt_sdk = None
def get_velt_sdk():
global _velt_sdk
if _velt_sdk is None:
_velt_sdk = VeltSDK.initialize(settings.VELT_SDK_CONFIG)
return _velt_sdk
```
**API Endpoints (views.py)**
```python theme={null}
import json
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.views.decorators.http import require_http_methods
from velt_py import GetCommentResolverRequest, SaveCommentResolverRequest, DeleteCommentResolverRequest
from .velt_sdk import get_velt_sdk
@csrf_exempt
@require_http_methods(["POST"])
def get_comments(request):
try:
data = json.loads(request.body)
comment_request = GetCommentResolverRequest.from_dict(data)
sdk = get_velt_sdk()
result = sdk.selfHosting.comments.getComments(comment_request)
return JsonResponse(result, status=result.get('statusCode', 200))
except json.JSONDecodeError:
return JsonResponse({
'success': False,
'error': 'Invalid JSON',
'errorCode': 'INVALID_INPUT',
'statusCode': 400
}, status=400)
except Exception as e:
return JsonResponse({
'success': False,
'error': str(e),
'errorCode': 'INTERNAL_ERROR',
'statusCode': 500
}, status=500)
@csrf_exempt
@require_http_methods(["POST"])
def save_comments(request):
try:
data = json.loads(request.body)
save_request = SaveCommentResolverRequest.from_dict(data)
sdk = get_velt_sdk()
result = sdk.selfHosting.comments.saveComments(save_request)
return JsonResponse(result, status=result.get('statusCode', 200))
except json.JSONDecodeError:
return JsonResponse({
'success': False,
'error': 'Invalid JSON',
'errorCode': 'INVALID_INPUT',
'statusCode': 400
}, status=400)
except Exception as e:
return JsonResponse({
'success': False,
'error': str(e),
'errorCode': 'INTERNAL_ERROR',
'statusCode': 500
}, status=500)
@csrf_exempt
@require_http_methods(["POST"])
def delete_comment(request):
try:
data = json.loads(request.body)
delete_request = DeleteCommentResolverRequest.from_dict(data)
sdk = get_velt_sdk()
result = sdk.selfHosting.comments.deleteComment(delete_request)
return JsonResponse(result, status=result.get('statusCode', 200))
except json.JSONDecodeError:
return JsonResponse({
'success': False,
'error': 'Invalid JSON',
'errorCode': 'INVALID_INPUT',
'statusCode': 400
}, status=400)
except Exception as e:
return JsonResponse({
'success': False,
'error': str(e),
'errorCode': 'INTERNAL_ERROR',
'statusCode': 500
}, status=500)
```
**Configuration (settings.py)**
```python theme={null}
import os
VELT_SDK_CONFIG = {
'database': {
'connection_string': os.environ.get('VELT_MONGODB_CONNECTION_STRING'),
# Or use individual components:
# 'host': os.environ.get('VELT_MONGODB_HOST'),
# 'username': os.environ.get('VELT_MONGODB_USERNAME'),
# 'password': os.environ.get('VELT_MONGODB_PASSWORD'),
# 'auth_database': os.environ.get('VELT_MONGODB_AUTH_DB'),
# 'database_name': os.environ.get('VELT_MONGODB_DATABASE'),
},
'user_schema': {
'userId': 'userId',
'name': 'name',
'photoUrl': 'photoUrl',
'email': 'email',
'color': 'color',
'textColor': 'textColor',
'isAdmin': 'isAdmin',
'initial': 'initial'
},
'collections': {
'comments': 'comment_annotations',
'reactions': 'reaction_annotations',
'attachments': 'attachments',
'users': 'users'
},
'aws': {
'bucket_name': os.environ.get('AWS_S3_BUCKET'),
'region': os.environ.get('AWS_REGION', 'us-east-1'),
'access_key_id': os.environ.get('AWS_ACCESS_KEY_ID'),
'secret_access_key': os.environ.get('AWS_SECRET_ACCESS_KEY'),
},
'apiKey': os.environ.get('VELT_API_KEY'),
'authToken': os.environ.get('VELT_AUTH_TOKEN')
}
```
```python theme={null}
from flask import Flask, request, jsonify
from velt_py import VeltSDK, GetCommentResolverRequest, SaveCommentResolverRequest, DeleteCommentResolverRequest
app = Flask(__name__)
# Initialize SDK
sdk = VeltSDK.initialize({
'database': {
'connection_string': 'mongodb+srv://...'
}
})
@app.route('/api/velt/comments/get', methods=['POST'])
def get_comments():
try:
data = request.json
comment_request = GetCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.getComments(comment_request)
return jsonify(result), result.get('statusCode', 200)
except Exception as e:
return jsonify({'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}), 500
@app.route('/api/velt/comments/save', methods=['POST'])
def save_comments():
try:
data = request.json
save_request = SaveCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.saveComments(save_request)
return jsonify(result), result.get('statusCode', 200)
except Exception as e:
return jsonify({'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}), 500
@app.route('/api/velt/comments/delete', methods=['POST'])
def delete_comment():
try:
data = request.json
delete_request = DeleteCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.deleteComment(delete_request)
return jsonify(result), result.get('statusCode', 200)
except Exception as e:
return jsonify({'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}), 500
```
```python theme={null}
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from velt_py import VeltSDK, GetCommentResolverRequest, SaveCommentResolverRequest, DeleteCommentResolverRequest
app = FastAPI()
# Initialize SDK
sdk = VeltSDK.initialize({
'database': {
'connection_string': 'mongodb+srv://...'
}
})
@app.post('/api/velt/comments/get')
async def get_comments(request: Request):
try:
data = await request.json()
comment_request = GetCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.getComments(comment_request)
return JSONResponse(content=result, status_code=result.get('statusCode', 200))
except Exception as e:
return JSONResponse(content={'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}, status_code=500)
@app.post('/api/velt/comments/save')
async def save_comments(request: Request):
try:
data = await request.json()
save_request = SaveCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.saveComments(save_request)
return JSONResponse(content=result, status_code=result.get('statusCode', 200))
except Exception as e:
return JSONResponse(content={'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}, status_code=500)
@app.post('/api/velt/comments/delete')
async def delete_comment(request: Request):
try:
data = await request.json()
delete_request = DeleteCommentResolverRequest.from_dict(data)
result = sdk.selfHosting.comments.deleteComment(delete_request)
return JSONResponse(content=result, status_code=result.get('statusCode', 200))
except Exception as e:
return JSONResponse(content={'success': False, 'error': str(e), 'errorCode': 'INTERNAL_ERROR', 'statusCode': 500}, status_code=500)
```
# Configuration
Configure MongoDB connection for storing comments, reactions, and user data.
```python theme={null}
config = {
'database': {
# Option 1: Connection string (recommended for MongoDB Atlas)
'connection_string': 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',
# Option 2: Individual components (for local MongoDB or custom setup)
# 'host': 'localhost:27017',
# 'username': 'your_username',
# 'password': 'your_password',
# 'auth_database': 'admin',
# 'database_name': 'velt-db'
}
}
```
Configure AWS S3 for storing file attachments.
```python theme={null}
config = {
'aws': {
'bucket_name': 'your-bucket-name',
'region': 'us-east-1',
'access_key_id': 'YOUR_AWS_ACCESS_KEY',
'secret_access_key': 'YOUR_AWS_SECRET_KEY'
}
}
```
Customize collection names for storing Velt data.
```python theme={null}
config = {
'collections': {
'comments': 'comment_annotations', # Default: 'comment_annotations'
'reactions': 'reaction_annotations', # Default: 'reaction_annotations'
'attachments': 'attachments', # Default: 'attachments'
'users': 'users' # Default: 'users'
}
}
```
Map your user schema fields to Velt's expected fields if your database uses different field names.
```python theme={null}
config = {
'user_schema': {
'userId': 'userId', # Your field name for user ID
'name': 'name', # Your field name for display name
'photoUrl': 'photoUrl', # Your field name for avatar URL
'email': 'email', # Your field name for email
'color': 'color', # Your field name for user color
'textColor': 'textColor', # Your field name for text color
'isAdmin': 'isAdmin', # Your field name for admin flag
'initial': 'initial' # Your field name for user initial
}
}
```
Full configuration with database, AWS, collections, and user schema.
```python theme={null}
from velt_py import VeltSDK
config = {
'database': {
'connection_string': 'mongodb+srv://user:pass@cluster.mongodb.net/velt-db',
},
'aws': {
'bucket_name': 'your-bucket-name',
'region': 'us-east-1',
'access_key_id': 'YOUR_AWS_ACCESS_KEY',
'secret_access_key': 'YOUR_AWS_SECRET_KEY'
},
'collections': {
'comments': 'comment_annotations',
'reactions': 'reaction_annotations',
'attachments': 'attachments',
'users': 'users'
},
'user_schema': {
'userId': 'userId',
'name': 'name',
'photoUrl': 'photoUrl',
'email': 'email',
'color': 'color',
'textColor': 'textColor',
'isAdmin': 'isAdmin',
'initial': 'initial'
},
'apiKey': 'YOUR_VELT_API_KEY',
'authToken': 'YOUR_VELT_AUTH_TOKEN'
}
sdk = VeltSDK.initialize(config)
```
# Response Format
All SDK methods return a consistent response format:
```python theme={null}
# Success response
{
'success': True,
'statusCode': 200,
'data': { ... } # The requested data
}
# Error response
{
'success': False,
'statusCode': 400, # or 500 for server errors
'error': 'Error message',
'errorCode': 'ERROR_CODE' # e.g., 'INVALID_INPUT', 'INTERNAL_ERROR'
}
```
Common error codes:
* `INVALID_INPUT`: Request data is malformed or missing required fields
* `INTERNAL_ERROR`: Server-side error during processing
* `NOT_FOUND`: Requested resource was not found
# API Reference
### Comments
| Method | Description |
| ------------------------------------------------- | ------------------------------ |
| `sdk.selfHosting.comments.getComments(request)` | Fetch comments from database |
| `sdk.selfHosting.comments.saveComments(request)` | Save comments to database |
| `sdk.selfHosting.comments.deleteComment(request)` | Delete a comment from database |
### Reactions
| Method | Description |
| --------------------------------------------------- | ------------------------------- |
| `sdk.selfHosting.reactions.getReactions(request)` | Fetch reactions from database |
| `sdk.selfHosting.reactions.saveReactions(request)` | Save reactions to database |
| `sdk.selfHosting.reactions.deleteReaction(request)` | Delete a reaction from database |
### Users
| Method | Description |
| ----------------------------------------- | ------------------------- |
| `sdk.selfHosting.users.getUsers(request)` | Fetch users from database |
### Attachments
| Method | Description |
| -------------------------------------------------------------------------------------- | ----------------------------------------- |
| `sdk.selfHosting.attachments.saveAttachment(request, file_data, file_name, mime_type)` | Upload attachment to S3 and save metadata |
| `sdk.selfHosting.attachments.deleteAttachment(request)` | Delete attachment from S3 and database |
# Request Types
Import the request types from `velt_py`:
```python theme={null}
from velt_py import (
# Comments
GetCommentResolverRequest,
SaveCommentResolverRequest,
DeleteCommentResolverRequest,
# Reactions
GetReactionResolverRequest,
SaveReactionResolverRequest,
DeleteReactionResolverRequest,
# Users
GetUserResolverRequest,
# Attachments
SaveAttachmentResolverRequest,
DeleteAttachmentResolverRequest
)
```
# Resources
* [Velt-Py PyPI Package](https://pypi.org/project/velt-py)
* [Self-Host Data Documentation](/self-host-data/overview)
# Advanced Setup
Source: https://docs.velt.dev/get-started/advanced
Optional advanced configuration options for Velt SDK
Explore optional advanced configuration options to enhance your Velt implementation with locations, contacts, and initialization state detection.
## Locations
Users logged into the same **Document** ID can see each other's `Presence`, `Cursors`, `Comments` etc.
However, if you want to add another layer of categorization to organize users together, you can use **Location**.
If a **Document** is like a house, a **Location** is like a room within the house.
To learn more about `Locations`, check out its dedicated section [here](/key-concepts/overview#locations).
## Contacts
When you reply to a comment, you can `@mention` other teammates that are added to a `User's Contacts List`.
To learn more about creating a `User's Contacts List`, [read here](/key-concepts/overview#contact-list).
## JWT Authentication Tokens
For enhanced security, you can use JWT tokens to authenticate users instead of passing user data directly in the client-side code. This provides an additional layer of security by verifying user identity on the server side.
After authentication, retrieve the current user object anytime using [`getCurrentUser()`](/api-reference/sdk/api/api-methods#getcurrentuser) or [`useCurrentUser()`](/api-reference/sdk/api/react-hooks#usecurrentuser).
Access control roles (Editor/Viewer): You can assign a user's role per resource (organization, folder, document) in the token permissions or via backend access APIs. Editors can create/edit collaboration data (e.g., comments); Viewers are read-only. See [Access Control](/key-concepts/overview#access-control), [Generate Token](/api-reference/rest-apis/v2/auth/generate-token), [Add Permissions](/api-reference/rest-apis/v2/auth/add-permissions), and [Add/Update Users](/api-reference/rest-apis/v2/users/add-users).
**Critical JWT Token Requirements:**
* JWT tokens must be generated server-side using your auth token from the Velt Console
* Never expose JWT tokens or auth tokens in client-side code
* Tokens expire after 48 hours and need to be refreshed
* Include the JWT token in the `authToken` field when calling `identify()`
### Step 1: Enable JWT Tokens in Console
First, enable JWT tokens in your Velt Console:
1. Go to [console.velt.dev](https://console.velt.dev/dashboard/config/general)
2. Enable the toggle for `Require JWT Token` (listed at the bottom of the page)
JWT tokens won't work unless you enable this setting in your console.
### Step 2: Generate Auth Token
You need an auth token to generate JWT tokens. You can generate this from the **Auth Token** section in your Velt Console dashboard.
Store auth tokens securely on your server-side environment and never expose them in client-side code.
Auth tokens are long-lived and should be rotated periodically for security best practices.
### Step 3: Create Server Endpoint for JWT Token Generation
Create a server endpoint that generates and serves JWT tokens to your client.
See our [generate\_token API call](/api-reference/rest-apis/v2/auth/generate-token) for more information.
```js Node.js Server Endpoint expandable lines theme={null}
const express = require('express');
const app = express();
const PORT = 8080;
// Your credentials from Velt Console
const VELT_API_KEY = "YOUR_VELT_API_KEY";
const VELT_AUTH_TOKEN = "your-generated-auth-token-from-console";
async function generateVeltJWTToken(userId, config = {}) {
const url = "https://api.velt.dev/v2/auth/generate_token";
const body = {
userId: userId,
userProperties: {
name: config.name,
email: config.email,
isAdmin: config.isAdmin || false
},
permissions: config.organizationId
? {
resources: [
{ type: "organization", id: config.organizationId }
]
}
: undefined
};
try {
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-velt-api-key": VELT_API_KEY,
"x-velt-auth-token": VELT_AUTH_TOKEN
},
body: JSON.stringify(body),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
return data?.result?.data?.token;
} catch (error) {
console.error("Error generating JWT token:", error);
throw error;
}
}
// Endpoint to generate JWT tokens
app.get('/generate-velt-jwt-token', async (req, res) => {
try {
const { userId, organizationId, name, email, isAdmin } = req.query;
const token = await generateVeltJWTToken(userId, {
organizationId,
name,
email,
isAdmin: isAdmin === 'true'
});
res.json({ token });
} catch (error) {
res.status(500).json({ error: 'Failed to generate token' });
}
});
app.listen(PORT, () => {
console.log(`JWT Server listening on port ${PORT}`);
});
```
```python Python Server Endpoint expandable lines theme={null}
from flask import Flask, request, jsonify
import requests
app = Flask(__name__)
# Your credentials from Velt Console
VELT_AUTH_TOKEN = "your-generated-auth-token-from-console"
VELT_API_KEY = "YOUR_VELT_API_KEY"
def generate_velt_jwt_token(user_id, config=None):
url = "https://api.velt.dev/v2/auth/generate_token"
if config is None:
config = {}
body = {
"userId": user_id,
"userProperties": {
"name": config.get("name"),
"email": config.get("email"),
"isAdmin": config.get("isAdmin", False)
}
}
if config.get("organizationId"):
body["permissions"] = {
"resources": [
{"type": "organization", "id": config.get("organizationId")}
]
}
try:
response = requests.post(url, json=body, headers={
"Content-Type": "application/json",
"x-velt-api-key": VELT_API_KEY,
"x-velt-auth-token": VELT_AUTH_TOKEN
})
response.raise_for_status()
data = response.json()
return data.get("result", {}).get("data", {}).get("token")
except Exception as error:
print(f"Error generating JWT token: {error}")
raise error
@app.route('/generate-velt-jwt-token', methods=['GET'])
def get_jwt_token():
try:
user_id = request.args.get('userId')
organization_id = request.args.get('organizationId')
name = request.args.get('name')
email = request.args.get('email')
is_admin = request.args.get('isAdmin') == 'true'
token = generate_velt_jwt_token(user_id, {
"organizationId": organization_id,
"name": name,
"email": email,
"isAdmin": is_admin
})
return jsonify({"token": token})
except Exception as error:
return jsonify({"error": "Failed to generate token"}), 500
if __name__ == '__main__':
app.run(port=8080)
```
```ruby Ruby Server Endpoint expandable lines theme={null}
require 'sinatra'
require 'net/http'
require 'json'
# Your credentials from Velt Console
VELT_AUTH_TOKEN = "your-generated-auth-token-from-console"
VELT_API_KEY = "YOUR_VELT_API_KEY"
def generate_velt_jwt_token(user_id, config = {})
url = URI("https://api.velt.dev/v2/auth/generate_token")
body = {
userId: user_id,
userProperties: {
name: config[:name],
email: config[:email],
isAdmin: config[:isAdmin] || false
}
}
if config[:organizationId]
body[:permissions] = {
resources: [
{ type: 'organization', id: config[:organizationId] }
]
}
end
begin
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["x-velt-api-key"] = VELT_API_KEY
request["x-velt-auth-token"] = VELT_AUTH_TOKEN
request.body = body.to_json
response = http.request(request)
unless response.is_a?(Net::HTTPSuccess)
raise "HTTP error! status: #{response.code}"
end
data = JSON.parse(response.body)
data.dig("result", "data", "token")
rescue => error
puts "Error generating JWT token: #{error}"
raise error
end
end
get '/generate-velt-jwt-token' do
begin
user_id = params['userId']
organization_id = params['organizationId']
name = params['name']
email = params['email']
is_admin = params['isAdmin'] == 'true'
token = generate_velt_jwt_token(user_id, {
organizationId: organization_id,
name: name,
email: email,
isAdmin: is_admin
})
{ token: token }.to_json
rescue => error
status 500
{ error: "Failed to generate token" }.to_json
end
end
```
```php PHP Server Endpoint expandable lines theme={null}
$userId,
"userProperties" => [
"name" => $config["name"] ?? null,
"email" => $config["email"] ?? null,
"isAdmin" => $config["isAdmin"] ?? false
]
];
if (!empty($config["organizationId"])) {
$body["permissions"] = [
"resources" => [
["type" => "organization", "id" => $config["organizationId"]]
]
];
}
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'x-velt-api-key: ' . $VELT_API_KEY,
'x-velt-auth-token: ' . $VELT_AUTH_TOKEN
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (curl_errno($ch) || $httpCode !== 200) {
throw new Exception("HTTP error! status: {$httpCode}");
}
curl_close($ch);
$data = json_decode($response, true);
return $data["result"]["data"]["token"] ?? null;
}
if ($_SERVER['REQUEST_METHOD'] === 'GET' && $_SERVER['REQUEST_URI'] === '/generate-velt-jwt-token') {
try {
$userId = $_GET['userId'] ?? null;
$organizationId = $_GET['organizationId'] ?? null;
$name = $_GET['name'] ?? null;
$email = $_GET['email'] ?? null;
$isAdmin = ($_GET['isAdmin'] ?? 'false') === 'true';
$token = generateVeltJWTToken($userId, [
"organizationId" => $organizationId,
"name" => $name,
"email" => $email,
"isAdmin" => $isAdmin
]);
header('Content-Type: application/json');
echo json_encode(["token" => $token]);
} catch (Exception $error) {
http_response_code(500);
echo json_encode(["error" => "Failed to generate token"]);
}
}
?>
```
## Token Refresh
JWT tokens expire after 48 hours from generation. Handle token expiration by subscribing to the error event and refreshing tokens when needed:
If you configured an Auth Provider on `VeltProvider`, token refresh is handled automatically. If you authenticate using the identify() method instead, you must listen for `token_expired` and re-authenticate with a fresh token as shown below.
```jsx React Token Refresh theme={null}
import { useVeltEventCallback } from "@veltdev/react";
export default function AuthComponent() {
const errorEvent = useVeltEventCallback('error');
useEffect(() => {
if (errorEvent?.code === "token_expired") {
// Generate new JWT token from your server
fetch("/api/auth/refresh-token")
.then(res => res.json())
.then(data => {
// Re-authenticate with new token
useIdentify(user, { authToken: data.newToken });
});
}
}, [errorEvent]);
return Authentication Component
;
}
```
```js Other Frameworks Token Refresh theme={null}
// Subscribe to error events to handle token expiration
client.on('error').subscribe((error) => {
if (error?.code === "token_expired") {
// Generate new JWT token from your server
fetch("/api/auth/refresh-token")
.then(res => res.json())
.then(data => {
// Re-authenticate with new token
client.identify(user, { authToken: data.newToken });
});
}
});
```
**Security Benefits of JWT Tokens:**
* Server-side validation of user identity
* Protection against client-side data manipulation
* Secure user authentication without exposing sensitive data
* Token expiration for enhanced security
## Error Handling in Authentication
By default, authentication methods like `identify()` and `setVeltAuthProvider()` return `null` when authentication fails. You can configure these methods to throw errors instead by setting `throwError: true` in the options parameter.
When `throwError` is enabled, failed authentication attempts will throw an error that you can catch and handle, providing more control over error handling in your application.
```jsx theme={null}
import { useIdentify, useVeltClient } from '@veltdev/react';
export default function AuthComponent({ user }) {
const { client } = useVeltClient();
// Using Promise-based approach
const handleAuthWithPromise = () => {
client.identify(user, {
throwError: true, // Throws error if authentication fails
}).then((authenticatedUser) => {
// User is authenticated
console.log('Authenticated:', authenticatedUser);
}).catch((err) => {
// Handle authentication error
console.error('Authentication failed:', err);
});
};
// Using async/await approach
const handleAuthWithAsync = async () => {
try {
const authenticatedUser = await client.identify(user, {
throwError: true, // Throws error if authentication fails
});
// User is authenticated
console.log('Authenticated:', authenticatedUser);
} catch (err) {
// Handle authentication error
console.error('Authentication failed:', err);
}
};
// Using setVeltAuthProvider
useEffect(() => {
if (client) {
client.setVeltAuthProvider({
user,
options: {
throwError: true, // Throws error if authentication fails
},
onError: (err) => {
// Handle authentication error
console.error('Auth provider error:', err);
}
});
}
}, [client]);
return Authentication Component
;
}
```
```html theme={null}
```
* Default value: `false` (returns `null` on authentication failure)
* Set to `true` to receive errors that can be caught with `.catch()` or `try/catch` blocks
* Useful for implementing custom error handling and recovery flows
## Velt Client
Access the core Velt client instance to call SDK APIs and subscribe to core events.
* [API reference →](/api-reference/sdk/api/api-methods#get-velt-client)
### Event Subscriptions
| Event | Description | Event Object |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `initUpdate` | Initialization lifecycle updates (documents/locations set/unset, user init) | [InitUpdateEvent](/api-reference/sdk/models/data-models#initupdateevent) |
| `userUpdate` | Fired when the Velt user changes (login, logout, or update) | [UserUpdateEvent](/api-reference/sdk/models/data-models#userupdateevent) |
| `documentInit` | Document initialization status changes | [DocumentInitEvent](/api-reference/sdk/models/data-models#documentinitevent) |
| `error` | Error events (e.g., token\_expired) | [ErrorEvent](/api-reference/sdk/models/data-models#errorevent) |
| `veltButtonClick` | Fired when a Velt Button is clicked | [VeltButtonClickEvent](/api-reference/sdk/models/data-models#veltbuttonclickevent) |
| `permissionProvider` | Permission Provider events for access requests, results, and errors | [PermissionProviderEvent](/api-reference/sdk/models/data-models#permissionproviderevent) |
| `dataProvider` | Data Provider events for debugging get, save, and delete operations. Includes [UserResolverEvent](/api-reference/sdk/models/data-models#userresolverevent), [CommentResolverEvent](/api-reference/sdk/models/data-models#commentresolverevent), [AttachmentResolverEvent](/api-reference/sdk/models/data-models#attachmentresolverevent), [ReactionResolverEvent](/api-reference/sdk/models/data-models#reactionresolverevent) | [DataProviderEvent](/api-reference/sdk/models/data-models#dataproviderevent) |
```jsx theme={null}
import { useEffect } from 'react';
import { useVeltClient } from '@veltdev/react';
export default function CoreEventsListener() {
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
// Listen to initialization updates
const initSub = client.on('initUpdate').subscribe((event) => {
console.log('Init update:', event);
});
// Listen to token lifecycle errors (e.g., token_expired)
const errorSub = client.on('error').subscribe((error) => {
console.log('Velt error:', error);
});
return () => {
initSub?.unsubscribe();
errorSub?.unsubscribe();
};
}, [client]);
return null;
}
```
```js theme={null}
async function loadVelt() {
await Velt.init('YOUR_VELT_API_KEY');
const initSub = Velt.on('initUpdate').subscribe((event) => {
console.log('Init update:', event);
});
const errorSub = Velt.on('error').subscribe((error) => {
console.log('Velt error:', error);
});
// When done, unsubscribe
// initSub?.unsubscribe();
// errorSub?.unsubscribe();
}
```
* Use the React hook `useVeltClient()` inside components rendered under `VeltProvider`.
* The client is available after initialization. In HTML/vanilla, call `Velt.init()` first.
* Always unsubscribe from event subscriptions to avoid memory leaks.
### getVeltInitState()
This returns true when both the Velt User and Document are initialized.
```jsx React / Next.js with Hooks theme={null}
import { useVeltInitState } from '@veltdev/react';
export default function MyComponent() {
const veltInitState = useVeltInitState();
useEffect(() => {
console.log('Velt Init State:', veltInitState);
if (veltInitState) {
// Velt state is initialized, so user can perform any action here
}
}, [veltInitState]);
return (
{/* Your component content */}
);
}
```
```jsx React / Next.js (Non-hooks) theme={null}
import { useVeltClient } from '@veltdev/react';
export default function MyComponent() {
const { client } = useVeltClient();
useEffect(() => {
if (client) {
const subscription = client.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
console.log('Velt Init State:', veltInitState);
});
return () => subscription?.unsubscribe();
}
}, [client]);
return (
{/* Your component content */}
);
}
```
```jsx Angular Initialization State theme={null}
import { Component, OnInit, OnDestroy } from '@angular/core';
import { initVelt } from '@veltdev/client';
@Component({
selector: 'app-root',
template: `
`
})
export class AppComponent implements OnInit, OnDestroy {
client: any;
subscription: any;
async ngOnInit() {
this.client = await initVelt('YOUR_VELT_API_KEY');
this.subscription = this.client.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
console.log('Velt Init State:', veltInitState);
});
}
ngOnDestroy() {
this.subscription?.unsubscribe();
}
}
```
```js Vue.js Initialization State theme={null}
import { initVelt } from '@veltdev/client';
export default {
name: 'App',
data() {
return {
client: null,
subscription: null
}
},
async mounted() {
this.client = await initVelt('YOUR_VELT_API_KEY');
this.subscription = this.client.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
console.log('Velt Init State:', veltInitState);
});
},
beforeUnmount() {
this.subscription?.unsubscribe();
}
}
```
```js HTML Initialization State theme={null}
// Subscribe to initialization state
let subscription = Velt.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
console.log('Velt Init State:', veltInitState);
});
// To unsubscribe
subscription?.unsubscribe();
```
```html Complete HTML with Init State theme={null}
My App
My Collaborative App
### fetchDebugInfo()
* Use this method to retrieve a one-time snapshot of essential debugging information about your Velt integration. This includes details like SDK version, API key, user, organizationId, documentId, folderId, version, and locations.
* You can also access this diagnostic information through [Velt’s Chrome DevTools extension](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl).
* Params: None
* Returns: `Promise<`[`VeltDebugInfo`](/api-reference/sdk/models/data-models#veltdebuginfo)`>`
```jsx theme={null}
const { client } = useVeltClient();
const handleFetchDebugInfo = async () => {
const debugInfo = await client.fetchDebugInfo();
console.log('Debug Info:', debugInfo);
console.log('SDK Version:', debugInfo.veltVersion);
console.log('API Key:', debugInfo.apiKey);
console.log('Server State:', debugInfo.serverMap);
console.log('Client State:', debugInfo.clientMap);
};
```
```javascript theme={null}
const debugInfo = await Velt.fetchDebugInfo();
console.log('Debug Info:', debugInfo);
console.log('SDK Version:', debugInfo.veltVersion);
console.log('API Key:', debugInfo.apiKey);
console.log('Server State:', debugInfo.serverMap);
console.log('Client State:', debugInfo.clientMap);
```
### getDebugInfo()
* Use this method to subscribe to real-time updates of debugging information about your Velt integration. This includes details like SDK version, API key, user, organizationId, documentId, folderId, version, and locations.
* You can also access this diagnostic information through [Velt’s Chrome DevTools extension](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl).
* Params: None
* Returns: `Observable<`[`VeltDebugInfo`](/api-reference/sdk/models/data-models#veltdebuginfo)`>`
```jsx theme={null}
const { client } = useVeltClient();
const [debugInfo, setDebugInfo] = useState(null);
useEffect(() => {
if (!client) return;
const subscription = client.getDebugInfo().subscribe((info) => {
setDebugInfo(info);
console.log('Debug Info Updated:', info);
});
return () => subscription.unsubscribe();
}, [client]);
```
```javascript theme={null}
const subscription = Velt.getDebugInfo().subscribe((debugInfo) => {
console.log('Debug Info Updated:', debugInfo);
console.log('SDK Version:', debugInfo.veltVersion);
console.log('API Key:', debugInfo.apiKey);
console.log('Server State:', debugInfo.serverMap);
console.log('Client State:', debugInfo.clientMap);
});
// Unsubscribe when done
subscription.unsubscribe();
```
# Velt CLI
Source: https://docs.velt.dev/get-started/cli
Use the add-velt CLI to scaffold Velt collaboration features into your Next.js app with a single command.
Add Velt real-time collaboration to an existing Next.js project from your terminal. The CLI installs dependencies, generates components, and auto-wires `VeltProvider` into your app layout — no manual configuration required.
## When to Use the CLI
* You want to add Velt to a Next.js project quickly from the command line
* You prefer a non-interactive, flag-driven workflow
* You want to scaffold specific features (comments, notifications, CRDT) in one step
* You are setting up Velt without an AI coding assistant
If you are using an AI coding agent like Claude Code or Cursor, see the [MCP Installer](/get-started/mcp-installer) for an AI-assisted setup experience.
## Prerequisites
* **Node.js** 18+
* **Next.js** 13.4.0+ (App Router or Pages Router)
* **React** 18.2.0+
* **Package manager**: npm, yarn, or pnpm
* A [Velt API key](https://console.velt.dev)
## Quickstart
Run the CLI in your Next.js project directory:
```bash theme={null}
npx @velt-js/add-velt
```
This installs the baseline Velt SDK (`@veltdev/react`, `@veltdev/types`) and generates core components. To include specific features, add flags:
```bash theme={null}
npx @velt-js/add-velt --comments
```
After the CLI completes, set your API key in `.env.local`:
```bash theme={null}
NEXT_PUBLIC_VELT_API_KEY=your_api_key_here
```
Then update the generated files with your app-specific logic:
1. **`components/velt/VeltInitializeDocument.tsx`** — replace the placeholder document ID with your own (e.g., from a route parameter)
2. **`components/velt/VeltInitializeUser.tsx`** — replace the placeholder user object with your real user context
Start your dev server and verify Velt loads in the browser console.
## Configuration
### API Key
The CLI wires `VeltProvider` to read your API key from the `NEXT_PUBLIC_VELT_API_KEY` environment variable. Add it to `.env.local`:
```bash theme={null}
NEXT_PUBLIC_VELT_API_KEY=your_api_key_here
```
Get your API key from the [Velt Console](https://console.velt.dev).
### Document ID
Update `components/velt/VeltInitializeDocument.tsx` with your document ID source:
```tsx theme={null}
// Replace with your document ID logic
const documentId = 'your-document-id';
const documentName = 'your-document-name';
```
### User Authentication
Update `components/velt/VeltInitializeUser.tsx` with your user retrieval logic:
```tsx theme={null}
// Replace with your user retrieval logic
const user = {
userId: 'user-id',
organizationId: 'organization-id',
email: 'user@example.com',
};
```
## Options
### Feature Flags
| Flag | Description |
| ----------------- | ------------------------------------------------------------------- |
| `--comments` | Add inline comments (VeltComments, VeltCommentsSidebar, VeltCursor) |
| `--notifications` | Add notifications (VeltNotificationsTool, VeltCursor) |
| `--presence` | Add presence indicators (VeltPresence) |
| `--cursors` | Add live cursors (VeltCursor) |
### CRDT Type Flags (choose one)
| Flag | Description |
| ------------------- | ------------------------------------------ |
| `--reactflow-crdt` | Canvas collaboration with ReactFlow |
| `--tiptap-crdt` | Rich text editor collaboration with Tiptap |
| `--codemirror-crdt` | Code editor collaboration with CodeMirror |
### Combined Flag
| Flag | Description |
| ------- | ------------------------------------------------------------------ |
| `--all` | Enable comments + notifications + CRDT (requires a CRDT type flag) |
### Installation Flags
| Flag | Description |
| -------------------- | ------------------------------- |
| `--force`, `-f` | Force overwrite existing files |
| `--legacy-peer-deps` | Use legacy peer deps (npm only) |
| `--help`, `-h` | Show help message |
## What the CLI Does
The CLI performs these steps automatically:
1. **Detects your project** — finds `next.config.js`/`next.config.ts`, determines App Router vs Pages Router, and identifies your package manager (npm, yarn, or pnpm with workspace support)
2. **Installs dependencies** — adds `@veltdev/react` and `@veltdev/types`, plus feature-specific packages (e.g., `yjs` for CRDT)
3. **Generates components** — creates files under `components/velt/` for collaboration, document initialization, and user authentication
4. **Copies assets** — adds icon SVGs to `public/icons/` when features like notifications are selected
After the CLI completes, you need to manually wrap your app with `VeltProvider`. See the [Troubleshooting](#manual-veltprovider-setup) section for the required code.
## Generated Files
### Core (always created)
```
components/velt/
├── VeltCollaboration.tsx # Main collaboration wrapper
├── VeltInitializeDocument.tsx # Document initialization hook
└── VeltInitializeUser.tsx # User authentication hook
```
### With features enabled
When you use `--comments`, `--notifications`, or CRDT flags, the CLI also generates:
```
components/velt/
├── VeltTools.tsx # Toolbar (presence, sidebar, notifications)
└── ui-customization/
├── VeltCustomization.tsx # Dark mode + wireframe wrapper
├── styles.css # Custom styles
└── ... # Feature-specific wireframe files
```
To use the toolbar components, import `VeltTools` into your page:
```tsx theme={null}
import VeltTools from '@/components/velt/VeltTools';
export default function MyPage() {
return (
<>
{/* Your page content */}
);
}
```
## Examples
```bash theme={null}
# Core only (minimal setup)
npx @velt-js/add-velt
# Comments only (includes Presence + Cursors)
npx @velt-js/add-velt --comments
# Notifications only (includes Presence + Cursors)
npx @velt-js/add-velt --notifications
# Comments + Notifications
npx @velt-js/add-velt --comments --notifications
# All features with ReactFlow CRDT
npx @velt-js/add-velt --all --reactflow-crdt
# All features with Tiptap CRDT
npx @velt-js/add-velt --all --tiptap-crdt
# Force overwrite existing files
npx @velt-js/add-velt --all --reactflow-crdt --force
```
## Troubleshooting
### Dependency conflicts
If installation fails due to peer dependency issues:
```bash theme={null}
npx @velt-js/add-velt --force
# or (npm only)
npx @velt-js/add-velt --legacy-peer-deps
```
The CLI uses a smart retry strategy that automatically tries `--force` and `--legacy-peer-deps` as fallbacks.
### Existing files
Use `--force` to overwrite previously generated files:
```bash theme={null}
npx @velt-js/add-velt --comments --force
```
### Multiple CRDT types
Only one CRDT type can be selected at a time:
```bash theme={null}
# Wrong — will error
npx @velt-js/add-velt --reactflow-crdt --tiptap-crdt
# Correct
npx @velt-js/add-velt --reactflow-crdt
```
### `--all` without a CRDT type
The `--all` flag requires a CRDT type:
```bash theme={null}
# Wrong — will error
npx @velt-js/add-velt --all
# Correct
npx @velt-js/add-velt --all --reactflow-crdt
```
### Manual VeltProvider setup
After running the CLI, wrap your app with `VeltProvider` in your layout file:
```tsx theme={null}
// app/layout.tsx
import { VeltProvider } from '@veltdev/react';
import { useVeltAuthProvider } from '@/components/velt/VeltInitializeUser';
import { VeltCollaboration } from '@/components/velt/VeltCollaboration';
function VeltClientWrapper({ children }: { children: React.ReactNode }) {
const { authProvider } = useVeltAuthProvider();
return (
);
}
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
);
}
```
## Next Steps
* **[Quickstart](/get-started/quickstart)**: Manual step-by-step Velt setup (without the CLI)
* **[Agent Skills](/get-started/skills)**: Teach your AI coding agent correct Velt patterns
* **[MCP Installer](/get-started/mcp-installer)**: AI-assisted Velt installation through MCP
* **[Comments Overview](/async-collaboration/comments/overview)**: Learn about commenting features
* **[CRDT Setup](/realtime-collaboration/crdt/overview)**: Set up collaborative editing
* **[Key Concepts](/key-concepts/overview)**: Understand documents, locations, users, and access control
# Velt Installation MCP
Source: https://docs.velt.dev/get-started/mcp-installer
Use the Velt MCP server to install collaboration features into React and Next.js projects through your AI coding agent.
Install Velt collaboration features into your React or Next.js project through an AI coding agent. The Velt MCP (Model Context Protocol) server connects to editors like Claude Code, Cursor, and Windsurf, enabling guided installation with plan generation, codebase scanning, and user approval — all through natural conversation.
## When to Use the MCP Installer
* You are using an AI coding agent (Claude Code, Cursor, Windsurf, or Claude Desktop)
* You want an interactive, guided setup with automatic codebase analysis
* You want the AI to generate an implementation plan before making changes
* You need help wiring Velt into an existing authentication system or document structure
For a non-interactive, terminal-based workflow, see the [CLI](/get-started/cli) page instead.
## Prerequisites
* **Node.js** 18+
* An existing **React** or **Next.js** project (Next.js App Router, Pages Router, Vite + React, or Create React App)
* A [Velt API key and auth token](https://console.velt.dev)
* An MCP-compatible AI coding editor
### Recommended: Install Agent Skills
For the best results, install Velt Agent Skills before using the MCP installer. Skills give your AI agent access to verified Velt implementation patterns.
```bash theme={null}
npx skills add velt-js/agent-skills
```
See [Agent Skills](/get-started/skills) for details.
## Quickstart
### Step 1: Add the MCP Server
Add the Velt MCP server to your editor. The commands below use `npx` to automatically download and run `@velt-js/mcp-installer`. You can also install it globally with:
```bash theme={null}
npm install -g @velt-js/mcp-installer
```
Run this command in your terminal:
```bash theme={null}
claude mcp add velt-installer -- npx -y @velt-js/mcp-installer
```
Add to `.cursor/mcp.json` in your project (or global config):
```json theme={null}
{
"mcpServers": {
"velt-installer": {
"command": "npx",
"args": ["-y", "@velt-js/mcp-installer"]
}
}
}
```
Add to your Windsurf MCP config:
```json theme={null}
{
"mcpServers": {
"velt-installer": {
"command": "npx",
"args": ["-y", "@velt-js/mcp-installer"]
}
}
}
```
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json theme={null}
{
"mcpServers": {
"velt-installer": {
"command": "npx",
"args": ["-y", "@velt-js/mcp-installer"]
}
}
}
```
The server runs over stdio. Use this command to start it:
```bash theme={null}
npx -y @velt-js/mcp-installer
```
Add it to your editor's MCP server configuration with `command: "npx"` and `args: ["-y", "@velt-js/mcp-installer"]`.
Restart your editor after adding the config.
### Step 2: Start the Installation
In your AI chat, say:
```
install velt
```
The AI will walk you through each step one at a time:
1. Confirm your project directory
2. Provide your Velt API key and auth token
3. Select features (or type **SKIP** for CLI-only mode)
4. Choose where to install `VeltProvider` (`app/page.tsx` recommended)
5. Choose corner position for Velt UI components
6. Review the implementation plan
7. Approve and apply changes
## Installation Modes
### Guided Mode (Default)
The guided mode generates a full implementation plan with codebase analysis before making any changes.
**Workflow:**
1. **Collect info** — the AI asks setup questions one at a time (project path, API key, auth token, features, provider location, corner position)
2. **Discovery consent** — the AI asks whether to scan your codebase for integration points (document ID sources, authentication patterns, JWT wiring)
3. **Verification** — if scanning is approved, the AI shows findings for you to confirm, edit, or override
4. **Plan generation** — a detailed implementation plan is generated based on your project structure and wiring data
5. **Apply** — after you approve the plan, the AI applies changes step by step
6. **Validation** — full QA validation runs automatically after installation
The installer recommends placing `VeltProvider` in `app/page.tsx`, not `app/layout.tsx`. Follow this recommendation unless you have a specific reason to do otherwise.
### CLI-Only Mode (SKIP)
For experienced Velt developers who want the scaffold files without full integration:
1. At the feature selection step, type **SKIP**
2. The Velt CLI runs with core-only flags
3. You receive a TODO checklist for manual setup
Use this mode when you want to wire features yourself or just need the base files.
## Available Features
| Feature | Description |
| ------------- | -------------------------------------------------------------------------------------------- |
| Comments | Inline comments with 8 types: freestyle, popover, page, text, inline, tiptap, lexical, slate |
| Presence | Real-time user avatars and online status |
| Cursors | Live cursor position tracking |
| Notifications | Async collaboration notifications |
| Recorder | Session recording and playback |
| CRDT | Collaborative editing with Tiptap, CodeMirror, BlockNote, or ReactFlow |
## Codebase Discovery
In guided mode, the installer can automatically scan your project for integration points:
| Discovery Target | What It Detects |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Document ID** | Dynamic route params (`[id]`), query params, state variables, database fetches |
| **User Authentication** | Next-Auth, Clerk, Auth0, Firebase Auth, Supabase Auth, custom auth |
| **JWT Authentication** | Token generation endpoints, bearer auth patterns |
| **Setup Location** | Root layout, specific pages, custom providers |
Each finding includes a confidence level (HIGH, MEDIUM, LOW, NONE). For uncertain findings, the installer asks you to verify rather than guessing.
If you decline the codebase scan, the AI asks a manual questionnaire covering document ID source, user authentication, JWT setup, and component insertion location.
## Framework Support
| Framework | Support | `"use client"` Directives |
| ---------------------- | ------- | ------------------------- |
| Next.js (App Router) | Full | Auto-applied |
| Next.js (Pages Router) | Full | N/A |
| Vite + React | Full | Not needed |
| Create React App | Full | Not needed |
## Generated Code Structure
After installation, the generated files follow this pattern:
```
app/
├── layout.tsx # Wraps with AppUserProvider
├── page.tsx # Contains VeltProvider with authProvider hook
└── userAuth/
├── AppUserContext.tsx # User context provider
└── useAppUser.tsx # User data hook
components/velt/
├── VeltInitializeUser.tsx # Exports useVeltAuthProvider hook
├── VeltInitializeDocument.tsx # Exports useCurrentDocument hook
└── VeltCollaboration.tsx # All Velt feature components
app/api/velt/token/
└── route.ts # JWT token generation API (if JWT is configured)
```
## MCP Tools
The MCP server exposes these tools to your AI agent:
| Tool | Description |
| -------------------------- | ----------------------------------------------------------------- |
| `install_velt_interactive` | Unified installer with guided or CLI-only mode |
| `install_velt_freestyle` | Legacy installer for basic freestyle comments |
| `take_project_screenshot` | Capture a screenshot of your running app via Playwright |
| `detect_comment_placement` | Analyze project structure to find the best locations for comments |
## Troubleshooting
### MCP server not loading
After adding the configuration, restart your editor. The MCP server runs over stdio and must be started by the editor process.
### AI not detecting the installer
Verify the MCP config is valid JSON and that `npx -y @velt-js/mcp-installer` runs successfully in your terminal. You can test with:
```bash theme={null}
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx -y @velt-js/mcp-installer
```
### Discovery scan returns low confidence
If the codebase scan cannot determine your document ID or auth setup with confidence, the AI will ask explicit follow-up questions. You can also choose the manual questionnaire path by declining the scan.
### Validation errors after installation
The installer runs QA validation automatically. Check the browser console for Velt-specific errors after starting your dev server. Common issues include missing API keys or incorrect document IDs.
## Next Steps
* **[Agent Skills](/get-started/skills)**: Install skills to improve AI-generated Velt code
* **[CLI](/get-started/cli)**: Terminal-based Velt setup without an AI agent
* **[Quickstart](/get-started/quickstart)**: Manual step-by-step Velt setup
* **[Comments Overview](/async-collaboration/comments/overview)**: Learn about commenting features
* **[Key Concepts](/key-concepts/overview)**: Understand documents, locations, users, and access control
# Overview
Source: https://docs.velt.dev/get-started/overview
## Getting Started
Set up Velt with a fresh App
Integrate Velt with an existing app
## Popular Features
Enable contextual discussions within your app
Notify users about comment updates or add custom app notifications
Loom-style audio, video & screen recording with AI transcription
Slack-style huddle calls within your app
## Async Collaboration
Leave a comment anywhere
A sidebar that holds your comments
Notification center in your app
Embeddable audio, video & screen recording
Frame.io style comments on video
Leave comments using an API
Add reactions to components
Show which users viewed a document
Point at what is important
## Realtime Collaboration
Sync the state of your app realtime
Lock access to a single editor
See who else is browsing online
See where everyone else is browsing
Let others follow along your screen
Hop on a group call with everyone
See what others are editing
## Advanced
Call a webhook when a comment is added
Set up email notifications
Retrieve or modify data
Fully customize Velt Components
# AI Plugins
Source: https://docs.velt.dev/get-started/plugins
Install the Velt plugin in Cursor or Claude Code to get skills, rules, an expert agent, and MCP servers for building with the Velt SDK.
Add Velt collaboration knowledge directly into your AI coding editor. The Velt AI plugin gives your AI agent access to 8 slash-command skills, 6 embedded best-practice rules, a `velt-expert` agent persona, and two MCP servers — so it can scaffold, debug, and extend Velt features with accurate, up-to-date patterns.
## When to Use AI Plugins
* You are building with Velt in Cursor or Claude Code and want your AI agent to have deep Velt SDK knowledge
* You want slash-command skills like `/install-velt`, `/add-comments`, or `/velt-help` available in your editor
* You want always-on rules that prevent common Velt integration mistakes (e.g., incorrect `VeltProvider` placement, missing `setDocuments`)
* You want the `velt-expert` agent persona for architecture and integration guidance
AI plugins bundle MCP servers, skills, rules, and an agent into a single installable package. If you only need one of these:
* **MCP servers only**: See the [MCP Installer](/get-started/mcp-installer)
* **Skills only** (for any AI agent): See [Agent Skills](/get-started/skills)
* **No AI agent**: See the [CLI](/get-started/cli)
## Prerequisites
* **Node.js** 18+
* **Cursor** or **Claude Code** with plugin support
* A [Velt API key](https://console.velt.dev)
## Quickstart
### Option 1: Local Plugin Directory
1. Clone the plugin repository:
```bash theme={null}
git clone https://github.com/velt-js/velt-plugin.git
```
2. Open Cursor Settings → Plugins
3. Add the local plugin path:
```
/packages/cursor-velt
```
4. Restart Cursor.
### Option 2: Marketplace CLI
From within Cursor, run:
```
/plugin marketplace add ./packages/cursor-velt
```
### Option 1: Direct Plugin Directory
Point Claude Code at the built plugin:
```bash theme={null}
git clone https://github.com/velt-js/velt-plugin.git
claude --plugin-dir packages/claude-velt
```
### Option 2: Local Marketplace
```bash theme={null}
# Inside Claude Code:
/plugin marketplace add ./packages/claude-marketplace
/plugin install velt@velt-plugins
```
After installation, verify by typing `/velt-help` in your editor's AI chat. The agent should respond using Velt-specific knowledge.
## What's Included
The plugin bundles four types of resources:
| Resource | Count | Description |
| --------------- | ----- | ---------------------------------------------------------------------- |
| **Skills** | 8 | Slash commands for common Velt tasks |
| **Rules** | 6 | Embedded best practices (3 always-on, 3 glob-triggered) |
| **Agent** | 1 | `velt-expert` persona for architecture guidance |
| **MCP Servers** | 2 | `velt-installer` (guided setup) and `velt-docs` (documentation search) |
## Available Skills
| Skill | Description | MCP Tool Used |
| -------------------- | ------------------------------------------------------------------------- | -------------------------- |
| `/install-velt` | Full guided Velt SDK installation | `install_velt_interactive` |
| `/add-comments` | Add comments (freestyle, popover, text, stream, page, editor) | `install_velt_interactive` |
| `/add-crdt` | Add CRDT collaborative editing (Tiptap, BlockNote, CodeMirror, ReactFlow) | `install_velt_interactive` |
| `/add-notifications` | Add in-app notifications, email, webhooks | `install_velt_interactive` |
| `/add-presence` | Add real-time user presence indicators | `install_velt_interactive` |
| `/add-cursors` | Add live cursor tracking | `install_velt_interactive` |
| `/screenshot` | Capture app screenshot for visual reference | `take_project_screenshot` |
| `/velt-help` | Answer questions about the Velt SDK | `velt-docs` MCP |
## Embedded Rules
The plugin includes 6 rules distilled from 105 agent-skills rules. Three are always active; three activate when your AI agent works on matching files.
| Rule | Covers | Activation |
| ----------------------------- | ---------------------------------------------------------- | -------------- |
| `velt-core-setup` | Installation, `VeltProvider`, API key, domain safelist | Always on |
| `velt-auth-patterns` | User object, `authProvider`, JWT, auth provider mapping | Always on |
| `velt-document-identity` | `setDocuments`, document ID strategies, anti-patterns | Always on |
| `velt-comments-patterns` | All comment modes, component placement, editor integration | Glob-triggered |
| `velt-crdt-patterns` | CRDT stores, Tiptap integration, history disable | Glob-triggered |
| `velt-notifications-patterns` | Setup, panel config, hooks, email, webhooks | Glob-triggered |
## How It Works
The plugin follows a three-tier priority chain when answering questions or generating code:
1. **Embedded rules** (always loaded) — distilled best practices that cover the most common mistakes
2. **Reference agent-skills** (vendored snapshot) — full detailed patterns with code examples from the [agent-skills repository](https://github.com/velt-js/agent-skills)
3. **velt-docs MCP** (live query) — fetches the latest API details or topics not covered by the first two tiers
This means the agent can answer most questions instantly from local knowledge, and only reaches out to the live docs API when needed.
## Claude Code Implementation
The Claude Code plugin lives at `packages/claude-velt/` and follows the Claude Code plugin specification.
### Plugin Structure
```
packages/claude-velt/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── .mcp.json # MCP server configuration
├── agents/
│ └── velt-expert.md # Expert agent persona
├── guides/
│ └── velt-rules.md # Combined best-practices guide (all 6 rules)
├── skills/
│ ├── install-velt/SKILL.md
│ ├── add-comments/SKILL.md
│ ├── add-crdt/SKILL.md
│ ├── add-notifications/SKILL.md
│ ├── add-presence/SKILL.md
│ ├── add-cursors/SKILL.md
│ ├── screenshot/SKILL.md
│ └── velt-help/SKILL.md
└── references/
└── agent-skills/ # Vendored snapshot (~992 KB)
```
### Plugin Manifest
The manifest at `.claude-plugin/plugin.json` registers the plugin with Claude Code:
```json theme={null}
{
"name": "velt",
"description": "Add real-time collaboration (comments, presence, cursors, CRDT editing, notifications) to React and Next.js apps using the Velt SDK.",
"version": "1.0.0",
"author": { "name": "Velt", "email": "support@velt.dev" },
"homepage": "https://docs.velt.dev",
"repository": "https://github.com/velt-js/velt-plugin",
"license": "MIT",
"keywords": ["velt", "collaboration", "comments", "presence", "cursors", "crdt", "real-time", "react", "nextjs"]
}
```
### MCP Server Configuration
The `.mcp.json` file configures two MCP servers that Claude Code connects to automatically:
```json theme={null}
{
"mcpServers": {
"velt-installer": {
"command": "npx",
"args": ["-y", "@velt-js/mcp-installer"]
},
"velt-docs": {
"type": "http",
"url": "https://docs.velt.dev/mcp"
}
}
}
```
* **`velt-installer`** — runs locally via `npx`, exposes `install_velt_interactive`, `take_project_screenshot`, and `detect_comment_placement` tools
* **`velt-docs`** — connects to the remote Velt docs API over HTTP for live documentation queries
### Agent Persona
The `velt-expert` agent at `agents/velt-expert.md` is a Velt SDK specialist. It uses frontmatter to register with Claude Code:
```yaml theme={null}
---
name: velt-expert
description: Velt collaboration SDK expert for architecture, setup, and integration guidance.
---
```
The agent follows these key principles:
* `VeltProvider` goes in `page.tsx`, not `layout.tsx` (Next.js App Router)
* All files importing `@veltdev/react` need `"use client"` directive
* Authenticate users before setting documents
* `setDocuments` in a child component, never in `VeltProvider`'s component
* For Tiptap CRDT: always disable history (`StarterKit.configure({ history: false })`)
### Combined Rules Guide
Unlike Cursor (which uses individual `.mdc` rule files with `alwaysApply` and glob triggers), the Claude Code plugin combines all 6 rules into a single `guides/velt-rules.md` file. This guide covers:
1. **Core setup** — `VeltProvider`, API key, domain safelist
2. **Authentication** — user object, `authProvider`, JWT, provider mapping
3. **Document identity** — `setDocuments`, ID strategies, anti-patterns
4. **Comments** — all modes (freestyle, popover, text, stream, page, editor-integrated)
5. **CRDT** — store types, Tiptap integration, history disable
6. **Notifications** — panel config, hooks, email via SendGrid, webhooks
Every skill's `SKILL.md` includes a footer that references this guide:
```
**Important**: Always consult `guides/velt-rules.md` for embedded best practices before querying external sources.
```
### Skill Format
Each Claude Code skill uses `description` frontmatter (Cursor uses both `name` and `description`):
```yaml theme={null}
---
description: Full guided installation of the Velt collaboration SDK into a React or Next.js project.
---
```
Skills follow a consistent structure: **Trigger** (when to activate), **Workflow** (step-by-step instructions), **Guardrails** (constraints), **Priority Chain** (where to look for answers), and **Output** (what gets delivered).
### Marketplace Wrapper
For distribution through the Claude Code marketplace, a wrapper exists at `packages/claude-marketplace/`:
```
packages/claude-marketplace/
├── .claude-plugin/
│ └── marketplace.json # Marketplace metadata
└── plugins/
└── velt/ # Copy of claude-velt (generated by build)
```
The `marketplace.json` registers the plugin collection:
```json theme={null}
{
"name": "velt-plugins",
"owner": { "name": "Velt", "email": "support@velt.dev" },
"metadata": {
"description": "Official Velt collaboration SDK plugins for Claude Code",
"version": "1.0.0"
},
"plugins": [
{
"name": "velt",
"source": "./plugins/velt",
"description": "Add real-time collaboration (comments, presence, cursors, CRDT editing, notifications) to React and Next.js apps."
}
]
}
```
### Differences from Cursor Plugin
| Aspect | Cursor (`cursor-velt`) | Claude Code (`claude-velt`) |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Manifest** | `.cursor-plugin/plugin.json` with `displayName`, `logo`, `category`, `tags`, `skills`, `rules`, `agents`, `mcpServers` fields | `.claude-plugin/plugin.json` with simpler schema (no `displayName`, `logo`, or path references) |
| **Rules** | 6 individual `.mdc` files with `alwaysApply` / glob frontmatter | Single `guides/velt-rules.md` combining all 6 rules |
| **MCP config** | `mcp.json` (top-level file) | `.mcp.json` (dotfile), `velt-docs` uses `"type": "http"` |
| **Skill frontmatter** | `name` + `description` | `description` only |
| **Agent footer** | No rules reference footer | Appends `guides/velt-rules.md` reference to agent and all skills |
| **Logo** | `assets/logo.svg` included | Not included |
| **Marketplace** | Direct plugin registration | Separate `claude-marketplace/` wrapper with `marketplace.json` |
## Contributing
If you are contributing to the plugin itself, the repository uses a shared-source architecture. All canonical content lives in `packages/shared/` and is built into platform-specific outputs.
### Build Workflow
```bash theme={null}
# 1. Sync the agent-skills reference (from a sibling ../agent-skills directory)
npm run sync
# 2. Generate both Cursor and Claude Code plugins from shared source
npm run build
# 3. Validate both plugins are complete
npm run validate
# Or run all three:
npm run all
```
### Sync Options
By default, `npm run sync` looks for the agent-skills repository at `../agent-skills`. To override:
```bash theme={null}
node scripts/sync-agent-skills.mjs /path/to/agent-skills
```
### What the Build Does
* Adds platform-specific frontmatter to skills and agents
* Converts shared rules to `.mdc` files (Cursor) or a combined `guides/velt-rules.md` (Claude Code)
* Copies the vendored agent-skills reference into both plugins
* Generates the Claude Code marketplace wrapper
### Validation Checks
`npm run validate` verifies:
* All 8 skills present in both plugins
* Both MCP servers configured
* Agent persona present
* JSON manifests valid and free of path traversal
* Reference agent-skills present
## Troubleshooting
### Plugin not loading after installation
Restart your editor after adding the plugin path. Verify the plugin directory contains a `.cursor-plugin/plugin.json` (Cursor) or `.claude-plugin/plugin.json` (Claude Code) manifest file.
### Skills not appearing
Confirm the plugin directory points to the correct built output (`packages/cursor-velt` or `packages/claude-velt`), not the root repository or `packages/shared`.
### Stale rules or skills
If you updated the shared source, re-run the build:
```bash theme={null}
npm run build
```
Then restart your editor to pick up the changes.
### MCP servers not connecting
The plugin configures two MCP servers automatically. If they fail to connect, verify that `npx -y @velt-js/mcp-installer` runs successfully in your terminal:
```bash theme={null}
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | npx -y @velt-js/mcp-installer
```
For the docs MCP server, verify `https://docs.velt.dev/mcp` is reachable from your network.
### Claude Code: `guides/velt-rules.md` not found
Ensure you are pointing at `packages/claude-velt`, not `packages/cursor-velt`. The Claude Code plugin uses a combined rules guide at `guides/velt-rules.md`, while Cursor uses individual `.mdc` files in `rules/`.
## Next Steps
* **[MCP Installer](/get-started/mcp-installer)**: AI-assisted Velt installation through MCP (without the full plugin)
* **[Agent Skills](/get-started/skills)**: Standalone skill packages for any AI coding agent
* **[CLI](/get-started/cli)**: Terminal-based Velt setup without an AI agent
* **[Quickstart](/get-started/quickstart)**: Manual step-by-step Velt setup
* **[Key Concepts](/key-concepts/overview)**: Understand documents, locations, users, and access control
# Quickstart
Source: https://docs.velt.dev/get-started/quickstart
Install and set up Velt in minutes in React, Angular, Vue, or HTML.
Get Velt up and running in your app with comments, presence, and real-time collaboration features. You'll install the package, configure authentication, set up documents, and see collaborative features working immediately.
The SDK will not work without proper authentication and document initialization.
## Prerequisites
* Package manager (npm, yarn, or pnpm)
* Node.js (v14 or higher)
* React 16+, Vue 2+, Angular 12+, or vanilla HTML/JS
* A [Velt account with an API key](https://console.velt.dev)
* Optional: TypeScript types package for better development experience
## Setup
### Step 1: Install Dependencies
Install the required packages:
```bash theme={null}
npm install @veltdev/react
# Optional: npm install --save-dev @veltdev/types
```
```bash theme={null}
npm install @veltdev/client
# Optional: npm install --save-dev @veltdev/types
```
```bash theme={null}
npm install @veltdev/client
# Optional: npm install --save-dev @veltdev/types
```
Use our CDN Script
```html theme={null}
```
### Step 2: Get Your API Key
1. Go to [console.velt.dev](https://console.velt.dev) and create an account
2. Copy your API key from the dashboard
Wrap your app with `VeltProvider` and pass your API key.
If using Next.js, add 'use client' directive at the top of files containing Velt components to ensure proper client-side rendering.
```jsx Step 1: Provider Setup theme={null}
'use client'; // MAKE SURE TO INCLUDE 'use client' for Next.js implementation
import { VeltProvider } from '@veltdev/react';
export default function App() {
return (
{/* Your app content */}
);
}
```
Step 1: Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to allow Angular to render Velt's custom elements (web components).
Step 2: Boot the Velt client by calling `initVelt` with your API key.
```jsx Step 1: App Module Setup theme={null}
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
AppRoutingModule
],
providers: [],
bootstrap: [AppComponent],
schemas: [CUSTOM_ELEMENTS_SCHEMA], // Add this line
})
export class AppModule { }
```
```jsx Step 2: Initialize Velt theme={null}
import { initVelt } from '@veltdev/client';
export class AppComponent implements OnInit {
async ngOnInit() {
await initVelt('YOUR_VELT_API_KEY');
}
}
```
Step 1: Register Velt's custom elements by setting `Vue.config.ignoredElements = [/velt-*/]`.
Step 2: Boot the Velt client by calling `initVelt` with your API key.
```js Step 1: Main.js Setup theme={null}
import Vue from 'vue';
import App from './App.vue';
// Allow Velt elements
Vue.config.ignoredElements = [/velt-*/];
new Vue({
render: h => h(App),
}).$mount('#app');
```
```js Step 2: Initialize Velt theme={null}
import { initVelt } from '@veltdev/client';
export default {
name: 'App',
async mounted() {
await initVelt('YOUR_VELT_API_KEY');
}
}
```
Call `Velt.init('YOUR_VELT_API_KEY')` to bootstrap the client before rendering Velt components.
```js Step 1: Script Include and Init theme={null}
```
### Step 5: Authenticate Users
There are two ways to authenticate in Velt. Pick one based on your needs:
* **Auth Provider (recommended)**: Configure once and Velt will **fetch/refresh tokens automatically**. See details in the [Key Concepts](/key-concepts/overview#authenticate-a-user).
* **Identify API (more personable)**: Call `identify(user, options)` directly where you need it for more control. If you use Identify, you must refresh tokens yourself, see [Token Refresh](/get-started/advanced#token-refresh).
After authenticating, you can retrieve the current user object anytime using [`getCurrentUser()`](/api-reference/sdk/api/api-methods#getcurrentuser) or [`useCurrentUser()`](/api-reference/sdk/api/react-hooks#usecurrentuser).
**Critical Authentication Requirement:**
* You must authenticate the user. The recommended path is configuring `authProvider` on `VeltProvider` during initialization.
During development, `generateToken` can be omitted; however, for production it is highly recommended to provide `generateToken` for basic security and seamless token refresh.
You first need to create a user object with the required user information. The `user` object should include the following fields: `userId`, `organizationId`, `name`, `email`, and `photoUrl`.
```javascript theme={null}
// Example user object
const user = {
userId: 'user-123',
organizationId: 'org-abc',
name: 'John Doe',
email: 'john.doe@example.com',
photoUrl: 'https://i.pravatar.cc/300',
};
```
**Error Handling**: By default, authentication methods return `null` on failure. You can configure them to throw errors instead by setting `throwError: true`. [Learn more about error handling](/get-started/advanced#error-handling-in-authentication).
Then, you need to provide a function that generates a Velt JWT token from your backend. See the [JWT Token Setup](/get-started/advanced#jwt-authentication-tokens). Tokens expire after 48 hours, handle renewals as shown in [Token Refresh](/get-started/advanced#token-refresh).
Access control roles: Assign users as Editor or Viewer per resource (organization, folder, document) via your JWT token permissions or backend access APIs. Editors can write collaboration data (e.g., add/edit comments); Viewers are read-only. See: [Access Control](/key-concepts/overview#access-control), APIs [Generate Token](/api-reference/rest-apis/v2/auth/generate-token), [Add Permissions](/api-reference/rest-apis/v2/auth/add-permissions), [Add/Update Users](/api-reference/rest-apis/v2/users/add-users).
```jsx theme={null}
return (
{
const token = await __generateVeltAuthTokenFromYourBackend__();
return token;
}
}}
>
{/* Your app content */}
);
```
```jsx theme={null}
Velt.setVeltAuthProvider({
user,
retryConfig: { retryCount: 3, retryDelay: 1000 },
generateToken: async () => {
const token = await __generateVeltAuthTokenFromYourBackend__();
return token;
}
});
```
```js theme={null}
Velt.setVeltAuthProvider({
user,
retryConfig: { retryCount: 3, retryDelay: 1000 },
generateToken: async () => {
const token = await __generateVeltAuthTokenFromYourBackend__();
return token;
}
});
```
```html theme={null}
```
### Step 6: Initialize Document
A **Document** represents a shared collaborative space where users can interact. The `setDocument` method initializes this space and takes a unique `documentId` and optional `metadata`.
By default, users can only access documents within their own organization. Use this to set the document for the current organization the user is logged into.
Learn more about documents [here](/key-concepts/overview#documents).
To subscribe to multiple documents in a single call, use `setDocuments` and pass an array; see [here for more information](/key-concepts/overview#subscribe-to-documents-from-other-organizations).
The SDK will not work without initializing the document.
```jsx React / Next.js theme={null}
import { useEffect } from 'react';
import { useVeltClient } from '@veltdev/react';
export default function DocumentComponent() {
const { client } = useVeltClient();
useEffect(() => {
if (client) {
client.setDocuments([
{ id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
]);
}
}, [client]);
return (
{/* Your document content */}
);
}
```
```jsx Angular Document Setup theme={null}
import { Component } from '@angular/core';
import { initVelt } from '@veltdev/client';
@Component({
selector: 'app-document',
template: `
`
})
export class DocumentComponent {
client: any;
async ngOnInit() {
this.client = await initVelt('YOUR_VELT_API_KEY');
// Set document for current organization
this.client.setDocuments([
{ id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
]);
}
}
```
```jsx Angular Service Approach theme={null}
// In your document service
export class DocumentService {
client: any;
async initializeDocument() {
if (this.client) {
this.client.setDocuments([
{ id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
]);
}
}
}
```
```js Vue.js Document Setup theme={null}
import { initVelt } from '@veltdev/client';
export default {
name: 'DocumentComponent',
data() {
return {
client: null
}
},
async mounted() {
this.client = await initVelt('YOUR_VELT_API_KEY');
// Set document for current organization
this.client.setDocuments([
{ id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
]);
}
}
```
```js Vue.js Composition API theme={null}
import { ref, onMounted } from 'vue';
import { initVelt } from '@veltdev/client';
export default {
setup() {
const client = ref(null);
onMounted(async () => {
client.value = await initVelt('YOUR_VELT_API_KEY');
// Set document for current organization
client.value.setDocuments([
{ id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
]);
});
return {
client
}
}
}
```
```js HTML Document Setup theme={null}
// In your script tag
async function loadVelt() {
await Velt.init("YOUR_VELT_API_KEY");
// Set document for current organization
Velt.setDocuments([
{ id: 'unique-document-id', metadata: { documentName: 'Document Name' } }
]);
}
```
```html Complete HTML Document theme={null}
My Document
My Document
### Step 7: Install Velt Feature Components
Add the `VeltComments`, `VeltCommentTool`, and `VeltPresence` components to enable comments and presence features.
Use the tabs below to see the setup for React, Angular, Vue, and HTML.
Render the comments surface at the app root; render presence and the comment tool within the document view:
```jsx App.js theme={null}
import { VeltProvider, VeltComments } from '@veltdev/react';
```
```jsx YourDocument.js theme={null}
import { VeltCommentTool, VeltPresence } from '@veltdev/react';
```
Render the comments surface in the root template; render presence and the comment tool in the document component template:
```html app.component.html theme={null}
Render the comments surface in App.vue; render presence and the comment tool in your document component:
```html App.vue theme={null}
```
```html YourDocument.vue theme={null}
```
In your root component add these features (tags inside ``):
```html index.html theme={null}
My Collaborative App
### Step 8: Verify Setup
A good first step is to check if the Velt SDK has been initialized correctly. Open your browser's developer console and run the following command:
```js theme={null}
await Velt.getMetadata()
```
This should return the document metadata you've set. If it returns an error or `null`, check the console for any initialization errors.
**To test comments functionality:**
1. Click the `VeltCommentTool` button, then hover over any element on the page to leave a comment
2. Click the `VeltCommentTool` button, then draw a box on the page to leave a comment
3. Try highlighting any text to leave a comment
4. Test replying to comments and using the comments tool
**To test presence functionality:**
1. Open two browser tabs side by side with one in incognito mode
2. Log in with different users in each tab
3. You should see user avatars appear showing presence in both tabs
If you don't see the comments tool, check your browser console for API key or network errors.
## Debugging
**Common issues:**
* **Invalid API key or domain not whitelisted**: Verify your API key and ensure your domain is added under "Managed Domains" in the [Velt Console](https://console.velt.dev)
* **Component not rendering**: Ensure the VeltProvider/script loads before your components
* **No collaborative features**: Verify that both authentication and document initialization are properly set up
* **Users can't see each other**: Ensure both users are in the same organization and document
* **Package not found**: Clear npm cache and reinstall (`npm cache clean --force`)
* **TypeScript errors**: Install the optional types package (`@veltdev/types`)
## Notes
* **API Key Required**: Always use a valid API key from the [Velt Console](https://console.velt.dev)
* **Framework Compatibility**: Ensure your framework version meets the minimum requirements
* **Child Components**: Call authentication and document setup methods in child components, never in the same file as your VeltProvider
* **Next.js 'use client'**: Add `'use client'` directive at the top of files containing Velt components for proper client-side rendering
* **Organization ID**: Always include the `organizationId` when identifying users - this is required for proper access control
* **Document Required**: The SDK will not work without calling `setDocument()` - this defines the collaborative space
* **@mention Support**: To enable @mention functionality, set up user contacts [here](/key-concepts/overview#contact-list)
* **Location Support**: For organizing users within documents, learn about Locations [here](/key-concepts/overview#set-location)
* **TypeScript Support**: Install the optional types package for better development experience
## Complete Example
If using Next.js, add 'use client' directive at the top of files containing Velt components to ensure proper client-side rendering.
```jsx App.js - Root Component theme={null}
import { VeltProvider, VeltComments } from '@veltdev/react';
import AuthComponent from './AuthComponent';
import DocumentComponent from './DocumentComponent';
export default function App() {
return (
);
}
```
```jsx AuthComponent.js - User Authentication theme={null}
import { useIdentify } from '@veltdev/react';
export default function AuthComponent() {
const userService = () => ({
uid: "user123",
organizationId: "org123",
displayName: "John Doe",
email: "john@example.com",
photoURL: "https://i.pravatar.cc/300"
});
const yourAuthenticatedUser = userService();
const { uid, displayName, email, photoURL, organizationId } = yourAuthenticatedUser;
const user = {
userId: uid,
organizationId: organizationId,
name: displayName,
email: email,
photoUrl: photoURL,
color: "#FF6B6B",
textColor: "#FFFFFF"
};
useIdentify(user);
return User: {user.name}
;
}
```
```jsx DocumentComponent.js - Document Setup theme={null}
import { useSetDocument, VeltCommentTool, VeltPresence } from '@veltdev/react';
export default function DocumentComponent() {
useSetDocument('my-document-id', { documentName: 'My Collaborative Document' });
return (
My Document
This is a collaborative document where multiple users can comment and see each other's presence.
);
}
```
```jsx app.module.ts - Module Setup theme={null}
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppRoutingModule } from './app-routing.module';
import { AppComponent } from './app.component';
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
AppRoutingModule
],
providers: [],
bootstrap: [AppComponent],
schemas: [CUSTOM_ELEMENTS_SCHEMA], // Add this line
})
export class AppModule { }
```
```jsx app.component.ts - Component Setup theme={null}
import { Component, OnInit } from '@angular/core';
import { initVelt } from '@veltdev/client';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.scss']
})
export class AppComponent implements OnInit {
client: any;
async ngOnInit() {
this.client = await initVelt('YOUR_VELT_API_KEY');
// Authenticate user
const user = {
userId: 'user123',
organizationId: 'org123',
name: 'John Doe',
email: 'john@example.com',
photoUrl: 'https://i.pravatar.cc/300',
color: '#FF6B6B',
textColor: '#FFFFFF'
};
await this.client.identify(user);
// Set document
await this.client.setDocument('my-document-id', { documentName: 'My Document' });
}
}
```
```html app.component.html - Template theme={null}
My Collaborative App
This is a collaborative document where multiple users can comment and see each other's presence.
```
```js main.js - Vue Configuration theme={null}
import Vue from 'vue';
import App from './App.vue';
// Allow Velt elements
Vue.config.ignoredElements = [/velt-*/];
new Vue({
render: h => h(App),
}).$mount('#app');
```
```js App.vue - Component Setup theme={null}
import { initVelt } from '@veltdev/client';
export default {
name: 'App',
data() {
return {
client: null
}
},
async mounted() {
this.client = await initVelt('YOUR_VELT_API_KEY');
// Authenticate user
const user = {
userId: 'user123',
organizationId: 'org123',
name: 'John Doe',
email: 'john@example.com',
photoUrl: 'https://i.pravatar.cc/300',
color: '#FF6B6B',
textColor: '#FFFFFF'
};
await this.client.identify(user);
// Set document
await this.client.setDocument('my-document-id', { documentName: 'My Document' });
}
}
```
```html App.vue Template theme={null}
```
```html index.html - Complete Setup theme={null}
My Collaborative App
My Collaborative App
My Collaborative App
My Collaborative App
## Next Steps
Now that you've completed the basic setup, you can explore more advanced Velt features and concepts:
* **[Key Concepts](/key-concepts)**: For new developers we recommend reading through our curated list for an in-depth breakdown of the Velt SDK and cool features.
* **[Documents and Locations](/key-concepts/overview#documents)**: Learn how to structure your app's collaborative spaces.
* **[Users and User Groups](/key-concepts/overview#users)**: Configure and manage your users and groups.
* **[Access Control](/key-concepts/overview#access-control)**: Define permissions to control who can access what.
* **[Authentication](/key-concepts/overview#authentication)**: Explore more advanced authentication methods.
* **[UI Customization](/ui-customization/overview)**: Customize layouts, styling, templates, and actions for Velt components.
# Quickstart Old Copy
Source: https://docs.velt.dev/get-started/quickstart-old
Quickstart for React. For other frameworks like `vue`, `angular`, `svelte`, `vanilla js` etc. check out the setup guide.
Create a new React app [using any method](https://react.dev/learn/start-a-new-react-project) you prefer.
```bash Terminal theme={null}
cd my-app && npm install @veltdev/react
```
If you're using TypeScript, you can install the types package.
```bash Terminal theme={null}
npm install --save-dev @veltdev/types
```
Go to [console.velt.dev](https://console.velt.dev) and grab your Velt API Key
In the Velt console, add the URL where your app is deployed to the list of Managed Domains.
In **App.js**, add the `VeltProvider` component to the root of your app with your Velt API Key.
```js App.js theme={null}
```
In **YourAuthComponent.js**, use the `useIdentify()` hook from the Velt SDK to identify your user.
```js YourAuthComponent.js theme={null}
import { useIdentify } from '@veltdev/react';
useIdentify(user)
```
Make sure to call `useIdentify()` within a child component of the Velt Provider. Otherwise, it will not work.
In **YourDocument.js**, use the `useSetDocumentId()` hook from the Velt SDK to set the Document ID.
```js YourDocument.js theme={null}
import { useSetDocumentId } from '@veltdev/react';
useSetDocumentId("my-document-id")
```
In **App.js**, add `VeltComments` to enable the `Comments` functionality.
```js App.js theme={null}
```
In **YourDocument.js**, add the `VeltCommentTool` and `VeltPresence` components to test out the `Comments` and `Presence` functionality.
```js YourDocument.js theme={null}
```
### Comments
* Click the `VeltCommentTool` button, then hover over any element on the page to leave a comment.
* Click the `VeltCommentTool` button, then try to draw a box on the page to leave a comment.
* You can also highlight any text to leave a comment.
### Presence
* Open two browser tabs side by side with one in Incognito mode. You should see a bubble showing the other browser's profile avatar pop up.
Check out this guide on [how to set up Velt with your existing app](/get-started/quickstart)
```jsx App.js theme={null}
import { VeltProvider, VeltComments, VeltPresence } from '@veltdev/react';
import YourAuthComponent from './YourAuthComponent';
import YourDocument from './YourDocument';
export default function App() {
return (
);
}
```
```jsx YourAuthComponent.js theme={null}
import { useIdentify} from "@veltdev/react";
import { useState } from "react";
export default function YourAuthComponent() {
const userService = () => {
return {
uid: "user1",
displayName: "User 1",
email: "user1@velt.dev",
photoURL: "https://i.pravatar.cc/301"
};
};
// Fetch user data from user service
let yourAuthenticatedUser = userService();
const { uid, displayName, email, photoURL } = yourAuthenticatedUser;
// Create the Velt user object
let veltUser = {
userId: uid,
name: displayName,
email: email,
photoUrl: photoURL,
};
//identify Velt user
useIdentify(veltUser)
let [user,setUser] = useState(veltUser)
return User: {user?.userId}
;
}
```
```jsx YourDocument.js theme={null}
import { useSetDocumentId, VeltCommentTool, VeltPresence } from '@veltdev/react';
import { useEffect, useState } from 'react';
export default function YourDocument() {
useSetDocumentId('my-document-id')
return (
);
}
```
# Agent Skills
Source: https://docs.velt.dev/get-started/skills
Use Velt Agent Skills to get accurate, best-practice code from AI coding agents like Claude Code, Cursor, and GitHub Copilot.
Get better results from AI coding agents when building with Velt. Agent Skills are structured knowledge packages that teach your AI agent the correct Velt patterns, so it writes working code on the first try instead of guessing from outdated training data.
Agent Skills follow the open [Agent Skills](https://agentskills.io/) format and work with Claude Code, Cursor, GitHub Copilot, and other AI coding agents that support skill discovery.
## What Are Agent Skills?
Agent Skills are folders of instructions, rules, and code examples that AI agents can discover and reference while helping you write code. Each skill covers a specific area of the Velt SDK and contains prioritized rules with correct and incorrect code patterns, verification checklists, and source pointers back to the official docs.
Instead of relying on the agent's general training data (which may be outdated or incomplete), skills give the agent access to verified, up-to-date Velt implementation patterns.
## When to Use Skills
Install Agent Skills when you are:
* Setting up Velt in a new project for the first time
* Adding collaborative commenting to a React, Next.js, or web application
* Integrating real-time collaborative editing with CRDT (Yjs) and editors like Tiptap, BlockNote, or CodeMirror
* Implementing in-app notifications, email delivery, or webhook integrations
* Debugging issues with Velt features and looking for correct patterns
## Installation
Install all available Velt skills with a single command:
```bash theme={null}
npx skills add velt-js/agent-skills
```
Skills are automatically available once installed. Your AI agent will use them when relevant tasks are detected.
## Available Skills
The repository contains four skills covering the core areas of the Velt SDK:
**21 rules** across 8 categories covering installation, VeltProvider configuration, user authentication, JWT tokens, and document initialization.
Use when setting up Velt in a new React, Next.js, Angular, Vue, or HTML project.
**33 rules** across 9 categories covering comment modes (Freestyle, Popover, Stream, Text, Page, Inline), rich text editor integrations (Tiptap, SlateJS, Lexical), and media/chart comments.
Use when adding collaborative commenting to your application.
**33 rules** across 5 categories covering CRDT store setup, Tiptap, BlockNote, CodeMirror, and ReactFlow integrations.
Use when implementing real-time collaborative editing.
**11 rules** across 8 categories covering notification panels, data access, delivery channels, and webhook integrations.
Use when adding in-app notifications or email delivery.
## How Skills Are Organized
Each skill follows a consistent structure:
```
skills/{skill-name}/
SKILL.md # Agent-facing manifest (when to apply, category index)
AGENTS.md # Generated compressed index of all rules
AGENTS.full.md # Generated verbose guide with all rules expanded
README.md # Contributor guide
metadata.json # Version, organization, and metadata
rules/
_sections.md # Section definitions and ordering
_template.md # Template for new rules
shared/ # Framework-agnostic rules
react/ # React / Next.js specific rules
non-react/ # Non-React specific rules
```
Rules are organized into **category folders** (e.g., `core/`, `panel/`, `data/`) within framework groups (`shared/`, `react/`, `non-react/`). Each rule file is named `{prefix}-{descriptive-name}.md` where the prefix matches its category.
## How to Pick the Right Skill
| You want to... | Use this skill |
| ---------------------------------------------- | ----------------------------------- |
| Set up Velt for the first time | `velt-setup-best-practices` |
| Add comments (any mode or editor) | `velt-comments-best-practices` |
| Add real-time collaborative editing (CRDT/Yjs) | `velt-crdt-best-practices` |
| Add notifications or email delivery | `velt-notifications-best-practices` |
## Example Prompts
Once skills are installed, you can give your AI agent prompts like these. The agent will automatically reference the relevant skill rules.
**Setting up Velt in a new project:**
```
Set up Velt collaboration in my Next.js app. I need comments and presence.
My API key is in .env.local as NEXT_PUBLIC_VELT_API_KEY.
```
**Adding CRDT collaborative editing:**
```
Set up Velt CRDT for my Tiptap editor. The document ID comes from
the route parameter. Ask me for any identifiers you need.
```
**Debugging an integration issue:**
```
Help me debug why my collaborative cursors aren't showing.
Check the Velt skills for correct setup patterns before suggesting fixes.
```
## Rule Priority Levels
Each rule in a skill is assigned an impact level so the agent knows what matters most:
| Level | Improvement | Examples |
| --------------- | --------------------------------------- | --------------------------------------------------- |
| **CRITICAL** | Prevents failure or 10-100x improvement | Provider setup, authentication, core initialization |
| **HIGH** | Major quality gain (5-20x) | Comment modes, CRDT editor integration |
| **MEDIUM-HIGH** | Significant benefit (2-5x) | Standalone components, design patterns |
| **MEDIUM** | Noticeable gain (1.5-3x) | UI customization, data handling |
| **LOW-MEDIUM** | Minor benefit (1.2-2x) | Configuration, debugging patterns |
| **LOW** | Incremental or edge cases | Advanced techniques, polish |
## Staying Up to Date
Skills are updated as the Velt SDK evolves with new features, API changes, and improved patterns. To pull the latest rules into your project, re-run the install command:
```bash theme={null}
npx skills add velt-js/agent-skills
```
This will fetch the latest version of all skills, including any new rules or updated code examples.
You can also watch the [agent-skills GitHub repository](https://github.com/velt-js/agent-skills) to get notified when new skills or rules are published. For broader SDK updates and announcements, follow us on [X](https://x.com/veltjs) and [LinkedIn](https://www.linkedin.com/company/veltjs/).
## Next Steps
* **[Quickstart](/get-started/quickstart)**: Set up Velt in your app from scratch
* **[Comments Overview](/async-collaboration/comments/overview)**: Learn about Velt's commenting features
* **[Notifications Overview](/async-collaboration/notifications/overview)**: Learn about in-app notifications
* **[Key Concepts](/key-concepts/overview)**: Understand documents, locations, users, and access control
# CSS Injection
Source: https://docs.velt.dev/global-styles/css-injection
## Custom CSS Injection
You can inject CSS with our special `client.injectCustomCss()` method.
### Passing style definition via string
```jsx theme={null}
client?.injectCustomCss({
type: 'styles',
value: `
.modal-div.dialog .modal-author__name {
font-size: 10rem !important;
background-color: green !important;
color: white !important;
}
`
});
```
### Passing style via link.
```jsx theme={null}
client?.injectCustomCss({
type: 'link',
value: '/relative_path_to_css/styles.css' // you could also pass the absolute link: 'https://yourappdomain.com/pathtocss/styles.css'
});
```
## Custom CSS Injection
You can inject CSS with our special `client.injectCustomCss()` method.
### Passing style definition via string
```jsx theme={null}
Velt?.injectCustomCss({
type: 'styles',
value: `
.modal-div.dialog .modal-author__name {
font-size: 10rem !important;
background-color: green !important;
color: white !important;
}
`
});
```
### Passing style via link.
```jsx theme={null}
Velt?.injectCustomCss({
type: 'link',
value: '/relative_path_to_css/styles.css' // you could also pass the absolute link: 'https://yourappdomain.com/pathtocss/styles.css'
});
```
```jsx React / Next.js theme={null}
import { useVeltClient } from '@veltdev/react';
import { useEffect, useState } from 'react';
export default function YourDocument() {
const { client } = useVeltClient();
useEffect(() => {
if (client) {
client?.injectCustomCss({
type: 'styles',
value: `
.modal-div.dialog .modal-author__name {
font-size: 10rem !important;
background-color: green !important;
color: white !important;
}
`
});
client?.injectCustomCss({
type: 'link',
value: '/relative_path_to_css/styles.css' // you could also pass the absolute link: 'https://yourappdomain.com/pathtocss/styles.css'
});
}
}, [client]);
return (
//your document template
);
}
```
```html HTML theme={null}
```
# Dark Mode
Source: https://docs.velt.dev/global-styles/dark-mode
## Enable Dark Mode on all Components
To enable Dark Mode on all Components, call the `client.setDarkMode(true)`
```jsx theme={null}
let client = useVeltClient();
client.setDarkMode(true);
```
## Enable Dark Mode on individual Components
To enable Dark Mode on individual components, set the `darkMode` attribute to `true`.
```jsx theme={null}
## Enable Dark Mode on all Components
To enable Dark Mode on all Components, call the `Velt.setDarkMode(true)`
```jsx theme={null}
Velt.setDarkMode(true);
```
## Enable Dark Mode on individual Components
To enable Dark Mode on individual components, set the `dark-mode` attribute to `true`.
```jsx theme={null}
# Global Styles
Source: https://docs.velt.dev/global-styles/global-styles
To edit the styling for all Velt components, you can use the following global CSS variables. This is recommended over editing the CSS for each tool individually.
```scss theme={null}
// default state
--velt-tool-padding: 6px;
--velt-tool-icon-size: 1.5rem;
--velt-tool-icon-color: var(--velt-neutral-4);
--velt-tool-border-radius: 50px;
--velt-tool-border-color: transparent;
--velt-tool-border: 2px solid var(--velt-tool-border-color);
--velt-tool-bg-color: transparent;
// default focus state
--velt-tool-focus-icon-size: var(--velt-tool-icon-size);
--velt-tool-focus-icon-color: var(--velt-tool-icon-color);
--velt-tool-focus-border-radius: var(--velt-tool-border-radius);
--velt-tool-focus-border-color: var(--velt-neutral-7);
--velt-tool-focus-border: 2px solid var(--velt-tool-focus-border-color);
--velt-tool-focus-bg-color: var(--velt-tool-bg-color);
// default hover state
--velt-tool-hover-icon-size: var(--velt-tool-icon-size);
--velt-tool-hover-icon-color: var(--velt-neutral-3);
--velt-tool-hover-border-radius: var(--velt-tool-border-radius);
--velt-tool-hover-border-color: var(--velt-neutral-7);
--velt-tool-hover-border: 2px solid var(--velt-tool-hover-border-color);
--velt-tool-hover-bg-color: var(--velt-neutral-7);
// active state
--velt-tool-active-icon-size: var(--velt-tool-icon-size);
--velt-tool-active-icon-color: var(--velt-neutral-9);
--velt-tool-active-border-radius: var(--velt-tool-border-radius);
--velt-tool-active-border-color: var(--velt-purple);
--velt-tool-active-border: 2px solid var(--velt-tool-active-border-color);
--velt-tool-active-bg-color: var(--velt-purple);
// active focus state
--velt-tool-active-focus-icon-size: var(--velt-tool-icon-size);
--velt-tool-active-focus-icon-color: var(--velt-tool-icon-color);
--velt-tool-active-focus-border-radius: var(--velt-tool-border-radius);
--velt-tool-active-focus-border-color: rgba(255, 255, 255, 0.24);
--velt-tool-active-focus-border: 2px solid
var(--velt-tool-active-focus-border-color);
--velt-tool-active-focus-bg-color: var(--velt-purple);
// active hover state
--velt-tool-active-hover-icon-size: var(--velt-tool-icon-size);
--velt-tool-active-hover-icon-color: var(--velt-tool-icon-color);
--velt-tool-active-hover-border-radius: var(--velt-tool-border-radius);
--velt-tool-active-hover-border-color: #433fa7;
--velt-tool-active-hover-border: 2px solid
var(--velt-tool-active-hover-border-color);
--velt-tool-active-hover-bg-color: #433fa7;
```
```scss Styles.css theme={null}
// default state
--velt-tool-padding: 6px;
--velt-tool-icon-size: 1.5rem;
--velt-tool-icon-color: var(--velt-neutral-4);
--velt-tool-border-radius: 50px;
--velt-tool-border-color: transparent;
--velt-tool-border: 2px solid var(--velt-tool-border-color);
--velt-tool-bg-color: transparent;
// default focus state
--velt-tool-focus-icon-size: var(--velt-tool-icon-size);
--velt-tool-focus-icon-color: var(--velt-tool-icon-color);
--velt-tool-focus-border-radius: var(--velt-tool-border-radius);
--velt-tool-focus-border-color: var(--velt-neutral-7);
--velt-tool-focus-border: 2px solid var(--velt-tool-focus-border-color);
--velt-tool-focus-bg-color: var(--velt-tool-bg-color);
// default hover state
--velt-tool-hover-icon-size: var(--velt-tool-icon-size);
--velt-tool-hover-icon-color: var(--velt-neutral-3);
--velt-tool-hover-border-radius: var(--velt-tool-border-radius);
--velt-tool-hover-border-color: var(--velt-neutral-7);
--velt-tool-hover-border: 2px solid var(--velt-tool-hover-border-color);
--velt-tool-hover-bg-color: var(--velt-neutral-7);
// active state
--velt-tool-active-icon-size: var(--velt-tool-icon-size);
--velt-tool-active-icon-color: var(--velt-neutral-9);
--velt-tool-active-border-radius: var(--velt-tool-border-radius);
--velt-tool-active-border-color: var(--velt-purple);
--velt-tool-active-border: 2px solid var(--velt-tool-active-border-color);
--velt-tool-active-bg-color: var(--velt-purple);
// active focus state
--velt-tool-active-focus-icon-size: var(--velt-tool-icon-size);
--velt-tool-active-focus-icon-color: var(--velt-tool-icon-color);
--velt-tool-active-focus-border-radius: var(--velt-tool-border-radius);
--velt-tool-active-focus-border-color: rgba(255, 255, 255, 0.24);
--velt-tool-active-focus-border: 2px solid
var(--velt-tool-active-focus-border-color);
--velt-tool-active-focus-bg-color: var(--velt-purple);
// active hover state
--velt-tool-active-hover-icon-size: var(--velt-tool-icon-size);
--velt-tool-active-hover-icon-color: var(--velt-tool-icon-color);
--velt-tool-active-hover-border-radius: var(--velt-tool-border-radius);
--velt-tool-active-hover-border-color: #433fa7;
--velt-tool-active-hover-border: 2px solid
var(--velt-tool-active-hover-border-color);
--velt-tool-active-hover-bg-color: #433fa7;
```
# Customize Behavior
Source: https://docs.velt.dev/in-app-user-feedback/customize-behavior
## 1. Feedback Mode
By default the component will be in `Feedback` mode. This will make your component say *"Give feedback"* and have a heart icon.
```js theme={null}
## 1. Feedback Mode
By default the component will be in `Feedback` mode. This will make your component say *"Give feedback"* and have a heart icon.
```js theme={null}
```js React theme={null}
import { VeltUserRequestTool } from '@veltdev/react';
function YourComponent() {
return (
)
}
```
```html HTML theme={null}
# Overview
Source: https://docs.velt.dev/in-app-user-feedback/overview
# Setup
Source: https://docs.velt.dev/in-app-user-feedback/setup
Import the `VeltUserRequestTool` component.
```js theme={null}
import { VeltUserRequestTool } from '@veltdev/react';
```
Place the component wherever you want the invite button to appear.
```js theme={null}
```
Place the component wherever you want the invite button to appear.
```jsx theme={null}
```
```js React / Next.js theme={null}
import { VeltUserRequestTool } from '@veltdev/react';
function YourComponent() {
return (
)
}
```
```html HTML theme={null}
Collaboration App
```
# AG Grid
Source: https://docs.velt.dev/integrations/ag-grid
## How to add Velt attributes to AG Grid cells?
Some Velt features like live selection require adding Velt specific attributes to the cell elements. Here's how you can do it:
1. In your AG Grid column definitions, use the `cell renderer` property to customize the cell rendering.
2. Within the `cell renderer`, add the necessary Velt attributes to the cell element.
Here's a code sample that shows how to add the `data-velt-live-selection-enabled` attribute and other required attributes to AG Grid cell div tags:
```jsx theme={null}
colDefs: ColDef[] = [
{
field: "FIELD_NAME",
cellRenderer: (params: any) => {
// Let AG Grid render the default cell, then modify the outer div
setTimeout(() => {
const cellElement = params.eGridCell;
// Add Velt attributes to the parent cell div
cellElement.setAttribute('data-velt-live-selection-enabled', 'true');
// Add other Velt attributes as required
}, 0); // Timeout to wait for the DOM to be ready
return params.value; // Use the default renderer, which is the text value
},
editable: true, // Set to true if the column is editable
},
];
```
# Overview
Source: https://docs.velt.dev/key-concepts/overview
## Overview
Velt organizes your collaborative data in a clear hierarchy. This structure helps control Velt feature data access with precision.
The hierarchy is: Organization → Folders → Documents → Locations.
Here are the core concepts:
* [Organizations](#organizations): The top-level container for everything. Think of it as your customer's entire account (e.g., Meta). It holds all their users, groups, and collaborative data.
* [Folders](#folders): A way to group and organize documents, just like in a file system. Folders can contain other folders and documents, inheriting permissions.
* [Documents](#documents): The primary collaborative space. This is where features like comments, presence, and cursors come alive. A document could be a design file, a dashboard, a spreadsheet, or a specific page in your app.
* [Locations](#locations): An optional, granular subspace within a document. If a document is a slide deck, a location is a single slide. If a document is a video, a location could be a specific timestamp.
* [Users](#users): Your end users who use your app.
* [Access Control](#access-control): The rules that control who can access what Velt feature data.
* [Authentication](#authenticate-a-user): The process of authenticating a user in Velt.
## Organizations
### Overview
An **Organization** is the top-level entity.
* It contains folders, documents, locations and users.
* Think of an `organization` as the account belonging to a company (e.g., Company A). This account may have several `users` (Company A employees). A `document` will be any file created within the organization (e.g., document, spreadsheet, slides, etc.). A `location` will be any child section within the document (e.g., slide within a presentation).
### Properties
* By default, Users within the organization can access all of it's resources like folder, documents, contact list etc. This can be modified using access control settings.
* A user can be added to multiple organizations but can only log in to one organization at a time.
* Access to resources can be restricted by setting controls at the individual resource level.
### APIs
### Frontend APIs
#### Sign in User into an Organization
* Sign in the user into an organization using [these options](/key-concepts/overview#sign-in-a-user).
* User needs to sign in to an organization in order to perform CRUD operations on it.
### Backend APIs
#### Create Organization
* When the user signs into an organization it will be created automatically if it doesn't exist.
* Explicitly create an organization using the REST API. [Learn more](/api-reference/rest-apis/v2/organizations/add-organizations)
#### Update Organization
* Update organization using the REST API. [Learn more](/api-reference/rest-apis/v2/organizations/update-organizations)
#### Delete Organization
* Delete organization using the REST API. [Learn more](/api-reference/rest-apis/v2/organizations/delete-organizations)
* It will delete all the data (folders, documents, locations and users) within the organization.
#### Get Organization
* Get organization and it's metadata using the REST API. [Learn more](/api-reference/rest-apis/v2/organizations/get-organizations-v2)
#### Disable Organization
* Disable CRUD access to an organization using the REST API. [Learn more](/api-reference/rest-apis/v2/organizations/update-organization-disable-state)
#### Provision Access to an Organization
* Provision access to an organization using [access control APIs](/key-concepts/overview#access-control)
## Folders
### Overview
Folders help you organize documents in a hierarchical way, like a traditional file system.
### Properties
* Folders can contain both documents and subfolders.
* Folders use the same permission model as Organizations and Documents.
* By default, folders inherits the permission from it's organization.
* A user can be added to multiple Folders but can only initialize one Folder at a time.
* By default, all Folder users have access to all Folder resources including sub folders, documents, locations and user contacts.
* Access to individual resources within the Folder **cannot** be restricted by setting controls at the individual resource level.
* Access of the Folder cascades to all resources within the Folder.
### APIs
### Frontend APIs
#### Subscribe to a folder
* Subscribe to a folder and its documents using the `setDocuments` method.
* Subscribe to all documents in the folder or a specific set of documents. If you want to subscribe to specific documents in the folder then you can pass upto 30 documents at a time.
**Filtering Behavior:** When using `setDocuments` with the `allDocuments` flag, the method automatically filters out documents the user doesn't have access to instead of failing the entire operation. The folder document limit is set to 50 documents when using `allDocuments: true`. Any documents the user doesn't have access to are silently filtered from the result.
**Using Hooks:**
```jsx expandable theme={null}
const { setDocuments } = useSetDocuments();
{/* Subscribe to a folder and all its documents */}
const rootDocument = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
}
];
setDocuments(
rootDocument,
{
folderId: 'folder1',
allDocuments: true
}
);
{/* Subscribe to a folder and some documents */}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
setDocuments(
documents,
{
folderId: 'folder1',
}
);
```
**Using API:**
```jsx expandable theme={null}
{/* Subscribe to a folder and all its documents */}
await client.setDocuments(
rootDocument,
{
folderId: 'folder1',
allDocuments: true
}
);
{/* Subscribe to a folder and some documents */}
await client.setDocuments(
documents,
{
folderId: 'folder1',
}
);
```
```js expandable theme={null}
// Subscribe to a folder and all its documents
const rootDocument = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
}
];
await Velt.setDocuments(
rootDocument,
{
folderId: 'folder1',
allDocuments: true
}
);
// Subscribe to a folder and some documents
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
await Velt.setDocuments(
documents,
{
folderId: 'folder1',
}
);
```
#### Fetch folder metadata
* Retrieve folder metadata and its subfolders using either `organizationId` or `folderId`, with support for pagination.
```jsx expandable theme={null}
// Get all folders for a specific organization
const folderMetadata = await client.fetchFolders({
organizationId: 'org1'
});
// Get a specific folder's metadata with its immediate subfolders
const folderMetadata = await client.fetchFolders({
organizationId: 'org1',
folderId: 'folder1'
});
console.log(folderMetadata); // { data: { folder1: { ... } }, nextPageToken: '...' }
```
```js expandable theme={null}
// Get all folders for a specific organization
const folderMetadata = await Velt.fetchFolders({
organizationId: 'org1'
});
// Get a specific folder's metadata with its immediate subfolders
const folderMetadata = await Velt.fetchFolders({
organizationId: 'org1',
folderId: 'folder1'
});
console.log(folderMetadata); // { data: { folder1: { ... } }, nextPageToken: '...' }
```
### Backend APIs
#### Create Folder
* Create a folder using the REST API. [Learn more](/api-reference/rest-apis/v2/folders/add-folder)
#### Update Folder
* Update folder using the REST API. [Learn more](/api-reference/rest-apis/v2/folders/update-folder)
#### Move Documents to Folder
* Move documents to a folder using the REST API. [Learn more](/api-reference/rest-apis/v2/documents/move-documents)
#### Delete Folder
* Delete folder using the REST API. [Learn more](/api-reference/rest-apis/v2/folders/delete-folder)
* It will delete all the data (subfolders, documents, locations and users) within the folder.
#### Get Folder
* Get folder and it's metadata using the REST API. [Learn more](/api-reference/rest-apis/v2/folders/get-folders)
#### Update Folder Access Type
* Update the access type of a folder using the REST API. [Learn more](/api-reference/rest-apis/v2/folders/update-folder-access)
#### Provision Access to a Folder
Provision access to a folder using [access control APIs](/key-concepts/overview#access-control)
## Documents
### Overview
A **Document** is a collaborative space within an Organization where users work together in real time. Each document includes:
* Feature data (such as Comments, Presence, Cursors, etc.)
* Locations
* Users (distinct from Organization users; see Access Control for details)
For example, in a slide presentation app, the whole slide deck would be a single document.
### Properties
* Anyone connected to the same `documentId` can see and interact with each other's activity, like presence, cursors, comments etc.
* Users can subscribe to a single document or multiple documents at the same time.
* Document inherits the permission from it's organization and parent folder.
* A user can be added to multiple Documents.
* You can set Document level access control to override the Organization's access control it inherited but not the Folder's access control.
**Document Access Priority:** Document-level access settings now take priority over folder-level access settings. If a document has its own explicit access configuration, those settings will be used. If the document doesn't have explicit access settings, it will inherit from its parent folder or organization.
### APIs
### Frontend APIs
#### Subscribe to Documents
* Use this to set and subscribe to one or multiple documents at the same time.
* You can specify 30 documents at a time.
* The first document in the list will be considered as the root document.
* For features like comments, notifications, recorder, reactions etc. you will be able to read and write to multiple documents at the same time.
* For features like cursors, presence, huddle, live state sync etc. it will default to the root document.
* Sidebar will automatically show data from all the documents.
**Access Filtering:** The `setDocuments` method now filters out documents the user doesn't have access to instead of failing the entire operation. Previously, if any document in the array was inaccessible, the entire query would fail. Now only accessible documents are subscribed, and inaccessible ones are silently filtered out.
**Params:**
* `documents`: [Document\[\]](/api-reference/sdk/models/data-models#document)
* `options?`: [SetDocumentsRequestOptions](/api-reference/sdk/models/data-models#setdocumentsrequestoptions)
**Using Hooks:**
```jsx theme={null}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
const { setDocuments } = useSetDocuments();
setDocuments(documents);
```
**Using API:**
```jsx theme={null}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
await client.setDocuments(documents);
```
**Using API:**
```js theme={null}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
await Velt.setDocuments(documents);
```
##### **Read/Write data from multiple documents on the same page**
* If you want to display data (eg: comments) from multiple documents on the same page, add `data-velt-document-id` attribute to the container that contains the `document`.
* It will be used to identify which part of the DOM belongs to which document.
```html theme={null}
...
...
...
```
#### Filter comments by context
You can filter which comments are loaded when subscribing to documents by passing a `context.access` parameter to `setDocuments()`. This is useful when you only want to fetch specific comments **within a document** that the user has access to.
Learn more about the [Feature Level Access Control](/key-concepts/overview#aset-feature-level-permissions-using-access-context-custom-metadata).
```jsx theme={null}
const { client } = useVeltClient();
client.setDocuments(documents, {
context: {
access: {
entityId: ['numberOfVisitors'],
dashboardId: ['myDashboard'],
}
},
});
```
```js theme={null}
Velt.setDocuments(documents, {
context: {
access: {
entityId: ['numberOfVisitors'],
dashboardId: ['myDashboard'],
}
},
});
```
#### Subscribe to Documents from Other Organizations
* By default, users can only access documents within their own organization.
* Enable cross-organization access by passing the target `organizationId` in the options parameter to `setDocument`/`setDocuments` (see Hook & API Example below).
* Ensure that the user has access to the target document in the target organization.
**Using Hook:**
```jsx expandable theme={null}
{/* Single Document */}
useSetDocument("DOCUMENT_ID", {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
{/* Multiple Documents */}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
useSetDocuments(documents, {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
```
**Using API:**
```jsx theme={null}
{/* Single Document */}
await client.setDocument("DOCUMENT_ID", {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
{/* Multiple Documents */}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
await client.setDocuments(documents, {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
```
```javascript expandable theme={null}
{/* Single Document */}
await Velt.setDocument(DOCUMENT_ID, {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
{/* Multiple Documents */}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
await Velt.setDocuments(documents, {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
```
#### Set Root Document
* Set the root document.
* This is useful when you have multiple documents subscribed in your app and you want change the root document during the session.
```jsx theme={null}
await client.setRootDocument({id:'DOCUMENT_ID'})
```
```javascript theme={null}
await Velt.setRootDocument({id:'DOCUMENT_ID'})
```
#### Unsubscribe from Documents
* Use this to unsubscribe from all documents at once.
**Using Hooks:**
```jsx theme={null}
useUnsetDocuments();
```
**Using API:**
```jsx theme={null}
await client.unsetDocuments();
```
```jsx theme={null}
await Velt.unsetDocuments();
```
#### Get Document Metadata
* Use this to get the metadata of a Document.
* This is useful when you want to display the document name in your app or any custom metadata that you have set.
* This returns a subscription with [`DocumentMetadata`](/api-reference/sdk/models/data-models#documentmetadata) object.
```jsx theme={null}
client.getDocumentMetadata().subscribe((documentMetadata) => {
console.log("Current document metadata: ", documentMetadata);
});
```
```jsx theme={null}
Velt.getDocumentMetadata().subscribe((documentMetadata) => {
console.log("Current document metadata: ", documentMetadata);
});
```
#### [Fetch Documents](/api-reference/sdk/api/api-methods#fetchdocuments)
* Fetch documents by organization, folder, or specific document IDs.
* Use `allDocuments: true` to fetch all documents for an organization or a specific folder.
* Supports pagination via `nextPageToken` in the response.
* When specifying individual `documentIds`, you can **pass up to 30 IDs at a time**.
This is a one-time fetch, not a realtime subscription. You will need to call again to refresh results.
**Params:**
* `request`: [FetchDocumentsRequest](/api-reference/sdk/models/data-models#fetchdocumentsrequest)
* Returns: [FetchDocumentsResponse](/api-reference/sdk/models/data-models#fetchdocumentsresponse)
```ts theme={null}
// Gets all documents for given org id
await client.fetchDocuments({ organizationId: 'org1', allDocuments: true });
// Gets all documents for the given folderId
await client.fetchDocuments({ organizationId: 'org1', folderId: 'folder1', allDocuments: true });
// Gets specified documents
await client.fetchDocuments({ organizationId: 'org1', documentIds: ['doc1', 'doc2'] });
```
```js theme={null}
// Gets all documents for given org id
await Velt.fetchDocuments({ organizationId: 'org1', allDocuments: true });
// Gets all documents for the given folderId
await Velt.fetchDocuments({ organizationId: 'org1', folderId: 'folder1', allDocuments: true });
// Gets specified documents
await Velt.fetchDocuments({ organizationId: 'org1', documentIds: ['doc1', 'doc2'] });
```
### Backend APIs
#### Create Document
* Create a document using the REST API. [Learn more](/api-reference/rest-apis/v2/documents/add-documents)
#### Update Document
* Update document using the REST API. [Learn more](/api-reference/rest-apis/v2/documents/update-documents)
#### Delete Document
* Delete document using the REST API. [Learn more](/api-reference/rest-apis/v2/documents/delete-documents)
* It will delete all the data (locations and users) within the document.
#### Get Document
* Get document and it's metadata using the REST API. [Learn more](/api-reference/rest-apis/v2/documents/get-documents-v2)
#### Update Document Access Type
* Update the access type of a document using the REST API. [Learn more](/api-reference/rest-apis/v2/documents/update-document-access)
#### Provision Access to a Document
Provision access to a document using [access control APIs](/key-concepts/overview#access-control)
#### Disable Document
* Disable CRUD access to a document using the REST API. [Learn more](/api-reference/rest-apis/v2/documents/update-document-disable-state)
#### Legacy APIs
##### **Subscribe to a Single Document**
* Use this to initialize and subscribe to a single Document.
* Once you set the document, you will start receiving realtime updates from the document.
* **Params:**
* `documentId`: The unique identifier for the document.
* `metadata`: (optional) This is a key/value pair object where you can set metadata about the document such as `documentName`. documentName is a special field that we use to display the document name in some Velt Components.
**Using Hooks:**
```jsx theme={null}
useSetDocument('unique-document-id', {documentName: 'Document Name'});
```
**Using API:**
```jsx theme={null}
await client.setDocument('unique-document-id', {documentName: 'Document Name'});
```
```jsx theme={null}
await Velt.setDocument('unique-document-id', {documentName: 'Document Name'});
```
##### **Unsubscribe from a Single Document**
* Use this to unsubscribe from the root Document
* Once you unset the document, you will no longer receive realtime updates from the document.
* For some parts of your app, you may not need Velt. In such cases, you can unset the document.
**Using Hooks:**
```jsx theme={null}
useUnsetDocumentId();
```
**Using API:**
```jsx theme={null}
await client.unsetDocumentId();
```
```jsx theme={null}
await Velt.unsetDocumentId();
```
## Locations
### Overview
**Locations** are optional subspaces (JSON object) within a document, providing finer partitioning of data.
Locations can represent:
* Pages
* Sections
* Video frames
* Data points on maps/charts
* Any other contextual area
For instance:
* In a slide presentation, the entire slide presentation will be a document each individual slide will be a location.
* In a dashboard, the entire dashboard is a document but various filters applied will be locations;
* In a video player, the entire video will be the document and timestamps will be locations.
If a **Document** is like a house, a **Location** is like a room within the house.
### Properties
* Any user with access to the document will have access to all locations in the document.
* Access controls cannot be set at the location level.
* Locations automatically generate location groups in the sidebar and organizes the comments within the group.
* The location object has these fields:
* `id` (required): A unique identifier for the location that can be used to reference it later
* `locationName` (recommended): A human-readable name displayed in Velt components like the `VeltCommentsSideBar`
* You can add any number of custom fields to the location object.
### APIs
### Frontend APIs
#### Subscribe to Locations
* Use this to set and subscribe to one or multiple locations at the same time.
* The first location in the list will be considered as the root location.
* Features will by default add data to the root location unless you use the location boundaries.
* Sidebar will automatically show data from all the documents.
**Params:**
* `locations`: [Location\[\]](/api-reference/sdk/models/data-models#location)
* `options?`: [SetLocationsRequestOptions](/api-reference/sdk/models/data-models#setlocationsrequestoptions)
* `rootLocationId`: The id of the location that will be set as the root location. If you don't specify this, the first location will be set as the root location.
* `appendLocation`: If you want to append new locations to the existing locations, set this to `true`.
**Using Hooks:**
```jsx theme={null}
const locations = [
{id:'location1', locationName:'Location 1'},
{id:'location2', locationName:'Location 2'}
];
const { setLocations } = useSetLocations();
setLocations(locations);
```
**Using API:**
```jsx theme={null}
await client.setLocations([
{id:'location1', locationName:'Location 1'},
{id:'location2', locationName:'Location 2'}
], {rootLocationId: 'location2'}); // By default 1st location will be set as root location unless rootLocationId is specified.
// Append new locations
await client.setLocations([
{id:'location3', locationName:'Location 3'},
{id:'location4', locationName:'Location 4'}
], {appendLocation: true})
```
```js theme={null}
await Velt.setLocations([
{id:'location1', locationName:'Location 1'},
{id:'location2', locationName:'Location 2'}
], {rootLocationId: 'location2'}); // By default 1st location will be set as root location unless rootLocationId is specified.
// Append new locations
await Velt.setLocations([
{id:'location3', locationName:'Location 3'},
{id:'location4', locationName:'Location 4'}
], {appendLocation: true})
```
##### Read/Write data from multiple locations on the same page using Location Boundaries
* If you want to display data (eg: comments) from multiple locations on the same page, add `data-velt-location-id` attribute to the container that contains the `location`.
* It will be used to identify which part of the DOM belongs to which location.
* This ensures that the comment added within the location is associated with the correct location.
```html theme={null}
...
...
...
```
#### Set Root Location
* Set the root location.
* This is useful when you have multiple locations subscribed in your app and you want change the root location during the session.
```jsx theme={null}
await client.setRootLocation({id:'LOCATION_ID'})
```
```javascript theme={null}
await Velt.setRootLocation({id:'LOCATION_ID'})
```
#### Unsubscribe from Locations
* Unset locations by ids or all of them if you don't specify any parameters.
```jsx theme={null}
// remove specific locations
await client.unsetLocationsIds(['location1', 'location2', 'location3'])
// remove all locations
await client.unsetLocationsIds()
```
```jsx theme={null}
// remove specific locations
await Velt.unsetLocationsIds(['location1', 'location2', 'location3'])
// remove all locations
await Velt.unsetLocationsIds()
```
#### Legacy APIs
##### **Subscribe to a Single Location**
* Use this to initialize and subscribe to a single Location.
**Using Hooks:**
```jsx theme={null}
useSetLocation({
'id': 'locationId1',
'locationName': 'MainVideoPlayer',
'videoFrame': '120'
})
```
**Using API:**
```jsx theme={null}
client.setLocation({
'id': 'locationId1',
'locationName': 'MainVideoPlayer',
'videoFrame': '120'
})
```
```jsx theme={null}
Velt.setLocation({
'id': 'locationId1',
'locationName': 'MainVideoPlayer',
'videoFrame': '120'
})
```
##### **Subscribe to Multiple Locations**
* Use this to subscribe to multiple locations at the same time.
* Add additional locations on the page by using set location with the `true` parameter.
**Using Hooks:**
```jsx expandable theme={null}
useSetLocation({
'id': 'locationId1',
'locationName': 'MainVideoPlayer',
'videoFrame': '120'
// You can keep adding more field to make the location very specific.
// The field names can be anything.
})
useSetLocation({
'id': 'locationId1',
'locationName': 'MainVideoPlayer',
'videoFrame': '120'
// You can keep adding more field to make the location very specific.
// The field names can be anything.
}, true)
```
**Using API:**
```jsx theme={null}
client.setLocation({
'id': 'locationId1',
'locationName': 'MainVideoPlayer',
'videoFrame': '120'
// You can keep adding more field to make the location very specific.
// The field names can be anything.
});
client.setLocation({
'id': 'locationId2',
'locationName': 'MainVideoPlayer2',
'videoFrame': '120'
// You can keep adding more field to make the location very specific.
// The field names can be anything.
}, true);
```
```jsx expandable theme={null}
Velt.setLocation({
'id': 'locationId1',
'locationName': 'MainVideoPlayer',
'videoFrame': '120'
// You can keep adding more field to make the location very specific.
// The field names can be anything.
});
Velt.setLocation({
'id': 'locationId2',
'locationName': 'MainVideoPlayer2',
'videoFrame': '120'
// You can keep adding more field to make the location very specific.
// The field names can be anything.
}, true);
```
## Users
### Overview
* A `User` is anyone authenticated with the Velt SDK.
* After authentication, a user's profile appears in Velt's collaboration features. For example, their name is shown next to their comments, in `@mentions`, and alongside their avatar in presence and cursor features.
### Contact List
When the user is on a document, they can `@mention` other users. By default, the contact list for the `@mention` feature includes users from:
* Organization.
* Folder.
* Document.
* User Groups.
* `@here`: This is a special group that includes only the users explicitly added on the document. This doesn't include organization users or organization user groups.
### User Groups
User Groups let you organize users into teams (like "engineering" or "marketing") for easier management and access control.
* Mention an entire group (e.g., @engineering) instead of individual users, similar to Slack.
* Organization users can be in multiple groups.
* Only organization users can join user groups.
### Properties
* Uniqueness of the user is determined by its `userId`.
* A user can be part of multiple organizations.
### APIs
### Frontend APIs
#### Authenticate a User
There are two ways to authenticate a user in Velt.
1. Using an Auth Provider (recommended)
2. Using Identify method
**Error Handling**: By default, authentication methods return `null` on failure. You can configure them to throw errors instead by setting `throwError: true`. [Learn more about error handling](/get-started/advanced#error-handling-in-authentication).
##### **1. Use Auth Provider**
* With this approach, you configure an authentication provider by specifying the user you want to authenticate and a function that returns a Velt JWT token.
* This function is automatically called by Velt whenever a token is required—such as during the initial sign-in or when the token expires.
* You should define this authentication provider within the Velt Provider during your app's initialization.
* Use this to [generate a Velt JWT token.](/api-reference/rest-apis/v2/auth/generate-token)
* **Params**:
* `user`: [User](/api-reference/sdk/models/data-models#user)
* `retryConfig`: [AuthRetryConfig](/api-reference/sdk/models/data-models#authretryconfig)
* `generateToken`: `() => Promise`
* `options`: [Options](/api-reference/sdk/models/data-models#options)
* `authToken`: `string`
* `forceReset`: `boolean`: By default, once the user is authenticated, the authentication state is preserved in the browser and a new token is not generated until you explicitly sign them out. If you want to force re-login the user, set this to `true`.
```js theme={null}
{
// See generateVeltAuthToken() tab for example implementation
const token = await generateVeltAuthToken();
return token;
}
}} />
```
```js theme={null}
Velt.setVeltAuthProvider({
user,
retryConfig: { retryCount: 3, retryDelay: 1000 },
generateToken: async () => {
// See generateVeltAuthToken() tab for example implementation
const token = await generateVeltAuthToken();
return token;
}
});
```
```ts expandable theme={null}
// Backend example: minimal token generator
export async function generateVeltAuthToken({
userId,
organizationId,
email,
}: {
userId: string;
organizationId: string;
email?: string;
}) {
const res = await fetch('https://api.velt.dev/v2/auth/generate_token', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'x-velt-api-key': YOUR_VELT_API_KEY_HERE,
'x-velt-auth-token': YOUR_VELT_AUTH_TOKEN_HERE,
},
body: JSON.stringify({
data: {
userId,
userProperties: {
organizationId,
...(email ? { email } : {}),
},
},
}),
});
const json = await res.json();
return json?.result?.data?.token as string | undefined;
}
```
##### **2. Use Identify with JWT Token**
* In this approach, you will call the `identify` method with the `user` object and a JWT token.
* Here you are responsible for re-generating a JWT token whenever it expires.
* This gives you more flexibility on when and where to initialize the user and generate the token.
* **Params**:
* `user`: [User](/api-reference/sdk/models/data-models#user)
* `options`: [Options](/api-reference/sdk/models/data-models#options)
* `authToken`: `string`
* `forceReset`: `boolean`: By default, once the user is authenticated, the authentication state is preserved in the browser and a new jwt token is not used until you explicitly sign them out. If you want to force re-login the user, set this to `true`.
**Using Hook:**
```js theme={null}
const user = {
userId: uid,
organizationId: organizationId, // this is the organization id the user belongs to. You should always use this.
name: displayName,
email: email,
photoUrl: photoURL,
color: colorCode, // Use valid Hex code value. Used in the background color of the user's avatar.
textColor: textColor // Use valid Hex code value. Used in the text color of the user's intial when photoUrl is not present.
};
useIdentify(user, {
authToken: authToken, // this is optional but highly recommended.
});
```
**Using API:**
```js theme={null}
await client.identify(user, {
authToken: authToken, // this is optional but highly recommended.
});
```
**Using API:**
```js theme={null}
await Velt.identify(user, {
authToken: authToken, // this is optional but highly recommended.
});
```
##### Sign in with force reset
* By default, when you identify a user, their authentication state is preserved in the browser until you explicitly sign them out.
* If you update a user's metadata or default access settings in the console and want those changes to take effect right away, you should call the `identify` method again with the `forceReset` option set to `true`.
* `Default: false`
```js theme={null}
await client.identify(user, {
forceReset: true
});
```
#### Get Current User
You can retrieve the currently authenticated user object using [`getCurrentUser()`](/api-reference/sdk/api/api-methods#getcurrentuser) method or [`useCurrentUser()`](/api-reference/sdk/api/react-hooks#usecurrentuser) hook.
**Using Hook:**
```jsx theme={null}
const currentUser = useCurrentUser();
console.log('Current user:', currentUser);
```
**Using API:**
```jsx theme={null}
client.getCurrentUser().subscribe((user) => {
console.log('Current user:', user);
});
```
```js theme={null}
Velt.getCurrentUser().subscribe((user) => {
console.log('Current user:', user);
});
```
#### Sign out a User
In a given session or browser tab, if you want to switch users,
you need to first signout the current user and then sign in using `identify` method again.
This will ensure we clean up the current user session and start a new session with the new user.
```jsx theme={null}
client.signOutUser();
```
#### Contact List
### Frontend APIs
You can update the contact list dynamically in your frontend. These updates are not saved in Velt. You can also fetch contacts from your backend and show them in Velt components.
* [Add/Update Users](/async-collaboration/comments/customize-behavior#updatecontactlist)
* [Search Users](/async-collaboration/comments/customize-behavior#customautocompletesearch)
### Backend APIs
You can add/delete users from your backend and save the list in Velt.
* [Add Users](/api-reference/rest-apis/v2/users/add-users)
* [Delete Users](/api-reference/rest-apis/v2/users/delete-users)
#### User Groups:
* [Add User Groups](/api-reference/rest-apis/v2/user-groups/add-groups)
* [Add Users to User Groups](/api-reference/rest-apis/v2/user-groups/add-users-to-group)
* [Delete Users from User Groups](/api-reference/rest-apis/v2/user-groups/delete-users-from-group)
## Access Control
### Overview
Velt's access control system is built around four main concepts:
1. [**Resources**](#1-resources) - The hierarchical structure of your app (Organizations → Folders → Documents)
2. [**Access Types**](#2-access-types) - This is applied to a resource to determine who can access it (public, organizationPrivate, or restricted)
3. [**Roles**](#3-roles) - This is applied to a user to determine what they can do on a resource (editor or viewer)
4. [**Permissions**](#4-permissions) – Define whether a user can access a resource, based on the resource's access type, the user's role, and explicit permission grants. Access can be temporary or permanent.
### Access Control Model
* **Inheritance (default)**: Similar to Google Drive, Velt Resources (Organizations, Folders, and Documents) follow a hierarchical permission model. By default, child resources inherit access control settings from their parents.
* **Overrides**: If a resource defines its own access type or user permissions, those explicit settings **override** the inherited values. This precedence applies during both permission evaluation and access enforcement.
**Example: Think of it like folders in Google Drive**
* You create a **folder** and set it to "Anyone with the link can view"
* Any **document** you add to that folder automatically inherits those same sharing settings
* If you want, you can override a specific document's sharing settings to be more restrictive or more open
**In Velt, this works the same way:**
* All **Folders** in that org automatically inherit `organizationPrivate` access
* All **Documents** in those folders also inherit `organizationPrivate` access
* If you explicitly set a specific Document to `restricted` access, that override takes precedence
### 1. Resources
Velt permissions apply to these resources and at the feature level using **Access Context**:
**Resource-Level Permissions:**
* **Organization** – top-level container that groups users, folders, and documents.
* **Folder** – groups documents under an organization.
* **Document** – individual collaborative unit (e.g., a canvas, page, or file).
Most permission changes occur at the **Folder** and **Document** level, but Organizations can set defaults that flow down hierarchically.
**Feature-Level Permissions (Access Context):**
Access Context enables granular, feature-level permissions using custom metadata. Unlike resource-level permissions that control access to entire organizations, folders, or documents, Access Context allows you to control access to specific features data (like individual comments or notifications) based on custom metadata fields you define.
**When to use Access Context:**
* **Fine-grained control**: When you need to restrict visibility of specific features data within a document rather than the entire document. For example, in a multi-tenant dashboard, users may access the same dashboard (document) but only see comments for widgets they’re authorized to view (scoped by widgetId).
* **Data-driven permissions**: When access needs to be determined by dynamic metadata such as entity IDs, project codes, section identifiers, or other custom fields specific to your application's data model.
* **Complex scenarios**: When resource-level permissions alone are too broad and you need feature-specific isolation within the same collaborative space.
### 2. Access Types
Access types define **who** can access a resource:
* **`public`** **(default)**: Any authenticated user in your app who initializes Velt can access the resource’s collaboration layer.
* **`organizationPrivate`**: Only users in the same organization as the resource can access it.
* **`restricted`**: Only explicitly permitted users can access the resource.
#### APIs (backend)
* **Folder:** Use [Update Folder Access Type](/api-reference/rest-apis/v2/folders/update-folder-access).
* **Document:** Use [Update Document Access Type](/api-reference/rest-apis/v2/documents/update-document-access).
* **Defaults:** Update default access across your app.
Go to the App Config in the Velt Console: [console.velt.dev](https://console.velt.dev/dashboard/config/appconfig)
Select the desired default access type for new resources and save your changes.
**Access Types = who can access. Roles = what they can do once they have access.** These controls are orthogonal and compose together.
### 3. Roles
Roles define **what** an allowed user can do on a resource:
* **Editor:** Read and write access to collaboration features data for the given resource. **This is the default role.**
* **Viewer:** Read-only access to collaboration features data for the given resource.
Assign or override roles per resource via your backend when granting permissions. Frontend SDK methods cannot set or change `accessRole`.
#### APIs
* [**Add users**](/api-reference/rest-apis/v2/users/add-users)
* [**Remove users**](/api-reference/rest-apis/v2/users/delete-users)
* [**Generate token**](/api-reference/rest-apis/v2/auth/generate-token) (to be used during login)
* [**Add permissions**](/api-reference/rest-apis/v2/auth/add-permissions)
* [**Remove permissions**](/api-reference/rest-apis/v2/auth/remove-permissions)
### 4. Permissions
Permissions control which users can access and collaborate on specific resources in your app. They determine what actions users can perform on organizations, folders, and documents.
Permissions are determined by a combination of the resource's **access type** and the user's **role**.
There are 3 ways to configure permissions in Velt. Choose the approach that best fits your app's architecture:
a. [On-Demand Permissions](#a-on-demand-permissions): Grant or revoke permissions **at runtime** when a user logs in or navigates to a resource.
b. [Synced Permissions](#b-synced-permissions): Periodically or event‑driven sync between your app and Velt. Do an initial bulk load, then keep up with adds/removes/role changes.
c. [Real-time Permission Provider](#c-real-time-permission-provider): With this approach, Velt pings your defined endpoint to verify whether a user should be granted access to a resource (organization, folder, or document). This ensures that your backend is still the source of truth and you don't have to sync the permissions into Velt directly.
### a. On-Demand Permissions
Grant or revoke permissions **at runtime** when a user logs in or navigates to a resource.
* Best when your app has a very complex and granular permissioning system and you want to keep your system as the source of truth.
* Supports temporary (time-bound) access and permanent access, enabling ad‑hoc sharing and expiring invites.
#### Temporary vs. Permanent Access
* **Temporary access**: Grant permissions with an expiry or revoke after session/end of task (e.g., guest reviewers, contractors). Use this when access should automatically end or be short‑lived.
* **Permanent access**: Grant durable permissions for members or long‑term collaborators. Use this when roles rarely change and should persist across sessions.
#### APIs
* [**Add Permissions**](/api-reference/rest-apis/v2/auth/add-permissions)
* **When user logs in**: Use an auth provider with JWT token to grant permissions to the organization present in the `User` object in the auth provider. ([Generate token](/api-reference/rest-apis/v2/auth/generate-token)).
* **When user sets documents**: Call [Add Permissions API](/api-reference/rest-apis/v2/auth/add-permissions) to grant or adjust access for the set of documents or folders in the `setDocuments` method.
* [**Remove Permissions**](/api-reference/rest-apis/v2/auth/remove-permissions)
* Revoke access when the user signs out, loses membership, or navigates away from folder/document using [Remove Permissions API](/api-reference/rest-apis/v2/auth/remove-permissions).
When you include `organizationId` in the identify/auth payload, Velt automatically creates and associates the user with that organization. This happens because the "Auto-create Organization Users" console setting is **enabled by default**. To change this default behavior, [go to Console under App Configuration -> Auto-create Organization User](https://console.velt.dev/dashboard/config/appconfig)
### b. Synced Permissions
* Periodically or event‑driven sync between your app and Velt.
* Do an initial bulk load, then keep up with adds/removes/role changes.
#### APIs
* [**Add users**](/api-reference/rest-apis/v2/users/add-users)
* **Initial sync:** Bulk add existing users so they appear in mentions and can be permissioned.
* **Ongoing sync:** When a user is added or granted permissions to additional resources in your app, call this API to sync that change in Velt.
* [**Remove users**](/api-reference/rest-apis/v2/users/delete-users)
* **Ongoing sync:** When a user is removed or their permissions are revoked to resources in your app, call this API to sync that change in Velt.
When you include `organizationId` in the identify/auth payload, Velt automatically creates and associates the user with that organization. The Auto-create Organization Users console setting is **enabled by default**, so you don't need to pre-create users for on-demand flows. [Go to Console under App Configuration -> Auto-create Organization User](https://console.velt.dev/dashboard/config/appconfig)
### c. Real-time Permission Provider
With this approach, Velt pings your defined endpoint to verify whether a user should be granted access to a resource (organization, folder, or document). This ensures that your backend is still the source of truth and you don't have to sync the permissions into Velt directly.
#### How it works
1. **Configure endpoint**: Set up your backend endpoint URL and optional auth token in the [Velt Console](https://console.velt.dev/dashboard/config/permission-provider).
2. **Initialize frontend**: Configure Permission Provider in your app using VeltProvider or [`setPermissionProvider()`](/api-reference/sdk/api/api-methods#setpermissionprovider).
3. **Automatic validation**: When users access resources (organizations, folders, documents, or contexts), Velt automatically queries your endpoint.
4. **Backend response**: Your backend checks permissions and returns access decisions.
5. **Instant enforcement**: Velt enforces the permissions immediately based on your response.
6. **Auto-revocation** (optional): Configure automatic permission cleanup when users switch documents or log out.
#### When to use
* Your app has complex, dynamic permissions that change frequently
* You want to avoid syncing permission data to an external system
* You need real-time permission validation without backend synchronization overhead
**How to Setup:**
**Step 1: Configure Endpoint in Velt Console**
1. Enable [Permission Provider in Velt Console](https://console.velt.dev/dashboard/config/permission-provider)
2. Add your POST endpoint URL (e.g., [https://yourdomain.com/api/check-permissions](https://yourdomain.com/api/check-permissions))
3. (Optional) Add auth token for request authentication
**Step 2: Implement Your Backend Endpoint**
Your backend receives permission requests from Velt, checks your authorization system, and returns access decisions.
* **Request (Velt → your endpoint)**: [PermissionQuery](/api-reference/sdk/models/data-models#permissionquery)
* **Response (your endpoint → Velt)**: [PermissionResult](/api-reference/sdk/models/data-models#permissionresult)
**Example**
```javascript expandable theme={null}
// Velt sends a POST request to your configured endpoint
fetch('https://yourdomain.com/api/check-permissions', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ${permissionProviderToken}'
},
body: JSON.stringify({
data: {
requests: [
{
userId: 'user123',
resource: {
id: 'org456',
type: 'organization',
source: 'identify',
organizationId: 'org456'
}
},
{
userId: 'user123',
resource: {
id: 'doc789',
type: 'document',
source: 'setDocuments',
organizationId: 'org456'
}
},
{
userId: 'user123',
resource: {
id: 'folder101',
type: 'folder',
source: 'setDocuments',
organizationId: 'org456'
}
},
{
userId: 'user123',
resource: {
id: 'doc789',
type: 'context',
source: 'setDocuments',
organizationId: 'org456',
context: {
access: {
entityId: 'numberOfVisitors'
}
}
}
}
]
}
})
});
```
```json expandable theme={null}
{
"data": [
{
"userId": "user123",
"resourceId": "org456",
"type": "organization",
"organizationId": "org456",
"hasAccess": true
},
{
"userId": "user123",
"resourceId": "doc789",
"type": "document",
"organizationId": "org456",
"hasAccess": true,
"accessRole": "editor",
"expiresAt": 1699876543210
},
{
"userId": "user123",
"resourceId": "folder101",
"type": "folder",
"organizationId": "org456",
"hasAccess": true
},
{
"userId": "user123",
"resourceId": "doc789",
"type": "context",
"organizationId": "org456",
"hasAccess": true
}
],
"success": true,
"statusCode": 200,
"message": "Permissions validated successfully"
}
```
```javascript expandable theme={null}
app.post('/api/check-permissions', async (req, res) => {
// Receive requests from Velt
const { requests } = req.body.data;
// Check your authorization system and build permissions array
const permissions = [];
for (const request of requests) {
let permission;
// Handle context-based permission requests
if (request.resource.type === 'context') {
const hasAccess = await yourAuthSystem.checkContextAccess(
request.userId,
request.resource.id,
request.resource.context.access
);
permission = {
userId: request.userId,
resourceId: request.resource.id,
type: 'context',
organizationId: request.resource.organizationId,
hasAccess: hasAccess,
};
}
// Handle standard resource permission requests
else {
const hasAccess = await yourAuthSystem.checkUserAccess(
request.userId,
request.resource.id,
request.resource.type
);
permission = {
userId: request.userId,
resourceId: request.resource.id,
type: request.resource.type,
organizationId: request.resource.organizationId,
hasAccess: hasAccess,
};
// For documents, add access role
if (request.resource.type === 'document' && hasAccess) {
permission.accessRole = await yourAuthSystem.getUserRole(
request.userId,
request.resource.id
); // 'viewer' or 'editor'
permission.expiresAt = Date.now() + 10 * 60 * 1000; // Optional: 10 min expiry
}
}
permissions.push(permission);
}
// Return response in expected format
res.json({
data: permissions,
success: true,
statusCode: 200,
message: 'Permissions validated successfully'
});
});
```
```python expandable theme={null}
@app.route('/api/check-permissions', methods=['POST'])
def check_permissions():
# Receive requests from Velt
request_data = request.json
requests_list = request_data.get('data', {}).get('requests', [])
# Check your authorization system and build permissions array
permissions = []
for req in requests_list:
# Handle context-based permission requests
if req['resource']['type'] == 'context':
has_access = your_auth_system.check_context_access(
req['userId'],
req['resource']['id'],
req['resource']['context']['access']
)
permission = {
'userId': req['userId'],
'resourceId': req['resource']['id'],
'type': 'context',
'organizationId': req['resource']['organizationId'],
'hasAccess': has_access
}
# Handle standard resource permission requests
else:
has_access = your_auth_system.check_user_access(
req['userId'],
req['resource']['id'],
req['resource']['type']
)
permission = {
'userId': req['userId'],
'resourceId': req['resource']['id'],
'type': req['resource']['type'],
'organizationId': req['resource']['organizationId'],
'hasAccess': has_access
}
# For documents, add access role
if req['resource']['type'] == 'document' and has_access:
permission['accessRole'] = your_auth_system.get_user_role(
req['userId'],
req['resource']['id']
) # 'viewer' or 'editor'
permission['expiresAt'] = int(time.time() * 1000) + 10 * 60 * 1000 # Optional: 10 min expiry
permissions.append(permission)
# Return response in expected format
return jsonify({
'data': permissions,
'success': True,
'statusCode': 200,
'message': 'Permissions validated successfully'
})
```
**Step 3: Configure Permission Provider Behavior in your Frontend**
Configure Permission Provider behavior in your frontend using [`setPermissionProvider()`](/api-reference/sdk/api/api-methods#setpermissionprovider).
**Configuration Options:**
View the complete [`VeltPermissionProvider` schema](/api-reference/sdk/models/data-models#veltpermissionprovider) for all available options.
* `isContextEnabled`: Enable context-based permission requests for granular access control per context value. Default: `false`
* `retryConfig`: Configure retry attempts and delays for failed permission requests. Default: 3 retries with 2000ms delay. See [`AuthRetryConfig`](/api-reference/sdk/models/data-models#authretryconfig)
* `forceRefresh`: Force re-validation on each access check when permissions change frequently. Default: `false`
* `revokeAccessOn`: Configure automatic access revocation on specific events (e.g., document unset, user logout).
You can configure the Permission Provider in two ways:
Option 1: In VeltProvider (Recommended)
```jsx expandable theme={null}
{/* Your app */}
```
Option 2: Using setPermissionProvider()
```jsx expandable theme={null}
const { client } = useVeltClient();
client.setPermissionProvider({
isContextEnabled: true,
retryConfig: { retryCount: 3, retryDelay: 2000 },
forceRefresh: false,
});
```
When using `setPermissionProvider()` method, call it before `identify()`, `setAuthProvider()`, and `setDocument()` methods to ensure proper initialization.
When using `setPermissionProvider()` method, call it before `identify()`, `setAuthProvider()`, and `setDocument()` methods to ensure proper initialization.
```javascript theme={null}
Velt.setPermissionProvider({
isContextEnabled: true,
retryConfig: { retryCount: 3, retryDelay: 2000 },
forceRefresh: false,
});
```
**Step 4: Configure Auto Revoke Access (optional)**
* Automatically revoke permissions when specific events occur, providing better control over user access and security.
* Access is automatically revoked from both cache and backend when triggered. This ensures immediate permission removal without requiring manual cleanup.
* Context access is only revoked when the user logs out and not at document unset.
**Configuration Options:**
* `type`: [`RevokeAccessOnType`](/api-reference/sdk/models/data-models#revokeaccessontype)
* `document_unset`: Revokes access when user unsets or leaves a document
* `user_logout`: Revokes access when user logs out
* `revokeOrganizationAccess`: Set to `true` to also revoke organization-level permissions (default: `false`)
**Option 1: In VeltProvider (Recommended)**
```jsx expandable theme={null}
{/* Your app */}
```
**Option 2: Using setPermissionProvider()**
```jsx expandable theme={null}
const { client } = useVeltClient();
// Example 1: Revoke access on document unset only
client.setPermissionProvider({
revokeAccessOn: {
type: 'document_unset',
revokeOrganizationAccess: false
}
});
// Example 2: Revoke all access including organization on user logout
client.setPermissionProvider({
revokeAccessOn: {
type: 'user_logout',
revokeOrganizationAccess: true // Also revoke organization permissions
}
});
```
Context-level access is only revoked on user logout, not on document unset.
```javascript expandable theme={null}
// Example 1: Revoke access on document unset only
Velt.setPermissionProvider({
revokeAccessOn: {
type: 'document_unset',
revokeOrganizationAccess: false
}
});
// Example 2: Revoke all access including organization on user logout
Velt.setPermissionProvider({
revokeAccessOn: {
type: 'user_logout',
revokeOrganizationAccess: true // Also revoke organization permissions
}
});
```
**Permission Provider Events**
[**On()**](/api-reference/sdk/api/api-methods#on-5)
Monitor permission checks by subscribing to Permission Provider events. These are the sub-event types you can receive:
| Sub-Event Type | Description | Event Object |
| -------------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
| `resourceAccessRequestFormed` | Triggered when a permission request is formed internally before being sent | [PermissionProviderEvent](/api-reference/sdk/models/data-models#permissionproviderevent) |
| `resourceAccessRequestTriggered` | Triggered when a permission request is actually triggered and sent | [PermissionProviderEvent](/api-reference/sdk/models/data-models#permissionproviderevent) |
| `resourceAccessResult` | Triggered when a permission check result is received from your server | [PermissionProviderEvent](/api-reference/sdk/models/data-models#permissionproviderevent) |
| `resourceAccessError` | Triggered when an error occurs during permission checking | [PermissionProviderEvent](/api-reference/sdk/models/data-models#permissionproviderevent) |
| `resourceAccessResultFromCache` | Triggered when a permission result is retrieved from cache instead of making a new request | [PermissionProviderEvent](/api-reference/sdk/models/data-models#permissionproviderevent) |
| `revokeAccessOnDocumentUnsetTriggered` | Triggered when permissions are automatically revoked due to document unset trigger | [RevokeAccessEvent](/api-reference/sdk/models/data-models#revokeaccessevent) |
| `revokeAccessOnUserLogoutTriggered` | Triggered when permissions are automatically revoked due to user logout trigger | [RevokeAccessEvent](/api-reference/sdk/models/data-models#revokeaccessevent) |
**Using React Hook**
```jsx expandable theme={null}
import { useVeltEventCallback } from '@veltdev/react';
function PermissionMonitor() {
// Subscribe to all permission provider events
useVeltEventCallback('permissionProvider', (event) => {
console.log('Permission provider event:', event);
});
// Event payload example for resourceAccessRequestTriggered:
// {
// "event": "resourceAccessRequestTriggered",
// "timestamp": 1761580810137,
// "methodName": "onResourceAccessRequired",
// "source": "internal",
// "payload": {
// "requests": [
// {
// "userId": "1.1",
// "resource": {
// "id": "org1",
// "type": "organization",
// "source": "identify"
// }
// }
// ],
// "fromCache": false
// }
// }
// Event payload example for resourceAccessResult:
// {
// "event": "resourceAccessResult",
// "timestamp": 1761580811228,
// "methodName": "onResourceAccessRequired",
// "source": "internal",
// "payload": {
// "result": {
// "data": [
// {
// "userId": "1.1",
// "resourceId": "org1",
// "type": "organization",
// "hasAccess": true
// }
// ],
// "success": true,
// "statusCode": 200,
// "signature": "811824052c1ea76f22fc67b36ca5dd867b89d4efeb85cf648bbbc0d2c0675545"
// }
// }
// }
// Event payload example for revokeAccessOnDocumentUnsetTriggered:
// {
// "event": "revokeAccessOnDocumentUnsetTriggered",
// "timestamp": 1761580810137,
// "payload": {
// "userId": "user_123",
// "documentId": "doc_456",
// "organizationId": "org_789",
// "revokeOrganizationAccess": false
// }
// }
// Event payload example for revokeAccessOnUserLogoutTriggered:
// {
// "event": "revokeAccessOnUserLogoutTriggered",
// "timestamp": 1761580810137,
// "payload": {
// "userId": "user_123",
// "organizationId": "org_789",
// "revokeOrganizationAccess": true
// }
// }
return Monitoring permission events...
;
}
```
**Using Client Method**
```jsx expandable theme={null}
const { client } = useVeltClient();
// Subscribe to all permission provider events
client.on('permissionProvider').subscribe(event => console.log(event));
// Event payload example for resourceAccessRequestFormed:
// {
// "event": "resourceAccessRequestFormed",
// "methodName": "identify",
// "timestamp": 1761580810137,
// "source": "internal",
// "payload": {
// "requests": [
// {
// "userId": "1.1",
// "resource": {
// "id": "org1",
// "type": "organization",
// "source": "identify"
// }
// }
// ]
// }
// }
// Event payload example for resourceAccessRequestTriggered:
// {
// "event": "resourceAccessRequestTriggered",
// "timestamp": 1761580810137,
// "methodName": "onResourceAccessRequired",
// "source": "internal",
// "payload": {
// "requests": [
// {
// "userId": "1.1",
// "resource": {
// "id": "org1",
// "type": "organization",
// "source": "identify"
// }
// }
// ],
// "fromCache": false
// }
// }
// Event payload example for resourceAccessResult:
// {
// "event": "resourceAccessResult",
// "timestamp": 1761580811228,
// "methodName": "onResourceAccessRequired",
// "source": "internal",
// "payload": {
// "result": {
// "data": [
// {
// "userId": "1.1",
// "resourceId": "org1",
// "type": "organization",
// "hasAccess": true
// }
// ],
// "success": true,
// "statusCode": 200,
// "signature": "811824052c1ea76f22fc67b36ca5dd867b89d4efeb85cf648bbbc0d2c0675545"
// }
// }
// }
// Event payload example for revokeAccessOnDocumentUnsetTriggered:
// {
// "event": "revokeAccessOnDocumentUnsetTriggered",
// "timestamp": 1761580810137,
// "payload": {
// "userId": "user_123",
// "documentId": "doc_456",
// "organizationId": "org_789",
// "revokeOrganizationAccess": false
// }
// }
// Event payload example for revokeAccessOnUserLogoutTriggered:
// {
// "event": "revokeAccessOnUserLogoutTriggered",
// "timestamp": 1761580810137,
// "payload": {
// "userId": "user_123",
// "organizationId": "org_789",
// "revokeOrganizationAccess": true
// }
// }
```
```javascript theme={null}
// Subscribe to all permission provider events
Velt.on('permissionProvider').subscribe(event => console.log(event));
// Event payload example for resourceAccessRequestFormed:
// {
// "event": "resourceAccessRequestFormed",
// "methodName": "identify",
// "timestamp": 1761580810137,
// "source": "internal",
// "payload": {
// "requests": [
// {
// "userId": "1.1",
// "resource": {
// "id": "org1",
// "type": "organization",
// "source": "identify"
// }
// }
// ]
// }
// }
// Event payload example for resourceAccessRequestTriggered:
// {
// "event": "resourceAccessRequestTriggered",
// "timestamp": 1761580810137,
// "methodName": "onResourceAccessRequired",
// "source": "internal",
// "payload": {
// "requests": [
// {
// "userId": "1.1",
// "resource": {
// "id": "org1",
// "type": "organization",
// "source": "identify"
// }
// }
// ],
// "fromCache": false
// }
// }
// Event payload example for resourceAccessResult:
// {
// "event": "resourceAccessResult",
// "timestamp": 1761580811228,
// "methodName": "onResourceAccessRequired",
// "source": "internal",
// "payload": {
// "result": {
// "data": [
// {
// "userId": "1.1",
// "resourceId": "org1",
// "type": "organization",
// "hasAccess": true
// }
// ],
// "success": true,
// "statusCode": 200,
// "signature": "811824052c1ea76f22fc67b36ca5dd867b89d4efeb85cf648bbbc0d2c0675545"
// }
// }
// }
// Event payload example for revokeAccessOnDocumentUnsetTriggered:
// {
// "event": "revokeAccessOnDocumentUnsetTriggered",
// "timestamp": 1761580810137,
// "payload": {
// "userId": "user_123",
// "documentId": "doc_456",
// "organizationId": "org_789",
// "revokeOrganizationAccess": false
// }
// }
// Event payload example for revokeAccessOnUserLogoutTriggered:
// {
// "event": "revokeAccessOnUserLogoutTriggered",
// "timestamp": 1761580810137,
// "payload": {
// "userId": "user_123",
// "organizationId": "org_789",
// "revokeOrganizationAccess": true
// }
// }
```
### d. Set Feature Level Permissions using Access Context
Access Context allows you to set granular, feature-level permissions using custom metadata. When configured, new feature data is added and existing feature data is fetched only for the access context values the current user has access to.
#### How it works
Access Context enables you to control access to specific features (like comments, notifications) based on custom metadata fields. For example, you could restrict comment visibility based on `widgetId`, `dashboardId`, or any custom field relevant to your application.
**Matching Logic:**
* When multiple fields are present in the context, Velt checks access for each field combination
* When multiple array values exist in each field, each value creates a separate permission request
* A user must have access to **all** fields in a context to view the associated feature data
* The access context supports up to **200 items** total
#### Configuration Steps
**Step 1: Add Access Context to Features**
You need to add access context metadata to your features on both frontend and backend.
**Frontend:**
If you add access context to comments, other features associated with it (like notifications) will automatically inherit the same access context.
When a comment annotation is added, attach the access context using the `addContext()` method. Pass a **string or number** for each context field:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
event.addContext({
access: {
widgetId: 2 // Pass string or number, not array
}
});
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.on('addCommentAnnotation').subscribe((event) => {
event.addContext({
access: {
widgetId: 2 // Pass string or number, not array
}
});
});
```
**Backend:**
If you are adding comments or notifications using REST APIs, you can use the following:
Use the REST API to add access context when creating comments programmatically:
```json theme={null}
POST /v2/comments
{
"data": {
"organizationId": "org1",
"documentId": "document1",
"commentText": "This is a comment",
"context": {
"access": {
"widgetId": 2
}
}
}
}
```
Use the REST API to add access context when creating notifications:
```json theme={null}
POST /v2/notifications
{
"data": {
"organizationId": "org1",
"documentId": "document1",
"notificationText": "New update available",
"context": {
"access": {
"dashboardId": "dashboard1"
}
}
}
}
```
**Step 2: Enable Context-Based Permissions**
Enable access context permission validation by setting `isContextEnabled: true` in your Permission Provider configuration. When enabled, the Permission Provider will receive individual requests for each context value, allowing you to control access at a granular level for features like comments and notifications.
Option 1: In VeltProvider (Recommended)
```jsx expandable theme={null}
{/* Your app */}
```
Option 2: Using setPermissionProvider()
```jsx expandable theme={null}
const { client } = useVeltClient();
client.setPermissionProvider({
isContextEnabled: true, // Enable context-based permissions for notifications
retryConfig: {
retryCount: 3,
retryDelay: 2000
},
forceRefresh: false,
revokeAccessOn: [
{
type: "document_unset",
revokeOrganizationAccess: false
},
{
type: "user_logout",
revokeOrganizationAccess: true
}
]
});
```
```js expandable theme={null}
Velt.setPermissionProvider({
isContextEnabled: true, // Enable context-based permissions for notifications
retryConfig: {
retryCount: 3,
retryDelay: 2000
},
forceRefresh: false,
revokeAccessOn: [
{
type: "document_unset",
revokeOrganizationAccess: false
},
{
type: "user_logout",
revokeOrganizationAccess: true
}
]
});
```
**Step 3: Subscribe to documents with specific Access Context**
Add access context when subscribing to documents. Pass the access context values as arrays in `setDocuments()`. Each value will generate a separate permission request:
**Context to Permission Conversion:** When you pass arrays of context values in `setDocuments()`, Velt automatically converts them to individual permission requests. For example, `entityId: ['value1', 'value2']` becomes two separate requests with `entityId: 'value1'` and `entityId: 'value2'`.
```jsx expandable theme={null}
const { client } = useVeltClient();
client.setDocuments(documents, {
context: {
access: {
widgetId: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] // Up to 200 items total
}
}
});
```
```js expandable theme={null}
Velt.setDocuments(documents, {
context: {
access: {
widgetId: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] // Up to 200 items total
}
}
});
```
**Example Request to Your Permission Provider Endpoint:**
```json expandable theme={null}
{
"data": {
"requests": [
{
"userId": "1.1",
"resource": {
"id": "document1",
"type": "document",
"source": "setDocuments",
"organizationId": "org1"
}
},
{
"userId": "1.1",
"resource": {
"id": "{\"widgetId\":1}",
"type": "context",
"source": "setDocuments",
"organizationId": "org1",
"context": {
"access": { "widgetId": 1 }
}
}
},
{
"userId": "1.1",
"resource": {
"id": "{\"widgetId\":2}",
"type": "context",
"source": "setDocuments",
"organizationId": "org1",
"context": {
"access": { "widgetId": 2 }
}
}
}
// ... more context items
]
}
}
```
**Example Response from Your Endpoint:**
```json expandable theme={null}
{
"data": [
{
"userId": "1.1",
"resourceId": "document1",
"type": "document",
"hasAccess": true,
"organizationId": "org1"
},
{
"userId": "1.1",
"resourceId": "{\"widgetId\":1}",
"type": "context",
"hasAccess": true,
"organizationId": "org1"
},
{
"userId": "1.1",
"resourceId": "{\"widgetId\":2}",
"type": "context",
"hasAccess": false,
"organizationId": "org1"
}
// ... more context results
],
"success": true,
"statusCode": 200
}
```
### Query Permissions
The following APIs can be used to query user permissions regardless of which permission approach you're using (On-Demand, Synced, or Real-time Permission Provider).
#### Backend API
[**Get Permissions**](/api-reference/rest-apis/v2/auth/get-permissions): Query a user's effective permissions/roles for the given resources. This returns what permissions your user has according to Velt.
#### Frontend APIs
##### getUserPermissions()
One-time fetch that returns a promise with the current user's permissions.
* **Params:** `request?`: [GetUserPermissionsRequest](/api-reference/sdk/models/data-models#getuserpermissionsrequest)
* **Returns:** `Promise<`[GetUserPermissionsResponse](/api-reference/sdk/models/data-models#getuserpermissionsresponse)`>`
```ts theme={null}
const request = {
organizationId: 'org_123',
folderIds: ['folder_1', 'folder_2'],
documentIds: ['doc_1', 'doc_2']
};
const permissions = await client.getUserPermissions(request);
```
```js theme={null}
const request = {
organizationId: 'org_123',
folderIds: ['folder_1', 'folder_2'],
documentIds: ['doc_1', 'doc_2']
};
const permissions = await Velt.getUserPermissions(request);
```
##### getCurrentUserPermissions()
Subscribe to real-time permission updates for the current authenticated user. Returns an observable that emits whenever permissions change.
* **Params:** None
* **Returns:** `Observable<`[GetUserPermissionsResponse](/api-reference/sdk/models/data-models#getuserpermissionsresponse)`>`
```ts theme={null}
const subscription = client.getCurrentUserPermissions().subscribe((permissions) => {
console.log('Current user permissions:', permissions);
});
// Cleanup when done
subscription.unsubscribe();
```
```js theme={null}
const subscription = Velt.getCurrentUserPermissions().subscribe((permissions) => {
console.log('Current user permissions:', permissions);
});
// Cleanup when done
subscription.unsubscribe();
```
**Response Structure:**
Both APIs return the same response format:
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"user_123": {
"documents": {
"document1": {
"accessRole": "editor"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
},
"context": {
"accessFields": ["widgetId:1", "widgetId:2", "widgetId:3"]
}
}
}
}
}
```
See the [API Reference](/api-reference/sdk/api/api-methods#getcurrentuserpermissions) for detailed method documentation.
# Customize Behavior
Source: https://docs.velt.dev/live-co-editing/customize-behavior
# Customize UI
Source: https://docs.velt.dev/live-co-editing/customize-ui
# Overview
Source: https://docs.velt.dev/live-co-editing/overview
Live Co-Editing is still in beta. If you would like to test it out please email [support@velt.dev](mailto:support@velt.dev) to get setup.
## Live Co-Editing
`Live Co-editing` enables Enable seamless co-editing experience in your app. We sync & merge your app state across all clients.
# Setup
Source: https://docs.velt.dev/live-co-editing/setup
# MCP Servers (Beta)
Source: https://docs.velt.dev/mcp/mcp
## Overview
We provide two MCP servers:
* [REST APIs MCP Server](#rest-apis-mcp-server): Allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc.
* [Docs MCP Server](#docs-mcp-server): Allows you to search and browse Velt's documentation directly within your MCP-compatible IDEs, like Cursor, Windsurf etc. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt.
## Supported MCP Clients
The MCP server is compatible with any client that supports MCP. Here are few examples:
* [Cursor](https://www.cursor.com/)
* [Windsurf](https://windsurf.dev/)
* [Claude Desktop](https://www.anthropic.com/products/claude-desktop)
## REST APIs MCP Server
This allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc.
### Tools
The MCP server exposes **all** the [Velt REST APIs](/api-reference/rest-apis) as tools.
Below you will find links to different collections of APIs:
* [Organizations](/api-reference/rest-apis/v2/organizations/add-organizations)
* [Folders](/api-reference/rest-apis/v2/folders/add-folder)
* [Documents](/api-reference/rest-apis/v2/documents/get-documents-v2)
* [Users](/api-reference/rest-apis/v2/users/get-users-v2)
* [User Groups](/api-reference/rest-apis/v2/user-groups/add-groups)
* [Comments](/api-reference/rest-apis/v2/comments-feature/comments/get-comments)
* [Notifications](/api-reference/rest-apis/v2/notifications/get-notifications-v2)
* [Live State](/api-reference/rest-apis/v2/livestate/broadcast-event)
* [Workspace](/api-reference/rest-apis/v2/workspace/add-domain)
### Setup
You can set up the REST API MCP Server using any of the following methods. Note you will be required to provide your Velt API key and Velt Auth token to the MCP server.
#### Using Smithery CLI
The easiest way to get started is by using the `@smithery/cli` package installer. This will automatically download and configure the MCP server for your chosen client.
You can visit: [https://smithery.ai/server/@velt-js/velt-api-mcp](https://smithery.ai/server/@velt-js/velt-api-mcp) to see the list of clients supported by the MCP server and steps to install it. Here are some examples:
```bash theme={null}
npx -y @smithery/cli install @velt-js/velt-api-mcp --client claude
```
```bash theme={null}
npx -y @smithery/cli install @velt-js/velt-api-mcp --client cursor
```
```bash theme={null}
npx -y @smithery/cli install @velt-js/velt-api-mcp --client windsurf
```
```bash theme={null}
npx -y @smithery/cli install @velt-js/velt-api-mcp --client cline
```
```bash theme={null}
npx -y @smithery/cli install @velt-js/velt-api-mcp --client vscode
```
#### Manual Configuration
If you prefer to configure the server manually, follow these steps.
1. **Install the Server Package:**
```bash theme={null}
npm i @veltdev/api-mcp
```
2. **Configure your client:**
Here are some examples:
1) Open Claude Desktop.
2) Go to **Settings > Developer > Edit Config**.
3) Add the following configuration to the `mcpServers` section in your config file. Make sure to replace the placeholder values.
```json theme={null}
{
"mcpServers": {
"velt-api-mcp": {
"command": "node",
"args": ["/dist/index.js"],
"env": {
"VELT_API_KEY": "",
"VELT_AUTH_TOKEN": ""
}
}
}
}
```
4) Save the configuration file.
5) Restart Claude Desktop. The `velt-api-mcp` server will now be available in the tools menu.
1. Open Cursor.
2. Go to **Cursor Settings → Tools & Integrations → New MCP Server**.
3. Add the following configuration, replacing the placeholders with the full path to the server and your Velt secrets.
```json theme={null}
{
"mcpServers": {
"velt-api-mcp": {
"command": "node",
"args": ["/dist/index.js"],
"env": {
"VELT_API_KEY": "",
"VELT_AUTH_TOKEN": ""
}
}
}
}
```
4. Ensure the server is enabled in the MCP List.
1. Open Windsurf.
2. Go to **Windsurf Settings → Manage Plugins → View Raw Config**.
3. Add the following configuration, replacing the placeholders with the full path to the server and your Velt secrets.
```json theme={null}
{
"mcpServers": {
"velt-api-mcp": {
"command": "node",
"args": ["/dist/index.js"],
"env": {
"VELT_API_KEY": "",
"VELT_AUTH_TOKEN": ""
}
}
}
}
```
4. Ensure the server is enabled in the MCP List.
### Use cases
Once configured, you can interact with the Velt API through your MCP client. Here are some examples:
1. **Querying Velt Data:**
* How many comments are there in this organization: ORGANIZATION\_ID?
* Provide a list of users in the this organization: ORGANIZATION\_ID.
* Give me a list of all open comments in this organization: ORGANIZATION\_ID.
* Get all notifications for this user: USER\_ID.
* and more...
2. **Adding or updating sample data:**
* Add, update or delete comments in a given document.
* Add notification for a given user.
* and more...
3. **Analysis:**
If you are using an agentic client like Cursor, you can also ask questions like:
* What are users discussing in comments in this organization: ORGANIZATION\_ID?
* Categorize the comments as bugs, feature requests, questions, etc in this organization: ORGANIZATION\_ID.
* and more...
4. **Debugging:**
* Add a comment using SDK and ask the MCP to fetch the comment.
* Tag a user in a comment using SDK and ask the MCP to fetch the notification for the user.
* and more...
5. **Use it as a tool for your AI Agent:**
* You could review a document (eg: essay, report, etc) and ask the Velt MCP to add comments providing contextual feedback on the document.
* Here is a sample code of using MCP tool in AI agent with Google AI SDK:
```python theme={null}
TARGET_FOLDER_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "")
root_agent = Agent(
name="AI Comment Agent",
model="gemini-2.5-flash",
description="Agent that adds comments for the product",
instruction="""
You are a reviewer who will review the text given and add the comment to improve the content
""",
tools=[
MCPToolset(
connection_params=StdioServerParameters(
command='npx',
args=[
"-y",
"@veltdev/api-mcp",
os.path.abspath(TARGET_FOLDER_PATH),
],
stderr=subprocess.STDOUT,
timeout=60,
env={
"VELT_API_KEY": api_key,
"VELT_AUTH_TOKEN": auth_token,
}
),
tool_filter=[
'get-comment-annotations',
'get-comments',
'add-comments',
'update-comments',
'delete-comments',
'add-comment-annotations',
'update-comment-annotations',
'delete-comment-annotations',
]
)
],
)
```
## Docs MCP Server
The Velt Docs MCP Server allows you to search and browse Velt's documentation directly within your MCP-compatible client, like Cursor, Windsurf, Claude Desktop and more. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt.
### Setup
To use the Velt Docs MCP server with Claude:
1. Navigate to the [Connectors](https://claude.ai/settings/connectors) page in the Claude settings.
2. Select **Add custom connector**.
3. Add the Velt Docs MCP server:
* Name: `Velt`
* URL: `https://docs.velt.dev/mcp`
4. Select **Add**.
1. When using Claude, select the attachments button (the plus icon).
2. Select the Velt Docs MCP server.
3. Ask Claude a question about Velt.
See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server#connecting-to-a-remote-mcp-server) for more details.
To use the Velt Docs MCP server with Claude Code, run the following command:
```bash theme={null}
claude mcp add --transport http Velt https://docs.velt.dev/mcp
```
Test the connection by running:
```bash theme={null}
claude mcp list
```
See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.
Install in Cursor
To connect the Velt Docs MCP server to Cursor, follow these steps:
1. Use Command + Shift + P (Ctrl + Shift + P on Windows) to open the command palette.
2. Search for "Open MCP settings".
3. Select **Add custom MCP**. This will open the `mcp.json` file.
In `mcp.json`, add:
```json theme={null}
{
"mcpServers": {
"Velt": {
"url": "https://docs.velt.dev/mcp"
}
}
}
```
In Cursor's chat, ask "What tools do you have available?" Cursor should show the Velt Docs MCP server as an available tool.
See [Installing MCP servers](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) in the Cursor documentation for more details.
Install in VS Code
To connect the Velt Docs MCP server to VS Code, click the **Install in VS Code** button. Or to manually connect the MCP server, create a `.vscode/mcp.json` file and add:
```json theme={null}
{
"servers": {
"Velt": {
"type": "http",
"url": "https://docs.velt.dev/mcp"
}
}
}
```
See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.
### Example Usage
Once the Velt Docs MCP Server is configured, you can use it to search for documentation from your client.
For example, in Cursor, you can use questions like `how to add Velt popover comments?` in the chat to ask questions about Velt.
**Query:**
`how to add Velt popover comments?`
**Result:**
The MCP will return relevant documentation pages and snippets related to adding popover comments, allowing you to quickly access the information you need.
**More examples:**
* `Generate sample data for adding Velt comment annotations via Velt Rest API`
# Managing Different Environments
Source: https://docs.velt.dev/migration/environments
Manage production, staging, and development environments with Velt API keys
Each API key in Velt represents a separate environment with completely isolated data and settings.
## Environment types
### Production
When you upgrade to a production plan, you receive a production API key.
#### Setup in 4 quick steps
##### **1. Upgrade your plan**
Select a production plan in the Velt Console. A production API key is generated automatically.
##### **2. Configure production environment**
Manually replicate your staging configurations:
* Feature settings
* UI customization
* Webhooks
* Permissions
##### **3. Update your application**
Replace the development API key with your production API key in all locations.
Update environment variables, config files, and any hardcoded references.
##### **4. Test**
Verify all features work with the production API key before going live.
#### **Regional keys (Enterprise only)**
Enterprise customers can create production API keys for specific regions to reduce latency and meet data residency requirements. See [Supported Regions](/security/supported-regions) for all available regions.
Example use cases:
* North America key for US/Canadian users
* EU key for GDPR compliance
* Additional regional keys as needed
### Staging and development
Create up to **10 API keys** for non-production environments. Use these for:
* Staging environments per team or feature
* Individual developer environments
* Testing and QA
# Migrate from Cord to Velt
Source: https://docs.velt.dev/migration/migrate-from-cord-to-velt
Cord has shut down their service. We are providing a migration path for all the Cord users to migrate to Velt.
## Migration Process Overview
* Download the cord data in JSON format using their REST APIs. Send it to us using a secure file-sharing system.
* We have an internal service written to transform that data and add it to your Velt account. You need not use our APIs for this. We will do it for you.
* It will take about a week for the end-to-end migration process. We can expedite it to be 1-2 days if it's more urgent for you.
* If you prefer, we can also help you migrate over to Velt on production over a weekend so that your customers don't notice any changes.
## Migration Steps
Give us access to a test account in your app where Cord is implemented. It should contain some cord comments.
Export the Cord data from the above test account and send it to us. [Learn more](#exporting-cord-data)
We will migrate that small sample first and verify it with you.
Once everything looks good, you will send all of the Cord data as JSON files. We will do a test run on the entire dataset.
Schedule a migration date: On this date, all your cord production data (as of this date) with Velt implemented in your app will go live.
## Exporting Cord Data
### Note:
* These APIs have pagination built-in and return 1000 entries by default. Either extend the limit or loop over the pages to get all the data.
* Send data pulled from each API in a separate JSON file.
## Comments
Use the following Cord REST APIs to pull all the comments-related data and export it as a JSON file:
• [Threads](https://docs.cord.com/rest-apis/threads)
• [Messages](https://docs.cord.com/rest-apis/messages)
• [Users](https://docs.cord.com/rest-apis/users)
• [Groups](https://docs.cord.com/rest-apis/groups)
## Comment File Attachments
When you pull thread and message data using the above APIs, the file attachment URL is also present in the data. However, those URLs expire. You have two options for migration:
**Option 1**: You can use the URL to download the files and upload them to your cloud. Send us the new file attachment URLs in the following format in a JSON file:
Sample Format:
```jsx theme={null}
[{
"documentId": "",
"userId": "",
"messageId": "",
"type": "file",
"fileData": {
"id": "",
"type": "file",
"name": "",
"url": "",
"mimeType": "MIME_TYPE",
"size": 6278949,
"uploadStatus": "uploaded"
},
"fileUrl": ""
}]
```
**Option 2**: Schedule file migration date with us so you can pull the latest comments data, which will have fresh file access tokens. Then we can download/store it on our end, and update the URLs ourselves.
## Notifications
Given the ephemeral nature of notifications, we don't think you need to migrate them. However, if you do want us to migrate your notifications data, you could use this API to get the notifications data from Cord:
* [Notifications](https://docs.cord.com/rest-apis/notifications)
# Migrate from Liveblocks to Velt
Source: https://docs.velt.dev/migration/migrate-from-liveblocks-to-velt
For customers facing limitations with Liveblocks (eg: features, security, pricing, etc.), we provide an easy path to migrate to Velt.
## Migration Process Overview
* Export your Liveblocks data in JSON format using [their REST APIs](https://liveblocks.io/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads) and send it to us through a secure file-sharing system.
* You have two options for migration: (1) Transform the data yourself and use [our REST APIs](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations) to migrate it, or (2) Send us the raw Liveblocks data and we'll handle the transformation and migration for you.
* The complete migration process typically takes about a week or so.
* We can coordinate the production migration over a weekend to ensure zero downtime and a seamless transition for your users.
## Migration Steps
Provide us with access to a test account in your application where Liveblocks is currently implemented. This test account should contain existing Liveblocks comments and collaboration data for validation purposes.
Export the Liveblocks data from your test account and securely share it with us. This allows us to understand your data structure and perform initial validation. [Learn more](#exporting-liveblocks-data)
We will perform a migration on your sample data and work with you to verify that all comments, user data, and collaboration features have been accurately migrated to Velt.
After successful validation of the test migration, export your complete Liveblocks production dataset as JSON files. We will perform a comprehensive test migration on the full dataset to ensure data integrity.
Schedule your production migration date. On the agreed date, we will migrate all your Liveblocks production data to Velt and coordinate the go-live process to ensure a seamless transition for your users.
## Exporting Liveblocks Data
### Comments
Use the following Liveblocks REST APIs to pull all the comments-related data and export it as a JSON file:
• [Threads](https://liveblocks.io/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads)
• [Comments](https://liveblocks.io/docs/api-reference/rest-api-endpoints#get-rooms-roomId-threads-threadId-comments-commentId)
### Users
Use the following Liveblocks REST APIs to pull all the users-related data and export it as a JSON file:
• [Users](https://liveblocks.io/docs/api-reference/rest-api-endpoints#get-rooms-roomId-active-users)
### Notifications
Given the ephemeral nature of notifications, we don't think you need to migrate them. However, if you do want us to migrate your notifications data, you could use this API to get the notifications data from Liveblocks:
* [Notifications](https://liveblocks.io/docs/api-reference/rest-api-endpoints#get-users-userId-inboxNotifications)
# Parts
Source: https://docs.velt.dev/permission-management/share-and-invite/customize-ui/parts
We offer several parts which can be used like classes. Full list below.
The component is encapsulated in Shadow DOM, which is isolated from the normal DOM.
Set whatever CSS rules you want.
The part lets you target a specific element within a Shadow DOM.
Reference the table below to see what parts we expose.
Alternatively, you can directly inspect the component HTML to see what parts are available.
| property | description |
| ------------------ | ----------------------------------------- |
| `container` | Targets the comment tool container |
| `button-container` | Targets the comment tool button container |
| `button-icon` | Targets the comment tool button SVG icon |
```css Tool theme={null}
velt-user-invite-tool::part(button-icon) {
width: 1.5rem;
height: 1.5rem;
}
```
# Slots
Source: https://docs.velt.dev/permission-management/share-and-invite/customize-ui/slots
Provide a template for the User Invite Tool.
Target the `button` slot with your own custom template.
```js theme={null}
User Invite
```
Provide a template for the User Invite Tool.
Target the `button` slot with your own custom template.
```html theme={null}
User Invite
```
```js React / Next.js theme={null}
import {
VeltUserInviteTool
} from '@veltdev/react';
export default function App() {
return (
<>
User Invite
);
}
```
```html HTML theme={null}
User Invite documentation
User Invite
```
# Variables
Source: https://docs.velt.dev/permission-management/share-and-invite/customize-ui/variables
To update CSS variables for the User Invite Tool, please refer to [Global Styles](/global-styles/global-styles)
# Invite
Source: https://docs.velt.dev/permission-management/share-and-invite/overview
A widget to invite others to collaborate together on a project
Import the `VeltUserInviteTool` component
```js theme={null}
import { VeltUserInviteTool } from '@veltdev/react';
```
Place the component wherever you want the invite button to appear.
```js theme={null}
Place the component wherever you want the invite button to appear.
```html theme={null}
```js React / Next.js theme={null}
import { VeltUserInviteTool } from '@veltdev/react';
function YourComponent() {
return (
//
Collaboration App
# Overview
Source: https://docs.velt.dev/realtime-collaboration/crdt/overview
CRDT (Yjs) based collaborative editing.
CRDT (Yjs) based collaborative editing. This feature is useful for building collaborative features like shared forms, whiteboards, or any real-time state that needs to be synced across all users.
* This is framework agnostic.
* Use our [Core guide](./setup/core) to create custom integrations if a purpose built library is not listed below
* Out of box support for the following libraries:
* [Tiptap Editor](./setup/tiptap)
* [ReactFlow](./setup/reactflow)
* [CodeMirror](./setup/codemirror)
* [BlockNote](./setup/blocknote)
* Lexical (coming soon)
## What you can build
* **Collaborative text editing**: rich text editors, notes, documents
* **Visual collaboration**: whiteboards, diagrams, flow editors
* **Shared app state**: forms, lists, dashboards synchronized across users
## Packages at a glance
* **Core library (`@veltdev/crdt`)**: Framework-agnostic CRDT stores (array, map, text, xml), versioning, subscriptions, and syncing via the Velt client. See setup: [`Core`](./setup/core).
* **React Hook Wrapper (`@veltdev/crdt-react`)**: A typed React hook for creating and consuming CRDT stores with minimal boilerplate. See setup: [`Core`](./setup/core).
* **Editor integrations**:
* **Tiptap**: Collaborative text editing with cursors and history. See setup: [`Tiptap`](./setup/tiptap).
* **ReactFlow**: Collaborative node/edge graphs. See setup: [`ReactFlow`](./setup/reactflow).
* **CodeMirror**: Collaborative code editing. See setup: [`CodeMirror`](./setup/codemirror).
* **BlockNote**: Collaborative block-based editor. See setup: [`BlockNote`](./setup/blocknote).
## Why Velt CRDT
* **Conflict‑free sync**: Yjs ensures eventual consistency without merge conflicts.
* **Low latency, offline‑first**: Local writes with automatic re‑sync when back online.
* **Batteries included**: Version history, subscriptions, presence, and editor integrations.
* **Use anywhere**: Core library for any framework; React Hook wrapper for the fastest React integration.
## Key capabilities
* **Low latency**: Optimized for snappy, real-time updates.
* **Offline-first**: Local-first reads/writes with automatic re-sync when back online.
* **Conflict-free**: Yjs CRDT ensures eventual consistency without merge conflicts.
* **Multi-tab support**: Same user can edit in multiple tabs simultaneously with full synchronization.
* **Version history**: Create checkpoints and restore prior states when needed.
* **Framework agnostic**: Use anywhere; React hook available for faster integration.
## How it works
* You initialize the Velt client in your app.
* You create a CRDT store (core or via the React hook) with a unique `id` and a data `type`.
* Components subscribe to the store to render the latest value and push updates.
* Yjs merges concurrent edits; Velt handles synchronization between connected clients.
## Choose your path
* **React apps**: Start with the React Hook wrapper in [`setup/core`](./setup/core#react-hook-wrapper-%40veltdev%2Fcrdt-react) (React tab).
* **Other frameworks / vanilla**: Use the core library in [`setup/core`](./setup/core#other-frameworks-%40veltdev%2Fcrdt) (Non‑React tab).
* **Rich editors**: Follow the dedicated guides for [`Tiptap`](./setup/tiptap), [`ReactFlow`](./setup/reactflow), [`CodeMirror`](./setup/codemirror), and [`BlockNote`](./setup/blocknote).
## Try it yourself!
```bash theme={null}
npm install @veltdev/blocknote-crdt-react
```
```txt theme={null}
Docs coming soon
```
### Step 2: Setup Velt
Initialize the Velt client by following the [Velt Setup Docs](/get-started/quickstart). This is required for the collaboration engine to work.
### Step 3: Initialize Velt CRDT Extension
* Initialize the Velt CRDT extension and use it to initialize the BlockNote editor.
* Pass an `editorId` to uniquely identify each editor instance you have in your app. This is especially important when you have multiple editors in your app.
```jsx theme={null}
const { collaborationConfig } = useVeltBlockNoteCrdtExtension({
editorId: 'YOUR_EDITOR_ID',
initialContent: JSON.stringify([{ type: "paragraph", content: "" }])
});
const editor = useCreateBlockNote({
collaboration: collaborationConfig,
}, [collaborationConfig]);
return (
```txt theme={null}
Docs coming soon
```
## Notes
* **Unique editorId**: Use a unique `editorId` per editor instance.
* **Pass collaborationConfig**: Provide an `editor` and key with collaborationConfig to BlockNote.
## Testing and Debugging
**To test collaboration:**
1. Login two unique users on two browser profiles and open the same page in both.
2. Edit in one window and verify changes and cursors appear in the other.
**Common issues:**
* Cursors not appearing: Ensure each editor has a unique `editorId` and users are authenticated. Also ensure that you are logged in with two different users in two different browser profiles.
* Editor not loading: Confirm the Velt client is initialized and the API key is valid.
Use the [VeltCrdtStoreMap debugging interface](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap) to inspect and monitor your CRDT stores in real-time from the browser console.
## Complete Example
See [Velt BlockNote Demo Repo](https://github.com/velt-js/velt-blocknote-crdt-demo) for our complete implementation.
```jsx Complete Implementation expandable lines theme={null}
import '@blocknote/core/fonts/inter.css';
import { BlockNoteView } from "@blocknote/mantine";
import '@blocknote/mantine/style.css';
import { useCreateBlockNote } from "@blocknote/react";
import { useVeltBlockNoteCrdtExtension } from "@veltdev/blocknote-crdt-react";
import React from "react";
const BlockNoteCollaborativeEditor: React.FC = () => {
const { collaborationConfig, isLoading } = useVeltBlockNoteCrdtExtension({
editorId: 'YOUR_EDITOR_ID',
initialContent: JSON.stringify([{ type: "paragraph", content: "" }])
});
// Now call the hook at top level with the config
const editor = useCreateBlockNote({
collaboration: collaborationConfig,
// Add any other static options here
}, [collaborationConfig]); // Deps ensure re-init if config changes
return (
<>
{!isLoading ? 'Connected to collaborative session' : 'Connecting to collaborative session...'}
);
};
export default BlockNoteCollaborativeEditor;
```
[Open in larger window](https://velt-blocknote-crdt-demo.vercel.app/)
## APIs
### Custom Encryption
You can encrypt CRDT data before it’s stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of type `Uint8Array | number[]`.
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
client.setEncryptionProvider(encryptionProvider);
```
See also: [setEncryptionProvider()](/api-reference/sdk/api/api-methods#setencryptionprovider-encryptionprovider)
· [VeltEncryptionProvider](/api-reference/sdk/models/data-models#veltencryptionprovider)
· [EncryptConfig](/api-reference/sdk/models/data-models#encryptconfig)
· [DecryptConfig](/api-reference/sdk/models/data-models#decryptconfig)
### [useVeltBlockNoteCrdtExtension()](/api-reference/sdk/api/api-methods#useveltblocknotecrdtextension)
Provides real-time collaborative BlockNote editor functionality with Yjs and Velt SDK synchronization.
* Signature: useVeltBlockNoteCrdtExtension(config: VeltBlockNoteCrdtExtensionConfig)
* Params: [VeltBlockNoteCrdtExtensionConfig](/api-reference/sdk/models/data-models#veltblocknotecrdtextensionconfig)
* `editorId`: Unique identifier for the editor instance.
* `initialContent`: Initial content for the editor.
* `debounceMs`: Debounce time for update propagation (ms).
* Returns: [VeltBlockNoteCrdtExtensionResponse](/api-reference/sdk/models/data-models#veltblocknotecrdtextensionresponse)
* `collaborationConfig`: Configuration object to pass into BlockNote.
* `store`: BlockNote CRDT store instance.
* `isLoading`: Whether the store is initialized. `false` once store is initialized, `true` by default.
### Store Methods
#### [store.getStore()](/api-reference/sdk/api/api-methods#getstore)
Access the underlying CRDT store managing document state.
* Returns: Store
```js theme={null}
const crdtStore = store.getStore();
```
#### [store.destroy()](/api-reference/sdk/api/api-methods#destroy)
Tear down the store and clean up listeners/resources.
* Returns: void
```js theme={null}
store.destroy();
```
#### [store.getYDoc()](/api-reference/sdk/api/api-methods#getydoc)
Accessor for the underlying Yjs document.
* Returns: Y.Doc
```jsx theme={null}
const ydoc = store.getYDoc();
```
#### [store.getYXml()](/api-reference/sdk/api/api-methods#getyxml)
Returns the Y.XmlFragment instance that handles Tiptap's rich text structure.
* Returns: Y.XmlFragment | null
```jsx theme={null}
const yxml = store.getYXml();
```
# CodeMirror Editor
Source: https://docs.velt.dev/realtime-collaboration/crdt/setup/codemirror
Setup Multiplayer Editing for CodeMirror Editor.
The `@veltdev/codemirror-crdt-react` library enables real-time collaborative editing on CodeMirror Editors. The collaboration editing engine is built on top of [Yjs](https://docs.yjs.dev/) and Velt SDK.
## Prerequisites
* Node.js (v14 or higher)
* React (v16.8 or higher for hooks)
* A Velt account with an API key ([sign up](https://console.velt.dev/))
* Optional: TypeScript for type safety
## Setup
### Step 1: Install Dependencies
Install the required packages:
```bash theme={null}
npm install @veltdev/codemirror-crdt-react @veltdev/react
```
```bash theme={null}
npm install @veltdev/codemirror-crdt @veltdev/client y-codemirror.next
```
### Step 2: Setup Velt
Initialize the Velt client by following the [Velt Setup Docs](/get-started/quickstart). This is required for the collaboration engine to work.
### Step 3: Initialize Velt CRDT Extension
* Initialize the Velt CRDT extension and use it to initialize the CodeMirror editor.
* Pass an `editorId` to uniquely identify each editor instance you have in your app. This is especially important when you have multiple editors in your app.
```jsx theme={null}
// Initialize the Velt CRDT extension
const { store, isLoading } = useVeltCodeMirrorCrdtExtension({ editorId });
useEffect(() => {
if (!store || !editorRef.current) return;
const startState = EditorState.create({
doc: store.getYText()?.toString() ?? '',
extensions: [
basicSetup,
yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() }),
],
});
viewRef.current = new EditorView({
state: startState,
parent: editorRef.current,
});
return () => viewRef.current?.destroy();
}, [store]);
```
```js theme={null}
// Create the CRDT store
const store = await createVeltCodeMirrorStore({
editorId: editorId,
veltClient: veltClient,
});
// Create editor state with yCollab extension
const startState = EditorState.create({
doc: store.getYText()?.toString() ?? '',
extensions: [
basicSetup,
yCollab(store.getYText(), store.getAwareness(), {
undoManager: store.getUndoManager(),
}),
],
});
// Create editor view
const view = new EditorView({
state: startState,
parent: editorContainer,
});
```
## Notes
* **Unique editorId**: Use a unique `editorId` per editor instance.
* **Wait for auth**: Initialize the store only after the Velt client is ready.
* **Use yCollab**: Pass the store's Yjs text, awareness, and undo manager to `yCollab`.
* **Initialize and clean up**: Destroy the `EditorView` and store on unmount to avoid leaks.
## Testing and Debugging
**To test collaboration:**
1. Login two unique users on two browser profiles and open the same page in both.
2. Edit in one window and verify changes and cursors appear in the other.
**Common issues:**
* Cursors not appearing: Ensure each editor has a unique `editorId` and users are authenticated. Also ensure that you are logged in with two different users in two different browser profiles.
* Editor not loading: Confirm the Velt client is initialized and the API key is valid.
* Disconnected session: Check network.
Use the [VeltCrdtStoreMap debugging interface](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap) to inspect and monitor your CRDT stores in real-time from the browser console.
## Complete Example
[Open Live Demo In Larger Window](https://sample-apps-codemirror-crdt-demo.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/react/crdt/text-editors/codemirror/codemirror-crdt-demo)
```jsx Complete Implementation expandable lines theme={null}
// Import required modules
import { useVeltCodeMirrorCrdtExtension } from "@veltdev/codemirror-crdt-react";
import { yCollab } from "y-codemirror.next";
import { EditorState } from "@codemirror/state";
import { basicSetup, EditorView } from "codemirror";
// Add hook in your codemirror editor component
const { store, isLoading } = useVeltCodeMirrorCrdtExtension({ editorId });
useEffect(() => {
if (!store || !editorRef.current) return;
// Clean up existing view if any
viewRef.current?.destroy();
const startState = EditorState.create({
doc: store.getYText()?.toString() ?? '',
extensions: [
basicSetup,
autocompletion(),
yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() }),
],
});
viewRef.current = new EditorView({
state: startState,
parent: editorRef.current,
});
return () => {
viewRef.current?.destroy();
viewRef.current = null;
};
}, [store]);
```
[Open Live Demo In Larger Window](https://sample-apps-codemirror-non-react-cr.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/javascript/crdt/text-editors/codemirror/codemirror-crdt-demo)
```js Complete Implementation expandable lines theme={null}
// Import required modules
import { initVelt } from '@veltdev/client';
import { createVeltCodeMirrorStore } from '@veltdev/codemirror-crdt';
import { yCollab } from 'y-codemirror.next';
import { EditorState } from '@codemirror/state';
import { basicSetup, EditorView } from 'codemirror';
// Step 1: Initialize Velt client
const veltClient = await initVelt('YOUR_API_KEY');
// Step 2: Authenticate user
await veltClient.identify({ userId: 'user-1', name: 'John Doe' });
// Step 3: Set document
await veltClient.setDocument('my-document-id');
// Step 4: Create CRDT store
const store = await createVeltCodeMirrorStore({
editorId: 'velt-codemirror-crdt-demo',
veltClient: veltClient,
});
// Step 5: Create CodeMirror editor
const startState = EditorState.create({
doc: store.getYText()?.toString() ?? '',
extensions: [
basicSetup,
yCollab(store.getYText(), store.getAwareness(), {
undoManager: store.getUndoManager(),
}),
],
});
const view = new EditorView({
state: startState,
parent: document.getElementById('editor'),
});
// Cleanup on unmount
view.destroy();
store.destroy();
```
[Open Live Demo In Larger Window](https://sample-apps-codemirror-crdt-demo.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/react/crdt/text-editors/codemirror/codemirror-crdt-demo)
[Open Live Demo In Larger Window](https://sample-apps-codemirror-non-react-cr.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/javascript/crdt/text-editors/codemirror/codemirror-crdt-demo)
## APIs
### Custom Encryption
You can encrypt CRDT data before it’s stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of type `Uint8Array | number[]`.
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
client.setEncryptionProvider(encryptionProvider);
```
See also: [setEncryptionProvider()](/api-reference/sdk/api/api-methods#setencryptionprovider-encryptionprovider)
· [VeltEncryptionProvider](/api-reference/sdk/models/data-models#veltencryptionprovider)
· [EncryptConfig](/api-reference/sdk/models/data-models#encryptconfig)
· [DecryptConfig](/api-reference/sdk/models/data-models#decryptconfig)
### Initialization
#### [useVeltCodeMirrorCrdtExtension()](/api-reference/sdk/api/api-methods#useveltcodemirrorcrdtextension)
React hook that provides real-time collaborative editing on CodeMirror editor with Yjs and Velt SDK.
* Signature: `useVeltCodeMirrorCrdtExtension(config: VeltCodeMirrorCrdtExtensionConfig)`
* Params: [VeltCodeMirrorCrdtExtensionConfig](/api-reference/sdk/models/data-models#veltcodemirrorcrdtextensionconfig)
* `editorId`: Unique identifier for the editor instance.
* `initialContent`: Initial content for the editor.
* `debounceMs`: Debounce time for update propagation (ms).
* Returns: [VeltCodeMirrorCrdtExtensionResponse](/api-reference/sdk/models/data-models#veltcodemirrorcrdtextensionresponse)
* `store`: CodeMirror CRDT store instance.
* `isLoading`: Whether the store is initialized. `false` once store is initialized, `true` by default.
```jsx theme={null}
const { store, isLoading } = useVeltCodeMirrorCrdtExtension({
editorId: 'velt-codemirror-crdt-demo'
});
```
#### [createVeltCodeMirrorStore()](/api-reference/sdk/api/api-methods#createveltcodemirrorstore)
Factory function that creates and initializes a `VeltCodeMirrorStore` instance for collaborative editing.
* Signature: `createVeltCodeMirrorStore(config: VeltCodeMirrorStoreConfig): Promise`
* Params: `VeltCodeMirrorStoreConfig`
* `editorId`: Unique identifier for the editor instance.
* `veltClient`: Velt client instance (from `initVelt()`).
* `initialContent`: Optional initial content for the editor.
* `debounceMs`: Optional debounce time for update propagation (ms).
* Returns: `Promise` - The store instance or null if creation fails.
```js theme={null}
import { createVeltCodeMirrorStore } from '@veltdev/codemirror-crdt';
const store = await createVeltCodeMirrorStore({
editorId: 'velt-codemirror-crdt-demo',
veltClient: client,
initialContent: '// Start coding...',
});
```
### Store Methods
#### [store.getStore()](/api-reference/sdk/api/api-methods#getstore)
Get the underlying `Store` that manages document state and synchronization.
* Returns: `Store`
```ts theme={null}
const underlying = store.getStore();
```
#### [store.getYDoc()](/api-reference/sdk/api/api-methods#getydoc)
Access the Yjs document used for collaborative editing.
* Returns: `Y.Doc`
```ts theme={null}
const ydoc = store.getYDoc();
```
#### [store.getYText()](/api-reference/sdk/api/api-methods#getytext)
Get the shared Y.Text bound to the current CodeMirror document.
* Returns: `Y.Text | null`
```ts theme={null}
const docText = store.getYText()?.toString() ?? '';
```
#### [store.getAwareness()](/api-reference/sdk/api/api-methods#getawareness)
Access the Yjs Awareness instance associated with the store.
* Returns: `Awareness`
```ts theme={null}
yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() });
```
#### [store.getUndoManager()](/api-reference/sdk/api/api-methods#getundomanager)
Access the Yjs UndoManager for collaborative undo/redo.
* Returns: `Y.UndoManager`
```ts theme={null}
const extensions = [
basicSetup,
yCollab(store.getYText()!, store.getAwareness(), { undoManager: store.getUndoManager() }),
];
```
#### [store.destroy()](/api-reference/sdk/api/api-methods#destroy)
Cleans up all resources, listeners, and destroys the store instance. Call this when unmounting the editor to prevent memory leaks.
* Returns: `void`
```ts theme={null}
// Cleanup when done
store.destroy();
```
# Core
Source: https://docs.velt.dev/realtime-collaboration/crdt/setup/core
Setup Multiplayer Editing for any frameworks or custom implementations.
## Introduction
Use these guides to add Yjs-based CRDT to your project with Velt. Pick the React Hook wrapper for the fastest integration in React apps, or the core library for other frameworks and custom implementations.
## Setup
### Step 1: Install Dependencies
**npm:**
```bash theme={null}
npm install @veltdev/crdt-react @veltdev/crdt @veltdev/react
```
**yarn:**
```bash theme={null}
yarn add @veltdev/crdt-react @veltdev/crdt @veltdev/react
```
**npm:**
```bash theme={null}
npm install @veltdev/crdt @veltdev/client
```
**yarn:**
```bash theme={null}
yarn add @veltdev/crdt @veltdev/client
```
### Step 2: Initialize Velt in your app
Initialize the Velt client by following the [Velt Setup Docs](/get-started/quickstart). This is required for the collaboration engine to work.
### Step 3: Initialize a CRDT store
```jsx theme={null}
import { useVeltCrdtStore } from '@veltdev/crdt-react';
function Component() {
const { store } = useVeltCrdtStore({
id: 'my-collab-note',
type: 'text',
initialValue: 'Hello, world!',
});
return null;
}
```
```ts theme={null}
import { createVeltStore } from '@veltdev/crdt';
import { initVelt } from '@veltdev/client';
const veltClient = await initVelt('YOUR_API_KEY');
const store = await createVeltStore({
id: 'my-document',
type: 'text', // 'array' | 'map' | 'text' | 'xml'
initialValue: 'Hello, world!',
veltClient,
});
```
### Step 4: Set or update the store value
Set or update local changes to the store.
```jsx theme={null}
import { useVeltCrdtStore } from '@veltdev/crdt-react';
function Component() {
const { update } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
const onChange = (e) => update(e.target.value);
return
```ts theme={null}
store.update('Hello, collaborative world!');
```
### Step 5: Listen for changes
Listen and subscribe for updates from local and remote peers.
```jsx theme={null}
import { useEffect } from 'react';
import { useVeltCrdtStore } from '@veltdev/crdt-react';
function Component() {
const { value } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
useEffect(() => {
console.log('Updated value:', value);
}, [value]);
return null;
}
```
```ts theme={null}
const unsubscribe = store.subscribe((newValue) => {
console.log('Updated value:', newValue);
});
```
### Step 6: Save and restore versions
Create checkpoints and roll back when needed.
```jsx theme={null}
import { useVeltCrdtStore } from '@veltdev/crdt-react';
function Component() {
const { saveVersion, getVersions, getVersionById, setStateFromVersion } =
useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
async function onSave() {
const versionId = await saveVersion('Checkpoint');
console.log('Saved version:', versionId);
}
async function onRestoreLatest() {
const versions = await getVersions();
if (versions.length === 0) return;
const latest = versions[0];
await setStateFromVersion(latest);
}
return (
Save Version
Restore Latest
);
}
```
```ts theme={null}
const versionId = await store.saveVersion('Initial checkpoint');
const versions = await store.getVersions();
const fetched = await store.getVersionById(versionId);
if (fetched) {
await store.setStateFromVersion(fetched);
}
```
## APIs
### Custom Encryption
Encrypt CRDT data before it's stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of type `Uint8Array | number[]`.
```tsx theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
client.setEncryptionProvider(encryptionProvider);
```
See also: [setEncryptionProvider()](/api-reference/sdk/api/api-methods#setencryptionprovider-encryptionprovider)
· [VeltEncryptionProvider](/api-reference/sdk/models/data-models#veltencryptionprovider)
· [EncryptConfig](/api-reference/sdk/models/data-models#encryptconfig)
· [DecryptConfig](/api-reference/sdk/models/data-models#decryptconfig)
### Core
#### Initialization
#### [useVeltCrdtStore](/api-reference/sdk/api/api-methods#useveltcrdtstore)
React hook to create and sync a collaborative CRDT store.
* Params: [useveltcrdtstore](/api-reference/sdk/models/data-models#useveltcrdtstore)
* `id`: Unique identifier for the store.
* `type`: Type of Yjs data structure (`'text'` | `'array'` | `'map'` | `'xml'`).
* `initialValue`: Optional initial value for the store.
* `debounceMs`: Optional debounce time for update propagation (ms).
* `enablePresence`: Optional boolean to enable realtime presence tracking (default: `true`).
* Returns: Store properties and methods
```jsx theme={null}
const {
value,
versions,
store,
update,
saveVersion,
getVersions,
getVersionById,
restoreVersion,
setStateFromVersion,
} = useVeltCrdtStore({
id: 'my-collab-note',
type: 'text',
initialValue: 'Hello, world!',
debounceMs: 100,
enablePresence: true,
});
```
#### [createVeltStore](/api-reference/sdk/api/api-methods#createveltstore)
Create and initialize a collaborative CRDT store.
* Params: [StoreConfig](/api-reference/sdk/models/data-models#storeconfig\%3B)
* `id`: Unique identifier for the store.
* `type`: Type of Yjs data structure (`'text'` | `'array'` | `'map'` | `'xml'`).
* `initialValue`: Optional initial value for the store.
* `veltClient`: Velt client instance (from `initVelt()`).
* `debounceMs`: Optional debounce time for update propagation (ms).
* `enablePresence`: Optional boolean to enable realtime presence tracking (default: `true`).
* Returns: `Promise | null>`
```ts theme={null}
const store = await createVeltStore({
id: 'my-document',
type: 'text',
initialValue: 'Hello, world!',
veltClient,
debounceMs: 100,
enablePresence: true,
});
```
#### [update](/api-reference/sdk/api/api-methods#update)
Update the store value and sync to peers.
* Params: `newValue: T`
* Returns: `void`
```jsx React theme={null}
const { update } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
update('New value');
```
```ts Other Frameworks theme={null}
store.update('New Value');
```
#### [getValue](/api-reference/sdk/api/api-methods#getvalue)
Access the current store value.
##### **Get one-time current value**
**[value](/api-reference/sdk/api/api-methods#value)**
Reactive property that updates automatically when the store changes.
* Type: `T | null`
```jsx theme={null}
const { value } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
console.log(value);
```
**[getValue()](/api-reference/sdk/api/api-methods#getvalue)**
Method to retrieve the current store value.
* Returns: `T`
```ts theme={null}
const value = store.getValue();
console.log(value);
```
##### **Subscribe to value changes**
Listen for updates from local and remote peers.
Use `useEffect` with the reactive `value` property for automatic updates, or use `store.subscribe()` for manual subscriptions.
```jsx theme={null}
const { store, value } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
// Option 1: Use reactive value (recommended)
useEffect(() => {
console.log('Value changed:', value);
}, [value]);
// Option 2: Manual subscription
useEffect(() => {
if (!store) return;
const subscription = store.subscribe((newValue) => {
console.log('Updated value:', newValue);
});
return () => subscription?.();
}, [store]);
```
**[subscribe()](/api-reference/sdk/api/api-methods#subscribe)**
Subscribe to changes in the store.
* Params: `(newValue: T) => void`
* Returns: `() => void` (unsubscribe function)
```ts theme={null}
const unsubscribe = store.subscribe((newValue) => {
console.log('Updated value:', newValue);
});
// Later, to stop listening:
unsubscribe();
```
#### [store](/api-reference/sdk/api/api-methods#store)
Access the underlying Velt Store instance for advanced operations.
The underlying store instance returned by the hook.
* Type: `Store | null`
```jsx theme={null}
const { store } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
console.log(store);
```
The store instance is returned directly from `createVeltStore()`.
* Type: `Store | null`
```ts theme={null}
const store = await createVeltStore({
id: 'my-document',
type: 'text',
veltClient,
});
console.log(store);
```
#### [destroy](/api-reference/sdk/api/api-methods#destroy)
Clean up resources when done with the store.
Cleanup is handled automatically by the hook when the component unmounts. No manual cleanup is required.
```jsx theme={null}
// Cleanup happens automatically when component unmounts
const { store } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
```
Manually destroy the store to clean up resources and listeners.
* Returns: `void`
```ts theme={null}
// When done with the store
store.destroy();
```
#### [on](/api-reference/sdk/api/api-methods#on)
Subscribe to CRDT events. Currently supports the `updateData` event which fires when CRDT data changes.
* Params: `eventType: "updateData"`
* Returns: `Observable<`[`CrdtUpdateDataEvent`](/api-reference/sdk/models/data-models#crdtupdatedataevent)`>`
**Using Hook:**
```jsx theme={null}
import { useCrdtEventCallback } from "@veltdev/react";
import { useEffect } from "react";
export function YourComponent() {
// Hook: Subscribe to updateData event
const crdtUpdateData = useCrdtEventCallback("updateData");
useEffect(() => {
console.log("[CRDT] event on data change: ", crdtUpdateData);
}, [crdtUpdateData]);
return Your Component
;
}
```
**Using API:**
```jsx theme={null}
import { useVeltClient } from "@veltdev/react";
import { useEffect } from "react";
export function YourComponent() {
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const crdtElement = client.getCrdtElement();
// Subscribe to updateData event
const subscription = crdtElement.on("updateData").subscribe((eventData) => {
console.log("[CRDT] event on data change: ", eventData);
});
return () => subscription.unsubscribe();
}, [client]);
return Your Component
;
}
```
```html theme={null}
```
### Versions
#### [saveVersion](/api-reference/sdk/api/api-methods#saveversion)
Save a snapshot of the current state as a named version.
* Params: `versionName: string`
* Returns: `Promise`
```jsx theme={null}
const { saveVersion } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
await saveVersion('Checkpoint');
```
```ts theme={null}
const versionId = await store.saveVersion('Initial checkpoint');
```
#### [getVersions](/api-reference/sdk/api/api-methods#getversions)
Fetch all saved versions.
* Returns: `Promise`
**Reactive property:**
```jsx theme={null}
const { versions } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
console.log(versions);
```
**Async method:**
```jsx theme={null}
const { getVersions } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
const versions = await getVersions();
```
```ts theme={null}
const versions = await store.getVersions();
```
#### [getVersionById](/api-reference/sdk/api/api-methods#getversionbyid)
Fetch a specific version by ID.
* Params: `versionId: string`
* Returns: `Promise`
```jsx theme={null}
const { getVersionById } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
const version = await getVersionById('abc123');
```
```ts theme={null}
const version = await store.getVersionById('abc123');
```
#### [setStateFromVersion](/api-reference/sdk/api/api-methods#setstatefromversion)
Restore the store state from a specific version object.
* Params: `version: Version`
* Returns: `Promise`
```jsx theme={null}
const { setStateFromVersion } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
await setStateFromVersion(version);
```
```ts theme={null}
await store.setStateFromVersion(version);
```
#### [restoreVersion](/api-reference/sdk/api/api-methods#restoreversion)
Restore the store to a specific version using its ID.
Convenience method that fetches and restores a version in one call.
* Params: `versionId: string`
* Returns: `Promise`
```jsx theme={null}
const { restoreVersion } = useVeltCrdtStore({ id: 'my-collab-note', type: 'text' });
await restoreVersion('abc123');
```
Combine `getVersionById()` and `setStateFromVersion()` to achieve the same result.
```ts theme={null}
const version = await store.getVersionById('abc123');
if (version) {
await store.setStateFromVersion(version);
}
```
### Yjs
#### [getDoc](/api-reference/sdk/api/api-methods#getdoc)
Get the underlying Yjs document.
* Returns: `Y.Doc`
```ts theme={null}
const ydoc = store.getDoc();
```
#### [getProvider](/api-reference/sdk/api/api-methods#getprovider)
Get the provider instance for the store.
* Returns: `Provider`
```ts theme={null}
const provider = store.getProvider();
```
#### [getText](/api-reference/sdk/api/api-methods#gettext)
Get the Y.Text instance if store type is 'text'.
* Returns: `Y.Text | null`
```ts theme={null}
const ytext = store.getText();
```
#### [getXml](/api-reference/sdk/api/api-methods#getxml)
Get the Y.XmlFragment instance if store type is 'xml'.
* Returns: `Y.XmlFragment | null`
```ts theme={null}
const yxml = store.getXml();
```
### Debugging
Use the Velt Chrome Extension or the `window.VeltCrdtStoreMap` debugging interface to inspect and monitor your CRDT stores.
#### window\.VeltCrdtStoreMap
`window.VeltCrdtStoreMap` is a global debugging interface that exposes all active CRDT stores in your application. It's automatically created and maintained by the Velt CRDT library, allowing you to inspect, monitor, and debug CRDT stores from the browser console or developer tools.
#### [get()](/api-reference/sdk/api/api-methods#get)
Get a store by its ID.
* Params:
* `id` (optional): Store ID. If omitted, returns the first registered store.
* Returns: `VeltCrdtStore | undefined` - Store instance or undefined if not found
* **Store object methods:**
* `getValue()`: Get the current value from the store
* `subscribe(callback: (value: any) => void)`: Subscribe to changes in the store. Returns an unsubscribe function.
```jsx theme={null}
// Get a specific store
const store = window.VeltCrdtStoreMap.get('my-store-id');
if (store) {
console.log('Current value:', store.getValue());
}
// Get the first registered store
const firstStore = window.VeltCrdtStoreMap.get();
```
```jsx theme={null}
// Get store and inspect
const store = window.VeltCrdtStoreMap.get('editor-123');
if (store) {
// Get current value
console.log('Current value:', store.getValue());
// Subscribe to changes
store.subscribe((value) => {
console.log('Value updated:', value);
});
// Log value every second
setInterval(() => {
console.log('Current value:', store.getValue());
}, 1000);
}
```
#### [getAll()](/api-reference/sdk/api/api-methods#getall)
Get all registered stores as an object.
* Returns: `{ [id: string]: VeltCrdtStore }` - Object mapping store IDs to store instances
* **Each store object provides:**
* `getValue()`: Get the current value from the store
* `subscribe(callback: (value: any) => void)`: Subscribe to changes in the store. Returns an unsubscribe function.
```jsx theme={null}
// Get all stores
const allStores = window.VeltCrdtStoreMap.getAll();
console.log('Total stores:', Object.keys(allStores).length);
// Iterate through all stores
Object.entries(allStores).forEach(([id, store]) => {
console.log(`Store ${id}:`, store.getValue());
});
```
```jsx theme={null}
// Find all stores
const allStores = window.VeltCrdtStoreMap.getAll();
// Find stores by pattern
const editorStores = Object.keys(allStores).filter(id =>
id.startsWith('editor-')
);
console.log('Editor stores:', editorStores);
// Get specific subset
const documentStores = Object.keys(allStores).filter(id =>
id.includes('document')
);
```
```jsx theme={null}
// Monitor all stores for changes
Object.keys(window.VeltCrdtStoreMap.stores).forEach(storeId => {
const store = window.VeltCrdtStoreMap.get(storeId);
store.subscribe((value) => {
console.log(`Store "${storeId}" changed:`, value);
});
});
```
#### Events
The library dispatches custom events when stores are registered or unregistered.
##### **veltCrdtStoreRegister**
Fired when a new store is registered.
* Event Detail: `{ id: string }` - Store ID
```jsx theme={null}
window.addEventListener('veltCrdtStoreRegister', (event) => {
console.log('Store registered:', event.detail.id);
const store = window.VeltCrdtStoreMap.get(event.detail.id);
// Do something with the new store
});
```
##### **veltCrdtStoreUnregister**
Fired when a store is unregistered (destroyed).
* Event Detail: `{ id: string }` - Store ID
```jsx theme={null}
window.addEventListener('veltCrdtStoreUnregister', (event) => {
console.log('Store unregistered:', event.detail.id);
});
```
## Backend REST APIs
Use these REST API endpoints for server-side access to CRDT editor data. Useful for seeding initial content, server-side processing, backups, or integrations.
* [Get CRDT Data](/api-reference/rest-apis/v2/crdt/get-crdt-data) — fetch data for a specific editor by `editorId`, or all editors in a document by omitting it.
* [Add CRDT Data](/api-reference/rest-apis/v2/crdt/add-crdt-data) — create new CRDT editor data on the backend (errors if the `editorId` already exists).
* [Update CRDT Data](/api-reference/rest-apis/v2/crdt/update-crdt-data) — replace existing CRDT editor data; generates proper CRDT operations so connected clients pick up the change.
## Webhooks
CRDT supports webhooks for data change events. Webhooks are disabled by default. When enabled, the default debounce time is 5 seconds.
For more information on setting up webhooks, see:
* [Basic Webhooks](/webhooks/basic#crdt-events)
* [Advanced Webhooks](/webhooks/advanced#crdt)
Enabling webhooks involves two steps:
1. Enable webhooks in the [Velt Console](https://console.velt.dev/dashboard/config/webhook)
2. Enable webhooks in the frontend using the `enableWebhook()` method
### Configure Webhooks
**Step 1: Enable in Velt Console**
Configure your webhook endpoint in the [Velt Console](https://console.velt.dev/dashboard/config/webhook).
**Step 2: Enable in Frontend**
Call the `enableWebhook()` method to enable webhook notifications. You can also optionally configure the debounce time.
**Using Hook:**
```jsx theme={null}
import { useCrdtUtils } from "@veltdev/react";
import { useEffect } from "react";
export function YourComponent() {
const crdtUtils = useCrdtUtils();
useEffect(() => {
if (crdtUtils) {
// Enable webhook
crdtUtils.enableWebhook();
// Optional: Change webhook debounce time (minimum 5 seconds)
crdtUtils.setWebhookDebounceTime(10 * 1000); // 10 seconds
}
}, [crdtUtils]);
return Your Component
;
}
```
**Using API:**
```jsx theme={null}
import { useVeltClient } from "@veltdev/react";
import { useEffect } from "react";
export function YourComponent() {
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const crdtElement = client.getCrdtElement();
// Enable webhook
crdtElement.enableWebhook();
// Optional: Change webhook debounce time (minimum 5 seconds)
crdtElement.setWebhookDebounceTime(10 * 1000); // 10 seconds
}, [client]);
return Your Component
;
}
```
```html theme={null}
```
### Webhook Methods
#### enableWebhook()
Enable webhook notifications for CRDT data changes.
* Params: `void`
* Returns: `void`
#### disableWebhook()
Disable webhook notifications for CRDT data changes.
* Params: `void`
* Returns: `void`
#### setWebhookDebounceTime()
Set the debounce time for webhook notifications.
* Params: `debounceTime: number` (in milliseconds, minimum 5000ms)
* Returns: `void`
The minimum debounce time is 5 seconds (5000ms). Setting a value lower than this will use 5 seconds as the default.
### Activity Log Debounce
#### setActivityDebounceTime()
Control how long CRDT editor keystrokes are batched before a single activity log record is flushed to the [activity log feed](/async-collaboration/activity/overview). This is distinct from the webhook debounce — it governs activity log generation only.
* Params: `time: number` (milliseconds)
* Returns: `void`
* Default: 10 minutes
* Minimum enforced: 10 seconds (10,000 ms)
**Using Hook:**
```jsx theme={null}
import { useCrdtUtils } from "@veltdev/react";
import { useEffect } from "react";
export function YourComponent() {
const crdtUtils = useCrdtUtils();
useEffect(() => {
if (!crdtUtils) return;
crdtUtils.setActivityDebounceTime(30000); // 30 seconds
}, [crdtUtils]);
return Your Component
;
}
```
**Using API:**
```jsx theme={null}
import { useVeltClient } from "@veltdev/react";
import { useEffect } from "react";
export function YourComponent() {
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const crdtElement = client.getCrdtElement();
crdtElement.setActivityDebounceTime(30000); // 30 seconds
}, [client]);
return Your Component
;
}
```
```html theme={null}
```
# React Flow Editor
Source: https://docs.velt.dev/realtime-collaboration/crdt/setup/reactflow
Setup Multiplayer Editing for React Flow diagrams.
The `@veltdev/reactflow-crdt` library enables real-time collaborative editing on React Flow diagrams. The collaboration editing engine is built on top of [Yjs](https://docs.yjs.dev/) and Velt SDK.
## Prerequisites
* Node.js (v14 or higher)
* React (v16.8 or higher for hooks)
* A Velt account with an API key ([sign up](https://console.velt.dev/))
* Optional: TypeScript for type safety
## Setup
### Step 1: Install Dependencies
Install the required packages:
```bash theme={null}
npm install @veltdev/reactflow-crdt @veltdev/react
```
### Step 2: Setup Velt
Initialize the Velt client by following the [Velt Setup Docs](/get-started/quickstart). This is required for the collaboration engine to work.
### Step 3: Initialize Velt CRDT Extension
* Initialize the Velt CRDT extension and use it to initialize the React Flow diagram.
* Pass an `editorId` to uniquely identify each diagram instance you have in your app. This is especially important when you have multiple diagrams in your app.
```jsx theme={null}
const { nodes, edges, onNodesChange, onEdgesChange, onConnect } = useVeltReactFlowCrdtExtension({
editorId: 'YOUR_EDITOR_ID',
initialNodes: [{ id: '1', data: { label: 'Start' }, position: { x: 0, y: 0 } }],
initialEdges: []
});
return (
);
```
## Notes
* **Unique editorId**: Use a unique `editorId` per diagram instance.
* **Use CRDT handlers**: Always apply the store-provided `nodes`, `edges`, `onNodesChange`, `onEdgesChange`, and `onConnect`.
## Testing and Debugging
**To test collaboration:**
1. Login two unique users on two browser profiles and open the same page in both.
2. Move nodes or create connections in one window and verify they sync in the other.
**Common issues:**
* Nodes/edges not syncing: Ensure each diagram has a unique `editorId` and the Velt client is initialized. Also ensure that you are logged in with two different users in two different browser profiles.
* No updates on connect: Use the provided CRDT-aware `nodes`, `edges`, `onNodesChange`/`onEdgesChange` and `onConnect` handlers from the store.
Use the [VeltCrdtStoreMap debugging interface](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap) to inspect and monitor your CRDT stores in real-time from the browser console.
## Complete Example
[Open Live Demo In Larger Window](https://sample-apps-reactflow-demo.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/react/crdt/canvas/reactflow/reactflow-demo)
```jsx Complete Implementation expandable lines theme={null}
import {
Background,
ReactFlow,
ReactFlowProvider,
useReactFlow,
type Edge
} from '@xyflow/react';
import { useCallback, useRef } from 'react';
import { useVeltInitState } from '@veltdev/react';
import { useVeltReactFlowCrdtExtension } from '@veltdev/reactflow-crdt';
import '@xyflow/react/dist/style.css';
const initialNodes = [
{
id: '0',
type: 'input',
data: { label: 'Node' },
position: { x: 0, y: 50 },
},
];
const initialEdges: Edge[] = [];
let id = 9;
const getId = () => `${id++}`;
const nodeOrigin: [number, number] = [0.5, 0];
const AddNodeOnEdgeDrop = () => {
const { nodes, edges, onNodesChange, onEdgesChange, onConnect } = useVeltReactFlowCrdtExtension({
editorId: 'YOUR_EDITOR_ID',
initialEdges,
initialNodes,
});
const reactFlowWrapper = useRef(null);
const { screenToFlowPosition } = useReactFlow();
const onConnectEnd = useCallback(
(event: any, connectionState: any) => {
if (!connectionState.isValid) {
const id = getId();
const { clientX, clientY } = 'changedTouches' in event ? event.changedTouches[0] : event;
const newNode = {
id,
position: screenToFlowPosition({ x: clientX, y: clientY }),
data: { label: `Node ${id}` },
origin: [0.5, 0.0],
};
// Add new node using CRDT-aware change handler
onNodesChange([{ type: 'add', item: newNode }]);
// Add new edge using CRDT-aware change handler
const newEdge = {
id,
source: connectionState.fromNode.id,
target: id,
};
onEdgesChange([{ type: 'add', item: newEdge }]);
}
},
[screenToFlowPosition, onNodesChange, onEdgesChange],
);
return (
);
};
function ReactFlowComponent() {
const veltInitialized = useVeltInitState();
if (!veltInitialized) {
return Loading...
;
}
return (
);
}
export default ReactFlowComponent;
```
[Open Live Demo In Larger Window](https://sample-apps-reactflow-demo.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/react/crdt/canvas/reactflow/reactflow-demo)
## APIs
### Custom Encryption
You can encrypt CRDT data before it’s stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of type `Uint8Array | number[]`.
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
client.setEncryptionProvider(encryptionProvider);
```
See also: [setEncryptionProvider()](/api-reference/sdk/api/api-methods#setencryptionprovider-encryptionprovider)
· [VeltEncryptionProvider](/api-reference/sdk/models/data-models#veltencryptionprovider)
· [EncryptConfig](/api-reference/sdk/models/data-models#encryptconfig)
· [DecryptConfig](/api-reference/sdk/models/data-models#decryptconfig)
### [useVeltReactFlowCrdtExtension()](/api-reference/sdk/api/api-methods#useveltreactflowcrdtextension)
Provides real-time collaborative editing on React Flow diagrams with Yjs and Velt SDK.
* Signature: `useVeltReactFlowCrdtExtension(config: VeltReactFlowCrdtExtensionConfig)`
* Params: [VeltReactFlowCrdtExtensionConfig](/api-reference/sdk/models/data-models#veltreactflowcrdtextensionconfig)
* `editorId`: Unique identifier for the diagram instance.
* `initialNodes`: Initial set of nodes.
* `initialEdges`: Initial set of edges.
* `debounceMs`: Debounce time for update propagation (ms).
* Returns: [VeltReactFlowCrdtExtensionResponse](/api-reference/sdk/models/data-models#veltreactflowcrdtextensionresponse)
* `store`: React Flow CRDT store instance.
* `nodes`: Array of nodes in the diagram.
* `edges`: Array of edges in the diagram.
* `onNodesChange`: CRDT-aware handler to apply node changes.
* `onEdgesChange`: CRDT-aware handler to apply edge changes.
* `onConnect`: CRDT-aware handler to apply connect changes.
* `setNodes`: Method to set nodes
* `setEdges`: Method to set edges
### [onNodesChange()](/api-reference/sdk/api/api-methods#onnodeschange)
CRDT-aware handler to apply node changes (add/update/remove) that sync across collaborators.
* Params: [NodeChange\[\]](/api-reference/sdk/models/data-models#nodechange)
* Returns: `void`
```tsx theme={null}
onNodesChange([{ type: 'add', item: newNode }]);
```
### [onEdgesChange()](/api-reference/sdk/api/api-methods#onedgeschange)
CRDT-aware handler to apply edge changes (add/update/remove) that sync across collaborators.
* Params: [EdgeChange\[\]](/api-reference/sdk/models/data-models#edgechange)
* Returns: `void`
```tsx theme={null}
onEdgesChange([{ type: 'add', item: newEdge }]);
```
### [onConnect()](/api-reference/sdk/api/api-methods#onconnect)
CRDT-aware connect handler compatible with React Flow’s `
```bash theme={null}
npm install @veltdev/tiptap-crdt-react @tiptap/react @tiptap/starter-kit @tiptap/extension-collaboration @tiptap/extension-collaboration-cursor
```
```bash theme={null}
npm install @veltdev/tiptap-crdt @veltdev/client @tiptap/core @tiptap/starter-kit @tiptap/extension-collaboration-caret
```
### Step 2: Setup Velt
Initialize the Velt client by following the [Velt Setup Docs](/get-started/quickstart). This is required for the collaboration engine to work.
### Step 3: Initialize Velt CRDT Extension
* Initialize the Velt CRDT extension and use it to initialize the Tiptap editor.
* Pass an `editorId` to uniquely identify each editor instance you have in your app. This is especially important when you have multiple editors in your app.
```jsx theme={null}
const { VeltCrdt } = useVeltTiptapCrdtExtension({
editorId: 'YOUR_EDITOR_ID'
});
const editor = useEditor({
extensions: [
StarterKit.configure({
history: false,
}),
...(VeltCrdt ? [VeltCrdt] : []),
],
content: ''
}, [VeltCrdt]);
return
```js theme={null}
// Create the CRDT store
const store = await createVeltTipTapStore({
editorId: editorId,
veltClient: veltClient,
});
// Create TipTap editor with collaboration extensions
const editor = new Editor({
element: editorContainer,
extensions: [
StarterKit.configure({
history: false, // Disable history as CRDT handles undo/redo
}),
store.getCollabExtension(),
CollaborationCaret.configure({
provider: store.getStore().getProvider(),
user: { name: user.name, color: user.color },
}),
],
content: '',
});
```
### Step 4: Add CSS for Collaboration Cursor
* Add the following CSS to your app to style the collaboration cursor.
```css theme={null}
/* Collaboration cursor styling */
.collaboration-cursor__caret,
.collaboration-carets__caret {
border-left: 1px solid #0d0d0d;
border-right: 1px solid #0d0d0d;
margin-left: -1px;
margin-right: -1px;
pointer-events: none;
position: relative;
word-break: normal;
}
/* Render the username above the caret */
.collaboration-cursor__label,
.collaboration-carets__label {
border-radius: 3px 3px 3px 0;
color: #0d0d0d;
font-size: 12px;
font-style: normal;
font-weight: 600;
left: -1px;
line-height: normal;
padding: 0.1rem 0.3rem;
position: absolute;
top: -1.4em;
user-select: none;
white-space: nowrap;
}
```
## Notes
* **Unique editorId**: Use a unique `editorId` per editor instance.
* **Disable history**: Turn off Tiptap `history` when using collaboration.
* **Auth required**: Ensure the Velt client is initialized and user is available before starting.
## Testing and Debugging
**To test collaboration:**
1. Login two unique users on two browser profiles and open the same page in both.
2. Edit in one window and verify changes and cursors appear in the other.
**Common issues:**
* Cursors not appearing: Ensure each editor has a unique `editorId` and users are authenticated. Also ensure that you are logged in with two different users in two different browser profiles.
* Editor not loading: Confirm the Velt client is initialized and the API key is valid.
* Desynced content: Make sure Tiptap `history` is disabled when using collaboration.
Enable browser console warnings to see detailed debugging information. The Velt SDK logs helpful warnings and errors to the console that can help you troubleshoot issues quickly. You can also use the [VeltCrdtStoreMap debugging interface](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap) to inspect and monitor your CRDT stores in real-time.
## Complete Example
[Open Live Demo In Larger Window](https://sample-apps-tiptap-crdt-demo.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/react/crdt/text-editors/tiptap/tiptap-crdt-demo)
```jsx Complete Implementation expandable lines theme={null}
import { EditorContent, useEditor } from '@tiptap/react';
import StarterKit from '@tiptap/starter-kit';
import { useVeltTiptapCrdtExtension } from '@veltdev/tiptap-crdt-react';
import React from 'react';
const CollaborativeEditor: React.FC = () => {
const { VeltCrdt } = useVeltTiptapCrdtExtension({
editorId: 'velt-tiptap-crdt-demo'
});
// Initialize the editor with our collaboration extension
const editor = useEditor({
extensions: [
StarterKit.configure({
history: false,
}),
...(VeltCrdt ? [VeltCrdt] : []),
],
content: ''
}, [VeltCrdt]);
return (
{VeltCrdt ? 'Connected to collaborative session' : 'Connecting to collaborative session...'}
);
};
export default CollaborativeEditor;
```
[Open Live Demo In Larger Window](https://sample-apps-tiptap-non-react-crdt-d.vercel.app) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/javascript/crdt/text-editors/tiptap/tiptap-crdt-demo)
```js Complete Implementation expandable lines theme={null}
// Import required modules
import { initVelt } from '@veltdev/client';
import { createVeltTipTapStore } from '@veltdev/tiptap-crdt';
import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import CollaborationCaret from '@tiptap/extension-collaboration-caret';
// Step 1: Initialize Velt client
const veltClient = await initVelt('YOUR_API_KEY');
// Step 2: Authenticate user
const user = { userId: 'user-1', name: 'John Doe', color: '#3b82f6' };
await veltClient.identify(user);
// Step 3: Set document
await veltClient.setDocument('my-document-id');
// Step 4: Create CRDT store
const store = await createVeltTipTapStore({
editorId: 'velt-tiptap-crdt-demo',
veltClient: veltClient,
});
// Step 5: Create TipTap editor
const editor = new Editor({
element: document.getElementById('editor'),
extensions: [
StarterKit.configure({ history: false }),
store.getCollabExtension(),
CollaborationCaret.configure({
provider: store.getStore().getProvider(),
user: { name: user.name, color: user.color },
}),
],
content: '',
});
// Cleanup on unmount
editor.destroy();
store.destroy();
```
[Open Live Demo In Larger Window](https://sample-apps-tiptap-crdt-demo.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/react/crdt/text-editors/tiptap/tiptap-crdt-demo)
[Open Live Demo In Larger Window](https://sample-apps-tiptap-non-react-crdt-d.vercel.app/) | [View Demo Repo](https://github.com/velt-js/sample-apps/tree/main/apps/javascript/crdt/text-editors/tiptap/tiptap-crdt-demo)
## APIs
### Custom Encryption
Encrypt CRDT data before it’s stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of type `Uint8Array | number[]`.
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
```ts theme={null}
async function encryptData(config: EncryptConfig): Promise {
const encryptedData = await yourEncryptDataMethod(config.data);
return encryptedData;
}
async function decryptData(config: DecryptConfig): Promise {
const decryptedData = await yourDecryptDataMethod(config.data);
return decryptedData;
}
const encryptionProvider: VeltEncryptionProvider = {
encrypt: encryptData,
decrypt: decryptData,
};
client.setEncryptionProvider(encryptionProvider);
```
See also: [setEncryptionProvider()](/api-reference/sdk/api/api-methods#setencryptionprovider-encryptionprovider)
· [VeltEncryptionProvider](/api-reference/sdk/models/data-models#veltencryptionprovider)
· [EncryptConfig](/api-reference/sdk/models/data-models#encryptconfig)
· [DecryptConfig](/api-reference/sdk/models/data-models#decryptconfig)
### Initialization
#### [useVeltTiptapCrdtExtension()](/api-reference/sdk/api/api-methods#usevelttiptapcrdtextension)
React hook that provides real-time collaborative editing on Tiptap editor with Yjs and Velt SDK.
* Signature: `useVeltTiptapCrdtExtension(config: VeltTiptapCrdtExtensionConfig)`
* Params: [VeltTiptapCrdtExtensionConfig](/api-reference/sdk/models/data-models#velttiptapcrdtextensionconfig)
* `editorId`: Unique identifier for the editor instance.
* `initialContent`: Initial content for the editor.
* `debounceMs`: Debounce time for update propagation (ms).
* Returns: [VeltTiptapCrdtExtensionResponse](/api-reference/sdk/models/data-models#velttiptapcrdtextensionresponse)
* `VeltCrdt`: Tiptap Velt CRDT Extension.
* `store`: Tiptap CRDT store instance.
* `isLoading`: Whether the store is initialized. `false` once store is initialized, `true` by default.
```jsx theme={null}
const { VeltCrdt, store, isLoading } = useVeltTiptapCrdtExtension({
editorId: 'velt-tiptap-crdt-demo'
});
```
#### [createVeltTipTapStore()](/api-reference/sdk/api/api-methods#createvelttiptapstore)
Factory function that creates and initializes a `VeltTipTapStore` instance for collaborative editing.
* Signature: `createVeltTipTapStore(config: VeltTipTapStoreConfig): Promise`
* Params: `VeltTipTapStoreConfig`
* `editorId`: Unique identifier for the editor instance.
* `veltClient`: Velt client instance (from `initVelt()`).
* `initialContent`: Optional initial content for the editor.
* `debounceMs`: Optional debounce time for update propagation (ms).
* Returns: `Promise` - The store instance or null if creation fails.
```js theme={null}
import { createVeltTipTapStore } from '@veltdev/tiptap-crdt';
const store = await createVeltTipTapStore({
editorId: 'velt-tiptap-crdt-demo',
veltClient: client,
initialContent: 'Start collaborating...
',
});
```
#### [store.getCollabExtension()](/api-reference/sdk/api/api-methods#getcollabextension)
Get the Tiptap collaboration extension bound to the current Yjs document.
* Returns: `Extension`
```js theme={null}
const collabExtension = store.getCollabExtension();
```
### Store Methods
#### [store.getStore()](/api-reference/sdk/api/api-methods#getstore)
Access the underlying CRDT store managing document state.
* Returns: Store
```js theme={null}
const crdtStore = store.getStore();
```
#### [store.destroy()](/api-reference/sdk/api/api-methods#destroy)
Tear down the store and clean up listeners/resources.
* Returns: void
```js theme={null}
store.destroy();
```
#### [store.getYDoc()](/api-reference/sdk/api/api-methods#getydoc)
Accessor for the underlying Yjs document.
* Returns: Y.Doc
```jsx theme={null}
const ydoc = store.getYDoc();
```
#### [store.getYXml()](/api-reference/sdk/api/api-methods#getyxml)
Returns the Y.XmlFragment instance that handles Tiptap's rich text structure.
* Returns: Y.XmlFragment | null
```jsx theme={null}
const yxml = store.getYXml();
```
#### [store.setStateFromVersion()](/api-reference/sdk/api/api-methods#setstatefromversion)
Restores the document to a specific version state. Useful for implementing undo/redo functionality or version control features.
* Signature: `setStateFromVersion(version: Version): Promise`
* Params:
* `version`: The version object to restore the document to.
* Returns: `Promise`
```js theme={null}
// Restore document to a previous version
await store.setStateFromVersion(previousVersion);
```
# Customize Behavior
Source: https://docs.velt.dev/realtime-collaboration/cursors/customize-behavior
## avatarMode
* Show the user's avatar floating next to their cursor instead of their name.
* Enabling this mode will allow you to show the user's avatar in context with the cursor.
```js theme={null}
```html theme={null}
## setInactivityTime
* Set the time it takes for a user to go inactive in milliseconds.
* By default we mark a user as inactive if they do not take any action on the document within a 5 mins timeframe.
* If they unfocus the tab, we mark them inactive immediately.
```js theme={null}
```html theme={null}
## allowedElementIds
* Provide a list of element IDs where the cursors should show.
* If you provide a list of element IDs, we will only show cursors that hover over those specific elements.
* For eg: For an app with canvas and tool picker: You can whitelist the canvas ID so that the cursors are only visible on the canvas and not the tool picker.
You must pass a string into allowedElementIds instead of an object
```js theme={null}
```html theme={null}
## onCursorUserChange
* Whenever the cursor for any user changes, we emit this event with the updated list of users currently online on this document with their cursor positions.
```js theme={null}
yourMethod(cursorUsers)} />
```
```js theme={null}
if(Velt){
const cursorTag = document.querySelector('velt-cursor');
cursorTag.addEventListener('onCursorUserChange', (event) => {
console.log("onCursorUserChange", event.detail);
});
}
```
## getOnlineUsersOnCurrentDocument
* Subscribe to a list of all online users who are either active or inactive on the current document.
```jsx theme={null}
const cursorElement = client.getCursorElement();
cursorElement.getOnlineUsersOnCurrentDocument().subscribe((cursorUsers) => {
console.log("Online users: ", cursorUsers);
});
```
```jsx theme={null}
const cursorElement = Velt.getCursorElement();
cursorElement.getOnlineUsersOnCurrentDocument().subscribe((cursorUsers) => {
console.log("Online users: ", cursorUsers);
});
```
# Overview
Source: https://docs.velt.dev/realtime-collaboration/cursors/overview
Your users can view each other's cursors when interacting on the same document. This makes your app more alive. We handle the complexity of adapting the cursors to different screen sizes, differences in content etc.
Import the `VeltCursor` component.
```js theme={null}
import { VeltProvider, VeltCursor } from '@veltdev/react'
```
Add the `VeltCursor` component to the root of your app.
```js theme={null}
```
This component renders the cursors of users on the same document and location in your web app.
Note that we automatically assign different colors to users & adapt the cursors to different screen sizes and to what's actually present on the screen. So you don't have to worry about building this logic.
Test it out by opening the target page in two browsers (with one in incognito) with two different users logged in.
You should see the cursors of the users rendered as you move mouse around.
Add the `` component to the root of your app.
```html theme={null}
Note that we automatically assign different colors to users & adapt the cursors to different screen sizes and to what's actually present on the screen. So you don't have to worry about building this logic.
Test it out by opening the target page in two browsers (with one in incognito) with two different users logged in.
You should see the cursors of the users rendered as you move mouse around.
```js React / Next.js theme={null}
import { VeltProvider, VeltCursor } from '@veltdev/react';
export default function App() {
return (
);
}
```
```js HTML theme={null}
Cursors documentation
# Customize Behavior
Source: https://docs.velt.dev/realtime-collaboration/flock-mode/customize-behavior
## flockMode
* To enable `Follow Me` Mode, set the `flockMode` attribute to `true`.
* This will enable `Follow Me mode` as an option for your `Users` globally, wherever Presence is shown.
* To start the shared flock session, click on a `User's` avatar to start following them.
* Learn more about it in the [Flock Mode feature section](/realtime-collaboration/flock-mode/overview).
```js theme={null}
```html theme={null}
## onNavigate
* Use a callback for custom navigation or side-effects.
* When the leader of a `Follow Me` session navigates, we can use the React Router to update the follower's position. In the callback you will receive a `PageInfo` object.
```js theme={null}
navigate(pageInfo.path)} />
```
```js theme={null}
let onNavigateHandler = (pageInfo) => navigate(pageInfo.path);
if (presenceDOMElement) {
presenceDOMElement.addEventListener("onNavigate", onNavigateHandler);
}
```
## defaultFlockNavigation
* Disable default `Follow Me` navigation.
* Our default navigation uses window\.location.href to detect navigation. If you are handling navigation using the callback method above, you should disable our default navigation.
* Default: `true`
```js theme={null}
```html theme={null}
## startFollowingUser()
* Start following a user by passing in their user ID.
```js theme={null}
// Start following the user
presenceElement.startFollowingUser(userId);
```
```js theme={null}
presenceElement.startFollowingUser(userId);
```
## stopFollowingUser()
* Stop following a user.
* If the current user is in a `Follow Me` session, they will be removed from that session. If there are no more followers in the session, the session will be destroyed.
```js theme={null}
// Stop following the user
presenceElement.stopFollowingUser();
```
```js theme={null}
presenceElement.stopFollowingUser();
```
# Overview
Source: https://docs.velt.dev/realtime-collaboration/flock-mode/overview
This is like Figma's follow along feature. Start a shared session in a click. One person is the leader, and whatever they do - like clicking, scrolling, or navigating - happens automatically on everyone else's screen.
Enable `Follow Me` mode feature.
```js theme={null}
Test it out by opening the target page in two browsers with two different users logged in.
You should see the avatars of the users rendered where you added the `Presence` component. Now click on any avatar to start following them.
Enable `Follow Me` mode feature.
```html theme={null}
Test it out by opening the target page in two browsers with two different users logged in.
You should see the avatars of the users rendered where you added the presence component. Now click on any avatar to start following them.
```js React / Next.js theme={null}
import { VeltPresence } from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
# Customize Behavior
Source: https://docs.velt.dev/realtime-collaboration/huddle/customize-behavior
## type
* Sets the type of the `Huddle`:
* `audio`
* `video`
* `screen`
* `all`
Default: `all`
```jsx theme={null}
```html theme={null}
## chat
* Whether the ephemeral Chat feature is enabled in Huddle.
* Default: `true`
```jsx theme={null}
```html theme={null}
## flockModeOnAvatarClick
* Whether `Follow Me` Mode should start when clicking on a user's avatar in Huddle.
* Default: `false`
```jsx theme={null}
```html theme={null}
## serverFallback
* Whether Huddle should fall back to a server-side connection if peer-to-peer fails.
* Default: `true`
```jsx theme={null}
```html theme={null}
# Overview
Source: https://docs.velt.dev/realtime-collaboration/huddle/overview
Enable slack-style effortless audio, video and screen sharing discussions inside your own product. It even comes with built in chat.
Import the `Huddle` component from the React library.
```js theme={null}
import { VeltHuddle, VeltHuddleTool } from '@veltdev/react';
```
Add the `VeltHuddle` component to the root of your app.
```js theme={null}
Add the `VeltHuddleTool` component wherever you want to show the `Huddle` tool button.
Clicking on it initiates a huddle.
```js theme={null}
```
Add the `VeltHuddle` component to the root of your app.
This component is required to render `Huddle` UI components and `Huddle` users in your app.
```html theme={null}
```
Add the `VeltHuddleTool` component wherever you want to show the `Huddle` tool button.
Clicking on it initiates a `Huddle`.
```html theme={null}
```
```js React / Next.js theme={null}
import { VeltHuddle, VeltHuddleTool} from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
```
# Webhooks
Source: https://docs.velt.dev/realtime-collaboration/huddle/webhooks
The `Huddle` component will emit webhook notifications when a user creates or joins a group huddle.
To read more about how to use webhooks with our SDK, [click here](https://docs.velt.dev/webhooks/basic).
Raw Format:
```jsx theme={null}
{
"actionType": "string", // created | joined
"notificationSource": "huddle",
"actionUser": {
// UserObject
},
"metadata": {
"apiKey": "string",
"clientDocumentId": "string",
"documentId": "string",
"pageInfo": {
"baseUrl": "string",
"path": "string",
"title": "string",
"url": "string"
}
},
"platform": "sdk"
}
```
Huddle Created Raw Format Example:
```jsx theme={null}
{
"actionType": "created",
"notificationSource": "huddle",
"actionUser": {
"clientOrganizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"color": "#19bcfe",
"email": "john@trysnippyly.com",
"organizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"name": "John Smith",
"plan": "free",
"type": "signedIn",
"userId": "1",
},
"metadata": {
"apiKey": "Emcfab4ysRXaC1CZ8hmG",
"clientDocumentId": "12-4-24",
"documentId": "1856907974154638",
"locations": {
"5638605251172150": {
"location": {
"id": "location1",
"locationName": "Location 1"
},
"locationId": 5638605251172150,
"pageInfo": {
"baseUrl": "http://localhost:3000",
"path": "/",
"title": "Velt React Demo",
"url": "http://localhost:3000/"
}
}
},
"pageInfo": {
"baseUrl": "http://localhost:3000",
"path": "/",
"title": "Velt React Demo",
"url": "http://localhost:3000/"
}
},
"platform": "sdk"
}
```
Huddle Joined Raw Format Example:
```jsx theme={null}
{
"actionType": "joined",
"notificationSource": "huddle",
"actionUser": {
"clientOrganizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"color": "#ff7162",
"contacts": [
{
"email": "john@trysnippyly.com",
"name": "John Smith",
"userId": "1"
},
{
"email": "sarah@trysnippyly.com",
"name": "Sarah Wilson",
"userId": "3"
}
],
"email": "maria@trysnippyly.com",
"organizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"name": "Maria Garcia",
"plan": "paid",
"type": "signedIn",
"userId": "2",
},
"metadata": {
"apiKey": "Emcfab4ysRXaC1CZ8hmG",
"clientDocumentId": "12-4-24",
"documentId": "1856907974154638",
"pageInfo": {
"baseUrl": "http://localhost:3000",
"path": "/",
"title": "Velt React Demo",
"url": "http://localhost:3000/"
}
},
"platform": "sdk"
}
```
# Customize Behavior
Source: https://docs.velt.dev/realtime-collaboration/live-selection/customize-behavior
## enableDefaultElementsTracking
* When **enabled**,
* the SDK will track User's presence on these elements types automatically: `input`, `textarea`, `button`, `contenteditable`.
* to disable tracking on certain elements, you need to manually add an attribute `data-velt-live-selection-enabled="false"` to those elements.
* When **disabled**,
* the SDK will not track User's presence on any elements.
* to enable tracking on certain elements, you need to manually add an attribute `data-velt-live-selection-enabled="true"` to those elements.
* Default: `Enabled`.
```javascript theme={null}
const selectionElement = client.getSelectionElement();
selectionElement.enableDefaultElementsTracking();
selectionElement.disableDefaultElementsTracking();
```
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
selectionElement.enableDefaultElementsTracking();
selectionElement.disableDefaultElementsTracking();
```
## enableUserIndicator
* User indicator is the user avatar or their name label that appears on the top left or top right of the selected element.
* Default: `Enabled`.
```javascript theme={null}
const selectionElement = client.getSelectionElement();
selectionElement.enableUserIndicator();
selectionElement.disableUserIndicator();
```
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
selectionElement.enableUserIndicator();
selectionElement.disableUserIndicator();
```
## setUserIndicatorPosition
* User indicator position can be set to `start` or `end`.
* You can set it globally using API or set it locally on individual elements using attributes.
* Default: `end`.
Set globally using API:
```javascript theme={null}
const selectionElement = client.getSelectionElement();
selectionElement.setUserIndicatorPosition('start');
```
Set locally on individual elements using attributes:
```html theme={null}
...
```
Set globally using API:
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
selectionElement.setUserIndicatorPosition('start');
```
Set locally on individual elements using attributes:
```html theme={null}
...
```
## setUserIndicatorType
* User indicator type can be set to `avatar` or `label`.
* `avatar`: Displays the user avatar.
* `label`: Displays the user's name.
* You can set the type globally using API or set it locally on individual elements using attributes.
* Default: `avatar`.
Set globally using API:
```javascript theme={null}
const selectionElement = client.getSelectionElement();
selectionElement.setUserIndicatorType('label');
```
Set locally on individual elements using attributes:
```html theme={null}
...
```
Set globally using API:
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
selectionElement.setUserIndicatorType('label');
```
Set locally on individual elements using attributes:
```html theme={null}
...
```
## getLiveSelectionData
* Get the live selection data for the current document.
**Using Hook:**
```jsx theme={null}
const liveSelectionData = useLiveSelectionDataHandler();
useEffect(() => {
console.log('liveSelectionData', liveSelectionData);
}, [liveSelectionData]);
```
**Using API:**
```javascript theme={null}
const selectionElement = client.getSelectionElement();
selectionElement.getLiveSelectionData().subscribe((liveSelectionData: LiveSelectionData) => {
console.log("liveSelectionData: ", liveSelectionData);
});
```
**Using API:**
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
selectionElement.getLiveSelectionData().subscribe((liveSelectionData: LiveSelectionData) => {
console.log("liveSelectionData: ", liveSelectionData);
});
```
## setInactivityTime
Set the duration of inactivity before Live Selection indicators are removed.
API: [`setInactivityTime()`](/api-reference/sdk/api/api-methods#setinactivitytime-1)
* After the specified time of no interaction, the user's Live Selection will be hidden.
* Default: `300000` milliseconds (5 minutes).
```javascript theme={null}
const selectionElement = client.getSelectionElement();
const tenMinutesInMs = 10 * 60 * 1000; // 10 minutes
selectionElement.setInactivityTime(tenMinutesInMs);
```
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
const tenMinutesInMs = 10 * 60 * 1000; // 10 minutes
selectionElement.setInactivityTime(tenMinutesInMs);
```
# Overview
Source: https://docs.velt.dev/realtime-collaboration/live-selection/overview
Your users can see what part of the document others are interacting with in real-time.
When Live Selection is enabled, users will see the users' avatar or name, and a highlight box around the element they are interacting with.
```js theme={null}
const { client } = useVeltClient();
useEffect(() => {
if (client) {
const selectionElement = client.getSelectionElement();
selectionElement.enableLiveSelection();
selectionElement.disableLiveSelection();
}
}, [client]);
```
```js theme={null}
if (Velt) {
const selectionElement = Velt.getSelectionElement();
selectionElement.enableLiveSelection();
selectionElement.disableLiveSelection();
}
```
# Overview
Source: https://docs.velt.dev/realtime-collaboration/live-state-sync/overview
Sync and broadcast data in real-time across all connected clients.
Live State Sync allows you to share and synchronize data in real-time across all connected clients. This feature is useful for building collaborative features like shared forms, whiteboards, or any real-time state that needs to be synced across all users.
## Latency
* Extremely low latency, with typical response times no greater than 10 ms.
## Offline Support
* Optimistic local‑first reads and writes.
* Full offline support with automatic syncing when reconnected.
## Conflict Resolution
* Server timestamp-based last-write-wins strategy for automatic conflict resolution.
,
disabledActionTypes?: Set,
allowAction?: (action: any) => boolean,
liveStateDataId?: string,
};
```
You can use it to define the following fields:
* `allowedActionTypes` - allow live state syncing on specific action types only
* `disabledActionTypes` - restrict live state syncing on specific action types
* `allowAction` - custom callback method to dynamically decide to allow or disable syncing for that action. Return `true` to allow the action and `false` to restrict the action.
* `liveStateDataId` - used to set a custom string value as live state data key. If not provided, we will store data in default key.
Example:
```jsx theme={null}
const { middleware, updateLiveStateDataId } = createLiveStateMiddleware({
allowedActionTypes: new Set(['action1', 'action2']),
disabledActionTypes: new Set(['disabledAction1', 'disabledAction2']),
allowAction: (action) => {
// return true to allow this action, false to restrict this action from syncing
},
liveStateDataId: 'custom-live-state-data-id'
});
```
It is recommended to first set a custom `liveStateDataId` in the middleware configuration. You can then change it dynamically later using the `updateLiveStateDataId` method.
To set `liveStateDataId` dynamically, call the `updateLiveStateDataId` method that was previously created and exported from your store.
```jsx theme={null}
import { updateLiveStateDataId } from 'path-to-store.js';
function YourComponent() {
// You can update liveStateDataId any time based on your requirements and all the actions called after that will be synced on new ID path.
const setLiveStateDataId = (id) => {
updateLiveStateDataId(id);
}
return (
Your HTML Template
);
}
```
## Step 4: Action Data Structure
The middleware automatically adds a UTC timestamp to each synced Redux action. The action data structure includes:
```json theme={null}
{
"id": "ACTION_ID",
"action": {
"type": "ACTION_TYPE",
"payload": "ACTION_PAYLOAD" // optional
},
"timestamp": 1759745729823 // UTC timestamp in milliseconds (automatically added)
}
```
The `timestamp` field is automatically added by the middleware and represents the UTC time in milliseconds when the action was dispatched. This helps with action ordering and debugging across distributed clients.
## Complete Example
Here's a complete example showing how to set up the Redux middleware with all configuration options:
```jsx theme={null}
// store.js
import { configureStore } from "@reduxjs/toolkit";
import { createLiveStateMiddleware } from "@veltdev/react";
//create middleware and updateLiveStateDataId method
const { middleware, updateLiveStateDataId } = createLiveStateMiddleware({
allowedActionTypes: new Set(['action1', 'action2']),
disabledActionTypes: new Set(['disabledAction1', 'disabledAction2']),
allowAction: (action) => {
// return true to allow this action, false to restrict this action from syncing
},
liveStateDataId: 'custom-live-state-data-id'
});
//add middleware to your Redux store configuration
export const store = configureStore({
reducer: {
... your reducers here
},
// You just have to concat our liveStateMiddleware in store
middleware: getDefaultMiddleware => getDefaultMiddleware().concat(middleware)
});
// you can optionally export the updateLiveStateDataId method if you want to set liveStateDataId dynamically
export { updateLiveStateDataId };
```
# Setup
Source: https://docs.velt.dev/realtime-collaboration/live-state-sync/setup
# Getter and Setter Methods
### Set Live Data
The Live State Sync feature allows you to set and update shared data that syncs in real-time across all connected clients.
**Params**
* `liveStateDataId` (`string`, required): A unique string ID to identify the data
* `liveStateData` (`any serializable type`, required): The data to sync (objects, arrays, strings, numbers)
* `setLiveStateDataConfig` (`object`, optional): Configuration object
* `merge` (`boolean`): Whether to merge the data with existing data (default: `false`)
Live State data persists indefinitely until manually removed - there is no automatic cleanup.
```jsx theme={null}
const liveStateDataId = 'uniqueId'; // A unique string identifier for the data
const liveStateData = { 'key': 'value' }; // The data to be synced (can be any serializable type)
const config = { merge: true };
// Using Hooks
useSetLiveStateData(liveStateDataId, liveStateData, config);
// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.setLiveStateData(liveStateDataId, liveStateData, config);
```
```jsx theme={null}
const liveStateDataId = 'uniqueId';
const liveStateData = { 'key': 'value' }; // any type of data
const config = { merge: true };
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.setLiveStateData(liveStateDataId, liveStateData, config);
```
### Get Live Data
Get live state data by providing the unique ID used when setting the data.
**Params**
* `liveStateDataId` (`string`, required) - A unique string ID to identify the data to retrieve
* `liveStateDataConfig` (`object`, optional) - Configuration object for controlling data retrieval behavior
* `listenToNewChangesOnly` (`boolean`, optional) - Whether to only receive new changes from when the client subscribed (default: `false`)
```jsx theme={null}
const liveStateDataConfig = {
listenToNewChangesOnly: true // default is false
};
const liveStateDataId = 'uniqueId';
// Using Hooks
const liveStateData = useLiveStateData(liveStateDataId, liveStateDataConfig);
// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.getLiveStateData(liveStateDataId, liveStateDataConfig).subscribe((data) => {
// your logic here...
});
```
If using API, you can unsubscribe from the subscription after you are done:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const liveStateDataConfig = {
listenToNewChangesOnly: true // default is false
};
const liveStateDataId = 'uniqueId';
const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.getLiveStateData(liveStateDataId, liveStateDataConfig).subscribe((data) => {
// your logic here...
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
### Fetch Live Data
Fetch live state data as a Promise when you need to retrieve the current state once, rather than subscribing to ongoing changes. This is useful for initialization, conditional logic, or one-time data retrieval.
**When to use `fetchLiveStateData()` vs `getLiveStateData()`:**
* **Use `fetchLiveStateData()`** (Promise): When you need the current value once
* **Use `getLiveStateData()`** (Observable): When you want to reactively update to changes
**Params**
* `request` (`FetchLiveStateDataRequest`, optional): Configuration object
* `liveStateDataId` (`string`, optional): Unique identifier for specific data. If not provided, returns all live state data.
**Returns**
* `Promise`: Promise resolving to the live state data. Supports generic type for type safety.
**Common Use Cases:**
* Initializing state on component mount
* Checking current state before performing an action
* Loading data for server-side rendering
* One-time data retrieval without needing updates
```jsx theme={null}
// Using Hooks
const liveStateSyncElement = useLiveStateSyncUtils();
/// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();
/// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
liveStateDataId: "LIVE_STATE_DATA_ID"
});
// Using API methods
const liveStateSyncElement = client.getLiveStateSyncElement();
/// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();
/// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
liveStateDataId: "LIVE_STATE_DATA_ID"
});
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();
// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
liveStateDataId: "LIVE_STATE_DATA_ID"
});
```
### Alternative: useLiveState()
The `useLiveState()` hook provides a familiar React's `useState()` like API while automatically syncing state changes across all connected clients in real-time.
The hook accepts the following parameters:
* `id` (string, required): Unique identifier for syncing this state across clients
* `initialValue` (any, required): Initial state value
* `options` (object, optional): Configuration object with the following properties:
* `syncDuration` (number, optional): Debounce delay in milliseconds before syncing. Defaults to 50ms.
* `resetLiveState` (boolean, optional): Whether to reset server state when the hook initializes. Defaults to false.
* `listenToNewChangesOnly` (boolean, optional): When true, only receives changes that occur after subscribing and discards historical changes. Defaults to false.
**Returns**
* `[value, setValue, connectionState]`
* `value`: Current value of the data you set
* `setValue`: Function to update the data
* `connectionState`: Current server connection status
```jsx theme={null}
import { useLiveState } from "@veltdev/react";
export function MyReactComponent() {
const [counter, setCounter, serverConnectionStateInLiveState] = useLiveState ("counter", 0, {
syncDuration: 100,
resetLiveState: true,
listenToNewChangesOnly: true // receive only new changes from when the client subscribed
});
useEffect(() => {
console.log('serverConnectionStateInLiveState:', serverConnectionStateInLiveState);
}, [serverConnectionStateInLiveState]);
return (
setCounter((counter || 0) - 1)}>-
Counter: {counter}
setCounter((counter || 0) + 1)}>+
);
}
```
# Server Connection State
The server connection state indicates the current status of the connection to Velt's servers. The possible states are:
```jsx theme={null}
enum ServerConnectionState {
ONLINE = 'online', // Connected to Velt's servers
OFFLINE = 'offline', // Not connected to Velt's servers
PENDING_INIT = 'pendingInit', // Pending SDK Initialization
PENDING_DATA = 'pendingData', // Pending receiving data from server
}
```
```jsx theme={null}
// Using Hooks
const serverConnectionState = useServerConnectionStateChangeHandler();
useEffect(() => {
console.log('serverConnectionState', serverConnectionState);
}, [serverConnectionState]);
// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.onServerConnectionStateChange().subscribe((data) => {
console.log('server connection state change: ', data);
});
```
If using API, you can unsubscribe from the subscription after you are done:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.onServerConnectionStateChange().subscribe((data) => {
console.log('server connection state change: ', data);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
# Best Practices
* Keep your state data structures simple and flat when possible
* Use meaningful IDs that reflect the purpose of the data
* If using APIs, clean up subscriptions when components unmount
* Consider network latency when setting `syncDuration`
* Sync only what you need, not the entire state
* Use `listenToNewChangesOnly` when appropriate
# Customize Behavior
Source: https://docs.velt.dev/realtime-collaboration/presence/customize-behavior
# Configuration
#### inactivityTime
* Configure when a user is considered inactive after being inactive.
* These are considered as inactive:
* no mouse movement
* no keyboard activity
* This is in milliseconds.
* This will set the following fields in the presence user object:
* `onlineStatus` to `away`
* `isUserIdle` to `true`
Note about tab focus:
* If a user's tab is unfocused, we immediately update following fields in the presence user object:
* `onlineStatus` to `away`
* `isTabAway` to `true`
Default: `300000` (5 min)
```js theme={null}
```html theme={null}
#### maxUsers
* Set how many `Presence` avatars to display at a time.
* You can set this via the `maxUsers` attribute. Any extra avatars will be hidden and shown in an avatar which indicates the number of extra `Users`.
```js theme={null}
```html theme={null}
#### offlineInactivityTime
* Configure when a user is considered offline if they do not take any action on the document within the specified timeframe.
* User is also marked offline if they lose internet connection.
* This is in milliseconds.
* This will set the `onlineStatus` field in the presence user object to `offline` if they are inactive for the given time.
Default: `600000` (10 min)
```jsx theme={null}
```html theme={null}
#### self
* Whether to include yourself in the list of `Presence` users.
* Default: `true`
```js theme={null}
```html theme={null}
#### locationId
* Renders the Presence avatar if any user is active on the given `locationId`.
```js theme={null}
```html theme={null}
# Data
#### getData
* Subscribe to presence data.
* **Params:** [`PresenceRequestQuery`](/api-reference/sdk/models/data-models#presencerequestquery) (optional)
* **Returns:** [`Observable`](/api-reference/sdk/models/data-models#getpresencedataresponse)
**Using Hook:**
```jsx theme={null}
// Fetch users with status: online
const presenceData = usePresenceData({ statuses: ['online'] });
useEffect(() => {
if (presenceData && presenceData.data) {
console.log('Presence data (online users): ', presenceData.data);
}
}, [presenceData]);
// Fetch all users (no query)
const presenceData = usePresenceData();
useEffect(() => {
if (presenceData && presenceData.data) {
console.log('Presence data (all users): ', presenceData.data);
}
}, [presenceData]);
```
**Using API:**
```ts theme={null}
const presenceElement = client.getPresenceElement();
// Fetch online users
presenceElement.getData({ statuses: ['online'] }).subscribe((response: GetPresenceDataResponse) => {
console.log("Presence data (online users): ", response.data);
});
// Fetch all users (no query)
presenceElement.getData().subscribe((response: GetPresenceDataResponse) => {
console.log("Presence data (all users): ", response.data);
});
```
```ts theme={null}
const presenceElement = Velt.getPresenceElement();
// Fetch online users
presenceElement.getData({ statuses: ['online'] }).subscribe((response) => {
console.log("Presence data (online users): ", response.data);
});
// Fetch all users (no query)
presenceElement.getData().subscribe((response) => {
console.log("Presence data (all users): ", response.data);
});
```
# Event Subscription
#### on
* Subscribe to Presence Events. Here is the list of events you can subscribe to and the event objects you will receive.
| Event Type | Description | Event Object |
| ----------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `userStateChange` | Triggered when a user state changes to online, offline, or away | [PresenceUserStateChangeEvent](/api-reference/sdk/models/data-models#presenceuserstatechangeevent) |
**Using Hook:**
```jsx theme={null}
const userStateChangeEventData = usePresenceEventCallback('userStateChange');
useEffect(() => {
if (userStateChangeEventData) {
console.log('userStateChange: ', userStateChangeEventData);
}
}, [userStateChangeEventData]);
```
**Using API:**
```ts theme={null}
const presenceElement = client.getPresenceElement();
presenceElement.on("userStateChange").subscribe((data: PresenceUserStateChangeEvent) => {
console.log("userStateChange", data);
});
```
```ts theme={null}
const presenceElement = Velt.getPresenceElement();
presenceElement.on("userStateChange").subscribe((data) => {
console.log("userStateChange", data);
});
```
#### onPresenceUserClick
* This event is triggered when a user clicks on a presence avatar.
```jsx theme={null}
const onPresenceUserClickEvent = (user) => {
console.log("Clicked presence user: ", user);
}
onPresenceUserClickEvent(user)} />
```
```jsx theme={null}
const presenceTag = document.querySelector('velt-presence');
presenceTag.addEventListener('onPresenceUserClick', (event) => {
console.log("Clicked presence user: ", event.detail);
});
```
# Overview
Source: https://docs.velt.dev/realtime-collaboration/presence/overview
Your users can see other users online on the document. This makes your app feel alive.
Import the `Presence` component from the React library.
```js theme={null}
import { VeltPresence } from '@veltdev/react';
```
Add it anywhere you want to see the `User` avatars.
```js theme={null}
Test it out by opening the target page in two browsers with two different `Users` logged in.
You should see the avatars of the `Users` rendered where you added the `Presence` component.
Place the component wherever you want the avatars to appear.
```html theme={null}
Test it out by opening the target page in two browsers with two different `Users` logged in.
You should see the avatars of the `Users` rendered where you added the `Presence` component.
```js React theme={null}
import { VeltPresence } from '@veltdev/react';
export default function App() {
return (
);
}
```
```html HTML theme={null}
Presence documentation
```
# Customize Behavior
Source: https://docs.velt.dev/realtime-collaboration/single-editor-mode/customize-behavior
## enableSingleEditorMode
Enables single editor mode, allowing only one user to edit the document at a time while others remain in read-only mode.
**Params**
* `config`: (`object`, optional). Configuration object for controlling single editor mode behavior
* `customMode`: (`boolean`, optional). When true, SDK won't automatically make HTML elements read-only for viewers. You need to handle this manually with the help of other APIs listed here. (default: `false`)
* `singleTabEditor`: (`boolean`, optional). When enabled, restricts the editor to edit in only one browser tab at a time, preventing them from making changes across multiple tabs simultaneously (default: `true`)
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
// Basic usage
liveStateSyncElement.enableSingleEditorMode();
// With configuration
liveStateSyncElement.enableSingleEditorMode({
customMode: true,
singleTabEditor: false
});
```
```jsx theme={null}
// Get LiveStateSyncElement from Velt Client
const liveStateSyncElement = Velt.getLiveStateSyncElement();
// Basic usage
liveStateSyncElement.enableSingleEditorMode();
// With configuration
liveStateSyncElement.enableSingleEditorMode({
customMode: true,
singleTabEditor: false
});
```
## disableSingleEditorMode
Disables single editor mode and returns to normal editing.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.disableSingleEditorMode();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.disableSingleEditorMode();
```
## Define Single Editor Mode Elements
### Restrict to specific containers
* Restrict Single Editor Mode to specific containers.
* By default Single Editor Mode is enabled at the entire DOM level. You can restrict this feature to only certain HTML containers & their children by using this.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.singleEditorModeContainerIds(["rightPanel", "editor"]);
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.singleEditorModeContainerIds(["rightPanel", "editor"]);
```
### Fine tune elements control
Control which elements are controlled by Single Editor Mode.
You must add the data-velt-sync-access-\* attributes to native HTML elements (e.g. button, input). It will not work directly on React components.
```jsx theme={null}
// Enable sync access on custom elements
return (
Controlled by Single Editor Mode
);
// Exclude elements from sync access
return (
Not controlled by Single Editor Mode
);
```
```html theme={null}
Controlled by Single Editor Mode
Not controlled by Single Editor Mode
```
## Timeout Configuration
### setEditorAccessTimeout
* Configure automatic editor access timeout.
* Default: `5 seconds`.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.setEditorAccessTimeout(15); // in seconds
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.setEditorAccessTimeout(15); // in seconds
```
### enableEditorAccessTransferOnTimeOut
* When editor access timeout is reached, automatically transfer editor access to the next user in the queue.
* Enabled by default.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.enableEditorAccessTransferOnTimeOut();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.enableEditorAccessTransferOnTimeOut();
```
### disableEditorAccessTransferOnTimeOut
* When editor access timeout is reached, do not automatically transfer editor access to the next user in the queue.
* Enabled by default.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.disableEditorAccessTransferOnTimeOut();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.disableEditorAccessTransferOnTimeOut();
```
### getEditorAccessTimer
Track the state of editor access request timeout.
**Returns**
* `EditorAccessTimer` object:
* `state` (`'idle'` | `'inProgress'` | `'completed'`)
* `durationLeft` (`number`)
```jsx theme={null}
// Using Hooks
const editorAccessTimer = useEditorAccessTimer();
useEffect(() => {
if (editorAccessTimer?.state === 'completed') {
// Handle timeout completion
if (isEditor) {
acceptEditorAccessRequest();
} else if (isRequester) {
setUserAsEditor();
}
}
}, [editorAccessTimer]);
return (
Status: {editorAccessTimer?.state}
Time Left: {editorAccessTimer?.durationLeft}s
);
// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.getEditorAccessTimer().subscribe((editorAccessTimer) => {
console.log('Editor Access Timer:', editorAccessTimer);
});
```
## Auto-Sync Text Elements
* Enable automatic syncing of text element contents across all users.
* Supported elements:
* `
```html theme={null}
```
## Editor
### setUserAsEditor
Sets the current user as the editor, making all other users read-only.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.setUserAsEditor();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.setUserAsEditor();
```
#### Error handling
`setUserAsEditor` includes validations to prevent assigning an editor when one already exists. It returns a promise that resolves to an optional error object.
```ts theme={null}
export interface SetUserAsEditorResponse {
error?: ErrorEvent;
}
export type ErrorEvent = {
error?: string;
code: string;
message?: string;
source?: string;
};
// Usage
const liveStateSyncElement = useLiveStateSyncUtils();
const result = await liveStateSyncElement.setUserAsEditor();
if (result?.error) {
if (result.error.code === 'same_user_editor_current_tab') {
// Same user already editor in current tab
} else if (result.error.code === 'same_user_editor_different_tab') {
// Same user already editor in different tab
} else if (result.error.code === 'another_user_editor') {
// Another user already editor
}
}
```
```js theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
const result = await liveStateSyncElement.setUserAsEditor();
if (result && result.error) {
if (result.error.code === 'same_user_editor_current_tab') {
// Same user already editor in current tab
} else if (result.error.code === 'same_user_editor_different_tab') {
// Same user already editor in different tab
} else if (result.error.code === 'another_user_editor') {
// Another user already editor
}
}
```
Possible error values:
```ts theme={null}
{
code: 'same_user_editor_current_tab',
message: 'Same user is already editor in current tab.',
source: 'setUserAsEditor',
}
{
code: 'same_user_editor_different_tab',
message: 'Same user is already editor in different tab.',
source: 'setUserAsEditor',
}
{
code: 'another_user_editor',
message: 'Another user is already editor.',
source: 'setUserAsEditor',
}
```
### isUserEditor
* Get the current user's editor status.
**Returns**
* `null`: When the state is not available yet.
* `undefined`: When there are no current editors available in single editor mode.
* `UserEditorAccess`: When there is at least one editor available in single editor mode.
* `isEditor` (`boolean`) - Whether the user is the editor
* `isEditorOnCurrentTab` (`boolean`) - Whether the user is editor on current tab
```jsx theme={null}
// Using Hooks
const { isEditor, isEditorOnCurrentTab } = useUserEditorState();
// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.isUserEditor().subscribe((userEditorAccess) => {
console.log('Is Editor:', userEditorAccess.isEditor);
console.log('Is Editor on Current Tab:', userEditorAccess.isEditorOnCurrentTab);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.isUserEditor().subscribe((userEditorAccess) => {
console.log('Is Editor:', userEditorAccess.isEditor);
console.log('Is Editor on Current Tab:', userEditorAccess.isEditorOnCurrentTab);
});
// To unsubscribe from the subscription:
subscription?.unsubscribe()
```
### getEditor
Get information about the current editor.
**Returns**
* `User` object:
* `email` (`string`) - Editor's email
* `name` (`string`) - Editor's name
* `photoUrl` (`string`) - Editor's photo URL
* `userId` (`string`) - Editor's unique ID
```jsx theme={null}
// Using Hooks
const editor = useEditor();
// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.getEditor().subscribe((user) => {
console.log('Editor:', user);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.getEditor().subscribe((user) => {
console.log('Editor:', user);
});
// To unsubscribe from the subscription:
subscription?.unsubscribe()
```
### isEditorAccessRequested
Check if any viewer has requested editor access.
**Returns**
* `null` - User is not editor or request was canceled
* `EditorRequest` object:
* `requestStatus` (`string`) - 'requested' for active requests
* `requestedBy` (`User`) - User object of the requester
```jsx theme={null}
// Using Hooks
const editorAccessRequested = useEditorAccessRequestHandler();
// Using API
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.isEditorAccessRequested().subscribe((data) => {
if (data === null) {
console.log('No active requests or user is not editor');
} else {
console.log('Request from:', data.requestedBy.name);
}
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.isEditorAccessRequested().subscribe((data) => {
if (data === null) {
console.log('No active requests or user is not editor');
} else {
console.log('Request from:', data.requestedBy.name);
}
});
// To unsubscribe from the subscription:
subscription?.unsubscribe()
```
### acceptEditorAccessRequest
Accept editor access requests.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.acceptEditorAccessRequest();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.acceptEditorAccessRequest();
```
### rejectEditorAccessRequest
Reject editor access requests.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.rejectEditorAccessRequest();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.rejectEditorAccessRequest();
```
### editCurrentTab
Make current tab editable when editor has multiple tabs open.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.editCurrentTab();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.editCurrentTab();
```
## Viewer
### requestEditorAccess
Request editor access from the current editor.
**Returns**
* `null` - Request is pending
* `true` - Request accepted
* `false` - Request rejected
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
let subscription = liveStateSyncElement.requestEditorAccess().subscribe((status) => {
if (status === null) console.log('Request pending');
else if (status === true) console.log('Request accepted');
else console.log('Request rejected');
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
let subscription = liveStateSyncElement.requestEditorAccess().subscribe((status) => {
if (status === null) console.log('Request pending');
else if (status === true) console.log('Request accepted');
else console.log('Request rejected');
});
// To unsubscribe from the subscription:
subscription?.unsubscribe()
```
### cancelEditorAccessRequest
Cancel the editor access request.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.cancelEditorAccessRequest();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.cancelEditorAccessRequest();
```
## Heartbeat
The heartbeat mechanism provides more reliable presence detection in single editor mode scenarios. This feature is enabled by default when single editor mode is enabled.
If you want to disable heartbeat functionality, you must disable it before enabling single editor mode.
### [enableHeartbeat](/api-reference/sdk/api/api-methods#enableheartbeat)
Enables/Disables the heartbeat mechanism for Single Editor Mode presence detection.
Default: `enabled`
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.enableHeartbeat();
liveStateSyncElement.disableHeartbeat();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.enableHeartbeat();
liveStateSyncElement.disableHeartbeat();
```
## Presence Heartbeat
### updateUserPresence
Send a lightweight heartbeat from your host app to Velt. Velt will use that as a fallback in rare edge cases if it fails to detect multi‑tab/device presence. Most apps don't need this; use only if you see ambiguity in who's the active editor.
```ts theme={null}
export interface LiveStateSingleEditorExternalUserPresence {
/** True if the same user is present on a different tab. */
sameUserPresentOnTab?: boolean;
/** True if a different user is present on a different tab. */
differentUserPresentOnTab?: boolean;
/** User IDs of users present on a different tab. */
userIds?: string[];
}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.updateUserPresence({
sameUserPresentOnTab: false,
differentUserPresentOnTab: true,
userIds: ['user-2']
});
```
```ts theme={null}
export interface LiveStateSingleEditorExternalUserPresence {
/** True if the same user is present on a different tab. */
sameUserPresentOnTab?: boolean;
/** True if a different user is present on a different tab. */
differentUserPresentOnTab?: boolean;
/** User IDs of users present on different tabs. */
userIds?: string[];
}
```
```js theme={null}
// API method
const liveStateSyncElement = Velt.getLiveStateSyncElement();
const userPresenceObject = {
sameUserPresentOnTab: false,
differentUserPresentOnTab: true,
userIds: ['user-2']
};
liveStateSyncElement.updateUserPresence(userPresenceObject);
```
### resetUserAccess
Reset editor access for all users.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.resetUserAccess();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.resetUserAccess();
```
## UI
### enableDefaultSingleEditorUI
* Control the visibility of the default Single Editor Mode System UI.
* The default UI shows:
* Current user's editor/viewer status
* Editor access requests
* Request timeout countdown
* Request rejection options
* If you disable the default UI, you'll need to implement your own UI for these features.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
// Enable default UI (enabled by default)
liveStateSyncElement.enableDefaultSingleEditorUI();
// Disable default UI for custom implementation
liveStateSyncElement.disableDefaultSingleEditorUI();
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
// Enable default UI (enabled by default)
liveStateSyncElement.enableDefaultSingleEditorUI();
// Disable default UI for custom implementation
liveStateSyncElement.disableDefaultSingleEditorUI();
```
### Embed Single Editor Mode Panel
* Embed the Single Editor Mode Panel into your UI.
```jsx theme={null}
```html theme={null}
## Event Subscription
### on
Subscribe to Single Editor Mode Events. Here is the list of events you can subscribe to and the event objects you will receive.
| Category | Event Type | Description | Event Object |
| ----------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Editor | `accessRequested` | When a user requests editor access. Editor will get this event. | [AccessRequestEvent](/api-reference/sdk/models/data-models#accessrequestevent) |
| Editor | `accessRequestCanceled` | When a user cancels their request for editor access. Editor will get this event. | [AccessRequestEvent](/api-reference/sdk/models/data-models#accessrequestevent) |
| Viewer | `accessAccepted` | When a user's request for editor access is accepted. Requesting Viewer will get this event. | [AccessRequestEvent](/api-reference/sdk/models/data-models#accessrequestevent) |
| Viewer | `accessRejected` | When a user's request for editor access is rejected. Requesting Viewer will get this event. | [AccessRequestEvent](/api-reference/sdk/models/data-models#accessrequestevent) |
| Access Assignment | `editorAssigned` | When a user is assigned as the editor. | [SEMEvent](/api-reference/sdk/models/data-models#semevent) |
| Access Assignment | `viewerAssigned` | When a user is assigned as a viewer. | [SEMEvent](/api-reference/sdk/models/data-models#semevent) |
| Editor | `editorOnDifferentTabDetected` | When the editor opens the same document in a different browser tab. Editor will get this event. | [SEMEvent](/api-reference/sdk/models/data-models#semevent) |
**Using Hooks:**
```jsx theme={null}
// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
const eventData = useLiveStateSyncEventCallback("EVENT_TYPE");
useEffect(() => {
if (eventData) {
console.log("EVENT_TYPE data: ", eventData);
}
}, [eventData]);
```
**Using API:**
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
liveStateSyncElement.on("EVENT_TYPE").subscribe((eventData) => {
console.log("EVENT_TYPE data: ", eventData);
});
```
```javascript theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
liveStateSyncElement.on("EVENT_TYPE").subscribe((eventData) => {
console.log("EVENT_TYPE data: ", eventData);
});
```
## Best Practices
* Use `singleTabEditor` to prevent confusion when users have multiple tabs open
* Add IDs to HTML elements with sync attributes for more robust syncing
* Only apply sync attributes to native HTML elements, not framework components
# Overview
Source: https://docs.velt.dev/realtime-collaboration/single-editor-mode/overview
Allow only one user to edit at a time but still allow everyone to see the changes as they happen.
## Latency
* Extremely low latency, with typical response times no greater than 10 ms.
## Offline Support
* Optimistic local‑first reads and writes.
* Full offline support with automatic syncing when reconnected.
## Conflict Resolution
* Server timestamp-based last-write-wins strategy for automatic conflict resolution.
- We recommend using the default UI for simplicity and velocity. You can customize it to change the look, feel and position of the UI. You can customize the UI by following [this guide](/ui-customization/features/realtime/single-editor-mode).
- If you do want to create your UI from scratch then you can use the following APIs to create a similar UX: [Editor](/realtime-collaboration/single-editor-mode/customize-behavior#editor) and [Viewer](/realtime-collaboration/single-editor-mode/customize-behavior#viewer).
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
useEffect(() => {
if (liveStateSyncElement) {
// Enable Single Editor Mode
liveStateSyncElement.enableSingleEditorMode({
customMode: false,
singleTabEditor: true
});
// Optional: Show default UI panel
liveStateSyncElement.enableDefaultSingleEditorUI();
// Optional: Restrict to specific containers
liveStateSyncElement.singleEditorModeContainerIds(['editor', 'rightPanel']);
}
// Cleanup on unmount
return () => liveStateSyncElement.disableSingleEditorMode();
}, [liveStateSyncElement]);
return (
{/* Single Editor Mode Panel UI */}
);
```
```html theme={null}
### Step 3: Set the editor
* Declare the editor for the current document/session so editing is enabled for one user while others remain read-only.
* You can set the current user as the editor programmatically on an explicit action.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
// Programmatically set the current user as the editor when they perform an explicit action. eg: start typing or interact with the UI.
function setEditor() {
liveStateSyncElement?.setUserAsEditor();
}
```
```html theme={null}
```
When the editor is set, editing tools should become enabled for that user while other users are placed in read-only mode.
You can fine tune which elements are enabled/disabled by following [this guide](/realtime-collaboration/single-editor-mode/customize-behavior#define-single-editor-mode-elements).
Learn more: [Set User as Editor](/realtime-collaboration/single-editor-mode/customize-behavior#setuseraseditor)
### Step 4: Update UI to reflect editor and viewer states
* Non-editor users are automatically viewers. Reflect that state in your UI.
* If you are using the default UI, it will automatically reflect the editor and viewer states in the UI. You can customize it to change the look, feel and position of the UI.
```jsx theme={null}
// Reflect viewer vs editor state in UI
const { isEditor, isEditorOnCurrentTab } = useUserEditorState();
return (
Role: {isEditor ? 'Editor' : 'Viewer'}
{isEditor &&
Editing on this tab: {isEditorOnCurrentTab ? 'Yes' : 'No'}
}
);
```
```html theme={null}
```
See: [Is User Editor](/realtime-collaboration/single-editor-mode/customize-behavior#isusereditor)
### Step 5: Passing access (requests + accept/reject UX)
Provide an access handoff flow so viewers can request edit access and the editor can accept or reject.
* Default UI (recommended): Use the built-in banner/controls.
* Custom UI: Use the APIs to request and respond to access.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
// Default UI (recommended): ensure default UI is enabled and/or panel is rendered
liveStateSyncElement.enableDefaultSingleEditorUI();
//
{editorAccessRequested && (
{`User ${editorAccessRequested.requestedBy?.name || editorAccessRequested.requestedBy?.email} requests access`} →
liveStateSyncElement.acceptEditorAccessRequest()}>Accept
liveStateSyncElement.rejectEditorAccessRequest()}>Reject
)}
{/* Custom UI: Viewer-side — request/cancel access */}
liveStateSyncElement.requestEditorAccess().subscribe((status) => {
console.log('Request status:', status);
})
}
>
Request edit access
liveStateSyncElement.cancelEditorAccessRequest()}>Cancel request
```html theme={null}
```
Learn more: [Is Editor Access Requested](/realtime-collaboration/single-editor-mode/customize-behavior#iseditoraccessrequested), [Accept Editor Access Request](/realtime-collaboration/single-editor-mode/customize-behavior#accepteditoraccessrequest), [Reject Editor Access Request](/realtime-collaboration/single-editor-mode/customize-behavior#rejecteditoraccessrequest), [Request Editor Access](/realtime-collaboration/single-editor-mode/customize-behavior#requesteditoraccess), [Cancel Editor Access Request](/realtime-collaboration/single-editor-mode/customize-behavior#canceleditoraccessrequest)
### Step 6: Prevent concurrent editing by the same user (tab locking)
If the same user opens another tab and tries to edit, lock the editor to a single tab and guide them back to the active tab when needed.
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
const { isEditor, isEditorOnCurrentTab } = useUserEditorState();
// If the user is the editor but on the wrong tab, prompt and switch
if (isEditor && isEditorOnCurrentTab === false) {
// Show UX prompt like: "You are already editing this page in another tab. Continue editing there."
// Provide an action to move editing to this tab:
const takeOver = () => liveStateSyncElement.editCurrentTab();
// Example: Edit on this tab
}
```
```html theme={null}
```
Recommended UX copy: "You are already editing this page in another tab. Continue editing there."
Learn more: [Edit Current Tab](/realtime-collaboration/single-editor-mode/customize-behavior#editcurrenttab) and [Is User Editor](/realtime-collaboration/single-editor-mode/customize-behavior#isusereditor)
## Notes
* **Initialize Velt first**: Ensure the Velt client is initialized and the user/document are set before enabling Single Editor Mode.
* **Default UI**: The built-in UI can be shown with `enableDefaultSingleEditorUI()` and/or by rendering `` (HTML).
* **Restrict scope**: Use `singleEditorModeContainerIds([...])` to limit Single Editor Mode to specific containers instead of the entire DOM.
* **Native elements only**: When `customMode: true`, you must mark native HTML elements with attributes to control them:
* `data-velt-sync-access="true"` to enable control
* `data-velt-sync-access-disabled="true"` to exclude elements
* These attributes work on native elements only, not directly on React components.
## Testing and Debugging
**To test Single Editor Mode:**
1. Open the same document as two different users in separate browser profiles (or two windows with different auth states).
2. Try editing simultaneously. Only one user should be able to edit; the other stays read-only.
3. Use the default UI panel to request/transfer access and verify the flow.
**Common issues:**
* UI not visible: Ensure `enableDefaultSingleEditorUI()` is called or the panel component/element is rendered.
* Elements not disabled: If using `customMode: true`, ensure you set `data-velt-sync-access` attributes on native elements. Attributes do not attach to React components.
* Editor can edit in multiple tabs: Confirm `singleTabEditor` is `true`. Use `editCurrentTab()` to move the editor role to the current tab.
## Complete Example
```jsx Complete Implementation expandable lines theme={null}
import React, { useEffect } from 'react';
import {
VeltProvider,
useLiveStateSyncUtils,
VeltSingleEditorModePanel,
useUserEditorState,
useEditorAccessRequestHandler
} from '@veltdev/react';
function SingleEditorExample() {
const liveStateSyncElement = useLiveStateSyncUtils();
const { isEditor, isEditorOnCurrentTab } = useUserEditorState();
const editorAccessRequested = useEditorAccessRequestHandler();
useEffect(() => {
liveStateSyncElement.enableSingleEditorMode({ singleTabEditor: true });
liveStateSyncElement.enableDefaultSingleEditorUI();
return () => liveStateSyncElement.disableSingleEditorMode();
}, []);
return (
Active editor: {isEditor ? 'Yes' : 'No'}
Editing on this tab: {isEditorOnCurrentTab ? 'Yes' : 'No'}
{editorAccessRequested &&
Access requested by: {editorAccessRequested.requestedBy?.email}
}
);
}
export default function App() {
return (
);
}
```
[Open in larger window](https://landing-page-demo-velt.vercel.app/?feature=single-editor-mode\&layout=vertical)
## Next: Customize Behavior
Learn how to fine-tune Single Editor Mode behavior, timeouts, events, and UI.
[Go to Customize Behavior](/realtime-collaboration/single-editor-mode/customize-behavior)
# Overview
Source: https://docs.velt.dev/realtime-collaboration/video-player-sync/overview
## Video Player Sync
`Video Player Sync` allows users to sync their video player with other `Users` in the same document.
This lets all `Users` watch the same video at the same time.
# Setup
Source: https://docs.velt.dev/realtime-collaboration/video-player-sync/setup
To enable `Video Player Sync` in any video, add the `data-sync-video-player="true"` attribute to your video player.
```html theme={null}
```
Test out `Video Player Sync` by opening two clients side-by-side and having one client play the video player.
To enable `Video Player Sync` in any video, add the `data-sync-video-player="true"` attribute to your video player.
```html theme={null}
```
```jsx React / Next.js theme={null}
export default function App() {
return (
);
}
```
```html HTML theme={null}
```
# Version 3.0.0
Source: https://docs.velt.dev/release-notes/3-0-0
## Change Log
### Improvements
* \[**Comments**]: Added pagination in autocomplete option dropdown for improved performance.
* \[**Comments**]: Added "Edit Comment" option in header options dropdown menu for editing the first comment. Only visible to comment author and admins. [Learn more](/ui-customization/features/async/comments/comment-dialog/subcomponents/options-dropdown).
* \[**Recorder**]: Added `shadow dom` prop in Recorder Player component to control shadow DOM encapsulation.
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
### Bug Fixes
* \[**Recorder**]: Fixed an issue where `summary` prop was not working in Recorder Player component.
### Improvements
* \[**Core**]: Added updates to the core library packages.
### Improvements
* \[**Core**]: Added accessibility props and test ids for most Velt components within Comments, Notifications, Live Selection features.
### Features
* \[**UI Customization**]: Added additional CSS variables for z-index customization. [Learn more](/ui-customization/customize-css/themes#available-theme-variables).
* `--velt-comment-pin-z-index: 2147483557`: For Components like Comment Pin, Triangle, etc.
* `--velt-arrow-z-index: 2147483557`: For Arrow Component.
* `--velt-recorder-player-z-index: 2147483557`: For Recorder Player Component.
* `--velt-cursor-z-index: 2147483647`: For Cursor Component.
* `--velt-persistent-comment-frame-z-index: 2147483647`: For Persistent Comment Frame Component.
* `--velt-toast-popup-z-index: 2147483647`: For Toast Popup Component.
* `--velt-live-state-sync-overlay-z-index: 2147483647`: For Live State Sync Overlay Component.
* `--velt-follow-mode-overlay-z-index: 2147483647`: For Follow Mode Overlay Component.
* `--velt-comments-minimap-z-index: 2147483637`: For Comments Minimap Component.
* `--velt-global-overlay-z-index: 2147483637`: For Global Overlay Component.
### Improvements
* \[**Comments**]: Improved comment annotation view count logic.
### Bug Fixes
* \[**Comments**]: Fixed an issue where default custom status was not applied when adding new comment annotation.
* \[**Comments**]: Added support for setting dynamic `targetElementId` value asynchronously in comment tool.
* \[**Comments**]: Fixed an issue where assign dropdown input wasn't closing after user selection.
* \[**Comments**]: Fixed padding around assign dropdown.
* \[**Comments**]: Fixed horizontal scroll and overflow issues for longer emails in assign dropdown input and assign banner.
This release changes how users navigate to comments from the sidebar. We've made navigation more explicit by requiring users to click a dedicated button rather than the comment itself.
### Improvements
* \[**Comments**]: Added navigation button as default in Comments Sidebar.
* Now just clicking on a comment doesn't open the comment on the DOM.
* A lot of users reported this behaviour as frustrating. That's why now there is an explicit navigation button for that.
* You will still get the [`onCommentClick`](/async-collaboration/comments-sidebar/customize-behavior#oncommentclick) event. You can still use that to maintain the old behavior [using this](/async-collaboration/comments/customize-behavior#selectcommentbyannotationid).
* If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/header) to show the navigation button.
* \[**Comments**]: Added feature to show resolved comments on for inline comments section.
* \[**Comments**]: Disabled collapsed comments by default. Most customers don't want to show collapsed comments by default so we disabled it. You can enable it by setting using [this](/async-collaboration/comments/customize-behavior#enablecollapsedcomments).
* \[**Comments**]: Disabled auto-focus on new comments in inline comments section and sidebar page mode.
### Bug Fixes
* \[**Comments**]: Fixed inline comment section horizontal scroll issue when the available width is too narrow.
* \[**Comments**]: Fixed Composer Send Button vertical alignment.
* \[**Comments**]: Removed autofocus for inline comments section when the page loads.
* \[**Comments**]: Fixed issue where clicking composer in edit mode was passing clicks through to the sidebar.
* \[**Comments**]: Fixed copy paste replace issue in the composer where pasting text over selected text was not working correctly.
* \[**Comments**]: Fixed Velt Button Sidebar wireframe loading default UI initially.
* \[**Comments**]: Fixed unread comments count APIs to return correct values on document switch.
### Improvements
* \[**Core**]: Added library upgrades to the SDK.
### Improvements
* \[**Comments**]: Added `readOnly` property in comment sidebar context so that it's available in `Velt Data` and `Velt If` features.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the Comments Sidebar was emitting multiple update calls.
* \[**UI Customization**]: Updated border radius for the status component in the Comment Dialog.
### Features
* \[**Velt Button**]: Added a customizable button component that can be used to add custom actions and extend the functionality of any Velt component. [Learn more](/ui-customization/custom-action-component). Some examples include:
* Add custom filtering, sorting and grouping to the Comment Sidebar.
* Add custom actions to each item in the Notifications panel.
* Add custom actions to the Comment Dialog.
* \[**Theme Playground**]: Added a new [Theme Playground](https://playground.velt.dev/themes). You can customize and test your themes. It will generate CSS variables that you can just copy and paste into your app.
### Improvements
* \[**Comments**]: Added additional wireframes for Comment Dialog Toggle Reply Component. [Learn more](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/togglereply).
* \[**Comments**]: Now users can't submit empty comments during editing.
* \[**Comments**]: Improved the padding on the @mention autocomplete dropdown.
* \[**Ergonomics**]: Updated `useCommentActionCallback` to `useCommentEventCallback`. The old hook name will continue to work.
* \[**Ergonomics**]: For Sidebar Custom actions and filters, updated APIs and Hooks:
* `onCommentSidebarInit` can now be also be accessed with `useCommentEventCallback('commentSidebarDataInit')` or `commentElement.on('commentSidebarDataInit')`
* `onCommentSidebarData` can now be also be accessed with `useCommentEventCallback('commentSidebarDataUpdate')` or `commentElement.on('commentSidebarDataUpdate')`
### Bug Fixes
* \[**Comments**]: Fixed an issue where the Comment sidebar group count was not updated correctly.
* \[**Comments**]: Fixed an issue where attached files were not displayed on the very first comment in inline and page mode comments.
* \[**Comments**]: Fixed a UI issue where attachments were misaligned when a comment was edited.
* \[**Comments**]: Fixed a UX issue where the comment composer did not scroll into view when comment edit button was clicked.
* \[**Comments**]: Resolved a UI issue where the Page Mode composer in the comment sidebar during embed mode was not taking the full width of the parent container.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the Comment Annotation unread count was not updated correctly.
### Features
* \[**Comments**]: Added ability to make comments read-only. When comments are made read-only, any features requiring user interaction (e.g., Composer, Reactions, Status) will be removed.
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed image lightbox CSS related issue
### Bug Fixes
* \[**Comments**]: Fixed undefined value error while updating context.
### Bug Fixes
* \[**Comments**]: Added `composerVariant` prop to `VeltInlineCommentsSection` component to support inline composer variant
```jsx theme={null}
```html theme={null}
* \[**UI**]: Minor CSS fixes and improvements
### Bug Fixes
* \[**Comments**]: Fixed undefined value error while updating context.
### Improvements
* \[**Comments**]: Added support for programatic selection and scrolling to comments in the `velt-comment-text` component used in Tiptap Comments.
### Features
* \[**Comments**]: Added ability to customize the placeholder text shown in the search input of the comments sidebar:
```jsx theme={null}
...
```
```html theme={null}
...
```
### Features
* \[**Comment**]: Added [new APIs, hooks and event callbacks](/async-collaboration/comments/customize-behavior) for each action that the user can perform on the Comment's Feature Components or API:
* **APIs & Hooks**:
* **Comment Annotation**: addCommentAnnotation, deleteCommentAnnotation
* **Comment**: addComment, deleteComment, updateComment, getComment
* **@Mention**: subscribeCommentAnnotation, unsubscribeCommentAnnotation, assignUser
* **Reaction**: addReaction, deleteReaction, toggleReaction
* **Attachment**: addAttachment, deleteAttachment, getAttachment
* **Status & Priority**: updateStatus, updatePriority, resolveCommentAnnotation
* **Recording**: getRecording, deleteRecording
* **Deep Link**: getLink, copyLink
* **Moderation**: approveCommentAnnotation, acceptCommentAnnotation, rejectCommentAnnotation, updateAccess
* **More Event Callbacks**:
* [On](/async-collaboration/comments/customize-behavior#on)
* [Here](/async-collaboration/comments/customize-behavior#on) is the list of events you can subscribe to.
* \[**Metadata**]: Get the currently set organization, document and location objects:
```jsx theme={null}
const metadata = await client.getMetadata();
```
* \[**UI Customization**]: Added ability to customize comment sidebar search placeholder:
```jsx theme={null}
```html theme={null}
### Features
* \[**UI Customization**]: Extended themes to include more components:
* Comments:
* Autocomplete
* Tooltip
* Chart Comments
* Text Comment Toolbar
* Comment Inbox
* Comment Text Portal
* Persistent Comment Mode
* Minimap
* Inline Comment Section
* Multi Thread Comments
* Notifications
* Notifications Panel
* Notification Tool
### Features
* \[**UI Customization**]: Introducing Themes! Now you can customize the look and feel of Velt components using CSS variables. This enables you to match Velt's UI with your application's design system.
* The following components now support theming (others will be added soon):
* Comment Components
* Recording Components
* Reactions
* You can customize:
* Border radius
* Spacing
* Typography
* Colors for light and dark modes
* Base Colors
* Accent Colors
* Text Shades
* Background Shades
* Border Shades
* Status Colors (error, warning, success)
* Transparent colors
* Learn more about UI Customization [here](/ui-customization/overview).
```css theme={null}
--velt-border-radius-2xs: 0.125rem; // 2px
--velt-border-radius-xs: 0.25rem; // 4px
--velt-border-radius-sm: 0.5rem; // 8px
--velt-border-radius-md: 0.75rem; // 12px
--velt-border-radius-lg: 1rem; // 16px
--velt-border-radius-xl: 1.25rem; // 20px
--velt-border-radius-2xl: 1.5rem; // 24px
--velt-border-radius-3xl: 2rem; // 32px
--velt-border-radius-full: 5rem; // 80px
```
```css theme={null}
--velt-spacing-2xs: 0.125rem; // 2px
--velt-spacing-xs: 0.25rem; // 4px
--velt-spacing-sm: 0.5rem; // 8px
--velt-spacing-md: 0.75rem; // 12px
--velt-spacing-lg: 1rem; // 16px
--velt-spacing-xl: 1.25rem; // 20px
--velt-spacing-2xl: 1.5rem; // 24px
```
```css theme={null}
--velt-default-font-family: sans-serif;
--velt-font-size-2xs: 0.625rem; // 10px
--velt-font-size-xs: 0.75rem; // 12px
--velt-font-size-sm: 0.875rem; // 14px
--velt-font-size-md: 1rem; // 16px
--velt-font-size-lg: 1.5rem; // 24px
--velt-font-size-xl: 1.75rem; // 28px
--velt-font-size-2xl: 2rem; // 32px
```
```css theme={null}
/* Base Colors */
--velt-light-mode-green: #0DCF82;
--velt-light-mode-magenta: #A259FE;
--velt-light-mode-amber: #FF7162;
--velt-light-mode-purple: #625DF5;
--velt-light-mode-cyan: #4BC9F0;
--velt-light-mode-orange: #FE965C;
--velt-light-mode-black: #080808;
--velt-light-mode-white: #FFFFFF;
--velt-light-mode-gray: #EBEBEB;
/* Accent Colors */
--velt-light-mode-accent: #625DF5;
--velt-light-mode-accent-text: #9491F8;
--velt-light-mode-accent-hover: #534FCF;
--velt-light-mode-accent-foreground: #FFFFFF;
--velt-light-mode-accent-light: #F2F2FE;
--velt-light-mode-accent-transparent: rgba(148, 145, 248, 0.08);
/* Text Shades */
--velt-light-mode-text-0: #0A0A0A;
--velt-light-mode-text-1: #141414;
--velt-light-mode-text-2: #1F1F1F;
--velt-light-mode-text-3: #292929;
--velt-light-mode-text-4: #3D3D3D;
--velt-light-mode-text-5: #525252;
--velt-light-mode-text-6: #666666;
--velt-light-mode-text-7: #7A7A7A;
--velt-light-mode-text-8: #858585;
--velt-light-mode-text-9: #999999;
--velt-light-mode-text-10: #B8B8B8;
--velt-light-mode-text-11: #A3A3A3;
--velt-light-mode-text-12: #8F8F8F;
/* Background Shades */
--velt-light-mode-background-0: #FFFFFF;
--velt-light-mode-background-1: #FAFAFA;
--velt-light-mode-background-2: #F5F5F5;
--velt-light-mode-background-3: #F0F0F0;
--velt-light-mode-background-4: #EBEBEB;
--velt-light-mode-background-5: #E5E5E5;
--velt-light-mode-background-6: #E0E0E0;
--velt-light-mode-background-7: #DBDBDB;
--velt-light-mode-background-8: #D6D6D6;
--velt-light-mode-background-9: #D1D1D1;
--velt-light-mode-background-10: #CCCCCC;
/* Border Shades */
--velt-light-mode-border-0: #FFFFFF;
--velt-light-mode-border-1: #FAFAFA;
--velt-light-mode-border-2: #F5F5F5;
--velt-light-mode-border-3: #F0F0F0;
--velt-light-mode-border-4: #EBEBEB;
--velt-light-mode-border-5: #E5E5E5;
--velt-light-mode-border-6: #E0E0E0;
--velt-light-mode-border-7: #DBDBDB;
--velt-light-mode-border-8: #D6D6D6;
--velt-light-mode-border-9: #D1D1D1;
--velt-light-mode-border-10: #CCCCCC;
/* Status Colors */
/* Error */
--velt-light-mode-error: #FF7162;
--velt-light-mode-error-hover: #DE5041;
--velt-light-mode-error-foreground: #FFFFFF;
--velt-light-mode-error-light: #FFF4F2;
--velt-light-mode-error-transparent: rgba(255, 113, 98, 0.08);
/* Warning */
--velt-light-mode-warning: #FFCD2E;
--velt-light-mode-warning-hover: #C69400;
--velt-light-mode-warning-foreground: #474747;
--velt-light-mode-warning-light: #FFFBEE;
--velt-light-mode-warning-transparent: rgba(255, 205, 46, 0.08);
/* Success */
--velt-light-mode-success: #198F65;
--velt-light-mode-success-hover: #006B41;
--velt-light-mode-success-foreground: #FFFFFF;
--velt-light-mode-success-light: #EDF6F3;
--velt-light-mode-success-transparent: rgba(25, 143, 101, 0.08);
/* Transparent Colors */
--velt-light-mode-background-transparent: rgba(255, 255, 255, 0.80);
--velt-light-mode-border-transparent: rgba(0, 0, 0, 0.16);
--velt-light-mode-animation-transparent: rgba(255, 255, 255, 0.2);
```
```css theme={null}
/* Base Colors */
--velt-dark-mode-green: #0DCF82;
--velt-dark-mode-magenta: #A259FE;
--velt-dark-mode-amber: #FF7162;
--velt-dark-mode-purple: #625DF5;
--velt-dark-mode-cyan: #4BC9F0;
--velt-dark-mode-orange: #FE965C;
--velt-dark-mode-black: #080808;
--velt-dark-mode-white: #FFFFFF;
--velt-dark-mode-gray: #EBEBEB;
/* Accent Colors */
--velt-dark-mode-accent: #625DF5;
--velt-dark-mode-accent-text: #9491F8;
--velt-dark-mode-accent-hover: #534FCF;
--velt-dark-mode-accent-foreground: #FFFFFF;
--velt-dark-mode-accent-light: #F2F2FE;
--velt-dark-mode-accent-transparent: rgba(148, 145, 248, 0.08);
/* Text Shades */
--velt-dark-mode-text-0: #FFFFFF;
--velt-dark-mode-text-1: #F5F5F5;
--velt-dark-mode-text-2: #EBEBEB;
--velt-dark-mode-text-3: #E0E0E0;
--velt-dark-mode-text-4: #D6D6D6;
--velt-dark-mode-text-5: #C2C2C2;
--velt-dark-mode-text-6: #ADADAD;
--velt-dark-mode-text-7: #8F8F8F;
--velt-dark-mode-text-8: #7A7A7A;
--velt-dark-mode-text-9: #666666;
--velt-dark-mode-text-10: #525252;
--velt-dark-mode-text-11: #474747;
--velt-dark-mode-text-12: #3D3D3D;
/* Background Shades */
--velt-dark-mode-background-0: #0F0F0F;
--velt-dark-mode-background-1: #1A1A1A;
--velt-dark-mode-background-2: #1F1F1F;
--velt-dark-mode-background-3: #242424;
--velt-dark-mode-background-4: #292929;
--velt-dark-mode-background-5: #2E2E2E;
--velt-dark-mode-background-6: #333333;
--velt-dark-mode-background-7: #383838;
--velt-dark-mode-background-8: #3D3D3D;
--velt-dark-mode-background-9: #424242;
--velt-dark-mode-background-10: #474747;
/* Border Shades */
--velt-dark-mode-border-0: #0F0F0F;
--velt-dark-mode-border-1: #1A1A1A;
--velt-dark-mode-border-2: #1F1F1F;
--velt-dark-mode-border-3: #242424;
--velt-dark-mode-border-4: #292929;
--velt-dark-mode-border-5: #2E2E2E;
--velt-dark-mode-border-6: #333333;
--velt-dark-mode-border-7: #383838;
--velt-dark-mode-border-8: #3D3D3D;
--velt-dark-mode-border-9: #424242;
--velt-dark-mode-border-10: #474747;
/* Status Colors */
/* Error */
--velt-dark-mode-error: #FF7162;
--velt-dark-mode-error-hover: #DE5041;
--velt-dark-mode-error-foreground: #FFFFFF;
--velt-dark-mode-error-light: #FFF4F2;
--velt-dark-mode-error-transparent: rgba(255, 113, 98, 0.08);
/* Warning */
--velt-dark-mode-warning: #FFCD2E;
--velt-dark-mode-warning-hover: #C69400;
--velt-dark-mode-warning-foreground: #474747;
--velt-dark-mode-warning-light: #FFFBEE;
--velt-dark-mode-warning-transparent: rgba(255, 205, 46, 0.08);
/* Success */
--velt-dark-mode-success: #198F65;
--velt-dark-mode-success-hover: #006B41;
--velt-dark-mode-success-foreground: #FFFFFF;
--velt-dark-mode-success-light: #EDF6F3;
--velt-dark-mode-success-transparent: rgba(25, 143, 101, 0.08);
/* Transparent Colors */
--velt-dark-mode-background-transparent: rgba(0, 0, 0, 0.80);
--velt-dark-mode-border-transparent: rgba(255, 255, 255, 0.16);
--velt-dark-mode-animation-transparent: rgba(255, 255, 255, 0.2);
```
* Example of theme customisation:
* You can update the following variables in `` tag to change the theme.
* For testing, try copy pasting the following sample themes in body tag:
```css theme={null}
body {
--velt-light-mode-accent: #0BA528;
--velt-light-mode-accent-text: #0BA528;
--velt-light-mode-accent-hover: #08841F;
--velt-light-mode-accent-foreground: #FFFFFF;
--velt-light-mode-accent-light: #DFF9E4;
--velt-light-mode-accent-transparent: rgba(11, 165, 40, 0.08);
--velt-dark-mode-accent: #0BA528;
--velt-dark-mode-accent-text: #0BA528;
--velt-dark-mode-accent-hover: #08841F;
--velt-dark-mode-accent-foreground: #FFFFFF;
--velt-dark-mode-accent-light: #DFF9E4;
--velt-dark-mode-accent-transparent: rgba(11, 165, 40, 0.08);
--velt-border-radius-2xs: 2px;
--velt-border-radius-xs: 2px;
--velt-border-radius-sm: 2px;
--velt-border-radius-md: 2px;
--velt-border-radius-lg: 2px;
--velt-border-radius-xl: 2px;
--velt-border-radius-2xl: 2px;
--velt-border-radius-3xl: 2px;
--velt-border-radius-full: 2px;
}
```
### Features
* \[**Comments**]: Added support for passing Comment Annotation objects to Standalone Comment Thread component.
* When using annotations from other documents:
* Comments will be read-only
* Reactions and recordings will not be rendered
* This enables creating Kanban boards by fetching comment annotations from multiple documents using our REST APIs.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `shortUserName` feature to control display of user names.
* For long names, this will first create an initial of the second name and if the name is still long, it will truncate it with ellipses.
* It's enabled by default.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### Improvements
* \[**Comments**]: Added support for light mode in the contact chip tooltip.
* \[**Comments**]: Removed unnecessary filtering in the sidebar when comment annotation selection changes.
### Bug Fixes
* \[**Comments**]: Fixed an issue where `onCommentSidebarData` event was getting triggered multiple times on sidebar clicks.
* \[**Comments**]: Fixed an issue where empty placeholder was not being displayed in the sidebar for page mode and custom action filters.
### Bug Fixes
* \[**Comments**]: Fixed issue where bottom sheet was incorrectly opening in the sidebar on mobile devices.
### Features
* \[**Comments**]: Fixed issue where edit comment composer was not appearing in the sidebar.
* \[**Comments**]: Added offset property to Comment Player Timeline. This allows comment bubbles to be positioned relative to both parent and child video clips.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Dynamic Hooks**]: Now the LiveStateSync and Views hooks support dynamic input parameters for non-primitive data types.
### Bug Fixes
* \[**Comments**]: Fixed issue where edit comment composer was not appearing in the sidebar.
### Features
* \[**REST APIs**]: Added advanced queries and pagination for GET endpoints.
* You need to upgrade to version 3.0.61 and enable this in your developer console.
* Check out the [V2 REST APIs endpoints](/api-reference/rest-apis/comments-feature/comment-annotations/get-comment-annotations-v2) for more information.
### Features
* \[**Comments**]: Added ability to enable/disable recording transcription feature on recorder:
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed range error that occurred when recording without comment text.
### Bug Fixes
* \[**Comments**]: Fixed several issues with the comment dialog and inline comments:
* Fixed cursor position not being set correctly when focusing comment input
* Fixed an issue where editing a comment and saving it as a draft created a new comment
* Fixed an issue where sometimes comment pin was visible on the inline comments section
### Improvements
* \[**Comments**]: Added ability to sort inline comments:
* `asc`: Show comments in ascending order of last updated timestamp
* `desc`: Show comments in descending order of last updated timestamp
* `none`: Show comments in order of creation (default)
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Further improved how empty comments are handled:
* Empty comments are now hidden from the sidebar and sidebar button count
* In popover mode, clicking a new comment button discards any previous empty comment
* \[**Comments**]: Added delete option for each comment in annotations when user has admin privileges.
### Bug Fixes
* \[**Notifications**]: Optimized and fixed issues related to loading notifications on `documentId` and `organizationId` change.
### Improvements
* \[**Comments**]: Improved the system grouping logic for locations.
* \[**Comments**]: Enhanced `updateContext` logic to prevent unnecessary updates if the passed context object remains unchanged.
* \[**Comments**]: Exposed `commentAnnotations` variable in the comments sidebar so that it can be used in `Velt Data` and `Velt If` Components.
### Bug Fixes
* \[**Comments**]: Fixed an issue where adding the `Copy Link` wireframe component in the header options menu generated undefined Comment URLs.
### Improvements
* \[**Comments**]: The "clear filter" button in the sidebar now only appears when comments are hidden due to active filters, not when there are no comments on the document.
### Bug Fixes
* \[**Comments**]: Fixed an issue with the Assign feature across different comment modes:
* Page mode
* Inline mode
* Multi-thread mode
* \[**Comments**]: Fixed an issue where reactions were not updated in focused thread mode.
### New Features
* \[**Comments**]: Now comments are supported on elements with duplicate DOM IDs.
* This is useful in cases where you have multiple instances of the same data component on a page and want the comment to appear on each instance, eg: Popover comments on a table.
* By default, comments appear on all matching elements. Use the `sourceId` attribute to control which element displays the comment dialog when adding a new comment.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Comments**]: In multithread mode, now you can deselect a thread by clicking on the header of the multi-thread dialog.
* \[**Comments**]: Removed self user from the list of users in the "Seen By" dropdown.
* \[**Comments**]: Removed users without name and email from the list of users in the "Seen By" dropdown.
### Bug Fixes
* \[**Tiptap Comments**]: Removed `data-velt-content` attribute. Now the highlighted text styling is only applied to text when there are comments available.
* \[**Comments**]: Fixed an issue where undefined and null string values appeared in individual and group contact lists.
### Bug Fixes
* \[**Security**]: Added security updates.
### New Features
* \[**Recorder**]: Added `getRecordingData` API to fetch [recording data](/api-reference/models/RecorderData) including transcript, summary, and recording URLs.
**Using Hook:**
```jsx theme={null}
const recorderData = useRecordingDataByRecorderId('-O9yTMWmEe5u6YGX8EFV');
useEffect(() => {
console.log('Recorder Data: ', recorderData);
}, [recorderData]);
```
**Using API:**
```jsx theme={null}
const recorderElement = client.getRecorderElement();
recorderElement.getRecordingDataByRecorderId("-O9yGiYS8lehOXMpQf4j").subscribe((recorderData) => {
console.log('Recorder Data: ', recorderData);
});
```
```javascript theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.getRecordingDataByRecorderId("-O9yGiYS8lehOXMpQf4j").subscribe((recorderData) => {
console.log('Recorder Data: ', recorderData);
});
```
### Improvements
* \[**Comments**]: In the sidebar, changed default `isExpanded` behavior in custom filtering. If not explicitly set, the first group will be expanded while remaining groups are collapsed.
### New Features
* \[**Comments**]: Added variant support to the `Velt Comment Pin` component. This is useful for customizing how the pin looks on different elements like charts, tables, etc.
```jsx theme={null}
```html theme={null}
* \[**Access Control**]: Enabled users logged in with "Org A" to access documents belonging to "Org B".
* By default, users can only access documents within their own organization.
* You can enable cross-organization access by specifying the `organizationId` of the target document in the document metadata.
* Ensure that the user has access to the target document in the target organization.
**Using Hook:**
```jsx theme={null}
useSetDocument(DOCUMENT_ID, {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
```
**Using API:**
```jsx theme={null}
client.setDocument(DOCUMENT_ID, {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
```
```javascript theme={null}
Velt.setDocument(DOCUMENT_ID, {
organizationId: 'ANOTHER_ORGANIZATION_ID'
});
```
* \[**Comments**]: Added ability to toggle the "Seen By" feature:
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### Improvements
* \[**Live Selection**]: Improved the live selection UI.
* \[**Recording**]: Added new wireframes for the recording feature:
* Media Source Settings
* Recorder All Tool
* Recorder All Tool Menu
* Recorder Audio Tool
* Recorder Video Tool
* Recorder Screen Tool
* Recording Preview Steps Dialog
* Recorder Control Panel
* Recorder Player
* Video Player
* Subtitles
* Transcription
* \[**Comments**]: Updated the empty state UI and added a clear filter button in the sidebar.
* \[**Comments**]: The "Custom filters" applied by the user are now stored in session storage just like the System filters.
### Improvements
### Bug Fixes
* \[**Comments**]: Fixed an issue in Tiptap editor where the comment dialog closed prematurely after adding a comment in single-thread mode.
* \[**Comments**]: Fixed an issue on minimap where clicking on it was not navigating to the comment location.
* \[**Comments**]: Fixed an issue where image attachments in comments were not opening in the lightbox.
* \[**Comments**]: Fixed an issue where the "AtHere" was not working when the label was set to "all".
### Improvements
* \[**Security**]: Added security updates.
### Improvements
* \[**Comments**]: Added dark mode support for the "Seen By" dropdown in the comment dialog.
### New Features
* \[**Webhooks**]: Added configuration option to encrypt webhook payloads using a secret key.
* Configure this option in the [Velt Console](https://console.velt.dev/dashboard/config/webhook).
* Encryption details:
* Payload encryption: AES-256-CBC
* Key encryption: RSA with PKCS1 OAEP padding and SHA-256 hash
* Public key format:
* Provide only the base64-encoded key string, without PEM headers/footers
* Recommended key size: 2048 bits
* Example of setting up encryption for Node.js:
```js theme={null}
{
"encryptedData": "1rtsa9UVvXzkP+u0ax2TOlz6xKcwKXhmtHyQF1I4II8X4n9uYb944Q/6AfUNFc2zQj9+AWJIV1Gtoo0j+j5VI8qS4kCVnP4In6v0I3wVECldgZsNAwwD4wKp85OJZUJL4scQmJJK+XXmMNGOW094BcIIa6zKRqYKja5RBm5zEj3k1qsP3WZkUXpggJ4FNuHkWX2nkoDLP5Rby6CY186TEeBIxY+aKS6FyWmOiDDC6ZfuY++BFNJbksNvsbBogDqHB2qa30nK9oEcOKSsXdU4AYof/mPOG01fK2diK3vyk4qcL83mJ0cXm7+SbM+FBFeJpdR+A7iIez1XrdnGlAqppnSfDoNBv2WZ/lRyZJWOyW7QHySMNTn746+JDr8oltIBDVUx5c2m8A/YeQ6E3wWEjjRZcfz3GNSzpEx+jqeNxS0StN7BUXUyHt3786EaXiUtjb2OtrP56mlidXytdHhPZPOy7stRwHnwgXfm5aLsS2yJSs3gSSUubL+ka4fhaJsqxtgXQATSh0RtNXSmAbx930DKn2DipbP23fJRduju/GP1nHnKuy8bOuyB5Du//RrysvKVC4+lMd4mVIc7cSXe25qcPjJFZGpJtJdkNwOZoWCmxMSdR32HBgo7KWJeOWqnWyuLdjQOaxol+JtTu8lopeQk7qfncEXMLcT7YRVQ4t1LZ5T9o4pZEtaOg1LwyX58VQS1OHvgBFWlEPxLfdS1r4c1YzMXLNA4sfYEp06Z11IlEFVCtWobK5//tLc+sIpwfMzdJ3VtVl9Z2XB9kASlnHf88eOdtzvn5A0CRhVBY/v855CttAy/WlPINtXxXSxm9oVMjrBFueWAZ3LQiXDl25to62L5i0NR93zEBKj1BG8egy3F27o8s5kcvrwpc3NGrmDe7x3S11noDAFsxZRWpHnRIapHcsrLWOjWVEumvUxlApKGKL3Ax80XBoN+aTNG4SXGq3dRHSneIs/MNSb0BGWoOD5U5ow58R1tvpzJHtLLnmesL1Vhr23Cug8KHU2q7+e8AnGGPTJIRKfVXjocMDclhDAk5/nuvtUTYG/hRZEQ1yCx3T7H08I6GvyOv4ErtKr+r883hXSYzf1K9eqk7de5mnmxwSEiAh0zagvZ+lMYhWpayeo+xHvtoyzfTsLNyXKc6AYZxfoIVK6UuBfkDnXiAh+NuJDa3wKwig13gQX8GmdJXeSSatI6uuXI1IU5xKIXysaHeAOaHfni+cfDgvUZTtVbWc1qDcNOVEUSl9KsjOUUgdzvST1tJ1ezMNZFbhlrPB3t5y0XvM9QQh1GyyeABxHl8nH/Icrp2Shf5vBntNbRZ3PlzK7nVtgTxXaKhZnGobwY7uruPpahNfkEi83JvOOnHeHBMXrVMAr8GHDRi8099wzvJRHYcb2p6eWocQsDV1X6tcTLuxj3EHGwykWREkkTDQ5C/F40n97PP0U2cxSGJIMePUwgAYw5OFo0dJMsU1HvXjm+2JoO8DkdwPl3Bc9F22trvsA3QecUCKQDGMTuFrFxtlubtJYtVl7w3pBST0SCKx3G2QiycRz0FMWv2FJpazQl6jE4xEqeKf7fiUn/QIo4Levk745LPhfr2tzlXbkdZ2q9TtmSAs5hjpK7ndswbIbvV8Ju5V8mDJXSR0y0NKG2C/8/vTB0xfqYtW/Bv3cXj6do9UQzP6fOFC4SGvYh/l8yohJmCTFq0tETqvZr9Atw9ZOz2cIBFx76wlS/eR9iB/JZ3DGM+2THC6Mjv70ipWX32UW7620Bb5KONm3Vw0eeIHckUn6QaHGfFL/URT6mr7YCJhG5lZynWYZcLv/ffWuFcSmO9p0xCrwqqPEjdaaGs52mqmA4Ikt9MulKAEp6p65V1vxt7Tdy6m9UVjzbEy1zFuU9iOHBAAaj6A8Mj1EEUe6sNx3fLHnC2c0+2Zf3eUxMZPm5dQZPOUXLI28yoCliBIhTYTSh7ATULDDvcnNMs/ziuG7WT/U1wuIHkT5kEE73tnG1EZY4RDODbQobmpBegcuUEh64HEGS7+aK/KPYWxFxWW5oVd0Dc7kvpariXqEhlNdDY65b2T8uBw8bI/HrfvT8d0EnsPz26B1xKZYqyusWnlR+10KdYzPNoupx8vWk74PW8zI5qlcV497SPtvn12a3wvZ8adJzMuP4hsBoKHG/M2nf0lOMbo1gcbHbT0FqcHE3mixY3lU+UnNC5jpmNCs1tK8yqeQdVtHE3YM4Y5SsnBTJddUWVpUxZ6rlU+H2NW/uGcDLBs3HmERTn1l6E1mmqKB2kPA/+Y/YbILXNojbkgRE/3lki5kX4+pjHDxF/mWEEeXpjIl4yKG97mVS2J0dGoJ5CqLv6/CdHhtwu35UydBVDVGHywufVLwPgEiDA9RklM/bQw3ojdlTrn6+irDcz8/Tj7KmK2votLaN6yIEM8Ex2htyBlyX/47eEsh63nSNwSx+uPcTxjH9N5cJpWzJ2KcBMIqZsWOTgISBUndgRdoVTFySY2XwbHlDjh8RCLLBsYRhvOK+nvNqEBnrfzz81B/sqDO1whQDTKT3ZcFnZouaVImRGHcOt0sRioq/JGHAHzRjyc/V9Gb/zTlI8QQob5y5k7dfReAy1rGdkeIa3LXSwWGz8hDjEnGsGGIC4evdiefgoJHkhzEywi/QUEOOnqms/0BzexbLP+89qMgGMlEbA9iLAW/BZgsAkxm+NHqGNtz9HDJStpqewElgjMQ+wV3TUGbrmY0O/FyQn/CXyhXjdRC0/5S1tZnzBMyolHF2a5L5EAzGck2MuV7TgLs6LcvGm7kIeq0vmBCkiUB4IBHMhraU7Ba+cC+CW7tDK0Tkanri5KSMXSXamJpU869Jcsk1JLm69ATMl3eIb5rPx5+GbPUrRogEUP3HQeLMQP8jjq6fVwzGPQByF70t0fE+Z23NuCLzhVss0YkMmzcKK8GjKCJ0vnCA0qanxovpDgCOHjgxvy44N+QNWfUynIKVHS9m7FDE3RgKf7rOfSM9vJ7F/KWo7kywi36ajuFbWcON/MTvlpPUhGm5dboiz3vyfpTWkQbd9XX7SPVBWCkvGg+A87R7RSN8bsWbmYm5m2wt3jrkBVSDn5FV3rek6X0GSpTDTWJ9ktmjKtshplXn7fx7XAKtS4hpEMGhZwi/LWvfTsGqOJlqi2FwYPLI7SVunch2VSfssejrfwxJHPqF50wTv6ax28lp7wToqsVunZprdhyY++gds/LAz083dZLM3EYcbHuGVXiNRFxptpiQNjEnyjZX0fc8UF1W2icDt7Gd5Pp2ckaPERLE+tJ+ackMxomH2/HjFB3XRXlDCoKuljtJ2cbw/gVPmHtV7Qw2w6tWaCzYP3g1D47BlrIqBV4RWjcPRjthfcWPnwUSSHwlJ4dLMQ+cJ402ol+HUukAKpkh5lcjME0uaD8KKReD/Ee9r4kubIR7z9JViXjnJJl3Jxr6KtK3abrg8cG8qVFRr5NDhxbfs9NY/zGDvbgt0GMWXRTi4oMrSkDKthZSWjVezDzPk11AMQ1E+SJSoSXgwUl1rbWPg0O29prkQdfdKQmZcaO5oj7+f3kSPsIOE9+Qn43VOxOWWybkCzSvEbzLgmuov5C8EWYeJgh13qDcNSwNdt4PgAqIq+tikKNUo9qeM9/q20an+i20fatPAcvrRes+xxnIBXmlPDCj02THjX4EulV2KE+nNxFnCrNvFKYp2bEAegJ2neqfeefDDDhn+t7OK9/73v3O3qnEwSyBlt+pEyHfLjv3Cm7Ik7JA5NUQ/nsS3JdC8OYy2i1DWSvi1qsP3ixAVCR7qBVdoOF2Lv5y2GWrJ0EvVcGqaPBnUezMGMdozNjreschNJvRlp3D72dGGQgs00GHyHbIQ5wicC5p+PiZ2z1EUBN7DiDy9ShQPKEDJtISiSrSaPkDPKpW7SxmSfDaLOIxEy4daAupV0gj7yTtrkpEvJjRECpa0kuKFP3/eFVVp/nIjWDzFASfDvYiry90dDrvLxO3tosuvMVfhXcOy/zbyeCkObaFgc3OkO4z2r4X4Vwt18BoRAammiEfgCbnhywl/CmLrSwV1qSjUgALh/XUPkqXCkqerNjYTlZw5NdRUKmheUXHYGwo4Z+xPfDtiHk1N5vRgNL9/qXsgt813spju9kDMGQGiXlrOgIyhArHR5p2B4S3FjRQ/lEoP5+5wN+9tBKYrR79sZXNS8CwR0BPrOoY9GQCYFdxrBtyH6KOWg29FVXNodt2Yvot7ktofcen1zwQJOAr0KTyqF9/TIltO+hS7swSzZMjV368SEPYjrtXfnXNWYltOS2zJAWYeqr0XLrL+iHbbOQLC7Rk0mnizmUt9wdefz4MtfXZNcdKR4LPsOqYyIz5ux90XiCbvcNZJaRa2/dzecv/koLQPbKzFPGxKiUOsHAa5SEGgbWFZE4Y9CBFS4nCuEOgUnVz9XtFAEP4dazc2cxjYLVzaG5msOiOY1O5ZygYMeVZfdKaITg7gMPbkL3Lpzo7QBMXcHmT5YAUeNaSbHxvgg45Jn8r7W72EQP9tF7SPKiPvxo91xkB7MA3JOcZXC1qymTUWqjO038wSShK48kE+qgu7V9rjP5fOCDW3+3338eifxqS7Zq6FSO053c5W2c8wFR4iw==",
"encryptedKey": "OzSHFXzrXFC5wDvM5NPRkriY/NaC/USvFUPE+f4NZ30tiD2qb8sJM2XT2K7uNIZ05uDLfsJ6/BbEoYC1SOPXcFJMYqRiYFiI9RWrNgR4EtPWZ84RgrmxGcZZjzSqHzjuls8g++cuqJGRV+ePbTRH+z2OuZZu0vMKZiemaZpHL46Ewi9HUnbRDXvOlKFFHmQm5tayZ7m7Mv5iu4T5R3DPEAHlZnGqtP98ToLxUJUS2Eku/iLHXRmhmZXn55Qt5GYiyss8P5/miPqJCu1QG0CStn5Nsl4KvU+I4QYAOcMFWWUAGofOwPWtt8vPh8Bx+7t7BbayKpA4ZUEWWAjC+zASxg==",
"iv": "SHM0UHU5WXoyTG03TnExWA=="
}
```
```javascript theme={null}
const crypto = require('crypto');
/**
* Decrypts the symmetric key using the provided private key.
* @param {string} encryptedKey - Base64 encoded encrypted symmetric key
* @param {string} privateKey - RSA private key
* @returns {Buffer} Decrypted symmetric key
*/
function decryptSymmetricKey(encryptedKey, privateKey) {
try {
const encryptedSymmetricKey = Buffer.from(encryptedKey, 'base64');
const decryptedSymmetricKey = crypto.privateDecrypt(
{
key: `-----BEGIN RSA PRIVATE KEY-----\n${privateKey}\n-----END RSA PRIVATE KEY-----`,
padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
oaepHash: 'sha256',
},
encryptedSymmetricKey
);
return decryptedSymmetricKey;
} catch (error) {
console.error('Error decrypting symmetric key:', error);
throw new Error('Failed to decrypt symmetric key');
}
}
/**
* Decrypts the webhook data using the provided symmetric key and IV.
* @param {string} encryptedWebhookData - Base64 encoded encrypted webhook data
* @param {Buffer} symmetricKey - Decrypted symmetric key
* @param {string} payloadIv - Base64 encoded initialization vector
* @returns {Object} Decrypted webhook data as a JSON object
*/
function decryptWebhookData(encryptedWebhookData, symmetricKey, payloadIv) {
try {
const iv = Buffer.from(payloadIv, 'base64');
const decipher = crypto.createDecipheriv('aes-256-cbc', symmetricKey, iv);
let decryptedData = decipher.update(encryptedWebhookData, 'base64', 'utf8');
decryptedData += decipher.final('utf8');
return JSON.parse(decryptedData);
} catch (error) {
console.error('Error decrypting webhook data:', error);
throw new Error('Failed to decrypt webhook data');
}
}
// Example usage:
// const decryptedKey = decryptSymmetricKey(encryptedKey, privateKey);
// const decryptedData = decryptWebhookData(encryptedWebhookData, decryptedKey, payloadIv);
```
### Improvements
* \[**Comments**]: Improved time display in comment dialog by removing "just" from timeago text to make it more concise.
### New Features
* \[**Comments**]: Added "Seen" Feature in the comment dialog. It shows which users have seen the comments. It's automatically enabled in the default component.
* If you had previously used a wireframe for the comment dialog, you will need to add the [seen component wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/threadcard).
### New Features
* \[**Comments**]: Added config to restrict resolve action to admin users only:
**Using props:**
```jsx theme={null}
**Using props:**
```html theme={null}
### Improvements
* \[**Comments**]: Added ability to @mention emails not present in the contact list.
* \[**Comments**]: Implemented focus on composer when clicked anywhere within the composer.
### Improvements
* \[**Comments**]: Added "This page" label to the sidebar filters.
* \[**Comments**]: Added React wireframe component for Navigation button:
```jsx theme={null}
```html theme={null}
### New Features
* \[**Comments**]: Added "focused thread mode" in the comments sidebar:
* In this mode, when you click on a comment in the sidebar, it will open the thread in expanded view within the sidebar itself.
* Other threads and actions like filters, search etc are hidden behind a back button.
* Turning this on also adds a navigation button in the comment dialog. Clicking it will navigate to the comment and also trigger a callback.
* If you had previously used a wireframe for the comment dialog, you will need to add the [navigation button wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/navigation-button) and the [focused thread wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/focused-thread).
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added standalone thread wireframe component:
```jsx theme={null}
{/* Velt Comment Dialog Wireframe */}
```
```html theme={null}
```
* \[**Live Selection**]: Add ability to get live selection data for the document:
**Using Hook:**
```jsx theme={null}
const liveSelectionData = useLiveSelectionDataHandler();
useEffect(() => {
console.log('liveSelectionData', liveSelectionData);
}, [liveSelectionData]);
```
**Using API:**
```javascript theme={null}
const selectionElement = client.getSelectionElement();
selectionElement.getLiveSelectionData().subscribe((liveSelectionData: LiveSelectionData) => {
console.log("liveSelectionData: ", liveSelectionData);
});
```
**Using API:**
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
selectionElement.getLiveSelectionData().subscribe((liveSelectionData: LiveSelectionData) => {
console.log("liveSelectionData: ", liveSelectionData);
});
```
* \[**Comments**]: Added standalone `Velt Comment Text` component:
* When you put any text inside this component and provide an annotationId, it will automatically highlight the text and attach the comment to it.
```jsx theme={null}
{/* your content here */}
{/* your content here */}
```
```html theme={null}
```
### Improvements
* \[**Notifications**]: Changed the default maximum days for which Notifications should be displayed from 30 days to 15 days.
* \[**Notifications**]: Added complete document and organization metadata objects to the Notification metadata object.
### New Features
* \[**Live Selection**]: Added new configurations to customize the UI and behavior of the live selection feature:
* Enable/disable user indicator
* Set user indicator position
* Set user indicator type
* Enable/disable default elements tracking
* Enable/disable default styling
* Earlier the live selection was triggered on click, now it is triggered on keyboard actions as well.
* [Learn more](/realtime-collaboration/live-selection/customize-behavior).
### New Features
* \[**Comments**]: Added ability to apply custom filtering, sorting and grouping in comments sidebar.
* Here is the overview on how it works:
* Enable custom actions in the comments sidebar.
* Add action buttons to the sidebar wireframe.
* Implement callback and event handlers to handle custom filtering, sorting, and grouping logic.
* Set custom filtered data in the comments sidebar.
* [Learn more](/async-collaboration/comments-sidebar/customize-behavior#2-custom-filtering-sorting-and-grouping).
### Bug Fixes
* \[**Mentions**]: Resolved an issue where `atHereDescription` was not rendering for non-organization users.
### New Features
* \[**Notifications**]: Added API to mark a single notification as read by notificationId.
```javascript theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.markNotificationAsReadById("notificationId");
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.markNotificationAsReadById("notificationId");
```
* \[**Debugger**]: Added call to `setDocument` method to the debugger.
### Improvements
* \[**Mentions**]: Added `atHereDescription` to the `description` field of the @mention data object.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where the "For You" tab was not displaying the updated document name on initial load.
### New Features
* \[**Mentions**]: Added styling for @mention in the composer when adding or editing a comment.
### Improvements
* \[**React Hooks**]: Updated client and comment related hooks to support dynamic input values.
### Bug Fixes
* \[**Mentions**]: Fixed an issue in the `updateContactList` API where the passed contact list data was being mutated directly.
* \[**Mentions**]: Resolved an issue where @mentions with special characters were not working correctly.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where the `unreadCommentsMap` count was not updating correctly when switching between documents with no unread comments.
### New Features
* \[**Comments**]: Added shadowDOM, dark mode, and variant support in standalone Comment Thread component.
```jsx theme={null}
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed an issue where scroll was causing the "Add reply" button to hide.
* \[**Comments**]: Fixed an issue where the assign to dialog was not closing after assigning a user using the keyboard.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where the `document` tab was not visible when user email was not set.
### New Features
* \[**Comments**]: Added support for overlay text commenting in Tiptap editor.
* It works with all frontend frameworks that are supported by Tiptap.
* You can find the extension [here](https://www.npmjs.com/package/@veltdev/tiptap-velt-comments).
```bash theme={null}
npm i @veltdev/tiptap-velt-comments
```
```javascript theme={null}
import { TiptapVeltComments } from '@veltdev/tiptap-velt-comments';
const editor = new Editor({
extensions: [
TiptapVeltComments,
// ... other extensions
],
});
```
* Call this method to add a comment to selected text in the Tiptap editor. You can use this when the user clicks on the comment button in context menu or presses a keyboard shortcut.
* Args:
* `editor`: instance of the Tiptap editor.
* `tiptapVeltCommentConfig`: optional object to set the Comment Annotation's custom metadata.
* Example:
```javascript theme={null}
import { addTiptapVeltComment } from '@veltdev/tiptap-velt-comments';
addTiptapVeltComment(editor, tiptapVeltCommentConfig);
```
### Improvements
* \[**Console Debugger**]: Added logs for the `updateContactList` method to improve debugging.
### Improvements
* \[**Console Debugger**]: Added logs for `addContext` and `updateContext` methods. The context object is now included in the log event properties for better debugging and tracking.
* \[**Comments**]: Now comments will be marked as read if opened via the `selectCommentByAnnotationId()` API.
### Bug Fixes
* \[**Comment Display**]: Improved comment rendering performance for Comments Sidebar.
### New Features
* \[**Comments Sidebar**]: Added a reset filter button to easily clear all applied filters.
* This new button allows users to quickly reset all filters in the comments sidebar when no comments are available for the applied filters.
* Here is the wireframe for the reset filter button:
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Notifications**]: Improved loading state for API calls, now returns null until data is fully loaded.
### New Features
* \[**Notifications**]: Added API to get unread notifications count.
* **Sample response:**
```javascript theme={null}
{
forYou: 4, // # of unread notifications in the "For You" tab
all: 5 // # of unread notifications in the "All" or "Document" tab
}
```
Using Hooks:
```jsx theme={null}
const unreadCount = useUnreadNotificationsCount();
useEffect(() => {
console.log('Unread Count', unreadCount);
}, [unreadCount]);
```
Using API:
```javascript theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.getUnreadNotificationsCount().subscribe((data) => {
console.log('Unread notifications count:', data);
});
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.getUnreadNotificationsCount().subscribe((data) => {
console.log('Unread notifications count:', data);
});
```
### Improvements
* \[**Comments**]: Improved search functionality in @mentions to support spaces in search queries.
### New Features
* \[**Comments**]: Added ability to control whether comments inside the annotation should be collapsed.
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
* \[**Comments**]: Added ability to get comment annotation by ID.
Using Hooks:
```jsx theme={null}
const annotation = useCommentAnnotationById({
annotationId: '-O6W3jD0Lz3rxuDuqQFx', // AnnotationID
documentId: 'document-id' // DocumentId (Optional)
});
React.useEffect(() => {
console.log('annotation', annotation);
}, [annotation]);
```
Using API:
```javascript theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationById({
annotationId: '-O6W3jD0Lz3rxuDuqQFx', // AnnotationID
documentId: 'document-id' // DocumentId (Optional)
}).subscribe((annotation) => {
console.log('annotation', annotation);
});
```
Using API:
```javascript theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationById({
annotationId: '-O6W3jD0Lz3rxuDuqQFx', // AnnotationID
documentId: 'document-id' // DocumentId (Optional)
}).subscribe((annotation) => {
console.log('annotation', annotation);
});
```
* \[**Notifications**]: Added API to mark all notifications as read.
* Mark all notifications as read, either globally or for a specific tab.
* Using 'all' or 'document' as the `tabId` marks all notifications as read across all tabs (equivalent to calling `setAllNotificationsAsRead()` without arguments).
* Using 'for-you' as the `tabId` only marks notifications in the 'for-you' tab as read.
```javascript theme={null}
const notificationElement = client.getNotificationElement();
// Mark all notifications as read
notificationElement.setAllNotificationsAsRead();
// Mark all notifications as read for a specific tab
notificationElement.setAllNotificationsAsRead({ tabId: 'for-you' });
notificationElement.setAllNotificationsAsRead({ tabId: 'all' });
notificationElement.setAllNotificationsAsRead({ tabId: 'document' });
```
```javascript theme={null}
const notificationElement = Velt.getNotificationElement();
// Mark all notifications as read
notificationElement.setAllNotificationsAsRead();
// Mark all notifications as read for a specific tab
notificationElement.setAllNotificationsAsRead({ tabId: 'for-you' });
notificationElement.setAllNotificationsAsRead({ tabId: 'all' });
notificationElement.setAllNotificationsAsRead({ tabId: 'document' });
```
### Bug Fixes
* \[**UI Customization**]: Fixed an issue in `velt if` where string comparisions were not working as expected.
### New Features
* \[**Comments**]: Added a reset filter button wireframe in multithread comment dialog.
* \[**Notifications**]: Added a notifications panel loading state skeleton with wireframes.
```javascript theme={null}
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed an issue where draft comments were not being saved for multithread comments in some cases.
* \[**Comments**]: Fixed an issue where in inline mode, when editing a comment, the annotation was not being selected.
### New Features
* \[**Comments**]: Added a prop to enable confirmation before deleting a reply.
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
* \[**Comments**]: Added a callback method for when a comment link is copied. You can use this to track when a comment link is copied or show a confirmation toast.
Using Hooks:
```jsx theme={null}
const commentLink = useCommentCopyLinkHandler();
useEffect(() => {
console.log('commentLink', commentLink);
}, [commentLink]);
```
Using API:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.onCopyLink().subscribe((commentLink) => {
console.log(commentLink);
});
```
Using API:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.onCopyLink().subscribe((commentLink) => {
console.log(commentLink);
});
```
Using API:
```javascript theme={null}
const commentElement = Velt.getCommentElement();
commentElement.onCopyLink().subscribe((commentLink) => {
console.log(commentLink);
});
```
* \[**Comments**]: Added a minimal Actions Dropdown in Multithread comment dialog. It contains actions like 'Mark all as read', 'Mark all as resolved'.
### Improvements
* \[**UI Customization**]: Renamed the `velt data` prop to `field` (old: `path`) to improve readability. This is backward compatible.
```jsx theme={null}
```jsx theme={null}
### Improvements
* \[**Comments**]: Renamed `multiThreadMode` prop to `multiThread` for improved clarity and consistency.
* \[**Comments**]: Removed the "0 comments" from the multithread container header, when the first thread is created.
* \[**Comments**]: The comment pin bubble count in multithread mode would sync with the number of unresolved comments in the multithread container.
* \[**Comments**]: Added an unread indicator on the comment pin bubble in multithread mode to help users quickly identify new or unread comments.
* \[**UI Customization**]: Added improvements to the `velt if` conditional rendering logic.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the menu trigger button would hide when the mouse moved on the menu.
* \[**Notifications**]: Resolved an issue where `documentName` wasn't displayed on the notification item in the notification panel.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the composer would throw a console error on Firefox. This didn't have any impact on functionality or UX.
* \[**Comments**]: Fixed reply button toggle issue.
### Improvements
* \[**Comments**]: Improvements to the comments UX in multithread mode.
### Bug Fixes
* \[**Comments**]: Fixed an issue where sign in button was showing up for logged in users on mobile. This only impacted customers where signIn button was enabled.
### New Features
* \[**Webhooks**]: Added configuration option for base64 encoding of webhook payloads (disabled by default).
* Addresses issues with payloads containing HTML tags that may fail due to strict endpoint policies.
* Ensures payload validity and processability by your endpoint.
* Example of decoding a base64 encoded payload:
```js theme={null}
const encodedData="eyJ0ZXN0IjoxLCJ0ZXN0MSI6IjxkaXY+PC9kaXY+In0="
const decodedData = Buffer.from(encodedData, 'base64').toString('utf-8');
console.log(JSON.parse(decodedData));
```
### Improvements
* \[**Comments**]: Significant enhancements to the comments UX in multithread mode:
* Implemented smooth auto-scroll animation to new threads for improved visibility
* Added a new comment button to the header for easier thread creation
* Refined composer show/hide logic for a more intuitive user experience
* Shortened the displayed timestamp format
* \[**Comments**]: Improved the UI for [custom autocomplete dropdown chip](async-collaboration/comments/customize-behavior/custom-lists#2-add-custom-lists-on-comment).
* \[**Notifications**]: Notifications feature and API no longer require documentId to be set for initialization.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the custom autocomplete chip would fail to render if the same chip is added multiple times.
### Bug Fixes
* \[**Comments**]: Fixed a bug where clicking on one's own reaction on the [Velt Comment Player Timeline](/async-collaboration/comments/setup/video-player-setup/custom-video-player-setup) didn't toggle it correctly.
### Improvements
* \[**Comments**]: Added `createdAt` field for [CommentAnnotation](/api-reference/models/CommentAnnotation) model. This can now be used to sort annotations in ascending order of creation.
* \[**Comments**]: Added `isEdited` and `editedAt` fields in [Comment](/api-reference/models/Comment) model. This can now used to indicate if and when a comment is edited.
* \[**Comments**]: In multithread mode, the count on the header is now synced with the total threads visible after all the filters are applied.
* \[**Comments**]: Inline and multi-thread comments are now sorted in ascending order by the `createdAt` field, maintaining backward compatibility.
* \[**Comments**]: Improved the behavior where the mutlthread container was auto-closing when one of the threads was deleted or resolved.
### Bug Fixes
* \[**Comments**]: Fixed a bug where deleting a recording in a single-comment thread incorrectly triggered the Delete Thread dialog.
* \[**Comments**]: Fixed a bug where resolved comment threads weren't disappearing in [inline comment mode](/async-collaboration/comments/setup/inline-comments).
### New Features
* \[**Notifications**]: Added a configurable option to show read notifications in the "For You" tab. By default, read notifications are removed from the "For You" tab.
Using Props:
```jsx theme={null}
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
```
Using API:
```html theme={null}
```
For more details on customizing notifications behavior, refer to the [Notifications Behavior](/async-collaboration/notifications/customize-behavior) section.
### Improvements
* \[**REST API**]: Added advanced querying and pagination on REST APIs for improved performance and functionality.
* \[**Comments**]: Made the rendering of comment dialog action buttons configurable via CSS on hover or selection.
### Bug Fixes
* \[**Comments**]: Resolved a rare bug where the triangle pin component would cause the comment dialog to flicker on hover in popover comment mode.
* \[**Autocomplete dropdowns**]: Fixed a bug where the autocomplete dropdown component would not apply the `--velt-default-font-family`.
* \[**Notifications**]: Fixed a bug occurring when marking all notifications as read in large notification data sets.
### New Features
* \[**Comments**]: Added a standalone Comment Composer component. Now you can use this in combination with [Velt Comment Threads](/async-collaboration/comments/standalone-components/comment-thread/overview) component to embed commenting experiences in custom ways.
```jsx theme={null}
```html theme={null}
* \[**Inline Comments**]: Added single thread option to inline comments. By default, it will be in multithread mode.
Default value: `true`
```jsx theme={null}
```html theme={null}
```
### New Features
* \[**Comments**]: Added a new prop to control the use of ShadowDOM for [Persistent Comment Mode](/async-collaboration/comments/customize-behavior/modes#persistent-comment-mode) banner.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Comments**]: Action buttons are now consistently displayed across all states (default, hover, selection) of the comment dialog and can be customized via CSS alone.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where the `tabConfig` React props was not working as expected.
### Improvements
* \[**Notifications**]: Added an empty state for the document and all tabs in the notification panel.
* \[**Notifications**]: Added type definition for the `tabConfig` prop to improve TypeScript support.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where React props for customizing the notification panel were not working as expected.
### New Features
* \[**Comments**]: Added a new `atHereDescription` prop to customize the description that appears for the @here mention.
Using Props:
```jsx theme={null}
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
* \[**Comments**]: Added the `getSelectedComments()` API to get the currently selected comment annotations.
* This returns an array of [`CommentAnnotation`](/api-reference/models/CommentAnnotation) objects.
```jsx theme={null}
const commentElement = client.getCommentElement();
const subscription = commentElement.getSelectedComments().subscribe((selectedComments) => {
console.log('Selected comments:', selectedComments);
});
```
Unsubscribe from the subscription when you're done:
```jsx theme={null}
subscription?.unsubscribe()
```
```js theme={null}
const commentElement = Velt.getCommentElement();
const subscription = commentElement.getSelectedComments().subscribe((selectedComments) => {
console.log('Selected comments:', selectedComments);
});
```
Unsubscribe from the subscription when you're done:
```js theme={null}
subscription?.unsubscribe()
```
### Bug Fixes
* \[**Comments**]: Fixed an issue where the [custom list](/async-collaboration/comments/customize-behavior/custom-lists#1-add-custom-lists-on-comment-annotation) chip tooltip icon was not displayed.
* \[**Comments**]: Fixed an issue where the reaction tooltip in the [comment player timeline component](/async-collaboration/comments/setup/video-player-setup/custom-video-player-setup) was getting distorted on hover.
* \[**Comments**]: Fixed an issue where the reaction bubble on the [comment player timeline component](/async-collaboration/comments/setup/video-player-setup/custom-video-player-setup) had a transparent background.
### New Features
* \[**Comments**]: Added a Minimal Filter Dropdown Component for the Multithread Comment Dialog. This provides basic filtering and sorting options, including:
* Sorting: by date, by unread status
* Filtering: unread comments, read comments, resolved comments
### Improvements
* \[**Comments**]: Updated multithread behavior to ensure only one composer is open at a time.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the Floating Mode Comment Sidebar would not close when clicked outside.
* \[**Comments**]: Resolved a problem where sidebar dropdowns were not closing when clicked on the trigger button again.
* \[**Comments**]: Fixed an issue where the Add Reply button wasn't working in Inline Comment Section.
### Bug Fixes
* \[**Comments**]: Fixed a bug related to updating comment annotations.
### New Features
* \[**Comments**]: Added Draft State:
* Empty comments are no longer saved.
* Partial comments are saved as drafts, visible only to the author.
* Draft creation:
* Comment is saved as draft when the user adds text, recording, or attachment and closes the comment dialog without submitting.
* On first attempt to close: Dialog shakes to indicate draft status.
* On second attempt: the comment is saved as draft and the dialog closes.
* Added a visual indicator for draft comments in the dialog.
* If you had previously used a wireframe for the comment dialog, you will need to add the [draft wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/threadcard).
### Improvements
* \[**UI Customization**]: Refactored `velt if` and `velt data` logic for improved performance.
### New Features
* \[**Comments**]: Added Draft State:
* Empty comments are no longer saved.
* Partial comments are saved as drafts, visible only to the author.
* Draft creation:
* Comment is saved as draft when the user adds text, recording, or attachment and closes the comment dialog without submitting.
* On first attempt to close: Dialog shakes to indicate draft status.
* On second attempt: the comment is saved as draft and the dialog closes.
* Added a visual indicator for draft comments in the dialog.
* If you had previously used a wireframe for the comment dialog, you will need to add the [draft wireframe](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/threadcard).
### New Features
* \[**UI Customization**]: Added **Conditional Templates**! These let you conditionally show or hide parts of the Velt Component Wireframes.
* You can add conditions based on the same data models available in [Template Variables](/ui-customization/template-variables).
```jsx theme={null}
{/* Content to render if condition is true */}
```
```html theme={null}
```
* \[**UI Customization**]: You can now customize confirmation dialogs (eg: Delete thread, Delete recorder etc) for each feature by defining variants.
* Supported variants: `recorder`, `comment`, `arrow`, `area`.
```jsx theme={null}
Custom Title
Custom Message
Custom Reject Button
Custom Approve Button
```
```html theme={null}
Custom Title
Custom Message
Custom Reject Button
Custom Approve Button
```
* \[**UI Customization**]: Added two new global [Template Variables](/ui-customization/template-variables):
* `unreadCommentAnnotationCount`: Number of unread comment annotations on the current document.
* `unreadCommentCount`: Total number of unread comments on the current document.
* \[**Comments**]: Added `updateContext` method for updating custom metadata (`context`) on comment annotations. [Learn more](/async-collaboration/comments/customize-behavior#metadata#2-update-custom-metadata-on-comment-annotation). This method is available in two scenarios:
1. **In the `onCommentUpdate` event callback:**
Use this to update the context when a comment is modified.
2. **Via the `updateContext` API method:**
Utilize this method to update the context of a comment annotation at any time. For example, you might use this when the name of the dashboard containing the comment annotation changes.
### Improvements
* \[**Comments**]: Updated the icon for the Unresolve button.
* \[**Comments**]: Whenever the comment sidebar is opened using the button or the api, any open comment dialog will be closed.
* \[**Comments**]: Made position of the reaction tool consistent across different states and content types in the comment dialog.
### Bug Fixes
* \[**Comments**]: Fixed the flicker issue when new popover comment thread was created. This only happened when the triangle component was disabled.
* \[**Comments**]: Fixed minor rendering issue with the @mention chip when it was added at the end of the content.
* \[**Velt Components**]: Reduced the default z-index for all Velt Components to prevent them from going over the host app's header or any other important UI elements.
* \[**Comments**]: Fixed menu overlay positioning to stay with its trigger during page scrolling.
### Bug Fixes
* \[**Comments**]: Reverted comment sidebar button wireframe changes.
### New Features
* \[**Inline Reactions**]: Added `customReactions` prop for `VeltInlineReactionsSection` component in React, allowing custom emoji definitions:
```jsx theme={null}
const customReactions = {
"EMOJI_ID_1": {
"emoji": "🔥" // You could also set emoji using a url or raw svg definition
},
"EMOJI_ID_2": {
"emoji": "🙌" // You could also set emoji using a url or raw svg definition
},
"EMOJI_ID_3": {
"emoji": "💪" // You could also set emoji using a url or raw svg definition
}
}
### New Features
* \[**Comments**]: Added multi-thread support for Comments:
Using Props:
```html theme={null}
* \[**Inline Reactions**]: Added ability to add list of custom reactions:
Using API Method:
```javascript theme={null}
const reactionElement = client.getReactionElement();
const customReactions = {
"EMOJI_ID_1": {
"emoji": "🔥" // You could also set emoji using a url or raw svg definition
},
"EMOJI_ID_2": {
"emoji": "🙌" // You could also set emoji using a url or raw svg definition
},
"EMOJI_ID_3": {
"emoji": "💪" // You could also set emoji using a url or raw svg definition
}
};
reactionElement.setCustomReactions(customReactions);
```
* \[**UI Customization**]: Added wireframe for MultiThreaded Comment Dialog.
* \[**UI Customization**]: Added wireframe for Comment Sidebar Button with the new name.
### Improvements
* \[**Comments**]: Made element binding consistent by using common `targetElementId` attribute in comment feature components:
```jsx theme={null}
```html theme={null}
### Bug Fixes
* \[**Notifications**]: Fixed an issue where unread icon was not showing up when a comment was added by the user themselves.
* \[**Notifications**]: Resolved a UI issue where the "All Read" container was showing up while the data was still loading.
* \[**Notifications**]: Fixed the load more button on all notifications tabs.
* \[**Notifications**]: Fixed an issue where using the "assign to" options from the thread options menu wasn't generating a notification.
* \[**Recorder**]: Fixed an issue where recording was saved when minimizing the preview panel.
### Improvements
* \[**Comments**]: Pass the `id` attribute on either the `` tag or its parent element. This simplifies the implementation of comments on custom video players.
```jsx theme={null}
```
```html theme={null}
```
### New Features
* \[**Comments**]: Added an "Unresolve Comment" button component in the comment dialog. This button is used to unresolve a comment that was previously marked as resolved.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Comments**]: Improved comment text handling by trimming whitespace from `commentText` and `commentHtml` in the comment dialog.
### Bug Fixes
* \[**Comments**]: Fixed an issue with autocomplete chip shadowDOM not being updated.
* \[**Notifications**]: Resolved an issue where documents with empty notifications were still being rendered.
* \[**Users**]: Fixed a bug related to special characters in user names.
* \[**Comments**]: Fixed an issue where the checkbox in the location filter dropdown in sidebar wasn't updating on selection.
* \[**Comments**]: Fixed an issue where the status filter menu in the sidebar wasn't closing properly.
* \[**Recorder**]: Resolved a problem where the device list wasn't updating correctly in the recording settings menu in certain scenarios.
### New Features
* \[**Comments**]: Added a minimal location filter in the sidebar wireframe for basic location based filtering. By default it's not enabled. You need to explicitly add the wireframe to the sidebar.
* \[**Sidebar**]: Added `Floating Mode` for Comments Sidebar. This allows the sidebar panel to appear as an overlay on top of the sidebar button when clicked.
```jsx theme={null}
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed a bug where clicking the "replies" button in the sidebar comment dialog incorrectly opened the comment dialog on the DOM. This issue only affected implementations using the sidebar comment dialog wireframe.
### New Features
* \[**Comments**]: Added persistent comment mode banner wireframe.
* \[**API**]: Added `getDocumentMetadata` method to get the current document's metadata. It returns a subscription with [`DocumentMetadata`](/api-reference/sdk/models/data-models#documentmetadata) object.
```javascript theme={null}
client.getDocumentMetadata().subscribe((documentMetadata) => {
console.log("Current document metadata: ", documentMetadata);
});
```
```js theme={null}
Velt.getDocumentMetadata().subscribe((documentMetadata) => {
console.log("Current document metadata: ", documentMetadata);
});
```
### Improvements
* \[**Comments**]: The persistent comment banner now inherits the shadow DOM property from `Velt Comments`.
### New Features
* \[**Comments**]: Added a minimal filtering and sorting dropdown in the sidebar wireframe. By default it's not enabled. You need to explicitly add the wireframe to the sidebar. It includes options like:
* Filter by `All`
* Filter by `Unread`
* Filter by `Read`
* Filter by `Resolved`
* Sort by `Unread`
* Sort by `Last Updated Timestamp`
### Bug Fixes
* \[**Comments**]: Fixed an issue where the dialog was overflowing out of the screen in some cases.
### New Features
* \[**Reactions**]: Added [inline reaction section](/async-collaboration/reactions/setup) feature component.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Comments**]: Truncated video timeline comment card to 100 characters for improved readability.
* \[**Users**]: Limited user names to a maximum of 20 characters and disallowed URLs in names for security purposes.
### Bug Fixes
* \[**Comments**]: Resolved an issue with the unread indicator in the comment dialog.
### New Features
* \[**Comments**]: Added feature to render a comment bubble on the comment pin or triangle instead of the comment dialog. Hovering or clicking the bubble will open the comment dialog.
* `bubbleOnPin`: Whether to show bubble on pin \[default: false]
* `bubbleOnPinHover`: If the above is true, whether to show bubble when the pin is hovered over or clicked \[default: true]
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
### Improvements
* \[**Comments**]: Increased the max allowed size of attachments in composer from 2MB to 15MB.
* \[**Comments**]: Decreased the size of triangle in comment pin from 15px to 10px.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the comment dialog composer user avatar wireframe was not working.
* \[**Comments**]: Resolved minor signal-related issues.
* \[**Comments**]: Fixed Comment Dialog Attachments and Recording UI for inline comment mode, addressing aspect ratio issues.
### Improvements
* \[**Performance**]: Rewrote change detection and state management for the entire SDK to make it more performant. This is a major update and will benefit all developers.
# April 16 2024
Source: https://docs.velt.dev/release-notes/archive/april-16-2024
## Versions
* Latest SDK: [1.0.107](https://www.npmjs.com/package/@veltdev/react)
* Latest Types: [1.0.119](https://www.npmjs.com/package/@veltdev/types)
## Method to Hide Comments from Users on specific Locations
The [client.excludeLocationIds()](https://docs.velt.dev/async-collaboration/comments/customize-behavior/general-controls) method can be used to hide `Comments` at specific `Locations` from `Users`.
```jsx theme={null}
const locationIds = ['location1', 'location2']; // list of location ids
client.excludeLocationIds(locationIds);
```
## Configuration to Disable Recording Summaries
If you want to [disable the Recording summaries](https://docs.velt.dev/async-collaboration/comments/customize-behavior/multimedia) that appear when you record you audio, voice or screen, you can can now do so.
Example:
```jsx theme={null}
...
)
}
```
## Added option to use a specific version of the Velt React SDK.
You can now use a [specific version of the Velt React SDK](https://docs.velt.dev/get-started/advanced).
To do so, in your `VeltProvider` component, set the `config` props object to `{ version: '1.0.XYZ' }`.
Example:
```jsx theme={null}
...
```
# Aug 12 2024
Source: https://docs.velt.dev/release-notes/archive/aug-12-2024
# 2.0.30
### New Features
* \[**Comments**]: Added `resolvedByUserId` field on comment resolve. This allows tracking which user resolved a comment thread.
* \[**Comments**]: Added a configuration on sidebar to open the filter panel as a bottom sheet (default) or overlap on the filter button.
* Prop: `filterPanelLayout`. Values: `'menu' | 'bottomSheet'` (default)
* Usage:
```jsx theme={null}
```html theme={null}
# Aug 13 2024
Source: https://docs.velt.dev/release-notes/archive/aug-13-2024
# 2.0.31
### New Features
* \[**UI Customization**]: Added [Confirm Dialog Wireframe](/ui-customization/features/async/comments/confirm-dialog/overview) and added support for light and dark modes.
* This is a common UI component used for multiple features like deleting comment thread, deleting a recorded content and more.
* It will automatically inherit the light or dark mode property from the parent feature.
# Aug 14 2024
Source: https://docs.velt.dev/release-notes/archive/aug-14-2024
# 2.0.33
### New Features
* \[**UI Customization**]: Added conditional dynamic classes for different states of various interactive components:
* `velt-sidebar-tool-open`: For the sidebar button when the sidebar is open.
* `velt-notification-tool-open`: For the notification tool when the notification panel is open.
* `velt-comments-sidebar-status-open`: For the status dropdown trigger when the dropdown is open.
* `velt-comments-sidebar-filter-button-open`: For the filter button when the filter panel is open.
### Bug Fixes
* \[**Comments**]: Fixed an issue where after adding '@here' the cursor position was incorrectly placed at the start of the text.
# 2.0.32
### New Features
* \[**UI Customization**]: Added conditional classes for different states of various interactive components:
* `velt-comment-pin-open`: For the comment pin when the pin is selected.
* `velt-dropdown-open`: For the dropdown trigger when the dropdown is open.
* `velt-assign-dropdown-open`: For the assign dropdown trigger when the dropdown is open.
* `velt-custom-dropdown-open`: For the custom dropdown trigger when the dropdown is open.
* `velt-options-dropdown-open`: For the options dropdown trigger when the dropdown is open.
* `velt-priority-dropdown-open`: For the priority dropdown trigger when the dropdown is open.
* `velt-status-dropdown-open`: For the status dropdown trigger when the dropdown is open.
* `velt-reaction-tool-open`: For the reaction tool when the tool is open.
* `velt-comment-bubble-open`: For the comment bubble when the bubble is selected.
* `velt-comment-bubble-hover`: For the comment bubble when the bubble is hovered over.
* \[**Comments**]: Added configuration for customizing the '@here' mention label. eg: @all, @everyone, @team, etc:
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
### Improvements
* \[**Notifications**]: Various UI improvements on the notification panel.
### Bug Fixes
* \[**Comments**]: Fixed a bug where email contacts could have an invalid character ('.') at the end.
* \[**Comments**]: Resolved an issue where the comment sidebar filter wouldn't be sticky on page refresh.
* \[**Debugger**]: Fixed typo with event name `commentMoreReplayOptionClicked` and updated it to `commentMoreReplyOptionClicked`.
# Aug 16 2024
Source: https://docs.velt.dev/release-notes/archive/aug-16-2024
# 2.0.35
### Improvements
* \[**Comments**]: Added dynamic `velt-composer-input-focused` class on the composer container whenever the input is focused.
This provides more control over the styling of the composer input when it is focused.
# 2.0.34
### Improvements
* \[**Comments**]: Added dynamic `velt-composer-open` class on the composer container whenever the composer is opened.
* \[**Comments**]: Improved contact and reaction tooltips:
* Inherited shadow DOM property from parent's shadow DOM property.
* Added light mode and dark mode support.
### Bug Fixes
* \[**Comments**]: Fixed user avatar background color in autocomplete chip tooltip to match the color assigned to the user in the SDK.
# Aug 21 2024
Source: https://docs.velt.dev/release-notes/archive/aug-21-2024
# 2.0.39
### Bug Fixes
* \[**Comments**]: Fixed a css padding issue related to the action buttons in the comment dialog composer.
# 2.0.38
## Bug Fixes
* \[**Comments**]: Fixed an issue with the user-avatar component, ensuring it's consistently used across all the components.
# 2.0.37
### New Features
* \[**Comments**]: Added the ability to exclude specific location IDs from the comments sidebar. This provides more control over the displayed content.
Using Props:
```jsx theme={null}
Using Props:
```html theme={null}
# 2.0.36
### Improvements
* \[**Comments**]: Applied `location` filters to the inline-comments-section component as well, following the same pattern like other comment components.
* \[**UI Customization**]: Removed `!important` declarations from some component CSS, improving overall style flexibility and reducing potential conflicts.
### Bug Fixes
* \[**Comments**]: Resolved an issue related to calculating comment pin positions, ensuring more accuracy and robustness.
# Aug 22 2024
Source: https://docs.velt.dev/release-notes/archive/aug-22-2024
# 2.0.40
### Bug Fixes
* \[**Comments**]: Fixed an issue related to `addContext` in the `onCommentAdd` event. This ensures that context is consistently added when a new comment is created.
# Aug 6 2024
Source: https://docs.velt.dev/release-notes/archive/aug-6-2024
# 2.0.27
### Bug Fixes
* \[**Comments**]: Fixed an issue with changes detection in the text comment feature.
# 2.0.26
### Improvements
* \[**Notifications**]: Renamed Notification panel "all read" container wireframe components for better clarity and consistency:
This is a breaking change.
```jsx theme={null}
// Old
```html theme={null}
# 2.0.25
### New Features
* \[**Comments**]: For [Custom Comment Annotation dropdown](/async-collaboration/comments/customize-behavior/custom-lists#1-add-custom-lists-on-comment-annotation) on comment dialog:
* Added a default placeholder for the custom dropdown and made it configurable.
* Added it to the composer by default.
```jsx theme={null}
let customList = [
{ id: 'violent', label: 'Violent' },
{ id: 'inappropriate', label: 'Inappropriate' },
{ id: 'robbery', label: 'Robbery' },
{ id: 'nsfw', label: 'NSFW' },
];
const customListDataOnCommentAnnotation = {
type: 'multi', // choose from 'multi' or 'single'
placeholder: 'Custom Placeholder',
data: customList, // your customList data here
};
```
**Using Props:**
```jsx theme={null}
Custom Placeholder
```
**Using Props:**
```jsx theme={null}
Custom Placeholder
```
**Using API:**
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.createCustomListDataOnAnnotation(customListDataOnCommentAnnotation);
```
**Using Wireframe:**
```html theme={null}
Custom Placeholder
```
### Bug Fixes
* \[**Comments**]: Fixed an issue related to `disableReactions` in comment dialog customization.
# Aug 8 2024
Source: https://docs.velt.dev/release-notes/archive/aug-8-2024
# 2.0.29
### New Features
* \[**Comments**]: Added feature to render a comment bubble on the comment pin or triangle instead of the comment dialog. Hovering or clicking the bubble will open the comment dialog.
Using props:
```jsx theme={null}
Using props:
```html theme={null}
* \[**Location**]: For multiple location setup, added support for using `data-velt-location-id` vs full location object for marking additional locations.
### Improvements
* \[**Comments**]:Refactored comment components code for better maintainability.
### Bug Fixes
* \[**Comments**]: Fixed an issue where assignee banner text color was not being applied correctly for custom statuses.
* \[**Notifications**]: Fixed an issue where the document name in the notifications documents tab was not being displayed correctly.
# 2.0.28
### New Features
* \[**Notifications**]: Added ability to customize tabs on the Notifications Panel.
```jsx theme={null}
```jsx theme={null}
```js theme={null}
const tabConfig = {
"forYou": {
name: 'Custom For You',
enable: true,
},
"documents": {
name: 'Custom Documents',
enable: true,
},
"all": {
name: 'Custom All',
enable: false,
},
};
const notificationsTool = document.querySelector('velt-notifications-tool');
notificationsTool?.setAttribute("tab-config", JSON.stringify(tabConfig));
```
Using APIs:
```jsx theme={null}
const notificationElement = Velt.getNotificationElement();
const tabConfig = {
"forYou": {
name: 'Custom For You',
enable: true,
},
"documents": {
name: 'Custom Documents',
enable: true,
},
"all": {
name: 'Custom All',
enable: false,
},
};
notificationElement.setTabConfig(tabConfig);
```
* \[**@ mention**]: Added ability to override contact list on the client side. [Learn more](/async-collaboration/comments/customize-behavior/@mentions).
* The `merge` parameter is used to determine if the new contact list should be merged with the existing contact list or replaced. Default: `false`.
```jsx theme={null}
const contactElement = useContactUtils();
useEffect(() => {
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: true});
}, [contactElement]);
```
```jsx theme={null}
const contactElement = client.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: true});
```
```jsx theme={null}
const contactElement = Velt.getContactElement();
contactElement.updateContactList([{userId: 'userId1', name: 'User Name', email: 'user1@velt.dev'}], {merge: true});
```
* \[**Document**]: Added ability to set metadata on the document while setting the `documentId`.
* You can set any key/value pair in the metadata object. `documentName` is a special field that we use to display the document name in some Velt Components.
```jsx theme={null}
useSetDocument('unique-document-id', {documentName: 'Document Name'});
```
```jsx theme={null}
const { client } = useVeltClient();
useEffect(() => {
if (client) {
client.setDocument('unique-document-id', {documentName: 'Document Name'});
}
}, [client]);
```
```jsx theme={null}
if(Velt){
Velt.setDocument('unique-document-id', {documentName: 'Document Name'});
}
```
```jsx theme={null}
this.client.setDocument('unique-document-id', {documentName: 'Document Name'});
```
```jsx theme={null}
client.setDocument('unique-document-id', {documentName: 'Document Name'});
```
### Improvements
* \[**Comments**]: Improved the get comment annotations API to determine data loading state in React:
```jsx theme={null}
const [loading, setLoading] = useState(true);
const commentAnnotations = useCommentAnnotations();
useEffect(() => {
if (commentAnnotations) {
setLoading(false);
} else {
setLoading(true);
}
}, [commentAnnotations]);
```
* \[**Core**]:Updated SDK CDN URL in React and Client libraries to point to `cdn.velt.dev`.
# Dec 28 2023
Source: https://docs.velt.dev/release-notes/archive/dec-28-2023
## Summary
The new features in this release give you more control over the sidebar button, Recorder media options, reactions, and contact list.
## Enable Sidebar Button on Comment Dialog
By default, each Comment Dialog has a button at the bottom that will open the Comments Sidebar when clicked. You can now disable this button by setting the sidebarButtonOnCommentDialog prop to false.
## Subscribe to Sidebar Button Clicks on Comment Dialog
You can now subscribe to clicks on the Sidebar Button at the bottom of the Comment Dialog by passing a callback to the onSidebarButtonOnCommentDialogClick event handler.
## Set Recorder Media Options
You can now set the Recorder media options within Comments: (audio, screen, video, all, or none). By default, only audio recording is enabled. To set the Recorder media options, pass in a comma separated string of the features you want to enable.
## Enable Reactions
You can now enable or disable emoji reactions in Comments. By default, reactions are enabled.
## Add Comments on specific elements
You can now add a Comment on a specific element by ID. To do this, use the addCommentOnElement() API method and pass in an object with a specific schema.
## Reset Contact List using POST Method API
You can also replace an entire Group Ids contact list using a POST Method on the following API endpoint: `https://updatecontactlist-4mfhcuyw2q-uc.a.run.app`
# Feb 13 2024
Source: https://docs.velt.dev/release-notes/archive/feb-13-2024
## Versions
* Latest SDK: 1.0.83
* Latest Types: 1.0.100
## Location Support in System Comments
Users can now specify location when adding a new comment using [System Comments](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations).
```jsx theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY",
"authToken": "YOUR_AUTH_TOKEN",
"documentId": "snippyly-tinymce-13-oct",
// You can pass location object to set comment to any specific location
"location": {
"locationName": "YOUR_LOCATION",
// You can optionally pass version in location object
// to show comment on specific version only
// Note: if you set version then id and name fields are mandatory
"version": {
"id": "v1",
"name": "Version 1"
}
},
"targetElement": {
"elementId": "systemCommentTest",
"targetText": "we want our custom elements",
"occurrence": 1
},
"commentData": [
{
"commentText": "Replace: dolor sit amet consectetur adipisicing elit with this is test comment",
"replaceContentHtml": "this is bold text test comment",
"from": {
"email": "test@velt.dev",
"name": "Test User"
}
}
]
}
}
```
## Comment Read Receipts
Newly added comments that have not been seen by Users will now display with a small red dot.
```jsx theme={null}
import { useSetDocumentId } from '@veltdev/react';
export default function YourDocument() {
useSetDocumentId("my-document-id")
return (
Your Document Template
)
}
```
```jsx theme={null}
import { useVeltClient } from '@veltdev/react';
import { useEffect, useState } from 'react';
export default function YourDocument() {
const { client } = useVeltClient();
useEffect(() => {
if (client) {
client.setDocumentId('unique-document-id');
}
}, [client]);
return (
Your Document Template
);
}
```
# Feb 27 2024
Source: https://docs.velt.dev/release-notes/archive/feb-27-2024
## Versions
* Latest SDK: [1.0.87](https://www.npmjs.com/package/@veltdev/react)
* Latest Types: [1.0.103](https://www.npmjs.com/package/@veltdev/types)
## Comment Thread Component
We've abstacted out the UI we use for the threads in our `Comments`component into its own component. Now you can use our [Comment Thread](/async-collaboration/comment-thread/overview) component with your comment data to create your own custom UIs.
```jsx theme={null}
```jsx theme={null}
# July 04 2024
Source: https://docs.velt.dev/release-notes/archive/july-04-2024
## Versions
* Latest React SDK: [2.0.0](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.0](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.0](https://www.npmjs.com/package/@veltdev/types)
## Added Shadow Dom Support in Notification and Video Component
We have now added Shadow DOM support in both the notification (for notification panel and notification tool) and video components.
```jsx theme={null}
```jsx theme={null}
# July 09 2024
Source: https://docs.velt.dev/release-notes/archive/july-09-2024
## Versions
* Latest React SDK: [2.0.3](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.3](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.3](https://www.npmjs.com/package/@veltdev/types)
## Added `selectCommentByAnnotationId` Method in Comment Element
A new method [`selectCommentByAnnotationId`](/api-reference/api-methods/comments#selectcommentbyannotationid) has been added to the comment element, allowing you to select a comment based on its annotation ID.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.selectCommentByAnnotationId("COMMENT_ANNOTATION_ID");
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.selectCommentByAnnotationId("COMMENT_ANNOTATION_ID");
```
# July 10 2024
Source: https://docs.velt.dev/release-notes/archive/july-10-2024
## Versions
* Latest React SDK: [2.0.4](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.4](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.4](https://www.npmjs.com/package/@veltdev/types)
## Overview
* We've enhanced our access control model and data structure by adding the concept of "[Organizations](https://docs.velt.dev/key-concepts/overview#organizations)" in addition to the existing [Document](https://docs.velt.dev/key-concepts/overview#documents) and [Location](https://docs.velt.dev/key-concepts/overview#documents) concepts.
* We've added a feature called “[Organization User Groups](https://docs.velt.dev/key-concepts/overview#organization-user-groups)". You can now create custom collection of users such as engineering, marketing etc to tag groups of users and manage access effectively.
* We have added a [debugger](https://console.velt.dev/dashboard/debugger) to improve the debugging experience during development.
## Breaking changes
* If you were previously using only Documents and want to start using the Organization feature, then you can either migrate your existing comments to the new Organization structure or contact us for this migration. We’d be happy to help you with this.
* If you start using Organizations without migration, your data will remain intact, but the older comments won’t show up on the client.
## Organizations
* An Organization is a top-level entity.
* It contains documents, locations, and users.
* Within an organization, you can create multiple documents, and each document can contain several locations.
* [Learn more](/key-concepts/organizations/setup).
## Organization User Groups
You can create a custom collection of users, such as engineering, marketing, etc., to group organization users and manage access effectively.
* This can be used to @mention a team group versus just individuals (just like in Slack).
* This can also be used to provision access to documents.
* Organization users can belong to multiple organization user groups.
* Non-organization users can't be part of organization user groups.
* [Learn more](/key-concepts/users/organization-user-groups).
## Access Control
You can now control access to Velt data at the Organization and Document levels.
This adds an extra layer of data security. [Learn more](/key-concepts/overview#access-control).
## Debugger
* The debugger can be found in the developer console [here](https://console.velt.dev/dashboard/debugger).
* It allows you to view real-time events fired from the Velt SDK in your application.
* The debugger automatically pauses after 5 minutes of use. You can resume it once it does.
## Added `updateCommentDialogPosition` Method in Comment Element
We have added a new method `updateCommentDialogPosition` in Comment element. This triggers a dialog position update for manual pin comments. If the pin position updates while the dialog is open and the dialog position doesn't update, using this will manually trigger an update.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.updateCommentDialogPosition();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.updateCommentDialogPosition();
```
# July 15 2024
Source: https://docs.velt.dev/release-notes/archive/july-15-2024
## Versions
* Latest React SDK: [2.0.5](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.5](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.5](https://www.npmjs.com/package/@veltdev/types)
## Added the Option to Enable or Disable Area Comments
We have added the option to enable or disable area comment in the comment element. By default area comments are enabled.
```jsx theme={null}
```jsx theme={null}
API Methods:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableAreaComment();
commentElement.disableAreaComment();
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.enableAreaComment();
commentElement.disableAreaComment();
```
# July 17 2024
Source: https://docs.velt.dev/release-notes/archive/july-17-2024
## Versions
* Latest React SDK: [2.0.9](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.9](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.9](https://www.npmjs.com/package/@veltdev/types)
## Update to `autocomplete-option-description-wireframe`
We have added a `field` property in `autocomplete-option-description-wireframe` to replace email data with mentioned property value, for example:
```jsx theme={null}
```
```jsx theme={null}
# July 18 2024
Source: https://docs.velt.dev/release-notes/archive/july-18-2024
## Versions
* Latest React SDK: [2.0.11](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.11](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.11](https://www.npmjs.com/package/@veltdev/types)
## Added Custom Cursor
We have introduced support for a custom cursor for comments. The custom cursor's image should be 32 x 32 pixels.
```jsx theme={null}
```jsx theme={null}
API Methods:
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setPinCursorImage(BASE64_IMAGE_STRING);
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.setPinCursorImage(BASE64_IMAGE_STRING);
```
## Added `placeholder` Support
We have added `placeholder` support for Comments DIalog within the `comment-dialog-composer-input-wireframe`. [Learn more](https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog/subcomponents/composer/overview).
## Added `notificationSourceData` Field
We have added the `notificationSourceData` field for custom notifications in SDK and REST API. It is added via the [Add Norifications API](https://docs.velt.dev/api-reference/rest-apis/notifications/add-notifications#add-notifications). This object can be any key value pair that the developer sets. It has no type.
## Added Additional Fields for SendGrid Email Template
We have added a few new fields for [SendGrid email](https://docs.velt.dev/async-collaboration/comments/notifications#email-notifications#email-template-data) template.
* `firstComment`: first message in the thread.
* `latestComment`: Latest message in the thread that prompted the email.
* `prevComment`: The previous message to the latestMessage.
* `commentsCount`: Total number of comments in the comment annotation.
* `fromUser`: Action user's object.
* `commentAnnotation`: The comment annotation object without the comments.
* `actionType`: The action that resulted in the notification.
## Added the Update to Create Organization if Not Specified
For the [Update Disable State](https://docs.velt.dev/api-reference/rest-apis/organizations/update-organization-disable-state#update-disabled-state-for-organizations) and [Add Users](https://docs.velt.dev/api-reference/rest-apis/v2/users/add-users#add-users) API, if Organization does not exist, we will create it with metadata.
# July 19 2024
Source: https://docs.velt.dev/release-notes/archive/july-19-2024
## Versions
* Latest React SDK: [2.0.13](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.13](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.13](https://www.npmjs.com/package/@veltdev/types)
## Added `velt-data` Support
Now you can render dynamic data from these Classes inside your Velt Components Wireframe:
1. User: This represents the current logged-in user. It is available across all components.
2. UserContact: This represents the user contact object (it has the same class like the User). It is available on the autocomplete component where the user contacts are rendered.
3. CommentAnnotation: This represents the comment thread. This is available within the comment feature components.
4. Comment: This represents the message inside the thread. This is available within the comment feature components.
Here is one way to use it:
```jsx theme={null}
```jsx theme={null}
# July 22 2024
Source: https://docs.velt.dev/release-notes/archive/july-22-2024
## Versions
* Latest React SDK: [2.0.14](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.14](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.14](https://www.npmjs.com/package/@veltdev/types)
## Added `updateContactList` Method
We have now added a way to update UserContacts from client using the `client.updateContactList(userContact[])` method.
a. By default, it will overwrite the current contact list.
b. To merge with the already present contacts, you may use it with the merge flag: `client.updateContactList(userContact[], {merge:true})`.
This will work for both organization and non-organization structures.
# July 23 2024
Source: https://docs.velt.dev/release-notes/archive/july-23-2024
## Versions
* Latest React SDK: [2.0.16](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.16](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.16](https://www.npmjs.com/package/@veltdev/types)
## Added the Option to Add Manual Comment with Context
Within the comment element, we have introduced `addManualComment` method to add manual comment with context.
API Method:
```jsx theme={null}
const commentElement = client.getCommentElement();
const config: ManualCommentAnnotationConfig = {
context: {}, // your context here
};
commentElement.addManualComment(config);
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
const config: ManualCommentAnnotationConfig = {
context: {}, // your context here
};
commentElement.addManualComment(config);
```
`ManualCommentAnnotationConfig` Class:
```jsx theme={null}
export class ManualCommentAnnotationConfig {
context?: any;
}
```
## Added `onCommentClick` Callback
We have added `onCommentClick` callback in `velt-comment-thread` component.
```jsx theme={null}
```jsx theme={null}
handleOnCommentClick(data)}
/>
```
# July 24 2024
Source: https://docs.velt.dev/release-notes/archive/july-24-2024
## Versions
* Latest React SDK: [2.0.20](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.20](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.20](https://www.npmjs.com/package/@veltdev/types)
## Added Minimap Component
We have just introduced Minimap Component within Comments. By default, it is positioned right, but you have the option to change it to left.
```jsx theme={null}
{/* scrollable content */}
```
```jsx theme={null}
## Added Support for Reaction Tool
We have added support for reaction tool in custom video player. Within the reaction tool, we have added `videoPlayerId` attribute and `onReactionToolClick` event listener.
```jsx theme={null}
onReactionToolClick()} />
```
```jsx theme={null}
# July 26 2024
Source: https://docs.velt.dev/release-notes/archive/july-26-2024
## Versions
* Latest React SDK: [2.0.21](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.21](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.21](https://www.npmjs.com/package/@veltdev/types)
## Added Notifications Panel and Tool Wireframes
We have just added Notifications Panel and Notifications Tool wireframes.
## Deprecated Notification History Panel
We have deprecated the Notification History Panel. It will now load the Notification Panel Component.
## Added Option to Open Sidebar From Left
Previously, the sidebar would only open from right by default. Now, we have added the option to open the sidebar from left as well.
```jsx theme={null}
```jsx theme={null}
## Added More Props Within Notifications Tool Component
We have added `variant`, `panelVariant` and `panelOpenMode` props in Notification Tool Component.
```jsx theme={null}
```jsx theme={null}
## Added Tab Configuration Support for Notification Tool
You can now customize your tabs for Notifications Tool Component.
```jsx theme={null}
```jsx theme={null}
const tabConfig = {
"forYou": {
name: 'Custom For You',
enable: true,
},
"documents": {
name: 'Custom Document',
enable: false,
},
"people": {
name: 'Custom People',
enable: false,
},
"all": {
name: "Custom All",
enable: true,
},
}
const notificationsTool = document.querySelector('velt-notifications-tool');
notificationsTool?.setAttribute("tab-config", JSON.stringify(tabConfig));
```
# July 29 2024
Source: https://docs.velt.dev/release-notes/archive/july-29-2024
## Versions
* Latest React SDK: [2.0.22](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.22](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.22](https://www.npmjs.com/package/@veltdev/types)
## Added Wireframe for Custom Annotation Dropdown
We have added wireframes for custom annotation. [Learn more](https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog/subcomponents/custom-annotation-dropdown).
## Added Custom Annotation Dropdown Component Feature
You can now customize annotation dropdown component feature. Create custom list data on annotation as required.
```jsx theme={null}
const customChipDropdownData: {
type: 'multi' | 'single',
data: {
id: string,
label: string
}[]
} = {
type: 'multi',
data: [
{ id: 'violent', label: 'Violent' },
{ id: 'inappropriate', label: 'Inappropriate' },
{ id: 'robbery', label: 'Robbery' },
{ id: 'nsfw', label: 'NSFW' },
]
}
```
## Configure `maxDays` In Notification Tool and Notification Element
Set maximum days for notifications tool and notifications element by using the `setMaxDays()` API method. By default, the maximum days are set to 30.
```jsx theme={null}
```jsx theme={null}
API Methods:
```jsx theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.setMaxDays(15);
```
```jsx theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.setMaxDays(15);
```
## Added New Action Types
We have added new action types within notifications: `reactionAdded`, `reactionDeleted`.
## Added Notifications Metadata Type
Added notifications metadata type. User will get this metadata from `notification.metadata` object in the notification callback. [Learn more](/api-reference/sdk/models/data-models#notification#notificationmetadata-class-properties).
```jsx theme={null}
export class NotificationMetadata {
apiKey?: string;
clientOrganizationId?: string;
organizationId?: string;
clientDocumentId?: string | number;
documentId?: string;
locationId?: number;
location?: Location;
}
```
## Added `customListDataOnComment` Method
For Autocomplete data, you can now directly set the data from comment element.
```jsx theme={null}
const customListDataOnComment: {
hotkey: string,
type: string,
data: {
id: string,
name: string,
description: string
}[]
} = {
hotkey: "!",
type: "custom",
data: [
{
id: '1',
name: 'Name 1',
description: 'Test Description 1'
},
{
id: '2',
name: 'Name 2',
description: 'Test Description 2'
},
{
id: '3',
name: 'Name 3',
description: 'Test Description 3'
}
],
}
```
API Methods
```jsx theme={null}
const commentElement = client.getCommentElement();
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.createCustomListDataOnComment(customListDataOnComment);
```
# July 31 2024
Source: https://docs.velt.dev/release-notes/archive/july-31-2024
## Versions
* Latest React SDK: [2.0.24](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.24](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.24](https://www.npmjs.com/package/@veltdev/types)
## Added the option to Subscribe/Unsubscribe at Thread Level
Within the comments dialog options dropdown, we have added subscribe/unsubscribe wireframes. [Learn more](/ui-customization/features/async/comments/comment-dialog/subcomponents/options-dropdown).
```jsx theme={null}
```
```jsx theme={null}
```
## Added the Option to Add a Custom Initial in the User Object
Users can now add an optional custom initial within the [user object](https://docs.velt.dev/api-reference/sdk/models/data-models#user). If the initial is not provided in the identify call or the Add User REST API, we will automatically create it using the name.
## Added Search on Organization Names
We have added the feature to search on organization names in the contact list, if present.
## Added Delete Button on the Thread Header
You can now add a delete button within the comments dialog thread header. [Learn more](/ui-customization/features/async/comments/comment-dialog/subcomponents/header).
```jsx theme={null}
Delete
```
```jsx theme={null}
Delete
```
# June 10 2024
Source: https://docs.velt.dev/release-notes/archive/june-10-2024
## Versions
* Latest SDK: [1.0.147](https://www.npmjs.com/package/@veltdev/react)
* Latest Types: [1.0.164](https://www.npmjs.com/package/@veltdev/types)
## Updated JWT Token to include user properties such as groupId and isAdmin
We updated the body that is sent to the `https://api.velt.dev/v1/auth/token/get` [JWT Token endpoint](/security/jwt-tokens) to include user properties such as `groupId` and `isAdmin`.
The `groupId` field is used to validate that the `groupId` provided in the `identify` call is the same as the one passed to the JWT Token.
The `isAdmin` field is used to set a user as an `admin`.
| Field | Required | Description |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `apiKey` | Yes | Velt API Key |
| `authToken ` | Yes | Auth Token from the Velt console |
| `userId ` | Yes | Unique user id of the user |
| `userProperties.groupId` | No | If `groupId` is provided, it will be validated with the groupId used in the identify call. Recommended if you are setting `groupIds` |
| `userProperties.isAdmin` | No | Set to `true` if you want to set user as `admin`. This is the only way to set a user as an `admin` User |
```jsx theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY", //Velt API Key
"authToken": "YOUR_AUTH_TOKEN", // Auth Token from the Velt console
"userId": "yourUserId", // unique user id of the user you are generating a JWT Token for
"userProperties": {
groupId: "YOUR_USER_GROUP_ID", // If groupId is provided here then we will validate it with the groupId used in the identify call
isAdmin: true, // Set to true if you want to set user as admin
}
}
}
```
## Option to force re-login user on identify call
By default when you [identify](/get-started/advanced) a user, we maintain the user auth in the browser unless you explicitly change the logged in user with another identify call.
If you are granting a user additional access or have changed some metadata about the user and want those changes to be reflected immediately, then you should re-call the identify method with `forceReset` set to `true`.
```jsx theme={null}
await client.identify(user, {
forceReset: true
});
```
# June 24 2024
Source: https://docs.velt.dev/release-notes/archive/june-24-2024
## Versions
* Latest React SDK: [1.0.158](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [1.0.158](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [1.0.178](https://www.npmjs.com/package/@veltdev/types)
## Added `onContactSelected` API Method
We have introduced the [`onContactSelected`](/api-reference/sdk/api/api-methods#client#oncontactselected) API method in the Contact Element. This new method allows organization clients to add selected users to their organization or document-level IAM directly.
API Method:
```jsx theme={null}
const contactElement = client.getContactElement();
contactElement.onContactSelected().subscribe((data: any) => {
console.log('contact selected: ', data);
});
```
```jsx theme={null}
const contactElement = Velt.getContactElement();
contactElement.onContactSelected().subscribe((data: any) => {
console.log('contact selected: ', data);
});
```
React Hook:
```jsx theme={null}
import React, { useEffect } from 'react';
import { useContactUtils, useContactSelected } from '@veltdev/react';
function YourComponent() {
const contactUtils = useContactUtils();
useEffect(() => {
console.log('contactUtils: ', contactUtils);
}, [contactUtils]);
const onContactSelected = useContactSelected();
useEffect(() => {
console.log('onContactSelected: ', onContactSelected);
}, [onContactSelected]);
return (
// Your component code
);
}
```
API Method Response Payload:
```jsx theme={null}
export class UserContactSelectedPayload {
/**
* Selected user contact details.
*/
contact!: UserContact;
/**
* Is user part of organization contact.
*/
isOrganizationContact!: boolean;
/**
* Is user part of document contact.
*/
isDocumentContact!: boolean;
/**
* Document access type.
*/
documentAccessType!: string;
}
```
# June 29 2024
Source: https://docs.velt.dev/release-notes/archive/june-29-2024
## Versions
* Latest React SDK: [1.0.159](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [1.0.159](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [1.0.177](https://www.npmjs.com/package/@veltdev/types)
## Added `organizationGroups` Support in Contacts and Autocomplete Feature
Within the contacts and autocomplete features we have added the support for `organizationGroups`.
## Added Various Methods in Contact Element
We have introduced three new methods in the Contact Element: [`enableAtHere`](/api-reference/sdk/api/api-methods#client#enableathere), [`disableAtHere`](/api-reference/sdk/api/api-methods#client#disableathere), and [`updateContactListScopeForOrganizationUsers`](/api-reference/sdk/api/api-methods#client#updatecontactlistscopefororganizationusers).
API Methods:
```jsx theme={null}
const contactElement = client.getContactElement();
// To enable @here for contact list
contactElement.enableAtHere();
// To disable @here for contact list
contactElement.disableAtHere();
/**
* Update contact list scope for organization users.
* @param scope ContactListScopeForOrganizationUsers[]
*/
contactElement.updateContactListScopeForOrganizationUsers(['all', 'organization', 'organizationUserGroup', 'document']);
```
```jsx theme={null}
const contactElement = Velt.getContactElement();
// To enable @here for contact list
contactElement.enableAtHere();
// To disable @here for contact list
contactElement.disableAtHere();
/**
* Update contact list scope for organization users.
* @param scope ContactListScopeForOrganizationUsers[]
*/
contactElement.updateContactListScopeForOrganizationUsers(['all', 'organization', 'organizationUserGroup', 'document']);
```
# June 30 2024
Source: https://docs.velt.dev/release-notes/archive/june-30-2024
## Versions
* Latest React SDK: [2.0.4](https://www.npmjs.com/package/@veltdev/react)
* Latest Non-React SDK: [2.0.4](https://www.npmjs.com/package/@veltdev/client)
* Latest Types: [2.0.4](https://www.npmjs.com/package/@veltdev/types)
## Added REST APIs
We have added REST APIs so that developers have more control when it comes to accessing and setting data.
REST APIs is a featureset that will have continued expansion but the current REST APIs give improved control over **Organizations**, **Documents**, **Users**, **Organization User Groups**, and **Comments**.
More REST APIs will be coming soon!
### [Organizations APIs](/api-reference/rest-apis/organizations/add-organizations)
1. Add Organizations
2. Update Organizations
3. Delete Organizations
4. Get Organizations
5. Update Disabled State for Organizations
### [Documents APIs](/api-reference/rest-apis/documents/add-documents)
1. Add Documents
2. Update Documents
3. Delete Documents
4. Get Documents
5. Update Access for Documents
6. Update Disabled State for Documents
### [Users APIs](/api-reference/rest-apis/v2/users/add-users)
1. Add Users
2. Update Users
3. Delete Users
4. Get Users
### [Organization User Groups APIs](/api-reference/rest-apis/v2/users/add-users)
1. Add User Groups
2. Add Users to Groups
3. Delete Users from Groups
### [Commenting APIs](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations)
1. Add Comment Annotations
2. Update Comment Annotations
3. Delete Comment Annotations
4. Get Comment Annotations
5. Add Comments
6. Update Comments
7. Delete Comments
8. Get Comments
# June 6 2024
Source: https://docs.velt.dev/release-notes/archive/june-6-2024
## Versions
* Latest SDK: [1.0.144](https://www.npmjs.com/package/@veltdev/react)
* Latest Types: [1.0.161](https://www.npmjs.com/package/@veltdev/types)
# 1. Major Improvements to Comments Sidebar Customization
In this update, we made several improvements to the `Customization` of the `Comments Sidebar` and `Sidebar Button`
## Support for customizing additional Subcomponents within the Comments Sidebar and Sidebar Button
We modified or added support for customizing the following `subcomponents` of the `Comments Sidebar`:
* [Filter](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/overview)
* [Filter Category](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/category)
* [Filter Close Button](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/close-button)
* [Filter Done Button](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/done-button)
* [Filter Item](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
* [Filter Groupby](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/groupby)
* [Filter Location](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/location)
* [Filter People](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/people)
* [Filter Priority](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/priority)
* [Filter Title](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/title)
* [Filter Versions](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/versions)
* [Header](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/overview)
* [Header Status](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/overview)
* [Header Status Trigger](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/subcomponents/trigger)
* [Header Status Content](/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/subcomponents/content)
* [List](/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/overview)
* [List Dialog Container](/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/subcomponents/dialog-container)
* [List Group](/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/subcomponents/group)
We modified or added support for customizing the following `subcomponents` of the `Sidebar Button`:
* [Sidebar Button](/ui-customization/features/async/comments/comments-sidebar/sidebar-button/overview)
* [Sidebar Button Icon](/ui-customization/features/async/comments/comments-sidebar/sidebar-button/subcomponents/icon)
## Subcomponent Name Changes
We changed the names of several subcomponents:
* `` -> ``
The `Private Badge` subcomponent was moved from being a child of `Comment Dialog` to being a child of the `Comment Dialog Composer`:
* ``
* `` -> ``
# 2. Live State Sync changes
## `getLiveStateData()` now has a config option to only subscribe to new changes
By default, the [getLiveStateData()](/realtime-collaboration/live-state-sync/setup) subscription will return all changes to the shared live data object including changes that occured when the current client was not subscribed.
If you want to only receive changes starting from when the client subscribed to `getLiveStateData()`, you can pass a config object as shown below:
```jsx theme={null}
const liveStateDataConfig = {
listenToNewChangesOnly: true // default is false
};
let subscription = liveStateSyncElement.getLiveStateData(LIVE_STATE_DATA_KEY, liveStateDataConfig).subscribe((data) => {
console.log('[Debug] getLiveStateData 31-05-2024-2 in html', data);
});
```
This also applies to the `useLiveStateData()` hook:
```jsx theme={null}
const liveStateDataConfig = {
listenToNewChangesOnly: true // default is false
};
const liveStateData = useLiveStateData(LIVE_STATE_DATA_KEY, liveStateDataConfig)
```
As well as the `useLiveState()` hook:
```jsx theme={null}
const [counter, setCounter] = useLiveState < number > ("counter", 0, {
syncDuration: 100,
resetLiveState: true,
listenToNewChangesOnly: true // default is false
});
```
## Method to listen to changes in server connection state
You can listen to changes in the server connection state with the [onServerConnectionStateChange()](/realtime-collaboration/live-state-sync/setup) method:
```jsx theme={null}
const liveStateSyncElement = client.getLiveStateSyncElement();
let subscription = liveStateSyncElement.onServerConnectionStateChange().subscribe((data) => {
console.log('server connection state change: ', data);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
The server connection state will be an ENUM with the following states:
```jsx theme={null}
export enum ServerConnectionState {
ONLINE = 'online',
OFFLINE = 'offline',
PENDING_INIT = 'pendingInit',
PENDING_DATA = 'pendingData',
}
```
You can also listen to changes in the server connection state using the `useServerConnectionStateChangeHandler()` hook as well:
```jsx theme={null}
const serverConnectionState = useServerConnectionStateChangeHandler();
```
# 3. Updates to Popover Comments
## Added support for Popover comments using Single Comment Tool
There are now two patterns to add the `Comment Tool` component with [Popover comments](/async-collaboration/comments/setup/popover):
* (Already Existed) Add a `Comment Tool` next to each element you want to have `Popover` comments
* (New) Have a single `Comment Tool` and use it to pin a `Popover `comment on a particular element
### Single Comment Tool
If you want to have a single `Comment Tool` in a single location such as the navigation bar, you can do so as well.
To do this, add `data-velt-target-comment-element-id` as an attribute on each element you want to add comments on.
Now, when you click on the `Comment Tool` and click on the target element, it will attach a `Popover` comment to the element.
You will now notice that you can only add one `Comment Annotation` per element.
If you don't add the `data-velt-target-comment-element-id` attribute, you will be adding multiple `Comment Annotations` on the same element.
```jsx theme={null}
```
# March 14 2024
Source: https://docs.velt.dev/release-notes/archive/march-14-2024
## Versions
* Latest SDK: [1.0.96](https://www.npmjs.com/package/@veltdev/react)
* Latest Types: [1.0.111](https://www.npmjs.com/package/@veltdev/types)
## Notifications Component
The [Notifications](/async-collaboration/notifications/setup) component can be used to notify your users in-app when they receive a reply to a comment or are `@mentioned` by a teammate.
You will need to [enable Notifications in your console](https://console.velt.dev/dashboard/config/notification) in order for Notifications component to work.
)
}
```
## Custom Notifications
Additionally, you can [send custom notifications](/async-collaboration/notifications/api-add-notification) to this component using our `https://api.velt.dev/v1/notifications/add` API end point.
Sample Post Request:
```jsx theme={null}
const options = {method: 'POST', body: JSON.stringify(body)};
fetch('https://api.velt.dev/v1/notifications/add', options)
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
Sample Body:
```jsx theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY",
"authToken": "YOUR_AUTH_TOKEN",
"documentId": "YOUR_DOCUMENT_ID",
"actionUser": {
"email": "actionuseremail@domain", // required
"name": "Action Username", // optional
"photoUrl": "Action User Photo URL", // optional
"userId": "User ID", // required
},
"displayHeadlineMessageTemplate": "This is main template, you can pass variables using curly brackets like this: {actionUser}, {recipientUser}, {yourCustomVariableWithStringValue}",
"displayHeadlineMessageTemplateData": {
"actionUser": {
"email": "actionuseremail@domain", // required
"name": "Action Username", // optional
"photoUrl": "Action User Photo URL", // optional
"userId": "User ID", // required
},
"recipientUser": {
"email": "recipientuseremail@domain", // required
"name": "Recipient Username", // optional
"photoUrl": "Recipient User Photo URL", // optional
"userId": "User ID", // required
},
"yourCustomVariableWithStringValue": "Variable will be replaced with this text"
},
"displayBodyMessage": "This is body message (Secondary message)",
// Pass list of users who should be notified, notification will be shown to all the users in all section in notification panel and notification history panel, but it will be shown in 'forYou' section also to notifyUsers.
"notifyUsers": [
{
"email": "notifyuseremail@domain", // required
"name": "Notify User Name", // optional
"photoUrl": "Notify User Photo URL", // optional
"userId": "User ID", // required
}
]
}
}
```
## Dark Mode on All Tool and Button Components
You can now configure Dark Mode individually on all Tool and Button Components in the Velt SDK.
Example:
```jsx theme={null}
Lorem ipsum dolor sit amet consectetur adipisicing elit. Dolorum, consequatur.
```
## Event Handler for Click Events on Presence Users
Implemented the [onPresenceUserClick](/realtime-collaboration/presence/customize-behavior) event handler for click events on Presence avatar circles.
```jsx theme={null}
const onPresenceUserClickEvent = (user) => {
console.log("Clicked presence user: ", user);
}
onPresenceUserClickEvent(user)} />
```
## Option to disclude current user from list of Presence Users
The [self](/realtime-collaboration/presence/customize-behavior) property can be used to include or disclude the current user from the list of Presence users. By default the current user is added.
```js theme={null}
setCounter((counter || 0) - 1)}>-
Counter: {counter}
setCounter((counter || 0) + 1)}>+
);
}
```
## Option to [Enable DOM Change Detection in Comment Mode](https://docs.velt.dev/async-collaboration/comments/customize-behavior/general-controls)
By default, we skip `Comment` `DOM Change Detection` when users are in `Comment Mode` to improve performance.
However, you can turn `Comment` `DOM Change Detection` back on with the `changeDetectionInCommentMode` property.
This will make `Comment's` reposition themselves if the DOM happens to change while in `Comment Mode`.
`Default: false`
```jsx theme={null}
#Your wireframe for variant sidebar1
#Your wireframe for variant sidebar2
```
To use a specific variant, define it on the `variant` props when using the Velt component in your app.
```jsx theme={null}
```
## Added Custom Dropdown Lists
You can have [custom dropdown lists](/async-collaboration/comments/customize-behavior/autocomplete) appear when certain `hotkeys` are pressed.
When you press a `hotkey` inside the `Comment Dialog` composer, it will open a dropdown list of items that you can select.
onCommentSelectionChange(data)} />
```
Callback response schema:
```jsx theme={null}
export class CommentSelectionChangeData {
selected!: boolean;
annotation!: CommentAnnotation;
}
```
API Methods:
```jsx theme={null}
const commentElement = client.getCommentElement();
let subscription = commentElement.onCommentSelectionChange().subscribe((data) => {
console.log('onCommentSelectionChange: ', data);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
Using Hooks:
The `useCommentSelectionChangeHandler` hook can be used to subscribe to Comment selection changes.
```jsx theme={null}
import React, { useEffect } from 'react';
import { useCommentSelectionChangeHandler } from '@veltdev/react';
function YourComponent() {
const commentSelectionChange = useCommentSelectionChangeHandler();
useEffect(() => {
console.log('commentSelectionChange', commentSelectionChange);
}, [commentSelectionChange]);
return (
<>
Selected Comment: {commentSelectionChange.annotation.id}
);
}
```
## Added prop to enable or disable Comment Pin Highlighter
The API Methods already existed, but we added a prop to enable or disable the [Comment Pin Highlighter](/async-collaboration/comments/customize-behavior/ui-controls)
```jsx theme={null}
Custom HTML
```
#### a. `With Parent` - Modifying the subcomponent within the context of its parent within the `
{/* Skeleton */}
...
{/* Header */}
Custom HTML
{/* Filter */}
...
{/* List */}
```
If you modify the component in both the `Parentless` and `With Parent` pattern, the `With Parent` pattern will override the `Parentless` pattern.
## Detect if Velt SDK is initialized
[To detect if the Velt SDK is initialized](/get-started/advanced), subscribe using the following method:
```jsx theme={null}
let subscription = client.getVeltInitState().subscribe((veltInitState: boolean | undefined) => {
console.log('Velt Init State:', veltInitState);
});
```
To unsubscribe from the subscription:
```jsx theme={null}
subscription?.unsubscribe()
```
You can also the use `useVeltInitState()` hook:
```jsx theme={null}
import { useVeltInitState } from '@veltdev/react';
function YourComponent() {
const veltInitState = useVeltInitState();
useEffect(() => {
console.log('Velt Init State:', veltInitState);
if (veltInitState) {
// Velt state is initialized, so user can perform any action here
}
}, [veltInitState]);
}
```
# BlockNote CRDT Library
Source: https://docs.velt.dev/release-notes/version-4/blocknote-changelog
Release Notes of Changes Affecting Velt BlockNote Library
### Libraries
* `@veltdev/blocknote-crdt`
* `@veltdev/blocknote-crdt-react`
### Improvements
* \[**Core**]: Improved the API signatures and naming to improve developer experience.
### Improvements
* \[**Core**]: Released a purpose built react package (`@veltdev/blocknote-crdt-react`) that reduced the implementation code by 95%.
### Bug Fixes
* \[**Core**]: Fixed an issue where last keystroke was not synced in some cases.
### New Features
* \[**Core**]: Introduced purpose built CRDT library for BlockNote Editor to enable multiplayer editing. This is based on the [Yjs](https://docs.yjs.dev/) library. [Learn more](/realtime-collaboration/crdt/setup/blocknote).
# CodeMirror CRDT Library
Source: https://docs.velt.dev/release-notes/version-4/codemirror-changelog
Release Notes of Changes Affecting Velt CodeMirror Library
### Libraries
* `@veltdev/codemirror-crdt`
* `@veltdev/codemirror-crdt-react`
### Improvements
* \[**Core**]: Improved CRDT store initialization by using `veltInitState` for streamlined internal store creation.
### Bug Fixes
* \[**Core**]: Fixed multi-tab synchronization for same user. When the same user edits content in multiple tabs, all tabs now sync correctly.
### Improvements
* \[**Core**]: Released stable version 4.5.8 of CodeMirror CRDT packages.
### New Features
* \[**Developer Tools**]: Added `window.VeltCrdtStoreMap` global interface to inspect and monitor CRDT stores during development. Access store values directly in the browser console using `VeltCrdtStoreMap.get(id)` or `VeltCrdtStoreMap.getAll()`. Subscribe to store updates and monitor registration events for debugging collaborative data synchronization. [Learn more](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap)
### Bug Fixes
* \[**Core**]: Fixed `initialContent` not being applied when no server-side data exists. You can now set `initialContent` in CodeMirror CRDT, and it will be used when the document is empty.
```jsx theme={null}
const { store, isLoading } = useVeltCodeMirrorCrdtExtension({
editorId: "UNIQUE_EDITOR_ID",
initialContent: "body { background-color: lightgrey; }",
});
```
```javascript theme={null}
const result = veltClient.getVeltCodeMirrorCrdtExtension({
editorId: "UNIQUE_EDITOR_ID",
initialContent: "body { background-color: lightgrey; }",
});
```
### Improvements
* \[**Core**]: Improved the API signatures and naming to improve developer experience.
### Improvements
* \[**Core**]: Released a purpose built react package (`@veltdev/codemirror-crdt-react`) that reduced the implementation code by 95%.
### Bug Fixes
* \[**Core**]: Fixed an issue where last keystroke was not synced in some cases.
### Improvements
* \[**Awareness**]: Adding support for awareness enabling features like live cursors and selection highlighting.
### New Features
* \[**Core**]: Introduced purpose built CRDT library for CodeMirror Editor to enable multiplayer editing. This is based on the [Yjs](https://docs.yjs.dev/) library. [Learn more](/realtime-collaboration/crdt/setup/codemirror).
# Core CRDT Library
Source: https://docs.velt.dev/release-notes/version-4/crdt-core-changelog
Release Notes of Changes Affecting All CRDT Libraries
### Libraries
* `@veltdev/crdt`
* `@veltdev/crdt-react`
### Improvements
* \[**Core**]: Improved CRDT store initialization by replacing user-based detection with `veltInitState`. Streamlines internal store creation logic.
### Bug Fixes
* \[**Core**]: Fixed multi-tab synchronization for same user. When the same user edits content in multiple tabs, all tabs now sync correctly.
### Improvements
* \[**Core**]: Released stable version 4.5.8 of all CRDT packages (except BlockNote packages). This version includes Tiptap v3 support and resolves the initialContent issue in tiptap-crdt-react.
### New Features
* \[**Developer Tools**]: Added `window.VeltCrdtStoreMap` global interface to inspect and monitor CRDT stores during development. Access store values directly in the browser console using `VeltCrdtStoreMap.get(id)` or `VeltCrdtStoreMap.getAll()`. Subscribe to store updates and monitor registration events for debugging collaborative data synchronization. [Learn more](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap)
```jsx theme={null}
// Get a specific store
const storeInstance = window.VeltCrdtStoreMap.get('my-store-id');
if (storeInstance) {
const currentValue = storeInstance.getValue();
console.log('Current store value:', currentValue);
// Subscribe to store changes
const unsubscribe = storeInstance.subscribe((newValue) => {
console.log('Store updated:', newValue);
});
}
// Get all registered stores
const allStores = window.VeltCrdtStoreMap.getAll();
console.log('All stores:', allStores);
// Access the stores map directly
const storesMap = window.VeltCrdtStoreMap.stores;
console.log('Stores map:', storesMap);
// Listen for store registration events
window.addEventListener('veltCrdtStoreRegister', (event) => {
console.log('Store registered:', event.detail);
});
// Listen for store unregistration events
window.addEventListener('veltCrdtStoreUnregister', (event) => {
console.log('Store unregistered:', event.detail);
});
```
```html theme={null}
```
### Bug Fixes
* \[**Core**]: Fixed `initialContent` not being applied when no server-side data exists. You can now set initial content in CRDT libraries, and it will be used when the document is empty.
### Bug Fixes
* \[**Core**]: Fixed CRDT synchronization issue affecting document changes in Velt CRDT SDK.
### Bug Fixes
* \[**Core**]: Fixed an issue with where versions were not being saved correctly in some cases.
### Bug Fixes
* \[**Core**]: Fixed an issue where last keystroke was not synced in some cases. Also fixed synchronization issues with React Flow nodes and edges.
### New Features
* \[**Security**]: Enhanced security for CRDTs with a new `encryptionProvider`. This allows you to provide custom encryption and decryption methods to secure your collaborative data.
* See [Custom Encryption](/realtime-collaboration/crdt/setup/core#custom-encryption) for setup instructions.
### New Features
* \[**Core**]: Introduced versioning support for CRDT stores. You can now save snapshots of your collaborative data, list previously saved versions, and restore the store to a specific version. This feature is currently supported for `text` and `array` data types.
### New Features
* \[**Core**]: Introduced our latest CRDT Libraries based on Yjs:
* `@veltdev/crdt`: Framework-agnostic CRDT stores (array, map, text, xml), versioning, subscriptions, and syncing via the Velt client.
* `@veltdev/crdt-react`: React Hook wrapper for CRDT integration.
* `@veltdev/tiptap-crdt`: Purpose built CRDT library for Tiptap Editor to enable multiplayer editing.
# Lexical Changelog
Source: https://docs.velt.dev/release-notes/version-4/lexical-changelog
Release Notes of Changes Affecting Velt Lexical Library
### Improvements
* \[**Comments**]: Refactored `@veltdev/lexical-velt-comments` to follow a common pattern and folder structure across all libraries. This enables faster development of Velt comment integrations and covers more rich text editor scenarios.
### New Features
* \[**Lexical**]: Released documentation for our Lexical CRDT integration. Also added a new `exportJSONWithoutComments` utility to serialize editor content without including comment nodes.
```javascript theme={null}
import { exportJSONWithoutComments } from '@veltdev/lexical-velt-comments';
const cleanState = exportJSONWithoutComments(editor);
```
# React Flow CRDT Library
Source: https://docs.velt.dev/release-notes/version-4/reactflow-changelog
Release Notes of Changes Affecting Velt React Flow Library
### Libraries
* `@veltdev/reactflow-crdt`
### Improvements
* \[**Core**]: Fixed an issue with the ReactFlow CRDT production build where certain test cases were failing. All test cases now pass correctly in production builds.
### Bug Fixes
* \[**Core**]: Fixed multi-tab synchronization for same user. When the same user edits content in multiple tabs, all tabs now sync correctly.
### Improvements
* \[**Core**]: Released stable version 4.5.8 of ReactFlow CRDT package.
### New Features
* \[**Developer Tools**]: Added `window.VeltCrdtStoreMap` global interface to inspect and monitor CRDT stores during development. Access store values directly in the browser console using `VeltCrdtStoreMap.get(id)` or `VeltCrdtStoreMap.getAll()`. Subscribe to store updates and monitor registration events for debugging collaborative data synchronization. [Learn more](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap)
### Bug Fixes
* \[**Core**]: Fixed `initialContent` not being applied when no server-side data exists. You can now set `initialEdges` and `initialNodes` in ReactFlow CRDT, and they will be used when the document is empty.
```jsx theme={null}
const { nodes, edges, onNodesChange, onEdgesChange, onConnect } = useVeltReactFlowCrdtExtension({
editorId: "UNIQUE_EDITOR_ID",
initialEdges: [
{
id: "edge1",
source: "node1",
target: "node2",
},
],
initialNodes: [
{
id: "node1",
type: 'input',
data: { label: `Node 1` },
position: { x: 0, y: 50 },
},
{
id: "node2",
type: 'default',
data: { label: `Node 2` },
position: { x: 0, y: 150 },
}
],
});
```
```javascript theme={null}
const result = veltClient.getVeltReactFlowCrdtExtension({
editorId: "UNIQUE_EDITOR_ID",
initialEdges: [
{
id: "edge1",
source: "node1",
target: "node2",
},
],
initialNodes: [
{
id: "node1",
type: 'input',
data: { label: `Node 1` },
position: { x: 0, y: 50 },
},
{
id: "node2",
type: 'default',
data: { label: `Node 2` },
position: { x: 0, y: 150 },
}
],
});
```
### New Features
* \[**Core**]: Optimized the library to reduce the implementation code by 95%.
### Bug Fixes
* \[**Core**]: Fixed an issue where last keystroke was not synced in some cases. Also fixed synchronization issues with React Flow nodes and edges.
### New Features
* \[**Core**]: Introduced purpose built CRDT library for React Flow Editor to enable multiplayer editing. This is based on the [Yjs](https://docs.yjs.dev/) library. [Learn more](/realtime-collaboration/crdt/setup/reactflow).
# Velt SDK Changelog
Source: https://docs.velt.dev/release-notes/version-4/sdk-changelog
Release Notes of changes added to the core Velt SDK
### Libraries
* `@veltdev/react`
* `@veltdev/client`
* `@veltdev/sdk`
### Bug Fixes
* \[**Comments**]: Fixed sidebar comment navigation scrolling the page unexpectedly. The window scroll position is now captured and restored after `scrollIntoView()` runs, so only the sidebar panel scrolls and the page remains at its current position.
### Bug Fixes
* \[**Comments**]: Fixed sidebar not auto-exiting focused thread mode when the annotation is deselected. The sidebar now automatically exits focused thread mode and returns to the "all comments" view when the focused annotation is deselected.
### New Features
* \[**Comments**]: Added `attachmentDownloadClicked` event and methods to control automatic attachment downloads. You can now intercept download clicks to implement custom download behavior such as analytics tracking, custom URLs, or access control checks.
```jsx theme={null}
// Using Hooks
import { VeltComments, useCommentUtils } from '@veltdev/react';
// Disable automatic downloads via component prop
```html theme={null}
### Improvements
* \[**Comments**]: Moved attachment loading indicator to a parent wrapper element for better CSS targeting. Custom CSS targeting `.loading` on attachment elements should be updated to target `.velt-composer-attachment--loading` on `.velt-composer-attachment-container`.
### Bug Fixes
* \[**Comments**]: Fixed unintended draft auto-save when navigating back from a focused thread view.
* \[**Comments**]: Fixed sidebar not deselecting annotations when navigating back from a focused thread.
* \[**Comments**]: Fixed thread card attachments not falling back to default rendering when an empty wireframe template is provided.
* \[**Comments**]: Fixed edit composer not rendering when custom thread card wireframe omits the edit composer wireframe. The default edit composer now renders automatically.
### Bug Fixes
* \[**Comments**]: Fixed `ADD_COMMENT` event not firing for page comment annotations. Event listeners subscribed to `ADD_COMMENT` now receive callbacks consistently for all comment creation flows, including page comments.
### Improvements
* \[**Comments**]: Added a `readOnly` prop to `VeltCommentComposer` and `VeltInlineCommentsSection` components that allows disabling comment input at the component level. Developers can now create mixed read/write interfaces where some comment areas are locked while others are interactive.
```jsx theme={null}
// Using Hooks
import { VeltCommentComposer, VeltInlineCommentsSection } from '@veltdev/react';
```html theme={null}
```
* \[**Comments**]: A new edit composer wireframe for the comment dialog lets you customize the edit composer UI within comment thread cards.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: You can associate comments created via the page mode composer with specific elements using the `targetElementId` property.
```jsx theme={null}
// Using Hooks
import { useCommentUtils } from '@veltdev/react';
const commentElement = useCommentUtils();
commentElement.setContextInPageModeComposer({
context: { projectId: 'abc123' },
targetElementId: 'my-target-element'
});
// Using API methods
const commentElement = client.getCommentElement();
commentElement.setContextInPageModeComposer({
context: { projectId: 'abc123' },
targetElementId: 'my-target-element'
});
```
```html theme={null}
```
* \[**Comments**]: Added `CommentAnnotation.resolvedByUser` property to expose the full `User` object so you can access it without additional API calls.
* \[**Comments**]: `setAssignToType()` now accepts an `AssignToConfig` object for consistent API patterns.
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
commentElement.setAssignToType({ type: 'dropdown' });
// or
commentElement.setAssignToType({ type: 'checkbox' });
// Using API methods
const commentElement = client.getCommentElement();
commentElement.setAssignToType({ type: 'dropdown' });
```
```html theme={null}
```
* \[**Comments**]: Added `targetElementId` to `CommentToolClickEvent` so you can identify which element was targeted when users initiate a comment.
```jsx theme={null}
// Using Hooks
const commentToolClickEvent = useCommentEventCallback('commentToolClick');
useEffect(() => {
if (commentToolClickEvent) {
console.log('Context:', commentToolClickEvent.context);
console.log('Target Element ID:', commentToolClickEvent.targetElementId);
}
}, [commentToolClickEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('commentToolClick').subscribe((event) => {
console.log('Target Element ID:', event.targetElementId);
});
```
```html theme={null}
```
### Bug Fixes
* \[**Comments**]: Fixed cursor position jumping when clicking autocomplete tool buttons so that @ mention and other autocomplete triggers now insert at the correct cursor position.
* \[**Comments**]: Fixed actions menu visibility in comment dialog so the menu on the first thread card remains visible when the assignment dropdown is opened.
* \[**Comments**]: Added "Assign" tooltip to the assignment button in comment dialog thread cards.
* \[**Comments**]: Added `velt-reaction-pin--no-reactions` CSS class to empty reaction pins for custom styling.
* \[**Comments**]: Fixed autocomplete panel viewport height calculation to respect custom `itemSize` from `autoCompleteScrollConfig`.
* \[**Comments**]: Fixed attachment upload failures by using fallback metadata values from document paths and config service.
* \[**Comments**]: Fixed read-only state management so local `readOnly` props are no longer overridden by global read-only state changes.
### New Features
* \[**Comments**]: Added Thread card assign button wireframe to customize the assign button that appears on individual comment thread cards.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Comments**]: Added a CSS class to indicate the selected state on the assign dropdown checkbox.
### Bug Fixes
* \[**Comments**]: Fixed "Assign To" label capitalization to "Assign to" for proper sentence case.
### New Features
* \[**Comments**]: Added ability to set context data and focus the page mode composer programmatically using `setContextInPageModeComposer()` and `focusPageModeComposer()` methods.
```jsx theme={null}
// Using Hooks
import { useCommentUtils } from '@veltdev/react';
const commentElement = useCommentUtils();
// Set context data for the page mode composer
commentElement.setContextInPageModeComposer({
documentId: 'doc-123',
sectionId: 'section-456',
customData: 'any-value'
});
// Clear the context
commentElement.setContextInPageModeComposer(null);
// Focus the page mode composer input
commentElement.focusPageModeComposer();
// Using API methods
const commentElement = client.getCommentElement();
commentElement.setContextInPageModeComposer({ documentId: 'doc-123' });
commentElement.focusPageModeComposer();
```
```html theme={null}
```
* \[**Comments**]: Added a new `commentToolClick` event that fires when the comment tool button is clicked.
```jsx theme={null}
// Using Hooks
const commentToolClickEvent = useCommentEventCallback('commentToolClick');
useEffect(() => {
if (commentToolClickEvent) {
console.log('Comment tool clicked');
console.log('Context:', commentToolClickEvent.context);
console.log('Target Element ID:', commentToolClickEvent.targetElementId);
}
}, [commentToolClickEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('commentToolClick').subscribe((event) => {
console.log('Context:', event.context);
});
```
```html theme={null}
```
* \[**Comments**]: Added a new `sidebarButtonClick` event that fires when the sidebar button is clicked.
```jsx theme={null}
// Using Hooks
const sidebarButtonClickEvent = useCommentEventCallback('sidebarButtonClick');
useEffect(() => {
if (sidebarButtonClickEvent) {
console.log('Sidebar button clicked');
}
}, [sidebarButtonClickEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('sidebarButtonClick').subscribe((event) => {
console.log('Metadata:', event.metadata);
});
```
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed `reactionId` prop on `VeltCommentDialogWireframe.ThreadCard.ReactionPin` not converting to dashed-case format when passed to the underlying HTML element.
### New Features
* \[**Comments**]: Added ability to configure the assign-to functionality to use either a dropdown or checkbox mode for assigning users to comments.
```jsx theme={null}
// Using component
import { VeltComments } from '@veltdev/react';
```html theme={null}
* \[**Comments**]: Context in page mode composer—pass context data to the page mode composer when opening the comment sidebar via the comment tool.
```jsx theme={null}
// Using component
import { VeltCommentTool } from '@veltdev/react';
```html theme={null}
```
* \[**Comments**]: Added `clearPageModeComposerContext()` method to clear context data from page mode composer. This is useful when you are using sidebar in embed mode and have to clear the context from page mode composer manually.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.clearPageModeComposerContext();
```
```html theme={null}
```
* \[**Comments**]: Reaction pin component—display specific reaction pins within comment thread cards using the new `VeltCommentDialogThreadCardReactionPin` wireframe component.
```jsx theme={null}
import { VeltCommentDialogWireframe } from '@veltdev/react';
```
```html theme={null}
```
* \[**Comments**]: Exclude reactions from thread cards—exclude specific reactions from being displayed using `excludeReactionIds` on `VeltCommentDialogThreadCardReactions` and `VeltCommentDialogThreadCardReactionTool` components.
```jsx theme={null}
import { VeltCommentDialogWireframe } from '@veltdev/react';
```html theme={null}
```
* \[**Comments**]: Assigned to me filter—filter comments assigned to the current user using the new filter option in the comment sidebar minimal filter dropdown.
```jsx theme={null}
import { VeltCommentsSidebarWireframe } from '@veltdev/react';
```
```html theme={null}
```
* \[**Comments**]: Batched per-document comment counts—added `batchedPerDocument` and `debounceMs` properties to `CommentRequestQuery`. This feature was documented in v5.0.0-beta.10 and has been backported to v4.x.
### Bug Fixes
* \[**Comments**]: Fixed `COMPOSER_TEXT_CHANGE` event not triggering when content is pasted into the composer.
### New Features
* \[**Comments**]: Renamed `targetElementId` prop to `targetComposerElementId` on `VeltCommentComposer`.
```jsx theme={null}
// Before
```html theme={null}
* \[**Comments**]: Changed `submitComment()` to accept request object instead of plain string. Update calls from `submitComment(targetElementId)` to `submitComment({ targetComposerElementId })`.
```jsx theme={null}
// Before
const commentElement = client.getCommentElement();
commentElement.submitComment('my-composer');
// After
const commentElement = client.getCommentElement();
commentElement.submitComment({ targetComposerElementId: 'my-composer' });
```
```html theme={null}
```
* \[**Comments**]: Added `clearComposer()` method to reset composer state including text, attachments, recordings, tagged users, assignments, and custom lists.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.clearComposer({ targetComposerElementId: 'my-composer' });
```
```html theme={null}
```
* \[**Comments**]: Added `getComposerData()` method to fetch current composer state on-demand. Returns the same data structure as the `COMPOSER_TEXT_CHANGE` event.
```jsx theme={null}
const commentElement = client.getCommentElement();
const composerData = commentElement.getComposerData({
targetComposerElementId: 'my-composer'
});
```
```html theme={null}
```
### Improvements
* \[**Comments**]: Enhanced `composerTextChange` event to include full draft `annotation` object and `targetComposerElementId`. Access attachments, recordings, tagged users, and other composer state in real-time.
```jsx theme={null}
// Using Hooks
import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';
const composerTextChangeEvent = useCommentEventCallback('composerTextChange');
useEffect(() => {
if (composerTextChangeEvent) {
console.log('Text:', composerTextChangeEvent.text);
console.log('Annotation:', composerTextChangeEvent.annotation);
console.log('Composer ID:', composerTextChangeEvent.targetComposerElementId);
}
}, [composerTextChangeEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('composerTextChange').subscribe((event) => {
console.log('composerTextChange event:', event);
});
```
```html theme={null}
```
### New Features
* \[**Comments**]: Added `submitComment()` method to programmatically trigger comment submission. Trigger submission from custom buttons or keyboard shortcuts instead of relying on the built-in submit button.
```jsx theme={null}
// Using Hooks
```html theme={null}
Send
```
* \[**Comments**]: Added `placeholder` prop to comment composer. Customize placeholder text to match your application context.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `composerTextChange` event to track text changes in comment composers. Track input for features like auto-save, character counters, or real-time validation.
```jsx theme={null}
// Using Hooks
import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';
const composerTextChangeEvent = useCommentEventCallback('composerTextChange');
useEffect(() => {
if (composerTextChangeEvent) {
console.log('composerTextChange: ', composerTextChangeEvent);
}
}, [composerTextChangeEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('composerTextChange').subscribe((event) => {
console.log('Text changed:', event.text);
});
```
```html theme={null}
```
### Bug Fixes
* \[**Comments**]: Fixed context issue for manual comment pins. Ensures manual comment pins display correctly across all integrations.
### Bug Fixes
* \[**Self-hosting**]: Fixed attachment metadata issue where `organizationId` was missing. Improves debugging for self-hosted attachment handling.
### Improvements
* \[**Core**]: Improved mutation observer element detection logic to skip animation-related elements. Prevents performance slowdowns caused by continuous animations.
* \[**Comments**]: Optimized read status handling to skip marking already-read comment annotations as read again.
### Bug Fixes
* \[**Comments**]: Fixed bottom sheet not closing properly after deleting a comment annotation.
### New Features
* \[**Self-hosting**]: Added attachment resolver support for config-based endpoints. Configure `saveConfig` and `deleteConfig` URLs for file uploads and deletions. [Learn more](/self-host-data/attachments)
```jsx theme={null}
// Using VeltProvider
'
// Note: Content-Type is automatically set by browser
}
},
deleteConfig: {
url: '/api/attachments/delete',
headers: {
'Content-Type': 'application/json'
}
}
}
}
}}>
{/* Your app content */}
// Using API method
const client = useVeltClient();
client.setDataProviders({
attachment: {
config: {
saveConfig: {
url: '/api/attachments/save',
headers: {
'Authorization': 'Bearer '
}
},
deleteConfig: {
url: '/api/attachments/delete',
headers: {
'Content-Type': 'application/json'
}
}
}
}
});
```
```js theme={null}
Velt.setDataProviders({
attachment: {
config: {
saveConfig: {
url: '/api/attachments/save',
headers: {
'Authorization': 'Bearer '
}
},
deleteConfig: {
url: '/api/attachments/delete',
headers: {
'Content-Type': 'application/json'
}
}
}
}
});
```
**File Upload Format:**
When using `saveConfig`, file uploads use `multipart/form-data`:
```typescript theme={null}
// Request
Method: POST
Content-Type: multipart/form-data (set by browser)
// Form fields:
{
file: File, // Binary file object
request: { // JSON string
"attachment": {
"attachmentId": number,
"name": string,
"mimeType": string
},
"metadata": { ... },
"event": string // Optional
}
}
// Response format:
{
data: {
url: string // URL of uploaded attachment
},
success: true,
statusCode: 200
}
```
**Backward Compatibility:**
* Existing custom `save()` and `delete()` methods continue to work
* If `saveConfig` or `deleteConfig` are not provided, the resolver falls back to provider methods
* No breaking changes to existing implementations
### Bug Fixes
* \[**Notifications**]: Fixed notification loading issue that affected rendering.
* \[**Comments**]: Fixed read status not updating when comment dialog opened in bottom sheet.
### New Features
* \[**CRDT**]: Added [Get CRDT Data](/api-reference/rest-apis/v2/crdt/get-crdt-data) REST API to retrieve editor data. Fetch all editors in a document or target a specific editor by ID. [Learn more](/realtime-collaboration/crdt/setup/core#backend-rest-apis)
* \[**Self-hosting**]: New Config-Based DataProviders: We've reduced self-hosting implementation overhead by **90%**.
* **Frontend**: Simply configure your URLs and headers; the SDK handles the requests automatically.
* **Backend**: Use the new [**Velt Python SDK**](https://pypi.org/project/velt-py) to pass your DB and storage configs. You can now pass the raw request object directly to the SDK methods and return the resulting response object straight to the client—no manual processing required.
```jsx theme={null}
// Using VeltProvider
{/* Your app content */}
// Using API method
const client = useVeltClient();
client.setDataProviders({
reaction: {
config: {
resolveTimeout: 2000,
getConfig: {
url: '/api/reactions/get',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer your-token'
}
},
saveConfig: {
url: '/api/reactions/save'
// headers default to Content-Type: application/json
},
deleteConfig: {
url: '/api/reactions/delete'
}
}
}
});
```
```js theme={null}
Velt.setDataProviders({
comment: {
config: {
resolveTimeout: 20000,
saveRetryConfig: {
retryCount: 3,
retryDelay: 2000
},
getConfig: {
url: '/api/comments/get',
headers: {
'Authorization': 'Bearer your-token'
}
},
saveConfig: {
url: '/api/comments/save',
headers: {
'Authorization': 'Bearer your-token'
}
},
deleteConfig: {
url: '/api/comments/delete',
headers: {
'Authorization': 'Bearer your-token'
}
}
}
// get, save, delete methods are optional when configs are provided
}
});
Velt.setDataProviders({
user: {
config: {
resolveUsersConfig: {
organization: false,
folder: false,
document: true
},
getConfig: {
url: '/api/users/get',
headers: {
'Authorization': 'Bearer your-token'
}
}
}
// get method is optional when getConfig is provided
}
});
```
**Backward Compatibility:**
* Fully backward compatible - existing implementations continue working unchanged
* Custom `get`, `save`, `delete` methods remain supported
* Configs are optional - if not provided, SDK uses provider methods
* User resolver's `get` method supports both old and new response formats
**Notes:**
* All requests use POST method with JSON body
* Response format automatically handled by SDK
* Retry logic (if configured) applies to config-based requests
### Improvements
* \[**Notifications**]: Added dropdown layout option for notification settings. Choose between accordion or dropdown layouts.
```jsx theme={null}
```html theme={null}
**Type:**
```typescript theme={null}
settingsLayout: 'accordion' | 'dropdown' // Default: 'accordion'
```
### Bug Fixes
* \[**Comments**]: Fixed comment dialog not changing read status in bottom sheet. Dialog now updates read status when opened.
### Improvements
* \[**Comments**]: Added `commentPlaceholder`, `replyPlaceholder`, and `composerPlaceholder` props to inline comments section. Customize placeholder text for different input fields.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `commentPlaceholder`, `replyPlaceholder`, and `pageModePlaceholder` props to sidebar. Customize placeholder text for sidebar input fields.
```jsx theme={null}
```html theme={null}
* \[**Core**]: Previous document now set on organization change. When `identify()` is called, the previous document is set unless `setDocuments()` is explicitly called.
### Bug Fixes
* \[**Comments**]: Fixed sidebar opening with previously selected inline comment annotation. Sidebar now opens in fresh state.
* \[**Notifications**]: Fixed notification messages not rendering. Messages now display correctly.
### New Features
* \[**Comments**]: Added `autoCompleteScrollConfig` to customize virtual scroll behavior in autocomplete. Configure scroll parameters like item size and buffer pixels.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `forceClose`, `sortOrder`, `sortBy`, and `defaultMinimalFilter` props to sidebar. Control sidebar behavior and default filtering options.
```jsx theme={null}
```html theme={null}
* \[**Notifications**]: Added `pageSize` prop to control initial notification load count in NotificationPanel and NotificationTool.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Comments**]: Added `elementId` support in `/v2/commentannotations/add` REST API. Pass `elementId` in `targetElement` to define text search boundaries for text comments.
```json theme={null}
{
"data": {
"organizationId": "yourOrganizationId",
"documentId": "yourDocumentId",
"commentAnnotations": [
{
"targetElement": {
"elementId": "yourElementId",
"targetText": "Your Target Text",
"occurrence": 1
},
"commentData": [
{
"commentText": "Sample Comment",
"commentHtml": "Sample Comment
",
"from": {
"userId": "yourUserId",
"name": "yourUserName",
"email": "yourUserEmail"
}
}
]
}
]
}
}
```
* \[**Comments**]: Context data now passed from sidebar and inline views to dialog. Access context in `velt-if` and `velt-data` directives.
* \[**Notifications**]: Truncated long notification text to 3 lines to prevent layout issues.
* \[**Notifications**]: Added `velt-confirm-dialog-overlay-pane` class to confirm dialog overlay for targeted styling.
### Bug Fixes
* \[**Comments**]: Fixed script tag content being included in text search for highlighting. Text comments now ignore script content during search.
* \[**Comments**]: Fixed tooltip visibility in sidebar due to z-index conflict.
* \[**Comments**]: Fixed autocomplete chip height issue. Added `display: block` to prevent scroll issues in thread cards.
* \[**Comments**]: Fixed edit mode not persisting when switching to focused thread mode. Edit state now maintained correctly.
* \[**Notifications**]: Fixed `velt-notifications-panel-settings-wireframe` mapping that was incorrectly configured.
### Improvements
* \[**Access Control**]: Added `context` field in document type during `setNotifications` call in PermissionProvider. Provides additional context data for better debugging.
* \[**CRDT**]: Added CRDT data in Velt Console Data tab. Helps with debugging and reviewing data in the CRDT store for improved developer visibility.
### Improvements
* \[**Access Control**]: Added polyfill for `Promise.allSettled`. Ensures compatibility when external dependencies override native implementations.
* \[**Access Control**]: Fixed response payload for `resourceAccessResultFromCache` in Provider. Now follows the same payload pattern as other methods for better debugging.
### Bug Fixes
* \[**Comments**]: Fixed a minor bug related to adding comments in focused mode.
### New Features
* \[**Comments**]: Added context, locationId, documentId, and folderId props to standalone Composer component. Pass organizational identifiers directly to the composer.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `openAnnotationInFocusMode` config to open comment dialog in focus mode when `focusedThreadMode` is enabled and reply button is clicked or comment is selected via `selectCommentByAnnotationId()`. Requires `focusedThreadMode` to be enabled.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Self-hosting**]: Added `moduleName` to resolver `on()` method for improved debugging. Identifies which module triggered the resolver call.
```typescript theme={null}
export enum UserResolverModuleName {
IDENTIFY = 'identify/authProvider',
GET_TEMPORARY_USERS = 'getTemporaryUsers',
GET_USERS = 'getUsers',
GET_HUDDLE_USERS = 'getHuddleUsers',
GET_SINGLE_EDITOR_USERS = 'getSingleEditorUsers',
}
export enum CommentResolverModuleName {
SET_DOCUMENTS = 'setDocuments',
GET_COMMENT_ANNOTATIONS = 'getCommentAnnotations',
GET_NOTIFICATIONS = 'getNotifications',
}
export enum ReactionResolverModuleName {
SET_DOCUMENTS = 'setDocuments',
GET_REACTION_ANNOTATIONS = 'getReactionAnnotations',
}
```
### Bug Fixes
* \[**Comments**]: Fixed inline comments not marking as read when clicked.
* \[**Comments**]: Fixed focused annotation not clearing when sidebar is closed.
* \[**Notifications**]: Fixed empty state display issue.
### New Features
* \[**Comments**]: Added mark as read/unread option in comment dialog. You can now toggle read status for individual comments. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#optionscontentmarkasread)
* \[**Comments**]: Added `unread` property to annotations. You can now check if an annotation is unread by the current user. See [`CommentAnnotation` data model](/api-reference/sdk/models/data-models#commentannotation).
* \[**Comments**]: Added Open and Reset filters to sidebar minimal filter dropdown. Filter annotations by open status or clear all active filters. [See wireframe customization →](/ui-customization/features/async/comments/comment-sidebar-components#minimalfilterdropdowncontent)
* \[**Comments**]: Added `context` prop to comment sidebar. Pass context data to page mode composer comments.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Comments**]: Added `velt-comment-dialog--read-only` class to comment dialogs. Style read-only comment dialogs with custom CSS.
* \[**Comments**]: Added `velt-comment-sidebar-minimal-filter-content-item--selected` class to selected filter items. Style selected filter items in sidebar minimal view.
* \[**Comments**]: Minimal actions and filter dropdowns now close automatically when an item is selected.
### Bug Fixes
* \[**Comments**]: Fixed sidebar button showing "..." instead of "0" when document has no comments. Unread count now displays correctly.
### New Features
* \[**CRDT**]: Added webhook support for CRDT data changes. Webhooks are disabled by default. When enabled, the default debounce time is 5 seconds. Control webhook behavior using `enableWebhook()`, `disableWebhook()`, and `setWebhookDebounceTime()` methods. [See documentation →](/realtime-collaboration/crdt/setup/core#webhooks)
* \[**CRDT**]: Added `updateData` event subscription to listen for CRDT data changes. Subscribe using the `on()` method to receive real-time notifications when CRDT data is modified. [See documentation →](/realtime-collaboration/crdt/setup/core#on)
```jsx theme={null}
import { useCrdtUtils, useCrdtEventCallback } from "@veltdev/react";
export function YourComponent() {
const crdtUtils = useCrdtUtils();
useEffect(() => {
if (crdtUtils) {
// Enable webhook
crdtUtils.enableWebhook();
// Optional: Change webhook debounce time (minimum 5 seconds)
crdtUtils.setWebhookDebounceTime(10 * 1000); // 10 seconds
}
}, [crdtUtils]);
// Subscribe to updateData event
const crdtUpdateData = useCrdtEventCallback("updateData");
useEffect(() => {
console.log("[CRDT] event on data change: ", crdtUpdateData);
}, [crdtUpdateData]);
return Your Component
;
}
```
```html theme={null}
```
### Improvements
* \[**Access Control**]: Added context information to permission provider requests when `setDocuments` is called. The context set during `setDocuments` is now included in resource access requests.
```jsx theme={null}
// Using API methods
client.setDocuments([{
documentId: 'document1',
context: {
access: {
code: [1, 2]
}
}
}]);
// Permission provider will receive context in request payload
```
```html theme={null}
```
```json theme={null}
{
"event": "resourceAccessRequestFormed",
"methodName": "setDocuments",
"uniqueId": "qaDuR1t4qN35xZ2lHTp0",
"timestamp": 1766506430306,
"source": "internal",
"payload": {
"requests": [
{
"userId": "user123",
"resource": {
"id": "document1",
"type": "document",
"source": "setDocuments",
"organizationId": "org1",
"context": {
"access": {
"code": [1, 2]
}
}
}
},
{
"userId": "user123",
"resource": {
"id": "{\"code\":1}",
"type": "context",
"source": "setDocuments",
"organizationId": "org1",
"context": {
"access": {
"code": 1
}
}
}
},
{
"userId": "user123",
"resource": {
"id": "{\"code\":2}",
"type": "context",
"source": "setDocuments",
"organizationId": "org1",
"context": {
"access": {
"code": 2
}
}
}
}
]
}
}
```
* \[**Access Control**]: Added context access information to `getUserPermissions` API response. Returns `accessFields` array showing which context values the user has access to.
```jsx theme={null}
// Using API methods
const request = {
organizationId: 'org1',
documentIds: ['document1']
};
const response = await client.getUserPermissions(request);
// Response includes context access info at the user level
console.log(response.result.data['user_123'].context.accessFields); // ['code:1', 'code:2', 'code:3']
```
```html theme={null}
```
```json theme={null}
{
"result": {
"status": "success",
"message": "User permissions retrieved successfully.",
"data": {
"user_123": {
"documents": {
"document1": {
"accessRole": "editor"
}
},
"organization": {
"org1": {
"accessRole": "editor"
}
},
"context": {
"accessFields": ["code:1", "code:2", "code:3"]
}
}
}
}
}
```
### Bug Fixes
* \[**Core**]: Fixed document metadata not being saved during `setDocuments`. Metadata details are now correctly persisted to the database.
### Improvements
* \[**Comments**]: Added paginated contact list to limit user downloads. Significantly reduces data transfer for apps with thousands of users.
```jsx theme={null}
// Using Props
```html theme={null}
### New Features
* \[**Live Selection**]: Added `setInactivityTime()` to configure inactivity duration before removing stale live selections. Default is 5 minutes.
```jsx theme={null}
// Using Hooks
import { useLiveSelectionUtils } from '@veltdev/react';
const selectionUtils = useLiveSelectionUtils();
const tenMinutesInMs = 10 * 60 * 1000;
selectionUtils.setInactivityTime(tenMinutesInMs);
// Using API methods
const selectionElement = client.getSelectionElement();
const tenMinutesInMs = 10 * 60 * 1000;
selectionElement.setInactivityTime(tenMinutesInMs);
```
```html theme={null}
```
* \[**Comments**]: Added `commentCountType` prop to control which count displays in sidebar buttons. Choose between total or unread comment counts.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `openDialog` prop to comment bubbles. Set to `false` to prevent dialog from opening when bubble is clicked.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `commentBubbleClickedEvent` to detect comment bubble interactions.
```jsx theme={null}
// Using Hooks
import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';
const commentBubbleClickedEvent = useCommentEventCallback('commentBubbleClicked');
useEffect(() => {
if (commentBubbleClickedEvent) {
console.log('commentBubbleClicked: ', commentBubbleClickedEvent);
}
}, [commentBubbleClickedEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('commentBubbleClicked').subscribe((eventData) => {
console.log('Comment bubble clicked:', eventData);
});
```
```html theme={null}
```
```typescript theme={null}
export interface CommentBubbleClickedEvent {
annotationId: string;
commentAnnotation: CommentAnnotation;
metadata?: VeltEventMetadata;
}
```
* \[**UI Customization**]: Added unread icon wireframes to sidebar buttons and comment bubbles. Display custom unread indicators for unread comments. [See sidebar button wireframes →](/ui-customization/features/async/comments/comment-sidebar-button#unreadicon) [See comment bubble wireframes →](/ui-customization/features/async/comments/comment-bubble#unreadicon)
### New Features
* \[**Core**]: Added `getCurrentUserPermissions` API to subscribe to current user permissions. Useful for debugging and developer tools integration.
```jsx theme={null}
// Subscribe to current user permissions
const subscription = client.getCurrentUserPermissions().subscribe((permissions) => {
console.log('Current user permissions:', permissions);
// permissions structure matches getUserPermissions response format
});
// Unsubscribe when done
subscription.unsubscribe();
```
```html theme={null}
```
### Improvements
* \[**Core**]: Added context access info to `getUserPermissions` and `getCurrentUserPermissions` APIs for enhanced debugging capabilities.
* \[**Core**]: Added context field from `setDocuments` to `fetchDebugInfo` method for improved debugging support.
### Improvements
* \[**Comments**]: Improved robust XPath detection logic when resolving elements through comment anchors. Anchoring now supports more scenarios for detecting target elements when adding comments.
### Bug Fixes
* \[**Comments**]: Fixed shadow DOM error in Comment Player Timeline where a variable was accessing an undefined component instance.
* \[**Comments**]: Fixed `data-velt-comment-pin-active` attribute being incorrectly removed when a dialog was still selected in the host element. The attribute now correctly reflects the active state across all annotations in the host.
* \[**Comments**]: Fixed reset filter in multi-thread comments not showing resolved comments. The reset button now clears all filters and displays all annotations including resolved ones.
### Bug Fixes
* \[**Comments**]: Fixed race condition in `addContext` where user context was being overwritten. Added internal timeout to ensure user context is properly applied alongside the default access context.
### Bug Fixes
* \[**Comments**]: Fixed Comment Bubble closing unexpectedly after adding the first comment. The bubble now remains open as expected.
* \[**Comments**]: Fixed draft comment annotations not being created. Users can now add draft comment annotations again.
### Bug Fixes
* \[**Comments**]: Fixed `contextId` generation in comment annotations. Context filtering now works correctly with exact matches in Comment Tool and Comment Bubble components.
### Improvements
* \[**Core**]: Added batching for internal service calls. Reduces network calls by 90%.
* \[**Comments**]: Refactored `@veltdev/tiptap-velt-comments` and `@veltdev/lexical-velt-comments` to follow a common pattern and folder structure across all libraries. This enables faster development of Velt comment integrations and covers more rich text editor scenarios.
### Improvements
* \[**Comments**]: Added `expandOnSelection` prop to Comments Sidebar. Control whether dialogs expand when selected in the sidebar.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added event subscription support for data providers via the `Velt.on` method. You can now monitor and debug data provider operations (get, save, delete) using the same event-based debugging pattern available for permission providers.
### Bug Fixes
* \[**Comments**]: Added pin click event support for Standalone Comment Pin Component (VeltCommentPin). Click events now work consistently across all pin types.
### Improvements
* \[**Comments**]: Reply counts now display in read-only mode. Previously hidden, you can now see the number of replies on each comment when viewing in read-only state.
* \[**Comments**]: Added `dialogSelection` prop to disable dialog selection in sidebar. Control whether users can select comment dialogs in the sidebar.
```jsx theme={null}
```html theme={null}
* \[**Core**]: Added `throwError` config to `identify()` and auth provider methods. Set `throwError: true` to receive errors instead of null when authentication fails. Default is `false`.
```jsx theme={null}
// Using Hooks
import { useIdentify } from '@veltdev/react';
// Using API methods
// Promise-based
client.identify(user, {
throwError: true,
}).then((user) => {
// user is authenticated
}).catch((err) => {
// handle error
});
// Async/await
try {
const user = await client.identify(user, {
throwError: true,
});
} catch (err) {
// handle error
}
// Using setVeltAuthProvider
client.setVeltAuthProvider({
user,
options: {
throwError: true,
},
onError: (err) => {
// handle error
}
});
```
```html theme={null}
```
* \[**Core**]: Improved `updateContext()` logic to handle context access scenarios. Context resolution now works correctly regardless of merge settings.
### Improvements
* \[**Core**]: Routine package updates.
### Improvements
* \[**Comments**]: Added `commentPinClicked` event to detect pin interactions. You can now capture click events on comment pins to track user engagement.
```jsx theme={null}
// Using Hooks
import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';
const commentPinClickedEvent = useCommentEventCallback('commentPinClicked');
useEffect(() => {
if (commentPinClickedEvent) {
console.log('commentPinClicked: ', commentPinClickedEvent);
}
}, [commentPinClickedEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('commentPinClicked')
.subscribe((eventData) => {
console.log('Comment pin clicked:', eventData);
});
```
```html theme={null}
```
* \[**Comments**]: Added `readOnly` property to Comments Sidebar. Sidebar comment dialogs can now be set to read-only mode to prevent edits.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Fixed tabindex behavior in all comment components. When a component is hidden or empty, tabindex is now removed to prevent focus on invisible elements.
### New Features
* \[**Core**]: Added `getCurrentUser()` method to subscribe to user object changes. You can now detect when the current user's data updates in real-time.
```jsx theme={null}
// Using Hooks
import { useCurrentUser } from '@veltdev/react';
import { useEffect } from 'react';
export function YourComponent() {
const veltUser = useCurrentUser();
useEffect(() => {
console.log("Velt user: ", veltUser);
}, [veltUser]);
}
// Using API methods
client.getCurrentUser().subscribe((veltUser: User | null) => {
console.log("Velt user: ", veltUser);
});
```
```html theme={null}
```
### Improvements
* \[**Comments**]: Added default access context in comments feature. This ensures that all relevant comments are fetched in the query if you are using feature level permissions using access context. [Learn More](https://docs.velt.dev/key-concepts/overview#set-feature-level-permissions-using-access-context-custom-metadata)
### Improvements
* \[**Comments**]: Extended private comments feature to support both admin and organization users.
### Improvements
* \[**REST APIs**]: Added `verifyUserPermissions` flag to [`Add Comment Annotations`](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations), [`Add Comments in Comment Annotation`](/api-reference/rest-apis/v2/comments-feature/comments/add-comments), [`Add Notifications`](/api-reference/rest-apis/v2/notifications/add-notifications), and [`Update Notifications`](/api-reference/rest-apis/v2/notifications/update-notifications) REST APIs. When enabled, these operations are only performed for users who have access to the specified document, preventing unauthorized resource creation or updates.
### Bug Fixes
* \[**Core**]: Added missing types and added automated reviews to prevent this in future.
### Bug Fixes
* \[**Core**]: Fixed an issue preventing fetching all documents within a folder.
### Bug Fixes
* \[**Core**]: Fixed TypeScript types for the Velt `on()` method to display properly in IDE suggestions.
* \[**Core**]: Added validation in `getUserPermissions()` to check if user is set before proceeding, preventing inconsistencies when user is not present.
* \[**Core**]: Added memoization to providers in `VeltProviders` to prevent unnecessary re-renders when input values haven't changed.
* \[**Core**]: Fixed document creation with folder support in the SDK.
### Bug Fixes
* \[**Core**]: Fixed race condition in the `identify()` method that prevented user colors from updating correctly.
* \[**Comments**]: Fixed an issue where text comments data remained stale in case of text editors that could cause data loss when saving annotations.
### New Features
* \[**Core**]: Added `getHeartbeat()` method to subscribe to user-specific heartbeat data. You can retrieve heartbeat data for the current user or specify a `userId` to get heartbeats for any user, providing better visibility into active sessions per user.
```jsx theme={null}
// Using Hooks
import { useHeartbeat } from "@veltdev/react";
import { useEffect } from "react";
const { data: heartbeatData } = useHeartbeat();
useEffect(() => {
console.log("Heartbeat data: ", heartbeatData);
}, [heartbeatData]);
// Using API methods
client.getHeartbeat().subscribe((heartbeatData) => {
console.log("Heartbeat data: ", heartbeatData);
});
```
```html theme={null}
```
**Heartbeat Interfaces:**
```typescript theme={null}
export interface HeartbeatConfig {
userId?: string;
}
export interface GetHeartbeatResponse {
data: Heartbeat[] | null;
}
```
### Improvements
* \[**Comments**]: Added location removal logic when video plays in Timeline Player. Comment pins are now properly removed as the video plays, ensuring accurate timeline visualization.
* \[**Comments**]: Added change detection in Timeline Player. The timeline bar now moves correctly when hovering over the play button or timeline, ensuring responsive playback controls.
### Bug Fixes
* \[**Core**]: Fixed disconnect errors in the heartbeat feature. The SDK now handles network issues at the client side without triggering server disconnect errors.
* \[**Core**]: Fixed user color and text color persistence during auto-login. Colors passed during `identify()` now persist correctly in auto-login scenarios, ensuring consistent user identification.
* \[**Presence**]: Fixed `multipleUsersOnline` event firing when only a single user is present. The presence feature now correctly identifies single-user scenarios, preventing unwanted analytics events.
### Bug Fixes
* \[**Comments**]: Fixed race condition errors in Player Timeline by adding proper lifecycle management. The player timeline now properly handles component destruction, preventing "undefined" errors that could occur when the component was destroyed during asynchronous operations.
* \[**Notifications**]: Fixed error handling for document notifications by adding metadata validation. The SDK now checks if notification metadata exists before processing document notifications, preventing unnecessary errors in analytics tracking when notifications are missing required data.
### Bug Fixes
* \[**Core**]: Fixed user resolution for tagged and assigned users in contact lists. Users added via `updateContactList()` are now properly cached, ensuring that tagged and assigned users resolve correctly from cached data instead of failing to load.
### Bug Fixes
* \[**Core**]: Improved `updateContactList()` method behavior by removing unnecessary validation checks. The method now directly applies user-provided contact list data without additional validation, giving you more control over contact list management.
### Bug Fixes
* \[**Recorder**]: Fixed an issue where zoom was not applied unless the zoom section in the timeline was modified directly.
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the zoom animation in the editor preview had a curve in the transition. The editor preview now displays smooth transitions to the correct coordinates instead of curved transitions.
* \[**Recorder**]: Fixed an issue where VeltIf was throwing an error when evaluating MediaStream object.
* \[**Comments**]: Fixed sanitization of `target` attributes in comment HTML content. The DomPurifier now preserves `target` attributes in comment HTML fields, allowing users to include links with target specifications (such as `target="_blank"`) in their comments.
### Improvements
* \[**Core**]: Optimized the initialization module and significantly reduced the SDK initialization time.
### New Features
* \[**Core**]: Added `fetchDebugInfo()` and `getDebugInfo()` methods to retrieve debugging information about your Velt implementation. Use `fetchDebugInfo()` to get a one-time snapshot or `getDebugInfo()` to subscribe to real-time updates of key setup info like sdk version, apikey, user, organizationId, documentId, folderID version, locations etc. You can also get this info from [Velt’s Chrome devtools](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl)
```jsx theme={null}
// Using API methods - One-time fetch
await client.fetchDebugInfo();
// Using API methods - Subscribe to updates
client.getDebugInfo().subscribe((debugInfo) => {
console.log("Debug info: ", debugInfo);
});
```
```html theme={null}
```
**Debug Info Interface:**
```typescript theme={null}
export interface VeltDebugInfo {
veltVersion?: string;
apiKey?: string;
serverMap?: {
organization?: OrganizationMetadata;
documents?: DocumentMetadata[];
locations?: Location[];
folder?: FolderMetadata;
user?: User;
};
clientMap?: {
organization?: OrganizationMetadata;
documents?: DocumentMetadata[];
locations?: Location[];
folder?: FolderMetadata;
user?: User;
};
}
```
### Improvements
* \[**Access Control**]: Prevent users from adding comments, reactions, recorders, and area comments through the SDK when `access context` is used and the user doesn’t have access to the specific context.
### New Features
* \[**Comments**]: Added preliminary infra required to capture screenshots in comments.
### Improvements
* \[**Access Control**]: Now you can set feature level permissions using Access Context. Access Context allows you to set granular, feature-level permissions using custom metadata. When configured, new feature data is added and existing feature data is fetched only for the access context values the current user has access to. [Learn more →](/key-concepts/overview#set-feature-level-permissions-using-access-context-custom-metadata)
### Improvements
* \[**Recorder**]: Updated video editor timeline picture mode design for improved visual clarity. The unselected portion of timeline pictures now displays with a cleaner design that better distinguishes selected from unselected frames.
* \[**Recorder**]: Fixed audio merging in screen recording to combine microphone and tab audio. When recording with both microphone and tab audio enabled, both audio sources are now properly merged into the final recording.
### Bug Fixes
* \[**Comments**]: Fixed type definition for `selectCommentByAnnotationId()` and made `annotationId` parameter optional.
* \[**Comments**]: Fixed embed mode logic in comments sidebar to support multiple embedded sidebars.
### New Features
* \[**Access Control**]: Added the new Permission Provider feature. With this approach, Velt pings your defined endpoint to verify whether a user should be granted access to a resource (organization, folder, or document). This ensures that your backend is still the source of truth and you don't have to sync the permissions into Velt directly. [Learn more →](/key-concepts/overview#c-real-time-permission-provider)
* \[**Access Control**]: Added a config to automatically revoke permissions, including revoking access to documents, folders, and optionally organizations when users log out or when documents are unset. This ensures immediate permission removal without requiring manual cleanup. [Learn more →](/key-concepts/overview#c-real-time-permission-provider)
* \[**Access Control**]: Added various Permission Provider events to monitor the sequence of permission check events for debugging and tracking purposes. [Learn more →](/api-reference/sdk/models/data-models#permissionproviderevent)
### Improvements
* \[**Access Control**]: Simplified Permission Provider implementation by removing `onResourceAccessRequired` call and signature handling from client SDK. Permission handling is now fully managed internally by the SDK. You no longer need to handle signatures or make `onResourceAccessRequired` calls. The SDK automatically handles permission caching, validation, and synchronization with the backend. [Learn more →](/api-reference/sdk/api/api-methods#setpermissionprovider)
### New Features
* \[**Recorder**]: Added video editor timeline image preview to display frame snapshots in the timeline. This helps you quickly navigate to specific scenes without scrubbing through the entire video.
```jsx theme={null}
```html theme={null}
The timeline preview only works when both `videoEditorTimelinePreview` and `videoEditor` are set to `true`.
### Improvements
* \[**Comments**]: Enhanced `selectCommentByAnnotationId()` to close the selected comment annotation when called with no arguments or an invalid ID.
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');
// Using API methods
const commentElement = client.getCommentElement();
// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');
```
```html theme={null}
```
### New Features
* \[**Access Control**]: Added early version of feature level permissions using Access Context. Access Context allows you to set granular, feature-level permissions using custom metadata. When configured, new feature data is added and existing feature data is fetched only for the access context values the current user has access to. [Learn more →](/key-concepts/overview#set-feature-level-permissions-using-access-context-custom-metadata)
### Improvements
* \[**Access Control**]: Added `source` field to Permission Provider requests to identify which method triggered the request. The `source` field helps you debug and trace which SDK method initiated the permission check. [Learn more →](/key-concepts/overview#c-real-time-permission-provider)
* \[**Access Control**]: Added various Permission Provider events to monitor the sequence of permission check events for debugging and tracking purposes. [Learn more →](/api-reference/sdk/models/data-models#permissionproviderevent)
### Bug Fixes
* \[**Notifications**]: Fixed notification fetching with Permission Provider when document IDs needed mapping to client document IDs.
### New Features
* \[**Comments**]: Added `markAsRead()` and `markAsUnread()` methods to mark comment annotations as read or unread for the current user.
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
commentElement.markAsUnread("eUgq6G6zXxJmOT9eBXtT");
commentElement.markAsRead("eUgq6G6zXxJmOT9eBXtT");
// Using API methods
const commentElement = client.getCommentElement();
commentElement.markAsUnread("eUgq6G6zXxJmOT9eBXtT");
commentElement.markAsRead("eUgq6G6zXxJmOT9eBXtT");
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.markAsUnread("eUgq6G6zXxJmOT9eBXtT");
commentElement.markAsRead("eUgq6G6zXxJmOT9eBXtT");
```
### Improvements
* \[**Recorder**]: Added system sound capture when recording a browser tab.
* \[**Comments**]: You can now tag users by copy-pasting their email address. Previously, only manually typed emails worked for tagging users not on the contact list.
* \[**Comments**]: Added `viewedBy` and `reactionAnnotations` fields to comment annotation objects returned via Get Comment Annotations frontend api methods.
* **`viewedBy`**: An array of User objects representing who has seen and read the comment annotation. Use this to track engagement, identify which stakeholders have reviewed feedback, or build custom read receipt indicators.
* **`reactionAnnotations`**: An array of complete ReactionAnnotation objects containing the full reaction data for each message inside the thread. Use this to render reactions data (eg: reaction counts, show who reacted with what emoji) in your own components.
```typescript theme={null}
// Comment Annotation Object
{
...
comments: [
{
...
reactionAnnotations?: ReactionAnnotation[]; // Complete reaction objects with full details
}
],
viewedBy?: User[]; // Users who have seen and read this annotation
}
```
### Bug Fixes
* \[**Recorder**]: Fixed an issue in the video editor where the playhead position was ignored after playback ended. When seeking or dragging the playhead after video completion, playback now correctly starts from the new position instead of always starting from the beginning.
### Improvements
* \[**Comments**]: Released v2 improved version of comment anchoring that makes comment positioning more dynamic and robust on more dynamic websites. This includes enhanced element detection for pin, text, and area comments, improved cursor display based on DOM element visibility, and better handling of image tag positioning with conditional relative positioning for container elements.
### Bug Fixes
* \[**Comments**]: Fixed an issue where draft comments with resolvers were incorrectly submitted before being finalized, causing data inconsistencies. Draft comments with resolvers now work properly and are only saved when explicitly published.
* \[**Access Control**]: Fixed an issue where organization access permissions were not being set correctly when using the permission provider. When users logged in, their organization-level permissions were failing to initialize properly. Organization access now gets assigned correctly during the identification process.
### New Features
* \[**Notifications**]: Added `triggerNotification` flag to the [Add Comment Annotations REST API](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations). When enabled, adding comments via the REST API will trigger in-app notifications, email notifications to relevant users and also trigger webhooks matching the SDK’s native notification behavior.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where marking all notifications as read in the SDK was not working correctly.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where a notification API was being called twice with the same request.
### Improvements
* \[**Notifications**]: In-app notifications and APIs now only create and retrieve notifications for documents the user has access to; notifications for inaccessible documents will no longer be generated or returned (including historical ones)
* \[**REST APIs**]: Added `verifyUserPermissions` flag to [`Add Notifications`](/api-reference/rest-apis/v2/notifications/add-notifications) and [`Update Notifications`](/api-reference/rest-apis/v2/notifications/update-notifications) REST APIs.
When enabled, notifications are only created or updated for users who have access to the specified document.
Note: If you are using the new `PermissionProvider` then this flag will not work, you will need to do the permissions validation on your end before adding or updating the notification.
### Bug Fixes
* \[**Core**]: Fixed document filtering logic that was incorrectly handling access permissions. Documents are now properly filtered based on user access rights.
### New Features
* \[**Access Control**]: Introduced a new **Permission Provider** approach for simpler, centralized access control. Key details:
* You no longer need to sync users into Velt or call the Permissions API directly.
* Configure an endpoint that Velt will call to verify user access to resources (organization, folder, or document).
* When a user logs in or tries to access a resource:
* Velt sends a request to your configured endpoint with relevant access details.
* Your endpoint evaluates access, signs the result using Velt's API, and returns the response.
* Velt validates the signature and updates access permissions accordingly.
* This creates a single, backend-controlled source of truth for permissions.
* You can use this approach instead of **user sync** and **on-demand** permission strategies.
* [Learn more](/key-concepts/overview#c-real-time-permission-provider).
### Improvements
* \[**Access Control**]: Added `maxDepth` parameter to [`Get Folders` REST API](/api-reference/rest-apis/v2/folders/get-folders). You can now retrieve nested subfolders at any depth level. The response includes `ancestors` array showing parent hierarchy and `inheritAccessFromParent` field indicating whether access is inherited.
* \[**Access Control**]: Added `inheritFromParent` parameter to the [Update Folder Access REST API](/api-reference/rest-apis/v2/folders/update-folder-access). You can now configure a folder to inherit access permissions from its parent folder.
* \[**Access Control**]: The [Update Folder REST API](/api-reference/rest-apis/v2/folders/update-folder) now handles folder moves correctly. When a folder is moved to a different parent, its `ancestors` array and `accessType` are automatically updated, and all subfolder information is updated accordingly.
* \[**Access Control**]: Added `accessType` parameter to the [Add Folder REST API](/api-reference/rest-apis/v2/folders/add-folder). You can now set a folder's access permissions during creation.
* \[**Core**]: The `setDocuments` method now filters out documents the user doesn't have access to instead of failing the entire operation. Previously, if any document in the array was inaccessible, the entire request would fail.
* \[**Access Control**]: Resources (Organizations, Folders, and Documents) follow a hierarchical permission model. By default, **each resource inherits its access type and user permissions** from its parent. If a resource defines its own access type or user permissions, those **explicit settings override the inherited values**. This precedence applies during both **permission evaluation and access enforcement**.
* \[**Access Control**]: Folder document limit set to 50 when using `setDocuments` with the `allDocuments` flag. When fetching all documents from a folder, only the first 50 documents are retrieved, and any documents the user doesn't have access to are filtered out.
### Bug Fixes
* \[**Live State Sync**]: Fixed `getLiveStateData()` so that with `listenToNewChangesOnly: true`, it now returns only new changes after subscribing—instead of including existing data.
### Bug Fixes
* \[**Comments**]: Fixed an issue where tagged users who don't exist in the database were not displaying correctly in email notifications. Comments now render with the proper format in both the UI and emails.
* \[**Comments**]: Fixed an issue where user mentions in email notifications were not resolving with correct user details. Tagged users in comments now display properly with accurate information in all email notifications.
* \[**Comments**]: Fixed an issue where user details were not resolving when a user from a different organization added comments in an accessible document. This previously caused skeleton loading states or fallback formatting for existing organization users, but now displays correctly.
### New Features
* \[**Live State Sync**]: Added `fetchLiveStateData()` method to retrieve synced state data. You can fetch all synced data or retrieve data for a specific `liveStateDataId`.
```jsx theme={null}
// Using Hooks
const liveStateSyncElement = useLiveStateSyncUtils();
/// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();
/// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
liveStateDataId: "LIVE_STATE_DATA_ID"
});
// Using API methods
const liveStateSyncElement = client.getLiveStateSyncElement();
/// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();
/// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
liveStateDataId: "LIVE_STATE_DATA_ID"
});
```
```jsx theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
// To get all the data
const data = await liveStateSyncElement.fetchLiveStateData();
// To get data for specific liveStateDataId
const specificData = await liveStateSyncElement.fetchLiveStateData({
liveStateDataId: "LIVE_STATE_DATA_ID"
});
```
### Bug Fixes
* \[**Live State Sync**]: The useServerConnectionStateChangeHandler hook was sometimes incorrectly reporting an offline state due to the behavior of our special listener in a multi-tab environment. When a browser throttled an idle tab, it would interfere with the shared network activity for this specific listener. This caused the listener in active tabs to momentarily and incorrectly return a false (disconnected) status, even though the primary database connection remained active. We added a 1.5s delay to resolve the network state before emitting the value in the hook.
### Improvements
* \[**Single Editor Mode**]: Improved offline handling for Single Editor Mode controls. When you're offline and attempt to use the "Edit Here" button or accept/reject actions, these operations are now prevented and a console warning is displayed.
* \[**Live State Sync**]: Added timestamp field to Redux action data in Live State Sync. Each action now includes a UTC timestamp for better tracking and debugging.
```json theme={null}
{
"id": "ACTION_ID",
"action": {
"type": "ACTION_TYPE",
"payload": "ACTION_PAYLOAD" // optional
},
"timestamp": 1759745729823 // UTC timestamp in milliseconds
}
```
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the control panel was not visible in thread mode.
### Bug Fixes
* \[**Comments**]: Fixed an issue with manual comment pin selection when working with draft comment annotations.
### Bug Fixes
* \[**Single Editor Mode**]: Fixed an issue related to switching editor access when heartbeat is disabled.
### New Features
* \[**Live State Sync**]: Added heartbeat feature for Single Editor Mode. The heartbeat mechanism provides more reliable presence detection in single editor mode scenarios. This feature is enabled by default when single editor mode is enabled.
If you want to disable heartbeat functionality, you must disable it before enabling single editor mode.
```jsx theme={null}
// Using Hooks
const liveStateSyncElement = useLiveStateSyncUtils();
liveStateSyncElement.enableHeartbeat();
liveStateSyncElement.disableHeartbeat();
// Using API methods
const liveStateSyncElement = client.getLiveStateSyncElement();
liveStateSyncElement.enableHeartbeat();
liveStateSyncElement.disableHeartbeat();
```
```html theme={null}
```
### Bug Fixes
* \[**Comments**]: Fixed an issue where the comment dialog would auto-close after submitting the first comment in popover mode.
### Improvements
* \[**Comments**]: Added option to close persistent comment mode with ESC key, even when a thread is active. Use `forceCloseAllOnEsc` (prop/API).
```jsx theme={null}
// Using props on component
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed an issue where `resolvedCommentsOnDom` was not applying to comment bubbles in the video player timeline.
### New Features
* \[**Comments**]: Added attachments data support in REST API endpoints for adding and updating comments. You can programmatically include attachment metadata when creating or modifying comments through the REST API.
The `attachments` field supports comprehensive metadata including:
* **File identification**: `attachmentId`, `name`, `bucketPath`
* **File properties**: `size`, `type`, `url`, `thumbnail`, `mimeType`
* **Custom metadata**: Flexible metadata object for dimensions, timestamps, and other custom properties
See the full REST API reference:
* [Add Comments API](/api-reference/rest-apis/v2/comments-feature/comments/add-comments)
* [Update Comments API](/api-reference/rest-apis/v2/comments-feature/comments/update-comments)
### Bug Fixes
* \[**UI Customization**]: Fixed an issue where inline comments section filter dropdown wireframe not rendering correctly.
### New Features
* \[**Notifications**]: Added ESC key support to close the notification panel.
* \[**Comments**]: Added unread badge in CommentPlayerTimeline for annotations.
* \[**Recorder**]: Added configuration to control playback behavior on preview click. You can now enable or disable the click-to-play/pause functionality on recording previews.
```jsx theme={null}
// Using props on component
```html theme={null}
* \[**Notifications**]: Added `considerAllNotifications` configuration to the notifications tool to control the notification count and unread indicator. When enabled, the notification count and unread badge include items from all tabs; when disabled (default), they only include items from the “For You” tab.
```jsx theme={null}
```html theme={null}
* \[**Notifications**]: Added ability to filter notifications to the currently set document only. By default it shows notifications for the 15 most recently active documents accessible to the current user in the current organization.
```jsx theme={null}
const notificationElement = client.getNotificationElement();
notificationElement.enableCurrentDocumentOnly();
notificationElement.disableCurrentDocumentOnly();
```
```html theme={null}
```
### Improvements
* \[**Notifications**]: Added ability to hide notification tabs when only one tab is enabled.
* \[**UI Customization**]: Improved CSS variable handling in the ESC button for Persistent Comments Banner.
* \[**UI Customization**]: Removed extra space next to the notification icon.
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the recording edit done event was not triggering with the correct data.
* \[**Recorder**]: Fixed an issue where the countdown timer for the recorder was not working in Firefox.
### New Features
* \[**UI Customization**]: Added hide reply button wireframe for the comment dialog. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#hidereply)
* \[**UI Customization**]: Added thread card reply button wireframe for the comment dialog to enable quick replies directly from comment thread cards. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#threadcardreply)
* \[**UI Customization**]: Added filter dropdown wireframe for the inline comments section. [See wireframe customization →](/ui-customization/features/async/comments/inline-comments-section#filterdropdown-panel)
* \[**Comments**]: Added `allowedFileTypes` property to limit file types in comment attachments.
```jsx theme={null}
// Using props on component
```html theme={null}
* \[**Comments**]: Added ability to display the attachment filename in the message when a file is attached.
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added setComposerFileAttachments() API method to programmatically add file attachments to the comment composer from your application instead of requiring users to select files from the file system.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.setComposerFileAttachments({
files: [file1, file2],
annotationId: 'annotation-123',
targetElementId: 'element-456',
});
```
```html theme={null}
```
### Bug Fixes
* \[**Comments**]: Fixed an issue where floating mode prop was being incorrectly added in React when enabling embed mode in the sidebar.
### New Features
* \[**UI Customization**]: Added comment-level reply button wireframe. This button is hidden by default and can be enabled through wireframe customization.
* \[**UI Customization**]: Added hide reply button wireframes for the comment dialog body.
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the Recorder control panel not being draggable.
* \[**Access Control**]: Fixed an issue where Get User Permissions REST API was not returning `permission_denied` errors in the response
See the full REST API reference: Get Permissions .
### New Features
* \[**Comments**]: Added `readOnly` flag to Comment Bubble component to prevent users from replying or editing existing comments in the target bubble while still displaying them. This is useful when you want to display comments in a read-only mode where users can view but not modify or respond to comments.
```jsx theme={null}
// Using props on component
```html theme={null}
* \[**Comments**]: Added `disabled` flag to Comment Tool component to disable the comment tool and prevent users from adding new comments. This is helpful when you want to temporarily or conditionally restrict comment creation while still allowing users to view existing comments.
```jsx theme={null}
// Using props on component
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed an issue where clicking on one comment bubble would unintentionally open multiple comment bubbles. Now clicking on a comment bubble correctly opens only that specific bubble.
* \[**Comments**]: Fixed an issue where empty comments were being saved in some scenarios.
### Bug Fixes
* \[**Comments**]: Fixed an issue where empty comments were being saved in some scenarios.
* \[**Core**]: Released 4.5.2 stable version.
### Bug Fixes
* \[**Comments**]: Fixed a minor issue with the `fullScreen` prop in the Comments Sidebar.
### New Features
* \[**Comments**]: Added full-screen mode for Comments Sidebar to maximize space for reviewing and managing comments. This is particularly useful when working with large volumes of feedback or conducting detailed comment reviews. By default, this feature is disabled and only supported in default mode (floating and embed modes are not supported).
```jsx theme={null}
// Using props on component
```html theme={null}
* \[**Comments**]: Added fixed annotation numbers to comment pins and dialogs that persist across sessions, making it easier to reference specific comments in discussions and documentation. This replaces the previous temporary numbering system that reset on page refresh.
* \[**Comments**]: Added search by annotation number in Comments Sidebar. You can now quickly find specific comments by typing their annotation number (e.g., `#2`) in the search field, making it faster to locate and navigate to referenced comments.
### UI Customization
* \[**Comments**]: Added new wireframes to customize the appearance of comment annotation numbers and full-screen button in the Comments Sidebar. [See comment dialog wireframes →](/ui-customization/features/async/comments/comment-dialog-components#commentnumber) [See comment pin wireframes →](/ui-customization/features/async/comments/comment-pin#number) [See sidebar wireframes →](/ui-customization/features/async/comments/comment-sidebar-components#fullscreenbutton)
### Bug Fixes
* \[**Recorder**]: Fixed Firefox compatibility issue that was preventing recordings from being stopped properly.
* \[**Notifications**]: Fixed an issue where Notification Panel was not closing if Velt was not initialized.
### Bug Fixes
* \[**Core**]: Fixed invalid user name validation to now accept email values in user names. Also improved URL handling by removing content after the last dot (.) to make URLs non-functional, and increased maximum character limit from 20 to 30.
### Improvements
* \[**Access Control**]: Updated Get User Permissions API to remove `userIds` from the request payload and now returns structured error codes alongside permission denied messages. This provides clearer error handling and makes it easier to diagnose permission issues programmatically.
```ts theme={null}
// Request Payload
interface GetUserPermissionsRequest {
organizationId?: string;
folderIds?: string[];
documentIds?: string[];
}
// Response Payload
interface GetUserPermissionsResponse {
[userId: string]: {
folders?: {
[folderId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
errorCode?: UserPermissionAccessRoleResult;
}
}
organization?: {
[organizationId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
errorCode?: UserPermissionAccessRoleResult;
}
}
documents?: {
[documentId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
errorCode?: UserPermissionAccessRoleResult;
}
}
}
}
enum UserPermissionAccessRoleResult {
DOES_NOT_EXIST = 'does_not_exist',
PERMISSION_DENIED = 'permission_denied',
SOMETHING_WENT_WRONG = 'something_went_wrong',
}
enum UserPermissionAccessRole {
EDITOR = 'editor',
VIEWER = 'viewer',
}
// Using API
await client.getUserPermissions(request as GetUserPermissionsRequest);
```
```ts theme={null}
// Request Payload
interface GetUserPermissionsRequest {
organizationId?: string;
folderIds?: string[];
documentIds?: string[];
}
// Response Payload
interface GetUserPermissionsResponse {
[userId: string]: {
folders?: {
[folderId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
errorCode?: UserPermissionAccessRoleResult;
}
}
organization?: {
[organizationId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
errorCode?: UserPermissionAccessRoleResult;
}
}
documents?: {
[documentId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
errorCode?: UserPermissionAccessRoleResult;
}
}
}
}
enum UserPermissionAccessRoleResult {
DOES_NOT_EXIST = 'does_not_exist',
PERMISSION_DENIED = 'permission_denied',
SOMETHING_WENT_WRONG = 'something_went_wrong',
}
enum UserPermissionAccessRole {
EDITOR = 'editor',
VIEWER = 'viewer',
}
// Using API
await Velt.getUserPermissions(request as GetUserPermissionsRequest);
```
* \[**Access Control**]: Users with Viewer access can no longer add comments or update metadata through the SDK. This ensures proper permission enforcement on Velt features.
### Bug Fixes
* \[**Core**]: Fixed document switch issue where comments were not properly disappearing when navigating between documents, ensuring clean state transitions.
* \[**Core**]: Fixed local cache comment persistence issue that was causing stale comment data to remain after document changes.
### New Features
* \[**Recorder**]: Added maximum recording length feature that allows you to set time limits on recordings. This helps manage storage costs and ensures recordings stay focused and relevant.
```jsx theme={null}
// Using props on components
```html theme={null}
* \[**Recorder**]: Added Picture-in-Picture (PiP) mode for screen recordings when camera is enabled. This allows users to continue recording while multitasking, improving workflow efficiency for tutorial creation and documentation.
Picture-in-Picture is only supported in Chrome browsers and only works for screen recordings when the camera is active. This feature is disabled by default.
```jsx theme={null}
// Enable PiP on components
Custom Pip Button
```
```html theme={null}
Custom Pip Button
```
* \[**Recorder**]: Added screen recording preview to let users see their screen recordings preview prior to staring the recording. This helps users make make necessary adjustments before starting the recording. You programmatically ask users for permissions using the new API.
```jsx theme={null}
// Request screen permission for preview
const recorderElement = client.getRecorderElement();
recorderElement.requestScreenPermission();
// Custom screen player wireframe
```html theme={null}
```
### Bug Fixes
* \[**Single Editor Mode**]: Fixed heartbeat handling issue when external heartbeat is passed to prevent conflicts with internal presence detection mechanisms.
* \[**UI Customization**]: Fixed Angular Material CSS scoping to prevent style conflicts by ensuring Angular Material styles are properly contained within Velt components.
### Bug Fixes
* \[**Single Editor Mode**]: Fixed issue where editor assignment process wasn't reinitiated when a user regained internet connection or became active again after being offline. This ensures proper editor role management in collaborative editing scenarios.
* \[**Single Editor Mode**]: Fixed "Edit here" functionality to properly assign editor role to users even when no existing data is available in the document.
* \[**Core**]: Fixed React hook `setDocumentSuccess` event that wasn't triggering properly by adding flush sync method for `initUpdate` events. This ensures proper event handling and state updates in React applications.
### New Features
* \[**Comments**]: Added `commentPlaceholder` and `replyPlaceholder` props on `VeltComments` so you can tailor input copy to your app’s voice and improve guidance for first-time users.
```jsx theme={null}
// Using Props on VeltComments
```html theme={null}
### Bug Fixes
* \[**Recorder**]: Fixed Recording Preview Dialog width issue.
### New Features
* \[**Access Control**]: Added User Permissions API to fetch a user's `editor`/`viewer` access across organizations, folders, and documents, for both permanent and temporary users. This helps you enforce read-only experiences.
Users with `viewer` access are read-only; write actions like adding comments are blocked in the SDK.
See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
#### REST API
Retrieves user permissions for organizations, folders, and documents in a single API call. Supports both regular and temporary users.
See the full REST API reference: Get Permissions .
#### SDK
```ts theme={null}
// Request Payload
interface GetUserPermissionsRequest {
organizationId?: string;
folderIds?: string[];
documentIds?: string[];
userIds?: string[];
}
// Response Payload
interface GetUserPermissionsResponse {
[userId: string]: {
folders?: {
[folderId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
}
}
organization?: {
[organizationId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
}
}
documents?: {
[documentId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
}
}
}
}
enum UserPermissionAccessRole {
EDITOR = 'editor',
VIEWER = 'viewer',
}
// Using API
await client.getUserPermissions(request as GetUserPermissionsRequest);
```
```ts theme={null}
// Request Payload
interface GetUserPermissionsRequest {
organizationId?: string;
folderIds?: string[];
documentIds?: string[];
userIds?: string[];
}
// Response Payload
interface GetUserPermissionsResponse {
[userId: string]: {
folders?: {
[folderId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
}
}
organization?: {
[organizationId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
}
}
documents?: {
[documentId: string]: {
accessRole?: UserPermissionAccessRole;
expiresAt?: number;
error?: string;
}
}
}
}
enum UserPermissionAccessRole {
EDITOR = 'editor',
VIEWER = 'viewer',
}
// Using API
await Velt.getUserPermissions(request as GetUserPermissionsRequest);
```
### New Features
* \[**Comments**]: Updated default placeholders and added props to customize placeholders for comment and reply inputs. Added wireframes to allow users to customize how it looks. [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#composerinput)
* Default placeholders:
* Comment: "Comment or add others with @"
* Reply: "Reply or add others with @"
* \[**Comments**]: Added hook to set and get UI state.
```jsx theme={null}
const { uiState, setUiState } = useUiState();
useEffect(() => {
console.log('uiState: ', uiState);
}, [uiState]);
setUiState({ a: 1, b: 2 })}>Set Data
setUiState({ a: null, b: null })}>Set Data Null
```
```html theme={null}
```
* \[**Comments**]: Added Edited chip in comment thread: Edits are now visibly transparent at a glance, improving auditability and helping reviewers quickly spot updated messages in long discussions. See [Comment Dialog components](/ui-customization/features/async/comments/comment-dialog-components).
**New wireframes added to customize "Edited" Chip:** [See wireframe customization →](/ui-customization/features/async/comments/comment-dialog-components#threadcardedited)
### Bug Fixes
* \[**Comments**]: In `InlineCommentsSection` single-thread mode, count now reflects the number of Comments vs Comment Annotations.
* \[**Recorder**]: Fixed an issue where longer recordings were not rendering the preview correctly in recording player and editor.
* \[**Recorder**]: Fixed an issue where the host app was not clickable when screen recording was used in floating mode.
### Improvements
* \[**Single Editor Mode**]: Added additional debugging logs for Single Editor Mode.
### Bug Fixes
* \[**UI**]: Scoped `.cdk-overlay-pane` CSS into `.velt-overlay-panel` class to avoid global style leakage.
### New Features
* \[**Comments**]: Added clickable links of text selection in comments and a link callback to handle link clicks programmatically.
```jsx theme={null}
// Link callback in comments
```html theme={null}
* \[**Recorder**]: Added `recorderId` prop to Video Editor.
```jsx theme={null}
// Video Editor
```html theme={null}
* \[**Comments**]: Slack-style link pasting: select text and paste a link to directly convert it into a clickable hyperlink. This speeds up authoring and provides a familiar UX for users.
### Improvements
* \[**Comments**]: Removed translation from group name in sidebar to allow special characters.
### Bug Fixes
* \[**Recorder**]: Fixed `recorderId` change detection in video player.
* \[**Recorder**]: Fixed thread mode UI for screen recordings.
### New Features
* \[**Comments**]: Added group support for custom lists. Useful for workflows like issue trackers (e.g., group by "Priority" or "Status"), allowing users to quickly refer and insert custom entities from your app. With this feature, you can combine multiple entity types into one drop down just like Linear. See full examples in Customize Behavior → [Create custom list data on comment](/async-collaboration/comments/customize-behavior#createcustomlistdataoncomment).
```ts theme={null}
const customListWithGroups = {
hotkey: "$",
type: "custom",
groups: [
{ id: "categories", name: "Categories" },
{ id: "priorities", name: "Priorities" }
],
data: [
// Categories group - 2 items
{
id: "bug_1",
name: "Bug 1",
description: "Bug report 1",
groupId: "categories",
icon: { svg: "
```js theme={null}
const customListWithGroups = {
hotkey: "$",
type: "custom",
groups: [
{ id: "categories", name: "Categories" },
{ id: "priorities", name: "Priorities" }
],
data: [
{ id: "bug_1", name: "Bug 1", description: "Bug report 1", groupId: "categories", icon: { svg: "
### Improvements
* \[**Single Editor Mode**]: Optimized and made Single Editor Mode more robust.
### New Features
* \[**Single Editor Mode**]: Added `updateUserPresence` to send heartbeat data from the host app. This helps Velt detect multi-tab activity and resolve who is the active editor when users switch tabs or devices and will use that as a fallback in rare edge cases if it fails to detect multi‑tab/device presence. Most apps don’t need this; use only if you see ambiguity in who’s the active editor.
```ts theme={null}
export interface LiveStateSingleEditorExternalUserPresence {
/** True if the same user is present on a different tab. */
sameUserPresentOnTab?: boolean;
/** True if a different user is present on a different tab. */
differentUserPresentOnTab?: boolean;
/** User IDs of users present on a different tab. */
userIds?: string[];
}
// API method
const liveStateSyncElement = client.getLiveStateSyncElement();
liveStateSyncElement.updateUserPresence({
sameUserPresentOnTab: false,
differentUserPresentOnTab: true,
userIds: ['user-2']
});
```
```js theme={null}
// API method
const liveStateSyncElement = Velt.getLiveStateSyncElement();
liveStateSyncElement.updateUserPresence({
sameUserPresentOnTab: false,
differentUserPresentOnTab: true,
userIds: ['user-2']
});
```
### Improvements
* \[**Single Editor Mode**]: Added validations in `setUserAsEditor` to set a user only if no editor is currently assigned.
```ts theme={null}
export interface SetUserAsEditorResponse {
error?: ErrorEvent;
}
export type ErrorEvent = {
error?: string;
code: string;
message?: string;
source?: string;
};
// Method signature
// public setUserAsEditor: () => Promise;
// Usage with response handling
const liveStateSyncElement = client.getLiveStateSyncElement();
const result = await liveStateSyncElement.setUserAsEditor();
if (result?.error) {
if (result.error.code === 'same_user_editor_current_tab') {
// Same user is already editor in current tab
} else if (result.error.code === 'same_user_editor_different_tab') {
// Same user is already editor in different tab
} else if (result.error.code === 'another_user_editor') {
// Another user is already editor
}
}
```
```ts theme={null}
// Possible error values
// For same user current tab error
{
code: 'same_user_editor_current_tab',
message: 'Same user is already editor in current tab.',
source: 'setUserAsEditor',
}
// For same user different tab error
{
code: 'same_user_editor_different_tab',
message: 'Same user is already editor in different tab.',
source: 'setUserAsEditor',
}
// For another user error
{
code: 'another_user_editor',
message: 'Another user is already editor.',
source: 'setUserAsEditor',
}
```
```js theme={null}
// Method usage
const liveStateSyncElement = Velt.getLiveStateSyncElement();
const result = await liveStateSyncElement.setUserAsEditor();
if (result && result.error) {
if (result.error.code === 'same_user_editor_current_tab') {
// Same user already editor in current tab
} else if (result.error.code === 'same_user_editor_different_tab') {
// Same user already editor in different tab
} else if (result.error.code === 'another_user_editor') {
// Another user already editor
}
}
```
* \[**Single Editor Mode**]: Optimized and made Single Editor Mode more robust.
### New Features
* \[**Access Control**]: Added support for viewer and editor roles for permanent and temporary users.
**Editor vs Viewer roles**
* **Editor**: Full read/write access to collaboration data on the resource (create/edit/delete comments and replies, add reactions, start recordings, etc.).
* **Viewer**: Read-only access to collaboration data (view comments and replies, presence, cursors, recordings, notifications) without the ability to modify.
Why this matters: You can enforce read-only experiences, safely grant temporary edit windows, and align Velt features with your app’s permission model.
For implementation details, see the v2 Auth APIs:
* Generate Token: [/api-reference/rest-apis/v2/auth/generate-token](/api-reference/rest-apis/v2/auth/generate-token)
* Add Permissions: [/api-reference/rest-apis/v2/auth/add-permissions](/api-reference/rest-apis/v2/auth/add-permissions)
`accessRole` is configurable only via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`.
Relevant endpoints:
* [/api-reference/rest-apis/v2/users/add-users](/api-reference/rest-apis/v2/users/add-users)
* [/api-reference/rest-apis/v2/users/update-users](/api-reference/rest-apis/v2/users/update-users)
* [/api-reference/rest-apis/v2/auth/add-permissions](/api-reference/rest-apis/v2/auth/add-permissions)
* [/api-reference/rest-apis/v2/auth/generate-token](/api-reference/rest-apis/v2/auth/generate-token)
See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance.
### Improvements
* \[**Single Editor Mode**]: Optimized and made Single Editor Mode more robust.
### New Features
* \[**Comments**]: Launched a purpose built library for adding comments to Lexical Editor. [Learn more](/async-collaboration/comments/setup/lexical).
### Improvements
* \[**Comments**]: Optimized how comment read/unread state is updated internally.
### Bug Fixes
* \[**UI Customization**]: Fixed an issue where `Velt Button` was not passing internal state to its children in some scenarios.
### Bug Fixes
* \[**Core**]: Resolved a race condition in resolving user data. Applied the same fix that was added to the `4.5.0-beta.66-patch.1` version.
Note after this update, if you plan to go back to older version of the SDK before `4.5.0-beta.43`, then please reach out to Velt Support for a graceful rollback.
### Bug Fixes
* \[**Core**]: Resolved a race condition in resolving user data.
### Improvements
* \[**Comments**]: Updated comment annotation count subscription. It now supports getting total and unread Comment Annotations count across Organization, Folder, Document and Multiple Documents levels.
```jsx theme={null}
// Organization level
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({ organizationId: 'org1' }).subscribe((data) => {
console.log('getCommentAnnotationsCount with organizationId', data);
});
// Folder level
commentElement.getCommentAnnotationsCount({ organizationId: 'org1', folderId: 'folder2', allDocuments: true }).subscribe((data) => {
console.log('getCommentAnnotationsCount with organizationId and folderId and allDocuments', data);
});
// Document Level
commentElement.getCommentAnnotationsCount().subscribe((data) => {
console.log('getCommentAnnotationsCount', data);
});
// Aggregate Across Multiple Documents
commentElement.getCommentAnnotationsCount({ aggregateDocuments: true }).subscribe((data) => {
console.log('getCommentAnnotationsCount with aggregateDocuments', data);
});
```
```js theme={null}
// Organization level
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({ organizationId: 'org1' }).subscribe((data) => {
console.log('getCommentAnnotationsCount with organizationId', data);
});
// Folder level
commentElement.getCommentAnnotationsCount({ organizationId: 'org1', folderId: 'folder2', allDocuments: true }).subscribe((data) => {
console.log('getCommentAnnotationsCount with organizationId and folderId and allDocuments', data);
});
// Document Level
commentElement.getCommentAnnotationsCount().subscribe((data) => {
console.log('getCommentAnnotationsCount', data);
});
// Aggregate Across Multiple Documents
commentElement.getCommentAnnotationsCount({ aggregateDocuments: true }).subscribe((data) => {
console.log('getCommentAnnotationsCount with aggregateDocuments', data);
});
```
Note after this update, if you plan to go back to older version of the SDK before `4.5.0-beta.43`, then please reach out to Velt Support for a graceful rollback.
### New Features
* \[**Comments**]: Added support to filter out ghost comments when retrieving comment annotations count.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount({ filterGhostComments: true }).subscribe((data) => {
console.log('getCommentAnnotationsCount with filterGhostComments', data);
});
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount({ filterGhostComments: true }).subscribe((data) => {
console.log('getCommentAnnotationsCount with filterGhostComments', data);
});
```
### New Features
* \[**Recorder**]: Added API to programmatically request audio and video permissions from the user.
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.askDevicePermission({
audio: true,
video: true
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.askDevicePermission({
audio: true,
video: true
});
```
### Improvements
* \[**UI Customization**]: Added an alternative approach to evaluate `Velt If` conditions. The default method could be blocked by some strict Content Security Policies (CSP) that disallow `unsafe-eval`.
```javascript theme={null}
client.enableSafeEval();
client.disableSafeEval();
```
```javascript theme={null}
Velt.enableSafeEval();
Velt.disableSafeEval();
```
* \[**Multiplayer Editing**]: Now you can encrypt CRDT data before it’s stored in Velt by registering a custom encryption provider. For CRDT methods, input data is of type `Uint8Array | number[]`. [Learn more](/realtime-collaboration/crdt/setup/core#custom-encryption)
### Improvements
* \[**Comments**]: Added `filterGhostCommentsInSidebar` config in comment sidebar to hide ghost comments from sidebar. Default: `false`
**Using Props:**
```jsx theme={null}
// Use either of the following
**Using Props:**
```html theme={null}
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the `recordingEditDone` event was not firing correctly under certain conditions.
### New Features
* \[**Notifications**]: Added wireframes to modify the title text of the Velt Notification Panel.
* \[**Video Editor**]: Introduced the `VeltVideoEditor`, a new embeddable component for viewing and editing video recordings directly in your application. It can be initialized using a URL, blob, or recorder ID.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Auth**]: When re-authentication occurs after a token expires, `setDocuments` now automatically restores the previous set of documents to maintain session continuity.
### New Features
* \[**Auth**]: Introduced `authProvider` for more robust and flexible authentication management. This includes automatic token refresh with configurable retry logic. [Learn more](/key-concepts/overview#sign-in-a-user).
* \[**Access Control**]: Added a new permissions API to [grant](/api-reference/rest-apis/v2/auth/add-permissions) and [revoke](/api-reference/rest-apis/v2/auth/remove-permissions) user permissions dynamically on demand.
* Grant permissions on demand vs syncing users to Velt.
* Grant temporary time based permissions or permanent permissions to Organizations, Folders and Documents.
* [Learn more](/key-concepts/overview#access-control).
### New Features
* \[**Multiplayer Editing**]: Introduced versioning support for CRDT stores. You can now save snapshots of your collaborative data, list previously saved versions, and restore the store to a specific version. This feature is currently supported for `text` and `array` data types.
### Improvements
* \[**Recorder**]: Expanded recorder functionality with a comprehensive set of lifecycle events, allowing you to build more integrated and responsive recording experiences. The following events are now available:
* `recordingEditDone`: Triggered when the "Done" button is clicked in the recording editor. Fires after edits are saved, or immediately if no edits were made.
* `recordingStarted`: Triggered when the recording starts.
* `recordingPaused`: Triggered when the recording is paused.
* `recordingCancelled`: Triggered when the recording is cancelled.
* `recordingStopped`: Triggered when the recording is stopped.
* `recordingResumed`: Triggered when the recording is resumed after being paused.
### New Features
* \[**Auth**]: Introduced a new streamlined authentication flow to simplify user session management within Velt.
### New Features
* \[**Auth**]: Added support for on-demand access control. Instead of syncing users to Velt, you can now grant permanent or temporary access to resources (organizations, folders, documents) to users on the fly.
* If you pass `organizationId` in the `identify` method and set `requireJwtToken` to `true` (in console), you **must** also include access to the same `organizationId` in the `resources` array of your permissions. Otherwise, it will throw an error.
```ts theme={null}
const authRequest: VeltAuthTokenRequest = {
apiKey: "API_KEY",
userId: "USER_ID",
userProperties: {
isAdmin: false,
name: "USER_NAME",
email: "USER_EMAIL"
},
permissions: {
resources: [
{
type: "organization",
id: "ORGANIZATION_ID"
},
{
type: "document",
id: "DOCUMENT_ID",
organizationId: "ORGANIZATION_ID",
expiresAt: Math.floor(Date.now() / 1000) + 3600 // 1 hour from now
}
]
}
};
try {
const response = await fetch('https://api.velt.dev/v2/auth/generate_token', {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(authRequest),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const responseJson = await response.json();
const token = responseJson?.result?.data?.token;
return token;
} catch (error) {
console.error("Error:", error);
}
```
```ts theme={null}
const token = await __yourBackendEndpointToGenerateToken__();
await client.identify(user, {
authToken: token,
})
```
* \[**Multiplayer Editing (CRDT)**]: Launched Yjs based CRDT libraries for:
* `@veltdev/crdt`: Framework-agnostic CRDT stores (array, map, text, xml), versioning, subscriptions, and syncing via the Velt client.
* `@veltdev/crdt-react`: React Hook wrapper for CRDT integration.
* `@veltdev/tiptap-crdt`: Purpose built CRDT library for Tiptap Editor to enable multiplayer editing.
### Improvements
* \[**REST APIs**]: Added support for `context` field on:
* `Comment` `add` and `update` APIs: Now you can pass `context` field at the comment level.
* `CommentAnnotation` `add` API: Now you can pass `context` field not only at the comment annotation level but also at the comment level.
### Bug Fixes
* \[**Recorder**]: Fixed edge cases in Firefox where devices were not appearing in settings, video sometimes remained off during video recording, and screen recording would not start until the browser was focused.
* \[**Recorder**]: Fixed an issue where the author was incorrectly shown for audio recordings in floating player.
* \[**Notifications**]: Fixed an issue where the Notification Panel and Comments Sidebar would not close if the document was not set.
* \[**Seen By**]: Fixed an issue where the "Seen by" list incorrectly included the author.
### Improvements
* \[**Comments Sidebar**]: Added `sidebarButtonCountType` config to control the count shown on the sidebar button.
* `default`: Shows the total count of comments in open and in progress states.
* `filter`: Shows the count of filtered comments.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### Improvements
* \[**User**]: Avatar colors are now generated consistently across frontend and backend when not set manually.
* \[**Self-hosting**]: Now we are returning author `userId` in comment and reaction resolver APIs for more flexible querying and filtering.
### Improvements
* \[**Core**]: Added internal optimzations for realtime data fetching.
### New Features
* \[**Comments**]: Added "Involved" filter to the comment sidebar to easily find comments where a user is author, mentioned, or assigned.
### Bug Fixes
* \[**Recorder**]: Fixed issues with audio/video capture and permission prompts in Firefox.
### Improvements
* \[**Notifications**]: Added an option to filter notifications based on type in the `getNotificationsData` method.
* Now this method/hook can accept an optional `GetNotificationsDataQuery` object, which supports a `type` property:
* `'all'` (default): returns all notifications from the documents the user has access to.
* `'forYou'`: returns notifications where the current user is involved.
* `'documents'`: returns notifications for documents where the current user has access to.
```jsx theme={null}
const notificationsData = useNotificationsData({ type: 'forYou' });
useEffect(() => {
if (notificationsData) {
console.log(notificationsData);
}
}, [notificationsData]);
```
```js theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.getNotificationsData({ type: 'forYou' }).subscribe((notifications) => {
console.log(notifications);
});
```
### Bug Fixes
* \[**Comments**]: Fixed an issue with aggregated comments dialog, where hitting the reply button would close the dialog.
* \[**Notifications**]: Fixed empty state issue in the notification API where the data would first return an empty array before returning the actual data.
### Bug Fixes
* \[**Comments**]: Fixed an issue with the comment tool in popover mode where the tool would not hide sometimes even when the comment was added.
### Improvements
* \[**Video Editor**]: Added robustness for edge cases with short videos (\< 2-3s) that could cause unexpected behavior in the editor. eg: zooming, trimming, etc.
* \[**Video Editor**]: Added robustness to playhead action buttons group and tooltip display and position logic for edge cases.
### Improvements
* \[**Core**]: Added internal optimzations for realtime data fetching.
### Updates
* \[**Huddle**]: Added `serverFallback` config in huddle. By default Huddle service is peer-to-peer. This will enable or disable the fallback to server-side for connectivity if peer-to-peer fails.
Default: `true`
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Notifications**]: Updated `documentName` rendering logic in the notification panel to only render the component if the `documentName` is available. Earlier it was falling back to the `documentId`.
* \[**Notifications**]: Added support to open and close the notification panel using APIs.
```jsx theme={null}
const notificationElement = useNotificationUtils()
notificationElement.openNotificationsPanel()
notificationElement.closeNotificationsPanel()
```
```html theme={null}
const notificationElement = Velt.getNotificationElement();
notificationElement.openNotificationsPanel();
notificationElement.closeNotificationsPanel();
```
### Bug Fixes
* \[**Comments**]: Fixed an issue where DOM changes detection was not working for text comments in some scenarios.
* \[**Video Editor**]: Hide video editor tooltips and selection during playback.
* \[**Notifications**]: Fixed an issue where notification panel was not closing when clicked on notification tool.
### New Features
* \[**Video Editor**]: Updated video editor with new UI design for improved UX including tooltips, floating action buttons, active/inactive states, etc.
* \[**Video Editor**]: Added a retake button on video editor.
**Using Props (use any one of the following):**
```jsx theme={null}
**Using Attributes (use any one of the following):**
```html theme={null}
* \[**Video Editor**]: Added onboarding tooltip for new users.
**Using APIs:**
```jsx theme={null}
const recorderElement = useRecorderUtils();
// Enable/disable onboarding tooltip
recorderElement.enableOnboardingTooltip();
recorderElement.disableOnboardingTooltip();
```
**Using APIs:**
```jsx theme={null}
const recorderElement = Velt.getRecorderElement();
// Enable/disable onboarding tooltip
recorderElement.enableOnboardingTooltip();
recorderElement.disableOnboardingTooltip();
```
### Improvements
* \[**Core**]: Added central DB for user metadata. Going forward, if user metadata changes via REST API or via identify method, it will be reflected across all data rendered in the UI.
Note after this update, if you plan to go back to older version of the SDK before `4.5.0-beta.43`, then please reach out to Velt Support for a graceful rollback.
### Bug Fixes
* \[**Comments**]: Fixed the issue where context was not applied to freestyle area comments.
### New Features
* \[**Comments**]: Added support to filter and aggregate comment annotations by `locationId` in `InlineCommentsSection`, `VeltCommentPin` and `VeltCommentBubble` components. `folderId` or `documentId` is required.
**Inline Comments Section:**
```jsx theme={null}
// folderId + locationId
**Inline Comments Section:**
```html theme={null}
* \[**Comments**]: Add ability to filter and aggregate comments by mulitple conditions: `folderId`/`documentId`/`locationId` and `context`. Only those comment annotations that satisfy all the conditions will be visible.
**Inline Comments Section:**
```jsx theme={null}
**Inline Comments Section:**
```jsx theme={null}
* \[**Comments**]: Added support to add context to comment tool in freestyle mode.
* \[**Core**]: Added window load event for Velt object after it is initialized. This is useful for developers using pure HTML/JS packages.
```jsx theme={null}
window.addEventListener('onVeltLoad', (event) => {
console.log('onVeltLoad', window.Velt);
});
```
### Bug Fixes
* \[**Comments**]: Fixed issue where bubble count was showing the total comments count instead of the non-terminal state comments count.
* \[**Comments**]: Fixed issue where area comments were not respecting dom id boundaries.
### New Features
* \[**Notifications**]: Added support to enable self notifications. By default notifications api and components exclude notifications where the current user is the action user.
**Using props:**
```jsx theme={null}
**Using attributes:**
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed issue where comment text and HTML content was not being properly stripped during deletion for self-hosted data.
### New Features
* \[**CRDT**]: Added Yjs based CRDT library (\`@veltdev/tiptap-crdt) for Tiptap Editor (in beta).
* This enables live cursors and collaborative editing out of the box.
* This is framework agnostic and can be used with any Tiptap editor.
* [Learn more](/realtime-collaboration/crdt/setup/tiptap)
* \[**Video Editor**]: Added zoom button in video editor with [wireframes support](/ui-customization/features/async/recorder/video-editor#addzoombutton).
* \[**Recorder**]: Added API to turn on/off the microphone on the recorder control panel.
**Using API:**
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.enableRecordingMic(); // Enables the microphone.
recorderElement.disableRecordingMic(); // Disables the microphone.
```
**Using API:**
```jsx theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.enableRecordingMic(); // Enables the microphone.
recorderElement.disableRecordingMic(); // Disables the microphone.
```
### Improvements
* \[**Video Editor**]: Enabled zoom options dropdown to be positioned at the center of the zoom track.
* \[**Comments**]: Enabled standalone comment composer width to be set to 100% of the parent container.
### New Features
* \[**Comments**]: Added reply avatar component with [wireframes support](/ui-customization/features/async/comments/comment-dialog/subcomponents/body/subcomponents/replyavatars). This shows the avatars of unique users who have replied to a comment.
**Using props:**
```jsx theme={null}
**Using props:**
```html theme={null}
* \[**Comments**]: Added template variable `totalReplies` for comment wireframes. It displays the total number of replies for a comment.
### Bug Fixes
* \[**Comments**]: Fixed locationName logic to use locationId in sidebar for 'This Page' filter.
* \[**Comments**]: Fixed "@" dropdown issue where it was not opening after user selection.
### New Features
* \[**Cursors**]: Added wireframes support for `Cursors` component.
### Improvements
* \[**Comments**]: Added sidebar filter dropdown into overlays for better handling of screen and UI edges.
### Bug Fixes
* \[**Comments**]: Fixed an issue where inline comments section width was not being set correctly.
### New Features
* \[**Core**]: Added MCP Servers for:
* **Velt REST APIs**: Allows you to interact with your Velt data directly from various MCP compatible clients, such as Cursor, Windsurf, Claude Desktop, etc. [Learn More](/mcp/mcp).
* **Velt Docs**: Allows you to search and browse Velt's documentation directly within your MCP-compatible IDEs, like Cursor, Windsurf etc. This enables you to quickly find information about our SDKs, APIs, and features without having to leave your editor, streamlining your development workflow when implementing Velt. [Learn More](/mcp/mcp).
### Bug Fixes
* \[**Comments**]: Minor UX fixes:
* Fixed an issue where composer auto-scroll was not working in sidebar embed mode.
* The composer now auto-scrolls to the text cursor when a long message is pasted.
* Mentions are now added at the cursor's position, and the cursor is placed after the mention, not at the end of the input.
### Improvements
* \[**Comments**]: Comment timestamps now show the created timestamp by default, and the last updated timestamp as fallback.
* \[**Core**]: Added improved error messages for identify method so it's easier to debug scenarios like domain mismatch, token expired, organization mismatch, missing token etc.
* \[**Comments**]: Added tooltips to an overlay.
### New Features
* \[**REST APIs**]: Extended v2 endpoints for all APIs. These come with additional schema validation.
* The previous v1 endpoints will work as usual.
### Bug Fixes
* \[**Core**]: Fixed an issue where location metadata, reset etc was not working as expected in some scenarios.
### Bug Fixes
* \[**Comments**]: Minor UX fixes:
* Fixed mention dropdown opening when typing space at the very start of input.
* Fixed mention dropdown opening when @ was added at the end of a word. Exceptions: (`,`, `;`, `:`).
* Updated custom list dropdowns to behave like the default @ dropdown.
* Fixed `ESC` key not closing the mentions dropdown.
* When clicking on collapsed composer, it will bring it into view.
* The composer will auto-scroll to the text cursor when the inputted text is very long.
* Comment dialog will come into view when returning from focused thread mode.
* Fixed an issue where custom filter was getting reset on page refresh.
* Fixed search placeholder type in React `
### New Features
* \[**Debugger**]: Added [Activity Logs](https://console.velt.dev/dashboard/debugger/activity-logs) to the Console.
* Review the historical Velt events stream of your users.
* This can help debug issues, user behaviour on Velt features, etc.
* Currently supports the last 30 days of events.
* There is a 24-48 hour delay in the events being shown in the console.
### Improvements
* \[**Comments**]: Improved autoscroll behavior in comment sidebar for new comment additions, comment dialog clicks, and composer clicks.
* \[**Comments**]: Added `system` type support in `filterConfig` for default filters
### Bug Fixes
* \[**Comments**]: Fixed autocomplete dropdown opening while typing `@` in a word.
* \[**Comments**]: Fixed autocomplete dropdown not closing after `@` followed by immediate space.
* \[**Comments**]: Fixed comment sidebar filter type menu closing on outside clicks.
* \[**Comments**]: Fixed comment sidebar filter search toggle functionality.
### Improvements
* \[**Comments**]: Added support to aggregate and show comment annotations by `folderId`, `documentId` and `context` in `InlineCommentSection`, `VeltCommentPin`, `VeltCommentTool` and `VeltCommentBubble` components.
* All the comment annotations matching these props will be aggregated and shown in the component.
* This will only work when the documents or the relevant folder are initialized first.
**Inline Comments Section:**
```jsx theme={null}
// Filter by folderId
**Inline Comments Section:**
```html theme={null}
### Improvements
* \[**Notifications**]: Modified `getSettings` in notifications from a one-time call to a subscription and added a new hook for it.
**Using Hook:**
```jsx theme={null}
const { setSettingsInitialConfig, setSettings, settings } = useNotificationSettings();
// setSettingsInitialConfig will set the default settings for the notifications.
// setSettings will update the settings for the notifications in the server.
// settings will return the current settings for the notifications. Initially it will be null and will be updated when the settings are fetched.
```
**Using API:**
```jsx theme={null}
const notificationsElement = client.getNotificationElement();
notificationsElement.getSettings().subscribe((settings) => {
console.log('current settings are', settings);
});
```
**Using API:**
```jsx theme={null}
const notificationsElement = Velt.getNotificationElement();
notificationsElement.getSettings().subscribe((settings) => {
console.log('current settings are', settings);
});
```
* \[**Documents**]: Added support for `folderId` in `updateDocuments` method.
```jsx theme={null}
await client.updateDocuments({
organizationId: 'ORGANIZATION_ID',
folderId: 'FOLDER_ID',
documents: [
{
documentId: 'DOCUMENT_ID',
}
]
});
```
```jsx theme={null}
await Velt.updateDocuments({
organizationId: 'ORGANIZATION_ID',
folderId: 'FOLDER_ID',
documents: [
{
documentId: 'DOCUMENT_ID',
}
]
});
```
### Bug Fixes
* \[**UI Customization**]: Fixed an issue where the internal state for User variable was not being cleaned up in Velt If component.
### Improvements
* \[**Comments**]: Added support for multiple text format selection and multiple paragraphs selection in [tiptap-velt-comments](https://www.npmjs.com/package/@veltdev/tiptap-velt-comments).
### Bug Fixes
* \[**Comments**]: Reverted back sidebar filter panel default layout to checkbox from dropdown.
### Improvements
* \[**Comments**]: Added default value for sidebar filter search input.
* \[**Recorder**]: Updated the video editor apply button behavior. Now it will always be enabled whether or not the user edited the video.
* \[**Comments**]: Added ability to add custom filters via `FilterConfig`.
1. First enable custom actions.
2. Add custom filters in filter config.
3. Add [custom filters wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/custom) to the sidebar wireframe.
4. Add callbacks to update sidebar data when the filters are used.
**1. Enable Custom Actions:**
```jsx theme={null}
```
**4. Add callbacks to update sidebar data when the filters are used:**
* The following callbacks will contain the `customFilters` field with the custom filter id and its options indicating which options are selected:
* `commentSidebarDataUpdate`
* `commentSidebarDataInit`
* `veltButtonClick`
```jsx theme={null}
const commentElement = client.getCommentElement();
// Button click callback
client.on('veltButtonClick').subscribe(contextData => {
console.log('veltButtonClick', contextData);
});
// Sidebar data callbacks
commentElement.on('commentSidebarDataUpdate').subscribe((contextData) => {
console.log('commentSidebarDataUpdate', contextData);
});
commentElement.on('commentSidebarDataInit').subscribe((contextData) => {
console.log('commentSidebarDataInit', contextData);
});
```
**1. Enable Custom Actions:**
```html theme={null}
```
**4. Add callbacks to update sidebar data when the filters are used:**
```javascript theme={null}
const commentElement = Velt.getCommentElement();
// Button click callback
client.on('veltButtonClick').subscribe(contextData => {
console.log('veltButtonClick', contextData);
});
// Sidebar data callbacks
commentElement.on('commentSidebarDataUpdate').subscribe((contextData) => {
console.log('commentSidebarDataUpdate', contextData);
});
commentElement.on('commentSidebarDataInit').subscribe((contextData) => {
console.log('commentSidebarDataInit', contextData);
});
```
### Improvements
* \[**Comments**]: Renamed `groupMultipleMatch` config to `groupMatchedComments` config for grouping multiple comment annotations in Comment Bubble component when multiple annotations match the provided `context` or `targetElementId`. The old config is still supported.
* Default: `false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### New Features
* \[**Presence**]: Added wireframes support for `Presence` component.
### Improvements
* \[**Comments**]: Added support for setting custom filter placeholders through `filterConfig`. This is used when `filterOptionLayout` is set to `dropdown`.
```jsx theme={null}
const filterConfig = {
location: {
name: 'Pages',
enable: true,
placeholder: 'Custom Location'
},
document: {
name: 'Documents',
enable: true,
placeholder: 'Custom Document'
}
};
```js theme={null}
const filterConfig = {
location: {
name: 'Pages',
enable: true,
placeholder: 'Custom Location'
},
document: {
name: 'Documents',
enable: true,
placeholder: 'Custom Document'
}
};
const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
commentsSidebar?.setAttribute("filter-config", JSON.stringify(filterConfig));
```
* \[**Comments**]: Added a `filteredCommentAnnotationsCount` template variable for visible comments in sidebar when a filter is applied.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the assign input was not closing when clicked outside in the sidebar.
* \[**Comments**]: Fixed an issue where the reaction panel tool was getting hidden when hovered out.
* \[**Comments**]: Fixed an issue where users set through `updateContactList` were not visible in tagged and assigned filters.
### New Features
* \[**Comments**]: Added support for grouping multiple comment annotations in Comment Bubble component when multiple annotations match the provided `context` or `targetElementId`
* Default: `false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed an issue that happened on sidebar where the recording service got into a bad state when the user cancelled the recording.
### Improvements
* \[**Comments**]: Added support for `filterCommentsOnDom` when custom sidebar filters are configured.
* \[**Comments**]: Added additional testIds in following components:
* Message input (element with class `velt-composer-input--message`)
* Container for author (element with class `velt-thread-card--author`)
* Confirmation dialog (element with class `velt-confirm-dialog`)
* Velt buttons (elements with class `velt-button`)
* \[**Comments**]: Removed quotes from the display message when `notificationSource` is `custom`.
### Improvements
* \[**Core**]: Added `unsetLocationsIds` method to unset locations by passing location IDs as parameters
```jsx theme={null}
client.unsetLocationsIds(['location1', 'location2', 'location3'])
```
### Improvements
* \[**Core**]: Improved SDK initialization layer and added new core methods to improve developer experience:
* Added `rootDocumentId` param in `setDocuments` method to specify which document should act as root. By default 1st document will be set as root document unless `rootDocumentId` is specified.
```jsx theme={null}
client.setDocuments([{id:'doc1'},{id:'doc2'}], {rootDocumentId:'doc2'})
```
* Added `setRootDocument` method to set a different document as root. If user has passed multiple documents and wants to switch the root document:
```jsx theme={null}
client.setRootDocument({id:'doc2'})
// There won't be any change in the other documents internally. They will remain as is.
```
* Added `setLocations` method to add multiple locations:
```jsx theme={null}
client.setLocations([
{id:'location1', locationName:'location1'},
{id:'location2', locationName:'location2'}
], {rootLocationId: 'location2'})
// By default 1st location will be set as root location unless rootLocationId is specified.
// If User wants to append new locations then 'appendLocation' flag needs to be passed.
client.setLocations([
{id:'location3', locationName:'location3'},
{id:'location4', locationName:'location4'}
], {appendLocation: true})
```
* Added `setRootLocation` method to set a different location as root:
```jsx theme={null}
client.setRootLocation({id:'location3', locationName:'location3'})
// There won't be any change in the other locations internally. They will remain as is.
```
* Added `removeLocations` method to remove multiple locations:
```jsx theme={null}
client.removeLocations(
{id:'location3', locationName:'location3'},
{id:'location4', locationName:'location4'}
)
```
* Most init methods now return promises:
* `await setDocuments`
* `await setDocument`
* `await setDocumentId`
* `await setRootDocument`
* `await setLocation`
* `await setLocations`
* `await setRootLocation`
* Added a listener event on `ON` method to subscribe to init changes:
```jsx theme={null}
Velt.on('initUpdate').subscribe((e) => console.log('New init event', e))
```
* Most Analytics events now trigger a common naming pattern:
* `setDocumentsTriggered`
* `setRootDocumentTriggered`
* `unsetDocumentsTriggered`
* `setLocationsTriggered`
* `setRootLocationTriggered`
* `removeLocationsTriggered`
* `setDocumentsSuccess`
* `unsetDocumentsSuccess`
* `setLocationsSuccess`
* `removeLocationsSuccess`
### New Features
* \[**Self-hosting**]: Added support to disable getting user resolver requests for organization, document and folder users. Helps optimize performance by avoiding unnecessary user data requests
* Sometimes you may have a lot of users within your organization, document or folder. In such cases, you may want to disable user resolver requests for organization, document and folder users and instead use [custom autocomplete feature](/async-collaboration/comments/customize-behavior#customautocompletesearch).
* Learn more about [user data provider](/self-host-data/users)
```jsx {19-29} expandable lines theme={null}
const formatUsersToRecord = (users) => {
// Format users array into a Record object with userId as key and user data as value
return users.reduce((record, user) => {
record[user.userId] = {
userId: user.userId,
name: user.name,
// any other fields
};
return record;
}, {});
};
const fetchUsersFromDB = async (userIds) => {
// Fetch users from your DB
const usersData = await __getUsersFromYourDB__(userIds);
return formatUsersToRecord(usersData);
};
const userDataProvider: UserDataProvider = {
get: fetchUsersFromDB,
config: {
resolveUsersConfig: {
organization: false, // Disable organization user requests
folder: false, // Disable folder user requests
document: true // Enable document user requests
}
}
};
```
```js {19-28} expandable lines theme={null}
const formatUsersToRecord = (users) => {
// Format users array into a Record object with userId as key and user data as value
return users.reduce((record, user) => {
record[user.userId] = {
userId: user.userId,
name: user.name,
// any other fields
};
return record;
}, {});
};
const fetchUsersFromDB = async (userIds) => {
// Fetch users from your DB
const usersData = await __getUsersFromYourDB__(userIds);
return formatUsersToRecord(usersData);
};
const userDataProvider = {
get: fetchUsersFromDB,
config: {
resolveUsersConfig: {
organization: false, // Disable organization user requests
folder: false, // Disable folder user requests
document: true // Enable document user requests
}
}
};
Velt.setDataProviders({
user: userDataProvider
});
```
### New Features
* \[**Comments**]: Added custom metadata support for comment tool and comment bubble components.
* Works only with `popover` mode comments. Perfect for complex tables with filtering and segmentation needs.
* Set flexible comment anchoring and filtering logic at the cell level using key-value pairs.
* **Supports aggregate views:** Eg: comments added in day view can appear in week/month views automatically.
* **Two new props:**
* `context`: key-value object for metadata
* `contextOptions`: matching behavior (default: full match, or set `partialMatch: true` for flexible matching)
* **How Partial Match Works:**
* A comment will match if ALL provided filter criteria exist in the comment's context
* Extra fields in the comment's context don't prevent matching
* Missing fields in the comment's context prevent matching
* Example: Comment has `{ day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }`
* Filter `{ day: "01", product: "cheese" }` → ✅ matches (both fields exist in comment)
* Filter `{ day: "01", category: "dairy" }` → ❌ no match (category doesn't exist in comment)
* **Partial Match Examples:**
* Comment has `{ day: "01", week: "01", month: "jan", product: "cheese" }`
* Filter with `{ day: "01", week: "01", month: "jan", product: "cheese" }` → matches (full)
* Filter with `{ week: "01", month: "jan", product: "cheese" }` → matches (partial)
* Filter with `{ day: "01", week: "01", month: "jan", product: "cheese", location: "zurich" }` → no match
```jsx theme={null}
```html theme={null}
### Bug Fixes
* \[**Recorder**]: Fixed an issue where sometimes the recorder service would not update the saved file url after the processing was completed due to a race condition.
### New Features
* \[**Comments**]: Added ability to filter out comments in the DOM when they are filtered in the sidebar.
* When the sidebar is closed (default mode) or unmounted (embed mode), the DOM filter will be removed.
* Default: `false`
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### New Features
* \[**Notifications**]: Added notification settings feature to allow users to configure their notification preferences.
* Enable this feature in the [Velt Console](https://console.velt.dev/dashboard/config/notification).
* Then enable settings on the notifications tool or panel in the UI. [Learn more](/async-collaboration/notifications/customize-behavior#enablesettings)
```jsx theme={null}
// You can enable this on either the tool or the panel
```html theme={null}
* Configure default settings with `setSettingsInitialConfig()` API and extend it to add more channels where you intend to send notifications to your users. [Learn more](/async-collaboration/notifications/customize-behavior#setsettingsinitialconfig)
* Update settings programmatically with `setSettings()` API. [Learn more](/async-collaboration/notifications/customize-behavior#setsettings)
* Get current settings with `getSettings()` API. [Learn more](/async-collaboration/notifications/customize-behavior#getsettings)
* Subscribe to settings updates with `settingsUpdated` event. [Learn more](/async-collaboration/notifications/customize-behavior#on)
* Added wireframe components for notifications panel settings UI. [Learn more](/ui-customization/features/async/notifications/notifications-panel#settings)
* Added Backend APIs to set and get notifications settings. [Learn more](/api-reference/rest-apis/v2/notifications/set-config)
### Improvements
* \[**DevTools**]: Exposed more events and improved the event stream ordering. The latest version is `1.1.6`
* \[**Recorder**]: Added `transcription` field to `RecorderDataAsset`.
```typescript theme={null}
class RecorderDataAsset {
// ...
transcription: RecorderDataTranscription;
// ...
}
```
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the mini player wouldn't play or pause the video on click.
* \[**Recorder**]: Fixed an issue where the mini player was not playing the latest edited version of the video.
* \[**Recorder**]: Fixed the alignment of the play button in the mini player.
* \[**Recorder**]: Fixed the responsive behavior of the expanded player.
* \[**Comments**]: Fixed an issue in composer wireframe where clicking on attachments, recordings, avatar components inside the composer was closing the composer.
### Bug Fixes
* \[**Comments**]: Reopen the resolved thread if someone replies.
### New Features
* \[**Recorder**]: Added a feature to download the latest version of a recording.
* It's available in the UI by default. Wireframe added.
* Added an API method to trigger download programmatically:
```js theme={null}
const recorderElement = client.getRecorderElement();
await recorderElement.downloadLatestVideo('RECORDER_ID');
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
await recorderElement.downloadLatestVideo('RECORDER_ID');
```
### Improvements
* \[**Recorder**]: Changed the background of removed video segments to a diagonal stripe pattern to clearly indicate removal (instead of waveform/thumbnails).
* \[**Recorder**]: Added a center focal point to the zoom selection rectangle for better UX.
* \[**Recorder**]: Added Edit button Wireframe in the recorder player.
### Bug Fixes
* \[**Recorder**]: Implemented several UX fixes for the video editor:
* Maintained correct aspect ratio for the zoom selection rectangle during resizing.
* Ensured the zoom selection rectangle maintains its original position while resizing with aspect ratio locked.
* Ensured video preview displays correct content at responsive widths.
* Prevented the zoom selection rectangle from moving outside the video content area.
* Corrected corner dragging behavior to ensure the zoom selection stays within boundaries.
* Fixed an issue where a small zoom selection at the boundary would go out of bounds when decreasing scale.
* Updated `recorderTime.duration` logic to store precise millisecond values.
* Resolved an issue where dragging the trim/scale handler during video playback affected both operations simultaneously.
* Reduced the drag threshold for improved responsiveness of drag operations.
* \[**Recorder**]: Fixed an issue where playback on the mini video player would not stop when the video player was expanded.
### Bug Fixes
* \[**Comments**]: Fixed an issue where folderId was getting unset when switching between documents too quickly.
### Improvements
* \[**Comments**]: Render default comment sidebar only when it is opened. Note this is not applicable for sidebar in embed mode.
* \[**Comments**]: Added a dynamic class for unread comment annotation in comment pin component: `velt-comment-pin-unread-comment`.
### New Features
* \[**Presence**]: Added event to track changes in user's presence state: `online`, `offline`, `away`.
**Using Hook:**
```jsx theme={null}
const userStateChangeEventData = usePresenceEventCallback('userStateChange');
useEffect(() => {
if (userStateChangeEventData) {
console.log('userStateChange: ', userStateChangeEventData);
}
}, [userStateChangeEventData]);
```
**Using API:**
```ts theme={null}
const presenceElement = client.getPresenceElement();
presenceElement.on("userStateChange").subscribe((data: PresenceUserStateChangeEvent) => {
console.log("userStateChange", data);
});
```
```ts theme={null}
export interface PresenceUserStateChangeEvent {
user: PresenceUser; // Object containing user details
state: string; // New state of the user, e.g., 'online', 'away', 'offline'
};
```
```ts theme={null}
const presenceElement = Velt.getPresenceElement();
presenceElement.on("userStateChange").subscribe((data: PresenceUserStateChangeEvent) => {
console.log("userStateChange", data);
});
```
* \[**Presence**]: Added api and hook to fetch presence data with query filters.
**Using Hook:**
```jsx theme={null}
// Fetch online users
const onlineUsersPresenceData = usePresenceData({ statuses: ['online'] });
useEffect(() => {
if (onlineUsersPresenceData && onlineUsersPresenceData.data) {
console.log('Presence data (online users): ', onlineUsersPresenceData.data);
}
}, [onlineUsersPresenceData]);
// Fetch all users (no query)
const allUsersPresenceData = usePresenceData();
useEffect(() => {
if (allUsersPresenceData && allUsersPresenceData.data) {
console.log('Presence data (all users): ', allUsersPresenceData.data);
}
}, [allUsersPresenceData]);
```
**Using API:**
```ts theme={null}
const presenceElement = client.getPresenceElement();
// Fetch online users
presenceElement.getData({ statuses: ['online'] }).subscribe((response: GetPresenceDataResponse) => {
console.log("Presence data (online users): ", response.data);
});
// Fetch all users (no query)
presenceElement.getData().subscribe((response: GetPresenceDataResponse) => {
console.log("Presence data (all users): ", response.data);
});
```
```ts theme={null}
PresenceRequestQuery {
documentId?: string;
organizationId?: string;
statuses?: string[]; // Filter by statuses, e.g., ['online', 'away', 'offline']
}
GetPresenceDataResponse {
data: PresenceUser[] | null; // Array of PresenceUser objects or null
}
```
```ts theme={null}
const presenceElement = Velt.getPresenceElement();
// Fetch online users
presenceElement.getData({ statuses: ['online'] }).subscribe((response: GetPresenceDataResponse) => {
console.log("Presence data (online users): ", response.data);
});
// Fetch all users (no query)
presenceElement.getData().subscribe((response: GetPresenceDataResponse) => {
console.log("Presence data (all users): ", response.data);
});
```
```ts theme={null}
PresenceRequestQuery {
documentId?: string;
organizationId?: string;
statuses?: string[]; // Filter by statuses, e.g., ['online', 'away', 'offline']
}
GetPresenceDataResponse {
data: PresenceUser[] | null; // Array of PresenceUser objects or null
}
```
* \[**Workspace**]: Added API to add and delete domains to the allowed domains list. [Learn more](/api-reference/rest-apis/v2/workspace/add-domain)
### New Features
* \[**Comments**]: Added a new `Document Filter Dropdown` component to the Comment Sidebar. This feature allows users to filter comments based on documents.
* By default, this filter is disabled. You need to enable it in filter config.
* This works when you are using multiple documents or folders.
```jsx theme={null}
const filterConfig = {
document: {
enable: true,
name: "Documents", // Optional: Customize the display name of the filter
enableGrouping: true, // Optional: Enable grouping of documents
multiSelection: true, // Optional: Allow multiple documents to be selected
}
};
```js theme={null}
const filterConfig = {
document: {
enable: true,
name: "Documents", // Optional: Customize the display name of the filter
enableGrouping: true, // Optional: Enable grouping of documents
multiSelection: true, // Optional: Allow multiple documents to be selected
}
};
const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
commentsSidebar?.setAttribute("filter-config", JSON.stringify(filterConfig));
```
### Improvements
* \[**Comments**]: Added support to add `context` in `Velt Comment Tool` component as well. Previously, context for comments could only be added via event callbacks or APIs. With this update, you can now predefine context directly within the `Velt Comment Tool` component itself. Currently, this feature is specific to popover comments, allowing you to, for example, assign unique context to each cell in a table.
```jsx theme={null}
```html theme={null}
* \[**Recorder**]: Enhanced error handling for the recorder by introducing a new `RecordingErrorEvent` event. It will be triggered when the following errors occur:
* `transcriptionFailed`: When transcription fails.
* `editFailed`: When a video edit operation fails.
* `recordingFailed`: When a recording fails.
```jsx theme={null}
// Hook
const recorderErrorEvent = useRecorderEventCallback('error');
useEffect(() => {
if (recorderErrorEvent) {
if (recorderErrorEvent.type === 'transcriptionFailed') {
console.error('Transcription failed:', recorderErrorEvent);
} else if (recorderErrorEvent.type === 'editFailed') {
console.error('Edit failed:', recorderErrorEvent);
} else if (recorderErrorEvent.type === 'recordingFailed') {
console.error('Recording failed:', recorderErrorEvent);
}
}
}, [recorderErrorEvent]);
// API Method
const recorderElement = client.getRecorderElement();
recorderElement.on('error').subscribe((event) => {
if (event.type === 'transcriptionFailed') {
console.error('Transcription failed:', event);
} else if (event.type === 'editFailed') {
console.error('Edit failed:', event);
} else if (event.type === 'recordingFailed') {
console.error('Recording failed:', event);
}
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.on('error').subscribe((event) => {
if (event.type === 'transcriptionFailed') {
console.error('Transcription failed:', event);
} else if (event.type === 'editFailed') {
console.error('Edit failed:', event);
} else if (event.type === 'recordingFailed') {
console.error('Recording failed:', event);
}
});
```
* \[**Recorder**]: Added `RecordingSaveInitiatedEvent` event. This event is dispatched before the actual save operation begins for original or edited recording.
```jsx theme={null}
// Using the hook
const recordingSaveInitiatedEvent = useRecorderEventCallback('recordingSaveInitiated');
useEffect(() => {
if (recordingSaveInitiatedEvent) {
if (recordingSaveInitiatedEvent.type === 'edit') {
console.log('Edited recording save initiated);
} else {
console.log('New recording save initiated.');
}
}
}, [recordingSaveInitiatedEvent]);
// Using the API method
const recorderElement = client.getRecorderElement();
recorderElement.on('recordingSaveInitiated').subscribe((event) => {
if (event.type === 'edit') {
console.log('Edited recording save initiated');
} else {
console.log('New recording save initiated');
}
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.on('recordingSaveInitiated').subscribe((event) => {
if (event.type === 'edit') {
console.log('Edited recording save initiated');
} else {
console.log('New recording save initiated.');
}
});
```
* \[**Recorder**]: Changed background color for video in the editor to gray when the editor is resized to a smaller size.
* \[**Recorder**]: Video playback now stops upon reaching the end and the player state is reset.
* \[**Recorder**]: Improved type for the legacy `onRecordedData` callback.
### Bug Fixes
* \[**Single Editor Mode**]: Fixed an issue where the editor sometimes lost edit access when opening the document in another tab when additional users were also present in the document.
### Improvements
* \[**Recorder**]: Added wireframes for Timeline and Zoom feature.
### Features
* \[**SDK**]: Added `apiProxyDomain` support, allowing Velt API calls to be proxied through your own domain. [Learn more](/security/proxy-server#proxying-velt-api-calls).
```jsx theme={null}
```jsx theme={null}
const client = await initVelt('YOUR_API_KEY', {
apiProxyDomain: 'https://api.yourdomain.com'
});
```
### Bug Fixes
* \[**Comments**]: Fixed an issue where Thread Card Dropdown Options: Delete Thread and Delete Comment button wireframes text was not updated correctly.
### Improvements
* \[**Recorder**]: Improved the post processing speed for zoom in effect by 90%.
* \[**Recorder**]: Added configuration API to specify [recording quality constraints](/async-collaboration/recorder/customize-behavior#setrecordingqualityconstraints) and [encoding options](/async-collaboration/recorder/customize-behavior#setrecordingencodingoptions). This provides finer control over the video and audio output of recordings.
```jsx theme={null}
const recorderElement = useRecorderUtils();
recorderElement.setRecordingQualityConstraints({
'other': {
'video': {
width: { exact: 3024 },
height: { exact: 1542 },
frameRate: { exact: 20 },
}
}
});
recorderElement.setRecordingEncodingOptions({
'other': {
videoBitsPerSecond: 2000000,
audioBitsPerSecond: 128000
}
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.setRecordingQualityConstraints({
'other': {
'video': {
width: { exact: 3024 },
height: { exact: 1542 },
frameRate: { exact: 20 },
}
}
});
recorderElement.setRecordingEncodingOptions({
'other': {
videoBitsPerSecond: 2000000,
audioBitsPerSecond: 128000
}
});
```
### Bug Fixes
* \[**Recorder**]: Removed loading animation in the apply button which was causing performance issues.
* \[**Recorder**]: Fixed the issue where disabled buttons were still clickable.
### Improvements
* \[**Presence**]: Added ability to configure when user is considered offline after being inactive. Default value: `600000`ms (10 minutes).
```jsx theme={null}
```html theme={null}
* \[**Presence**]: Added `isUserIdle` and `isTabAway` fields in presence user objects.
* When a user navigates away from the current tab, their status will be marked as `away`, and the `isTabAway` field in their presence object will be set to `true`.
* If a user remains inactive (no mouse movement) for a duration defined by `inactivityTime` (default: 5 minutes), their status will be set to `away`, and the `isUserIdle` field in their presence object will be set to `true`.
* \[**Single Editor Mode**]: Added new events for Single Editor Mode, enabling finer-grained tracking of collaborative states and user interactions.
The new events are:
* `accessRequested`: When a user requests editor access.
* `accessRequestCanceled`: When a user cancels their request for editor access.
* `accessAccepted`: When a user's request for editor access is accepted.
* `accessRejected`: When a user's request for editor access is rejected.
* `editorAssigned`: When a user is assigned as the editor.
* `viewerAssigned`: When a user is assigned as a viewer.
* `editorOnDifferentTabDetected`: When the current editor navigates away to a different browser tab or window.
**Using Hooks:**
```jsx theme={null}
// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
const eventData = useLiveStateSyncEventCallback("EVENT_TYPE");
useEffect(() => {
if (eventData) {
console.log("EVENT_TYPE data: ", eventData);
}
}, [eventData]);
```
**Using API:**
```jsx theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
liveStateSyncElement.on("EVENT_TYPE").subscribe((eventData) => {
console.log("EVENT_TYPE data: ", eventData);
});
```
```javascript theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
// Replace "EVENT_TYPE" with an actual event string. eg: "accessRequested".
liveStateSyncElement.on("EVENT_TYPE").subscribe((eventData) => {
console.log("EVENT_TYPE data: ", eventData);
});
```
* \[**Comments**]: The `updateContext` method is now supported even when multiple documents are initialized.
### New Features
* \[**Recorder**]: Added zooming functionality. Users can now add smooth zoom in and out effects on the video scenes. Note: This is in beta and currently the processing time for zoom in effect is quite high. We are working to optimize it.
### Improvements
* \[**Recorder**]: Improved wireframes for video editor elements with mouse events to remove all styles if children are provided in the wireframe. Earlier for these elements, some residual styles were required to be overridden via CSS.
* \[**Recorder**]: Added the `recordingEditDone` event. This event fires the recording edits are done processing and the new recording file is generated.
```jsx theme={null}
const recordingEditDoneEvent = useRecorderEventCallback('recordingEditDone');
useEffect(() => {
if (recordingEditDoneEvent) {
console.log('recordingEditDone: ', recordingEditDoneEvent);
}
}, [recordingEditDoneEvent]);
```
```javascript theme={null}
const recorderelement = Velt.getRecorderElement();
recorderelement.on('recordingEditDone').subscribe((event) => {
console.log('recording edit done:' , event);
});
```
* \[**Recorder**]: Added the `deleteRecordings` API method to delete recordings.
**Using API:**
```ts theme={null}
const recorderelement = client.getRecorderElement();
await recorderelement.deleteRecordings({
recorderIds: ['RECORDER_ID_1']
});
```
```js theme={null}
const recorderelement = Velt.getRecorderElement();
await recorderelement.deleteRecordings({
recorderIds: ['RECORDER_ID_1']
});
```
### Bug Fixes
* \[**Core**]: Release 4.4.0 stable version.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the `velt-comment-sidebar-filter-item--Added` class was not being applied correctly in the people filter.
* \[**Notifications**]: Fixed an issue where `setNotificationAsRead` was not working as expected in some scenarios.
### Bug Fixes
* \[**Live State Sync**]: Fixed an issue where `serverConnectionState` value was not updating correctly in some scenarios.
### Improvements
* \[**Comments**]: Added support to specify whether the system filters (e.g., "me", "this page") should be combined with an "and" or "or" operator. Default is `and`.
**Using Props:**
```tsx theme={null}
```html theme={null}
* \[**Comments**]: Improved filters for comments author in the sidebar.
### Bug Fixes
* \[**SDK**]: Fixed an issue where delete notification REST API was causing some older notifications to be hidden in the frontend component.
### Improvements
* \[**REST APIs**]: Added support for persisting read notifications in "For You" tab through `Update Notifications` REST API. You can pass `persistReadForUsers` param as true.
### Bug Fixes
* \[**SDK**]: Fixed an issue where the `setAllNotificationsAsRead` SDK API method was not working as expected.
### Improvements
* \[**REST APIs**]: Added realtime updates to SDK when notifications are deleted via the REST APIs.
* \[**REST APIs**]: Added support for marking notifications as read through `Update Notifications` REST API.
### Bug Fixes
* \[**Single Editor Mode**]: Fixed accept reject buttons disappearing issue when multiple users request access in single editor mode.
### Improvements
* \[**Live State Sync**]: Improved types in `getLiveStateData`, `setLiveStateData` methods and hooks.
* \[**Comments Sidebar**]: Ensured that "me" and "this page" options are on the top of the comments sidebar filters.
* \[**Notifications**]: Added missing `panelOpenMode` prop to `VeltNotificationsPanel` in React.
```tsx theme={null}
### New Features
* \[**Comments**]: Added ability to attach comment pins to the closest allowed element when clicking on a non-allowed element. Default: `false`
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added ability to enable/disable draft mode in comments. Default: `true`
```jsx theme={null}
```html theme={null}
* \[**Presence**]: Added ability to turn off shadow DOM in Presence component. Default: `true`
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Webhooks**]: Added `assigned: true` in comment added event when someone is assigned to the comment during creation.
* \[**Live State Sync**]: Enhanced Redux middleware with support to dynamically update configuration options:
* `allowedActionTypes`
* `disabledActionTypes`
* `allowAction`
### Bug Fixes
* \[**Core**]: Added additional compatibility for Safari v16 and older versions.
### Improvements
* \[**Recorder**]: Added ability to control whether recorded videos play in full-screen mode.
* You can use this prop on any of the following components:
* `Velt Recorder Notes`
* `Velt Recorder Control Panel`
* `Velt Recorder Player`
* Its turned on by default for Comments feature and off by default for standalone Recorder feature.
```jsx theme={null}
// Change behaviour globally
```html theme={null}
* \[**Recorder**]: Added keyboard shortcuts in video editor for improved editing experience:
* `s`: Split the video at the selected frame.
* `d`, `delete`, or `backspace`: Delete the selected video section.
* `space`: Toggle video play/pause.
* \[**Single Editor Mode**]: Added wireframe for Single Editor Mode Panel.
* \[**Single Editor Mode**]: Added embeddable component for Single Editor Mode Panel.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**UI Customization**]: Added dynamic key support and square bracket notation support in Velt If conditions for more flexible conditional logic.
### Bug Fixes
* \[**Follow Mode**]: Fixed an issue where follow mode was not working as expected.
* \[**Comments**]: Fixed "All" status filter not displaying all comments in sidebar.
### New Features
* \[**UI Customization**]: Added support of adding dynamic id on Velt Button. You can use template variables to set the id.
```jsx theme={null}
```html theme={null}
### Improvements
* \[**Recorder**]: Improved video editor UX for trimming and splitting videos.
* \[**Single Editor Mode**]: Return `undefined` value in `isUserEditor` when there are no current editors available in single editor mode.
* \[**Presence**]: Added `locationId` support in presence component.
```jsx theme={null}
```html theme={null}
### Bug Fixes
* \[**Comments**]: Fixed an issue where comment dialog composer in sidebar was getting autofocused when `fullExpanded` mode was enabled.
### New Features
* \[**UI Customization**]: Added `resetVeltButtonState` method to reset the state of Velt Button components.
```ts theme={null}
// Reset state for a specific button in a given group
client.resetVeltButtonState({id: 'openSidebar', group: 'multi'})
// Reset state for all buttons in a given group
client.resetVeltButtonState({group: 'multi'})
// Reset state for a specific button in all groups
client.resetVeltButtonState({id: 'openSidebar'})
// Reset state for all buttons
client.resetVeltButtonState()
```
### Improvements
* \[**Comments**]: Updated copy and icons for sidebar filter buttons.
* \[**Recorder**]: Made the transition to editor smoother when `autoOpenVideoEditor` is enabled.
* \[**Recorder**]: Improved the control panel embedded settings menu UX.
* \[**Recorder**]: Added keyboard shortcuts for Play, Pause, Split, and Delete actions in video editor.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the dialog might close if the user clicked outside the dialog while a recording was in progress.
### New Features
* \[**Self Hosting**]: Added support for self-hosting file attachments in comments.
### Improvements
* \[**Self Hosting**]: Added retries for GET operations.
* \[**Analytics**]: Exposed additional events to Velt Debugger.
* \[**Live State Sync**]: Added config to choose between merging and replacing live state data.
**Using Hooks:**
```ts theme={null}
const liveStateData = {
'yourKey': 'yourValue'
};
useSetLiveStateData('LIVE_STATE_DATA_KEY',liveStateData, { merge: true });
```
**Using API:**
```ts theme={null}
const liveStateSyncElement = useLiveStateSyncUtils();
const liveStateData = {
'yourKey': 'yourValue'
};
liveStateSyncElement.setLiveStateData('LIVE_STATE_DATA_KEY', liveStateData, {
merge: true
});
```
```ts theme={null}
const liveStateSyncElement = Velt.getLiveStateSyncElement();
const liveStateData = {
'yourKey': 'yourValue'
};
liveStateSyncElement.setLiveStateData('LIVE_STATE_DATA_KEY', liveStateData, {
merge: true
});
```
### Bug Fixes
* \[**Live State Sync**]: Fixed an issue in the Redux Middleware where the middleware was not initializing when Velt Provider was added conditionally.
### Bug Fixes
* \[**Single Editor Mode**]: Fixed an issue where `contenteditable` div's access was not syncing properly when editor state changed.
### Improvements
* \[**Recorder**]: Added missing audio waveform visualization for screen recordings.
* \[**Recorder**]: Made query parameter optional for `fetchRecordings` method.
* \[**Recorder**]: Improved metadata handling to ensure clean object state.
```typescript theme={null}
export class RecorderData {
recorderId!: string;
from?: User | null;
metadata?: RecorderMetadata;
assets: RecorderDataAsset[] = [];
transcription: RecorderDataTranscription = new RecorderDataTranscription();
}
```
### Improvements
* \[**Recorder**]: Added additional props in `Recorder Control Panel` component:
* `settingsEmbedded`: If set to true, the settings will be embedded in the control panel vs a menu. Default is `false`. Please use this together with the Control Panel Wireframes so that you can move the settings panel in a different part of the control panel UI.
* `autoOpenVideoEditor`: If set to true, the video editor will be opened automatically when the recording is done. Default is `false`.
```jsx theme={null}
```html theme={null}
* \[**Recorder**]: Added wireframe for recording preview in recording control panel.
```jsx theme={null}
```html theme={null}
### New Features
* \[**Comments**]: Added `fullExpanded` mode to control the expanded state of comments.
* When enabled, comments will be shown in fully expanded state by default.
* Available on all comment-related components and can be controlled via props or API methods.
Using Props:
```jsx theme={null}
// Apply this change globally to all types of comments
Using Props:
```html theme={null}
### New Features
* \[**Dev Tools**]: Published beta version of Velt Devtools Chrome extension. It allows you to inspect and debug your Velt implementation. If you are interested in trying it out, please reach out to us.
* \[**Console**]: Added support for viewing folders, recordings and notifications data in the console data page.
* \[**Console**]: Added support for additional filters in the console data page: organizationId, folderId, documentId, userId.
* \[**Comments**]: Added support for folder users in `@` mentions dropdown.
* \[**Recorder**]: Added an API to subscribe to all recorder data in the current document.
* Param: `RecorderRequestQuery`, optional, Gets the data for the provided query.
* Returns: `Observable`, Subscription of the recorder data.
**Using Hook:**
```jsx theme={null}
const recordings = useRecordings();
useEffect(() => {
console.log('recordings', recordings);
}, [recordings]);
```
**Using API:**
```js theme={null}
const recorderElement = useRecorderUtils();
recorderElement.getRecordings().subscribe((data) => {
console.log('recordings', data);
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.getRecordings().subscribe((data) => {
console.log('recordings', data);
});
```
* \[**Recorder**]: Extended the `on` event subscription API to include:
* `recordingDone`: Triggered when recording is completed.
* `deleteRecording`: Triggered when a recording is deleted.
**Using Hook:**
```jsx theme={null}
const recordingDoneEvent = useRecorderEventCallback('recordingDone');
const recordingDeleteEvent = useRecorderEventCallback('deleteRecording');
useEffect(() => {
console.log('recordingDoneEvent', recordingDoneEvent);
}, [recordingDoneEvent]);
useEffect(() => {
console.log('recordingDeleteEvent', recordingDeleteEvent);
}, [recordingDeleteEvent]);
```
**Using API:**
```js theme={null}
const recorderElement = useRecorderUtils();
recorderElement.on('recordingDone').subscribe((data) => {
console.log('recordingDone:' , data);
});
recorderElement.on('deleteRecording').subscribe((data) => {
console.log('deleteRecording:' , data);
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.on('deleteRecording').subscribe((data) => {
console.log('deleteRecording:' , data);
});
recorderElement.on('recordingDone').subscribe((data) => {
console.log('recordingDone:' , data);
});
```
### Improvements
* \[**UI**]: Made custom list search case insensitive.
* \[**Recorder**]: Make the video preview responsive in video editor.
* \[**Recorder**]: Improved types for all APIs and Props for the recording feature.
### New Features
* \[**Core**]: Added the following events in `on` method of Velt client:
* `userUpdate`: Triggered when the Velt user is updated.
* `documentInit`: Triggered when the Velt document is initialized.
* `error`: Triggered when an error occurs. Currently this is only triggered for `token_expired` error. In future, this will be extended for other relevant errors.
**Using Hook:**
```jsx theme={null}
const userUpdateEvent = useVeltEventCallback('userUpdate');
const documentInitEvent = useVeltEventCallback('documentInit');
const errorEvent = useVeltEventCallback('error');
useEffect(() => {
console.log('userUpdate', userUpdateEvent);
}, [userUpdateEvent]);
useEffect(() => {
console.log('documentInit', documentInitEvent);
}, [documentInitEvent]);
useEffect(() => {
// for token expired, error.code = 'token_expired'
console.log('error', errorEvent);
}, [errorEvent]);
```
**Using API:**
```js theme={null}
client.on('userUpdate').subscribe((user) => {
console.log('userUpdate', user);
});
client.on('documentInit').subscribe((documentInit) => {
console.log('documentInit', documentInit);
});
client.on('error').subscribe((error) => {
// for token expired, error.code = 'token_expired'
console.log('error', error);
});
```
```js theme={null}
Velt.on('userUpdate').subscribe((user) => {
console.log('userUpdate', user);
});
Velt.on('documentInit').subscribe((documentInit) => {
console.log('documentInit', documentInit);
});
Velt.on('error').subscribe((error) => {
// for token expired, error.code = 'token_expired'
console.log('error', error);
});
```
* \[**Recorder**]: Added ability to enable/disable video editor via props on `Velt Recorder Player` and `Velt Recorder Control Panel` components. You could use any of these.
```jsx theme={null}
```
```html theme={null}
* \[**Recorder**]: Added `recordingCountdown` and `recordingTranscription` props on `Velt Recorder Notes` and `Velt Recorder Control Panel` components.
```jsx theme={null}
```html theme={null}
* \[**Recorder**]: Added video editor wireframes.
### Improvements
* \[**Core**]: Improved types for data resolvers.
* \[**Recorder**]: Removed drag functionality from recording control panel and player.
* \[**Recorder**]: If a `null` value is set for `recorder Id` prop in `Velt Recorder Player` component, a warning will be thrown.
### Bug Fixes
* \[**Comments**]: Added a check to prevent an error in @mentions dropdown if the user group has no users and the `expandMentionGroups` config is set to true.
### New Features
* \[**Comments**]: Added support for new filters in `fetchCommentAnnotations` method:
* `resolvedBy`: `string`, Filter comments by user who resolved the comment
* `userIds`: `string[]`, Filter comments by comment annotation author
* `mentionedUserIds`: `string[]`, Filter comments if the provided users are tagged in the comment
* \[**Contacts**]: Added API and Hook to get the list of users added to organization, document, user groups or the ones overwritten using the `updateContactList` API.
```jsx theme={null}
export interface UserGroup {
groupId!: string;
groupName!: string;
users?: User[];
}
export interface GetContactListResponse {
organizationUsers?: User[];
folderUsers?: User[];
documentUsers?: User[];
userGroups?: UserGroup[];
updatedContactList?: User[];
}
// React Hook
const contactList = useContactList();
console.log(contactList); // initial value will be null
// API method
const contactElement = client.getContactElement();
contactElement.getContactList().subscribe((response) => {
console.log(response); // initial value will be null
});
```
```js theme={null}
export interface UserGroup {
groupId!: string;
groupName!: string;
users?: User[];
}
export interface GetContactListResponse {
organizationUsers?: User[];
folderUsers?: User[];
documentUsers?: User[];
userGroups?: UserGroup[];
updatedContactList?: User[];
}
// API method
const contactElement = Velt.getContactElement();
contactElement.getContactList().subscribe((response) => {
console.log(response); // initial value will be null
});
```
### New Features
* \[**Comments**]: Added a config to show expanded user groups inside the @mentions dropdown menu.
* Added [new wireframes](/ui-customization/features/async/comments/comment-dialog/subcomponents/autocomplete-group-option) to customize the display of user groups.
* Here are some props to control the display of user groups:
* `expandMentionGroups`: Whether to expand the user groups and show individual users inside the groups in the @mentions dropdown menu.
* `showMentionGroupsFirst`: Whether to show the user groups in the @mentions dropdown menu before the non-group users.
* `showMentionGroupsOnly`: Whether to show only the user groups in the @mentions dropdown menu and not the non-group users.
```jsx theme={null}
```html theme={null}
* \[**Comments Sidebar**]: Added two new default system filters and their wireframes to the sidebar:
* `Tagged`: Filter comments by specifying the user who was tagged in the comment. ([Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/tagged))
* `Assigned`: Filter comments by specifying the user who was assigned to the comment. ([Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/assigned))
```typescript theme={null}
class CommentSidebarFilterConfig {
// ... existing properties ...
tagged?: FilterTypeConfig;
assigned?: FilterTypeConfig;
// ... existing properties ...
}
```
* \[**Comments Sidebar**]: Added another UI pattern for filters options: searchable dropdown with checklist. ([Example Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/tagged))
```jsx theme={null}
```html theme={null}
* \[**Comments Sidebar**]: Added a reset filter button. ([Wireframe](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/reset-button))
* \[**Comments Sidebar**]: Added prop to disable count calculation for sidebar filter options.
```jsx theme={null}
```
```html theme={null}
### Improvements
* \[**Comments**]: Updated `getCommentAnnotations()` method to now [query](/api-reference/sdk/models/data-models#commentrequestquery) and subscribe to comments data even if its not the currently set document.
* \[**Comments**]: Improved comment dialog positioning on text comments when the text is at the bottom edge of the page.
* \[**Notifications**]: Added support in `getNotificationsData()` for retrieving custom notifications created with `notifyAll: false`.
* \[**REST API**]: Improved the performance of [GDPR Delete API](/api-reference/rest-apis/v2/gdpr/delete-all-user-data-gdpr) and made it 90%+ faster and more efficient.
### Bug Fixes
* \[**Comments**]: Fixed an issue with SlateJS comments where comment was not being added when the text was selected from right to left.
### Improvements
* \[**Recorder**]: Optimized the video recording performance: 50% smaller files with 90% faster uploads!
### Improvements
* \[**Core**]: Upgraded several dependency packages to new versions.
### Improvements
* \[**REST API**]: Added support to get all user data for GDPR requests. [Learn more](/api-reference/rest-apis/v2/gdpr/get-all-user-data-gdpr).
### Improvements
* \[**Localization**]: Added additional null checks for provided localization strings.
* \[**REST API**]: Added support for special characters (`_`, `-`) while creating custom notifications.
### New Features
* \[**Localization**]: Added support for localization for all static strings visible in the SDK Components.
* You can get the complete list of strings that can be localized [here](https://firebasestorage.googleapis.com/v0/b/snippyly.appspot.com/o/external%2Flocalization-strings-map.json?alt=media\&token=0cdd2b52-10ed-4033-a08a-5c2b622ce7df).
```jsx theme={null}
// Provide the localization object for the languages you want to support.
client.setTranslations({
'en': {
'All comments': 'All comments',
},
'fr': {
'All comments': 'Tous les commentaires',
},
// Add more languages as needed.
});
// Set one of the languages you've provided the translations for.
client.setLanguage('en');
```
```js theme={null}
// Provide the localization object for the languages you want to support.
Velt.setTranslations({
'en': {
'All comments': 'All comments',
},
'fr': {
'All comments': 'Tous les commentaires',
},
// Add more languages as needed.
});
// Set one of the languages you've provided the translations for.
Velt.setLanguage('en');
```
* \[**Comments**]: Added support for `.txt` file attachments in Comments.
### New Features
* \[**Comments, Notifications**]: Added a first-party [extension](https://www.npmjs.com/package/@veltdev/slate-velt-comments) for [SlateJS](https://www.slatejs.org/) to allow comments and notifications on text content.
### Bug Fixes
* \[**UI Customization**]: Fixed an issue where empty wireframes for repeated components were not being rendered in some scenarios.
### Improvements
* \[**Comments**]: Changed default value of `pin-highlighter` to false for better initial experience.
* \[**REST API**]: Added `deleteAll` parameter to [`/v1/organizations/usergroups/users/delete`](/api-reference/rest-apis/v2/user-groups/delete-users-from-group) remove all users from a group.
* \[**REST API**]: Added `metadata` field on the returned comment annotation objects. It will contain documentId, organizationId, folderId, etc.
### Improvements
* \[**Recorder**]: Improved the video editor to be smoother and enabled "select and delete" feature.
* \[**Recorder**]: Added support for audio waveform visualization in video recordings.
* \[**Recorder**]: Reduced the size of the video recordings by 50%.
### New Features
* \[**Reactions**]: Added support for self hosting reactions data.
### Improvements
* \[**Core**]: Improved signature of User Resolver (used for self hosting user PII) for better consistency with backward compatibility.
* \[**Core**]: Extended data resolvers with an option to configure retries and optimized operation order to prioritize client-side execution. Learn more [here](/api-reference/sdk/models/data-models#resolverconfig).
* \[**REST API**]: Added support for updating users in existing comment annotations via REST APIs. Learn more [here](/api-reference/rest-apis/v2/comments-feature/comment-annotations/update-comment-annotations#param-update-users).
### Improvements
* \[**Core**]: Added support for automatic folder creation from the frontend when folders don't exist. New documents without existing data are now automatically added to the currently set folder.
* \[**REST API**]: Added support for user mentions via REST APIs. Learn more [here](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations).
### Bug Fixes
* \[**Comments**]: Fixed an issue where deleting inline comments in multi-document scenarios wasn't always updating the UI state.
### New Features
* \[**Core**]: Added `updateLocations` method to update location(s) metadata. Previously this could only be done via REST APIs.
```js theme={null}
client.updateLocations({
organizationId: 'org1',
documentIds: ['doc1', 'doc2'],
locations: [{
id: 'location1',
locationName: 'MyLocation'
}]
})
export interface UpdateLocationsRequest {
organizationId?: string;
documentIds?: string[];
locations?: UpdateLocationMetadata[];
}
export interface UpdateLocationMetadata {
id: string;
[key: string]: T | string;
}
```
### Improvements
* \[**Core**]: Improved types for `updateDocuments` method.
```js theme={null}
client.updateDocuments({
organizationId: 'org1',
documents: [{
documentId: 'doc1',
documentName: 'MyDoc'
}]
})
export interface UpdateDocumentsRequest {
organizationId?: string;
documents?: UpdateDocumentMetadata[];
}
export interface UpdateDocumentMetadata {
documentId: string;
[key: string]: T | string;
}
```
* \[**Core**]: Added support for location persistence by after debounced document updates.
* \[**Core**]: Show the most updated location metadata in features like sidebar and notifications even if the features have stale data.
* \[**Core**]: `client.getMetadata()` method now provides most updated information about organization, folders documents and locations for debugging purposes.
* \[**Core**]: Added logs for get API methods like `fetchCommentAnnotations` if it's called without an authenticated user.
* \[**Core**]: SDK state and location are preserved after auto-relogin when browser extensions clear indexedDb during idle periods of >1hr.
* \[**Core**]: Enhanced `disableLogs` method with more granular control:
* `disableLogs()`: turns off only warnings
* `disableLogs({suppressAll: true})`: turns off all logs
* `disableLogs({warning: false, suppressAll: true})`: Keeps the warning logs but turns off all other logs
### Improvements
* \[**Core**]: Auto-relogin user in rare scenarios where after an hour of idle time indexedDb is cleared by browser extensions.
### New Features
* \[**Comments**]: Added `svgAsImg` configuration in comments to treat SVGs as images instead layered elements. Default is `false`.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### Improvements
* \[**Comments**]: Added `data-velt-comment-dialog-comments-priority` attribute in comment dialog if a comment priority is set. This can be used to style comments differently based on their priority.
* \[**Notifications**]: Changed min height to 300px in Notification panel.
* \[**Comments**]: Added ability to apply filters via API before mounting the Sidebar (in embed mode).
### Improvements
* \[**Comments**]: Now, if both inline and popover comments are used, clicking on a comment in the inline comments section will not activate comment bubble.
* \[**Comments**]: Added additional classes to inline comments section's container divs to allow for more precise custom styling.
* \[**Core**]: Added configuration options to aggressively suppress error messages especially on Safari related to index db and network errors.
```js theme={null}
client.disableLogs({suppressAll:true})
```
### Bug Fixes
* \[**Comments**]: Added missing type for `placeholder` field in `createCustomListDataOnAnnotation` in React.
* \[**Comments**]: Fixed minor bugs with Custom Lists wireframes.
### Improvements
* \[**Notifications**]: Added minimum height to notification panel to prevent layout shift when there is just one notification.
* \[**Notifications**]: Removed default styling from notifications tool when Wireframe is used.
* \[**Comments**]: Added active state support in Tiptap comments mark tags.
### Bug Fixes
* \[**Comments**]: Fixed an issue with `onCommentAdd` event that was not triggered once the comments component was unmounted and remounted during the session.
### New Features
* \[**Debugging**]: Added events for `unsetDocuments` and `unsetLocations`.
* \[**Comments**]: Added type for `fetchCommentAnnotations` in `CommentElement` for React.
* \[**Documents**]: Added `updateDocuments` method to update document(s) metadata.
```js theme={null}
client.updateDocuments({
organizationId: 'org1',
documents: [
{
documentId: 'document-id',
documentName: 'document-name'
},
{
documentId: 'document-id-2',
documentName: 'document-name-2'
}
]
});
export interface UpdateDocumentsRequest {
organizationId?: string;
documents?: {documentId: string; [key: string]: any}[];
}
```
* \[**Debugging**]: Added `folderId` property in `Velt.getMetadata()` response.
### Improvements
* \[**Notifications**]: Improved the notification tool component to prevent layout shift when notification count was updated.
### Bug Fixes
* \[**Comments**]: Added missing type definition for Sidebar Filter Config in React to include status property.
### Improvements
* \[**Comments**]: Improved type names for comment resolver.
```ts theme={null}
// Data models
export interface VeltDataProvider {
comment?: CommentAnnotationDataProvider;
user?: UserDataProvider;
}
export interface CommentAnnotationDataProvider {
get: (request: GetCommentResolverRequest) => Promise>;
save: (request: SaveCommentResolverRequest) => Promise;
delete: (request: DeleteCommentResolverRequest) => Promise;
resolveTimeout?: number; // optional. In milliseconds. Expected timeout to get a response from your API.
}
export interface GetCommentResolverRequest {
organizationId: string;
commentAnnotationIds?: string[];
documentIds?: string[];
folderId?: string;
allDocuments?: boolean;
}
export interface SaveCommentResolverRequest {
commentAnnotation: { [key: string]: PartialCommentAnnotation };
}
export interface PartialComment {
commentId: string | number;
commentHtml?: string;
commentText?: string;
}
export interface PartialCommentAnnotation {
annotationId: string;
metadata?: VeltMetadata;
comments: {
[commentId: string]: PartialComment;
};
}
```
### New Features
* \[**Recorder**]: Added Video Editing feature allowing users to edit recorded videos.
**Using Props:**
```jsx theme={null}
**Using Props:**
```html theme={null}
### Improvements
* \[**Recorder**]: Improved Recorder player UX.
### New Features
* \[**Comments**]: Comments Self Hosting now available. Store and retrieve comment and notification text on your own backend while using Velt's UI components.
* Combined with existing user PII self hosting, you can now store all sensitive data on your infrastructure.
* Support for self-hosted attachments and recordings coming soon.
```jsx theme={null}
// Define your comment data provider
const commentDataProvider = {
get: async (request) => {
const result = await getDataFromYourServer(request);
// Ensure the result is in the required format
return result;
},
save: async (request) => {
const result = await saveDataOnYourServer(request);
return result;
},
delete: async (request) => {
await deleteDataFromYourServer(request.commentAnnotationId);
},
};
// Set the data provider
{/* Your app content */}
```
**Request Objects:**
```js theme={null}
// GET Request:
{
organizationId: string;
commentAnnotationIds?: string[];
documentIds?: string[];
folderId?: string;
allDocuments?: boolean;
}
// Save Request:
{
commentAnnotation: { [key: string]: IStrippedCommentAnnotation };
}
// IStrippedCommentAnnotation:
{
annotationId: string;
metadata?: any;
comments: {
[commentId: string]: StrippedComment;
};
}
// StrippedComment:
{
commentId: string | number;
commentHtml?: string;
commentText?: string;
}
// Delete Request:
{
commentAnnotationId: string;
metadata?: any;
}
```
```js theme={null}
// Define your comment data provider
const commentDataProvider = {
get: async (request) => {
const result = await getDataFromYourServer(request);
// Ensure the result is in the required format
return result;
},
save: async (request) => {
const result = await saveDataOnYourServer(request);
return result;
},
delete: async (request) => {
await deleteDataFromYourServer(request.commentAnnotationId);
},
};
// Set the data provider
client.setDataProviders({
comment: commentDataProvider,
});
```
**Request Objects:**
```js theme={null}
// GET Request:
{
organizationId: string;
commentAnnotationIds?: string[];
documentIds?: string[];
folderId?: string;
allDocuments?: boolean;
}
// Save Request:
{
commentAnnotation: { [key: string]: IStrippedCommentAnnotation };
}
// IStrippedCommentAnnotation:
{
annotationId: string;
metadata?: any;
comments: {
[commentId: string]: StrippedComment;
};
}
// StrippedComment:
{
commentId: string | number;
commentHtml?: string;
commentText?: string;
}
// Delete Request:
{
commentAnnotationId: string;
metadata?: any;
}
```
### Improvements
* \[**Comments**]: Added mobile support for inline comment section, improving the user experience on smaller screens.
* \[**Debugging**]: Now `client.getMetadata()` method only returns the currently set documents instead of all documents used in the current session.
### New Features
* \[**Comments**]: Tiptap comments marks are now persisted automatically by default. This simplifies implementation as you no longer need to store marks yourself or modify your editor's content handling.
* \[**Comments**]: Added Sorting Dropdown Wireframe support for inline comments section. [Learn more](/ui-customization/features/async/comments/inline-comments-section/subcomponents/panel/sorting-dropdown)
### Improvements
* \[**Comments**]: Made the freestyle comment pins adapt to DOM elements with complex layouts.
* \[**Comments**]: Improved loading skeleton in inline comments section to match comment card width and adapt responsively to smaller widths.
* \[**Comments**]: Improved the alignment of the assign to dropdown in inline comments section when the width of the section is large.
* \[**Comments**]: Added dark mode styling for the new sorting dropdown in inline comments section.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the comment bubble was not keeping the dialog open when a fresh annotation was added.
### New Features
* \[**Comments**]: Added a default sorting UI component in the inline comments section. This was one of the most requested features.
* \[**Comments**]: Added config to prevent deleting the entire thread when the first comment is deleted.
```jsx theme={null}
```js theme={null}
### Improvements
* \[**Comments**]: Improved the overall UI/UX of the inline comments section based on user feedback, including: loading state, inner padding, layout shift etc.
### Bug Fixes
* \[**Comments**]: Fixed an issue where inline comments sorting was not working when the prop was changed dynamically.
* \[**Comments**]: Fixed issue in single-threaded mode where delete thread label now correctly appears on the root comment regardless of sorting order.
### New Features
* \[**Core**]: Added ability to enable or disable Velt's logs/warnings in Browser Console.
```jsx theme={null}
client.enableLogs();
client.disableLogs();
```
```js theme={null}
Velt.enableLogs();
Velt.disableLogs();
```
### Improvements
* \[**Core**]: Added performance improvements for scenarios where the user accesses and switches between large number of documents at a high frequency.
### Improvements
* \[**Recorder**]: Improved [`TranscriptionDoneEvent`](/api-reference/sdk/models/data-models#transcriptiondoneevent) object.
* \[**Comments**]: Fixed `useSetDocuments` hook to properly support `setDocuments` method in dependency array in React `useEffect`:
```jsx theme={null}
const { setDocuments } = useSetDocuments();
useEffect(() => {
setDocuments(yourDocuments);
}, [setDocuments]);
```
* \[**Comments**]: Made small UI improvements:
* Removed 0 from Velt bubble count.
* Fixed Velt bubble wireframe layout shift issue.
### Bug Fixes
* \[**Comments**]: Fixed small UI issues:
* Fixed an issue where draft comments were showing up when reaction was updated.
* Fixed an issue where selecting a comment in inline comment section was also opening the Velt Comment bubble.
* Fixed an issue where focused thread mode scroll was not working as expected.
### Bug Fixes
* \[**Comments**]: Fixed an issue where the SeenBy dropdown wasn't opening on the first click.
* \[**Comments**]: Fixed an issue where clicking @mention button was not opening the mention dropdown. Typing @ was working as expected.
* \[**Comments**]: Fixed a re-rendering issue when adding reactions.
### New Features
* \[**Core**]: Added `getUser` method to get the current user.
```jsx theme={null}
const user = client.getUser();
console.log(user);
```
```js theme={null}
const user = Velt.getUser();
console.log(user);
```
* \[**UI Customization**]: Simplified how UI can be customized using wireframes.
* Conditional Component Rendering: Conditionally render any component directly without needing to specify parent or sibling wireframes.
* Conditional CSS Classes: Classes can now be conditionally applied to components based on the data in the component.
* Wireframe CSS Classes Support: CSS Classes added to wireframes components are automatically applied to the related rendered components.
**Conditional Component Rendering:**
```jsx theme={null}
// Old
// New
**Conditional Component Rendering:**
```html theme={null}
```
**Conditional CSS Classes:**
```jsx theme={null}
```
**Wireframe CSS Classes Support:**
```html theme={null}
```
* \[**UI Customization**]: Set and render custom state data into Velt components. This data is available in all Velt Wireframes, Velt If and Velt Data components.
```jsx theme={null}
// Setter
client.setUiState({
dashboardName: 'MRR Growth',
anyKey: 'anyValue'
});
// Getter
client.getUiState().subscribe((data) => {
console.log('UI State: ', data);
});
// Use it in Velt Wireframe
```
```js theme={null}
// Setter
Velt.setUiState({
dashboardName: 'MRR Growth',
anyKey: 'anyValue'
});
// Getter
Velt.getUiState().subscribe((data) => {
console.log('UI State: ', data);
});
// Use it in Velt Wireframe
```
* \[**Comments**]: Added support for custom autocomplete search for contact list or [custom lists](/async-collaboration/comments/customize-behavior#createcustomlistdataoncomment). You should use this if you have a large dataset that you want to plug into the autocomplete dropdown, and search directly your own data source.
**Enable the feature:**
```jsx theme={null}
// Enable via props
**Enable the feature:**
```js theme={null}
// Enable via attribute
* \[**Comments**]: Added `composerClicked` event to detect when comment composer is clicked.
```jsx theme={null}
const composerClickEvent = useCommentEventCallback('composerClicked');
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.on('composerClicked').subscribe((data) => {
console.log('Composer clicked', data);
});
```
### Bug Fixes
* \[**Comments**]: Fixed assign comment input double border CSS issue.
### New Features
* \[**Folders**]: Introducing Folders! Organize documents hierarchically with granular access control. Modeled after Google Drive's folder structure.
* Folders can contain documents and other folders.
* Uses same permission model as Organizations and Documents.
* APIs:
* **Frontend**: Subscribe to folders and query by folderId.
* **Backend**: CRUD operations for folders and access control. [Learn More](/api-reference/rest-apis/v2/folders/add-folder)
* Added folder support to existing relevant APIs.
* \[**Folders**]: API to subscribe to a particular folder and all its documents at the same time.
**Using Hooks:**
```jsx theme={null}
const { setDocuments } = useSetDocuments();
{/* Subscribe to a folder and all its documents */}
const rootDocument = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
}
];
setDocuments(
rootDocument,
{
folderId: 'folder1',
allDocuments: true
}
);
{/* Subscribe to a folder and some documents */}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
setDocuments(
documents,
{
folderId: 'folder1',
}
);
```
**Using API:**
```jsx theme={null}
{/* Subscribe to a folder and all its documents */}
client.setDocuments(
rootDocument,
{
folderId: 'folder1',
allDocuments: true
}
);
{/* Subscribe to a folder and some documents */}
client.setDocuments(
documents,
{
folderId: 'folder1',
}
);
```
```js theme={null}
// Subscribe to a folder and all its documents
const rootDocument = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
}
];
Velt.setDocuments(
rootDocument,
{
folderId: 'folder1',
allDocuments: true
}
);
// Subscribe to a folder and some documents
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
Velt.setDocuments(
documents,
{
folderId: 'folder1',
}
);
```
* \[**Folders**]: Added an API to fetch folder metadata and subfolders by organizationId, folderId with pagination.
```jsx theme={null}
// Get all folders for a specific organization
client.fetchFolders({
organizationId: 'org1'
});
// Get a specific folder's metadata with its immediate subfolders
client.fetchFolders({
organizationId: 'org1',
folderId: 'folder1'
});
interface FetchFoldersRequest {
organizationId?: string;
folderId?: string;
}
interface FetchFoldersResponse {
data: Record | null;
nextPageToken: string;
}
```
```js theme={null}
// Get all folders for a specific organization
Velt.fetchFolders({
organizationId: 'org1'
});
// Get a specific folder's metadata with its immediate subfolders
Velt.fetchFolders({
organizationId: 'org1',
folderId: 'folder1'
});
interface FetchFoldersRequest {
organizationId?: string;
folderId?: string;
}
interface FetchFoldersResponse {
data: Record | null;
nextPageToken: string;
}
```
* \[**Documents**]: Added an API to fetch document metadata by organizationId, folderId or documentIds with pagination.
```jsx theme={null}
// Get all documents for a specific folder
client.fetchDocuments({
organizationId: 'org1',
folderId: 'folder1',
allDocuments: true
});
// Get specific documents by IDs
client.fetchDocuments({
organizationId: 'org1',
documentIds: ['doc1', 'doc2']
});
interface FetchDocumentsRequest {
organizationId?: string;
documentIds?: string[];
folderId?: string;
allDocuments?: boolean;
}
interface FetchDocumentsResponse {
data: Record | null;
nextPageToken: string;
}
```
```js theme={null}
// Get all documents for a specific folder
Velt.fetchDocuments({
organizationId: 'org1',
folderId: 'folder1',
allDocuments: true
});
// Get specific documents by IDs
Velt.fetchDocuments({
docElement.fetchDocuments({
organizationId: 'org1',
documentIds: ['doc1', 'doc2']
});
interface FetchDocumentsRequest {
organizationId?: string;
documentIds?: string[];
folderId?: string;
allDocuments?: boolean;
}
interface FetchDocumentsResponse {
data: Record | null;
nextPageToken: string;
}
```
* \[**Comments**]: Added a new API to fetch comment annotations by organizationId, folderId or documentIds with pagination and filtering options. This is different from the existing subscription API which susbcribes to realtime changes to the comments data.
```jsx theme={null}
// Get all annotations for a specific folder
const commentElement = client.getCommentElement();
commentElement.fetchCommentAnnotations({
organizationId: 'org1',
folderId: 'folder1',
allDocuments: true
});
// Get annotations for specific documents
const commentElement = client.getCommentElement();
commentElement.fetchCommentAnnotations({
organizationId: 'org1',
documentIds: ['doc1', 'doc2']
});
interface FetchCommentAnnotationsRequest {
createdAfter?: number;
createdBefore?: number;
updatedAfter?: number;
updatedBefore?: number;
statusIds?: string[];
order?: 'asc' | 'desc';
pageToken?: string;
allDocuments?: boolean;
pageSize?: number;
organizationId?: string;
locationId?: string;
documentIds?: string[];
folderId?: string;
}
interface FetchCommentAnnotationsResponse {
data: Record | null;
nextPageToken: string;
}
```
```js theme={null}
// Get all annotations for a specific folder
const commentElement = Velt.getCommentElement();
commentElement.fetchCommentAnnotations({
organizationId: 'org1',
folderId: 'folder1',
allDocuments: true
});
// Get annotations for specific documents
const commentElement = Velt.getCommentElement();
commentElement.fetchCommentAnnotations({
organizationId: 'org1',
documentIds: ['doc1', 'doc2']
});
interface FetchCommentAnnotationsRequest {
createdAfter?: number;
createdBefore?: number;
updatedAfter?: number;
updatedBefore?: number;
statusIds?: string[];
order?: 'asc' | 'desc';
pageToken?: string;
allDocuments?: boolean;
pageSize?: number;
organizationId?: string;
locationId?: string;
documentIds?: string[];
folderId?: string;
}
interface FetchCommentAnnotationsResponse {
data: Record | null;
nextPageToken: string;
}
```
### Features
* \[**Self-hosting**] You can now self-host your user PII metadata.
* Send only userId instead of full user object and a client side data provider.
* Components will automatically fetch the user details from the provider and hydrate the user object.
* The metadata will not be sent to Velt servers.
```jsx theme={null}
const fetchUsersFromDB = async (userIds) => {
// Fetch users from your DB
const usersData = await getUsersFromYourDB(userIds);
return formatUsersToRecord(usersData);
};
const formatUsersToRecord = (users) => {
// Format users array into a Record object with userId as key and user data as value
return users.reduce((record, user) => {
record[user.userId] = {
userId: user.userId,
name: user.name,
// any other fields
};
return record;
}, {});
};
```
```js theme={null}
Velt.setUserDataProvider({
getUsers: fetchUsersFromDB
});
function fetchUsersFromDB(userIds) {
// Fetch users from your DB
const usersData = getUsersFromYourDB(userIds);
return formatUsersToRecord(usersData);
}
function formatUsersToRecord(users) {
// Format users array into a Record object with userId as key and user data as value
return users.reduce((record, user) => {
record[user.userId] = {
userId: user.userId,
name: user.name,
// any other fields
};
return record;
}, {});
}
```
### Improvements
* \[**Core**]: Added core performance improvements throughout the SDK.
* \[**Recorder**]: Added new API methods to get the recorded data.
```jsx theme={null}
const recorderElement = client.getRecorderElement();
await recorderElement.getRecordingData({
recorderIds: ['RECORDER_ID']
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
await recorderElement.getRecordingData({
recorderIds: ['RECORDER_ID']
});
```
* \[**Recorder**] Added missing props to disable shadow DOM for recorder components in React SDK.
```jsx theme={null}
### Bug Fixes
* \[**Recorder**]: Fixed Safari recording compatibility issues across some macOS versions.
### Features
* \[**Core**]: Added support for React v19 in `sdk-react` library.
### Improvements
* \[**Authentication**]: Made `organizationId` mandatory in `identify` method.
* \[**New Accounts**]: New accounts or API keys will have advanced queries turned on by default.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where notifications were not working when organizationId was not set.
* \[**REST API**]: Fixed an issue where the REST API for adding or updating organizations and documents did not allow custom fields in metadata.
### Improvements
* \[**Comments**]: Improved comments performance with optimistic local-first reads and writes.
* \[**Notifications**]: Added `documentMetadata` object in the properties that are sent to SendGrid for emails.
### Bug Fixes
* \[**Comments**]: Fixed an issue where custom metadata added to a comment using `addContext` was not sent to the first notification event (`newlyAdded`).
### Features
* \[**Comments**]: Added a `transcriptionDone` event callback when recording transcription is done.
**Using Hooks:**
```jsx theme={null}
const onTranscriptionDone = useRecorderEventCallback('transcriptionDone');
useEffect(() => {
console.log(onTranscriptionDone);
}, [onTranscriptionDone])
```
**Using API:**
```jsx theme={null}
const recorderElement = client.getRecorderElement();
recorderElement.on('transcriptionDone').subscribe((data) => {
console.log('transcriptionDone', data);
});
```
**Using API:**
```js theme={null}
const recorderElement = Velt.getRecorderElement();
recorderElement.on('transcriptionDone').subscribe((data) => {
console.log('transcriptionDone', data);
});
```
### Improvements
* \[**Comments**]: Disabled @here in the contacts dropdown by default. You can turn it on using [this](/async-collaboration/comments/customize-behavior#enableathere).
### Bug Fixes
* \[**Comments**]: Removed virtual scroll from autocomplete panel and removed fixed height. This was causing weird UI issues. We are rewriting the autocomplete panel with virtual scroll.
* \[**Comments**]: Fixed an issue where horizontal scroll was visible on sidebar in some scenarios.
* \[**Comments**]: Fixed an issue where the `shadowDom` prop was not passed down to page mode composer in comment sidebar.
* \[**Comments**]: Fixed an issue where `sortData` prop was not working in comments sidebar.
### Bug Fixes
* \[**Comments**]: Fixed an issue where comments was not working for fresh documents if the advanced queries option wasn't enabled. Note this is mandatory for all versions of v4 SDK.
* \[**Comments**]: Fixed an issue where [updateContactList](/async-collaboration/comments/customize-behavior#updatecontactlist) was not working.
* \[**Comments**]: Fixed an issue where in inline comments, the resolve button was visible for all messages in a thread.
### Features
* \[**Self-hosting**] You can now self-host your user PII metadata.
* Send only userId instead of full user object and a client side data provider.
* Components will automatically fetch the user details from the provider and hydrate the user object.
* The metadata will not be sent to Velt servers.
```jsx theme={null}
const fetchUsersFromDB = async (userIds) => {
// Fetch users from your DB
const usersData = await getUsersFromYourDB(userIds);
return formatUsersToRecord(usersData);
};
const formatUsersToRecord = (users) => {
// Format users array into a Record object with userId as key and user data as value
return users.reduce((record, user) => {
record[user.userId] = {
userId: user.userId,
name: user.name,
// any other fields
};
return record;
}, {});
};
```
```js theme={null}
Velt.setUserDataProvider({
getUsers: fetchUsersFromDB
});
function fetchUsersFromDB(userIds) {
// Fetch users from your DB
const usersData = getUsersFromYourDB(userIds);
return formatUsersToRecord(usersData);
}
function formatUsersToRecord(users) {
// Format users array into a Record object with userId as key and user data as value
return users.reduce((record, user) => {
record[user.userId] = {
userId: user.userId,
name: user.name,
// any other fields
};
return record;
}, {});
}
```
### Improvements
* \[**Core**]: Added core performance improvements throughout the SDK.
* \[**Recorder**]: Added new API methods to get the recorded data.
```jsx theme={null}
const recorderElement = client.getRecorderElement();
await recorderElement.getRecordingData({
recorderIds: ['RECORDER_ID']
});
```
```js theme={null}
const recorderElement = Velt.getRecorderElement();
await recorderElement.getRecordingData({
recorderIds: ['RECORDER_ID']
});
```
* \[**Recorder**] Added missing props to disable shadow DOM for recorder components in React SDK.
```jsx theme={null}
### Bug Fixes
* \[**Recorder**]: Fixed Safari recording compatibility issues across some macOS versions.
### Features
* \[**Core**]: Added support for React v19 in `sdk-react` library.
### Improvements
* \[**Authentication**]: Made `organizationId` mandatory in `identify` method.
* \[**New Accounts**]: New accounts or API keys will have advanced queries turned on by default.
### Bug Fixes
* \[**Notifications**]: Fixed an issue where notifications were not working when organizationId was not set.
* \[**REST API**]: Fixed an issue where the REST API for adding or updating organizations and documents did not allow custom fields in metadata.
### Improvements
* \[**Comments**]: Improved comments performance with optimistic local-first reads and writes.
* \[**Notifications**]: Added `documentMetadata` object in the properties that are sent to SendGrid for emails.
### Bug Fixes
* \[**Comments**]: Fixed an issue where custom metadata added to a comment using `addContext` was not sent to the first notification event (`newlyAdded`).
### Bug Fixes
* \[**Comments**]: Fixed an issue with `getCommentAnnotationsCount` API when filtering by specific document IDs in the query.
### Improvements
* \[**Security**]: Merged security patch in the React package
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the floating recording player was visible for threaded recorder notes
* \[**Comments**]: Fixed an issue where the sidebar button border color was using light mode colors in dark mode
## New APIs
### 1. setDocuments
* Set multiple documents at the same time. You can specify 30 documents at a time.
* The first document in the list will be considered as the root document.
* For features like comments, notifications, recorder, reactions etc. you will be able to read and write to multiple documents at the same time.
* For features like cursors, presence, huddle, live state sync etc. it will default to the root document.
* Sidebar will automatically show data from all the documents.
* Params:
* `documents`: [Document\[\]](/api-reference/sdk/models/data-models#document)
* `options?`: [SetDocumentsRequestOptions](/api-reference/sdk/models/data-models#setdocumentsrequestoptions)
**Using Hooks:**
```jsx theme={null}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
const { setDocuments } = useSetDocuments();
setDocuments(documents);
```
**Using API:**
```jsx theme={null}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
client.setDocuments(documents);
```
**Using API:**
```js theme={null}
const documents = [
{
id: 'document-1',
metadata: {
documentName: 'Document 1'
}
},
{
id: 'document-2',
metadata: {
documentName: 'Document 2'
}
}
];
Velt.setDocuments(documents);
```
### 2. getCommentAnnotations
* Get all the comment annotations for all the specified documents.
* You can specify 30 documents at a time.
* If you don't specify any query, it will return data from the documents specified in the `setDocuments` method.
**Using Hooks:**
```jsx theme={null}
const { data } = useGetCommentAnnotations(query);
// initial data value will be null while the request is in progress
```
**Using API:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotations(query).subscribe((response) => {
console.log(response.data);
// initial data value will be null while the request is in progress
});
```
```jsx theme={null}
CommentRequestQuery {
documentIds!: string[],
locationIds!: string[],
statusIds!: string[]
};
GetCommentAnnotationsResponse {
data: Record | null; // Key: documentId, Value: CommentAnnotation[]
};
```
**Using API:**
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotations(query).subscribe((response) => {
console.log(response.data);
// initial data value will be null while the request is in progress
});
```
```js theme={null}
CommentRequestQuery {
documentIds!: string[],
locationIds!: string[],
statusIds!: string[]
};
GetCommentAnnotationsResponse {
data: Record; // Key: documentId, Value: CommentAnnotation[]
};
```
### 3. getCommentAnnotationsCount
* Get the total and unread comment annotations count of all the comment annotations for all the specified documents.
* You can specify 30 documents at a time.
* If you don't specify any query, it will return data from the documents specified in the `setDocuments` method.
**Using Hooks:**
```jsx theme={null}
const { data } = useCommentAnnotationsCount(query);
// initial data value will be null while the request is in progress
```
**Using API:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.getCommentAnnotationsCount(query).subscribe((response) => {
console.log(response.data);
// initial data value will be null while the request is in progress
});
```
```jsx theme={null}
CommentRequestQuery {
documentIds!: string[],
locationIds!: string[],
statusIds!: string[]
};
GetCommentAnnotationsCountResponse {
data: Record | null; // Key: documentId, Value: CommentAnnotationsCount
};
CommentAnnotationsCount {
unread: number,
total: number
}
```
**Using API:**
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.getCommentAnnotationsCount(query).subscribe((response) => {
console.log(response.data);
});
```
```js theme={null}
CommentRequestQuery {
documentIds!: string[],
locationIds!: string[],
statusIds!: string[]
};
GetCommentAnnotationsCountResponse {
data: Record; // Key: documentId, Value: CommentAnnotationsCount
};
CommentAnnotationsCount {
unread: number,
total: number
}
```
### 4. Read/Write data from multiple documents on the same page
* If you want to display data (eg: comments) from multiple documents on the same page, you can add `data-velt-document-id` attribute to the container that contains the `document`.
* It will be used to identify which part of the DOM belongs to which document.
```html theme={null}
...
...
...
```
## Other updates
### New Features
* \[**Comments**]: Added support for Status Filter in Comments Sidebar's main filter menu:
* By default, the status filter is disabled in the main filter menu.
* Currently, it doesn't support grouping.
* Added Wireframe support for this. [Learn more](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/status).
* If you were using wireframes before, you will add this to your wireframes.
```jsx theme={null}
const filterConfig = {
status: {
enable: true,
name: "Status",
multiSelection: true,
}
};
```jsx theme={null}
const filterConfig = {
status: {
enable: true,
name: "Status",
multiSelection: true,
}
};
const commentsSidebar = document.querySelector(`velt-comments-sidebar`);
commentsSidebar?.setAttribute("filter-config",JSON.stringify(filterConfig));
```
### Bug Fixes
* \[**Comments**]: Fixed an issue where empty state visibility was not visible when filter is applied and grouping was disabled.
* \[**Comments**]: Fixed an issue where users could click on the comment in the sidebar and navigate to comments when they shouldn't.
# Tiptap CRDT Library
Source: https://docs.velt.dev/release-notes/version-4/tiptap-changelog
Release Notes of Changes Affecting Velt Tiptap CRDT Library
### Libraries
* `@veltdev/tiptap-crdt`
* `@veltdev/tiptap-crdt-react`
### Improvements
* \[**Core**]: Added production test cases for tiptap-crdt. Improved CRDT store initialization by using `veltInitState` for streamlined internal store creation.
### Bug Fixes
* \[**Core**]: Fixed multi-tab synchronization for same user. When the same user edits content in multiple tabs, all tabs now sync correctly.
**Tiptap v3 Required**: This release upgrades Tiptap from v2 to v3. You must update your Tiptap dependency to v3 to use the latest CRDT packages.
### Improvements
* \[**Core**]: Released stable version 4.5.8 with Tiptap v3 support. Fixed initialContent issue in tiptap-crdt-react that prevented proper initialization of editor content.
### New Features
* \[**Developer Tools**]: Added `window.VeltCrdtStoreMap` global interface to inspect and monitor CRDT stores during development. Access store values directly in the browser console using `VeltCrdtStoreMap.get(id)` or `VeltCrdtStoreMap.getAll()`. Subscribe to store updates and monitor registration events for debugging collaborative data synchronization. [Learn more](/realtime-collaboration/crdt/setup/core#veltcrdtstoremap)
### Bug Fixes
* \[**Core**]: Fixed `initialContent` not being applied when no server-side data exists. You can now set `initialContent` in TipTap CRDT, and it will be used when the document is empty.
```jsx theme={null}
const { VeltCrdt } = useVeltTiptapCrdtExtension({
editorId: "UNIQUE_EDITOR_ID",
initialContent: "Hello World
",
});
```
```javascript theme={null}
const veltCrdt = veltClient.getVeltTiptapCrdtExtension({
editorId: "UNIQUE_EDITOR_ID",
initialContent: "Hello World
",
});
```
### Improvements
* \[**Core**]: Improved the API signatures and naming to improve developer experience.
### Improvements
* \[**Core**]: Released a purpose built react package (`@veltdev/tiptap-crdt-react`) that reduced the implementation code by 95%.
### Bug Fixes
* \[**Core**]: Fixed an issue where last keystroke was not synced in some cases.
### New Features
* \[**Core**]: Introduced purpose built CRDT library for Tiptap Editor to enable multiplayer editing. This is based on the [Yjs](https://docs.yjs.dev/) library. [Learn more](/realtime-collaboration/crdt/setup/tiptap).
# Upgrade Guide
Source: https://docs.velt.dev/release-notes/version-4/upgrade-guide
## Overview
* **Key improvements in this series will focus on**:
* Advanced data querying capabilities
* Enhanced security features
* Powerful customization capabilities that will require significantly less code than before
* We are adding support for multiple document operations:
* **Multi-Document Handling**:
* Work with multiple Velt documents on a single page simultaneously
* Subscribe, view, and perform CRUD operations across multiple documents in real-time
* Comments from multiple documents are now automatically rendered in the Sidebar
* **Enhanced Querying**:
* Query comments, comment counts, unread counts across multiple documents with a simpler API
* Filter by document IDs, location IDs, and status IDs
## Breaking Changes
* \[**Authentication**] Made `organizationId` mandatory in `identify` method.
* \[**UI Customization**] If you applied CSS to wireframe component selectors, you need to update them to target Velt component selectors directly.
* Wireframe components are no longer rendered within Velt components. In previous versions, there were a few wireframe components that were rendered within Velt components.
* If you are an existing customer who is impacted, reach out and we will provide you the updated CSS for your implementation.
* \[**REST APIs**]: v1 GET APIs will not work once you deploy to this series. Use v2 GET APIs instead. All the other REST APIs should work as is.
## How to Upgrade
Use these steps with your test API key first. Once you are ready, follow the same steps on all your production API keys as well.
1. Ensure you are using `organizationId` vs `groupId` in the `identify` method. If you have existing data with groupId, then first migrate your data using [this guide](#migrating-from-groupid-to-organizationid).
2. Enable 'Advanced Queries and Filters' in the Velt Console [here](https://console.velt.dev/dashboard/config/appconfig). It will take 15-30 mins for this to be enabled in your API key depending on the size of your data.
3. Once, the feature is enabled, deploy the latest version of the Velt SDK to your product. Do this within couple of hours of enabling the feature.
### Migrating from `groupId` to `organizationId`
Use these steps with your test API key first. Once you are ready, follow the same steps on all your production API keys as well.
1. Change the `groupId` field to `organizationId` in the `identify` method. Once you do this, you will stop seeing the existing data locally. This is expected.
2. Goto the [data page in Velt Console](https://console.velt.dev/dashboard/data/organization). You will see an option to migrate data to `organizationId` structure.
3. Click on the `Migrate` button. The migration will take 15-30 mins to complete depending on the size of your data.
4. Once, the migration is done, you will start seeing the data. Your original `groupId` data will be retained as backup.
5. Deploy your changes to production. Note: Deploy soon after the migration completes to minimize any data inconsistency.
# Velt SDK Changelog
Source: https://docs.velt.dev/release-notes/version-5/sdk-changelog
Release Notes of changes added to the core Velt SDK
### Libraries
* `@veltdev/react`
* `@veltdev/client`
* `@veltdev/sdk`
### New Features
* \[**Activity Logs**]: A complete, real-time record of everything that happens across your product. Velt automatically generates activity log records for Comments, Reactions, Recorder, and CRDT features, and you can push custom events (deployments, status changes, escalations) into the same timeline using `createActivity()`. Subscribe org-wide for admin dashboards, filter by document for inline timelines, or scope by feature type to reduce noise. [Learn more →](/async-collaboration/activity/overview)
* \[**CRDT**]: Added `setActivityDebounceTime(time)` on `CrdtElement` to control how long editor keystrokes are batched before flushing a single activity log record. Default: 10 minutes. Minimum: 10 seconds. [Documentation →](/realtime-collaboration/crdt/setup/core#activity-log-debounce)
* \[**Activity Logs REST API**]: Added CRUD endpoints for activity log records (`/v2/activities/get`, `/v2/activities/add`, `/v2/activities/update`, `/v2/activities/delete`). Also added a `triggerActivities` flag on `POST /v2/commentannotations/add` to auto-create activity log records when comments are added. [REST API Reference →](/api-reference/rest-apis/v2/activities/get-activities)
### Bug Fixes
* \[**Comments**]: Fixed temp annotation context being cleared prematurely during comment submission in composer mode, preventing stale context from affecting subsequent comment operations.
### Bug Fixes
* \[**Comments**]: Fixed sidebar filters restored from `sessionStorage` being overwritten by the initial empty emission on page reload.
* \[**Comments**]: Fixed DOM annotation visibility diverging from sidebar filter state when filters were restored from session storage or set via defaults.
* \[**Comments**]: Fixed `mergeClientFilters` not handling `null` or empty `{}` filter objects correctly, which prevented filters from being cleared.
* \[**Comments**]: Fixed autocomplete hotkey button inserting a duplicate character when the hotkey already existed at the cursor position.
* \[**Comments**]: Fixed autocomplete cursor save/restore failing inside shadow DOM.
* \[**Comments**]: Fixed partial `@mention` replacement when one tagged user's name is a prefix of another (e.g., `@Alice` corrupting `@AliceSmith`).
* \[**Comments**]: Fixed multi-thread comment annotations not being filtered by sidebar filter state in the DOM.
### New Features
* \[**UI Customization**]: Added 13 standalone autocomplete primitive components (`VeltAutocompleteOption`, `VeltAutocompleteChip`, `VeltAutocompleteEmpty`, etc.) for building fully custom autocomplete UIs without requiring the full `` panel. [Learn More →](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltautocomplete)
* \[**UI Customization**]: Added `multiSelect`, `selectedFirstOrdering`, `readOnly`, `inline`, and `contacts` props to the [`VeltAutocomplete`](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltautocomplete) panel component.
### Improvements
* \[**Access Control**]: [`AccessRequestEvent`](/api-reference/sdk/models/data-models#accessrequestevent) and [`SEMEvent`](/api-reference/sdk/models/data-models#semevent) now include `totalUsers`, `presenceSnippylyUserIds`, and `presenceClientUserIds` fields for real-time presence context.
* \[**Analytics**]: `COMMENT_ADDED` and `COMMENT_STATUS_CHANGED` events now include `commentAnnotationCreatedAt`, `taggedClientUserIds`, and `taggedSnippylyUserIds`.
* \[**Analytics**]: New `REACTION_ADDED` and `REACTION_DELETED` events fire with `annotationId`, `commentId`, `reactionId`, and `commentMode`.
* \[**Analytics**]: Added `CRDT_DATA_UPDATED` analytics event with deduplication.
### Bug Fixes
* \[**Core**]: Fixed `client.setDocuments()` triggering duplicate concurrent initializations when called multiple times in rapid succession with identical document IDs and options.
* \[**Comments**]: Replaced custom `VeltCommentDialogVisibilityBannerDropdownContentUserPicker` sub-components with the shared autocomplete component.
### New Features
* \[**Comments**]: Added Private Comments UI. Enable it with `visibilityOptions`. Users see a persistent banner below the composer with four visibility levels — `public`, `organization-private`, `restricted-self`, and `restricted` — and an inline user-picker (search, avatar list, multi-select) when `restricted` is chosen. Visibility can also be changed after submission from the thread options menu.
```jsx theme={null}
```html theme={null}
The banner surface is fully wireframe-customizable via the new [`VeltCommentDialogWireframe.VisibilityBanner.*` / `velt-comment-dialog-visibility-banner-*`](/ui-customization/features/async/comments/comment-dialog-components#visibility-banner) family.
* \[**Comments**]: Added `AddCommentRequest.visibility` field of type `CommentVisibilityConfig` to set comment visibility at creation time. Previously visibility could only be set after creation via `updateVisibility()`.
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.addComment({
annotationId: 'annotation-id',
comment: { text: 'Visible only to selected users' },
visibility: {
type: 'restricted',
userIds: ['user1', 'user2'],
},
});
```
```html theme={null}
```
### Improvements
* \[**Comments**]: `VisibilityOptionClickedEvent` now includes an optional `users` field containing the list of selected users when `visibility === 'restricted'`. Previously, the event only reported the visibility type string.
```jsx theme={null}
const eventData = useCommentEventCallback('visibilityOptionClicked');
useEffect(() => {
if (eventData) {
console.log(eventData.visibility); // 'public' | 'organization-private' | 'restricted-self' | 'restricted'
console.log(eventData.users); // populated when visibility === 'restricted'
}
}, [eventData]);
```
```html theme={null}
```
* \[**Comments**]: `CommentSaveTriggeredEvent` now includes a `commentAnnotation` field with the full annotation object at save time. Handlers for `onCommentSaveTriggered` can now access comment content, assignment, and visibility state without a separate lookup.
### New Features
* \[**Comments**]: Added [`AnonymousUserDataProvider`](/self-host-data/users#anonymous-user-resolution) to resolve email → `userId` mappings for users who are tagged by email in comments but are not part of the contact list. When a comment is saved and a tagged contact or `to` recipient has an email but no `userId`, the SDK calls the registered provider to look up the `userId` and backfills it into the comment data before persisting.
```jsx theme={null}
// Option 1: standalone method
client.setAnonymousUserDataProvider({
resolveUserIdsByEmail: async (request) => {
// request.emails: string[]
const map = await yourBackend.lookupUserIds(request.emails);
return { statusCode: 200, success: true, data: map };
},
config: {
resolveTimeout: 5000,
getRetryConfig: { retryCount: 2, retryDelay: 300 },
},
});
// Option 2: via setDataProviders
client.setDataProviders({
anonymousUser: {
resolveUserIdsByEmail: async (request) => { /* ... */ },
},
});
```
```html theme={null}
```
Results are cached in memory for the session; emails already resolved are not re-fetched. On timeout or error, the provider returns whatever was cached and proceeds without the unresolved user IDs. If no [`UserDataProvider`](/api-reference/sdk/models/data-models#userdataprovider) is configured, resolved user IDs are automatically backfilled to the organization database as stub user records (`{ userId, name: email, email }`). If a `UserDataProvider` is already configured, the org DB backfill is skipped.
### Improvements
* \[**Comments**]: Comment annotations now store a top-level [`visibilityConfig`](/api-reference/sdk/models/data-models#commentannotationvisibilityconfig) field (`{ type, organizationId, userIds }`) alongside the existing `context.accessFields` tokens. This makes the original visibility setting inspectable without reversing hashed tokens. Annotations without an explicit visibility setting default to `{ type: 'public' }`. The `context.accessFields` tokens continue to govern actual access control.
* \[**Comments**]: When setting restricted visibility, the current user's `userId` is now automatically appended to `userIds` (deduplicated) if not already present. Existing explicit `userIds` lists are preserved. This applies across [`enablePrivateMode`](/async-collaboration/comments/customize-behavior#enableprivatemode), [`addCommentAnnotation`](/async-collaboration/comments/customize-behavior#addcommentannotation), and [`updateVisibility`](/async-collaboration/comments/customize-behavior#updatevisibility).
### New Features
* \[**Comments**]: Added a `commentSaveTriggered` event that fires immediately when a user clicks the save button, before the async save completes. Use it for immediate pre-save feedback alongside the existing `commentSaved` event, which continues to fire after the save finishes.
```jsx theme={null}
// Using hook
const event = useCommentEventCallback('commentSaveTriggered');
useEffect(() => {
if (event) {
console.log('Save triggered for annotation:', event.annotationId);
}
}, [event]);
```
```html theme={null}
```
The exported [`CommentSaveTriggeredEvent`](/api-reference/sdk/models/data-models#commentsavetriggeredevent) interface has the following shape:
```ts theme={null}
interface CommentSaveTriggeredEvent {
annotationId: string;
metadata: VeltEventMetadata;
}
```
### Improvements
* \[**Comments**]: The sidebar now automatically returns to the full comment list when all annotations are deselected while in focused thread mode.
* \[**Comments**]: Page scroll position is now preserved when navigating to a highlighted annotation from the sidebar.
### New Features
* \[**Comments**]: Added a visibility dropdown to the comment composer, letting users set a comment's visibility to `public` or `private` before submitting. Disabled by default; enable it via the `visibilityOptionDropdown` prop or API methods. A `visibilityOptionClicked` event fires on each selection, emitting the annotation ID, full [`CommentAnnotation`](/api-reference/sdk/models/data-models#commentannotation), and chosen visibility.
```tsx theme={null}
// Declarative prop
```html theme={null}
To customize the dropdown via wireframes, you can refer to the [wireframe documentation](/ui-customization/features/async/comments/comment-dialog-components#visibility-dropdown-composer).
### Bug Fixes
* \[**Comments Sidebar**]: Fixed the "(This page)" indicator not appearing for locations identified by `locationName` instead of `id`. The sidebar now matches the current location by `id`, `locationName`, or legacy `locationId`, in that order.
### Bug Fixes
* \[**Comments**]: Fixed temporary composer annotations (prefixed `TEMP_COMPOSER_`) being inadvertently persisted to the database. Guards were added so temp annotations remain client-only and are never written to the database.
* \[**Comments**]: Fixed the comment dialog calling `markAsRead()` for `TEMP_COMPOSER_` annotations that do not yet exist in the database. The call is now guarded so only persisted annotations are marked read when a pin is selected.
* \[**Comments Sidebar**]: Fixed the sidebar failing to identify the current page's annotation group when a location is configured with `locationName` but no `id`. The sidebar now resolves the current location using `location.id` first, then `location.locationName`, then alphabetical order.
* \[**Notifications**]: Fixed a race condition where a stale async call completing after a newer one could overwrite the user's saved notification config with defaults.
* \[**Comments**]: Fixed comment pins being placed at incorrect positions on video timelines whose total duration is not a whole number of seconds. Fractional-second durations are now preserved correctly.
### New Features
* \[**Comments**]: Added `enablePrivateMode(config)` and `disablePrivateMode()` methods to set a global visibility policy for all newly created comments. Supports `restricted` (user-list), `organizationPrivate`, and `public` visibility types via the new [`PrivateModeConfig`](/api-reference/sdk/models/data-models#privatemodeconfig) type.
```tsx theme={null}
// Using API methods
const commentElement = client.getCommentElement();
// Restrict all new comments to specific users
commentElement.enablePrivateMode({ type: 'restricted', userIds: ['user-1', 'user-2'] });
// Restrict all new comments to the current organization
commentElement.enablePrivateMode({ type: 'organizationPrivate' });
// Revert to default public visibility
commentElement.disablePrivateMode();
```
```ts theme={null}
const commentElement = Velt.getCommentElement();
// Restrict all new comments to specific users
commentElement.enablePrivateMode({ type: 'restricted', userIds: ['user-1', 'user-2'] });
// Restrict all new comments to the current organization
commentElement.enablePrivateMode({ type: 'organizationPrivate' });
// Revert to default public visibility
commentElement.disablePrivateMode();
```
* \[**Comments**]: Added a `commentSaved` event that fires after a comment is persisted to the database, providing a reliable signal for triggering downstream actions. The payload includes the annotation ID, full [`CommentAnnotation`](/api-reference/sdk/models/data-models#commentannotation), and [`VeltEventMetadata`](/api-reference/sdk/models/data-models#velteventmetadata).
```tsx theme={null}
// Using Hooks
import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';
const commentSavedData = useCommentEventCallback('commentSaved');
useEffect(() => {
if (commentSavedData) {
console.log('Comment saved:', commentSavedData.annotationId);
console.log('Annotation:', commentSavedData.commentAnnotation);
}
}, [commentSavedData]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('commentSaved').subscribe((event) => {
console.log('Comment saved:', event.annotationId);
console.log('Annotation:', event.commentAnnotation);
});
```
```ts theme={null}
const commentElement = Velt.getCommentElement();
commentElement.on('commentSaved').subscribe((event) => {
console.log('Comment saved:', event.annotationId);
console.log('Annotation:', event.commentAnnotation);
});
```
* \[**Notifications**]: Added opt-in notification delay and batching pipeline for comment notifications. Configure `delayConfig` to hold notifications and suppress delivery if a user views the comment during the delay window. Configure `batchConfig` to accumulate notifications per document or per user before delivery, reducing noise on high-activity content. Webhooks and workflow triggers always fire immediately and are never subject to delay or batching.
```json theme={null}
{
"delayConfig": {
"isEnabled": true,
"delaySeconds": 30
},
"batchConfig": {
"document": {
"isEnabled": true,
"batchWindowSeconds": 300,
"maxActivities": 10
},
"user": {
"isEnabled": true,
"batchWindowSeconds": 300,
"maxActivities": 10
}
}
}
```
Set `notificationServiceConfig` in your workspace notification settings in the [Velt Console](https://console.velt.dev/dashboard/config/notification). [Learn more](/async-collaboration/notifications/customize-behavior#notificationserviceconfig)
* \[**Notifications**]: Webhook payloads now include per-user notification preferences for all involved users. Depending on the config level, payloads carry either `usersOrganizationNotificationsConfig` or `usersDocumentNotificationsConfig`, enabling downstream consumers to route notifications based on each user's settings. See [`UserNotificationsConfig`](/api-reference/sdk/models/data-models#usernotificationsconfig) for the type definition. [Learn more](/webhooks/basic)
```json theme={null}
{
"webhookId": "notif-123",
"usersOrganizationNotificationsConfig": {
"user-1": { "inbox": "ALL", "email": "MINE" },
"user-2": { "inbox": "ALL", "email": "MINE" }
}
}
```
```json theme={null}
{
"webhookId": "notif-456",
"usersDocumentNotificationsConfig": {
"user-1": { "inbox": "ALL", "email": "MINE" },
"user-2": { "inbox": "ALL", "email": "MINE" }
}
}
```
* \[**Notifications**]: The `getConfig` notification API now supports a `getOrganizationConfig: true` option to retrieve org-level notification config for a user. `documentIds` is now optional in `setConfig` — omitting it applies the config at the organization level as the user's default for all documents. [setConfig](/api-reference/rest-apis/v2/notifications/set-config) | [getConfig](/api-reference/rest-apis/v2/notifications/get-config)
```json theme={null}
{
"data": {
"organizationId": "org-123",
"userIds": ["user-1", "user-2"],
"config": {
"inbox": "ALL",
"email": "NONE"
}
}
}
```
```json theme={null}
{
"data": {
"organizationId": "org-123",
"userId": "user-1",
"getOrganizationConfig": true
}
}
```
### Improvements
* \[**Comments**]: Added auto-resolution of the organization ID from the current org configuration when `updateVisibility()` or `enablePrivateMode()` is called with `type: 'organizationPrivate'` and no `organizationId` is provided.
### Bug Fixes
* \[**Comments**]: Fixed global dark mode toggling not affecting open comment dialogs. Dialog initialization no longer sets a component-level dark mode override that would block `ThemeService` propagation.
* \[**Comments**]: Fixed composer placeholder text not reappearing after a user typed and deleted all text. The contenteditable element is now cleared with `innerHTML = ''` to ensure the CSS `:empty::before` placeholder renders correctly.
* \[**Comments**]: Fixed SVG gradient, clip-path, and filter rendering for duplicate emoji reactions. Each emoji SVG instance now receives unique internal IDs via `EmojiService.uniquifySvgIds()`.
* \[**Comments**]: Fixed priority dropdown showing an incorrect background color in dark mode when no priority was set.
* \[**Comments**]: Fixed user migration not updating `{{userId}}` placeholders in `commentText`/`commentHtml` and not remapping `views`/`viewedByUserIds` by internal user key. All userId references in comment content and view tracking are now correctly updated during migration.
### Improvements
* \[**Comments**]: Added backward compatibility so V4 custom wireframes using property names `allowAssignment`, `allowEdit`, `allowToggleNotification`, and `allowChangeCommentAccessMode` automatically resolve to their v5 equivalents. No changes to your wireframe code are required when upgrading from v4 to v5.
* \[**Comments**]: Added edit composer wireframe reuse in comment thread cards so it now applies the same `velt-comment-dialog-composer-wireframe` customization as the reply composer. Previously the edit composer always rendered the default template.
### Bug Fixes
* \[**Comments**]: Fixed custom wireframes for nested comment dialog components — including thread cards, priority/status dropdowns, attachment layouts, reply avatars, and seen dropdowns — silently falling back to the default template instead of rendering correctly. This restores the v4 behavior where parent components extracted nested wireframes via `querySelector` and passed them to children.
* \[**Comments**]: Fixed `veltDynamicTemplate` placement in multiple components so it wraps only the replaceable inner content (e.g., an icon) instead of the entire component structure. Previously the default template always rendered and the wireframe content was never injected.
* \[**Comments**]: Fixed `velt-class` conditional styling in custom wireframes not resolving correctly for per-item data such as `{commentObj.*}`, `{attachment.*}`, and `{file.*}`. Added `applyConditionalClasses()` calls with per-item data contexts across 40+ comment dialog primitive components.
* \[**Comments**]: Fixed click event handlers being lost when custom wireframes replace default content by moving handlers from inside `veltDynamicTemplate` blocks to wrapper elements outside the template directive. This restores click functionality for custom wireframes on mark-as-read, dropdown items, options, and priority/status items.
* \[**Comments**]: Fixed per-dialog state (`localUIStateSignal`) not being propagated to child primitives and `veltDynamicTemplate` contexts throughout the entire comment dialog component tree, including through wireframe-replaced sections.
* \[**Comments**]: Fixed custom wireframes using data bindings like `
### New Features
* \[**Comments**]: Added `enableAttachmentDownload()` / `disableAttachmentDownload()` API methods and an `attachmentDownload` prop on `` to control whether clicking an attachment triggers a file download. A new `attachmentDownloadClicked` event fires on every attachment click regardless of the download setting, letting you intercept clicks for custom viewers, analytics, or access control. Download is enabled by default so there is no breaking change.
```jsx theme={null}
// Declarative prop
```html theme={null}
The exported `AttachmentDownloadClickedEvent` interface has the following shape:
```ts theme={null}
interface AttachmentDownloadClickedEvent {
annotationId: string;
commentAnnotation: CommentAnnotation;
attachment: Attachment;
metadata?: VeltEventMetadata;
}
```
### Improvements
* \[**Comments**]: The wireframe template for the resolve and unresolve buttons in the assignee banner is now nested inside the button component rather than wrapping it, giving custom wireframes direct access to button state, styling, and event handlers. The affected wireframes are `velt-comment-dialog-assignee-banner-resolve-button-wireframe` and `velt-comment-dialog-assignee-banner-unresolve-button-wireframe`.
* \[**Comments**]: Added CSS classes to comment composer attachment components to reflect loading and edit-mode states: `.velt-composer-attachment-container`, `.velt-composer-attachment--loading`, and `.velt-composer-attachment--edit-mode`.
* \[**Comments**]: Added `.s-comment-dialog-assign-to-menu` and `.velt-thread-card--assign-to-menu` CSS classes to the assign-to menu component for more granular styling control.
### Bug Fixes
* \[**Comments**]: Added `'iframe'` to the list of non-nestable elements so that `getHostElement()` returns the iframe's parent element instead of attempting to place a comment pin inside the iframe document context.
* \[**Comments**]: Fixed a regression where navigating back from a focused thread triggered an unintended draft auto-save. A guard now skips auto-save when the focused thread dialog is destroyed via back navigation.
* \[**Comments**]: Fixed stale selection state in the sidebar after back-navigating from a focused annotation. The annotation is now properly deselected from the internal selection map on exit.
* \[**Comments**]: Thread card attachment components now use `isTemplateEmpty()` to detect empty wireframe templates instead of a truthy check, so attachments correctly fall back to default rendering when an empty wireframe is provided.
* \[**Comments**]: Custom thread card wireframes that do not include an edit composer wireframe now automatically render the default edit composer, so inline comment editing remains functional without requiring wireframe changes.
### New Features
* \[**Comments**]: Added `clearContext` option to `PageModeComposerConfig` to control whether comment context is cleared after page mode composer submission. Set `clearContext: false` to preserve context data across submissions (defaults to `true`).
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
commentElement.setContextInPageModeComposer({
context: { documentId: '123', section: 'intro' },
targetElementId: 'my-element',
clearContext: false
});
// Using API methods
const commentElement = client.getCommentElement();
commentElement.setContextInPageModeComposer({
context: { documentId: '123', section: 'intro' },
targetElementId: 'my-element',
clearContext: false
});
```
```html theme={null}
```
### Bug Fixes
* \[**Comments**]: Removed host CSS classes `velt-composer-open` and `velt-composer-input-focused` from the Comment Dialog Composer component. If your custom styles targeted these classes, update your selectors accordingly.
* \[**Comments**]: Fixed wireframe template forwarding in Comment Dialog so custom templates set via `dialogTemplate` are now correctly applied to all child components.
* \[**Comments**]: Fixed nested wireframe template extraction in Comment Dialog Threads so custom `velt-comment-dialog-thread-card-wireframe` and `velt-comment-dialog-more-reply-wireframe` templates are correctly applied.
* \[**Comments**]: Fixed Mark as Read/Unread wireframe template structure so custom wireframe templates now provide proper control over the button's internal elements.
* \[**Comments**]: Added proper wireframe template wrapper to the parent Mark as Read component with a clickable container that includes accessibility attributes for the toggle action.
* \[**Comments**]: Fixed comment annotation data resolution in button click handlers so `commentAnnotation` context data now correctly resolves from the updated component config structure.
### New Features
* \[**CRDT**]: Added [Add CRDT Data](/api-reference/rest-apis/v2/crdt/add-crdt-data) REST API to create new CRDT editor data on the backend. Supports `text`, `map`, `array`, and `xml` types for use with Multiplayer Editing (Yjs).
* \[**CRDT**]: Added [Update CRDT Data](/api-reference/rest-apis/v2/crdt/update-crdt-data) REST API to replace existing CRDT editor data. Generates proper CRDT operations so connected clients pick up the change automatically.
### Bug Fixes
* \[**Comments**]: Fixed edit mode not working in thread card messages. Edit mode now properly propagates to comment messages within thread cards.
### Improvements
* \[**Comments**]: Updated `updateVisibility()` with `type: 'restricted'` to auto-default to the current authenticated user when no `userIds` are provided. Developers no longer need to manually pass the current user's ID.
```jsx theme={null}
// Using hook
const commentElement = useCommentUtils();
// Before: Had to pass userIds manually
commentElement.updateVisibility({
annotationId: 'annotation-1',
visibility: { type: 'restricted', userIds: ['current-user-id'] }
});
// After: userIds auto-defaults to current authenticated user
commentElement.updateVisibility({
annotationId: 'annotation-1',
visibility: { type: 'restricted' }
});
// Using API method
const commentElement = client.getCommentElement();
commentElement.updateVisibility({
annotationId: 'annotation-1',
visibility: { type: 'restricted' }
});
```
```html theme={null}
```
* \[**Comments**]: Improved performance of `getCommentAnnotationsCount()` by automatically batching queries when 2+ `documentIds` are provided. You can customize the debounce delay with `debounceMs` parameter (default 5000ms).
```jsx theme={null}
// Using hook
const commentElement = useCommentUtils();
// Automatically batches when 2+ documentIds are provided
const counts = commentElement.getCommentAnnotationsCount({
documentIds: ['doc-1', 'doc-2', 'doc-3']
});
// Optional: customize debounce (default 5000ms)
const countsWithDebounce = commentElement.getCommentAnnotationsCount({
documentIds: ['doc-1', 'doc-2', 'doc-3'],
debounceMs: 2000
});
// Using API method
const commentElement = client.getCommentElement();
const counts = commentElement.getCommentAnnotationsCount({
documentIds: ['doc-1', 'doc-2', 'doc-3']
});
```
```html theme={null}
```
* \[**Comments**]: Deprecated legacy `enablePrivateCommentMode()`, `disablePrivateCommentMode()`, and `updateAccess()` methods. These are replaced by the visibility API. Existing usage continues to work but IDEs will show deprecation warnings.
### Improvements
* \[**Core**]: Added ability to control Firestore SDK logs via `sessionStorage` or environment config. By default, logs are silenced to reduce console noise in production.
* \[**Performance**]: Added GSAP animation detection to reduce MutationObserver overhead. Pages using GSAP now experience \~20x performance improvement (from \~375ms to \~18ms per callback).
### Bug Fixes
* \[**Comments**]: Fixed cursor position loss on mobile when selecting autocomplete options. The cursor now stays at the correct position after selecting @-mentions.
* \[**Comments**]: Fixed hotkey insertion in autocomplete tool. Clicking the autocomplete trigger button (e.g. "@") now inserts at cursor position on all browsers, preserving mention spans.
* \[**Comments**]: Fixed autocomplete panel click events bubbling through dropdown. Selecting options no longer accidentally triggers underlying elements on mobile browsers.
* \[**Comments**]: Disabled format options (bold, italic, etc.) by default. To enable, set `enableFormatOptions: true` in your comment configuration.
* \[**Comments**]: Fixed cursor position in bottomsheet mode after selecting mentions. The cursor now appears after the mention span instead of jumping to the beginning.
* \[**Comments**]: Fixed attachment components not receiving parent UI state. Selected and invalid attachment components now correctly react to parent composer state changes.
### New Features
* \[**Comments**]: Added rich text formatting toolbar for comment composers. Users can apply bold, italic, underline, and strikethrough formatting to emphasize text.
```jsx theme={null}
// Using Hooks
import { VeltComments } from '@veltdev/react';
```html theme={null}
* \[**Comments**]: Added `clearComposer()` method to programmatically reset composer state (text, attachments, recordings, tagged users).
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
commentElement.clearComposer({ targetComposerElementId: 'my-composer-1' });
// Using API methods
const commentElement = client.getCommentElement();
commentElement.clearComposer({ targetComposerElementId: 'my-composer-1' });
```
```html theme={null}
```
* \[**Comments**]: Added `getComposerData()` method to retrieve current composer state synchronously without subscribing to events.
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
const data = commentElement.getComposerData({ targetComposerElementId: 'my-composer-1' });
if (data) {
console.log(data.text);
console.log(data.annotation);
console.log(data.targetComposerElementId);
}
// Using API methods
const commentElement = client.getCommentElement();
const data = commentElement.getComposerData({ targetComposerElementId: 'my-composer-1' });
```
```html theme={null}
```
* \[**Comments**]: Added `context` prop to `VeltCommentDialogComposer` to attach custom context data to comments created from standalone composers.
```jsx theme={null}
```html theme={null}
```
### Improvements
* \[**Comments**]: Updated `composerTextChange` event to include the full draft annotation object and `targetComposerElementId`. Access tagged users, attachments, recordings, context, and assign-to data without additional API calls.
```jsx theme={null}
// Using Hooks
const composerTextChangeEvent = useCommentEventCallback('composerTextChange');
useEffect(() => {
if (composerTextChangeEvent) {
console.log(composerTextChangeEvent.text);
console.log(composerTextChangeEvent.annotation);
console.log(composerTextChangeEvent.targetComposerElementId);
}
}, [composerTextChangeEvent]);
// Using API methods
const commentElement = client.getCommentElement();
commentElement.on('composerTextChange').subscribe((event) => {
console.log(event.text);
console.log(event.annotation);
console.log(event.targetComposerElementId);
});
```
```html theme={null}
```
* \[**Notifications**]: Fixed notification panel settings accordion wireframes to properly forward custom trigger and content templates to child components.
### Bug Fixes
* \[**Comments**]: Fixed `assignToType` to correctly respect values set via attribute or API without being overridden by hardcoded defaults.
* \[**Comments**]: Fixed formatted text (bold, italic, underline, strikethrough) to preserve formatting on submit and edit.
### New Features
* \[**Comments**]: Added page mode composer context APIs to pass context when opening the sidebar via the comment tool. When enabled, clicking the comment tool opens the sidebar with the page mode composer and passes configured context automatically.
```jsx theme={null}
// Using API methods
import { useCommentUtils, VeltCommentTool } from '@veltdev/react';
const commentElement = useCommentUtils();
// Enable context passing mode
commentElement.enableContextInPageModeComposer();
// Set context with target element
commentElement.setContextInPageModeComposer({
context: { projectId: 'abc123', section: 'header' },
targetElementId: 'my-target-element'
});
// Focus the composer programmatically
commentElement.focusPageModeComposer();
// Clear context
commentElement.clearPageModeComposerContext();
// Disable context passing mode
commentElement.disableContextInPageModeComposer();
// Using props
Using props:
```html theme={null}
Using API methods:
```
* \[**Comments**]: Added `setAssignToType()` method to switch the assignment UI between dropdown and checkbox modes. Checkbox mode allows quick self-assignment with a toggle.
```jsx theme={null}
// Using Hooks
import { useCommentUtils, VeltComments } from '@veltdev/react';
const commentElement = useCommentUtils();
// Use dropdown mode (default)
commentElement.setAssignToType({ type: 'dropdown' });
// Use checkbox mode for quick self-assignment
commentElement.setAssignToType({ type: 'checkbox' });
// Using props
Using props:
```html theme={null}
* \[**Comments**]: Added "Assigned to me" filter option in the sidebar to filter comments by assignment.
```jsx theme={null}
import { VeltCommentsSidebarWireframe } from '@veltdev/react';
```
```html theme={null}
```
* \[**Comments**]: Added new event types to track comment tool and sidebar button clicks. Subscribe to these events to access context data for analytics and custom workflows.
```jsx theme={null}
// Using Hooks
import { useCommentEventCallback } from '@veltdev/react';
import { useEffect } from 'react';
const commentToolClickEvent = useCommentEventCallback('commentToolClicked');
useEffect(() => {
if (commentToolClickedEvent) {
console.log('Context:', commentToolClickedEvent.context);
console.log('Target Element ID:', commentToolClickedEvent.targetElementId);
}
}, [commentToolClickedEvent]);
const sidebarButtonClickedEvent = useCommentEventCallback('sidebarButtonClicked');
useEffect(() => {
if (sidebarButtonClickedEvent) {
console.log('Sidebar button clicked');
}
}, [sidebarButtonClickedEvent]);
// Using API methods
import { useVeltClient } from '@veltdev/react';
const { client } = useVeltClient();
const commentElement = client.getCommentElement();
commentElement.on('commentToolClicked').subscribe((event) => {
console.log('Context:', event.context);
console.log('Target Element ID:', event.targetElementId);
});
commentElement.on('sidebarButtonClicked').subscribe((event) => {
console.log('Sidebar button clicked');
});
```
```html theme={null}
```
* \[**Comments**]: Added `readOnly` prop to control read-only mode at the component level. The local prop takes precedence over global settings when explicitly set.
```jsx theme={null}
import { VeltCommentComposer, VeltInlineCommentsSection } from '@veltdev/react';
```html theme={null}
```
* \[**Comments**]: Added wireframe component to customize the assign button on thread cards.
```jsx theme={null}
import { VeltCommentDialogWireframe } from '@veltdev/react';
```html theme={null}
* \[**Comments**]: Added wireframe component to customize the edit composer within comment thread cards.
```jsx theme={null}
import { VeltCommentDialogWireframe } from '@veltdev/react';
```html theme={null}
```
* \[**Comments**]: Added reaction pin component to pin specific reactions and exclude them from the general list.
```jsx theme={null}
import { VeltCommentDialogWireframe } from '@veltdev/react';
```
```html theme={null}
```
* \[**Comments**]: Added `resolvedByUser` property on [`CommentAnnotation`](/api-reference/sdk/models/data-models#commentannotation) to access the full user object of who resolved a comment.
### Improvements
* \[**Comments**]: Renamed `targetElementId` to `targetComposerElementId` on `VeltCommentComposer` for clarity.
```jsx theme={null}
import { VeltCommentComposer } from '@veltdev/react';
// Before (deprecated)
```html theme={null}
* \[**Comments**]: Added CSS class `.velt-assign-dropdown--checkbox-icon-selected` to style the checkbox selected state.
### Bug Fixes
* \[**Comments**]: Fixed cursor jumping when clicking autocomplete tool buttons. Text now inserts at the correct cursor position.
* \[**Comments**]: Fixed actions menu visibility so it remains visible when the assignment dropdown is opened.
* \[**Comments**]: Added "Assign" tooltip to the assignment button in thread cards.
* \[**Comments**]: Fixed "Assign To" label capitalization to "Assign to".
* \[**Reactions**]: Added `.velt-reaction-pin--no-reactions` CSS class for styling empty reaction pins.
* \[**Comments**]: Fixed autocomplete panel viewport height to respect custom `itemSize` from `autoCompleteScrollConfig`.
* \[**Comments**]: Fixed attachment metadata handling to use fallback values when metadata is unavailable.
* \[**Comments**]: Fixed read-only state management so local `readOnly` props are not overridden by global state changes.
* \[**Reactions**]: Fixed reactions panel to return an empty array on error instead of default emojis.
* \[**Comments**]: Fixed `reactionId` prop on `VeltCommentDialogWireframe.ThreadCard.ReactionPin` to properly convert to dashed-case in React.
### New Features
* \[**Notifications**]: Added ability to enable organization-level notification settings. This allows you to configure notifications once for all documents in an organization instead of per document.
```jsx theme={null}
```html theme={null}
```
### Improvements
* \[**Comments**]: Comments sidebar group-by views now display "Unassigned" for annotations without assignees and "Untagged" for annotations without tagged users.
### Bug Fixes
* \[**Comments**]: Fixed an issue where image attachments in comment dialog were not opening in a lightbox view.
* \[**Comments**]: Fixed an issue where sometimes user mentions did not include the leading `@` symbol in display text.
* \[**Comments**]: Fixed an issue where the recorder control panel in comment dialog composer did not appear when a valid comment dialog ID was not present in component configuration.
* \[**Comments**]: Fixed an issue where assignment and private comment options did not respect explicit configuration in sidebar mode.
* \[**Comments**]: Fixed an issue where the comment dialog internal tag was changed from `snippyly-comment-dialog` to `velt-comment-dialog-internal` for correct sidebar focus and keyboard behavior.
### Improvements
* \[**Comments**]: Added ability to enable/disable Private Comments feature in [Velt Console](https://console.velt.dev/dashboard/config/appconfig)
### Improvements
* \[**Comments**]: Added `batchedPerDocument` mode for `getCommentAnnotationsCount()` that makes the query more efficient by up to 80% while maintaining per-document granularity. Very useful for UIs that need to display comment counts for 100 documents or less on the same page.
```jsx theme={null}
// Using hook
const commentElement = useCommentUtils();
const counts = commentElement.getCommentAnnotationsCount({
documentIds: ['doc-1', 'doc-2', ..., 'doc-100'],
batchedPerDocument: true
});
// Using API method
const client = useVeltClient();
const commentElement = client.getCommentElement();
const counts = commentElement.getCommentAnnotationsCount({
documentIds: ['doc-1', 'doc-2', ..., 'doc-100'],
batchedPerDocument: true,
debounceMs: 5000
});
```
```html theme={null}
```
**Return Format:**
```typescript theme={null}
{
data: {
"doc-1": { total: 10, unread: 2 },
"doc-2": { total: 15, unread: 5 }
}
}
```
### Bug Fixes
* \[**Comments**]: Fixed draft mode not working properly. Draft content is now preserved when the dialog is closed and the shake animation now works as expected.
* \[**Comments**]: Fixed context property access in `velt-data` elements. Templates can now access context properties using `{context.propertyName}` patterns.
* \[**Comments**]: Fixed edit mode state persisting after dialog close. Reopening the dialog now shows the normal view instead of the edit composer.
* \[**Comments**]: Fixed text reappearing when using select-all-and-delete in edit mode composer. Users can now properly delete all text in edit mode.
* \[**Comments**]: Fixed links in comment body not clickable. Clicking links in comment text now opens them in a new tab.
* \[**Comments**]: Fixed paste handling. Pasting a URL over selected text creates a hyperlink, multiline text preserves line breaks, and images paste as attachments.
* \[**Comments**]: Fixed ghost comment banners not displaying. "Comment is syncing..." messages now properly show while annotation data is loading.
* \[**Comments**]: Fixed priority selection not working on new annotations. Users can now set priority before submitting the first comment.
* \[**Comments**]: Fixed email detection after @ symbol. Typing `@user@example.com` and pressing space now creates an email mention.
* \[**Comments**]: Fixed recording in progress flag not clearing. Dialog now properly closes on click outside after recording finishes.
* \[**Comments**]: Fixed links and @here mentions not highlighted in comment text. URLs are now styled as clickable links and @here mentions are properly highlighted.
### New Features
* \[**Comments**]: Introducing Private Comments feature: Added `updateVisibility()` method to programmatically set comment access (public, organizationPrivate, or restricted). [Learn more](/async-collaboration/comments/customize-behavior#updatevisibility)
```jsx theme={null}
// Using hook
const commentElement = useCommentUtils();
// Set comment to organization-only
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'organizationPrivate',
organizationId: 'org-123'
});
// Set comment to private (specific users)
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'restricted',
userIds: ['user-1', 'user-2']
});
// Set comment to public
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'public'
});
// Using API method
const client = useVeltClient();
const commentElement = client.getCommentElement();
commentElement.updateVisibility({
annotationId: "annotationId",
type: 'organizationPrivate',
organizationId: 'org-123'
});
```
```html theme={null}
```
### Bug Fixes
* \[**Comments**]: Fixed mentioned users not receiving notifications. Users @mentioned in comments now correctly receive notifications.
* \[**Comments**]: Fixed notification action type validation. Clients only receive data for valid event types.
* \[**Comments**]: Fixed status reset when deleting comments. Status now only resets when current status is terminal.
### New Features
* \[**Comments**]: Added `addCommentAnnotationDraft` event to dynamically set context when creating comment annotations. Triggered before `addCommentAnnotation` event clicks on the comment tool and the composer is rendered.
```jsx theme={null}
// Using hook
const addCommentAnnotationDraftEvent = useCommentEventCallback('addCommentAnnotationDraft');
useEffect(() => {
if (addCommentAnnotationDraftEvent?.addContext) {
addCommentAnnotationDraftEvent.addContext({
questionId: '123',
questionText: 'What is the capital of France?',
});
}
}, [addCommentAnnotationDraftEvent]);
// Using API method
const client = useVeltClient();
const commentElement = client.getCommentElement();
commentElement.on('addCommentAnnotationDraft').subscribe((event) => {
if (event?.addContext) {
event.addContext({
questionId: '123',
questionText: 'What is the capital of France?',
});
}
});
```
```html theme={null}
```
### Improvements
* \[**Comments**]: Added `setContextProvider` method to set a global context provider for all comment annotations. Also added `useSetContextProvider` hook for React applications.
```jsx theme={null}
// Using hook
import { useCallback, useEffect } from 'react';
import { useSetContextProvider } from '@veltdev/react';
const contextProvider = useCallback((documentId, location) => {
return {
questionId: '123',
questionText: 'What is the capital of France?',
}
}, []);
const { setContextProvider } = useSetContextProvider();
useEffect(() => {
if (setContextProvider && contextProvider) {
setContextProvider(contextProvider);
}
}, []);
// Using API method
const client = useVeltClient();
const commentElement = client.getCommentElement();
commentElement.setContextProvider((documentId, location) => {
return {
questionId: '123',
questionText: 'What is the capital of France?',
}
});
```
```html theme={null}
```
### Bug Fixes
* \[**Core**]: Fixed package integrity issue in v5.0.0-beta.5.
### Bug Fixes
* \[**Comments**]: Fixed page mode and multi-thread annotation ID not found error. Page mode and multi-thread comments now work as expected.
* \[**Comments**]: Fixed `updateOverlayPosition` function not triggering. Comment dialog now opens in the correct position.
* \[**Comments**]: Fixed unread status issues in inline and focused thread modes. Annotations are now marked as read when opened or clicked.
* \[**Comments**]: Fixed three-dot menu not visible in sidebar.
* \[**Comments**]: Fixed composer not being focused when opened.
* \[**Comments**]: Fixed comments navigating on click. Comments now only navigate when the navigation button is clicked.
### Bug Fixes
* \[**Comments**]: Fixed `lastUpdated` timestamp not being updated when changing context in comment annotation via SDK. Ensures context updates are properly synced to other users.
### Improvements
* \[**Core**]: Added robustness to initialization when `VeltProvider` was re-rendered multiple times over a slow network.
### Bug Fixes
* \[**Comments**]: Refactored `submitComment` method to fix resolver issue for `velt-comment-composer`. Now follows the standard comment submission flow.
* \[**Comments**]: Fixed unread status not updating correctly in bottom sheet. This was a regression in v5.
* \[**Comments**]: Fixed navigation button not working properly. This was a regression in v5.
* \[**Comments**]: Fixed disable recording option not working in `velt-comment-composer`. This was a regression in v5.
### New Features
* \[**Core**]: Added `globalStyles` option to control whether Velt's global CSS is loaded. Set to `false` to disable default styles when implementing custom theming.
```jsx theme={null}
// Using VeltProvider
{/* Your app content */}
// Using API method
const client = useVeltClient();
client.initConfig('API_KEY', {
globalStyles: false
});
```
```html theme={null}
```
* \[**Comments**]: Added `submitComment(targetElementId)` method to programmatically trigger comment submission. Enables custom buttons or keyboard shortcuts for submitting comments.
```jsx theme={null}
```html theme={null}
Send 1
Send 2
```
* \[**Comments**]: Added `placeholder` prop to customize input placeholder text in comment composer. Overrides default placeholders. [Learn more](/ui-customization/features/async/comments/standalone-components/comment-composer#placeholder)
```jsx theme={null}
```html theme={null}
* \[**Comments**]: Added `composerTextChange` event that fires when text changes in any comment composer. Enables features like auto-save drafts, character counters, or real-time validation. [Learn more](/async-collaboration/comments/customize-behavior#event-subscription)
```jsx theme={null}
// Using hook
const composerTextChangeEvent = useCommentEventCallback('composerTextChange');
useEffect(() => {
if (composerTextChangeEvent) {
console.log('Text changed:', composerTextChangeEvent.text);
}
}, [composerTextChangeEvent]);
// Using API method
const client = useVeltClient();
const commentElement = client.getCommentElement();
commentElement.on('composerTextChange').subscribe((event) => {
console.log('Text changed:', event.text);
});
```
```html theme={null}
```
### Bug Fixes
#### Comment Dialog Primitives
Released 115+ primitive components for building custom comment dialogs. Each subcomponent can now be used independently without requiring the full dialog structure.
```jsx theme={null}
// Pattern 1: ID-Based (Standalone)
```
```html theme={null}
```
**Available Components:**
* **Header/Body**: Header, Body, CloseButton
* **Thread**: ThreadCard with Avatar, Name, Time, Message, Reactions, Recordings, Reply, Options, and more
* **Composer**: Composer, ComposerInput, ComposerActionButton, ComposerAttachmentButton, ComposerRecorderButton, ComposerRecorderPlayer, ComposerFiles
* **Dropdowns**: StatusDropdown, PriorityDropdown, OptionsDropdown, CustomAnnotationDropdown (each with full sub-component breakdown)
* **Additional**: ReplyAvatars, AssigneeBanner, ResolveButton, UnresolveButton, CopyLink, DeleteButton, PrivateBanner, NavigationButton, and 90+ more
[View full documentation →](/ui-customization/features/async/comments/comment-dialog-primitives/overview) | [API Methods](/api-reference/sdk/api/api-methods#comment-dialog-primitives) | [Data Models](/api-reference/sdk/models/data-models#comment-dialog-primitives)
# Upgrade Guide
Source: https://docs.velt.dev/release-notes/version-5/upgrade-guide
## Overview
* **Key improvements in this series**:
* 115+ primitive components for building custom comment dialogs
* Each subcomponent can now be used independently without requiring the full dialog structure
* Two usage patterns: ID-Based (Standalone) and Context Wrapper
* Full control over comment dialog layout and styling
## Breaking Changes
* \[**CSS Element Names**] If you applied CSS to comment dialog element selectors, you need to update them to target the new element names.
* Replace `snippyly-comment-dialog` with `velt-comment-dialog-internal`
* Replace `app-comment-dialog-*` pattern with `velt-comment-dialog-*-internal`
* For example: `app-comment-dialog-composer` becomes `velt-comment-dialog-composer-internal`
* **Important**: Only element names need to be updated. Class names remain unchanged.
* \[**`CommentVisibilityType` Renamed Values**] The `type` field values for [`updateVisibility()`](/async-collaboration/comments/customize-behavior#updatevisibility) and [`PrivateModeConfig`](/api-reference/sdk/models/data-models#privatemodeconfig) have been renamed.
* `'organization'` → `'organizationPrivate'`
* `'self'` → `'restricted'`
**Before:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.updateVisibility({ annotationId: 'id', type: 'organization', organizationId: 'org-123' });
commentElement.updateVisibility({ annotationId: 'id', type: 'self', userIds: ['user-1'] });
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.updateVisibility({ annotationId: 'id', type: 'organization', organizationId: 'org-123' });
commentElement.updateVisibility({ annotationId: 'id', type: 'self', userIds: ['user-1'] });
```
**After:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.updateVisibility({ annotationId: 'id', type: 'organizationPrivate', organizationId: 'org-123' });
commentElement.updateVisibility({ annotationId: 'id', type: 'restricted', userIds: ['user-1'] });
```
```js theme={null}
const commentElement = Velt.getCommentElement();
commentElement.updateVisibility({ annotationId: 'id', type: 'organizationPrivate', organizationId: 'org-123' });
commentElement.updateVisibility({ annotationId: 'id', type: 'restricted', userIds: ['user-1'] });
```
## How to Upgrade
1. Search your CSS files for any element selectors using `snippyly-comment-dialog` or `app-comment-dialog-*` patterns.
2. Update the element selectors using the following replacements:
| Old Element Name | New Element Name |
| ----------------------------- | --------------------------------------- |
| `snippyly-comment-dialog` | `velt-comment-dialog-internal` |
| `app-comment-dialog-composer` | `velt-comment-dialog-composer-internal` |
| `app-comment-dialog-header` | `velt-comment-dialog-header-internal` |
| `app-comment-dialog-body` | `velt-comment-dialog-body-internal` |
3. Deploy the latest version of the Velt SDK to your product.
If you are only using class selectors (e.g., `.comment-dialog-composer`), no changes are required.
# Generating Auth Tokens
Source: https://docs.velt.dev/security/auth-tokens
Open the Velt Console at [console.velt.dev](https://console.velt.dev)
Under the Auth Token section, click on Generate Token button:
# Content security policy
Source: https://docs.velt.dev/security/content-security-policy
## Whitelisting Rules for Content Security Policy (CSP)
If you have a Content Security Policy (CSP) enabled in your app configuration, ensure that the following URLs are whitelisted:
### script-src
* `*.velt.dev`
* `*.api.velt.dev`
* `*.firebaseio.com`
* `*.googleapis.com`
* `wss://*.firebaseio.com`
* `wss://*.firebasedatabase.app`
### connect-src
* `*.velt.dev`
* `*.api.velt.dev`
* `*.firebaseio.com`
* `*.googleapis.com`
* `wss://*.firebaseio.com`
* `wss://*.firebasedatabase.app`
### img-src
* `storage.googleapis.com`
* `firebasestorage.googleapis.com`
### media-src
* `storage.googleapis.com`
* `firebasestorage.googleapis.com`
# JWT Tokens
Source: https://docs.velt.dev/security/jwt-tokens
Generate JWT Tokens for additional security
## Overview
`JWT Tokens` is an optional feature to add additional authentication security to our `client.identify()` method to prevent user impersonation.
Go to [https://console.velt.dev](https://console.velt.dev/dashboard/config/general) and enable the toggle for `Require JWT Token`. The toggle is listed at the very bottom of the page.
JWT Tokens won't work unless you enable it in your console.
Create a server endpoint that will be used to generate and send a `JWT Token` to the client.
Example server endpoint code:
```jsx theme={null}
app.get('/generate-velt-jwt-token', async (req,res) => {
const veltAuthToken = await generateVeltAuthToken(req.body.userId)
res.json(veltAuthToken)
})
```
In your server endpoint, call our `https://api.velt.dev/v1/auth/token/get` endpoint to generate a `JWT Token`.
Example server code:
```jsx theme={null}
async function generateVeltAuthToken(userId: string) {
const url = "https://api.velt.dev/v1/auth/token/get";
const body = {
data: {
userId: userId, // Unique user id of your user
apiKey: "YOUR_VELT_API_KEY",
authToken: "YOUR_CLIENT_AUTH_TOKEN", // Get this token from console.velt.dev
userProperties: {
isAdmin: true, // Set to true if you want to set user as admin
organizationId: "YOUR_ORGANIZATION_ID", // If organizationId is provided here then we will validate it with the organizationId used in the identify call
email: "USER_EMAIL", // If email is provided here then we will validate it with the email used in the identify call
}
},
};
try {
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(body),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
return data?.result?.data?.token;
} catch (error) {
console.error("Error:", error);
}
}
```
### Request Body:
To get your Auth Token that is required for your request body, [read here](/security/auth-tokens).
| Field | Required | Description |
| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey` | Yes | Velt API Key |
| `authToken ` | Yes | Auth Token from the Velt console |
| `userId ` | Yes | Unique user id of the user |
| `userProperties.organizationId` | Yes | The ogranizationId should match the organizationId used in the `identify` call. |
| `userProperties.isAdmin` | No | Set to `true` if you want to set user as `admin`. This is the only way to set a user as an `admin` User. Please do not set this property in the `identify` call as this will unset the `isAdmin` property. |
| `userProperties.email` | No | If `email` is provided, it will be validated with the `email` used in the identify call. Recommended if you are setting email. |
```jsx theme={null}
{
"data": {
"apiKey": "YOUR_API_KEY", //Velt API Key
"authToken": "YOUR_AUTH_TOKEN", // Auth Token from the Velt console
"userId": "yourUserId", // unique user id of the user you are generating a JWT Token for
"userProperties": {
isAdmin: true, // Set to true if you want to set user as admin
organizationId: "YOUR_ORGANIZATION_ID", // If organizationId is provided here then we will validate it with the organizationId used in the identify call
email: "USER_EMAIL", // If email is provided here then we will validate it with the email used in the identify call
}
}
}
```
### Success Response:
```jsx theme={null}
{
"result": {
"status": "success",
"message": "Token generated successfully.",
"data": {
"token": "YOUR_JWT_TOKEN"
}
}
}
```
### Failure Response:
```jsx theme={null}
{
"error": {
"message": "Auth token not found.",
"status": "INVALID_ARGUMENT"
}
}
```
Make sure to generate the JWT Token from your server, not your client. Otherwise, your JWT Token will not be secure.
Call your server endpoint from your client to pass your `JWT Token` to your client.
```jsx theme={null}
const yourJWTToken = await callToYourServerToGetJWTToken(userId)
```
Once the JWT Token is generated, you can pass it into the `client.identify()` method. The `client.identify()` method has an optional second parameter that takes in a configuration object that includes the `JWT Token` as a field.
```jsx theme={null}
const yourJWTToken = await callToYourServerToGetJWTToken(userId)
client.identify(user, {
authToken: yourJWTToken,
});
```
The JWT token has the following lifecycle:
* Tokens expire after 48 hours from generation
* When a token expires, Velt emits a `token_expired` error event
* Your application should:
1. Subscribe to the `error` event to detect expired tokens
2. Generate a new token via your server endpoint when expiry occurs
3. Call `identify()` with the fresh token to re-authenticate the user
**Using Hook:**
```jsx theme={null}
const errorEvent = useVeltEventCallback('error');
useEffect(() => {
if (errorEvent?.code === "token_expired") {
// Generate new Velt Auth Token
// Call identify with the new token
}
}, [errorEvent]);
```
**Using API:**
```js theme={null}
client.on('error').subscribe((error) => {
if (error?.code === "token_expired") {
// Generate new Velt Auth Token
// Call identify with the new token
}
});
```
```js theme={null}
Velt.on('error').subscribe((error) => {
if (error?.code === "token_expired") {
// Generate new Velt Auth Token
// Call identify with the new token
}
});
```
You are all done! Now you have added an additional level of security with `JWT Tokens`.
```jsx Server Code theme={null}
import express from 'express';
const app = express();
const PORT = 8080;
async function generateVeltAuthToken(userId) {
const url = "https://api.velt.dev/v1/auth/token/get";
const body = {
data: {
userId: userId, // Unique user id of your user
apiKey: "YOUR_VELT_API_KEY",
authToken: "YOUR_CLIENT_AUTH_TOKEN", // Get this token from console.velt.dev
userProperties: {
isAdmin: true, // Set to true if you want to set user as admin
organizationId: "YOUR_ORGANIZATION_ID", // If organizationId is provided here then we will validate it with the organizationId used in the identify call
email: "USER_EMAIL", // If email is provided here then we will validate it with the email used in the identify call
}
},
};
try {
const response = await fetch(url, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(body),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
return data?.result?.data?.token;
} catch (error) {
console.error("Error:", error);
}
}
app.get('/generate-velt-jwt-token', async (req,res) => {
const veltAuthToken = await generateVeltAuthToken(req.body.userId)
res.json(veltAuthToken)
})
app.listen(PORT, () => {
console.log(`JWT Server listening on port ${PORT}`);
});
```
```jsx Client Code theme={null}
import { useVeltClient } from "@veltdev/react";
import { useEffect, useState } from "react";
export default function YourAuthComponent() {
let [user, setUser] = useState(null);
const userService = () => {
return {
uid: "user1",
displayName: "User 1",
email: "user1@velt.dev",
photoURL: "https://i.pravatar.cc/301",
organizationId: "YOUR_ORGANIZATION_ID"
};
};
// Fetch user data from user service
let yourAuthenticatedUser = userService();
// Get the Velt Client
const { client } = useVeltClient();
// Call to your Server to get JWT Token
async function callToYourServerToGetJWTToken(userId){
let baseUrl = "your-server.com"
let result = await fetch(`${baseUrl}/generate-velt-jwt-token`, {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify({
userId:userId
}),
})
let data = await result.json();
return data;
}
useEffect(() => {
const initVelt = async () => {
if (client && yourAuthenticatedUser) {
const { uid, displayName, email, photoURL } = yourAuthenticatedUser;
// Create the Velt user object
const user = {
userId: uid,
name: displayName,
email: email,
photoUrl: photoURL,
organizationId: "YOUR_ORGANIZATION_ID"
};
//Get JWT Token from your server
const yourJWTToken = await callToYourServerToGetJWTToken(user.userId)
// Identify the user with the Velt client, with JWT Token
await client.identify(user, {
authToken: yourJWTToken,
});
setUser(user);
}
};
initVelt().catch(console.error);
}, [client]);
return User: {user?.userId}
;
}
```
# Proxy Server
Source: https://docs.velt.dev/security/proxy-server
You can route Velt SDK events and API calls via a proxy to your own domain. This means you will have most Velt-related network calls branded to your domain.
There are two main aspects to this:
1. Proxying the Velt SDK
2. Proxying Velt API calls
### Proxying the Velt SDK
To serve the Velt SDK via your own proxy server (e.g., `nginx`) instead of Velt's servers, provide your proxy's base URL.
* Velt will automatically append `/lib/sdk@[VERSION_NUMBER]/velt.js` to your `proxyDomain` to determine the full URL for fetching the SDK.
* If `proxyDomain` is `https://cdn.yourdomain.com`, the SDK will be loaded from `https://cdn.yourdomain.com/lib/sdk@[VERSION_NUMBER]/velt.js`.
* Your proxy server must be configured to to forward requests from `[your_proxyDomain]` to `https://cdn.velt.dev` without any modifications to headers or any other content.
```jsx theme={null}
```jsx theme={null}
const client = await initVelt('YOUR_API_KEY', {
proxyDomain: 'https://cdn.yourdomain.com',
});
```
### Proxying Velt API calls
To serve the Velt APIs via your own proxy server (e.g., `nginx`) instead of Velt's servers, provide your proxy's base URL.
* If `apiProxyDomain` is `https://api.yourdomain.com`, the APIs will be loaded from `https://api.yourdomain.com`.
* Your proxy server should be configured to forward requests from `[your_apiProxyDomain]` to `https://api.velt.dev` without any modifications to headers or any other content.
```jsx theme={null}
```jsx theme={null}
const client = await initVelt('YOUR_API_KEY', {
apiProxyDomain: 'https://api.yourdomain.com'
});
```
### Integrity Check
To ensure the integrity of the Velt SDK, especially when served via a proxy, Velt leverages Subresource Integrity (SRI).
Subresource Integrity (SRI) is a security feature that enables browsers to verify that resources they fetch (for example, from a CDN or your proxy server) are delivered without unexpected manipulation.
* Default: `false`
```jsx theme={null}
```
```js theme={null}
let client = await initVelt("YOUR_API_KEY", {
integrity: true,
});
```
# Supported Regions
Source: https://docs.velt.dev/security/supported-regions
Persistent features like Comments, Notifications, Recording, etc. are available in the following regions:
## North America
| Region name | Region description |
| ----------------------- | ------------------ |
| us-west1 | Oregon |
| us-west2 | Los Angeles |
| us-west3 | Salt Lake City |
| us-west4 | Las Vegas |
| us-central1 | Iowa |
| northamerica-northeast1 | Montréal |
| northamerica-northeast2 | Toronto |
| northamerica-south1 | Queretaro |
| us-east1 | South Carolina |
| us-east4 | Northern Virginia |
| us-east5 | Columbus |
| us-south1 | Dallas |
## South America
| Region name | Region description |
| ------------------ | ------------------ |
| southamerica-west1 | Santiago |
| southamerica-east1 | São Paulo |
## Europe
| Region name | Region description |
| ----------------- | ------------------ |
| europe-west2 | London |
| europe-west1 | Belgium |
| europe-west4 | Netherlands |
| europe-west8 | Milan |
| europe-southwest1 | Madrid |
| europe-west9 | Paris |
| europe-west12 | Turin |
| europe-west10 | Berlin |
| europe-west3 | Frankfurt |
| europe-north1 | Finland |
| europe-north2 | Stockholm |
| europe-central2 | Warsaw |
| europe-west6 | Zürich |
## Middle East
| Region name | Region description |
| ----------- | ------------------ |
| me-central1 | Doha |
| me-central2 | Dammam |
| me-west1 | Tel Aviv |
## Asia
| Region name | Region description |
| --------------- | ------------------ |
| asia-south1 | Mumbai |
| asia-south2 | Delhi |
| asia-southeast1 | Singapore |
| asia-southeast2 | Jakarta |
| asia-east2 | Hong Kong |
| asia-east1 | Taiwan |
| asia-northeast1 | Tokyo |
| asia-northeast2 | Osaka |
| asia-northeast3 | Seoul |
## Australia
| Region name | Region description |
| -------------------- | ------------------ |
| australia-southeast1 | Sydney |
| australia-southeast2 | Melbourne |
## Africa
| Region name | Region description |
| ------------- | ------------------ |
| africa-south1 | Johannesburg |
## Multi-Regions
| Multi-region name | Multi-region description | Read-Write regions | Witness region |
| ----------------- | ------------------------ | ------------------------------------------------------------- | ------------------------- |
| eur3 | Europe | europe-west1 (Belgium), europe-west4 (Netherlands) | europe-north1 (Finland) |
| nam5 | United States | us-central1 (Iowa), us-central2 (Oklahoma—private GCP region) | us-east1 (South Carolina) |
# Attachments
Source: https://docs.velt.dev/self-host-data/attachments
Self-host your comments file attachments data while using Velt's components. Keep attachment storage on your infrastructure with minimal metadata stored on Velt servers.
* This is currently only compatible with `setDocuments` method.
* Ensure that the data providers are set prior to calling `identify` method.
* The data provider methods must return the correct status code (e.g. 200 for success, 500 for errors) and success boolean in the response object. This ensures proper error handling and retries.
# Overview
Velt supports self-hosting your comments file attachments data:
* Attachments can be stored on your own infrastructure, with only necessary identifiers on Velt servers.
* Velt Components automatically hydrate attachment data in the frontend by fetching from your configured data provider.
* This gives you full control over attachment data while maintaining the file attachment features.
# How does it work?
When users upload or delete attachments:
1. The SDK uses your configured [`AttachmentDataProvider`](/api-reference/sdk/models/data-models#attachmentdataprovider) to handle storage
2. Your data provider implements two key methods:
* `save`: Stores the file and returns its URL
* `delete`: Removes the file from storage
**The process works as follows:**
When an attachment operation occurs:
1. The SDK first attempts to save/delete the file on your storage infrastructure
2. If successful:
* The SDK updates Velt's servers with minimal metadata
* The [`PartialComment`](/api-reference/sdk/models/data-models#partialcomment) object is updated to reference the attachment including the attachment url, name and metadata.
* When the comment is saved, this information is stored on your end.
* Velt servers only store necessary identifiers, not the actual files or URLs
3. If the operation fails, no changes are made to Velt's servers and the operation is retried if you have configured retries.
# Implementation Approaches
You can implement attachment self-hosting using either of these approaches:
1. **Endpoint based**: Provide endpoint URLs and let the SDK handle HTTP requests
2. **Function based**: Implement `save` and `delete` methods yourself
Both approaches are fully backward compatible and can be used together.
| Feature | Function based | Endpoint based |
| ------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Best For** | Complex setups requiring middleware logic, dynamic headers, or transformation before sending | Standard REST APIs where you just need to pass the request "as-is" to the backend |
| **Implementation** | You write the `fetch()` or `axios` code | You provide the `url` string and `headers` object |
| **Flexibility** | High | Medium |
| **Speed** | Medium | High |
## Endpoint based DataProvider
Instead of implementing custom methods, you can configure endpoints directly and let the SDK handle HTTP requests.
Unlike comments and reactions, attachment upload uses `multipart/form-data` format to avoid base64 conversion overhead. The browser automatically manages the Content-Type header with the proper boundary parameter.
### saveConfig
Config-based endpoint for saving attachments. The SDK automatically makes HTTP POST requests with multipart/form-data.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request format: `multipart/form-data` with two fields:
* `file`: File object (binary)
* `request`: JSON string containing [`SaveAttachmentResolverRequest`](/api-reference/sdk/models/data-models#saveattachmentresolverrequest)
* Response format: [`ResolverResponse`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const attachmentResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/attachments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
// Note: Content-Type is automatically set by browser
}
};
const attachmentDataProvider = {
config: attachmentResolverConfig
};
```
```js theme={null}
const attachmentResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/attachments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
// Note: Content-Type is automatically set by browser
}
};
const attachmentDataProvider = {
config: attachmentResolverConfig
};
Velt.setDataProviders({ attachment: attachmentDataProvider });
```
```javascript theme={null}
// Backend handler for /api/velt/attachments/save
const file = req.file;
const request = JSON.parse(req.body.request);
// Use metadata to organize files
const { metadata } = request;
const { organizationId, documentId } = metadata;
const key = `attachments/${organizationId}/${documentId}/${Date.now()}-${file.originalname}`;
await s3Client.send(new PutObjectCommand({
Bucket: process.env.S3_BUCKET,
Key: key,
Body: file.buffer,
ContentType: file.mimetype
}));
const url = `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`;
// Return response in required format
res.json({ data: { url }, success: true, statusCode: 200 });
```
### deleteConfig
Config-based endpoint for deleting attachments. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`DeleteAttachmentResolverRequest`](/api-reference/sdk/models/data-models#deleteattachmentresolverrequest)
* Response format: [`ResolverResponse`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const attachmentResolverConfig = {
deleteConfig: {
url: 'https://your-backend.com/api/velt/attachments/delete',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
}
}
};
const attachmentDataProvider = {
config: attachmentResolverConfig
};
```
```js theme={null}
const attachmentResolverConfig = {
deleteConfig: {
url: 'https://your-backend.com/api/velt/attachments/delete',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
}
}
};
const attachmentDataProvider = {
config: attachmentResolverConfig
};
Velt.setDataProviders({ attachment: attachmentDataProvider });
```
```javascript theme={null}
// Backend handler for /api/velt/attachments/delete
const { url } = req.body;
// Delete file from S3
const key = url.split('.s3.amazonaws.com/')[1];
await s3Client.send(new DeleteObjectCommand({
Bucket: process.env.S3_BUCKET,
Key: key
}));
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
### Endpoint based Complete Example
```jsx theme={null}
const attachmentResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/attachments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
deleteConfig: {
url: 'https://your-backend.com/api/velt/attachments/delete',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
}
},
resolveTimeout: 5000,
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const attachmentDataProvider = {
config: attachmentResolverConfig
};
```
```js theme={null}
const attachmentResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/attachments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
deleteConfig: {
url: 'https://your-backend.com/api/velt/attachments/delete',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer YOUR_TOKEN'
}
},
resolveTimeout: 5000,
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const attachmentDataProvider = {
config: attachmentResolverConfig
};
Velt.setDataProviders({ attachment: attachmentDataProvider });
```
## Function based DataProvider
Implement custom methods to handle data operations yourself.
### save
Save attachments to your storage backend. Return the url with a success or error response. On error we will retry.
* Param: [`SaveAttachmentResolverRequest`](/api-reference/sdk/models/data-models#saveattachmentresolverrequest)
* Return: [`Promise>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx React / Next.js theme={null}
const saveAttachmentsToDB = async (request) => {
const formData = new FormData();
formData.append('file', request.file);
formData.append('metadata', JSON.stringify(request.metadata));
const response = await fetch('/api/velt/attachments/save', {
method: 'POST',
body: formData
});
return await response.json();
};
const attachmentDataProvider = {
save: saveAttachmentsToDB,
};
```
```js Other Frameworks theme={null}
const saveAttachmentsToDB = async (request) => {
const formData = new FormData();
formData.append('file', request.file);
formData.append('metadata', JSON.stringify(request.metadata));
const response = await fetch('/api/velt/attachments/save', {
method: 'POST',
body: formData
});
return await response.json();
};
const attachmentDataProvider = {
save: saveAttachmentsToDB,
};
Velt.setDataProviders({ attachment: attachmentDataProvider });
```
```javascript theme={null}
const file = req.file;
const metadata = JSON.parse(req.body.metadata);
// Use metadata to organize files by organization and document
const { organizationId, documentId } = metadata;
const key = `attachments/${organizationId}/${documentId}/${Date.now()}-${file.originalname}`;
await s3Client.send(new PutObjectCommand({
Bucket: process.env.S3_BUCKET,
Key: key,
Body: file.buffer,
ContentType: file.mimetype
}));
const url = `https://${process.env.S3_BUCKET}.s3.amazonaws.com/${key}`;
// Return response in required format
res.json({ data: { url }, success: true, statusCode: 200 });
```
### delete
Delete attachments from your storage backend. Return a success or error response. On error we will retry.
* Param: [`DeleteAttachmentResolverRequest`](/api-reference/sdk/models/data-models#deleteattachmentresolverrequest)
* Return: [`Promise>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx React / Next.js theme={null}
const deleteAttachmentsFromDB = async (request) => {
const response = await fetch('/api/velt/attachments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const attachmentDataProvider = {
delete: deleteAttachmentsFromDB,
};
```
```js Other Frameworks theme={null}
const deleteAttachmentsFromDB = async (request) => {
const response = await fetch('/api/velt/attachments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const attachmentDataProvider = {
delete: deleteAttachmentsFromDB,
};
Velt.setDataProviders({ attachment: attachmentDataProvider });
```
```javascript theme={null}
const { url } = req.body;
// Delete file from S3
const key = url.split('.s3.amazonaws.com/')[1];
await s3Client.send(new DeleteObjectCommand({
Bucket: process.env.S3_BUCKET,
Key: key
}));
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
### config
Configuration for the attachment data provider.
* Type: [`ResolverConfig`](/api-reference/sdk/models/data-models#resolverconfig). Relevant properties:
* `resolveTimeout`: Timeout duration (in milliseconds) for resolver operations
* `saveRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for save operations.
* `deleteRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for delete operations.
```jsx theme={null}
const attachmentResolverConfig = {
resolveTimeout: 5000,
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
```
### Function based Complete Example
```jsx theme={null}
const saveAttachmentsToDB = async (request) => {
const formData = new FormData();
formData.append('file', request.file);
formData.append('metadata', JSON.stringify(request.metadata));
const response = await fetch('/api/velt/attachments/save', {
method: 'POST',
body: formData
});
return await response.json();
};
const deleteAttachmentsFromDB = async (request) => {
const response = await fetch('/api/velt/attachments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const attachmentResolverConfig = {
resolveTimeout: 5000,
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const attachmentDataProvider = {
save: saveAttachmentsToDB,
delete: deleteAttachmentsFromDB,
config: attachmentResolverConfig
};
```
```js theme={null}
const saveAttachmentsToDB = async (request) => {
const formData = new FormData();
formData.append('file', request.file);
formData.append('metadata', JSON.stringify(request.metadata));
const response = await fetch('/api/velt/attachments/save', {
method: 'POST',
body: formData
});
return await response.json();
};
const deleteAttachmentsFromDB = async (request) => {
const response = await fetch('/api/velt/attachments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const attachmentResolverConfig = {
resolveTimeout: 5000,
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const attachmentDataProvider = {
save: saveAttachmentsToDB,
delete: deleteAttachmentsFromDB,
config: attachmentResolverConfig
};
Velt.setDataProviders({ attachment: attachmentDataProvider });
```
# Sample Data
```json theme={null}
{
"annotationId": "ANNOTATION_ID",
"metadata": {
"apiKey": "API_KEY",
"documentId": "DOCUMENT_ID",
"organizationId": "ORGANIZATION_ID"
},
"comments": {
"184639": {
"commentId": 184639,
"commentHtml": "Hello
",
"commentText": "Hello",
"from": {
"userId": "USER_ID"
}
},
"743772": {
"commentId": 743772,
"attachments": {
"758336": {
"url": "https://your-bucket.s3.amazonaws.com/attachments/API_KEY/ATTACHMENT_ID.png",
"name": "image.png",
"attachmentId": 758336
}
},
"from": {
"userId": "USER_ID"
}
}
}
}
```
When an attachment is added, the comment object is updated with the attachment details including the URL and name from your storage.
```json theme={null}
{
"attachmentId": 758336,
"metadata": {
"organizationId": "ORGANIZATION_ID",
"documentId": "DOCUMENT_ID",
"apiKey": "API_KEY"
},
"file": "https://your-bucket.s3.amazonaws.com/attachments/API_KEY/ATTACHMENT_ID.png",
"mimeType": "image/png",
"name": "image.png"
}
```
This is a separate attachments collection on your database that stores the full attachment details.
```json theme={null}
{
"annotationId": "ANNOTATION_ID",
"comments": [
{
"commentId": 184639,
"from": {
"userId": "USER_ID"
},
"isCommentResolverUsed": true,
"isCommentTextAvailable": true,
"attachments": []
},
{
"commentId": 743772,
"from": {
"userId": "USER_ID"
},
"isCommentResolverUsed": true,
"attachments": [
{
"attachmentId": 758336,
"bucketPath": "API_KEY/organizations/ORG_ID/docs/DOC_ID/comments/ANNOTATION_ID/758336_image.png",
"isAttachmentResolverUsed": true,
"mimeType": "image/png",
"size": 289870,
"type": "png"
}
]
}
],
"metadata": {
"apiKey": "API_KEY",
"documentId": "DOCUMENT_ID",
"organizationId": "ORGANIZATION_ID"
}
}
```
Only attachment identifiers, bucket path, and file metadata (mimeType, size, type) are stored on Velt servers. The actual file URL and name remain on your storage infrastructure.
# Debugging
You can subscribe to `dataProvider` events to monitor and debug save and delete operations.
You can also use the [Velt Chrome DevTools extension](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl) to inspect and debug your Velt implementation.
```jsx theme={null}
import { useVeltClient } from '@veltdev/react';
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const subscription = client.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
});
return () => subscription?.unsubscribe();
}, [client]);
```
```javascript theme={null}
const subscription = Velt.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
});
// Unsubscribe when done
subscription?.unsubscribe();
```
# Comments
Source: https://docs.velt.dev/self-host-data/comments
Self-host your comments data while using Velt's components. Keep comment storage on your infrastructure with minimal metadata stored on Velt servers.
* This is currently only compatible with `setDocuments` method.
* Ensure that the data providers are set prior to calling `identify` method.
* The data provider methods must return the correct status code (e.g. 200 for success, 500 for errors) and success boolean in the response object. This ensures proper error handling and retries.
* If you are using REST API to add or update comments, ensure that you set `isCommentResolverUsed` and `isCommentTextAvailable` fields in the request object. [Learn more](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations)
# Overview
Velt supports self-hosting your comments and related data:
* Comments can be stored on your own infrastructure, with only necessary identifiers on Velt servers.
* Velt Components automatically hydrate comment data in the frontend by fetching from your configured data provider.
* This gives you full control over comment data while maintaining all Velt collaboration features.
* This automatically also ensures that the in-app notifications content is not stored on Velt servers. The content is generated using the comments data in the frontend.
Email notifications via Velt's SendGrid integration are not available when you self-host comment content. Since the content lives on your infrastructure, Velt cannot construct and send emails via the sendgrid integration. Instead, use [Webhooks](/webhooks/basic) to receive events (e.g., mentions, replies), fetch the relevant comment/notification content from your database, and send emails from your own email provider.
# How does it work?
* When comments are created, updated, deleted or requested, the SDK uses your configured [`CommentAnnotationDataProvider`](/api-reference/sdk/models/data-models#commentannotationdataprovider) to handle storage and retrieval
* The data provider implements `get`, `save`, and `delete` methods to interact with your database
* Velt handles the data mapping and realtime synchronization while delegating persistence of actual content to your infrastructure
* The data provider works at the Comment Annotation (Thread) level not at the individual Comment (Message) level.
* For write requests (save, delete), the operation is first performed on your database and only if we get a success response, the SDK will perform the operation on the Velt server. If the operation fails on your database, the SDK will not perform the operation on the Velt server.
* You can configure retries, timeouts, etc. for the data provider.
# Implementation Approaches
You can implement comment self-hosting using either of these approaches:
1. **Endpoint based**: Provide endpoint URLs and let the SDK handle HTTP requests
2. **Function based**: Implement `get`, `save`, and `delete` methods yourself
Both approaches are fully backward compatible and can be used together.
| Feature | Function based | Endpoint based |
| ------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Best For** | Complex setups requiring middleware logic, dynamic headers, or transformation before sending | Standard REST APIs where you just need to pass the request "as-is" to the backend |
| **Implementation** | You write the `fetch()` or `axios` code | You provide the `url` string and `headers` object |
| **Flexibility** | High | Medium |
| **Speed** | Medium | High |
## Endpoint based DataProvider
Instead of implementing custom methods, you can configure endpoints directly and let the SDK handle HTTP requests.
### getConfig
Config-based endpoint for fetching comments. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`GetCommentResolverRequest`](/api-reference/sdk/models/data-models#getcommentresolverrequest)
* Response format: [`ResolverResponse>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const commentResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/comments/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const commentDataProvider = {
config: commentResolverConfig
};
```
```js theme={null}
const commentResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/comments/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const commentDataProvider = {
config: commentResolverConfig
};
Velt.setDataProviders({ comment: commentDataProvider });
```
### saveConfig
Config-based endpoint for saving comments. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`SaveCommentResolverRequest`](/api-reference/sdk/models/data-models#savecommentresolverrequest)
* Response format: [`ResolverResponse`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const commentResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/comments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const commentDataProvider = {
config: commentResolverConfig
};
```
```js theme={null}
const commentResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/comments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const commentDataProvider = {
config: commentResolverConfig
};
Velt.setDataProviders({ comment: commentDataProvider });
```
### deleteConfig
Config-based endpoint for deleting comments. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`DeleteCommentResolverRequest`](/api-reference/sdk/models/data-models#deletecommentresolverrequest)
* Response format: [`ResolverResponse`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const commentResolverConfig = {
deleteConfig: {
url: 'https://your-backend.com/api/velt/comments/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const commentDataProvider = {
config: commentResolverConfig
};
```
```js theme={null}
const commentResolverConfig = {
deleteConfig: {
url: 'https://your-backend.com/api/velt/comments/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const commentDataProvider = {
config: commentResolverConfig
};
Velt.setDataProviders({ comment: commentDataProvider });
```
### Endpoint based Complete Example
```jsx theme={null}
const commentResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/comments/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
saveConfig: {
url: 'https://your-backend.com/api/velt/comments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
deleteConfig: {
url: 'https://your-backend.com/api/velt/comments/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const commentDataProvider = {
config: commentResolverConfig
};
```
```js theme={null}
const commentResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/comments/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
saveConfig: {
url: 'https://your-backend.com/api/velt/comments/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
deleteConfig: {
url: 'https://your-backend.com/api/velt/comments/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const commentDataProvider = {
config: commentResolverConfig
};
Velt.setDataProviders({ comment: commentDataProvider });
```
## Function based DataProvider
Implement custom methods to handle data operations yourself.
### get
Method to fetch comments from your database. On error we will retry.
* Param: [`GetCommentResolverRequest`](/api-reference/sdk/models/data-models#getcommentresolverrequest)
* Return: [`Promise>>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx React / Next.js theme={null}
const fetchCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentDataProvider = {
get: fetchCommentsFromDB,
};
```
```js Other Frameworks theme={null}
const fetchCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentDataProvider = {
get: fetchCommentsFromDB,
};
Velt.setDataProviders({ comment: commentDataProvider });
```
```javascript theme={null}
// Build query from request
const { commentAnnotationIds, documentIds, organizationId } = req.body;
const query = {};
if (commentAnnotationIds?.length) {
query.annotationId = { $in: commentAnnotationIds };
}
if (documentIds?.length) {
query.documentId = { $in: documentIds };
}
if (organizationId) {
query.organizationId = organizationId;
}
const annotations = await collection.find(query).toArray();
// Convert to Record
const result = {};
for (const annotation of annotations) {
result[annotation.annotationId] = annotation;
}
// Return response in required format
res.json({ data: result, success: true, statusCode: 200 });
```
```javascript theme={null}
// Build parameterized query
const { commentAnnotationIds, documentIds, organizationId } = req.body;
const conditions = [];
const values = [];
let paramIndex = 1;
if (commentAnnotationIds?.length) {
conditions.push(`annotation_id = ANY($${paramIndex++})`);
values.push(commentAnnotationIds);
}
if (documentIds?.length) {
conditions.push(`document_id = ANY($${paramIndex++})`);
values.push(documentIds);
}
if (organizationId) {
conditions.push(`organization_id = $${paramIndex++}`);
values.push(organizationId);
}
const whereClause = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
const { rows } = await client.query(
`SELECT annotation_id, data FROM comment_annotations ${whereClause}`,
values
);
// Convert to Record
const result = {};
for (const row of rows) {
result[row.annotation_id] = row.data;
}
// Return response in required format
res.json({ data: result, success: true, statusCode: 200 });
```
### save
Save comments to your database. Return a success or error response. On error we will retry.
* Param: [`SaveCommentResolverRequest`](/api-reference/sdk/models/data-models#savecommentresolverrequest)
* Note in the `SaveCommentResolverRequest` object, you will receive [the event name](/api-reference/sdk/models/data-models#resolveractions) that triggered the save.
* Return: [`Promise>`](/api-reference/sdk/models/data-models#resolverresponse)
If you are using REST API to add or update comments, ensure that you set `isCommentResolverUsed` and `isCommentTextAvailable` fields in the request object. [Learn more](/api-reference/rest-apis/v2/comments-feature/comment-annotations/add-comment-annotations)
```jsx React / Next.js theme={null}
const saveCommentsToDB = async (request) => {
const response = await fetch('/api/velt/comments/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentDataProvider = {
save: saveCommentsToDB,
};
```
```js Other Frameworks theme={null}
const saveCommentsToDB = async (request) => {
const response = await fetch('/api/velt/comments/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentDataProvider = {
save: saveCommentsToDB,
};
Velt.setDataProviders({ comment: commentDataProvider });
```
```javascript theme={null}
const { annotations, context } = req.body;
// Bulk upsert annotations
const operations = Object.entries(annotations).map(([id, annotation]) => ({
updateOne: {
filter: { annotationId: id },
update: {
$set: {
...annotation,
annotationId: id,
documentId: context?.documentId || annotation.documentId,
organizationId: context?.organizationId || annotation.organizationId,
}
},
upsert: true
}
}));
if (operations.length > 0) {
await collection.bulkWrite(operations);
}
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
```javascript theme={null}
const { annotations, context } = req.body;
// Transaction-based upsert
await client.query('BEGIN');
for (const [id, annotation] of Object.entries(annotations)) {
const data = { ...annotation, annotationId: id };
await client.query(
`INSERT INTO comment_annotations (annotation_id, document_id, organization_id, data, updated_at)
VALUES ($1, $2, $3, $4, NOW())
ON CONFLICT (annotation_id)
DO UPDATE SET data = EXCLUDED.data, updated_at = NOW()`,
[id, annotation.documentId, annotation.organizationId, JSON.stringify(data)]
);
}
await client.query('COMMIT');
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
### delete
Delete comments from your database. Return a success or error response. On error we will retry.
* Param: [`DeleteCommentResolverRequest`](/api-reference/sdk/models/data-models#deletecommentresolverrequest)
* Return: [`Promise>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx React / Next.js theme={null}
const deleteCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentDataProvider = {
delete: deleteCommentsFromDB,
};
```
```js Other Frameworks theme={null}
const deleteCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentDataProvider = {
delete: deleteCommentsFromDB,
};
Velt.setDataProviders({ comment: commentDataProvider });
```
```javascript theme={null}
const { annotationId } = req.body;
await collection.deleteOne({ annotationId });
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
```javascript theme={null}
const { annotationId } = req.body;
await client.query(
'DELETE FROM comment_annotations WHERE annotation_id = $1',
[annotationId]
);
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
### config
Configuration for the comment data provider.
* Type: [`ResolverConfig`](/api-reference/sdk/models/data-models#resolverconfig). Relevant properties:
* `resolveTimeout`: Timeout duration (in milliseconds) for resolver operations
* `getRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for get operations.
* `saveRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for save operations.
* `deleteRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for delete operations.
```jsx theme={null}
const commentResolverConfig = {
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
```
### Function based Complete Example
```jsx theme={null}
const fetchCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const saveCommentsToDB = async (request) => {
const response = await fetch('/api/velt/comments/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const deleteCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentResolverConfig = {
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const commentDataProvider = {
get: fetchCommentsFromDB,
save: saveCommentsToDB,
delete: deleteCommentsFromDB,
config: commentResolverConfig
};
```
```js theme={null}
const fetchCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const saveCommentsToDB = async (request) => {
const response = await fetch('/api/velt/comments/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const deleteCommentsFromDB = async (request) => {
const response = await fetch('/api/velt/comments/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const commentResolverConfig = {
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const commentDataProvider = {
get: fetchCommentsFromDB,
save: saveCommentsToDB,
delete: deleteCommentsFromDB,
config: commentResolverConfig
};
Velt.setDataProviders({ comment: commentDataProvider });
```
# Triggering Email Notifications when Self-Hosting
When you self-host content, use Webhooks to trigger emails from your own system:
Subscribe to comment-related events (e.g., user mentions, replies). See [Webhooks](/webhooks/advanced).
Your server receives the webhook event. Use IDs from the payload (e.g., `annotationId`, `commentId`) to query your own comment and notification content from your database via your Data Provider.
Combine the webhook event context with the self-hosted content to build the subject, body, and list of recipients (e.g., mentioned users).
Use your own email service (SendGrid under your account, SES, Postmark, etc.) to send the email.
**Example:**
```json cURL theme={null}
POST /webhooks/velt HTTP/1.1
Content-Type: application/json
{
"webhookId": "webhook-123",
"actionType": "newlyAdded",
"commentAnnotation": {
"annotationId": "ANNOTATION_ID",
"metadata": {
"documentId": "DOC_ID",
"apiKey": "API_KEY"
}
},
"targetComment": {
"commentId": 123,
"from": {
"userId": "USER_1"
}
},
"actionUser": {
"userId": "USER_1",
"name": "John Doe",
"email": "john@example.com"
},
"metadata": {
"apiKey": "API_KEY",
"documentId": "DOC_ID",
"pageInfo": {
"url": "https://app.example.com/doc/123"
}
},
"notificationSource": "comment",
"platform": "sdk"
}
```
```javascript Node.js theme={null}
// Pseudocode: handle webhook, fetch content, send email
app.post('/webhooks/velt', async (req, res) => {
const evt = req.body;
const annotationId = evt?.commentAnnotation?.annotationId;
const targetCommentId = evt?.targetComment?.commentId;
// 1) Fetch self-hosted content
const annotation = await db.commentAnnotations.get(annotationId);
const targetComment = annotation?.comments?.[targetCommentId];
// 2) Resolve recipients (e.g., mentioned users)
const recipients = await resolveMentionedUsers(annotation, targetComment);
// 3) Compose email
const subject = `${evt.actionUser?.name} mentioned you`;
const body = targetComment?.commentText || '';
const pageUrl = evt?.metadata?.pageInfo?.url;
// 4) Send via your provider
await emailClient.send({ to: recipients, subject, html: renderTemplate({ body, pageUrl }) });
res.sendStatus(200);
});
```
# Sample Data
```json theme={null}
{
"annotationId": "ANNOTATION_ID",
"metadata": {
"apiKey": "API_KEY",
"documentId": "DOCUMENT_ID",
"organizationId": "ORGANIZATION_ID"
},
"comments": {
"184639": {
"commentId": 184639,
"commentHtml": "Hey @Jane, can you review this?
",
"commentText": "Hey @Jane, can you review this?",
"from": {
"userId": "USER_ID"
},
"to": [
{
"userId": "JANE_USER_ID"
}
],
"taggedUserContacts": [
{
"userId": "JANE_USER_ID",
"contact": {
"userId": "JANE_USER_ID"
},
"text": "@Jane"
}
]
},
"743772": {
"commentId": 743772,
"attachments": {
"758336": {
"url": "https://your-bucket.s3.amazonaws.com/attachments/API_KEY/ATTACHMENT_ID.png",
"name": "image.png",
"attachmentId": 758336
}
},
"from": {
"userId": "USER_ID"
}
}
}
}
```
```json theme={null}
{
"annotationId": "ANNOTATION_ID",
"annotationIndex": 3,
"annotationNumber": 4,
"color": "#A25F9E",
"comments": [
{
"attachments": [],
"commentId": 184639,
"createdAt": 1768544691938,
"from": {
"userId": "USER_ID"
},
"isCommentResolverUsed": true,
"isCommentTextAvailable": true,
"isDraft": false,
"lastUpdated": "2026-01-16T05:34:19.402Z",
"reactionAnnotationIds": ["REACTION_ANNOTATION_ID"],
"taggedUserContacts": [],
"to": [],
"type": "text"
},
{
"attachments": [
{
"attachmentId": 758336,
"bucketPath": "API_KEY/organizations/ORG_ID/docs/DOC_ID/comments/ANNOTATION_ID/758336_image.png",
"isAttachmentResolverUsed": true,
"mimeType": "image/png",
"size": 289870,
"type": "png"
}
],
"commentId": 743772,
"createdAt": 1768544717230,
"from": {
"userId": "USER_ID"
},
"isCommentResolverUsed": true,
"isDraft": false,
"lastUpdated": "2026-01-16T05:34:31.352Z",
"reactionAnnotationIds": [],
"taggedUserContacts": [],
"to": [],
"type": "text"
}
],
"createdAt": 1768544637011,
"from": {
"userId": "USER_ID"
},
"involvedUserIds": ["USER_ID"],
"lastUpdated": 1768542354784,
"metadata": {
"apiKey": "API_KEY",
"clientDocumentId": "DOCUMENT_ID",
"clientOrganizationId": "ORGANIZATION_ID",
"documentId": "INTERNAL_DOC_ID",
"organizationId": "INTERNAL_ORG_ID"
},
"pageInfo": {
"baseUrl": "https://your-app.com",
"commentUrl": "https://your-app.com/?commentId=ANNOTATION_ID",
"path": "/",
"url": "https://your-app.com/"
},
"status": {
"id": "OPEN",
"name": "Open",
"color": "var(--velt-accent, #625DF5)",
"lightColor": "var(--velt-accent-light, #E7E8FA)",
"type": "default"
}
}
```
Note: Comment text/HTML content is NOT stored on Velt servers when using the comment resolver. Only metadata like `isCommentResolverUsed`, `isCommentTextAvailable`, attachment references (without URL/name), and reaction annotation IDs are stored.
# Debugging
You can subscribe to `dataProvider` events to monitor and debug get, save, and delete operations. The event includes a `moduleName` field that identifies which module triggered the resolver call, helping you trace data provider requests.
You can also use the [Velt Chrome DevTools extension](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl) to inspect and debug your Velt implementation.
Type: [`CommentResolverModuleName`](/api-reference/sdk/models/data-models#commentresolvermodulename)
```jsx theme={null}
import { useVeltClient } from '@veltdev/react';
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const subscription = client.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
console.log('Module Name:', event.moduleName);
});
return () => subscription?.unsubscribe();
}, [client]);
```
```javascript theme={null}
const subscription = Velt.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
console.log('Module Name:', event.moduleName);
});
// Unsubscribe when done
subscription?.unsubscribe();
```
# Overview
Source: https://docs.velt.dev/self-host-data/overview
Self-host the user generated content on your infrastructure while storing only minimal identifiers on Velt servers.
# Self-Hosting Data
Velt allows you to self-host sensitive content while still using most of the collaboration features and components:
* **Comments**: Store comment content on your infrastructure with only identifiers on Velt servers
* **Attachments**: Store comment file attachments on your infrastructure with only identifiers on Velt servers
* **In-app notifications**: In-app notification content is automatically handled when you use comments and reactions self-hosted solutions
* **Reactions**: Store reaction data on your systems with only identifiers on Velt servers
* **Users**: Store sensitive user PII on your servers, with only identifiers on Velt servers
For each data type, you configure a data provider that implements specific methods (get, save, delete) to interact with your database. Velt Components automatically hydrate data in the frontend by fetching from your configured providers.
This approach gives you complete control and ownership of your data while maintaining all Velt collaboration features and real-time functionality.
Email notifications via Velt's SendGrid integration are not available when you self-host comment content. Since the content lives on your infrastructure, Velt cannot construct and send emails via the sendgrid integration. Instead, use [Webhooks](/webhooks/basic) to receive events (e.g., mentions, replies), fetch the relevant comment/notification content from your database, and send emails from your own email provider.
# Supported Infrastructure
You can self-host your data on any infrastructure that you want as long as you can receive and return the data in the provided format. Here are some examples:
* AWS
* GCP
* Azure
* Any Custom Infrastructure
# Reactions
Source: https://docs.velt.dev/self-host-data/reactions
Self-host your reactions data while using Velt's components. Keep reaction storage on your infrastructure with minimal metadata stored on Velt servers.
* This is currently only compatible with `setDocuments` method.
* Ensure that the data providers are set prior to calling `identify` method.
* The data provider methods must return the correct status code (e.g. 200 for success, 500 for errors) and success boolean in the response object. This ensures proper error handling and retries.
# Overview
Velt supports self-hosting your reactions and related data:
* Reactions can be stored on your own infrastructure, with only necessary identifiers on Velt servers.
* Velt Components automatically hydrate reaction data in the frontend by fetching from your configured data provider.
* This gives you full control over reaction data while maintaining all Velt collaboration features.
* This automatically also ensures that the in-app notifications content related to reactions is not stored on Velt servers. The content is generated using the reactions data in the frontend.
# How does it work?
When users add or remove reactions:
1. The SDK uses your configured [`ReactionAnnotationDataProvider`](/api-reference/sdk/models/data-models#reactionannotationdataprovider) to handle storage
2. Your data provider implements three key methods:
* `get`: Fetches reactions from your database
* `save`: Stores reactions and returns success/error
* `delete`: Removes reactions from your database
**The process works as follows:**
When a reaction operation occurs:
1. The SDK first attempts to save/delete the reaction on your database
2. If successful:
* The SDK updates Velt's servers with minimal metadata
* The [`PartialReactionAnnotation`](/api-reference/sdk/models/data-models#partialreactionannotation) object is updated with the reaction details including emoji, user, and metadata
* When the reaction is saved, this information is stored on your end
* Velt servers only store necessary identifiers, not the actual reaction content
3. If the operation fails, no changes are made to Velt's servers and the operation is retried if you have configured retries.
You can configure retries, timeouts, etc. for the data provider.
# Implementation Approaches
You can implement reaction self-hosting using either of these approaches:
1. **Endpoint based**: Provide endpoint URLs and let the SDK handle HTTP requests
2. **Function based**: Implement `get`, `save`, and `delete` methods yourself
Both approaches are fully backward compatible and can be used together.
| Feature | Function based | Endpoint based |
| ------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Best For** | Complex setups requiring middleware logic, dynamic headers, or transformation before sending | Standard REST APIs where you just need to pass the request "as-is" to the backend |
| **Implementation** | You write the `fetch()` or `axios` code | You provide the `url` string and `headers` object |
| **Flexibility** | High | Medium |
| **Speed** | Medium | High |
## Endpoint based DataProvider
Instead of implementing custom methods, you can configure endpoints directly and let the SDK handle HTTP requests.
### getConfig
Config-based endpoint for fetching reactions. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`GetReactionResolverRequest`](/api-reference/sdk/models/data-models#getreactionresolverrequest)
* Response format: [`ResolverResponse>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const reactionResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/reactions/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const reactionDataProvider = {
config: reactionResolverConfig
};
```
```js theme={null}
const reactionResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/reactions/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const reactionDataProvider = {
config: reactionResolverConfig
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
### saveConfig
Config-based endpoint for saving reactions. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`SaveReactionResolverRequest`](/api-reference/sdk/models/data-models#savereactionresolverrequest)
* Response format: [`ResolverResponse`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const reactionResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/reactions/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const reactionDataProvider = {
config: reactionResolverConfig
};
```
```js theme={null}
const reactionResolverConfig = {
saveConfig: {
url: 'https://your-backend.com/api/velt/reactions/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const reactionDataProvider = {
config: reactionResolverConfig
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
### deleteConfig
Config-based endpoint for deleting reactions. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`DeleteReactionResolverRequest`](/api-reference/sdk/models/data-models#deletereactionresolverrequest)
* Response format: [`ResolverResponse`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx theme={null}
const reactionResolverConfig = {
deleteConfig: {
url: 'https://your-backend.com/api/velt/reactions/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const reactionDataProvider = {
config: reactionResolverConfig
};
```
```js theme={null}
const reactionResolverConfig = {
deleteConfig: {
url: 'https://your-backend.com/api/velt/reactions/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}
};
const reactionDataProvider = {
config: reactionResolverConfig
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
### Endpoint based Complete Example
```jsx theme={null}
const reactionResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/reactions/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
saveConfig: {
url: 'https://your-backend.com/api/velt/reactions/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
deleteConfig: {
url: 'https://your-backend.com/api/velt/reactions/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const reactionDataProvider = {
config: reactionResolverConfig
};
```
```js theme={null}
const reactionResolverConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/reactions/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
saveConfig: {
url: 'https://your-backend.com/api/velt/reactions/save',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
deleteConfig: {
url: 'https://your-backend.com/api/velt/reactions/delete',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const reactionDataProvider = {
config: reactionResolverConfig
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
## Function based DataProvider
Implement custom methods to handle data operations yourself.
### get
Method to fetch reactions from your database. On error we will retry.
* Param: [`GetReactionResolverRequest`](/api-reference/sdk/models/data-models#getreactionresolverrequest)
* Return: [`Promise>>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx React / Next.js theme={null}
const fetchReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionDataProvider = {
get: fetchReactionsFromDB,
};
```
```js Other Frameworks theme={null}
const fetchReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionDataProvider = {
get: fetchReactionsFromDB,
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
```javascript theme={null}
// Build query from request
const { reactionAnnotationIds, documentIds, organizationId } = req.body;
const query = {};
if (reactionAnnotationIds?.length) {
query.annotationId = { $in: reactionAnnotationIds };
}
if (documentIds?.length) {
query.documentId = { $in: documentIds };
}
if (organizationId) {
query.organizationId = organizationId;
}
const annotations = await collection.find(query).toArray();
// Convert to Record
const result = {};
for (const annotation of annotations) {
result[annotation.annotationId] = annotation;
}
// Return response in required format
res.json({ data: result, success: true, statusCode: 200 });
```
```javascript theme={null}
// Build parameterized query
const { reactionAnnotationIds, documentIds, organizationId } = req.body;
const conditions = [];
const values = [];
let paramIndex = 1;
if (reactionAnnotationIds?.length) {
conditions.push(`annotation_id = ANY($${paramIndex++})`);
values.push(reactionAnnotationIds);
}
if (documentIds?.length) {
conditions.push(`document_id = ANY($${paramIndex++})`);
values.push(documentIds);
}
if (organizationId) {
conditions.push(`organization_id = $${paramIndex++}`);
values.push(organizationId);
}
const whereClause = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
const { rows } = await client.query(
`SELECT annotation_id, data FROM reaction_annotations ${whereClause}`,
values
);
// Convert to Record
const result = {};
for (const row of rows) {
result[row.annotation_id] = row.data;
}
// Return response in required format
res.json({ data: result, success: true, statusCode: 200 });
```
### save
Save reactions to your database. Return a success or error response. On error we will retry.
* Param: [`SaveReactionResolverRequest`](/api-reference/sdk/models/data-models#savereactionresolverrequest)
* Return: [`Promise>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx React / Next.js theme={null}
const saveReactionsToDB = async (request) => {
const response = await fetch('/api/velt/reactions/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionDataProvider = {
save: saveReactionsToDB,
};
```
```js Other Frameworks theme={null}
const saveReactionsToDB = async (request) => {
const response = await fetch('/api/velt/reactions/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionDataProvider = {
save: saveReactionsToDB,
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
```javascript theme={null}
const { annotations, context } = req.body;
// Bulk upsert annotations
const operations = Object.entries(annotations).map(([id, annotation]) => ({
updateOne: {
filter: { annotationId: id },
update: {
$set: {
...annotation,
annotationId: id,
documentId: context?.documentId || annotation.documentId,
organizationId: context?.organizationId || annotation.organizationId,
}
},
upsert: true
}
}));
if (operations.length > 0) {
await collection.bulkWrite(operations);
}
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
```javascript theme={null}
const { annotations, context } = req.body;
// Transaction-based upsert
await client.query('BEGIN');
for (const [id, annotation] of Object.entries(annotations)) {
const data = { ...annotation, annotationId: id };
await client.query(
`INSERT INTO reaction_annotations (annotation_id, document_id, organization_id, data, updated_at)
VALUES ($1, $2, $3, $4, NOW())
ON CONFLICT (annotation_id)
DO UPDATE SET data = EXCLUDED.data, updated_at = NOW()`,
[id, annotation.documentId, annotation.organizationId, JSON.stringify(data)]
);
}
await client.query('COMMIT');
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
### delete
Delete reactions from your database. Return a success or error response. On error we will retry.
* Param: [`DeleteReactionResolverRequest`](/api-reference/sdk/models/data-models#deletereactionresolverrequest)
* Return: [`Promise>`](/api-reference/sdk/models/data-models#resolverresponse)
```jsx React / Next.js theme={null}
const deleteReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionDataProvider = {
delete: deleteReactionsFromDB,
};
```
```js Other Frameworks theme={null}
const deleteReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionDataProvider = {
delete: deleteReactionsFromDB,
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
```javascript theme={null}
const { annotationId } = req.body;
await collection.deleteOne({ annotationId });
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
```javascript theme={null}
const { annotationId } = req.body;
await client.query(
'DELETE FROM reaction_annotations WHERE annotation_id = $1',
[annotationId]
);
// Return response in required format
res.json({ success: true, statusCode: 200 });
```
### config
Configuration for the reaction data provider.
* Type: [`ResolverConfig`](/api-reference/sdk/models/data-models#resolverconfig). Relevant properties:
* `resolveTimeout`: Timeout duration (in milliseconds) for resolver operations
* `getRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for get operations.
* `saveRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for save operations.
* `deleteRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig). Configure retry behavior for delete operations.
```jsx theme={null}
const reactionResolverConfig = {
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
```
### Function based Complete Example
```jsx theme={null}
const fetchReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const saveReactionsToDB = async (request) => {
const response = await fetch('/api/velt/reactions/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const deleteReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionResolverConfig = {
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const reactionDataProvider = {
get: fetchReactionsFromDB,
save: saveReactionsToDB,
delete: deleteReactionsFromDB,
config: reactionResolverConfig
};
```
```js theme={null}
const fetchReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const saveReactionsToDB = async (request) => {
const response = await fetch('/api/velt/reactions/save', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const deleteReactionsFromDB = async (request) => {
const response = await fetch('/api/velt/reactions/delete', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(request)
});
return await response.json();
};
const reactionResolverConfig = {
resolveTimeout: 2000,
getRetryConfig: { retryCount: 3, retryDelay: 2000 },
saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};
const reactionDataProvider = {
get: fetchReactionsFromDB,
save: saveReactionsToDB,
delete: deleteReactionsFromDB,
config: reactionResolverConfig
};
Velt.setDataProviders({ reaction: reactionDataProvider });
```
# Sample Data
```json theme={null}
{
"annotationId": "REACTION_ANNOTATION_ID",
"metadata": {
"apiKey": "API_KEY",
"documentId": "DOCUMENT_ID",
"organizationId": "ORGANIZATION_ID"
},
"icon": "HEART_FACE"
}
```
The reaction annotation on your database stores the actual reaction icon/emoji content.
```json theme={null}
{
"annotationId": "REACTION_ANNOTATION_ID",
"commentAnnotationId": "COMMENT_ANNOTATION_ID",
"from": {
"userId": "USER_ID"
},
"involvedUserIds": ["USER_ID"],
"isReactionResolverUsed": true,
"lastUpdated": 1768542354775,
"metadata": {
"apiKey": "API_KEY",
"clientDocumentId": "DOCUMENT_ID",
"clientOrganizationId": "ORGANIZATION_ID",
"documentId": "INTERNAL_DOC_ID",
"organizationId": "INTERNAL_ORG_ID"
},
"pageInfo": {
"baseUrl": "https://your-app.com",
"path": "/",
"url": "https://your-app.com/"
},
"reactions": [
{
"from": {
"userId": "USER_ID"
},
"lastUpdated": 1768542354775
}
],
"type": "reaction"
}
```
Only reaction identifiers and metadata are stored on Velt servers. The actual reaction icon/emoji remains on your infrastructure.
```json theme={null}
{
"annotationId": "COMMENT_ANNOTATION_ID",
"comments": [
{
"commentId": 184639,
"from": {
"userId": "USER_ID"
},
"isCommentResolverUsed": true,
"isCommentTextAvailable": true,
"reactionAnnotationIds": ["REACTION_ANNOTATION_ID"]
}
],
"metadata": {
"apiKey": "API_KEY",
"documentId": "DOCUMENT_ID",
"organizationId": "ORGANIZATION_ID"
}
}
```
The comment annotation on Velt servers keeps a reference to the reaction annotation IDs (`reactionAnnotationIds`), but the actual reaction content is stored on your infrastructure.
# Debugging
You can subscribe to `dataProvider` events to monitor and debug get, save, and delete operations. The event includes a `moduleName` field that identifies which module triggered the resolver call, helping you trace data provider requests.
You can also use the [Velt Chrome DevTools extension](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl) to inspect and debug your Velt implementation.
Type: [`ReactionResolverModuleName`](/api-reference/sdk/models/data-models#reactionresolvermodulename)
```jsx theme={null}
import { useVeltClient } from '@veltdev/react';
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const subscription = client.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
console.log('Module Name:', event.moduleName);
});
return () => subscription?.unsubscribe();
}, [client]);
```
```javascript theme={null}
const subscription = Velt.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
console.log('Module Name:', event.moduleName);
});
// Unsubscribe when done
subscription?.unsubscribe();
```
# Users
Source: https://docs.velt.dev/self-host-data/users
Self-host your users' PII while using Velt's collaboration features. Keep sensitive user data on your infrastructure with only user IDs stored on Velt servers.
Ensure that the data providers are set prior to calling `identify` method.
# Overview
Velt supports self-hosting your users' personally identifiable information (PII):
* Only the userId is stored on Velt servers, keeping sensitive user metadata on your infrastructure
* Velt Components automatically hydrate user details in the frontend by fetching from your configured data provider
* This gives you full control over user data while maintaining all Velt functionality
## How does it work?
* When the SDK is initialized, it will call the [`UserDataProvider`](/api-reference/sdk/models/data-models#userdataprovider) you configure with the list of userIds that it needs to fetch for the currently set user, organization, document, etc.
* The [`UserDataProvider`](/api-reference/sdk/models/data-models#userdataprovider) takes in a list of userIds and returns a Record object with the userIds as keys and the user data as values.
# Implementation Approaches
You can implement user self-hosting using either of these approaches:
1. **Endpoint based**: Provide an endpoint URL and let the SDK handle HTTP requests
2. **Function based**: Implement the `get` method yourself
Both approaches are fully backward compatible and can be used together.
| Feature | Function based | Endpoint based |
| ------------------ | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Best For** | Complex setups requiring middleware logic, dynamic headers, or transformation before sending | Standard REST APIs where you just need to pass the request "as-is" to the backend |
| **Implementation** | You write the `fetch()` or `axios` code | You provide the `url` string and `headers` object |
| **Flexibility** | High | Medium |
| **Speed** | Medium | High |
## Endpoint based DataProvider
Instead of implementing custom methods, you can configure an endpoint directly and let the SDK handle HTTP requests.
### getConfig
Config-based endpoint for fetching users. The SDK automatically makes HTTP POST requests with the request body.
* Type: [`ResolverEndpointConfig`](/api-reference/sdk/models/data-models#resolverendpointconfig)
* Request body format: [`GetUserResolverRequest`](/api-reference/sdk/models/data-models#getuserresolverrequest) - `{ organizationId: string, userIds: string[] }`
* Response format: [`ResolverResponse>`](/api-reference/sdk/models/data-models#resolverresponse)
The config-based approach uses a different request format than the custom methods approach. It passes `{ organizationId, userIds }` instead of just `userIds`.
```jsx theme={null}
const userConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/users/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveUsersConfig: {
organization: false,
folder: false,
document: true
}
};
const userDataProvider = {
config: userConfig
};
```
```js theme={null}
const userConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/users/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveUsersConfig: {
organization: false,
folder: false,
document: true
}
};
const userDataProvider = {
config: userConfig
};
Velt.setDataProviders({ user: userDataProvider });
```
### Endpoint based Complete Example
```jsx theme={null}
const userConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/users/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveUsersConfig: {
organization: false,
folder: false,
document: true
}
};
const userDataProvider = {
config: userConfig
};
```
```js theme={null}
const userConfig = {
getConfig: {
url: 'https://your-backend.com/api/velt/users/get',
headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
},
resolveUsersConfig: {
organization: false,
folder: false,
document: true
}
};
const userDataProvider = {
config: userConfig
};
Velt.setDataProviders({ user: userDataProvider });
```
## Function based DataProvider
Here are the methods that you need to implement on the data provider:
### get
Method to fetch users from your database.
* Param: `string[]`: Array of userIds to fetch
* Return: `Promise>` or [`Promise>>`](/api-reference/sdk/models/data-models#resolverresponse)
Both response formats are supported for backward compatibility:
* **Old format**: `Record` - Returns user data directly
* **New format**: [`ResolverResponse>`](/api-reference/sdk/models/data-models#resolverresponse) - Returns `{ data, success, statusCode, message?, timestamp? }`
```jsx React / Next.js theme={null}
const fetchUsersFromDB = async (userIds) => {
const response = await fetch('/api/velt/users/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userIds })
});
return await response.json();
};
const userDataProvider = {
get: fetchUsersFromDB,
};
```
```js Other Frameworks theme={null}
const fetchUsersFromDB = async (userIds) => {
const response = await fetch('/api/velt/users/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userIds })
});
return await response.json();
};
const userDataProvider = {
get: fetchUsersFromDB,
};
Velt.setDataProviders({ user: userDataProvider });
```
```javascript theme={null}
const { userIds } = req.body;
const users = await collection.find({
userId: { $in: userIds }
}).toArray();
// Convert to Record
const result = {};
for (const user of users) {
result[user.userId] = user;
}
// Return response in required format
res.json(result);
```
```javascript theme={null}
const { userIds } = req.body;
const { rows } = await client.query(
'SELECT user_id, name, email, photo_url FROM users WHERE user_id = ANY($1)',
[userIds]
);
// Convert to Record
const result = {};
for (const row of rows) {
result[row.user_id] = {
userId: row.user_id,
name: row.name,
email: row.email,
photoUrl: row.photo_url
};
}
// Return response in required format
res.json(result);
```
### config
Configuration for the user data provider.
* Type: [`ResolverConfig`](/api-reference/sdk/models/data-models#resolverconfig). Relevant properties:
* `resolveUsersConfig`: [`ResolveUsersConfig`](/api-reference/sdk/models/data-models#resolveusersconfig). Controls whether Velt issues user-resolver requests during initialization to fetch contact lists at the organization, folder, and document levels. Use this to optimize performance in environments with a large number of users by preventing unnecessary user-data fetches. You can selectively disable user-resolver requests for specific scopes and instead provide your own user data via the [custom autocomplete feature](/async-collaboration/comments/customize-behavior#customautocompletesearch) instead.
* `organization`: boolean - Enable/disable user requests for organization users (default: true)
* `document`: boolean - Enable/disable user requests for document users (default: true)
* `folder`: boolean - Enable/disable user requests for folder users (default: true)
```jsx theme={null}
const userConfig = {
resolveUsersConfig: {
organization: false,
folder: false,
document: true
}
};
```
### Function based Complete Example
```jsx theme={null}
const fetchUsersFromDB = async (userIds) => {
const response = await fetch('/api/velt/users/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userIds })
});
return await response.json();
};
const userDataProvider = {
get: fetchUsersFromDB,
config: {
resolveUsersConfig: {
organization: false,
folder: false,
document: true
}
}
};
```
```js theme={null}
const fetchUsersFromDB = async (userIds) => {
const response = await fetch('/api/velt/users/get', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ userIds })
});
return await response.json();
};
const userDataProvider = {
get: fetchUsersFromDB,
config: {
resolveUsersConfig: {
organization: false,
folder: false,
document: true
}
}
};
Velt.setDataProviders({ user: userDataProvider });
```
# Anonymous User Resolution
When a user who is not part of the contact list is tagged by email in a comment, they won't have a `userId`. The [`AnonymousUserDataProvider`](/api-reference/sdk/models/data-models#anonymoususerdataprovider) resolves these email → `userId` mappings automatically. When a comment is saved and a tagged contact or `to` recipient has an email but no `userId`, the SDK calls the registered provider to look up the `userId`, backfills it into the comment data before persisting, and optionally writes a stub user record to the organization database.
* Type: [`AnonymousUserDataProvider`](/api-reference/sdk/models/data-models#anonymoususerdataprovider)
* `resolveUserIdsByEmail`: Callback that maps email addresses to user IDs. Called automatically at comment save time.
* Param: [`ResolveUserIdsByEmailRequest`](/api-reference/sdk/models/data-models#resolveuseridsbyemailrequest) - `{ organizationId: string, documentId?: string, folderId?: string, emails: string[] }`
* Return: [`Promise>>`](/api-reference/sdk/models/data-models#resolverresponse) - `{ statusCode, success, data: { [email]: userId } }`
* `config`: Optional configuration for timeout and retry behavior.
* Type: [`AnonymousUserDataProviderConfig`](/api-reference/sdk/models/data-models#anonymoususerdataproviderconfig)
* `resolveTimeout`: `number` - Timeout in milliseconds for the resolve call
* `getRetryConfig`: [`RetryConfig`](/api-reference/sdk/models/data-models#retryconfig) - `{ retryCount, retryDelay }`
Key behaviors:
* Results are cached in memory for the session; emails already resolved are not re-fetched.
* On timeout or error, the provider returns whatever was cached and proceeds without the unresolved user IDs.
* If no [`UserDataProvider`](/api-reference/sdk/models/data-models#userdataprovider) is configured, resolved user IDs are automatically backfilled to the organization database as stub user records (`{ userId, name: email, email }`).
* If a `UserDataProvider` is already configured, the org DB backfill is skipped.
```jsx theme={null}
// Option 1: via VeltProvider
const anonymousUserDataProvider = {
resolveUserIdsByEmail: async (request) => {
const map = await yourBackend.lookupUserIds(request.emails);
return { statusCode: 200, success: true, data: map };
},
config: {
resolveTimeout: 5000,
getRetryConfig: { retryCount: 2, retryDelay: 300 },
},
};
// Option 2: standalone method
client.setAnonymousUserDataProvider({
resolveUserIdsByEmail: async (request) => {
const map = await yourBackend.lookupUserIds(request.emails);
return { statusCode: 200, success: true, data: map };
},
config: {
resolveTimeout: 5000,
getRetryConfig: { retryCount: 2, retryDelay: 300 },
},
});
// Option 3: via setDataProviders
client.setDataProviders({
anonymousUser: {
resolveUserIdsByEmail: async (request) => { /* ... */ },
},
});
```
```html theme={null}
```
# Sample Data
```json theme={null}
{
"USER_ID_1": {
"userId": "USER_ID_1",
"name": "John Doe",
"email": "john.doe@example.com",
"photoUrl": "https://example.com/photos/john.jpg",
"organizationId": "ORG_ID",
"role": "admin"
},
"USER_ID_2": {
"userId": "USER_ID_2",
"name": "Jane Smith",
"email": "jane.smith@example.com",
"photoUrl": "https://example.com/photos/jane.jpg",
"organizationId": "ORG_ID",
"role": "member"
}
}
```
```json theme={null}
{
"userId": "USER_ID_1"
}
```
Only the userId is stored on Velt servers. All other user metadata (name, email, photoUrl, etc.) remains on your infrastructure.
# Debugging
You can subscribe to `dataProvider` events to monitor and debug get operations. The event includes a `moduleName` field that identifies which module triggered the resolver call, helping you trace data provider requests.
You can also use the [Velt Chrome DevTools extension](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl) to inspect and debug your Velt implementation.
Type: [`UserResolverModuleName`](/api-reference/sdk/models/data-models#userresolvermodulename)
```jsx theme={null}
import { useVeltClient } from '@veltdev/react';
const { client } = useVeltClient();
useEffect(() => {
if (!client) return;
const subscription = client.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
console.log('Module Name:', event.moduleName);
});
return () => subscription?.unsubscribe();
}, [client]);
```
```javascript theme={null}
const subscription = Velt.on('dataProvider').subscribe((event) => {
console.log('Data Provider Event:', event);
console.log('Module Name:', event.moduleName);
});
// Unsubscribe when done
subscription?.unsubscribe();
```
# Temp release notes
Source: https://docs.velt.dev/temp-release-notes
### New Features
* \[**Comments**]: Added `markAsRead()` and `markAsUnread()` methods to mark comment annotations as read or unread for the current user.
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
commentElement.markAsUnread("eUgq6G6zXxJmOT9eBXtT");
commentElement.markAsRead("eUgq6G6zXxJmOT9eBXtT");
// Using API methods
const commentElement = client.getCommentElement();
commentElement.markAsUnread("eUgq6G6zXxJmOT9eBXtT");
commentElement.markAsRead("eUgq6G6zXxJmOT9eBXtT");
```
```jsx theme={null}
const commentElement = Velt.getCommentElement();
commentElement.markAsUnread("eUgq6G6zXxJmOT9eBXtT");
commentElement.markAsRead("eUgq6G6zXxJmOT9eBXtT");
```
### Improvements
* \[**Recorder**]: Added system sound capture when recording a browser tab.
* \[**Comments**]: You can now tag users by copy-pasting their email address. Previously, only manually typed emails worked for tagging users not on the contact list.
* \[**Comments**]: Added `viewedBy` and `reactionAnnotations` fields to comment annotation objects returned via REST APIs including [Get Comment Annotations](/api-reference/rest-apis/v2/comments-feature/comment-annotations/get-comment-annotations-v2) and [Get Comments](/api-reference/rest-apis/v2/comments-feature/comments/get-comments). These fields provide enhanced visibility into user engagement and reactions.
**`viewedBy`**: An array of User objects representing who has seen and read the comment annotation. Use this to track engagement, identify which stakeholders have reviewed feedback, or build custom read receipt indicators.
**`reactionAnnotations`**: An array of complete ReactionAnnotation objects containing the full reaction data for each comment. Each object includes the reaction ID, icon, user information, and metadata. Use this to display reaction counts, show who reacted with what emoji, or build custom reaction analytics.
```typescript theme={null}
// Comment Annotation Object
{
...
comments: [
{
...
reactionAnnotations?: ReactionAnnotation[]; // Complete reaction objects with full details
}
],
viewedBy?: User[]; // Users who have seen and read this annotation
}
```
### Bug Fixes
* \[**Recorder**]: Fixed an issue in the video editor where the playhead position was ignored after playback ended. When seeking or dragging the playhead after video completion, playback now correctly starts from the new position instead of always starting from the beginning.
### Improvements
* \[**Comments**]: Released v2 improved version of comment anchoring that makes comment positioning more dynamic and robust on more dynamic websites. This includes enhanced element detection for pin, text, and area comments, improved cursor display based on DOM element visibility, and better handling of image tag positioning with conditional relative positioning for container elements.
### Bug Fixes
* \[**Comments**]: Fixed an issue where draft comments with resolvers were incorrectly submitted before being finalized, causing data inconsistencies. Draft comments with resolvers now work properly and are only saved when explicitly published.
* \[**Access Control**]: Fixed an issue where organization access permissions were not being set correctly when using the permission provider. When users logged in, their organization-level permissions were failing to initialize properly. Organization access now gets assigned correctly during the identification process.
# Temp release notes input
Source: https://docs.velt.dev/temp-release-notes-input
### New Features
* \[**Core**]: Added `getHeartbeat()` method to subscribe to user-specific heartbeat data. You can retrieve heartbeat data for the current user or specify a `userId` to get heartbeats for any user, providing better visibility into active sessions per user.
```jsx theme={null}
// Using Hooks
import { useHeartbeat } from "@veltdev/react";
import { useEffect } from "react";
const { data: heartbeatData } = useHeartbeat();
useEffect(() => {
console.log("Heartbeat data: ", heartbeatData);
}, [heartbeatData]);
// Using API methods
client.getHeartbeat().subscribe((heartbeatData) => {
console.log("Heartbeat data: ", heartbeatData);
});
```
```html theme={null}
```
**Heartbeat Interfaces:**
```typescript theme={null}
export interface HeartbeatConfig {
userId?: string;
}
export interface GetHeartbeatResponse {
data: Heartbeat[] | null;
}
```
### Improvements
* \[**Comments**]: Added location removal logic when video plays in Timeline Player. Comment pins are now properly removed as the video plays, ensuring accurate timeline visualization.
* \[**Comments**]: Added change detection in Timeline Player. The timeline bar now moves correctly when hovering over the play button or timeline, ensuring responsive playback controls.
### Bug Fixes
* \[**Core**]: Fixed disconnect errors in the heartbeat feature. The SDK now handles network issues at the client side without triggering server disconnect errors.
* \[**Core**]: Fixed user color and text color persistence during auto-login. Colors passed during `identify()` now persist correctly in auto-login scenarios, ensuring consistent user identification.
* \[**Presence**]: Fixed `multipleUsersOnline` event firing when only a single user is present. The presence feature now correctly identifies single-user scenarios, preventing unwanted analytics events.
### Bug Fixes
* \[**Comments**]: Fixed race condition errors in Player Timeline by adding proper lifecycle management. The player timeline now properly handles component destruction, preventing "undefined" errors that could occur when the component was destroyed during asynchronous operations.
* \[**Notifications**]: Fixed error handling for document notifications by adding metadata validation. The SDK now checks if notification metadata exists before processing document notifications, preventing unnecessary errors in analytics tracking when notifications are missing required data.
### Bug Fixes
* \[**Core**]: Fixed user resolution for tagged and assigned users in contact lists. Users added via `updateContactList()` are now properly cached, ensuring that tagged and assigned users resolve correctly from cached data instead of failing to load.
### Bug Fixes
* \[**Core**]: Improved `updateContactList()` method behavior by removing unnecessary validation checks. The method now directly applies user-provided contact list data without additional validation, giving you more control over contact list management.
### Bug Fixes
* \[**Recorder**]: Fixed an issue where zoom was not applied unless the zoom section in the timeline was modified directly.
### Bug Fixes
* \[**Recorder**]: Fixed an issue where the zoom animation in the editor preview had a curve in the transition. The editor preview now displays smooth transitions to the correct coordinates instead of curved transitions.
* \[**Recorder**]: Fixed an issue where VeltIf was throwing an error when evaluating MediaStream object.
* \[**Comments**]: Fixed sanitization of `target` attributes in comment HTML content. The DomPurifier now preserves `target` attributes in comment HTML fields, allowing users to include links with target specifications (such as `target="_blank"`) in their comments.
### Improvements
* \[**Core**]: Optimized the initialization module and significantly reduced the SDK initialization time.
### New Features
* \[**Core**]: Added `fetchDebugInfo()` and `getDebugInfo()` methods to retrieve debugging information about your Velt implementation. Use `fetchDebugInfo()` to get a one-time snapshot or `getDebugInfo()` to subscribe to real-time updates of key setup info like sdk version, apikey, user, organizationId, documentId, folderID version, locations etc. You can also get this info from [Velt's Chrome devtools](https://chromewebstore.google.com/detail/velt-devtools/nfldoicbagllmegffdapcnohakpamlnl)
```jsx theme={null}
// Using API methods - One-time fetch
await client.fetchDebugInfo();
// Using API methods - Subscribe to updates
client.getDebugInfo().subscribe((debugInfo) => {
console.log("Debug info: ", debugInfo);
});
```
```html theme={null}
```
**Debug Info Interface:**
```typescript theme={null}
export interface VeltDebugInfo {
veltVersion?: string;
apiKey?: string;
serverMap?: {
organization?: OrganizationMetadata;
documents?: DocumentMetadata[];
locations?: Location[];
folder?: FolderMetadata;
user?: User;
};
clientMap?: {
organization?: OrganizationMetadata;
documents?: DocumentMetadata[];
locations?: Location[];
folder?: FolderMetadata;
user?: User;
};
}
```
### Improvements
* \[**Access Control**]: Prevent users from adding comments, reactions, recorders, and area comments through the SDK when `access context` is used and the user doesn't have access to the specific context.
### New Features
* \[**Comments**]: Added preliminary infra required to capture screenshots in comments.
### Improvements
* \[**Access Control**]: Now you can set feature level permissions using Access Context. Access Context allows you to set granular, feature-level permissions using custom metadata. When configured, new feature data is added and existing feature data is fetched only for the access context values the current user has access to. [Learn more →](/key-concepts/overview#set-feature-level-permissions-using-access-context-custom-metadata)
### Improvements
* \[**Recorder**]: Updated video editor timeline picture mode design for improved visual clarity. The unselected portion of timeline pictures now displays with a cleaner design that better distinguishes selected from unselected frames.
* \[**Recorder**]: Fixed audio merging in screen recording to combine microphone and tab audio. When recording with both microphone and tab audio enabled, both audio sources are now properly merged into the final recording.
### Bug Fixes
* \[**Comments**]: Fixed type definition for `selectCommentByAnnotationId()` and made `annotationId` parameter optional.
* \[**Comments**]: Fixed embed mode logic in comments sidebar to support multiple embedded sidebars.
### New Features
* \[**Access Control**]: Added the new Permission Provider feature. With this approach, Velt pings your defined endpoint to verify whether a user should be granted access to a resource (organization, folder, or document). This ensures that your backend is still the source of truth and you don't have to sync the permissions into Velt directly. [Learn more →](/key-concepts/overview#c-real-time-permission-provider)
* \[**Access Control**]: Added a config to automatically revoke permissions, including revoking access to documents, folders, and optionally organizations when users log out or when documents are unset. This ensures immediate permission removal without requiring manual cleanup. [Learn more →](/key-concepts/overview#c-real-time-permission-provider)
* \[**Access Control**]: Added various Permission Provider events to monitor the sequence of permission check events for debugging and tracking purposes. [Learn more →](/api-reference/sdk/models/data-models#permissionproviderevent)
### Improvements
* \[**Access Control**]: Simplified Permission Provider implementation by removing `onResourceAccessRequired` call and signature handling from client SDK. Permission handling is now fully managed internally by the SDK. You no longer need to handle signatures or make `onResourceAccessRequired` calls. The SDK automatically handles permission caching, validation, and synchronization with the backend. [Learn more →](/api-reference/sdk/api/api-methods#setpermissionprovider)
### New Features
* \[**Recorder**]: Added video editor timeline image preview to display frame snapshots in the timeline. This helps you quickly navigate to specific scenes without scrubbing through the entire video.
```jsx theme={null}
```html theme={null}
The timeline preview only works when both `videoEditorTimelinePreview` and `videoEditor` are set to `true`.
### Improvements
* \[**Comments**]: Enhanced `selectCommentByAnnotationId()` to close the selected comment annotation when called with no arguments or an invalid ID.
```jsx theme={null}
// Using Hooks
const commentElement = useCommentUtils();
// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');
// Using API methods
const commentElement = client.getCommentElement();
// Close the currently selected annotation
commentElement.selectCommentByAnnotationId();
commentElement.selectCommentByAnnotationId('invalid-id');
```
```html theme={null}
```
### New Features
* \[**Access Control**]: Added early version of feature level permissions using Access Context. Access Context allows you to set granular, feature-level permissions using custom metadata. When configured, new feature data is added and existing feature data is fetched only for the access context values the current user has access to. [Learn more →](/key-concepts/overview#set-feature-level-permissions-using-access-context-custom-metadata)
### Improvements
* \[**Access Control**]: Added `source` field to Permission Provider requests to identify which method triggered the request. The `source` field helps you debug and trace which SDK method initiated the permission check. [Learn more →](/key-concepts/overview#c-real-time-permission-provider)
* \[**Access Control**]: Added various Permission Provider events to monitor the sequence of permission check events for debugging and tracking purposes. [Learn more →](/api-reference/sdk/models/data-models#permissionproviderevent)
### Bug Fixes
* \[**Notifications**]: Fixed notification fetching with Permission Provider when document IDs needed mapping to client document IDs.
# Conditional Templates
Source: https://docs.velt.dev/ui-customization/conditional-templates
* Conditional Templates let you conditionally show or hide parts of the Velt Component Wireframes.
* You can add conditions based on the same data models available in [Template Variables](/ui-customization/template-variables).
There are two ways to use Conditional Templates:
## 1. Using `Velt If` component
* Wrap wireframe components and html elements in `Velt If` component.
* If the condition is not met, the component will not be rendered.
* Good for targeting groups of components at once.
```jsx theme={null}
{/* Content to render if condition is true */}
```
```html theme={null}
```
## 2. Using `Velt If` attribute
* Add `Velt If` attribute to existing wireframe components.
* If the condition is not met, the component will not be rendered.
* Good for targeting a single component.
```jsx theme={null}
```html theme={null}
```
## Syntax
The condition is specified as a string that will be evaluated as a JavaScript expression. Here is a sample syntax:
Syntax: `{} `
Example: `{annotation.status.id} === 'OPEN'`
* Template variables need to be enclosed in curly braces: `{variable.property}`
* Operators:
* Comparison operators: `===`, `==`, `!==`, `>`, `<`, `>=`, `<=`
* Logical operators: `&&`, `||`, `!`
* Value can be a string, number or boolean.
## Strict CSP Policy
Some environments enforce strict Content Security Policies (CSP) that disallow `unsafe-eval`. In such cases, the default method could be blocked and the conditions may not be evaluated.
Here is how you can use an alternative approach to evaluate `Velt If` conditions. This method uses a safer, CSP-compliant parser to evaluate your `Velt If` conditions.
```javascript theme={null}
client.enableSafeEval();
client.disableSafeEval();
```
```javascript theme={null}
Velt.enableSafeEval();
Velt.disableSafeEval();
```
## Examples
```jsx theme={null}
{/* 1. Show content only for open annotations: */}
This annotation is currently open.
{/* 2. Display a message for annotations with more than 5 comments: */}
This is a popular annotation!
{/* 3. Combine multiple conditions: */}
This is a new open annotation without any comments yet.
```
```html theme={null}
This annotation is currently open.
This is a popular annotation!
This is a new open annotation without any comments yet.
```
# Action Components
Source: https://docs.velt.dev/ui-customization/custom-action-component
* A customizable button component that can be used to add custom actions and extend the functionality of any Velt component. Some examples include:
* Add custom filtering, sorting and grouping to the Comment Sidebar
* Add custom actions to each item in the Notifications panel.
* Add custom actions to the Comment Dialog.
* In the [callback event](#callback-event), in addition to returning the button context, it also returns the key component data that it sits within Eg: `CommentAnnotation`, `Comment`, `Notification`, `CommentSidebarData` etc.
## Types
* `button`: Basic clickable button
* `button-toggle`: Toggleable button that maintains state
* `single-select`: Single select (radio button) group
* `multi-select`: Multi select (checkbox) group
## Component Props
| Property | Type | Required | Description |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | Unique identifier for the button. This can be a static id or a dynamic id using a template variable. |
| `type` | string | No | Button type: 'button' (default), 'button-toggle', 'multi-select', or 'single-select' |
| `disabled` | boolean | No | Whether the button is disabled |
| `active` | boolean | No | Whether the button is in active/selected state. Use this if you want to add a default state to the button. Applies to 'button-toggle', 'multi-select', or 'single-select' buttons. |
| `group` | string | No | Group identifier for single-select/multi-select buttons |
## Usage
### Button
```jsx {6-8} theme={null}
```
**Handle the button click event:**
```jsx theme={null}
// Hook
const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
useEffect(() => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext.clickedButtonId === 'close-sidebar') {
// Close sidebar
}
}
}, [veltButtonClickEventData]);
// API Method
client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext.clickedButtonId === 'close-sidebar') {
// Close sidebar
}
}
});
```
```html {6-8} theme={null}
```
**Handle the button click event:**
```js theme={null}
Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext.clickedButtonId === 'close-sidebar') {
// Close sidebar
}
}
});
```
### Button Toggle
```jsx {6-8} theme={null}
```
**Handle the button click event:**
```jsx theme={null}
// Hook
const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
useEffect(() => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.clickedButtonId === 'toggleCommentPins') {
if (veltButtonClickEventData.buttonContext?.selections?.ungrouped['toggleCommentPins']) {
commentElement.showCommentsOnDom();
} else {
commentElement.hideCommentsOnDom();
}
}
}
}, [veltButtonClickEventData]);
// API Method
client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.clickedButtonId === 'toggleCommentPins') {
if (veltButtonClickEventData.buttonContext?.selections?.ungrouped['toggleCommentPins']) {
commentElement.showCommentsOnDom();
} else {
commentElement.hideCommentsOnDom();
}
}
}
});
```
```html {6-8} theme={null}
```
**Handle the button click event:**
```js theme={null}
Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.clickedButtonId === 'toggleCommentPins') {
if (veltButtonClickEventData.buttonContext?.selections?.ungrouped['toggleCommentPins']) {
commentElement.showCommentsOnDom();
} else {
commentElement.hideCommentsOnDom();
}
}
}
});
```
### Single Select Button Group
```jsx {6-12} theme={null}
```
**Handle the button click event:**
```jsx theme={null}
// Hook
const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
useEffect(() => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selectedFilter = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selectedFilter?.unread) {
// show unread comments
} else if (selectedFilter?.mentions) {
// show comments with mentions
}
}
}
}, [veltButtonClickEventData]);
// API Method
client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selectedFilter = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selectedFilter?.unread) {
// show unread comments
} else if (selectedFilter?.mentions) {
// show comments with mentions
}
}
}
});
```
```html {6-12} theme={null}
```
**Handle the button click event:**
```js theme={null}
Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selectedFilter = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selectedFilter?.unread) {
// show unread comments
} else if (selectedFilter?.mentions) {
// show comments with mentions
}
}
}
});
```
### Multi Select Button Group
```jsx {6-12} theme={null}
```
**Handle the button click event:**
```jsx theme={null}
// Hook
const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
useEffect(() => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selections?.unread) {
// show unread comments
}
if (selections?.mentions) {
// show comments with mentions
}
}
}
}, [veltButtonClickEventData]);
// API Method
client.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selections?.unread) {
// show unread comments
}
if (selections?.mentions) {
// show comments with mentions
}
}
}
});
```
```html {6-12} theme={null}
```
**Handle the button click event:**
```js theme={null}
Velt.on('veltButtonClick').subscribe(veltButtonClickEventData => {
if (veltButtonClickEventData) {
if (veltButtonClickEventData.buttonContext?.groupId === 'custom-filter') {
const selections = veltButtonClickEventData.buttonContext?.selections?.['custom-filter'];
if (selections?.unread) {
// show unread comments
}
if (selections?.mentions) {
// show comments with mentions
}
}
}
});
```
### Callback Event
The Velt Button Wireframe emits events when users interact with it. You can listen to these events to implement custom behaviors.
* Returns: [VeltButtonClickEvent](/api-reference/sdk/models/data-models#veltbuttonclickevent)
```jsx theme={null}
// Hook
const veltButtonClickEventData = useVeltEventCallback('veltButtonClick');
useEffect(() => {
if (veltButtonClickEventData) {
// Handle button click event response
}
}, [veltButtonClickEventData]);
// API Method
client.on('veltButtonClick').subscribe((veltButtonClickEventData) => {
// Handle button click event response
});
```
```js theme={null}
Velt.on('veltButtonClick').subscribe((veltButtonClickEventData) => {
// Handle button click event response
});
```
### Set Dynamic ID to Velt Button
* You can use template variables to set the id.
```jsx theme={null}
```html theme={null}
### Reset Velt Button State
* Reset the state of Velt Button components programmatically.
* Params: (optional) [VeltResetButtonStateConfig](/api-reference/sdk/models/data-models#veltresetbuttonstateconfig)
```jsx theme={null}
// Reset state for a specific button in a given group
client.resetVeltButtonState({id: 'openSidebar', group: 'multi'});
// Reset state for all buttons in a given group
client.resetVeltButtonState({group: 'multi'});
// Reset state for a specific button in all groups
client.resetVeltButtonState({id: 'openSidebar'});
// Reset state for all buttons
client.resetVeltButtonState();
```
```js theme={null}
// Reset state for a specific button in a given group
Velt.resetVeltButtonState({id: 'openSidebar', group: 'multi'});
// Reset state for all buttons in a given group
Velt.resetVeltButtonState({group: 'multi'});
// Reset state for a specific button in all groups
Velt.resetVeltButtonState({id: 'openSidebar'});
// Reset state for all buttons
Velt.resetVeltButtonState();
```
# Custom Button
Source: https://docs.velt.dev/ui-customization/features/async/arrows/custom-button
## Custom Arrow Button
If you want to replace the default arrow button with your own custom button, you can pass it in as a child component.
```js React / Next.js theme={null}
import { VeltArrowTool } from '@veltdev/react';
function YourComponent() {
return (
//custom arrow button goes here
# Parts
Source: https://docs.velt.dev/ui-customization/features/async/arrows/parts
We offer several parts which can be used like classes. Full list below.
The component is encapsulated in Shadow DOM, which is isolated from the normal DOM.
Set whatever CSS rules you want.
The part lets you target a specific element within a Shadow DOM.
Reference the table below to see what parts we expose.
Alternatively, you can directly inspect the component HTML to see what parts are available.
| property | description |
| ------------------ | ----------------------------------------- |
| `container` | Targets the comment tool container |
| `button-container` | Targets the comment tool button container |
| `button-icon` | Targets the comment tool button SVG icon |
```css Tool theme={null}
velt-arrow-tool::part(button-icon) {
width: 1.5rem;
height: 1.5rem;
}
```
# Slots
Source: https://docs.velt.dev/ui-customization/features/async/arrows/slots
Provide a template for the Arrow Tool.
Target the `button` slot with your own custom template.
```js React / Next.js theme={null}
import {
VeltArrowTool
} from '@veltdev/react';
export default function App() {
return (
<>
Arrow
);
}
```
```html HTML theme={null}
Arrow documentation
Arrow
```
# Variables
Source: https://docs.velt.dev/ui-customization/features/async/arrows/variables
To update CSS variables for the Arrow Tool, please refer to [Global Styles](/global-styles/global-styles)
# Comment Bubble
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-bubble
This button shows the comment count and the author's avatar. This is used in Popover comments feature.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltCommentBubbleWireframe
```jsx theme={null}
```
```html theme={null}
```
## CommentsCount
```jsx theme={null}
```
```html theme={null}
```
## Avatar
```jsx theme={null}
```
```html theme={null}
```
## UnreadIcon
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
```jsx theme={null}
```jsx theme={null}
### Dark Mode
By default, all components are in Light Mode, but there are several properties and methods to enable Dark Mode.
Default: `false`
**Using Props:**
```js theme={null}
**Using Props:**
```HTML theme={null}
### Open Dialog on Click
Control whether the comment dialog opens when the bubble is clicked.
Default: `true`
```jsx theme={null}
```html theme={null}
# Comment Dialog
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog-components
Comments Dialog Component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## Ghost Banner
```jsx theme={null}
```
```html theme={null}
```
## Private Banner
```jsx theme={null}
```
```html theme={null}
```
## Assignee Banner
```jsx theme={null}
```
```html theme={null}
```
### Resolve Button (Assignee Banner)
```jsx theme={null}
```
```html theme={null}
```
### Unresolve Button (Assignee Banner)
```jsx theme={null}
```
```html theme={null}
```
### User Avatar (Assignee Banner)
```jsx theme={null}
```
```html theme={null}
```
### User Name (Assignee Banner)
```jsx theme={null}
```
```html theme={null}
```
## Header
```jsx theme={null}
// Pin Dialog Header
// Sidebar Dialog Header
```
```html theme={null}
```
### Status (Header)
```jsx theme={null}
```
```html theme={null}
```
#### Trigger (Header Status)
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Header Status Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Header Status Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Arrow (Header Status Trigger)**
```jsx theme={null}
```
```html theme={null}
```
#### Content (Header Status)
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Header Status Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Header Status Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Header Status Content Item)**
```jsx theme={null}
```
```html theme={null}
```
### Priority (Header)
```jsx theme={null}
```
```html theme={null}
```
#### Trigger (Header Priority)
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Header Priority Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Header Priority Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Arrow (Header Priority Trigger)**
```jsx theme={null}
```
```html theme={null}
```
#### Content (Header Priority)
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Header Priority Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Header Priority Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Header Priority Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tick (Header Priority Content Item)**
```jsx theme={null}
```
```html theme={null}
```
### Options (Header)
```jsx theme={null}
```
```html theme={null}
```
#### Trigger (Header Options)
```jsx theme={null}
```
```html theme={null}
```
#### Content (Header Options)
```jsx theme={null}
```
```html theme={null}
```
##### **Mark As Read (Header Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Make Private (Header Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Enable (Header Options Content Make Private)**
```jsx theme={null}
```
```html theme={null}
```
##### **Disable (Header Options Content Make Private)**
```jsx theme={null}
```
```html theme={null}
```
##### **Assign (Header Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Edit (Header Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Delete (Header Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Thread (Header Options Content Delete)**
```jsx theme={null}
```
```html theme={null}
```
##### **Comment (Header Options Content Delete)**
```jsx theme={null}
```
```html theme={null}
```
##### **Notification (Header Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Subscribe (Header Options Content Notification)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unsubscribe (Header Options Content Notification)**
```jsx theme={null}
```
```html theme={null}
```
### Copy Link (Header)
```jsx theme={null}
```
```html theme={null}
```
### Resolve Button (Header)
```jsx theme={null}
```
```html theme={null}
```
### Custom Annotation Dropdown (Header)
```jsx theme={null}
```
```html theme={null}
```
#### Trigger (Header Custom Annotation Dropdown)
```jsx theme={null}
```
```html theme={null}
```
##### **List (Header Custom Annotation Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Header Custom Annotation Dropdown Trigger List)**
```jsx theme={null}
```
```html theme={null}
```
##### **Remaining Count (Header Custom Annotation Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Placeholder (Header Custom Annotation Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Arrow (Header Custom Annotation Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
#### Content (Header Custom Annotation Dropdown)
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Header Custom Annotation Dropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Label (Header Custom Annotation Dropdown Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Header Custom Annotation Dropdown Content Item)**
```jsx theme={null}
```
```html theme={null}
```
### Comment Index (Header)
```jsx theme={null}
```
```html theme={null}
```
### Comment Number (Header)
The annotation number displays in the comment dialog header, providing a persistent identifier for each comment that remains constant across sessions. This number makes it easy to reference specific comments in team discussions or documentation.
```jsx theme={null}
```
```html theme={null}
```
### Comment Category (Header)
```jsx theme={null}
```
```html theme={null}
```
### Comment Suggestion Status (Header)
```jsx theme={null}
```
```html theme={null}
```
### Navigation Button (Header)
```jsx theme={null}
```
```html theme={null}
```
## Private Badge
```jsx theme={null}
```
```html theme={null}
```
## Body
```jsx theme={null}
```
```html theme={null}
```
### Threads (Body)
```jsx theme={null}
```
```html theme={null}
```
#### Thread Card (Body Threads)
```jsx theme={null}
```
```html theme={null}
```
##### **Avatar (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unread (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Seen Dropdown (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Body Threads Thread Card Seen Dropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Body Threads Thread Card Seen Dropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Title (Body Threads Thread Card Seen Dropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Items (Body Threads Thread Card Seen Dropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Body Threads Thread Card Seen Dropdown Content Items)**
```jsx theme={null}
```
```html theme={null}
```
##### **Time (Body Threads Thread Card Seen Dropdown Content Items Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Body Threads Thread Card Seen Dropdown Content Items Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Avatar (Body Threads Thread Card Seen Dropdown Content Items Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Time (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Device Type (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Edited (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Options (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Body Threads Thread Card Options)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Body Threads Thread Card Options)**
```jsx theme={null}
```
```html theme={null}
```
##### **Mark As Read (Body Threads Thread Card Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Edit (Body Threads Thread Card Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Delete (Body Threads Thread Card Options Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Thread (Body Threads Thread Card Options Content Delete)**
```jsx theme={null}
```
```html theme={null}
```
##### **Comment (Body Threads Thread Card Options Content Delete)**
```jsx theme={null}
```
```html theme={null}
```
##### **Message (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **EditComposer (Body Threads Thread Card)**
Conditionally renders when a comment is being edited.
```jsx theme={null}
```
```html theme={null}
```
##### **Reaction Tool (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Reactions (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **ReactionPin (Body Threads Thread Card)**
Display a specific reaction as a pinned standalone element.
```jsx theme={null}
```
```html theme={null}
```
**Props**:
* `reactionId` ([`IVeltCommentDialogThreadCardReactionPinProps`](/api-reference/sdk/models/data-models#iveltcommentdialogthreadcardreactionpinprops)): Unique identifier of the reaction to pin and display
##### **Attachments (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Image (Body Threads Thread Card Attachments)**
```jsx theme={null}
```
```html theme={null}
```
##### **Preview (Body Threads Thread Card Attachments Image)**
```jsx theme={null}
```
```html theme={null}
```
##### **Delete (Body Threads Thread Card Attachments Image)**
```jsx theme={null}
```
```html theme={null}
```
##### **Download (Body Threads Thread Card Attachments Image)**
```jsx theme={null}
```
```html theme={null}
```
##### **Other (Body Threads Thread Card Attachments)**
```jsx theme={null}
```
```html theme={null}
```
##### **Delete (Body Threads Thread Card Attachments Other)**
```jsx theme={null}
```
```html theme={null}
```
##### **Download (Body Threads Thread Card Attachments Other)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Body Threads Thread Card Attachments Other)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Body Threads Thread Card Attachments Other)**
```jsx theme={null}
```
```html theme={null}
```
##### **Size (Body Threads Thread Card Attachments Other)**
```jsx theme={null}
```
```html theme={null}
```
##### **Recordings (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Autocomplete Chip Tooltip (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Body Threads Thread Card Autocomplete Chip Tooltip)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Body Threads Thread Card Autocomplete Chip Tooltip)**
```jsx theme={null}
```
```html theme={null}
```
##### **Description (Body Threads Thread Card Autocomplete Chip Tooltip)**
```jsx theme={null}
```
```html theme={null}
```
##### **Reactions Panel (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Items (Body Threads Thread Card Reactions Panel)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Body Threads Thread Card Reactions Panel Items)**
```jsx theme={null}
```
```html theme={null}
```
##### **Emoji (Body Threads Thread Card Reactions Panel Items Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Reaction Pin (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Emoji (Body Threads Thread Card Reaction Pin)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Body Threads Thread Card Reaction Pin)**
```jsx theme={null}
```
```html theme={null}
```
##### **Reaction Pin Tooltip (Body Threads Thread Card)**
```jsx theme={null}
```
```html theme={null}
```
##### **Users (Body Threads Thread Card Reaction Pin Tooltip)**
```jsx theme={null}
```
```html theme={null}
```
##### **User (Body Threads Thread Card Reaction Pin Tooltip Users)**
```jsx theme={null}
```
```html theme={null}
```
##### **Avatar (Body Threads Thread Card Reaction Pin Tooltip Users User)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Body Threads Thread Card Reaction Pin Tooltip Users User)**
```jsx theme={null}
```
```html theme={null}
```
##### **Reaction Tool (Body Threads Thread Card)**
```jsx theme={null}
{/* Your custom element */}
```
```html theme={null}
```
##### **Reply (Body Threads Thread Card)**
The Reply component provides a quick reply button on each comment thread card, enabling users to respond directly without expanding the full comment dialog. This streamlines the commenting workflow in collaborative environments.
This button is hidden by default and can be enabled through wireframe customization.
```jsx theme={null}
```
```html theme={null}
```
##### **Assign Button (Body Threads Thread Card)**
The Assign Button component allows you to customize the assign button that appears on individual comment thread cards.
```jsx theme={null}
```
```html theme={null}
```
#### MoreReply (Body Threads)
```jsx theme={null}
```
```html theme={null}
```
### Reply Avatars (Body)
```jsx theme={null}
```
```html theme={null}
```
#### List (Body Reply Avatars)
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Body Reply Avatars List)**
```jsx theme={null}
```
```html theme={null}
```
#### Remaining Count (Body Reply Avatars)
```jsx theme={null}
```
```html theme={null}
```
### Toggle Reply (Body)
```jsx theme={null}
```
```html theme={null}
```
#### Icon (Body Toggle Reply)
```jsx theme={null}
```
```html theme={null}
```
#### Count (Body Toggle Reply)
```jsx theme={null}
```
```html theme={null}
```
#### Text (Body Toggle Reply)
```jsx theme={null}
```
```html theme={null}
```
### Hide Reply (Body)
The Hide Reply component adds a button to hide replies in the comment dialog, letting you control when replies are visible to match your workflow.
```jsx theme={null}
```
```html theme={null}
```
## Composer
```jsx theme={null}
```
```html theme={null}
```
### Avatar (Composer)
```jsx theme={null}
```
```html theme={null}
```
### Attachments (Composer)
```jsx theme={null}
```
```html theme={null}
```
#### Selected (Composer Attachments)
```jsx theme={null}
```
```html theme={null}
```
##### **Image (Composer Attachments Selected)**
```jsx theme={null}
```
```html theme={null}
```
##### **Other (Composer Attachments Selected)**
```jsx theme={null}
```
```html theme={null}
```
#### Invalid (Composer Attachments)
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Composer Attachments Invalid)**
```jsx theme={null}
```
```html theme={null}
```
### Recordings (Composer)
```jsx theme={null}
```
```html theme={null}
```
### Input (Composer)
```jsx theme={null}
```
```html theme={null}
```
### Format Toolbar (Composer)
The format toolbar contains text formatting buttons (bold, italic, underline, strikethrough).
```jsx theme={null}
```
```html theme={null}
```
#### Button (Composer Format Toolbar)
Individual format button with type: `bold`, `italic`, `underline`, or `strikethrough`.
```jsx theme={null}
```
```html theme={null}
```
### Action Button (Composer)
Supports types: `autocomplete`, `file`, `attachments`, `audio`, `video`, `screen`, `format`, `submit`.
```jsx theme={null}
```
```html theme={null}
```
### Assign User (Composer)
```jsx theme={null}
```
```html theme={null}
```
### Visibility Dropdown (Composer)
```jsx theme={null}
```
```html theme={null}
```
#### Trigger (Composer Visibility Dropdown)
```jsx theme={null}
```
```html theme={null}
```
##### **Label (Composer Visibility Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Composer Visibility Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
#### Content (Composer Visibility Dropdown)
```jsx theme={null}
```
```html theme={null}
```
##### **Public (Composer Visibility Dropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Private (Composer Visibility Dropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
### Autocomplete Option (Composer)
For standalone autocomplete primitive components (e.g., `VeltAutocompleteOption`, `VeltAutocompleteChip`), see the [Autocomplete Primitives](/ui-customization/features/async/comments/comment-dialog-primitives/overview#veltautocomplete) section.
```jsx theme={null}
```
```html theme={null}
```
#### Icon (Composer Autocomplete Option)
```jsx theme={null}
```
```html theme={null}
```
#### Name (Composer Autocomplete Option)
```jsx theme={null}
```
```html theme={null}
```
#### Description (Composer Autocomplete Option)
```jsx theme={null}
```
```html theme={null}
```
#### Error Icon (Composer Autocomplete Option)
```jsx theme={null}
```
```html theme={null}
```
### Autocomplete Group Option (Composer)
```jsx theme={null}
```
```html theme={null}
```
## Visibility Banner
Displays below the composer to let users set per-comment visibility. The `selectedVisibility` data variable exposes the current [`CommentVisibilityOptionType`](/api-reference/sdk/models/data-models#commentvisibilityoptiontype).
```jsx theme={null}
```
```html theme={null}
```
### Icon (Visibility Banner)
```jsx theme={null}
```
```html theme={null}
```
### Text (Visibility Banner)
```jsx theme={null}
```
```html theme={null}
```
### Dropdown (Visibility Banner)
```jsx theme={null}
```
```html theme={null}
```
#### Trigger (Visibility Banner Dropdown)
```jsx theme={null}
```
```html theme={null}
```
##### **Label (Visibility Banner Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **AvatarList (Visibility Banner Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
**Item (Visibility Banner Dropdown Trigger AvatarList)**
```jsx theme={null}
```
```html theme={null}
```
**RemainingCount (Visibility Banner Dropdown Trigger AvatarList)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Visibility Banner Dropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
#### Content (Visibility Banner Dropdown)
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Visibility Banner Dropdown Content)**
Accepts `type`: `'public' | 'org-users' | 'personal' | 'selected-people'`.
```jsx theme={null}
```
```html theme={null}
```
**Icon (Visibility Banner Dropdown Content Item)**
```jsx theme={null}
```
```html theme={null}
```
**Label (Visibility Banner Dropdown Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **UserPicker (Visibility Banner Dropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
**Search (Visibility Banner Dropdown Content UserPicker)**
```jsx theme={null}
```
```html theme={null}
```
**Icon (Visibility Banner Dropdown Content UserPicker Search)**
```jsx theme={null}
```
```html theme={null}
```
**Input (Visibility Banner Dropdown Content UserPicker Search)**
```jsx theme={null}
```
```html theme={null}
```
**Header (Visibility Banner Dropdown Content UserPicker)**
```jsx theme={null}
```
```html theme={null}
```
**Count (Visibility Banner Dropdown Content UserPicker Header)**
```jsx theme={null}
```
```html theme={null}
```
**UnselectAll (Visibility Banner Dropdown Content UserPicker Header)**
```jsx theme={null}
```
```html theme={null}
```
**Item (Visibility Banner Dropdown Content UserPicker)**
```jsx theme={null}
```
```html theme={null}
```
**Avatar (Visibility Banner Dropdown Content UserPicker Item)**
```jsx theme={null}
```
```html theme={null}
```
**Info (Visibility Banner Dropdown Content UserPicker Item)**
```jsx theme={null}
```
```html theme={null}
```
**Check (Visibility Banner Dropdown Content UserPicker Item)**
```jsx theme={null}
```
```html theme={null}
```
## All Comment
```jsx theme={null}
```
```html theme={null}
```
## Approve
```jsx theme={null}
```
```html theme={null}
```
## Sign In
```jsx theme={null}
```
```html theme={null}
```
## Upgrade
```jsx theme={null}
```
```html theme={null}
```
## Suggestion Action
```jsx theme={null}
```
```html theme={null}
```
### Accept (Suggestion Action)
```jsx theme={null}
```
```html theme={null}
```
### Reject (Suggestion Action)
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
##### **Example**
```jsx theme={null}
##### **Example**
```
### Dark Mode
##### **Example**
```js theme={null}
```
##### **API methods**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableDarkMode();
commentElement.disableDarkMode();
```
##### **Example**
```js theme={null}
## Pre-defined Variants
The Comment Dialog has 2 pre-defined variants:
* `dialog`: this will customize the Comment Dialog only within Pin, Area, and Text Comments
* `sidebar`: this will customize the Comment Dialog only within Sidebar comments
To use them, set the `variant` name in the wireframe template equal to one of the pre-defined variants. You do not need to add it to the actual Velt component.
```jsx React / Next.js theme={null}
{/* This pre-defined variant will change the appearance of the Comment Dialog within Pin, Area, and Text comments only */}
...
{/* This pre-defined variant will change the appearance of the Comment Dialog within the Sidebar only */}
...
{/* If you dont use any variants, then customization will be applied to the Comment Dialog globally */}
...
```
```jsx Other Frameworks theme={null}
```
# Comment Dialog Primitives
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog-primitives/overview
92+ primitive components for building custom Comment Dialog interfaces with maximum flexibility.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
The Comment Dialog Primitives API provides 92+ granular components that can be used independently to build completely custom comment interfaces. Each primitive can be used standalone or composed together for maximum customization flexibility.
## Usage Patterns
### Pattern 1: Context Wrapper (Recommended)
Components are wrapped in a context wrapper that provides shared context to children.
```jsx theme={null}
```
```html theme={null}
```
### Pattern 2: ID-Based (Standalone)
Each component receives `annotationId` directly and works independently.
```jsx theme={null}
```html theme={null}
## Common Inputs
All components inherit these base inputs. See [`CommentDialogCommonProps`](/api-reference/sdk/models/data-models#commentdialogcommonprops) for the type definition.
| React Prop | HTML Attribute | Type | Default | Description |
| -------------------------- | ----------------------------- | --------- | ------- | --------------------------- |
| `annotationId` | `annotation-id` | `string` | - | The annotation ID |
| `defaultCondition` | `default-condition` | `boolean` | `true` | When false, always shows |
| `inlineCommentSectionMode` | `inline-comment-section-mode` | `boolean` | `false` | Inline comment section mode |
| `commentPinSelected` | `comment-pin-selected` | `boolean` | `false` | Comment pin selected state |
| `fullExpanded` | `full-expanded` | `boolean` | `false` | Full expansion state |
***
## Components
### VeltCommentDialogContextWrapper
Context wrapper that provides shared annotation context to child primitives.
Props: [`CommentDialogContextWrapperProps`](/api-reference/sdk/models/data-models#commentdialogcontextwrapperprops)
```jsx theme={null}
{children}
```
**Props:**
| Prop | Type | Required | Description |
| -------------------- | --------- | ---------- | --------------------------------------- |
| `annotationId` | `string` | Yes (root) | Annotation ID for children |
| `commentId` | `string` | No | Comment ID for children |
| `attachmentId` | `string` | No | Attachment ID for children |
| `commentPinSelected` | `boolean` | No | Selection state for children |
| `[key: string]` | `any` | No | Any custom attribute passed via context |
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| ---------------------- | -------- | ---------- | -------------------------------- |
| `annotation-id` | `string` | Yes (root) | Annotation ID for children |
| `comment-id` | `string` | No | Comment ID for children |
| `attachment-id` | `string` | No | Attachment ID for children |
| `comment-pin-selected` | `string` | No | Selection state ("true"/"false") |
***
### VeltCommentDialogHeader
Header component for the comment dialog.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogBody
Body container for the comment dialog thread content.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogThreadCard
Complete thread card with all comment metadata and content. See [`ThreadCardProps`](/api-reference/sdk/models/data-models#threadcardprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | --------------- | -------- | ------------------------------------ |
| `comment-obj` | `string (JSON)` | No | Direct comment object (Priority 1) |
| `comment-id` | `string` | No | Comment ID for lookup (Priority 2) |
| `comment-index` | `string` | No | Index in comments array (Priority 3) |
***
### VeltCommentDialogThreadCardAvatar
User avatar for the comment author. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardName
Display name of the comment author. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardTime
Timestamp of when the comment was created. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardMessage
The comment message content. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardReactions
Reactions display for the comment. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardReactionTool
Tool for adding reactions to a comment. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardRecordings
Recordings attached to the comment. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardReply
Reply indicator for the thread card.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogThreadCardUnread
Unread indicator for the comment. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardEdited
Edited indicator for the comment. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardDraft
Draft indicator for the comment. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardDeviceType
Device type indicator for the comment. See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogThreadCardOptions
Options menu for the comment (edit, delete, etc.). See [`CommentIndexProps`](/api-reference/sdk/models/data-models#commentindexprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------- |
| `comment-index` | `string` | No | Index of comment in array |
***
### VeltCommentDialogComposer
Complete composer with input, attachments, and action buttons. See [`ComposerProps`](/api-reference/sdk/models/data-models#composerprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| ---------------------------- | --------------- | -------- | --------------------------------------------- |
| `placeholder` | `string` | No | Primary placeholder (Priority 1) |
| `commentplaceholder` | `string` | No | Placeholder for new comment |
| `replyplaceholder` | `string` | No | Placeholder for reply |
| `editplaceholder` | `string` | No | Placeholder for edit mode |
| `edit-mode` | `string` | No | Enable edit mode ("true"/"false") |
| `comment-obj` | `string (JSON)` | No | Comment object for edit mode |
| `comment-index` | `string` | No | Index of comment being edited |
| `target-composer-element-id` | `string` | No | Unique identifier for programmatic submission |
| `context` | `string (JSON)` | No | Custom context data to attach to comment |
***
### VeltCommentDialogComposerInput
Text input field for composing comments. See [`ComposerInputProps`](/api-reference/sdk/models/data-models#composerinputprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| ------------- | -------- | -------- | ---------------------- |
| `placeholder` | `string` | No | Input placeholder text |
***
### VeltCommentDialogComposerActionButton
Submit/send button for the composer.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogComposerAttachmentButton
Button to add file attachments to comments.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogComposerRecorderButton
Button to add audio/video recordings.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogComposerRecorderPlayer
Player for audio/video recordings in the composer.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogComposerFiles
Files display in the composer.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdown
Complete status dropdown with trigger and content.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdownTrigger
Button that opens the status dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdownTriggerIcon
Icon for the status dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdownTriggerName
Name display for the status dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdownTriggerArrow
Arrow indicator for the status dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdownContent
Dropdown content container for status options.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdownContentItem
Individual status item in the dropdown. See [`StatusDropdownItemProps`](/api-reference/sdk/models/data-models#statusdropdownitemprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| -------------- | --------------- | -------- | ------------------------------------ |
| `status-obj` | `string (JSON)` | No | Direct status object (Priority 1) |
| `status-id` | `string` | No | Status ID for lookup (Priority 2) |
| `status-index` | `string` | No | Index in statuses array (Priority 3) |
***
### VeltCommentDialogStatusDropdownContentItemIcon
Icon for a status dropdown item.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatusDropdownContentItemName
Name display for a status dropdown item.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdown
Complete priority dropdown with trigger and content.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownTrigger
Button that opens the priority dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownTriggerIcon
Icon for the priority dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownTriggerName
Name display for the priority dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownTriggerArrow
Arrow indicator for the priority dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownContent
Dropdown content container for priority options.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownContentItem
Individual priority item in the dropdown. See [`PriorityDropdownItemProps`](/api-reference/sdk/models/data-models#prioritydropdownitemprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| ---------------- | --------------- | -------- | -------------------------------------- |
| `priority-obj` | `string (JSON)` | No | Direct priority object (Priority 1) |
| `priority-id` | `string` | No | Priority ID for lookup (Priority 2) |
| `priority-index` | `string` | No | Index in priorities array (Priority 3) |
***
### VeltCommentDialogPriorityDropdownContentItemIcon
Icon for a priority dropdown item.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownContentItemName
Name display for a priority dropdown item.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriorityDropdownContentItemTick
Tick/checkmark for a priority dropdown item.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdown
Options menu for actions like assignment, editing, and notifications. See [`OptionsDropdownProps`](/api-reference/sdk/models/data-models#optionsdropdownprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| ---------------------------------- | -------- | -------- | --------------------------------- |
| `comment-index` | `string` | No | Index of comment for options |
| `enable-assignment` | `string` | No | Enable assignment option |
| `allow-assignment` | `string` | No | V4 alias for enable-assignment |
| `enable-edit` | `string` | No | Enable edit option |
| `allow-edit` | `string` | No | V4 alias for enable-edit |
| `enable-notifications` | `string` | No | Enable notifications option |
| `allow-notifications` | `string` | No | V4 alias for enable-notifications |
| `allow-toggle-notification` | `string` | No | V4 alias for enable-notifications |
| `enable-private-mode` | `string` | No | Enable private mode option |
| `allow-private-mode` | `string` | No | V4 alias for enable-private-mode |
| `allow-change-comment-access-mode` | `string` | No | V4 alias for enable-private-mode |
| `enable-mark-as-read` | `string` | No | Enable mark as read option |
| `allow-mark-as-read` | `string` | No | V4 alias for enable-mark-as-read |
***
### VeltCommentDialogOptionsDropdownTrigger
Trigger button for the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContent
Content container for the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentAssign
Assign option in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentEdit
Edit option in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentDelete
Delete option in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentDeleteComment
Delete comment option in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentDeleteThread
Delete thread option in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentMakePrivate
Make private option container in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentMakePrivateEnable
Enable private mode option.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentMakePrivateDisable
Disable private mode option.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentNotification
Notification option container in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentNotificationSubscribe
Subscribe to notifications option.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentNotificationUnsubscribe
Unsubscribe from notifications option.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentMarkAsRead
Mark as read option container in the options dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentMarkAsReadMarkRead
Mark as read action option.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptionsDropdownContentMarkAsReadMarkUnread
Mark as unread action option.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdown
Custom annotation dropdown component.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownTrigger
Trigger button for the custom annotation dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownTriggerArrow
Arrow indicator for the custom annotation dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownTriggerList
List container for the custom annotation dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownTriggerListItem
Individual item in the custom annotation dropdown trigger list. See [`CustomAnnotationItemProps`](/api-reference/sdk/models/data-models#customannotationitemprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------- | --------------- | -------- | ---------------- |
| `item` | `string (JSON)` | No | Item data object |
| `index` | `string` | No | Item index |
***
### VeltCommentDialogCustomAnnotationDropdownTriggerPlaceholder
Placeholder for the custom annotation dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownTriggerRemainingCount
Remaining count indicator for the custom annotation dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownContent
Content container for the custom annotation dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownContentItem
Individual item in the custom annotation dropdown content. See [`CustomAnnotationItemProps`](/api-reference/sdk/models/data-models#customannotationitemprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------- | --------------- | -------- | ---------------- |
| `item` | `string (JSON)` | No | Item data object |
| `index` | `string` | No | Item index |
***
### VeltCommentDialogCustomAnnotationDropdownContentItemIcon
Icon for a custom annotation dropdown item.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdownContentItemLabel
Label for a custom annotation dropdown item.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogReplyAvatars
Container for reply avatars.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogReplyAvatarsList
List container for reply avatars.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogReplyAvatarsListItem
Individual avatar item in the reply avatars list. See [`ReplyAvatarsListItemProps`](/api-reference/sdk/models/data-models#replyavatarslistitemprops).
```jsx theme={null}
```html theme={null}
```
**Attributes:**
| Attribute | Type | Required | Description |
| --------- | --------------- | -------- | --------------------- |
| `user` | `string (JSON)` | Yes | User data object |
| `index` | `string` | Yes | Index of user in list |
***
### VeltCommentDialogReplyCount
Reply count display.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAssigneeBanner
Assignee banner container.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAssigneeBannerResolved
Resolved state of the assignee banner.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAssigneeBannerUnresolved
Unresolved state of the assignee banner.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAssigneeBannerUnresolveButton
Button to unresolve the assignee banner.
```jsx theme={null}
```html theme={null}
***
### VeltAutocomplete
To customize the **wireframe appearance** of autocomplete options, chips, and tooltips, see the [Autocomplete Option](/ui-customization/features/async/comments/comment-dialog-components#autocomplete-option-composer) and [Autocomplete Chip Tooltip](/ui-customization/features/async/comments/comment-dialog-components#autocomplete-chip-tooltip-body-threads-thread-card) sections in the Comment Dialog Components page.
The autocomplete panel component accepts the following props for controlling selection mode, ordering, and data source.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteEmptyWireframe
Customize the empty state shown when the autocomplete panel has no results. This is a wireframe component — for more wireframe customization patterns, see the [Comment Dialog Components](/ui-customization/features/async/comments/comment-dialog-components) page.
```jsx theme={null}
import { VeltWireframe, VeltAutocompleteEmptyWireframe } from '@veltdev/react';
No results found
```
```html theme={null}
No results found
```
***
### VeltAutocompleteChip
Standalone autocomplete chip component for rendering selected contact chips.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteOption
Standalone autocomplete option component for rendering contact/custom options.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteOptionDescription
Standalone autocomplete option description component.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteOptionIcon
Icon for an autocomplete option.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteOptionName
Name display for an autocomplete option.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteOptionErrorIcon
Error icon for an autocomplete option.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteGroupOption
Group option in the autocomplete panel.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteTool
Tool component for the autocomplete panel.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteEmpty
Empty state for the autocomplete panel.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteChipTooltip
Tooltip for an autocomplete chip.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteChipTooltipIcon
Icon within the autocomplete chip tooltip.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteChipTooltipName
Name display within the autocomplete chip tooltip.
```jsx theme={null}
```html theme={null}
***
### VeltAutocompleteChipTooltipDescription
Description within the autocomplete chip tooltip.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogResolveButton
Button to resolve a comment thread.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogUnresolveButton
Button to unresolve a comment thread.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCopyLink
Button to copy the comment link to clipboard.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCloseButton
Button to close the comment dialog.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogDeleteButton
Button to delete a comment.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPrivateBanner
Banner indicating a comment's private status.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPrivateButton
Button to toggle private mode on a comment.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogGhostBanner
Banner displayed for ghost or anonymous comments.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBanner
Banner displaying the current visibility setting for a comment.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerIcon
Icon within the visibility banner.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerText
Text label within the visibility banner.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdown
Dropdown for selecting visibility options within the banner.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownTrigger
Trigger element for the visibility dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownTriggerLabel
Label text within the visibility dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownTriggerAvatarList
Avatar list within the visibility dropdown trigger showing selected users.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownTriggerAvatarListItem
Individual avatar within the trigger avatar list.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownTriggerAvatarListRemainingCount
Count of remaining avatars not displayed in the trigger list.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownTriggerIcon
Icon within the visibility dropdown trigger.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContent
Content container for the visibility dropdown options.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentItemIcon
Icon for a visibility option item in the dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentItemLabel
Label for a visibility option item in the dropdown.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPicker
User picker for selecting specific users when visibility is set to `selected-people`.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerSearch
Search container within the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerSearchIcon
Search icon within the user picker search.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerSearchInput
Search input field within the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerHeader
Header section of the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerHeaderCount
Count of selected users displayed in the user picker header.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerHeaderUnselectAll
Button to unselect all users in the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerItem
Individual user item within the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerItemAvatar
Avatar for a user item in the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerItemInfo
Info text for a user item in the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogVisibilityBannerDropdownContentUserPickerItemCheck
Check indicator for a selected user in the user picker.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogSignIn
Sign-in prompt displayed to unauthenticated users.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogNavigationButton
Button for navigating between comments.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAttachmentButton
Button for adding file attachments to a comment.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogDeviceTypeIcons
Icons indicating the device type used when the comment was created.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCommentIndex
Display for the comment's index position.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCommentNumber
Display for the comment's number.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCommentCategory
Display for the comment's category.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogMetadata
Display for comment metadata.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogThreads
Container for the comment threads.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAllComment
View for displaying all comments.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogApprove
Approve button for comment approval workflows.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogUpgrade
Upgrade prompt component.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogMoreReply
Indicator showing additional replies are available.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogHideReply
Button to hide replies in a thread.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogToggleReply
Toggle control for showing or hiding replies.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogToggleReplyShow
Show-replies variant of the reply toggle.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogToggleReplyHide
Hide-replies variant of the reply toggle.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogToggleReplyCount
Reply count displayed within the reply toggle.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogSuggestionAction
Container for suggestion accept/reject actions.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogSuggestionActionAccept
Button to accept a suggestion.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogSuggestionActionReject
Button to reject a suggestion.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCommentSuggestionStatus
Status indicator for a comment suggestion.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAssignDropdown
Dropdown for assigning a comment to a user.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogAssignMenu
Menu for assignment options.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogOptions
Options menu for the comment thread.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogPriority
Priority selector for the comment.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogStatus
Status selector for the comment.
```jsx theme={null}
```html theme={null}
***
### VeltCommentDialogCustomAnnotationDropdown
Dropdown for custom annotation categories.
```jsx theme={null}
```html theme={null}
***
## Notes
* **Attribute Naming:** HTML uses kebab-case, React uses camelCase
* **Boolean Values:** HTML uses "true"/"false" strings, React uses actual booleans
* **Object Values:** HTML uses JSON strings, React uses actual objects
* **Required vs Optional:** `annotationId` is required when using standalone mode, not required inside context wrapper
## API Reference
* [Comment Dialog Primitives API](/api-reference/sdk/api/api-methods#comment-dialog-primitives)
* [Data Models](/api-reference/sdk/models/data-models#comment-dialog-primitives)
# Comment Dialog — Structure
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog-structure
Canonical structure for the Velt Comment Dialog Wireframe (React & HTML mirrors). Order follows your provided JSX/HTML. Parent/child is defined only by the extension path. Direct children are marked with (Leaf) when they have no descendants.
> **Conventions**
>
> * **React names** use `PascalCase` under the `VeltCommentDialogWireframe` namespace.
> * **Parent/child** is determined **only** by the extension path (`A.B` → `B` is a child of `A`). Visual placement (e.g., inside `Header`) does not imply hierarchy.
> * **HTML names** mirror React 1:1 in `kebab-case`.
> * **(Leaf)** = component has no children in this wireframe.
***
## React
`VeltCommentDialogWireframe`
### `VeltCommentDialogWireframe.GhostBanner`
*(no direct children)*
***
### `VeltCommentDialogWireframe.PrivateBanner`
*(no direct children)*
***
### `VeltCommentDialogWireframe.AssigneeBanner`
* `VeltCommentDialogWireframe.AssigneeBanner.ResolveButton` **(Leaf)**
* `VeltCommentDialogWireframe.AssigneeBanner.UnresolveButton` **(Leaf)**
* `VeltCommentDialogWireframe.AssigneeBanner.UserAvatar` **(Leaf)**
* `VeltCommentDialogWireframe.AssigneeBanner.UserName` **(Leaf)**
***
### `VeltCommentDialogWireframe.Header`
***
### `VeltCommentDialogWireframe.CommentNumber` **(Leaf)**
***
### `VeltCommentDialogWireframe.Status`
***
### `VeltCommentDialogWireframe.Priority`
***
### `VeltCommentDialogWireframe.Options`
* `VeltCommentDialogWireframe.Options.Trigger` **(Leaf)**
* `VeltCommentDialogWireframe.Options.Content`
#### `VeltCommentDialogWireframe.Options.Content`
* `VeltCommentDialogWireframe.Options.Content.MarkAsRead` **(Leaf)**
* `VeltCommentDialogWireframe.Options.Content.MakePrivate`
* `VeltCommentDialogWireframe.Options.Content.Assign` **(Leaf)**
* `VeltCommentDialogWireframe.Options.Content.Edit` **(Leaf)**
* `VeltCommentDialogWireframe.Options.Content.Delete`
* `VeltCommentDialogWireframe.Options.Content.Notification`
***
### `VeltCommentDialogWireframe.CopyLink`
***
### `VeltCommentDialogWireframe.ResolveButton`
***
### `VeltCommentDialogWireframe.CustomAnnotationDropdown`
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger`
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Content`
#### `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger`
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger.List`
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger.RemainingCount` **(Leaf)**
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger.Placeholder` **(Leaf)**
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger.Arrow` **(Leaf)**
#### `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger.List`
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Trigger.List.Item` **(Leaf)**
#### `VeltCommentDialogWireframe.CustomAnnotationDropdown.Content`
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Content.Item`
#### `VeltCommentDialogWireframe.CustomAnnotationDropdown.Content.Item`
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Content.Item.Label` **(Leaf)**
* `VeltCommentDialogWireframe.CustomAnnotationDropdown.Content.Item.Icon` **(Leaf)**
***
### `VeltCommentDialogWireframe.CommentIndex`
***
### `VeltCommentDialogWireframe.CommentCategory`
***
### `VeltCommentDialogWireframe.CommentSuggestionStatus`
***
### `VeltCommentDialogWireframe.NavigationButton`
***
### `VeltCommentDialogWireframe.PrivateBadge`
***
### `VeltCommentDialogWireframe.Body`
### `VeltCommentDialogWireframe.Threads`
### `VeltCommentDialogWireframe.ThreadCard`
#### `VeltCommentDialogWireframe.ThreadCard`
* `VeltCommentDialogWireframe.ThreadCard.Avatar` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Name` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Unread` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown`
* `VeltCommentDialogWireframe.ThreadCard.Time` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.DeviceType` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Options`
* `VeltCommentDialogWireframe.ThreadCard.Message` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.EditComposer`
* `VeltCommentDialogWireframe.ThreadCard.ReactionTool` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Reactions` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Attachments`
* `VeltCommentDialogWireframe.ThreadCard.Recordings` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Reply` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.AssignButton` **(Leaf)**
##### `VeltCommentDialogWireframe.ThreadCard.Options`
* `VeltCommentDialogWireframe.ThreadCard.Options.Trigger` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Options.Content`
##### `VeltCommentDialogWireframe.ThreadCard.Options.Content`
* `VeltCommentDialogWireframe.ThreadCard.Options.Content.MarkAsRead` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Options.Content.MakePrivate`
* `VeltCommentDialogWireframe.ThreadCard.Options.Content.Assign` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Options.Content.Edit` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Options.Content.Delete`
* `VeltCommentDialogWireframe.ThreadCard.Options.Content.Notification`
##### `VeltCommentDialogWireframe.ThreadCard.EditComposer`
*(no direct children)*
##### `VeltCommentDialogWireframe.ThreadCard.SeenDropdown`
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Trigger` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content`
##### `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content`
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Title` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Items`
##### `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Items`
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Items.Item`
##### `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Items.Item`
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Items.Item.Time` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Items.Item.Name` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.SeenDropdown.Content.Items.Item.Avatar` **(Leaf)**
##### `VeltCommentDialogWireframe.ThreadCard.Attachments`
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Image`
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Other`
##### `VeltCommentDialogWireframe.ThreadCard.Attachments.Image`
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Image.Preview` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Image.Delete` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Image.Download` **(Leaf)**
##### `VeltCommentDialogWireframe.ThreadCard.Attachments.Other`
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Other.Delete` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Other.Download` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Other.Icon` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Other.Name` **(Leaf)**
* `VeltCommentDialogWireframe.ThreadCard.Attachments.Other.Size` **(Leaf)**
### `VeltCommentDialogWireframe.ReplyAvatars`
#### `VeltCommentDialogWireframe.ReplyAvatars`
* `VeltCommentDialogWireframe.ReplyAvatars.List`
* `VeltCommentDialogWireframe.ReplyAvatars.RemainingCount` **(Leaf)**
##### `VeltCommentDialogWireframe.ReplyAvatars.List`
* `VeltCommentDialogWireframe.ReplyAvatars.List.Item` **(Leaf)**
### `VeltCommentDialogWireframe.ToggleReply`
#### `VeltCommentDialogWireframe.ToggleReply`
* `VeltCommentDialogWireframe.ToggleReply.Icon` **(Leaf)**
* `VeltCommentDialogWireframe.ToggleReply.Count` **(Leaf)**
* `VeltCommentDialogWireframe.ToggleReply.Text` **(Leaf)**
***
### `VeltCommentDialogWireframe.HideReply`
#### `VeltCommentDialogWireframe.HideReply`
*(no direct children)*
***
### `VeltCommentDialogWireframe.Composer`
* `VeltCommentDialogWireframe.Composer.Avatar` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments`
* `VeltCommentDialogWireframe.Composer.Recordings` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Input` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.ActionButton` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.AssignUser` **(Leaf)**
#### `VeltCommentDialogWireframe.Composer.Attachments`
* `VeltCommentDialogWireframe.Composer.Attachments.Selected`
* `VeltCommentDialogWireframe.Composer.Attachments.Invalid`
##### `VeltCommentDialogWireframe.Composer.Attachments.Selected`
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Image`
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Other`
##### `VeltCommentDialogWireframe.Composer.Attachments.Selected.Image`
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Image.Preview` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Image.Delete` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Image.Loading` **(Leaf)**
##### `VeltCommentDialogWireframe.Composer.Attachments.Selected.Other`
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Other.Delete` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Other.Loading` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Other.Icon` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Other.Name` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Selected.Other.Size` **(Leaf)**
##### `VeltCommentDialogWireframe.Composer.Attachments.Invalid`
* `VeltCommentDialogWireframe.Composer.Attachments.Invalid.Item`
##### `VeltCommentDialogWireframe.Composer.Attachments.Invalid.Item`
* `VeltCommentDialogWireframe.Composer.Attachments.Invalid.Item.Preview` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Invalid.Item.Message` **(Leaf)**
* `VeltCommentDialogWireframe.Composer.Attachments.Invalid.Item.Delete` **(Leaf)**
***
### `VeltCommentDialogWireframe.VisibilityBanner`
* `VeltCommentDialogWireframe.VisibilityBanner.Icon` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Text` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown`
#### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content`
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger.Label` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger.AvatarList`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger.Icon` **(Leaf)**
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger.AvatarList`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger.AvatarList.Item` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Trigger.AvatarList.RemainingCount` **(Leaf)**
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.Item` (accepts `type`: `'public'` | `'org-users'` | `'personal'` | `'selected-people'`)
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker`
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.Item`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.Item.Icon` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.Item.Label` **(Leaf)**
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Search`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Header`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Item`
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Search`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Search.Icon` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Search.Input` **(Leaf)**
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Header`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Header.Count` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Header.UnselectAll` **(Leaf)**
##### `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Item`
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Item.Avatar` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Item.Info` **(Leaf)**
* `VeltCommentDialogWireframe.VisibilityBanner.Dropdown.Content.UserPicker.Item.Check` **(Leaf)**
***
### `VeltCommentDialogWireframe.AllComment`
***
### `VeltCommentDialogWireframe.Approve`
***
### `VeltCommentDialogWireframe.SignIn`
***
### `VeltCommentDialogWireframe.Upgrade`
***
### `VeltCommentDialogWireframe.SuggestionAction`
* `VeltCommentDialogWireframe.SuggestionAction.Accept` **(Leaf)**
* `VeltCommentDialogWireframe.SuggestionAction.Reject` **(Leaf)**
***
## HTML (1:1 mirror)
`velt-comment-dialog-wireframe`
### `velt-comment-dialog-ghost-banner-wireframe`
*(no direct children)*
***
### `velt-comment-dialog-private-banner-wireframe`
*(no direct children)*
***
### `velt-comment-dialog-assignee-banner-wireframe`
* `velt-comment-dialog-assignee-banner-resolve-button-wireframe` **(Leaf)**
* `velt-comment-dialog-assignee-banner-unresolve-button-wireframe` **(Leaf)**
* `velt-comment-dialog-assignee-banner-user-avatar-wireframe` **(Leaf)**
* `velt-comment-dialog-assignee-banner-user-name-wireframe` **(Leaf)**
***
### `velt-comment-dialog-header-wireframe`
*(no direct children)*
***
### `velt-comment-dialog-comment-number-wireframe` **(Leaf)**
***
### `velt-comment-dialog-status-wireframe`
***
### `velt-comment-dialog-priority-wireframe`
***
### `velt-comment-dialog-options-wireframe`
* `velt-comment-dialog-options-trigger-wireframe` **(Leaf)**
* `velt-comment-dialog-options-content-wireframe`
#### `velt-comment-dialog-options-content-wireframe`
* `velt-comment-dialog-options-content-mark-as-read-wireframe` **(Leaf)**
* `velt-comment-dialog-options-content-make-private-wireframe`
* `velt-comment-dialog-options-content-assign-wireframe` **(Leaf)**
* `velt-comment-dialog-options-content-edit-wireframe` **(Leaf)**
* `velt-comment-dialog-options-content-delete-wireframe`
* `velt-comment-dialog-options-content-notification-wireframe`
***
### `velt-comment-dialog-copy-link-wireframe`
***
### `velt-comment-dialog-resolve-button-wireframe`
***
### `velt-comment-dialog-custom-annotation-dropdown-wireframe`
* `velt-comment-dialog-custom-annotation-dropdown-trigger-wireframe`
* `velt-comment-dialog-custom-annotation-dropdown-content-wireframe`
#### `velt-comment-dialog-custom-annotation-dropdown-trigger-wireframe`
* `velt-comment-dialog-custom-annotation-dropdown-trigger-list-wireframe`
* `velt-comment-dialog-custom-annotation-dropdown-trigger-remaining-count-wireframe` **(Leaf)**
* `velt-comment-dialog-custom-annotation-dropdown-trigger-placeholder-wireframe` **(Leaf)**
* `velt-comment-dialog-custom-annotation-dropdown-trigger-arrow-wireframe` **(Leaf)**
#### `velt-comment-dialog-custom-annotation-dropdown-trigger-list-wireframe`
* `velt-comment-dialog-custom-annotation-dropdown-trigger-list-item-wireframe` **(Leaf)**
#### `velt-comment-dialog-custom-annotation-dropdown-content-wireframe`
* `velt-comment-dialog-custom-annotation-dropdown-content-item-wireframe`
#### `velt-comment-dialog-custom-annotation-dropdown-content-item-wireframe`
* `velt-comment-dialog-custom-annotation-dropdown-content-item-label-wireframe` **(Leaf)**
* `velt-comment-dialog-custom-annotation-dropdown-content-item-icon-wireframe` **(Leaf)**
***
### `velt-comment-dialog-comment-index-wireframe`
***
### `velt-comment-dialog-comment-category-wireframe`
***
### `velt-comment-dialog-comment-suggestion-status-wireframe`
***
### `velt-comment-dialog-navigation-button-wireframe`
***
### `velt-comment-dialog-private-badge-wireframe`
***
### `velt-comment-dialog-body-wireframe`
*(no direct children here — see its children below)*
***
### `velt-comment-dialog-threads-wireframe`
* `velt-comment-dialog-thread-card-wireframe`
#### `velt-comment-dialog-thread-card-wireframe`
* `velt-comment-dialog-thread-card-avatar-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-name-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-unread-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-seen-dropdown-wireframe`
* `velt-comment-dialog-thread-card-time-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-device-type-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-options-wireframe`
* `velt-comment-dialog-thread-card-message-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-edit-composer-wireframe`
* `velt-comment-dialog-thread-card-reaction-tool-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-reactions-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-attachments-wireframe`
* `velt-comment-dialog-thread-card-recordings-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-reply-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-assign-button-wireframe` **(Leaf)**
##### `velt-comment-dialog-thread-card-options-wireframe`
* `velt-comment-dialog-thread-card-options-trigger-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-options-content-wireframe`
##### `velt-comment-dialog-thread-card-options-content-wireframe`
* `velt-comment-dialog-thread-card-options-content-mark-as-read-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-options-content-make-private-wireframe`
* `velt-comment-dialog-thread-card-options-content-assign-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-options-content-edit-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-options-content-delete-wireframe`
* `velt-comment-dialog-thread-card-options-content-notification-wireframe`
##### `velt-comment-dialog-thread-card-edit-composer-wireframe`
*(no direct children)*
##### `velt-comment-dialog-thread-card-seen-dropdown-wireframe`
* `velt-comment-dialog-thread-card-seen-dropdown-trigger-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-seen-dropdown-content-wireframe`
##### `velt-comment-dialog-thread-card-seen-dropdown-content-wireframe`
* `velt-comment-dialog-thread-card-seen-dropdown-content-title-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-seen-dropdown-content-items-wireframe`
##### `velt-comment-dialog-thread-card-seen-dropdown-content-items-wireframe`
* `velt-comment-dialog-thread-card-seen-dropdown-content-items-item-wireframe`
##### `velt-comment-dialog-thread-card-seen-dropdown-content-items-item-wireframe`
* `velt-comment-dialog-thread-card-seen-dropdown-content-items-item-time-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-seen-dropdown-content-items-item-name-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-seen-dropdown-content-items-item-avatar-wireframe` **(Leaf)**
##### `velt-comment-dialog-thread-card-attachments-wireframe`
* `velt-comment-dialog-thread-card-attachments-image-wireframe`
* `velt-comment-dialog-thread-card-attachments-other-wireframe`
##### `velt-comment-dialog-thread-card-attachments-image-wireframe`
* `velt-comment-dialog-thread-card-attachments-image-preview-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-attachments-image-delete-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-attachments-image-download-wireframe` **(Leaf)**
##### `velt-comment-dialog-thread-card-attachments-other-wireframe`
* `velt-comment-dialog-thread-card-attachments-other-delete-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-attachments-other-download-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-attachments-other-icon-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-attachments-other-name-wireframe` **(Leaf)**
* `velt-comment-dialog-thread-card-attachments-other-size-wireframe` **(Leaf)**
***
### `velt-comment-dialog-reply-avatars-wireframe`
* `velt-comment-dialog-reply-avatars-list-wireframe`
* `velt-comment-dialog-reply-avatars-remaining-count-wireframe` **(Leaf)**
#### `velt-comment-dialog-reply-avatars-list-wireframe`
* `velt-comment-dialog-reply-avatars-list-item-wireframe` **(Leaf)**
***
### `velt-comment-dialog-toggle-reply-wireframe`
* `velt-comment-dialog-toggle-reply-icon-wireframe` **(Leaf)**
* `velt-comment-dialog-toggle-reply-count-wireframe` **(Leaf)**
* `velt-comment-dialog-toggle-reply-text-wireframe` **(Leaf)**
***
### `velt-comment-dialog-hide-reply-wireframe`
*(no direct children)*
***
### `velt-comment-dialog-composer-wireframe`
* `velt-comment-dialog-composer-avatar-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-wireframe`
* `velt-comment-dialog-composer-recordings-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-input-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-action-button-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-assign-user-wireframe` **(Leaf)**
#### `velt-comment-dialog-composer-attachments-wireframe`
* `velt-comment-dialog-composer-attachments-selected-wireframe`
* `velt-comment-dialog-composer-attachments-invalid-wireframe`
##### `velt-comment-dialog-composer-attachments-selected-wireframe`
* `velt-comment-dialog-composer-attachments-selected-image-wireframe`
* `velt-comment-dialog-composer-attachments-selected-other-wireframe`
##### `velt-comment-dialog-composer-attachments-selected-image-wireframe`
* `velt-comment-dialog-composer-attachments-selected-image-preview-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-selected-image-delete-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-selected-image-loading-wireframe` **(Leaf)**
##### `velt-comment-dialog-composer-attachments-selected-other-wireframe`
* `velt-comment-dialog-composer-attachments-selected-other-delete-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-selected-other-loading-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-selected-other-icon-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-selected-other-name-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-selected-other-size-wireframe` **(Leaf)**
##### `velt-comment-dialog-composer-attachments-invalid-wireframe`
* `velt-comment-dialog-composer-attachments-invalid-item-wireframe`
##### `velt-comment-dialog-composer-attachments-invalid-item-wireframe`
* `velt-comment-dialog-composer-attachments-invalid-item-preview-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-invalid-item-message-wireframe` **(Leaf)**
* `velt-comment-dialog-composer-attachments-invalid-item-delete-wireframe` **(Leaf)**
***
### `velt-comment-dialog-visibility-banner-wireframe`
* `velt-comment-dialog-visibility-banner-icon-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-text-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-wireframe`
#### `velt-comment-dialog-visibility-banner-dropdown-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-trigger-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-wireframe`
##### `velt-comment-dialog-visibility-banner-dropdown-trigger-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-trigger-label-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-trigger-avatar-list-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-trigger-icon-wireframe` **(Leaf)**
##### `velt-comment-dialog-visibility-banner-dropdown-trigger-avatar-list-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-trigger-avatar-list-item-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-trigger-avatar-list-remaining-count-wireframe` **(Leaf)**
##### `velt-comment-dialog-visibility-banner-dropdown-content-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-item-wireframe` (accepts `type`: `public` | `org-users` | `personal` | `selected-people`)
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-wireframe`
##### `velt-comment-dialog-visibility-banner-dropdown-content-item-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-item-icon-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-content-item-label-wireframe` **(Leaf)**
##### `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-search-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-header-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-item-wireframe`
##### `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-search-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-search-icon-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-search-input-wireframe` **(Leaf)**
##### `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-header-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-header-count-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-header-unselect-all-wireframe` **(Leaf)**
##### `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-item-wireframe`
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-item-avatar-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-item-info-wireframe` **(Leaf)**
* `velt-comment-dialog-visibility-banner-dropdown-content-user-picker-item-check-wireframe` **(Leaf)**
***
### `velt-comment-dialog-all-comment-wireframe`
***
### `velt-comment-dialog-approve-wireframe`
***
### `velt-comment-dialog-sign-in-wireframe`
***
### `velt-comment-dialog-upgrade-wireframe`
***
### `velt-comment-dialog-suggestion-action-wireframe`
* `velt-comment-dialog-suggestion-action-accept-wireframe` **(Leaf)**
* `velt-comment-dialog-suggestion-action-reject-wireframe` **(Leaf)**
# Variants
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog/pre-defined-variants
## Pre-defined Variants
The Comment Dialog has 2 pre-defined variants:
* `dialog`: this will customize the Comment Dialog only within Pin, Area, and Text Comments
* `sidebar`: this will customize the Comment Dialog only within Sidebar comments
To use them, set the `variant` name in the wireframe template equal to one of the pre-defined variants. You do not need to add it to the actual Velt component.
```jsx React / Next.js theme={null}
{/* This pre-defined variant will change the appearance of the Comment Dialog within Pin, Area, and Text comments only */}
...
{/* This pre-defined variant will change the appearance of the Comment Dialog within the Sidebar only */}
...
{/* If you dont use any variants, then customization will be applied to the Comment Dialog globally */}
...
```
```jsx HTML theme={null}
```
# Styling
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-dialog/styling
## Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
### Example
```jsx theme={null}
### Example
```
## Dark Mode
### Example
```js theme={null}
```
### API methods
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableDarkMode();
commentElement.disableDarkMode();
```
### Example
```js theme={null}
# Comment Pin
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-pin
The Pin that appears on the DOM when you place a Comment.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltCommentPinWireframe
```jsx theme={null}
```
```html theme={null}
```
## GhostCommentIndicator
```jsx theme={null}
```
```html theme={null}
```
## Index
```jsx theme={null}
```
```html theme={null}
```
## Number
The annotation number displays on comment pins, providing a persistent identifier for each comment that remains constant across sessions. This number makes it easy to reference specific comments in team discussions or documentation.
```jsx theme={null}
```
```html theme={null}
```
## PrivateCommentIndicator
```jsx theme={null}
```
```html theme={null}
```
## Triangle
```jsx theme={null}
```
```html theme={null}
```
## UnreadCommentIndicator
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
**Using Props:**
```jsx theme={null}
**Using Props:**
```jsx theme={null}
### Dark Mode
**Using Props:**
```js theme={null}
```
**Using API:**
```jsx theme={null}
const commentElement = client.getCommentElement();
commentElement.enableDarkMode();
commentElement.disableDarkMode();
```
**Using Props:**
```html theme={null}
### Variants
* Define variants for the `Velt Comment Pin` component. This is useful for customizing how the pin looks on different elements like charts, tables, etc.
* Learn more about how to define and use variants [here](/ui-customization/layout#variants).
```jsx theme={null}
```html theme={null}
# Comment Player Timeline
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-player-timeline
```jsx theme={null}
```jsx theme={null}
# Comments Sidebar Button
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-sidebar-button
The button used to open the Comments Sidebar panel.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltSidebarButtonWireframe
```jsx theme={null}
```
```html theme={null}
```
### Icon
```jsx theme={null}
```
```html theme={null}
```
### CommentsCount
```jsx theme={null}
```
```html theme={null}
```
### UnreadIcon
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
### Example
```jsx theme={null}
### Example
```html theme={null}
### Dark Mode
### Example
```js theme={null}
### Example
```js theme={null}
# Comment Sidebar
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-sidebar-components
Comment Sidebar Component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## Skeleton
```jsx theme={null}
```
```html theme={null}
```
## Panel
```jsx theme={null}
```
```html theme={null}
```
### Header (Panel)
```jsx theme={null}
```
```html theme={null}
```
#### FullscreenButton (Panel Header)
Button to toggle full-screen mode for the Comments Sidebar. This component only appears when full-screen mode is enabled via the `fullScreen` prop or API method. Clicking it allows users to expand the sidebar to fill the entire viewport or return to normal mode.
```jsx theme={null}
```
```html theme={null}
```
#### CloseButton (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
#### Search (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
#### ResetFilterButton (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
#### Status (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Panel Header Status)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Header Status Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Arrow (Panel Header Status Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Indicator (Panel Header Status Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Panel Header Status)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Header Status Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon (Panel Header Status Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Header Status Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Header Status Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Header Status Content Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Header Status Content Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Header Status Content Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
#### LocationFilterDropdown (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Panel Header LocationFilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Label (Panel Header LocationFilterDropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Panel Header LocationFilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
#### MinimalFilterDropdown (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Panel Header MinimalFilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Panel Header MinimalFilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **SortDate (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Sort by date
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content SortDate)**
```jsx theme={null}
```
```html theme={null}
Sort by date
```
##### **SortUnread (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Sort by unread
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content SortUnread)**
```jsx theme={null}
```
```html theme={null}
Sort by unread
```
##### **FilterAll (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Unread or Read
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content FilterAll)**
```jsx theme={null}
```
```html theme={null}
Unread or Read
```
##### **FilterUnread (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Unread only
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content FilterUnread)**
```jsx theme={null}
```
```html theme={null}
Unread only
```
##### **FilterRead (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Read only
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content FilterRead)**
```jsx theme={null}
```
```html theme={null}
Read only
```
##### **FilterResolved (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Resolved
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content FilterResolved)**
```jsx theme={null}
```
```html theme={null}
Resolved
```
##### **FilterOpen (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Open only
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content FilterOpen)**
```jsx theme={null}
```
```html theme={null}
Open only
```
##### **FilterReset (Panel Header MinimalFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
Reset filters
```
##### **SelectedIcon (Panel Header MinimalFilterDropdown Content FilterReset)**
```jsx theme={null}
```
```html theme={null}
Reset filters
```
#### MinimalActionsDropdown (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Panel Header MinimalActionsDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Panel Header MinimalActionsDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **MarkAllRead (Panel Header MinimalActionsDropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **MarkAllResolved (Panel Header MinimalActionsDropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
#### DocumentFilterDropdown (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Panel Header DocumentFilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Panel Header DocumentFilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Document (Panel Header DocumentFilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
#### FilterButton (Panel Header)
```jsx theme={null}
```
```html theme={null}
```
### Filter (Panel)
```jsx theme={null}
```
```html theme={null}
```
#### Title (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
#### CloseButton (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
#### Location (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Location)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Location)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Location Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Location Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Location Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Location Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Location Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Location)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Location Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Location Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Location Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Location Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Location Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **ViewAll (Panel Filter Location)**
```jsx theme={null}
```
```html theme={null}
```
#### Document (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Document)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Document)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Document Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Document Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Document Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Document Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Document Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Document)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Document Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Document Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Document Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Document Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Document Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **ViewAll (Panel Filter Document)**
```jsx theme={null}
```
```html theme={null}
```
#### Involved (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Involved)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Involved)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Involved Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Involved Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Involved Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Involved Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Involved Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Involved)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Involved Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Involved Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Involved Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Involved Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Involved Item)**
```jsx theme={null}
```
```html theme={null}
```
#### People (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter People)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter People)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter People Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter People Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter People Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Close (Panel Filter People Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter People Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter People Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter People Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter People)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter People Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter People Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter People Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter People Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter People Item)**
```jsx theme={null}
```
```html theme={null}
```
#### Tagged (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Tagged)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Tagged)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Tagged Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Tagged Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Tagged Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Close (Panel Filter Tagged Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Tagged Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Tagged Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Tagged Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Tagged)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Tagged Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Tagged Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Tagged Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Tagged Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Tagged Item)**
```jsx theme={null}
```
```html theme={null}
```
#### Assigned (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Assigned)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Assigned)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Assigned Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Assigned Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Assigned Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Close (Panel Filter Assigned Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Assigned Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Assigned Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Assigned Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Assigned)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Assigned Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Assigned Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Assigned Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Assigned Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Assigned Item)**
```jsx theme={null}
```
```html theme={null}
```
#### Custom (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Custom)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Custom)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Custom Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Custom Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Custom Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Close (Panel Filter Custom Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Custom Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Custom Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Custom Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Custom)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Custom Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Custom Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Custom Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Custom Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Custom Item)**
```jsx theme={null}
```
```html theme={null}
```
#### Category (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Category)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Category)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Category Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Category Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Category Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Close (Panel Filter Category Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Category Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Category Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Category Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Category)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Category Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Category Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Category Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Category Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Category Item)**
```jsx theme={null}
```
```html theme={null}
```
#### Priority (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Priority)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Priority)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Priority Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Priority Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Priority Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Close (Panel Filter Priority Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Priority Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Priority Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Priority Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Priority)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Priority Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Priority Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Priority Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Priority Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Priority Item)**
```jsx theme={null}
```
```html theme={null}
```
#### Status (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Status)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Status)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Status Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Status Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Status Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Close (Panel Filter Status Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Status Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Status Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Status Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Status)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Status Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Status Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Status Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Status Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Status Item)**
```jsx theme={null}
```
```html theme={null}
```
#### CommentType (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter CommentType)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter CommentType)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter CommentType Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter CommentType Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter CommentType Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter CommentType Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter CommentType Item)**
```jsx theme={null}
```
```html theme={null}
```
#### Versions (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Versions)**
```jsx theme={null}
```
```html theme={null}
```
##### **Search (Panel Filter Versions)**
```jsx theme={null}
```
```html theme={null}
```
##### **Tags (Panel Filter Versions Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Versions Search Tags)**
```jsx theme={null}
```
```html theme={null}
```
###### **Name (Panel Filter Versions Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
###### **Close (Panel Filter Versions Search Tags Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **HiddenCount (Panel Filter Versions Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Input (Panel Filter Versions Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **DropdownIcon (Panel Filter Versions Search)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter Versions)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter Versions Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter Versions Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter Versions Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter Versions Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter Versions Item)**
```jsx theme={null}
```
```html theme={null}
```
#### GroupBy (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter GroupBy)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel Filter GroupBy)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel Filter GroupBy Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Filter GroupBy Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Filter GroupBy Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel Filter GroupBy Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel Filter GroupBy Item)**
```jsx theme={null}
```
```html theme={null}
```
#### ResetButton (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
#### DoneButton (Panel Filter)
```jsx theme={null}
```
```html theme={null}
```
If you want to change the filters globally across all filters in the sidebar, customize the shared filter option item (shown below) once and reuse it. Use `VeltCommentsSidebarWireframe.Filter.Item` (and its `Checkbox`, `Name`, and `Count` subcomponents) to apply changes across all filters.
### Item (Panel)
```jsx theme={null}
```
```html theme={null}
```
#### Checkbox (Panel Item)
```jsx theme={null}
```
```html theme={null}
```
##### **Checked (Panel Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
##### **Unchecked (Panel Item Checkbox)**
```jsx theme={null}
```
```html theme={null}
```
#### Name (Panel Item)
```jsx theme={null}
```
```html theme={null}
```
#### Count (Panel Item)
```jsx theme={null}
```
```html theme={null}
```
### List (Panel)
```jsx theme={null}
```
```html theme={null}
```
#### Item (Panel List)
```jsx theme={null}
```
```html theme={null}
```
##### **Group (Panel List Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel List Item Group)**
```jsx theme={null}
```
```html theme={null}
```
##### **Count (Panel List Item Group)**
```jsx theme={null}
```
```html theme={null}
```
##### **Arrow (Panel List Item Group)**
```jsx theme={null}
```
```html theme={null}
```
##### **Annotation (Panel List Item)**
```jsx theme={null}
```
```html theme={null}
```
### EmptyPlaceholder (Panel)
```jsx theme={null}
```
```html theme={null}
```
### PageModeComposer (Panel)
```jsx theme={null}
```
```html theme={null}
```
## FocusedThread
```jsx theme={null}
```
```html theme={null}
```
### BackButton (FocusedThread)
```jsx theme={null}
```
```html theme={null}
```
### DialogContainer (FocusedThread)
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
##### **Example**
```jsx theme={null}
##### **Example**
```jsx theme={null}
### Dark Mode
##### **Example**
```js theme={null}
##### **Example**
```js theme={null}
## Variants
Here are the variants that you can use in Comments Sidebar:
* `variant`: This is the variant for the entire Comments Sidebar.
* `dialogVariant`: This is the variant for the Comment Dialog that appears in the Comments Sidebar.
* `pageModeComposerVariant`: This is the variant for the Comment Composer that appears in the Comments Sidebar in page mode.
* `focusedThreadDialogVariant`: This is the variant for the Comment Dialog that appears when a focused thread mode is enabled.
```jsx React / Next.js theme={null}
```jsx Other Frameworks theme={null}
# Comments Sidebar — Structure
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-sidebar-structure
Canonical structure for the Velt Comments Sidebar Wireframe (React only). Order follows your provided JSX. Parent/child is defined ONLY by dot-path extensions. Direct children with no descendants are marked (Leaf).
> **Conventions**
>
> * **React names** use `PascalCase` under the `VeltCommentsSidebarWireframe` namespace.
> * **Parent/child** is determined **only** by the extension path (`A.B` → `B` is a child of `A`). Visual placement (e.g., inside `Header`) does not imply hierarchy.
> * **HTML names** mirror React 1:1 in `kebab-case`.
> * **(Leaf)** = component has no children in this wireframe.
> * **The highest parents will start with '##' as their header tag, their children will use one more '#' at each level.**
***
## React
`VeltCommentsSidebarWireframe`
### `VeltCommentsSidebarWireframe.Skeleton` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.Panel` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.Header` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.FullscreenButton` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.CloseButton` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.Search` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.ResetFilterButton` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.Status`
#### `VeltCommentsSidebarWireframe.Status.Trigger`
* `VeltCommentsSidebarWireframe.Status.Trigger.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Status.Trigger.Arrow` **(Leaf)**
* `VeltCommentsSidebarWireframe.Status.Trigger.Indicator` **(Leaf)**
#### `VeltCommentsSidebarWireframe.Status.Content`
* `VeltCommentsSidebarWireframe.Status.Content.Item`
##### `VeltCommentsSidebarWireframe.Status.Content.Item`
* `VeltCommentsSidebarWireframe.Status.Content.Item.Icon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Status.Content.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Status.Content.Item.Count` **(Leaf)**
* `VeltCommentsSidebarWireframe.Status.Content.Item.Checkbox`
###### `VeltCommentsSidebarWireframe.Status.Content.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Status.Content.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Status.Content.Item.Checkbox.Unchecked` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.LocationFilterDropdown`
#### `VeltCommentsSidebarWireframe.LocationFilterDropdown.Trigger`
* `VeltCommentsSidebarWireframe.LocationFilterDropdown.Trigger.Label` **(Leaf)**
#### `VeltCommentsSidebarWireframe.LocationFilterDropdown.Content` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.MinimalFilterDropdown`
#### `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Trigger` **(Leaf)**
#### `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content`
* `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content.SortDate` **(Leaf)**
* `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content.SortUnread` **(Leaf)**
* `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content.FilterAll` **(Leaf)**
* `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content.FilterUnread` **(Leaf)**
* `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content.FilterRead` **(Leaf)**
* `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content.FilterResolved` **(Leaf)**
* `VeltCommentsSidebarWireframe.MinimalFilterDropdown.Content.SelectedIcon` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.MinimalActionsDropdown`
#### `VeltCommentsSidebarWireframe.MinimalActionsDropdown.Trigger` **(Leaf)**
#### `VeltCommentsSidebarWireframe.MinimalActionsDropdown.Content`
* `VeltCommentsSidebarWireframe.MinimalActionsDropdown.Content.MarkAllRead` **(Leaf)**
* `VeltCommentsSidebarWireframe.MinimalActionsDropdown.Content.MarkAllResolved` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.DocumentFilterDropdown`
#### `VeltCommentsSidebarWireframe.DocumentFilterDropdown.Trigger` **(Leaf)**
#### `VeltCommentsSidebarWireframe.DocumentFilterDropdown.Content` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.FilterButton` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.Filter`
#### `VeltCommentsSidebarWireframe.Filter.Title` **(Leaf)**
#### `VeltCommentsSidebarWireframe.Filter.CloseButton` **(Leaf)**
#### `VeltCommentsSidebarWireframe.Filter.Location`
* `VeltCommentsSidebarWireframe.Filter.Location.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Search`
* `VeltCommentsSidebarWireframe.Filter.Location.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Location.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Location.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Item`
* `VeltCommentsSidebarWireframe.Filter.Location.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Location.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.Item.Count` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Location.ViewAll` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Document`
* `VeltCommentsSidebarWireframe.Filter.Document.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Search`
* `VeltCommentsSidebarWireframe.Filter.Document.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Document.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Document.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Item`
* `VeltCommentsSidebarWireframe.Filter.Document.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Document.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.Item.Count` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Document.ViewAll` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Involved`
* `VeltCommentsSidebarWireframe.Filter.Involved.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Search`
* `VeltCommentsSidebarWireframe.Filter.Involved.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Involved.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Involved.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Item`
* `VeltCommentsSidebarWireframe.Filter.Involved.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Involved.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Involved.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.People`
* `VeltCommentsSidebarWireframe.Filter.People.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Search`
* `VeltCommentsSidebarWireframe.Filter.People.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.People.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.People.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Item`
* `VeltCommentsSidebarWireframe.Filter.People.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.People.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.People.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Tagged`
* `VeltCommentsSidebarWireframe.Filter.Tagged.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search`
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Item`
* `VeltCommentsSidebarWireframe.Filter.Tagged.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Tagged.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Tagged.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Assigned`
* `VeltCommentsSidebarWireframe.Filter.Assigned.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search`
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Item`
* `VeltCommentsSidebarWireframe.Filter.Assigned.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Assigned.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Assigned.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Custom`
* `VeltCommentsSidebarWireframe.Filter.Custom.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Search`
* `VeltCommentsSidebarWireframe.Filter.Custom.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Custom.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Custom.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Item`
* `VeltCommentsSidebarWireframe.Filter.Custom.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Custom.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Custom.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Category`
* `VeltCommentsSidebarWireframe.Filter.Category.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Search`
* `VeltCommentsSidebarWireframe.Filter.Category.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Category.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Category.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Item`
* `VeltCommentsSidebarWireframe.Filter.Category.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Category.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Category.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Priority`
* `VeltCommentsSidebarWireframe.Filter.Priority.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Search`
* `VeltCommentsSidebarWireframe.Filter.Priority.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Priority.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Priority.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Item`
* `VeltCommentsSidebarWireframe.Filter.Priority.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Priority.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Priority.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Status`
* `VeltCommentsSidebarWireframe.Filter.Status.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Search`
* `VeltCommentsSidebarWireframe.Filter.Status.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Status.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Status.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Item`
* `VeltCommentsSidebarWireframe.Filter.Status.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Status.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Status.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.CommentType`
* `VeltCommentsSidebarWireframe.Filter.CommentType.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.CommentType.Item`
* `VeltCommentsSidebarWireframe.Filter.CommentType.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.CommentType.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.CommentType.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.CommentType.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.CommentType.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.Versions`
* `VeltCommentsSidebarWireframe.Filter.Versions.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Search`
* `VeltCommentsSidebarWireframe.Filter.Versions.Search.Tags`
* `VeltCommentsSidebarWireframe.Filter.Versions.Search.Tags.Item`
* `VeltCommentsSidebarWireframe.Filter.Versions.Search.Tags.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Search.Tags.Item.Close` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Search.HiddenCount` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Search.Input` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Search.DropdownIcon` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Item`
* `VeltCommentsSidebarWireframe.Filter.Versions.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Versions.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Versions.Item.Count` **(Leaf)**
***
#### `VeltCommentsSidebarWireframe.Filter.GroupBy`
* `VeltCommentsSidebarWireframe.Filter.GroupBy.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.GroupBy.Item`
* `VeltCommentsSidebarWireframe.Filter.GroupBy.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.GroupBy.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.GroupBy.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.GroupBy.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.GroupBy.Item.Count` **(Leaf)**
#### `VeltCommentsSidebarWireframe.Filter.ResetButton` **(Leaf)**
#### `VeltCommentsSidebarWireframe.Filter.DoneButton` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.Filter.Item`
* `VeltCommentsSidebarWireframe.Filter.Item.Checkbox`
* `VeltCommentsSidebarWireframe.Filter.Item.Checkbox.Checked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Item.Checkbox.Unchecked` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Item.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.Filter.Item.Count` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.List`
#### `VeltCommentsSidebarWireframe.List.Item`
* `VeltCommentsSidebarWireframe.List.Item.Group`
* `VeltCommentsSidebarWireframe.List.Item.Group.Name` **(Leaf)**
* `VeltCommentsSidebarWireframe.List.Item.Group.Count` **(Leaf)**
* `VeltCommentsSidebarWireframe.List.Item.Group.Arrow` **(Leaf)**
* `VeltCommentsSidebarWireframe.List.Item.Annotation` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.EmptyPlaceholder` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.PageModeComposer` **(Leaf)**
***
### `VeltCommentsSidebarWireframe.FocusedThread`
#### `VeltCommentsSidebarWireframe.FocusedThread.BackButton` **(Leaf)**
#### `VeltCommentsSidebarWireframe.FocusedThread.DialogContainer` **(Leaf)**
***
## Related (Global status dropdown alternative)
`VeltCommentsSidebarStatusDropdownWireframe`
### `VeltCommentsSidebarStatusDropdownWireframe.Trigger` **(Leaf)**
### `VeltCommentsSidebarStatusDropdownWireframe.Content` **(Leaf)**
## HTML (1:1 mirror)
`velt-comments-sidebar-wireframe`
### `velt-comment-sidebar-skeleton-wireframe` **(Leaf)**
***
### `velt-comment-sidebar-panel-wireframe`
#### `velt-comments-sidebar-header-wireframe`
* `velt-comments-sidebar-fullscreen-button-wireframe` **(Leaf)**
* `velt-comments-sidebar-close-button-wireframe` **(Leaf)**
* `velt-comments-sidebar-reset-filter-button-wireframe` **(Leaf)**
* `velt-comments-sidebar-search-wireframe` **(Leaf)**
##### `velt-comments-sidebar-status-wireframe`
* `velt-comments-sidebar-status-dropdown-trigger-wireframe`
* `velt-comments-sidebar-status-dropdown-trigger-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-status-dropdown-trigger-arrow-wireframe` **(Leaf)**
* `velt-comments-sidebar-status-dropdown-trigger-indicator-wireframe` **(Leaf)**
* `velt-comments-sidebar-status-dropdown-content-wireframe`
* `velt-comments-sidebar-status-dropdown-content-item-wireframe`
* `velt-comments-sidebar-status-dropdown-content-item-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-status-dropdown-content-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-status-dropdown-content-item-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-status-dropdown-content-item-checkbox-wireframe`
* `velt-comments-sidebar-status-dropdown-content-item-checkbox-unchecked-wireframe` **(Leaf)**
* `velt-comments-sidebar-status-dropdown-content-item-checkbox-checked-wireframe` **(Leaf)**
##### `velt-comments-sidebar-location-filter-dropdown-wireframe`
* `velt-comments-sidebar-location-filter-dropdown-trigger-wireframe`
* `velt-comments-sidebar-location-filter-dropdown-trigger-label-wireframe` **(Leaf)**
* `velt-comments-sidebar-location-filter-dropdown-content-wireframe` **(Leaf)**
##### `velt-comments-sidebar-minimal-filter-dropdown-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-trigger-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-filter-dropdown-content-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-content-sort-date-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-content-selected-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-filter-dropdown-content-sort-unread-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-content-selected-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-filter-dropdown-content-filter-all-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-content-selected-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-filter-dropdown-content-filter-unread-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-content-selected-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-filter-dropdown-content-filter-read-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-content-selected-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-filter-dropdown-content-filter-resolved-wireframe`
* `velt-comments-sidebar-minimal-filter-dropdown-content-selected-icon-wireframe` **(Leaf)**
##### `velt-comments-sidebar-minimal-actions-dropdown-wireframe`
* `velt-comments-sidebar-minimal-actions-dropdown-trigger-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-actions-dropdown-content-wireframe`
* `velt-comments-sidebar-minimal-actions-dropdown-content-mark-all-read-wireframe` **(Leaf)**
* `velt-comments-sidebar-minimal-actions-dropdown-content-mark-all-resolved-wireframe` **(Leaf)**
##### `velt-comments-sidebar-document-filter-dropdown-wireframe`
* `velt-comments-sidebar-document-filter-dropdown-trigger-wireframe` **(Leaf)**
* `velt-comments-sidebar-document-filter-dropdown-content-wireframe`
* `velt-comments-sidebar-filter-document-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-button-wireframe` **(Leaf)**
***
#### `velt-comments-sidebar-filter-wireframe`
* `velt-comments-sidebar-filter-title-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-close-button-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-location-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-view-all-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-document-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-view-all-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-involved-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-people-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-custom-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-tagged-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-assigned-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-category-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-comment-type-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-priority-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-status-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-versions-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-wireframe`
* `velt-comments-sidebar-filter-search-tags-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-wireframe`
* `velt-comments-sidebar-filter-search-tags-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-tags-item-close-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-hidden-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-input-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-search-dropdown-icon-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
##### `velt-comments-sidebar-filter-group-by-wireframe`
* `velt-comments-sidebar-filter-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-reset-button-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-done-button-wireframe` **(Leaf)**
***
#### `velt-comments-sidebar-list-wireframe`
* `velt-comments-sidebar-list-item-wireframe`
* `velt-comments-sidebar-list-item-group-wireframe`
* `velt-comments-sidebar-list-item-group-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-list-item-group-count-wireframe` **(Leaf)**
* `velt-comments-sidebar-list-item-group-arrow-wireframe` **(Leaf)**
* `velt-comments-sidebar-list-item-annotation-wireframe` **(Leaf)**
#### `velt-comments-sidebar-empty-placeholder-wireframe` **(Leaf)**
#### `velt-comments-sidebar-page-mode-composer-wireframe` **(Leaf)**
***
### `velt-comments-sidebar-focused-thread-wireframe`
* `velt-comments-sidebar-focused-thread-back-button-wireframe` **(Leaf)**
* `velt-comments-sidebar-focused-thread-dialog-container-wireframe` **(Leaf)**
***
## Common Filter Item (Reusable)
`velt-comments-sidebar-filter-item-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-wireframe`
* `velt-comments-sidebar-filter-item-checkbox-checked-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-checkbox-unchecked-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-name-wireframe` **(Leaf)**
* `velt-comments-sidebar-filter-item-count-wireframe` **(Leaf)**
# Comment Tool
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-tool
The button to add new comments.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltCommentToolWireframe
```jsx theme={null}
{/* Your custom element */}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
```jsx theme={null}
```jsx theme={null}
### Dark Mode
```js theme={null}
```js theme={null}
# Velt Video Player
Source: https://docs.velt.dev/ui-customization/features/async/comments/comment-video-player
```jsx theme={null}
```jsx theme={null}
# Styling
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/styling
## Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
### Example
```jsx theme={null}
### Example
```jsx theme={null}
## Dark Mode
### Example
```js theme={null}
### Example
```js theme={null}
# Empty placeholder
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/empty-placeholder
The subcomponent of the Comments Sidebar that represents the placeholder when there are no Comments
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/overview
The subcomponent of the Comments Sidebar that represents the filter that is used to filter what Comments appear in the Sidebar
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
{/* Title */}
```
```HTML HTML theme={null}
```
# Filter Type - Assigned
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/assigned
The subcomponent of the Comments Sidebar Filter that represents the Assigned filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Filter Type - Category
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/category
The subcomponent of the Comments Sidebar Filter that represents the Category
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
## Default Subcomponent
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Close button
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/close-button
The subcomponent of the Comments Sidebar Filter that represents the Close button
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Filter Type - Comment Type
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/comment-type
The subcomponent of the Comments Sidebar Filter that represents the Comment Type filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Filter Type - Custom
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/custom
The subcomponent of the Comments Sidebar Filter that represents the Custom filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You need to add one for each custom filter you want to add.
```jsx React / Next.js theme={null}
{/* If you are using the default filterOptionLayout */}
```
```HTML HTML theme={null}
```
# Filter Type - Document
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/document
The subcomponent of the Comments Sidebar Filter that represents the Document filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Done button
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/done-button
The subcomponent of the Comments Sidebar Filter that represents the Done Button
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Filter item
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item
Used to customize all the filter option items of the Comments Sidebar Filter at once
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Groupby
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/groupby
The subcomponent of the Comments Sidebar Filter that represents the Groupby filter option
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx eact / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Filter Type - Involved
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/involved
The subcomponent of the Comments Sidebar Filter that represents the Involved filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Filter Type - Location
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/location
The subcomponent of the Comments Sidebar Filter that represents the Location filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
## Default Subcomponent
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Filter Type - Author
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/people
The subcomponent of the Comments Sidebar Filter that represents the Author filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
## Default Subcomponent
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Filter Type - Priority
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/priority
The subcomponent of the Comments Sidebar Filter that represents the Priority filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
## Default Subcomponent
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Reset button
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/reset-button
The subcomponent of the Comments Sidebar Filter that represents the Reset Filter Button
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Filter Type - Status
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/status
The subcomponent of the Comments Sidebar Filter that represents the Status filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Filter Type - Tagged
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/tagged
The subcomponent of the Comments Sidebar Filter that represents the Tagged filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Title
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/title
The subcomponent of the Comments Sidebar Filter that represents the Title
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Filter Type - Versions
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/versions
The subcomponent of the Comments Sidebar Filter that represents the Version filter
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can either use this or use the global filter item wireframe to customize all the filter types of filter options at once. [Learn More](/ui-customization/features/async/comments/comments-sidebar/subcomponents/filter/subcomponents/filter-item)
## Default Subcomponent
```jsx React / Next.js theme={null}
{/* Checklist: It's visible by default. */}
```
```HTML HTML theme={null}
```
# Focused thread
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/focused-thread
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
```jsx React / Next.js theme={null}
{/* Back Button to back to default view with all threads */}
```
```HTML HTML theme={null}
```
# Header
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header
The subcomponent of the Comments Sidebar that represents the Header of the Sidebar
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/overview
The subcomponent of the Comments Sidebar that represents the Header of the Sidebar
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/document-filter-dropdown/overview
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
This component is not included in the default Comments Sidebar component. You need to explicitly add it to the sidebar wireframe.
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/location-filter-dropdown/overview
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
This component is not included in the default Comments Sidebar component. You need to explicitly add it to the sidebar wireframe.
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/minimal-action-dropdown/overview
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
* This enables actions like `Mark all read` and `Mark all resolved` in the sidebar. By default it's not enabled. You need to explicitly add the wireframe to the sidebar.
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/minimal-filter-dropdown/overview
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
* This enables minimal filtering and sorting dropdown in the sidebar. By default it's not enabled. You need to explicitly add the wireframe to the sidebar. It includes options like:
* Filter by `All`
* Filter by `Unread`
* Filter by `Read`
* Filter by `Resolved`
* Filter by `Assigned to Me`
* Sort by `Unread`
* Sort by `Last Updated Timestamp`
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
### FilterAssignedToMe (MinimalFilterDropdown Content)
```jsx theme={null}
```
```html theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/overview
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Content
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/subcomponents/content
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Trigger
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/header/subcomponents/status/subcomponents/trigger
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/overview
The subcomponent of the Comments Sidebar that represents the List of Comments in the Sidebar
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Dialog container
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/subcomponents/dialog-container
You can customize the Comment Dialog that appears inside the Sidebar with this subcomponent
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
You can customize the Comment Dialog that appears in the Sidebar by adding a Comment Dialog Wireframe inside this subcomponent and modifying it to your liking.
```jsx React / Next.js theme={null}
...
```
```HTML HTML theme={null}
...
```
# Group
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/list/subcomponents/group
The subcomponent of the Comments Sidebar List that represents the Group
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Page mode composer
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/page-mode-composer
The subcomponent of the Comments Sidebar that represents the Composer that appears in Page Mode.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Panel
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/panel
The subcomponent of the Comments Sidebar that represents the List of Comments in the Sidebar
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
{/* Header */}
```
```HTML HTML theme={null}
```
# Reset filter button
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/reset-filter-button
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Overview
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/sidebar-button/overview
The button that is used to open the Comments Sidebar panel.
We recommend that you familiarize yourselves with [Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Component
Here's how the default sidebar button looks like:
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Styling
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/sidebar-button/styling
## Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
### Example
```jsx theme={null}
### Example
```jsx theme={null}
## Dark Mode
### Example
```js theme={null}
### Example
```js theme={null}
# Comments count
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/sidebar-button/subcomponents/comments-count
The subcomponent on the Sidebar Button that shows the total
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Icon
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/sidebar-button/subcomponents/icon
The subcomponent on the Sidebar Button that shows the total
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Skeleton
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/subcomponents/skeleton
The subcomponent of the Comments Sidebar that represents the Skeleton loader that appears when the Sidebar is first loading.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Default Subcomponent
```jsx React / Next.js theme={null}
```
```HTML HTML theme={null}
```
# Variants
Source: https://docs.velt.dev/ui-customization/features/async/comments/comments-sidebar/variants
## Variants
Here are the variants that you can use in Comments Sidebar:
* `variant`: This is the variant for the entire Comments Sidebar.
* `dialogVariant`: This is the variant for the Comment Dialog that appears in the Comments Sidebar.
* `pageModeComposerVariant`: This is the variant for the Comment Composer that appears in the Comments Sidebar in page mode.
* `focusedThreadDialogVariant`: This is the variant for the Comment Dialog that appears when a focused thread mode is enabled.
```jsx React / Next.js theme={null}
# Confirmation Dialog
Source: https://docs.velt.dev/ui-customization/features/async/comments/confirm-dialog
The Confirmation Dialog that appears when you delete a comment annotation.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltConfirmDialogWireframe
```jsx theme={null}
```
```html theme={null}
```
## Title
```jsx theme={null}
```
```html theme={null}
```
## Message
```jsx theme={null}
```
```html theme={null}
```
## RejectButton
```jsx theme={null}
```
```html theme={null}
```
## ApproveButton
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
ShadowDOM is not used in this component. You can apply your styling directly to the component.
### Dark Mode
This component takes the dark mode property from the parent feature (eg: comments) where this used.
If the parent feature component is in dark mode, this component will also be in dark mode.
# Inline Comments Section
Source: https://docs.velt.dev/ui-customization/features/async/comments/inline-comments-section
Components that appear when using Inline Comments
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltInlineCommentsSectionWireframe
```jsx theme={null}
```
```html theme={null}
```
### Skeleton
```jsx theme={null}
```
```html theme={null}
```
### Panel
```jsx theme={null}
```
```html theme={null}
```
#### ComposerContainer
```jsx theme={null}
```
```html theme={null}
```
##### **VeltCommentDialogWireframe.Composer**
You can find the wireframe for the `Comment Dialog Composer` [here](/ui-customization/features/async/comments/comment-dialog-components#composer).
#### SortingDropdown
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger**
```jsx theme={null}
```
```html theme={null}
```
##### **Name**
```jsx theme={null}
```
```html theme={null}
```
##### **Icon**
```jsx theme={null}
```
```html theme={null}
```
##### **Content**
```jsx theme={null}
```
```html theme={null}
```
##### **Item**
```jsx theme={null}
```
```html theme={null}
```
#### FilterDropdown (Panel)
```jsx theme={null}
```
```html theme={null}
```
##### **Trigger (Panel FilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **Arrow (Panel FilterDropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Name (Panel FilterDropdown Trigger)**
```jsx theme={null}
```
```html theme={null}
```
##### **Content (Panel FilterDropdown)**
```jsx theme={null}
```
```html theme={null}
```
##### **List (Panel FilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
##### **Item (Panel FilterDropdown Content List)**
```jsx theme={null}
```
```html theme={null}
```
##### **Label (Panel FilterDropdown Content List Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **Checkbox (Panel FilterDropdown Content List Item)**
```jsx theme={null}
```
```html theme={null}
```
##### **ApplyButton (Panel FilterDropdown Content)**
```jsx theme={null}
```
```html theme={null}
```
#### CommentCount
```jsx theme={null}
```
```html theme={null}
```
#### List
```jsx theme={null}
```
```html theme={null}
```
##### **VeltCommentDialogWireframe**
You can find the wireframe for the `Comment Dialog` [here](/ui-customization/features/async/comments/comment-dialog-components).
## Pre-defined Variants
Here are the pre-deinfed variants:
1. `dialog-variant`: Use this to customize the `Comment Dialog` that appears within the `Inline Comments Section` component.
2. `variant`: Use this to customize the entire `Inline Comments Section` component itself.
3. `composer-variant`: Use this to customize the main Composer that appears within the `Inline Comments Section` component.
Learn more about Variants [here](/ui-customization/layout#variants)
```jsx React / Next.js theme={null}
```HTML theme={null}
```
# MultiThread Comment Dialog
Source: https://docs.velt.dev/ui-customization/features/async/comments/multithread-comment-dialog
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltMultiThreadCommentDialogWireframe
```jsx theme={null}
```
```html theme={null}
```
## CommentCount
```jsx theme={null}
```
```html theme={null}
```
## MinimalFilterDropdown
```jsx theme={null}
```
```html theme={null}
```
## MinimalActionsDropdown
```jsx theme={null}
```
```html theme={null}
```
## NewThreadButton
```jsx theme={null}
```
```html theme={null}
```
## CloseButton
```jsx theme={null}
```
```html theme={null}
```
## List
```jsx theme={null}
```
```html theme={null}
```
## ResetFilterButton
```jsx theme={null}
```
```html theme={null}
```
## ComposerContainer
```jsx theme={null}
```
```html theme={null}
```
# Persistent Comment Mode Banner
Source: https://docs.velt.dev/ui-customization/features/async/comments/persistent-comment-mode-banner
The persistent comment mode banner that appears when persistent mode is enabled and user is adding a comment.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltPersistentCommentModeWireframe
```jsx theme={null}
```
```html theme={null}
```
## CloseButton
```jsx theme={null}
```
```html theme={null}
```
## Label
```jsx theme={null}
```
```html theme={null}
```
### Label.Public
```jsx theme={null}
```
```html theme={null}
```
### Label.Private
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
```jsx theme={null}
```
```html theme={null}
# Comment Composer
Source: https://docs.velt.dev/ui-customization/features/async/comments/standalone-components/comment-composer
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
This component is a thin wrapper around the [Comment Dialog Composer](/ui-customization/features/async/comments/comment-dialog-components#composer) component.
## VeltCommentComposerWireframe
```jsx theme={null}
```
```html theme={null}
```
### VeltCommentDialogWireframe.Composer
You can find the wireframe for the `Comment Composer` [here](/ui-customization/features/async/comments/comment-dialog-components#composer).
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
```jsx theme={null}
```html theme={null}
### Dark Mode
`Default: false`
```jsx theme={null}
```html theme={null}
### Variants
* Define variants for the entire Comment Composer component. This will enable you to show different Composer UI in different parts of your app.
* Alternatively, define a variant for the Comment Dialog component and use it here. This will enable you to show different Comment Dialog UI on the DOM vs here.
* Learn more about how to define and use variants [here](/ui-customization/layout#variants).
```jsx theme={null}
```html theme={null}
# Comment Thread
Source: https://docs.velt.dev/ui-customization/features/async/comments/standalone-components/comment-thread
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
This component is a thin wrapper around the [Comment Dialog](/ui-customization/features/async/comments/comment-dialog-components) component.
## VeltCommentThreadWireframe
```jsx theme={null}
```
```html theme={null}
```
### VeltCommentDialogWireframe
You can find the wireframe for the `Comment Dialog` [here](/ui-customization/features/async/comments/comment-dialog-components).
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
```jsx theme={null}
```html theme={null}
### Dark Mode
```js theme={null}
```html theme={null}
### Variants
* Define variants for the entire Comment Thread component. This will enable you to show different Thread UI in different parts of your app.
* Alternatively, define a variant for the Comment Dialog component and use it here. This will enable you to show different Comment Dialog UI on the DOM vs here.
* Learn more about how to define and use variants [here](/ui-customization/layout#variants).
```jsx theme={null}
```html theme={null}
# Text Comment Tool
Source: https://docs.velt.dev/ui-customization/features/async/comments/text-comment-tool
The Comment Tool that appears when you highlight some text.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltTextCommentToolWireframe
```jsx theme={null}
{/* Your custom element */}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
```jsx theme={null}
```jsx theme={null}
### Dark Mode
By default, all components are in Light Mode, but there are several properties and methods to enable Dark Mode.
Default: `false`
Below are the examples to enable Dark Mode for text comment tool.
**Using Props:**
```js theme={null}
**Using Props:**
```js theme={null}
# Text Comment Toolbar
Source: https://docs.velt.dev/ui-customization/features/async/comments/text-comment-toolbar
The Toolbar that appears when you highlight some text
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltTextCommentToolbarWireframe
```jsx theme={null}
```
```html theme={null}
```
## CommentAnnotation
```jsx theme={null}
```
```html theme={null}
```
## Divider
```jsx theme={null}
```
```html theme={null}
```
## Copywriter
```jsx theme={null}
```
```html theme={null}
```
## Generic
```jsx theme={null}
```
````html theme={null}
```
## Styling
### Disable ShadowDOM
- By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
- Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
```jsx
```jsx theme={null}
### Dark Mode
By default, all components are in Light Mode, but there are several properties and methods to enable Dark Mode.
Default: `false`
**Using Props:**
```js theme={null}
**Using Props:**
```js theme={null}
# Inline Reactions Section
Source: https://docs.velt.dev/ui-customization/features/async/inline-reactions
This component is used to render the reaction tool and all the reactions.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltInlineReactionsSectionWireframe
```jsx theme={null}
```
```html theme={null}
```
### Panel
```jsx theme={null}
```
```html theme={null}
```
#### ToolContainer
```jsx theme={null}
```
```html theme={null}
```
##### VeltReactionToolWireframe
```jsx theme={null}
```
```html theme={null}
```
#### List
```jsx theme={null}
```
```html theme={null}
```
##### VeltReactionPinWireframe
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
```jsx theme={null}
```jsx theme={null}
### Dark Mode
Default: `false`
**Using Props:**
```js theme={null}
**Using Props:**
```html theme={null}
## Variants
### Pre-defined Variants
The Inline Reactions has 1 pre-defined variant:
* `inline`: This will customize the default components inside the Inline Reactions Component.
You can define your own variants and use them in different places of your app.
```jsx theme={null}
```
```html theme={null}
```
# Notifications Panel
Source: https://docs.velt.dev/ui-customization/features/async/notifications/notifications-panel
The Notification Panel contains all notifications within the current organization. It appears when you click the notification tool or embed it directly on a page.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## Title
```jsx theme={null}
```
```html theme={null}
```
## ReadAllButton
```jsx theme={null}
```
```html theme={null}
```
## Skeleton
```jsx theme={null}
```
```html theme={null}
```
## Header
```jsx theme={null}
```
```html theme={null}
```
#### TabAll
```jsx theme={null}
```
```html theme={null}
```
#### TabDocuments
```jsx theme={null}
```
```html theme={null}
```
#### TabForYou
```jsx theme={null}
```
```html theme={null}
```
#### TabPeople
```jsx theme={null}
```
```html theme={null}
```
## Content
```jsx theme={null}
```
```html theme={null}
```
### ForYou
```jsx theme={null}
```
```html theme={null}
```
### All
```jsx theme={null}
```
```html theme={null}
```
#### All List
```jsx theme={null}
```
```html theme={null}
```
#### All List Item
```jsx theme={null}
```
```html theme={null}
```
#### All List Item Label
```jsx theme={null}
```
```html theme={null}
```
#### All List Item Content
```jsx theme={null}
```
```html theme={null}
```
### Documents
```jsx theme={null}
```
```html theme={null}
```
#### Documents List
```jsx theme={null}
```
```html theme={null}
```
#### Documents List Item
```jsx theme={null}
```
```html theme={null}
```
#### Documents List Item Unread
```jsx theme={null}
```
```html theme={null}
```
#### Documents List Item Name
```jsx theme={null}
```
```html theme={null}
```
#### Documents List Item Count
```jsx theme={null}
```
```html theme={null}
```
#### Documents List Item Content
```jsx theme={null}
```
```html theme={null}
```
### People
```jsx theme={null}
```
```html theme={null}
```
#### People List
```jsx theme={null}
```
```html theme={null}
```
#### People List Item
```jsx theme={null}
```
```html theme={null}
```
#### People List Item Avatar
```jsx theme={null}
```
```html theme={null}
```
#### People List Item Name
```jsx theme={null}
```
```html theme={null}
```
#### People List Item Count
```jsx theme={null}
```
```html theme={null}
```
#### People List Item Content
```jsx theme={null}
```
```html theme={null}
```
## Settings
```jsx theme={null}
```
```html theme={null}
```
### Settings Header
```jsx theme={null}
```
```html theme={null}
```
#### Header BackButton
```jsx theme={null}
```
```html theme={null}
```
#### Header Title
```jsx theme={null}
```
```html theme={null}
```
### Settings Title
```jsx theme={null}
```
```html theme={null}
```
### Settings Description
```jsx theme={null}
```
```html theme={null}
```
### Settings List
```jsx theme={null}
```
```html theme={null}
```
#### Settings List Accordion
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Trigger
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Trigger Label
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Trigger SelectedValue
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Trigger Icon
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Content
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Content Item
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Content Item Icon
```jsx theme={null}
```
```html theme={null}
```
#### Accordion Content Item Label
```jsx theme={null}
```
```html theme={null}
```
### Settings Footer
```jsx theme={null}
```
```html theme={null}
```
#### MuteAllTitle
```jsx theme={null}
```
```html theme={null}
```
#### MuteAllDescription
```jsx theme={null}
```
```html theme={null}
```
#### MuteAllToggle
```jsx theme={null}
```
```html theme={null}
```
## Shared Components
### Content List
```jsx theme={null}
```
```html theme={null}
```
### Content List Item
```jsx theme={null}
```
```html theme={null}
```
#### Content List Item Avatar
```jsx theme={null}
```
```html theme={null}
```
#### Content List Item Unread
```jsx theme={null}
```
```html theme={null}
```
#### Content List Item Headline
```jsx theme={null}
```
```html theme={null}
```
#### Content List Item Body
```jsx theme={null}
```
```html theme={null}
```
#### Content List Item FileName
```jsx theme={null}
```
```html theme={null}
```
#### Content List Item Time
```jsx theme={null}
```
```html theme={null}
```
### LoadMore
```jsx theme={null}
```
```html theme={null}
```
### AllReadContainer
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
```jsx theme={null}
```jsx theme={null}
### Dark Mode
`Default: false`
```js theme={null}
```html theme={null}
# Notifications Tool
Source: https://docs.velt.dev/ui-customization/features/async/notifications/notifications-tool
The button that opens or closes the notification panel.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltNotificationsToolWireframe
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
**Example**
```jsx theme={null}
```jsx theme={null}
### Dark Mode
`Default: false`
```js theme={null}
```js theme={null}
## Variant
You can define and use [variants](/ui-customization/layout#variants) for the Notification Tool or the Notification Panel.
1. `variant`: For the Notification Tool.
2. `panelVariant`: For the Notification Panel.
```jsx theme={null}
```html theme={null}
# Control Panel
Source: https://docs.velt.dev/ui-customization/features/async/recorder/control-panel
Recorder control panel component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## Floating Mode
```jsx theme={null}
```
```html theme={null}
```
### Container (Floating Mode)
```jsx theme={null}
```
```html theme={null}
```
#### Video (Floating Mode Container)
```jsx theme={null}
```
```html theme={null}
```
#### Waveform (Floating Mode Container)
```jsx theme={null}
```
```html theme={null}
```
#### CollapsedButton (Floating Mode Container)
```jsx theme={null}
```
```html theme={null}
```
##### On (CollapsedButton)
```jsx theme={null}
```
```html theme={null}
```
##### Off (CollapsedButton)
```jsx theme={null}
```
```html theme={null}
```
#### Paused (Floating Mode Container)
```jsx theme={null}
```
```html theme={null}
```
### ScreenMiniContainer (Floating Mode)
```jsx theme={null}
```
```html theme={null}
```
#### Video (Floating Mode ScreenMiniContainer)
This is the same Video component as used in the Floating Mode Container.
```jsx theme={null}
```
```html theme={null}
```
#### Screen (Floating Mode ScreenMiniContainer)
```jsx theme={null}
```
```html theme={null}
```
### Loading (Floating Mode)
```jsx theme={null}
```
```html theme={null}
```
### ActionBar (Floating Mode)
```jsx theme={null}
```
```html theme={null}
```
#### TypeIcon (ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Time (ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Waveform (ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Toggle (ActionBar)
```jsx theme={null}
```
```html theme={null}
```
##### Pause (Toggle)
```jsx theme={null}
```
```html theme={null}
```
##### Play (Toggle)
```jsx theme={null}
```
```html theme={null}
```
#### Pip (ActionBar)
Picture-in-Picture button for screen recordings with camera. This allows users to view the recording in a floating window during screen capture.
Picture-in-Picture is only supported in Chrome browsers and only works for screen recordings when the camera is active. This feature is disabled by default.
```jsx theme={null}
```
```html theme={null}
```
#### Stop (ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Clear (ActionBar)
```jsx theme={null}
```
```html theme={null}
```
## Thread Mode
```jsx theme={null}
```
```html theme={null}
```
### Video (Thread Mode)
```jsx theme={null}
```
```html theme={null}
```
### Loading (Thread Mode)
```jsx theme={null}
```
```html theme={null}
```
### ActionBar (Thread Mode)
This ActionBar is similar in structure to the Floating Mode ActionBar but specific to ThreadMode.
```jsx theme={null}
```
```html theme={null}
```
#### TypeIcon (Thread Mode ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Time (Thread Mode ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Waveform (Thread Mode ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Toggle (Thread Mode ActionBar)
```jsx theme={null}
```
```html theme={null}
```
##### Pause (Thread Mode Toggle)
```jsx theme={null}
```
```html theme={null}
```
##### Play (Thread Mode Toggle)
```jsx theme={null}
```
```html theme={null}
```
#### Pip (Thread Mode ActionBar)
Picture-in-Picture button for screen recordings with camera in Thread Mode. This allows users to view the recording in a floating window during screen capture.
Picture-in-Picture is only supported in Chrome browsers and only works for screen recordings when the camera is active. This feature is disabled by default.
```jsx theme={null}
```
```html theme={null}
```
#### Stop (Thread Mode ActionBar)
```jsx theme={null}
```
```html theme={null}
```
#### Clear (Thread Mode ActionBar)
```jsx theme={null}
```
```html theme={null}
```
### ScreenMiniContainer (Thread Mode)
```jsx theme={null}
```
```html theme={null}
```
#### Video (Thread Mode ScreenMiniContainer)
This is the same Video component as used in the main Thread Mode section.
```jsx theme={null}
```
```html theme={null}
```
#### Screen (Thread Mode ScreenMiniContainer)
```jsx theme={null}
```
```html theme={null}
```
# Media Source Settings
Source: https://docs.velt.dev/ui-customization/features/async/recorder/media-source-settings
Media source settings component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## Audio
```jsx theme={null}
```
```html theme={null}
```
### ToggleIcon
```jsx theme={null}
```
```html theme={null}
```
### SelectedLabel
```jsx theme={null}
```
```html theme={null}
```
### Divider
```jsx theme={null}
```
```html theme={null}
```
### Options
```jsx theme={null}
```
```html theme={null}
```
#### Item
```jsx theme={null}
```
```html theme={null}
```
## Video
```jsx theme={null}
```
```html theme={null}
```
### ToggleIcon
```jsx theme={null}
```
```html theme={null}
```
### SelectedLabel
```jsx theme={null}
```
```html theme={null}
```
### Divider
```jsx theme={null}
```
```html theme={null}
```
### Options
```jsx theme={null}
```
```html theme={null}
```
#### Item
```jsx theme={null}
```
```html theme={null}
```
# Recorder player
Source: https://docs.velt.dev/ui-customization/features/async/recorder/recorder-player
Recorder player component. This is the small player that appears when a recording is done.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## VideoContainer
```jsx theme={null}
```
```html theme={null}
```
#### Video
```jsx theme={null}
```
```html theme={null}
```
#### Timeline
```jsx theme={null}
```
```html theme={null}
```
#### PlayButton
```jsx theme={null}
```
```html theme={null}
```
#### SeekBar
```jsx theme={null}
```
```html theme={null}
```
#### FullScreenButton
```jsx theme={null}
```
```html theme={null}
```
#### Overlay
```jsx theme={null}
```
```html theme={null}
```
#### PlayButton
```jsx theme={null}
```
```html theme={null}
```
#### Time
```jsx theme={null}
```
```html theme={null}
```
#### Subtitles
```jsx theme={null}
```
```html theme={null}
```
#### Avatar
```jsx theme={null}
```
```html theme={null}
```
#### Name
```jsx theme={null}
```
```html theme={null}
```
#### SubtitlesButton
```jsx theme={null}
```
```html theme={null}
```
#### Transcription
```jsx theme={null}
```
```html theme={null}
```
#### EditButton
```jsx theme={null}
```
```html theme={null}
```
#### CopyLink
```jsx theme={null}
```
```html theme={null}
```
#### Delete
```jsx theme={null}
```
```html theme={null}
```
## AudioContainer
```jsx theme={null}
```
```html theme={null}
```
#### AudioToggle
```jsx theme={null}
```
```html theme={null}
```
#### Pause
```jsx theme={null}
```
```html theme={null}
```
#### Play
```jsx theme={null}
```
```html theme={null}
```
#### Time
```jsx theme={null}
```
```html theme={null}
```
#### AudioWaveform
```jsx theme={null}
```
```html theme={null}
```
#### Subtitles
```jsx theme={null}
```
```html theme={null}
```
#### Avatar
```jsx theme={null}
```
```html theme={null}
```
#### Name
```jsx theme={null}
```
```html theme={null}
```
#### SubtitlesButton
```jsx theme={null}
```
```html theme={null}
```
#### Transcription
```jsx theme={null}
```
```html theme={null}
```
#### CopyLink
```jsx theme={null}
```
```html theme={null}
```
#### Delete
```jsx theme={null}
```
```html theme={null}
```
#### Audio
This tag loads the audio recording and is hidden by default to prevent it from displaying in the UI.
```jsx theme={null}
```
```html theme={null}
```
# Recorder Player Expanded
Source: https://docs.velt.dev/ui-customization/features/async/recorder/recorder-player-expanded
Recorder player expanded component. This is the expanded player that appears when user wants to view the recording in full screen.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## Panel
```jsx theme={null}
```
```html theme={null}
```
#### Display
```jsx theme={null}
```
```html theme={null}
```
#### Subtitles
```jsx theme={null}
```
```html theme={null}
```
#### CopyLink
```jsx theme={null}
```
```html theme={null}
```
#### MinimizeButton
```jsx theme={null}
```
```html theme={null}
```
#### Controls
```jsx theme={null}
```
```html theme={null}
```
#### ProgressBar
```jsx theme={null}
```
```html theme={null}
```
#### ToggleButton
```jsx theme={null}
```
```html theme={null}
```
##### Pause
```jsx theme={null}
```
```html theme={null}
```
##### Play
```jsx theme={null}
```
```html theme={null}
```
#### Time
```jsx theme={null}
```
```html theme={null}
```
##### CurrentTime
```jsx theme={null}
```
```html theme={null}
```
##### TotalTime
```jsx theme={null}
```
```html theme={null}
```
#### SubtitleButton
```jsx theme={null}
```
```html theme={null}
```
##### Icon
```jsx theme={null}
```
```html theme={null}
```
##### Tooltip
```jsx theme={null}
```
```html theme={null}
```
#### TranscriptionButton
```jsx theme={null}
```
```html theme={null}
```
##### Icon
```jsx theme={null}
```
```html theme={null}
```
##### Tooltip
```jsx theme={null}
```
```html theme={null}
```
#### VolumeButton
```jsx theme={null}
```
```html theme={null}
```
#### SettingsButton
```jsx theme={null}
```
```html theme={null}
```
#### DeleteButton
```jsx theme={null}
```
```html theme={null}
```
## Transcription
```jsx theme={null}
```
```html theme={null}
```
# Recorder Tool
Source: https://docs.velt.dev/ui-customization/features/async/recorder/recorder-tool
The button to add new recordings.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltRecorderAllToolWireframe
```jsx theme={null}
{/* ... Add your content here */}
```
```html theme={null}
```
### VeltRecorderAllToolMenuWireframe
```jsx theme={null}
{/* ... Add your content here */}
{/* ... Add your content here */}
{/* ... Add your content here */}
```
```html theme={null}
```
#### Audio
```jsx theme={null}
{/* ... Add your content here */}
```
```html theme={null}
```
#### Video
```jsx theme={null}
{/* ... Add your content here */}
```
```html theme={null}
```
#### Screen
```jsx theme={null}
{/* ... Add your content here */}
```
```html theme={null}
```
## VeltRecorderAudioToolWireframe
```jsx theme={null}
{/* ... Add your content here */}
```
```html theme={null}
```
## VeltRecorderVideoToolWireframe
```jsx theme={null}
{/* ... Add your content here */}
```
```html theme={null}
```
## VeltRecorderScreenToolWireframe
```jsx theme={null}
{/* ... Add your content here */}
```
```html theme={null}
```
# Styling
## Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
`Default: true`
```jsx theme={null}
```html theme={null}
## Dark Mode
`Default: false`
```js theme={null}
```html theme={null}
# Recording Preview Steps Dialog
Source: https://docs.velt.dev/ui-customization/features/async/recorder/recording-preview-steps-dialog
Recording preview steps dialog component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
### Audio
This component is used for audio recording preview.
```jsx theme={null}
```
```html theme={null}
```
#### Audio Bottom Panel
Bottom panel of the audio recording preview dialog.
```jsx theme={null}
```
```html theme={null}
```
##### Icon
```jsx theme={null}
```html theme={null}
##### Countdown
```jsx theme={null}
```html theme={null}
##### Close
```jsx theme={null}
```html theme={null}
#### Audio Button Panel
Button panel of the audio recording preview dialog.
```jsx theme={null}
```
```html theme={null}
```
##### Start Recording
```jsx theme={null}
```html theme={null}
##### Mic Button
```jsx theme={null}
```
```html theme={null}
```
###### On
```jsx theme={null}
```html theme={null}
###### Off
```jsx theme={null}
```html theme={null}
##### Settings
```jsx theme={null}
```html theme={null}
#### Audio Timer
Timer of the audio recording preview dialog.
```jsx theme={null}
```
```html theme={null}
```
##### Countdown
```jsx theme={null}
```html theme={null}
##### Cancel
```jsx theme={null}
```html theme={null}
#### Close Button
```jsx theme={null}
```html theme={null}
#### Waveform
```jsx theme={null}
```html theme={null}
#### Settings Panel
```jsx theme={null}
```html theme={null}
### Video
This component is used for both video and screen recording previews.
```jsx theme={null}
```
```html theme={null}
```
#### Video Bottom Panel
Bottom panel of the video recording preview dialog.
```jsx theme={null}
// If you want to customize the Icon for individual media types, you can use the following:
{/* Your custom icon here */}
{/* Your custom icon here */}
{/* Your custom icon here */}
```
```html theme={null}
```
##### Icon
```jsx theme={null}
{/* audio icon */}
{/* video icon */}
{/* screen icon */}
```
```html theme={null}
##### Countdown
```jsx theme={null}
```html theme={null}
##### Close
```jsx theme={null}
```html theme={null}
#### Video Button Panel
Button panel of the video recording preview dialog.
```jsx theme={null}
```
```html theme={null}
```
##### Start Recording
```jsx theme={null}
```html theme={null}
##### Mic Button
```jsx theme={null}
```
```html theme={null}
```
###### On
```jsx theme={null}
```html theme={null}
###### Off
```jsx theme={null}
```html theme={null}
##### Camera Button
```jsx theme={null}
```
```html theme={null}
```
###### On
```jsx theme={null}
```html theme={null}
###### Off
```jsx theme={null}
```html theme={null}
##### Settings
```jsx theme={null}
```html theme={null}
#### Video Timer
Timer of the video recording preview dialog.
```jsx theme={null}
```
```html theme={null}
```
##### Countdown
```jsx theme={null}
```html theme={null}
##### Cancel
```jsx theme={null}
```html theme={null}
#### Waveform
```jsx theme={null}
```html theme={null}
#### Close Button
```jsx theme={null}
```html theme={null}
#### Camera Off Message
```jsx theme={null}
```html theme={null}
#### Settings Panel
```jsx theme={null}
```html theme={null}
#### Video Player
```jsx theme={null}
```html theme={null}
#### ScreenPlayer (Video)
This component is used for screen recording preview within the video dialog. It displays the screen capture content for screen recordings.
```jsx theme={null}
```
```html theme={null}
```
# Subtitles
Source: https://docs.velt.dev/ui-customization/features/async/recorder/subtitles
Subtitles component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## EmbedMode
```jsx theme={null}
```
```html theme={null}
```
#### Text
```jsx theme={null}
```
```html theme={null}
```
## FloatingMode
```jsx theme={null}
```
```html theme={null}
```
#### Button
```jsx theme={null}
```
```html theme={null}
```
#### Tooltip
```jsx theme={null}
```
```html theme={null}
```
#### Panel
```jsx theme={null}
```
```html theme={null}
```
#### CloseButton
```jsx theme={null}
```
```html theme={null}
```
#### Text
```jsx theme={null}
```
```html theme={null}
```
# Transcription
Source: https://docs.velt.dev/ui-customization/features/async/recorder/transcription
Transcription component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
## FloatingMode
```jsx theme={null}
```
```html theme={null}
```
#### Button
```jsx theme={null}
```
```html theme={null}
```
#### Tooltip
```jsx theme={null}
```
```html theme={null}
```
#### PanelContainer
```jsx theme={null}
```
```html theme={null}
```
#### Panel
```jsx theme={null}
```
```html theme={null}
```
#### CloseButton
```jsx theme={null}
```
```html theme={null}
```
#### CopyLink
```jsx theme={null}
```
```html theme={null}
```
#### Button
```jsx theme={null}
```
```html theme={null}
```
#### Tooltip
```jsx theme={null}
```
```html theme={null}
```
#### Summary
```jsx theme={null}
```
```html theme={null}
```
#### Text
```jsx theme={null}
```
```html theme={null}
```
#### ExpandToggle
```jsx theme={null}
```
```html theme={null}
```
#### On
```jsx theme={null}
```
```html theme={null}
```
#### Off
```jsx theme={null}
```
```html theme={null}
```
#### Content
```jsx theme={null}
```
```html theme={null}
```
#### Item
```jsx theme={null}
```
```html theme={null}
```
#### Text
```jsx theme={null}
```
```html theme={null}
```
#### Time
```jsx theme={null}
```
```html theme={null}
```
## EmbedMode
```jsx theme={null}
```
```html theme={null}
```
#### Panel
```jsx theme={null}
```
```html theme={null}
```
#### CloseButton
```jsx theme={null}
```
```html theme={null}
```
#### CopyLink
```jsx theme={null}
```
```html theme={null}
```
#### Button
```jsx theme={null}
```
```html theme={null}
```
#### Tooltip
```jsx theme={null}
```
```html theme={null}
```
#### Summary
```jsx theme={null}
```
```html theme={null}
```
#### Text
```jsx theme={null}
```
```html theme={null}
```
#### ExpandToggle
```jsx theme={null}
```
```html theme={null}
```
#### On
```jsx theme={null}
```
```html theme={null}
```
#### Off
```jsx theme={null}
```
```html theme={null}
```
#### Content
```jsx theme={null}
```
```html theme={null}
```
#### Item
```jsx theme={null}
```
```html theme={null}
```
#### Text
```jsx theme={null}
```
```html theme={null}
```
#### Time
```jsx theme={null}
```
```html theme={null}
```
# Video Editor
Source: https://docs.velt.dev/ui-customization/features/async/recorder/video-editor
Video editor component.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## Overview
```jsx theme={null}
```
```html theme={null}
```
### Title
```jsx theme={null}
```
```html theme={null}
```
### ApplyButton
```jsx theme={null}
```
```html theme={null}
```
#### Loading
```jsx theme={null}
```
```html theme={null}
```
### RetakeButton
```jsx theme={null}
```
```html theme={null}
```
### DownloadButton
```jsx theme={null}
```
```html theme={null}
```
### CloseButton
```jsx theme={null}
```
```html theme={null}
```
### Preview
```jsx theme={null}
```
```html theme={null}
```
#### Loading
```jsx theme={null}
```
```html theme={null}
```
#### Video
```jsx theme={null}
```
```html theme={null}
```
### ToggleButton
```jsx theme={null}
```
```html theme={null}
```
### Time
```jsx theme={null}
```
```html theme={null}
```
#### CurrentTime
```jsx theme={null}
```
```html theme={null}
```
#### TotalTime
```jsx theme={null}
```
```html theme={null}
```
### SplitButton
```jsx theme={null}
```
```html theme={null}
```
#### CurrentTime
```jsx theme={null}
```
```html theme={null}
```
### DeleteButton
```jsx theme={null}
```
```html theme={null}
```
### AddZoomButton
```jsx theme={null}
```
```html theme={null}
```
### Timeline
```jsx theme={null}
```
```html theme={null}
```
#### BackspaceHint
```jsx theme={null}
```
```html theme={null}
```
#### Onboarding
```jsx theme={null}
```
```html theme={null}
```
##### **Content**
```jsx theme={null}
```
```html theme={null}
```
##### **Text**
```jsx theme={null}
```
```html theme={null}
```
###### **Title**
```jsx theme={null}
```
```html theme={null}
```
###### **Description**
```jsx theme={null}
```
```html theme={null}
```
##### **Arrow**
```jsx theme={null}
```
```html theme={null}
```
#### Container
```jsx theme={null}
```
```html theme={null}
```
##### **Playhead**
```jsx theme={null}
```
```html theme={null}
```
###### **Line**
```jsx theme={null}
```
```html theme={null}
```
###### **Actions**
```jsx theme={null}
```
```html theme={null}
```
##### **Trim**
```jsx theme={null}
```
```html theme={null}
```
##### **Scale**
```jsx theme={null}
```
```html theme={null}
```
###### **ZoomButton**
```jsx theme={null}
```
```html theme={null}
```
###### **Trigger**
```jsx theme={null}
```
```html theme={null}
```
###### **Options**
```jsx theme={null}
```
```html theme={null}
```
###### **List**
```jsx theme={null}
```
```html theme={null}
```
###### **Item**
```jsx theme={null}
```
```html theme={null}
```
###### **Input**
```jsx theme={null}
```
```html theme={null}
```
#### Marker
```jsx theme={null}
```
```html theme={null}
```
# Cursors
Source: https://docs.velt.dev/ui-customization/features/realtime/cursors
The Cursors component displays the cursors of users in a document.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltCursorPointerWireframe
```jsx theme={null}
```
```html theme={null}
```
### Arrow
```jsx theme={null}
```
```html theme={null}
```
### Avatar
```jsx theme={null}
```
```html theme={null}
```
### Default
```jsx theme={null}
```
```html theme={null}
```
#### Name
```jsx theme={null}
```
```html theme={null}
```
#### Comment
```jsx theme={null}
```
```html theme={null}
```
### AudioHuddle
```jsx theme={null}
```
```html theme={null}
```
#### Avatar
```jsx theme={null}
```
```html theme={null}
```
#### Audio
```jsx theme={null}
```
```html theme={null}
```
### VideoHuddle
```jsx theme={null}
```
```html theme={null}
```
# Parts
Source: https://docs.velt.dev/ui-customization/features/realtime/huddle/parts
We offer several parts which can be used like classes. Full list below.
The component is encapsulated in Shadow DOM, which is isolated from the normal DOM.
Set whatever CSS rules you want.
The part lets you target a specific element within a Shadow DOM.
Reference the table below to see what parts we expose.
Alternatively, you can directly inspect the component HTML to see what parts are available.
| property | description |
| ------------------ | ----------------------------------------- |
| `container` | Targets the comment tool container |
| `button-container` | Targets the comment tool button container |
| `button-icon` | Targets the comment tool button SVG icon |
```css Tool theme={null}
velt-huddle-tool::part(button-icon) {
width: 1.5rem;
height: 1.5rem;
}
```
# Slots
Source: https://docs.velt.dev/ui-customization/features/realtime/huddle/slots
Provide a template for the Huddle Tool.
Target the `button` slot with your own custom template.
```js theme={null}
Huddle
```
Provide a template for the Huddle Tool.
Target the `button` slot with your own custom template.
```html theme={null}
Huddle
```
```js React / Next.js theme={null}
import {
VeltHuddleTool
} from '@veltdev/react';
export default function App() {
return (
<>
Huddle
);
}
```
```html HTML theme={null}
Huddle documentation
Huddle
```
# Variables
Source: https://docs.velt.dev/ui-customization/features/realtime/huddle/variables
To update CSS variables for the Huddle Tool, please refer to [Global Styles](/global-styles/global-styles)
# Live Selection
Source: https://docs.velt.dev/ui-customization/features/realtime/live-selection
## 1. Enable/Disable Default Styling
* When enabled, the SDK will apply default styling to the selected elements.
* When disabled, the SDK will not apply any styling to the selected elements. You can use these classes to style the selected elements:
* `.velt-live-selection-on-element`: This dynamic class will be added to the selected element only when there is a user on that element.
* `.velt-live-selection-on-text`: This dynamic class will be added to the text node only when a user has selected that text.
* Default: `Enabled`.
```javascript theme={null}
const selectionElement = client.getSelectionElement();
selectionElement.enableDefaultStyling();
selectionElement.disableDefaultStyling();
```
**Custom Styling:**
```css theme={null}
.velt-live-selection-on-element {
outline: 2px solid var(--velt-color);
outline-offset: -2px;
}
```
```javascript theme={null}
const selectionElement = Velt.getSelectionElement();
selectionElement.enableDefaultStyling();
selectionElement.disableDefaultStyling();
```
**Custom Styling:**
```css theme={null}
.velt-live-selection-on-element {
outline: 2px solid var(--velt-color);
outline-offset: -2px;
}
```
# Presence
Source: https://docs.velt.dev/ui-customization/features/realtime/presence
The Presence component displays the avatars of users in a room.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltPresenceWireframe
```jsx theme={null}
```
```html theme={null}
```
### AvatarList
```jsx theme={null}
```
```html theme={null}
```
#### Item
```jsx theme={null}
```
```html theme={null}
```
### AvatarRemainingCount
```jsx theme={null}
```
```html theme={null}
```
## VeltPresenceTooltipWireframe
```jsx theme={null}
```
```html theme={null}
```
### Avatar
```jsx theme={null}
```
```html theme={null}
```
### StatusContainer
```jsx theme={null}
```
```html theme={null}
```
#### UserName
```jsx theme={null}
```
```html theme={null}
```
#### UserActive
```jsx theme={null}
```
```html theme={null}
```
#### UserInactive
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, ShadowDOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
```jsx theme={null}
```jsx theme={null}
# Single Editor Mode
Source: https://docs.velt.dev/ui-customization/features/realtime/single-editor-mode
Wireframes for the Single Editor Mode Panel.
We recommend that you familiarize yourselves with [UI Customization Concepts](/ui-customization/overview) before attempting to modify any components.
## VeltSingleEditorModePanelWireframe
```jsx theme={null}
```
```html theme={null}
```
### ViewerText
```jsx theme={null}
```
```html theme={null}
```
### EditorText
```jsx theme={null}
```
```html theme={null}
```
### Countdown
```jsx theme={null}
```
```html theme={null}
```
### EditHere
```jsx theme={null}
```
```html theme={null}
```
### AcceptRequest
```jsx theme={null}
```
```html theme={null}
```
### RejectRequest
```jsx theme={null}
```
```html theme={null}
```
### RequestAccess
```jsx theme={null}
```
```html theme={null}
```
### CancelRequest
```jsx theme={null}
```
```html theme={null}
```
## Styling
### Disable ShadowDOM
* By default, Shadow DOM is used to ensure that your app's CSS does not interfere with the styling of the SDK components.
* Disable the shadow dom to apply your custom CSS to the component.
Default: `true`
```jsx theme={null}
```html theme={null}
### Dark Mode
By default, all components are in Light Mode. Use this prop to enable Dark Mode.
Default: `false`
```js theme={null}
```html theme={null}
### Variants
You can apply variants like you do for other components. You need to define variants using Wireframes. Read more here [here](/ui-customization/layout#create-custom-variants).
```js theme={null}
```html theme={null}
# Layout Customization
Source: https://docs.velt.dev/ui-customization/layout
# Overview
This lets you modify how components are structured and rendered in your app. You can:
* Replace default HTML with your own components and HTML structure
* Remove or reorder components
* Create multiple variants of the same component
All layout customizations are done using Wireframe components that act as templates. Changes apply globally wherever that component is used.
Styling note: Passing `className`/`style` to Velt components does not change their UI. Add your classes/styles inside the Wireframe templates, or use CSS overrides with Shadow DOM disabled. See [Styling](/ui-customization/styling).
# Ways to Customize Layout
### Single Component Customization (Targeted)
This lets you customize individual parts of a component without dealing with the entire structure. **We recommend this approach for most use cases**.
**Benefits:**
* Simpler, more maintainable code
* Focus on just the parts you need to change
* Greater flexibility for specific UI elements
**Example:** Customizing just the Comment Dialog header:
```jsx theme={null}
```
```html theme={null}
```
### Full Component Tree Customization (Comprehensive)
Use this pattern when you need to modify the entire component structure or multiple related components.
**Benefits:**
* Complete control over component hierarchy
* Easier to modify relationships between components
* Better for large-scale structural changes
**Drawbacks:**
* Custom CSS required for the entire component tree since adding children components to wireframes removes Velt's default styles.
**Example:** Customizing the entire Comment Dialog structure:
```jsx theme={null}
```
```html theme={null}
```
# Variants
Variants allow you to:
* Create multiple styled versions of the same component
* Switch between them dynamically in different parts of your app
* Maintain consistent behavior while having different looks
### Create Custom Variants
Custom variants let you define your own versions of components. For example: You can have a variant of Comment Sidebar for one page and another for another page.
On the wireframe component, add the `variant` prop to define your custom variants.
```jsx theme={null}
{/* Variant for preview page */}
{/* Custom layout for preview */}
{/* Variant for editor page */}
{/* Custom layout for editor */}
```
```html theme={null}
{/* Variant for preview page */}
{/* Custom layout for preview */}
{/* Variant for editor page */}
{/* Custom layout for editor */}
```
* Use the `variant` prop on the related Velt component to apply the custom variant you defined. The value should match the variant name from step 1.
* For example, use `variant="preview-page"` to apply the preview page variant you created above.
```jsx theme={null}
```html theme={null}
### Use Pre-defined Variants
Many components come with built-in variants optimized for specific use cases. For example, the Comment Dialog has two pre-defined variants for different contexts:
```jsx theme={null}
{/* For Pin, Area, and Text comments */}
{/* Custom layout */}
{/* For Sidebar comments */}
{/* Custom layout */}
```
```html theme={null}
{/* For Pin, Area, and Text comments */}
{/* Custom layout */}
{/* For Sidebar comments */}
{/* Custom layout */}
```
* Each component's documentation lists its supported pre-defined variants
* Pre-defined variants are optimized for specific use cases but can still be customized
* You can combine pre-defined variants with your own custom styling
# Common Customization Tasks
### Replace Default Layout
Simply provide your own HTML or components as children of the wireframe component:
```jsx theme={null}
```
```html theme={null}
```
### Remove Components
To remove a component, you either:
* simply omit it from the wireframe template as shown below, or
* use [Conditional Templates](/ui-customization/conditional-templates)
```jsx theme={null}
{/* Priority and CopyLink buttons removed */}
```
```html theme={null}
{/* Priority and CopyLink buttons removed */}
```
### Reorder Components
To reorder components, simply rearrange them within the wireframe template.
```jsx theme={null}
```
```html theme={null}
```
# Localisation
Source: https://docs.velt.dev/ui-customization/localisation
Localize all static strings visible in the SDK Components.
If you notice any missing strings, please reach out to us.
## Steps
Get the complete list of strings that can be localized [here](https://firebasestorage.googleapis.com/v0/b/snippyly.appspot.com/o/external%2Flocalization-strings-map.json?alt=media\&token=0cdd2b52-10ed-4033-a08a-5c2b622ce7df).
* Translate the strings in the languages you want to support.
* Create an object with the translations for the languages you want to support in the following format:
```json theme={null}
{
"language-code-1": {
"original string 1": "translated string 1",
"original string 2": "translated string 2",
...
},
"language-code-2": {
"original string 1": "translated string 1",
"original string 2": "translated string 2",
...
},
...
}
```
Call the `setTranslations` method with the translations object you created in the previous step.
```js theme={null}
client.setTranslations(translationsObject);
```
Set the language you want to use for the SDK. The language code should be the same as the language code you used in the translations object.
```js theme={null}
client.setLanguage('en');
```
## Example
```jsx theme={null}
// Provide the localization object for the languages you want to support.
client.setTranslations({
'en': {
'All comments': 'All comments',
},
'fr': {
'All comments': 'Tous les commentaires',
},
// Add more languages as needed.
});
// Set one of the languages you've provided the translations for.
client.setLanguage('en');
```
```js theme={null}
// Provide the localization object for the languages you want to support.
Velt.setTranslations({
'en': {
'All comments': 'All comments',
},
'fr': {
'All comments': 'Tous les commentaires',
},
// Add more languages as needed.
});
// Set one of the languages you've provided the translations for.
Velt.setLanguage('en');
```
# Overview
Source: https://docs.velt.dev/ui-customization/overview
Velt Components can be customized in 5 key ways:
1. [**Layout**](#1-layout): For structure and organization of components
2. [**Styling**](#2-styling): For visual design using CSS, themes, or your CSS framework
3. [**Template Variables**](#3-template-variables): For rendering dynamic content
4. [**Conditional Templates**](#4-conditional-templates): For custom rendering logic
5. [**Action Components**](#5-action-components): For interactivity and custom behaviors
# 1. Layout
### Understanding Wireframes
Think of Wireframes like blueprints - they're templates that let you customize how Velt components render in your app. They are not functional components. Define them once, and Velt will swap in your custom template wherever a component renders, overriding the default.
When you create a wireframe:
* It acts as a global template
* Changes apply everywhere that component is used
* You can use your own components and HTML structure
**What you can do:**
* ✅ Use your own Components/HTML
* ✅ Apply your styling
* ✅ Nest regular HTML elements
* ✅ Use other Velt wireframe components
**Limitations with Wireframes:**
* ❌ Cannot nest regular Velt components inside wireframes
* ❌ Host App's dynamic variables: Won't work directly inside wireframes.
* ❌ Host App's JavaScript: Custom scripts won't run natively inside wireframes.
**How Velt solves these:**
* **Host App's dynamic variables:** Use [UI State](/ui-customization/template-variables#2-injecting-your-own-data) to inject your app's dynamic variables into Velt components seamlessly. This is available across all Velt Wireframes.
* **Host App's JavaScript:** Wrap your component in [`VeltButtonWireframe`](/ui-customization/custom-action-component). It exposes a callback. Listen for it to trigger your custom JS logic.
Empty wireframes keep Velt's default styling.
Adding any children to a wireframe template removes most of its default styling. This gives you full control over the layout.
However, you will still need to use a combination of CSS overrides on any remaining styles and your own components to achieve the desired styling.
### a. Replace Layout
Replace Velt's default HTML with your own structure.
[Learn more](/ui-customization/layout#replace-default-layout)
### b. Remove Components
Remove specific parts of a Velt component you don't need.
[Learn more](/ui-customization/layout#remove-components)
### c. Reorder Components
Change the order of elements within a Velt component.
[Learn more](/ui-customization/layout#reorder-components)
### d. Use Variants
Need different versions of the same component? Use variants to:
* Create multiple styled versions
* Switch between them dynamically
* Maintain consistent behavior with different looks
[Learn more about variants](/ui-customization/layout#variants)
# 2. Styling
Velt components can be styled in two main ways:
### a. Themes
**NEW:** Try the [Theme Playground](https://playground.velt.dev/themes) to visually customize and preview themes.
1. **CSS Variables:** Quickest way to match your design system using CSS variables. This gets applied to all components globally. [Learn more](/ui-customization/styling#themes)
2. **Dark Mode:** Built in support for light and dark modes. [Learn more](/ui-customization/styling#dark-mode)
### b. Custom CSS or libraries
1. **Custom CSS or frameworks:** Gives you full control over the styling of Velt components using your own CSS or frameworks. This requires disabling Shadow DOM. [Learn more](/ui-customization/styling#custom-css-or-libraries)
2. **Conditional Classes:** Apply classes conditionally based available template variables. [Learn more](/ui-customization/styling#conditional-classes)
Passing `className` or `style` to Velt components does not change their UI. Style via Wireframes (by adding your own HTML and classes inside the templates) or via CSS overrides with Shadow DOM disabled.
# 3. Template Variables
Template Variables let you work with dynamic data in two ways:
a. **Use Existing Velt Component Data**
* Access and render data that's already present inside Velt components.
* eg: Customer metadata set on comment threads.
b. **Inject Your App's Data**
* Inject and render custom dynamic data from your application into Velt components.
[Learn more](/ui-customization/template-variables)
# 4. Conditional Templates
Add logic to show/hide components based on the template variables.
[Learn more](/ui-customization/conditional-templates)
# 5. Action Components
* Extend the functionality of any Velt component.
* Clicking an action button provides a callback where you can write your own custom code.
[Learn more](/ui-customization/custom-action-component)
# Setup Wireframes
Source: https://docs.velt.dev/ui-customization/setup
# Understanding Wireframes
Wireframes are templates that define how Velt components should render in your app:
* Act as global templates. Changes apply everywhere the component is used.
* Allow full customization of layout and styling.
* Wireframes themselves don't render in the DOM.
Adding any children to a wireframe template removes most of its default styling. This gives you full control over the layout.
However, you will still need to use a combination of CSS overrides on any remaining styles and your own components to achieve the desired styling.
## Step-by-Step Setup
```jsx theme={null}
import { VeltWireframe, VeltProvider } from '@veltdev/react'
{/* Your customization templates */}
```
```html theme={null}
```
Copy the wireframe template of the component you want to customize. You can find the wireframe templates in the component's UI Customization documentation.
```jsx theme={null}
{/* Example: Customizing Comment Dialog Header */}
```
```html theme={null}
```
You can customize using the options like:
* [Layout](/ui-customization/layout): Customize the layout of the component
* [Styling](/ui-customization/styling): Apply custom CSS and [themes](https://playground.velt.dev/themes)
* [Template Variables](/ui-customization/template-variables): Add dynamic content to your templates
* [Conditional Templates](/ui-customization/conditional-templates): Add conditional rendering logic
* [Custom Actions](/ui-customization/custom-action-component): Add custom interactivity
**Example:**
```jsx theme={null}
Custom HTML
```
```html theme={null}
Custom HTML
```
* After defining templates, use the actual feature components in your app as normal.
* The wireframe components are not meant to be rendered directly in your application. They merely serve as template definitions.
```jsx theme={null}
function MyApp() {
return (
)
}
```
```html theme={null}
```
# CSS Customization
Source: https://docs.velt.dev/ui-customization/styling
**NEW:** Try out the [Theme Playground](https://playground.velt.dev/themes) to visually customize and preview your themes.
Velt components can be styled in two main ways:
1. **Themes**
2. **Custom CSS**
Direct classes and inline styles on Velt components are not applied. Passing `className` or `style` to a Velt component does not change its UI. Add classes/styles to your HTML inside the corresponding Wireframe template, or use CSS overrides after disabling Shadow DOM.
# Themes
You can use the [Theme Playground](https://playground.velt.dev/themes) to customize and preview the themes fast.
### CSS Variables
* You can customize:
* Border radius
* Spacing
* Typography
* Colors for light and dark modes
* Z-Index
* Set CSS variables on your `` tag to customize all Velt components:
**Example:**
```css theme={null}
body {
/* Colors */
--velt-light-mode-accent: #0BA528;
/* Border Radius */
--velt-border-radius-sm: 4px;
/* Spacing */
--velt-spacing-sm: 8px;
}
```
**Available Theme Variables:**
```css theme={null}
--velt-border-radius-2xs: 0.125rem; // 2px
--velt-border-radius-xs: 0.25rem; // 4px
--velt-border-radius-sm: 0.5rem; // 8px
--velt-border-radius-md: 0.75rem; // 12px
--velt-border-radius-lg: 1rem; // 16px
--velt-border-radius-xl: 1.25rem; // 20px
--velt-border-radius-2xl: 1.5rem; // 24px
--velt-border-radius-3xl: 2rem; // 32px
--velt-border-radius-full: 5rem; // 80px
```
```css theme={null}
--velt-spacing-2xs: 0.125rem; // 2px
--velt-spacing-xs: 0.25rem; // 4px
--velt-spacing-sm: 0.5rem; // 8px
--velt-spacing-md: 0.75rem; // 12px
--velt-spacing-lg: 1rem; // 16px
--velt-spacing-xl: 1.25rem; // 20px
--velt-spacing-2xl: 1.5rem; // 24px
```
```css theme={null}
--velt-default-font-family: sans-serif;
--velt-font-size-2xs: 0.625rem; // 10px
--velt-font-size-xs: 0.75rem; // 12px
--velt-font-size-sm: 0.875rem; // 14px
--velt-font-size-md: 1rem; // 16px
--velt-font-size-lg: 1.5rem; // 24px
--velt-font-size-xl: 1.75rem; // 28px
--velt-font-size-2xl: 2rem; // 32px
```
```css theme={null}
/* Base Colors */
--velt-light-mode-green: #0DCF82;
--velt-light-mode-magenta: #A259FE;
--velt-light-mode-amber: #FF7162;
--velt-light-mode-purple: #625DF5;
--velt-light-mode-cyan: #4BC9F0;
--velt-light-mode-orange: #FE965C;
--velt-light-mode-black: #080808;
--velt-light-mode-white: #FFFFFF;
--velt-light-mode-gray: #EBEBEB;
/* Accent Colors */
--velt-light-mode-accent: #625DF5;
--velt-light-mode-accent-text: #9491F8;
--velt-light-mode-accent-hover: #534FCF;
--velt-light-mode-accent-foreground: #FFFFFF;
--velt-light-mode-accent-light: #F2F2FE;
--velt-light-mode-accent-transparent: rgba(148, 145, 248, 0.08);
/* Text Shades */
--velt-light-mode-text-0: #0A0A0A;
--velt-light-mode-text-1: #141414;
--velt-light-mode-text-2: #1F1F1F;
--velt-light-mode-text-3: #292929;
--velt-light-mode-text-4: #3D3D3D;
--velt-light-mode-text-5: #525252;
--velt-light-mode-text-6: #666666;
--velt-light-mode-text-7: #7A7A7A;
--velt-light-mode-text-8: #858585;
--velt-light-mode-text-9: #999999;
--velt-light-mode-text-10: #B8B8B8;
--velt-light-mode-text-11: #A3A3A3;
--velt-light-mode-text-12: #8F8F8F;
/* Background Shades */
--velt-light-mode-background-0: #FFFFFF;
--velt-light-mode-background-1: #FAFAFA;
--velt-light-mode-background-2: #F5F5F5;
--velt-light-mode-background-3: #F0F0F0;
--velt-light-mode-background-4: #EBEBEB;
--velt-light-mode-background-5: #E5E5E5;
--velt-light-mode-background-6: #E0E0E0;
--velt-light-mode-background-7: #DBDBDB;
--velt-light-mode-background-8: #D6D6D6;
--velt-light-mode-background-9: #D1D1D1;
--velt-light-mode-background-10: #CCCCCC;
/* Border Shades */
--velt-light-mode-border-0: #FFFFFF;
--velt-light-mode-border-1: #FAFAFA;
--velt-light-mode-border-2: #F5F5F5;
--velt-light-mode-border-3: #F0F0F0;
--velt-light-mode-border-4: #EBEBEB;
--velt-light-mode-border-5: #E5E5E5;
--velt-light-mode-border-6: #E0E0E0;
--velt-light-mode-border-7: #DBDBDB;
--velt-light-mode-border-8: #D6D6D6;
--velt-light-mode-border-9: #D1D1D1;
--velt-light-mode-border-10: #CCCCCC;
/* Status Colors */
/* Error */
--velt-light-mode-error: #FF7162;
--velt-light-mode-error-hover: #DE5041;
--velt-light-mode-error-foreground: #FFFFFF;
--velt-light-mode-error-light: #FFF4F2;
--velt-light-mode-error-transparent: rgba(255, 113, 98, 0.08);
/* Warning */
--velt-light-mode-warning: #FFCD2E;
--velt-light-mode-warning-hover: #C69400;
--velt-light-mode-warning-foreground: #474747;
--velt-light-mode-warning-light: #FFFBEE;
--velt-light-mode-warning-transparent: rgba(255, 205, 46, 0.08);
/* Success */
--velt-light-mode-success: #198F65;
--velt-light-mode-success-hover: #006B41;
--velt-light-mode-success-foreground: #FFFFFF;
--velt-light-mode-success-light: #EDF6F3;
--velt-light-mode-success-transparent: rgba(25, 143, 101, 0.08);
/* Transparent Colors */
--velt-light-mode-background-transparent: rgba(255, 255, 255, 0.80);
--velt-light-mode-border-transparent: rgba(0, 0, 0, 0.16);
--velt-light-mode-animation-transparent: rgba(255, 255, 255, 0.2);
```
```css theme={null}
/* Base Colors */
--velt-dark-mode-green: #0DCF82;
--velt-dark-mode-magenta: #A259FE;
--velt-dark-mode-amber: #FF7162;
--velt-dark-mode-purple: #625DF5;
--velt-dark-mode-cyan: #4BC9F0;
--velt-dark-mode-orange: #FE965C;
--velt-dark-mode-black: #080808;
--velt-dark-mode-white: #FFFFFF;
--velt-dark-mode-gray: #EBEBEB;
/* Accent Colors */
--velt-dark-mode-accent: #625DF5;
--velt-dark-mode-accent-text: #9491F8;
--velt-dark-mode-accent-hover: #534FCF;
--velt-dark-mode-accent-foreground: #FFFFFF;
--velt-dark-mode-accent-light: #F2F2FE;
--velt-dark-mode-accent-transparent: rgba(148, 145, 248, 0.08);
/* Text Shades */
--velt-dark-mode-text-0: #FFFFFF;
--velt-dark-mode-text-1: #F5F5F5;
--velt-dark-mode-text-2: #EBEBEB;
--velt-dark-mode-text-3: #E0E0E0;
--velt-dark-mode-text-4: #D6D6D6;
--velt-dark-mode-text-5: #C2C2C2;
--velt-dark-mode-text-6: #ADADAD;
--velt-dark-mode-text-7: #8F8F8F;
--velt-dark-mode-text-8: #7A7A7A;
--velt-dark-mode-text-9: #666666;
--velt-dark-mode-text-10: #525252;
--velt-dark-mode-text-11: #474747;
--velt-dark-mode-text-12: #3D3D3D;
/* Background Shades */
--velt-dark-mode-background-0: #0F0F0F;
--velt-dark-mode-background-1: #1A1A1A;
--velt-dark-mode-background-2: #1F1F1F;
--velt-dark-mode-background-3: #242424;
--velt-dark-mode-background-4: #292929;
--velt-dark-mode-background-5: #2E2E2E;
--velt-dark-mode-background-6: #333333;
--velt-dark-mode-background-7: #383838;
--velt-dark-mode-background-8: #3D3D3D;
--velt-dark-mode-background-9: #424242;
--velt-dark-mode-background-10: #474747;
/* Border Shades */
--velt-dark-mode-border-0: #0F0F0F;
--velt-dark-mode-border-1: #1A1A1A;
--velt-dark-mode-border-2: #1F1F1F;
--velt-dark-mode-border-3: #242424;
--velt-dark-mode-border-4: #292929;
--velt-dark-mode-border-5: #2E2E2E;
--velt-dark-mode-border-6: #333333;
--velt-dark-mode-border-7: #383838;
--velt-dark-mode-border-8: #3D3D3D;
--velt-dark-mode-border-9: #424242;
--velt-dark-mode-border-10: #474747;
/* Status Colors */
/* Error */
--velt-dark-mode-error: #FF7162;
--velt-dark-mode-error-hover: #DE5041;
--velt-dark-mode-error-foreground: #FFFFFF;
--velt-dark-mode-error-light: #FFF4F2;
--velt-dark-mode-error-transparent: rgba(255, 113, 98, 0.08);
/* Warning */
--velt-dark-mode-warning: #FFCD2E;
--velt-dark-mode-warning-hover: #C69400;
--velt-dark-mode-warning-foreground: #474747;
--velt-dark-mode-warning-light: #FFFBEE;
--velt-dark-mode-warning-transparent: rgba(255, 205, 46, 0.08);
/* Success */
--velt-dark-mode-success: #198F65;
--velt-dark-mode-success-hover: #006B41;
--velt-dark-mode-success-foreground: #FFFFFF;
--velt-dark-mode-success-light: #EDF6F3;
--velt-dark-mode-success-transparent: rgba(25, 143, 101, 0.08);
/* Transparent Colors */
--velt-dark-mode-background-transparent: rgba(0, 0, 0, 0.80);
--velt-dark-mode-border-transparent: rgba(255, 255, 255, 0.16);
--velt-dark-mode-animation-transparent: rgba(255, 255, 255, 0.2);
```
```css theme={null}
/* Comment Pin, Triangle */
--velt-comment-pin-z-index: 2147483557;
/* Comments Minimap */
--velt-comments-minimap-z-index: 2147483637;
/* Persistent Comment Frame */
--velt-persistent-comment-frame-z-index: 2147483647;
/* Global Overlay */
--velt-global-overlay-z-index: 2147483637;
/* Recorder Player */
--velt-recorder-player-z-index: 2147483557;
/* Cursor */
--velt-cursor-z-index: 2147483647;
/* Arrow */
--velt-arrow-z-index: 2147483557;
/* Toast Popup */
--velt-toast-popup-z-index: 2147483647;
/* Live State Sync Overlay */
--velt-live-state-sync-overlay-z-index: 2147483647;
/* Follow Mode Overlay */
--velt-follow-mode-overlay-z-index: 2147483647;
```
### Dark Mode
* Enable dark mode globally or per component.
* Most components accept a `darkMode` prop (`dark-mode="true"` for non-React).
* Some components that are not directly injected by you like dialogs and pins use specific props (e.g. `dialogDarkMode`, `pinDarkMode`). You can add these props to the root component responsible for injecting them.
* Check each component's UI customization documentation for its dark mode props.
```jsx theme={null}
// Global
const client = useVeltClient();
client.setDarkMode(true);
// Per component example
```js theme={null}
// Global
const client = useVeltClient();
client.setDarkMode(true);
// Per component example
# Custom CSS or libraries
You can use your own CSS or libraries like Tailwind CSS to style the Velt components. You will need to disable the Shadow DOM to apply your styles.
### 1. **Using CSS on rendered components**
* Inspect the DOM using browser dev tools to find the class names and selectors of the target Velt components.
* Override the styles using your CSS.
* Make sure to [disable the Shadow DOM](#disable-shadow-dom) to apply your styles.
```css theme={null}
.velt-composer--input-button {
background-color: red;
border-radius: 0;
}
```
```css theme={null}
.velt-composer--input-button {
background-color: red;
border-radius: 0;
}
```
### 2. **Using CSS on Wireframes**
* Add the relevant wireframe component.
* Add class or inline styles to the wireframe component like you would on a normal HTML element.
* When the actual component is rendered, the styles will be applied to that component.
* Make sure to [disable the Shadow DOM](#disable-shadow-dom) to apply your styles.
* Passing `className` or `style` directly to Velt components does not change their UI; apply styling in the Wireframe template (or your own elements within it).
```jsx theme={null}
{/* Use CSS classes */}
{/* Or inline styles */}
```
```html theme={null}
```
### Component-Specific CSS Classes
Certain Velt components include CSS classes for specific states that you can target for custom styling. For example, the assign dropdown checkbox includes a CSS class to indicate the selected state on checkboxes.
To target the selected state, inspect the assign dropdown checkbox element in your browser dev tools to find the specific class name, then apply your custom styles. Make sure to [disable the Shadow DOM](#disable-shadow-dom) first.
```css theme={null}
/* Example: Style selected checkboxes in assign dropdown */
/* Inspect the DOM to find the exact class name */
.velt-assign-dropdown-checkbox--selected {
background-color: #625DF5;
border-color: #625DF5;
}
/* Composer attachment classes */
.velt-composer-attachment-container { /* Container for attachment display */ }
.velt-composer-attachment--loading { /* Applied during attachment upload/processing */ }
.velt-composer-attachment--edit-mode { /* Applied when viewing attachments in edit mode */ }
/* Assign-to menu classes */
.s-comment-dialog-assign-to-menu { /* Assign-to menu in dialog context */ }
.velt-thread-card--assign-to-menu { /* Assign-to menu in thread card context */ }
```
```css theme={null}
/* Example: Style selected checkboxes in assign dropdown */
/* Inspect the DOM to find the exact class name */
.velt-assign-dropdown-checkbox--selected {
background-color: #625DF5;
border-color: #625DF5;
}
/* Composer attachment classes */
.velt-composer-attachment-container { /* Container for attachment display */ }
.velt-composer-attachment--loading { /* Applied during attachment upload/processing */ }
.velt-composer-attachment--edit-mode { /* Applied when viewing attachments in edit mode */ }
/* Assign-to menu classes */
.s-comment-dialog-assign-to-menu { /* Assign-to menu in dialog context */ }
.velt-thread-card--assign-to-menu { /* Assign-to menu in thread card context */ }
```
#### Disable Shadow DOM
* By default, Velt components use Shadow DOM to isolate their styles from your application's CSS. This ensures that styles don't conflict with each other.
* If you want your application's CSS to affect the styling of Velt components, you can disable the Shadow DOM.
* Most components accept a `shadowDom` prop (`shadow-dom="false"` for non-React).
* Some components that are not directly injected by you like dialogs and pins use specific props (e.g. `dialogShadowDom`, `pinShadowDom`).
* Check each component's UI customization documentation for its shadow DOM props.
```jsx theme={null}
```html theme={null}
#### Disable Global Styles
When implementing custom themes, you can disable Velt's default global CSS styles by setting `globalStyles: false` in the SDK configuration. This prevents conflicts with your custom styling.
```jsx theme={null}
// Using VeltProvider
{/* Your app content */}
// Using API method
const client = useVeltClient();
client.initConfig('API_KEY', {
globalStyles: false
});
```
```html theme={null}
```
### Conditional Classes
Apply classes conditionally based available [template variables](/ui-customization/template-variables).
**Syntax:**
```jsx theme={null}
```html theme={null}
`: 'class-name': {velt-template-variable} 'value'`
* **class-name:** The class name to apply. This should be within single quotes `'`.
* **template-variable:** The template variable to evaluate. This should be within curly braces `{}`.
* **operator:** The operator to use for the comparison. This should be one of the following: `===`, `!==`, `>`, `>=`, `<`, `<=`. You can also use `&&` and `||` to combine multiple conditions.
* **value:** The value to compare the template variable to. This should be within single quotes `'`.
**Example:**
```jsx theme={null}
```
```html theme={null}
```
# Template Variables
Source: https://docs.velt.dev/ui-customization/template-variables
Template variables allow you to:
* Display dynamic data within Velt components.
* Use the dynamic data to apply conditional templates or CSS classes.
There are two main ways to use them:
1. Using built-in Velt data
2. Injecting your own application data
## 1. Using Built-in Velt Data
Velt provides access to various data objects that you can display in your components using the `VeltData` component.
### Basic Usage
```jsx theme={null}
// Display user name
```jsx theme={null}
// Display user name
### Available Data Objects
#### Global Variables
These are available across all Velt components:
| Variable | Description | Data Fields |
| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------ |
| `user` | Current logged-in user | You can find all the fields [here](/api-reference/sdk/models/data-models#user) |
| `unreadCommentAnnotationCount` | Number of unread annotations | - |
| `unreadCommentCount` | Total unread comments | - |
#### Context-Specific Variables
These are only available within relevant components they are used in:
| Variable | Available In | Description |
| --------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------- |
| `userContact` | Autocomplete components | You can find all the fields [here](/api-reference/sdk/models/data-models#user) |
| `commentAnnotation` | Comment components | You can find all the fields [here](/api-reference/sdk/models/data-models#commentannotation) |
| `comment` | Comment thread components | You can find all the fields [here](/api-reference/sdk/models/data-models#comment) |
| `notification` | Notification components | You can find all the fields [here](/api-reference/sdk/models/data-models#notification) |
| `filteredCommentAnnotationsCount` | Comments Sidebar | Number of visible comments in sidebar when system filters are applied |
### Example: Building a Custom User Card
```jsx theme={null}
```
```jsx theme={null}
```
## 2. Injecting Your Own Data
* You can inject custom data from your application to use within Velt components.
* This data is available in all Velt Wireframes, Velt If and Velt Data components.
### Setting Custom Data
```jsx theme={null}
// Set custom data
client.setUiState({
projectName: 'Dashboard 2.0',
teamSize: 5,
customFlag: true
});
// Read custom data
client.getUiState().subscribe((data) => {
console.log('Custom Data:', data);
});
```
```js theme={null}
// Set custom data
Velt.setUiState({
projectName: 'Dashboard 2.0',
teamSize: 5,
customFlag: true
});
// Read custom data
Velt.getUiState().subscribe((data) => {
console.log('Custom Data:', data);
});
```
### Using Custom Data in Components
```jsx theme={null}
Team Size:
```
```jsx theme={null}
```
# Advanced Webhooks
Source: https://docs.velt.dev/webhooks/advanced
This is only available to Enterprise customers.
Webhooks are how services notify each other of events.
At their core they are just a POST request to a pre-determined endpoint.
The endpoint can be whatever you want, and you can just add them from the UI.
You normally use one endpoint per service, and that endpoint listens to all of the event types.
For example, if you receive webhooks from Acme Inc., you can structure your URL like: [https://www.example.com/acme/webhooks/](https://www.example.com/acme/webhooks/).
The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s).
It's also important to disable CSRF protection for this endpoint if the framework you use enables them by default.
Another important aspect of handling webhooks is to verify the signature and timestamp when processing them.
You can learn more about it in the [signature verification section](#verifying-webhook-signatures).
## Endpoints
### Adding an endpoint
In order to start listening to messages, you will need to configure your endpoints.
Adding an endpoint is as simple as providing a URL that you control and selecting the event types that you want to listen to.
### Playground
If your endpoint isn't quite ready to start receiving events, you can press the "with Svix Play" button to have a unique URL generated for you.
You'll be able to view and inspect webhooks sent to your Svix Play URL, making it effortless to get started.
### Testing endpoints
Once you've added an endpoint, you'll want to make sure its working.
The "Testing" tab lets you send test events to your endpoint.
After sending an example event, you can click into the message to view the message payload, all of the message attempts, and whether it succeeded or failed.
## Events
If you don't specify any event types, by default, your endpoint will receive all events, regardless of type.
This can be helpful for getting started and for testing, but we recommend changing this to a subset later on to avoid receiving extraneous messages.
### Payload Schema
1. **Default payload**: [WebhookV2Payload](/api-reference/sdk/models/data-models#webhookv2payload) — common fields shared across all events
* [CommentPayload](/api-reference/sdk/models/data-models#commentpayload) — comment-specific fields
* [HuddlePayload](/api-reference/sdk/models/data-models#huddlepayload) — huddle-specific fields
* [CRDTPayload](/api-reference/sdk/models/data-models#crdtpayload) — CRDT-specific fields
2. **Encoded payload**: If you have enabled payload encoding, you will receive the payload in this format: [WebhookV2PayloadEncoded](/api-reference/sdk/models/data-models#webhookv2payloadencoded)
3. **Encrypted payload**: If you have enabled payload encryption, you will receive the payload in this format: [WebhookV2PayloadEncrypted](/api-reference/sdk/models/data-models#webhookv2payloadencrypted)
If you have configured [notification settings](/async-collaboration/notifications/customize-behavior), per-user notification preferences (`usersOrganizationNotificationsConfig` or `usersDocumentNotificationsConfig`) will be included in the webhook payload.
### Comments
#### Comment Annotations (Threads)
| Event Type | Description |
| --------------------------------------- | -------------------------------------------------------------------------------------------- |
| `comment_annotation.add` | When a new comment thread is created with the first comment. |
| `comment_annotation.assign` | When a comment thread is assigned to a specific user. |
| `comment_annotation.status_change` | When a comment thread's status is updated (e.g., open, in progress, resolved). |
| `comment_annotation.priority_change` | When a comment thread's priority level is modified (e.g., P0, P1, P2, or custom priorities). |
| `comment_annotation.custom_list_change` | When a custom list item is added to or modified on a comment thread. |
| `comment_annotation.subscribe` | When a user subscribes to receive notifications for a comment thread. |
| `comment_annotation.unsubscribe` | When a user unsubscribes from notifications for a comment thread. |
| `comment_annotation.accept` | When a moderator accepts a comment thread. Only available when Moderator Mode is enabled. |
| `comment_annotation.reject` | When a moderator rejects a comment thread. Only available when Moderator Mode is enabled. |
| `comment_annotation.approve` | When a moderator approves a comment thread. Only available when Moderator Mode is enabled. |
#### Comments (Messages)
| Event Type | Description |
| ------------------------- | ----------------------------------------------------------------- |
| `comment.add` | When a new comment is added to a comment thread. |
| `comment.update` | When an existing comment's content or metadata is modified. |
| `comment.delete` | When an existing comment is permanently removed from a thread. |
| `comment.reaction_add` | When a user adds an emoji reaction to a specific comment. |
| `comment.reaction_delete` | When a user removes their emoji reaction from a specific comment. |
#### Sample Payload
You will find the sample schema and payload in the advanced webhooks section of the console.
```json expandable lines theme={null}
{
"actionType": "add",
"data": {
"actionUser": {
"clientUserName": "actorUser",
"email": "actor@example.com",
"initial": "A",
"name": "Actor User",
"organizationId": "org123",
"userId": "user123"
},
"commentAnnotation": {
"annotationId": "anno-xyz",
"annotationIndex": 1,
"comments": [
{
"commentHtml": "Hello world
",
"commentId": 101,
"commentText": "Hello world",
"createdAt": 1610000000000,
"from": {
"clientUserName": "commenter",
"email": "commenter@example.com",
"initial": "C",
"name": "Commenter One",
"organizationId": "org123",
"userId": "user456"
},
"isCommentTextAvailable": true,
"isDraft": false,
"lastUpdated": "2025-05-28T12:00:00.000Z",
"status": "added",
"type": "text"
}
],
"createdAt": 1610000000000,
"from": {
"clientUserName": "commenter",
"email": "commenter@example.com",
"initial": "C",
"name": "Commenter One",
"organizationId": "org123",
"userId": "user456"
},
"lastUpdated": 1610000001000,
"location": {
"browser": "chrome",
"browserVersion": "90.0",
"deviceName": "Laptop",
"id": "loc-001",
"locationName": "chrome-1920x1080",
"resolution": "1920x1080"
},
"locationId": 1001,
"metadata": {
"apiKey": "dummyApiKey"
},
"pageInfo": {
"baseUrl": "https://example.com",
"commentUrl": "https://example.com/page#comment-anno",
"deviceInfo": {
"browserName": "Chrome",
"browserVersion": "90.0",
"deviceType": "Desktop",
"orientation": "landscape",
"osName": "Windows",
"osVersion": "10",
"screenHeight": 1080,
"screenWidth": 1920,
"userAgent": "Mozilla/5.0"
},
"path": "/page",
"queryParams": "?foo=bar",
"screenWidth": 1920,
"title": "Example Page",
"url": "https://example.com/page?foo=bar"
},
"resolvedByUserId": "user123",
"status": {
"color": "#000000",
"id": "RESOLVED",
"lightColor": "#CCCCCC",
"name": "Resolved",
"svg": "Target comment
",
"commentId": 202,
"commentText": "Target comment",
"createdAt": 1610000020000,
"from": {
"clientUserName": "actorUser",
"email": "actor@example.com",
"initial": "A",
"name": "Actor User",
"organizationId": "org123",
"userId": "user123"
},
"isCommentTextAvailable": true,
"isDraft": false,
"lastUpdated": "2025-05-29T12:00:00.000Z",
"status": "added",
"type": "text"
}
},
"event": "comment.add",
"platform": "sdk",
"source": "comment",
"webhookId": "dummyWebhookId",
"usersOrganizationNotificationsConfig": {
"user0": {
"inbox": "ALL",
"email": "MINE"
},
"user1": {
"inbox": "NONE",
"email": "ALL"
}
}
}
```
### Huddle
| Event Type | Description |
| --------------- | ----------------------------- |
| `huddle.create` | When a user creates a Huddle. |
| `huddle.join` | When a user joins a Huddle. |
### CRDT
Learn how to configure CRDT webhooks in the [CRDT Core Setup documentation](/realtime-collaboration/crdt/setup/core#webhooks).
| Event Type | Description |
| ------------------ | ------------------------------------------------------------------------------------ |
| `crdt.update_data` | When CRDT data is updated. Webhooks are enabled by default with a 5-second debounce. |
#### Sample Payload
You will find the sample schema and payload in the advanced webhooks section of the console.
```json expandable lines theme={null}
{
"actionType": "updateData",
"data": {
"actionUser": {
"clientUserName": "Michael Scott",
"color": "#ffcb00",
"email": "michael.scott@dundermifflin.com",
"initial": "M",
"isAdmin": false,
"name": "Michael Scott",
"organizationId": "crdt-array-demo-org1",
"type": "signedIn",
"userId": "michael"
},
"crdtData": {
"data": [
{
"completed": false,
"id": "seed-1",
"text": "Welcome Todo - Edit me!"
},
{
"completed": false,
"id": "bmg6tpj7we",
"text": "Todo1"
},
{
"completed": false,
"id": "dt0vhs2t3os",
"text": "Todo2"
}
],
"id": "crdt-array-demo-todos-1",
"lastUpdate": "2026-03-17T06:23:24.514Z",
"lastUpdatedBy": "michael",
"sessionId": "tvLupvP0L2jiztlba4P0"
},
"metadata": {
"apiKey": "VKabul7W2DJhLu1BiMaj",
"document": {
"documentId": "crdt-array-demo-doc-1",
"documentName": "CRDT Array Demo"
},
"organization": {
"organizationId": "crdt-array-demo-org1"
},
"pageInfo": {
"baseUrl": "http://localhost:5225",
"path": "/",
"queryParams": "",
"title": "CRDT Array Demo",
"url": "http://localhost:5225/"
}
}
},
"event": "crdt.update_data",
"platform": "sdk",
"source": "crdt",
"webhookId": "-OnuSfG_ffGIwNkodE2a"
}
```
## Rate Limits
The rate limit is defined as a limit for the number of messages per second to send to the endpoint. After the limit is reached, requests will get throttled so to keep a consistent rate under the limit.
Due to the nature of distributed systems the actual rate of messages can sometimes be slightly above the enforce rate limit. So for example, if you set a rate limit of 1,000 per seconds, an endpoint may potentially get messages at a rate of 1,050 or even higher.
You can set the rate limit on each of the endpoints you create.
## Retries
We attempt to deliver each webhook message based on a retry schedule with exponential backoff.
Each message is attempted based on the following schedule, where each period is started following the failure of the preceding attempt:
* Immediately
* 5 seconds
* 5 minutes
* 30 minutes
* 2 hours
* 5 hours
* 10 hours
* 10 hours (in addition to the previous)
For example, an attempt that fails three times before eventually succeeding will be delivered roughly 35 minutes and 5 seconds following the first attempt.
If an endpoint is removed or disabled delivery attempts to the endpoint will be disabled as well.
### Indicating successful delivery
The way to indicate that a webhook has been processed is by returning a 2xx (status code 200-299) response to the webhook message within a reasonable time-frame (15s). Any other status code, including 3xx redirects are treated as failures.
### Failed delivery handling
After the conclusion of the above attempts the message will be marked as Failed for this endpoint, and you will get a webhook of type `message.attempt.exhausted` notifying you of this error.
### Manual retries
Use the console to manually retry each message at any time, or automatically retry ("Recover") all failed messages starting from a given date.
## Transformations
Transformations are a powerful feature that allows the modification of the received webhook data in-flight. When you enable Transformations, you can write JavaScript code on the endpoints that can change a webhook's HTTP method, target URL, and body payload.
You can enable Transformations in the Advanced tab of the endpoint configuration.
### How to write a Transformation
We expect a Transformation to declare a function named `handler`. We will pass a `WebhookObject` to this function as its only argument, and expect the function to always return a `WebhookObject`.
`WebhookObject` is a JSON object containing 4 properties:
* `method`, a string representing the HTTP method the webhook will be sent with. It is always `POST` by default, and its only valid values are `POST` or `PUT`
* `url`, a string representing the endpoint's URL. It can be changed to any valid URL.
* `payload`, which contains the webhook's payload as a JSON object. It can be changed as needed.
* `cancel`, a Boolean which controls whether or not to cancel the dispatch of a webhook. This value defaults to `false`. Note that canceled messages appear as successful dispatches.
The Transformation will only work if the `handler` function returns the modified `WebhookObject`.
### Example
Suppose that sometimes, you want to redirect webhooks to a custom URL instead of the endpoint's defined URL. You only want to do this redirect if a custom URL is present in the webhook payload. You can write a transformation like this:
```javascript theme={null}
function handler(webhook) {
if (webhook.payload.customUrl) {
webhook.url = webhook.payload.customUrl;
}
return webhook;
}
```
Great, the webhook is redirected to the custom URL if the customUrl property exists on the payload. Otherwise, it is sent to the endpoint's defined URL.
## Security
### Verifying webhook signatures
Webhook signatures let you verify that webhook messages are actually sent by us and not a malicious actor.
Each webhook call includes three headers with additional information that are used for verification:
* `webhook-id`: the unique message identifier for the webhook message. This identifier is unique across all messages, but will be the same when the same webhook is being resent (e.g. due to a previous failure).
* `webhook-timestamp`: timestamp in [seconds since epoch](https://en.wikipedia.org/wiki/Unix_time).
* `webhook-signature`: the [Base64](https://en.wikipedia.org/wiki/Base64) encoded list of signatures (space delimited).
#### Constructing the signed content
The content to sign is composed by concatenating the id, timestamp and payload, separated by the full-stop character (`.`). In code, it will look something like:
```javascript theme={null}
const signedContent = `${webhook_id}.${webhook_timestamp}.${body}`;
```
Where `body` is the raw body of the request. The signature is sensitive to any changes, so even a small change in the body will cause the signature to be completely different. This means that you should *not* change the body in any way before verifying.
#### Determining the expected signature
We use an [HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2) to sign its webhooks.
So to calculate the expected signature, you should HMAC the `signed_content` from above using the base64 portion of your signing secret (this is the part after the `whsec_` prefix) as the key.
For example, given the secret `whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw` you will want to use `MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw`.
For example, this is how you can calculate the signature in Node.js:
```javascript theme={null}
const crypto = require('crypto');
const signedContent = `${webhook_id}.${webhook_timestamp}.${body}`;
const secret = "whsec_5WbX5kEWLlfzsGNjH64I8lOOqUB6e8FH";
// Need to base64 decode the secret
const secretBytes = Buffer.from(secret.split('_')[1], "base64");
const signature = crypto
.createHmac('sha256', secretBytes)
.update(signedContent)
.digest('base64');
console.log(signature);
```
This generated signature should match one of the ones sent in the `webhook-signature` header.
The `webhook-signature` header is composed of a list of space delimited signatures and their corresponding version identifiers. The signature list is most commonly of length one. Though there could be any number of signatures. For example:
```
v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE= v1,bm9ldHUjKzFob2VudXRob2VodWUzMjRvdWVvdW9ldQo= v2,MzJsNDk4MzI0K2VvdSMjMTEjQEBAQDEyMzMzMzEyMwo=
```
Make sure to remove the version prefix and delimiter (e.g. `v1,`) before verifying the signature.
Please note that to compare the signatures it's recommended to use a constant-time string comparison method in order to prevent timing attacks.
#### Verify timestamp
As mentioned above, we also send the timestamp of the attempt in the `webhook-timestamp` header. You should compare this timestamp against your system timestamp and make sure it's within your tolerance in order to prevent timestamp attacks.
#### Example signatures
Here is an example you can use to verify you implemented everything correctly. Please note that this may fail verification due to the timestamp being old.
```javascript theme={null}
secret = 'whsec_plJ3nmyCDGBKInavdOK15jsl';
payload = '{"event_type":"ping","data":{"success":true}}';
msg_id = 'msg_loFOjxBNrRLzqYUf';
timestamp = '1731705121';
// Would generate the following signature:
signature = 'v1,rAvfW3dJ/X/qxhsaXPOyyCGmRKsaKWcsNccKXlIktD0=';
```
Additionally, you can use the [webhook simulation tool](https://www.standardwebhooks.com/simulate) to generate as many examples as you need.
### Additional Authentication
We sign all webhooks in order to ensure the security and authenticity of all of the webhooks being sent.
This security mechanism is already sufficient (and better) than other methods such as [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), and using an authentication token. However, some systems and IT departments have varying requirements for any HTTP request hitting their services (including webhooks), so we've built in support for these additional authentication modes.
#### HTTP Basic Authentication
HTTP Basic Authentication (Basic Auth), is a common way of sending a server a pair of username and password, or more often a username and auth token. While there are different ways of passing these credentials, the simplest and most common way is by including it as part of the URL.
You can add it to the URL by prefixing the URL with the username and password (or token) and the @ symbol as such:
```
https://USERNAME:PASSWORD@example.com/webhook/
```
#### Header based authentication
Some services require specific headers to be passed in order to be processed by their load balancers or application servers. These services often require a specific authentication token passed in the `Authorization` header, but sometimes there could also be different headers and values.
You can set custom headers using the Advanced tab in the endpoint configuration.
#### Firewalls (IP blocking)
Many organizations have strict firewall rules for which IPs are allowed to send traffic to their systems. While this is not a very strong security mechanism on its own, it's often useful when used in conjunction with other methods (such as webhook signatures).
We only send webhooks requests from a specific set of IPs as detailed below:
#### Static Source IP Addresses
In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from these static IP addresses.
```plaintext theme={null}
44.228.126.217
50.112.21.217
52.24.126.164
54.148.139.208
2600:1f24:64:8000::/56
```
### Payload Encoding
* Enable Base64 encoding for webhook payloads (disabled by default).
* Addresses issues with payloads containing HTML tags that may fail due to strict endpoint policies.
* If enabled, ensure your server can decode Base64 encoded payloads.
* Example of decoding a Base64 encoded payload:
```js theme={null}
const encodedData = "eyJ0ZXN0IjoxLCJ0ZXN0MSI6IjxkaXY+PC9kaXY+In0="
const decodedData = Buffer.from(encodedData, 'base64').toString('utf-8');
console.log(JSON.parse(decodedData));
```
### Payload Encryption
* Enable payload encryption for enhanced security (disabled by default).
* Configure this option in the [Velt Console](https://console.velt.dev/dashboard/config/webhook).
* Encryption details:
* Payload encryption: AES-256-CBC
* Key encryption: RSA with PKCS1 OAEP padding and SHA-256 hash
* Public key format:
* Provide only the base64-encoded key string, without PEM headers/footers
* Recommended key size: 2048 bits
* Example of setting up decryption for Node.js:
```js theme={null}
{
"encryptedData": "1rtsa9UVvXzkP+u0ax2TOlz6xKcwKXhmtHyQF1I4II8X4n9uYb944Q/6AfUNFc2zQj9+AWJIV1Gtoo0j+j5VI8qS4kCVnP4In6v0I3wVECldgZsNAwwD4wKp85OJZUJL4scQmJJK+XXmMNGOW094BcIIa6zKRqYKja5RBm5zEj3k1qsP3WZkUXpggJ4FNuHkWX2nkoDLP5Rby6CY186TEeBIxY+aKS6FyWmOiDDC6ZfuY++BFNJbksNvsbBogDqHB2qa30nK9oEcOKSsXdU4AYof/mPOG01fK2diK3vyk4qcL83mJ0cXm7+SbM+FBFeJpdR+A7iIez1XrdnGlAqppnSfDoNBv2WZ/lRyZJWOyW7QHySMNTn746+JDr8oltIBDVUx5c2m8A/YeQ6E3wWEjjRZcfz3GNSzpEx+jqeNxS0StN7BUXUyHt3786EaXiUtjb2OtrP56mlidXytdHhPZPOy7stRwHnwgXfm5aLsS2yJSs3gSSUubL+ka4fhaJsqxtgXQATSh0RtNXSmAbx930DKn2DipbP23fJRduju/GP1nHnKuy8bOuyB5Du//RrysvKVC4+lMd4mVIc7cSXe25qcPjJFZGpJtJdkNwOZoWCmxMSdR32HBgo7KWJeOWqnWyuLdjQOaxol+JtTu8lopeQk7qfncEXMLcT7YRVQ4t1LZ5T9o4pZEtaOg1LwyX58VQS1OHvgBFWlEPxLfdS1r4c1YzMXLNA4sfYEp06Z11IlEFVCtWobK5//tLc+sIpwfMzdJ3VtVl9Z2XB9kASlnHf88eOdtzvn5A0CRhVBY/v855CttAy/WlPINtXxXSxm9oVMjrBFueWAZ3LQiXDl25to62L5i0NR93zEBKj1BG8egy3F27o8s5kcvrwpc3NGrmDe7x3S11noDAFsxZRWpHnRIapHcsrLWOjWVEumvUxlApKGKL3Ax80XBoN+aTNG4SXGq3dRHSneIs/MNSb0BGWoOD5U5ow58R1tvpzJHtLLnmesL1Vhr23Cug8KHU2q7+e8AnGGPTJIRKfVXjocMDclhDAk5/nuvtUTYG/hRZEQ1yCx3T7H08I6GvyOv4ErtKr+r883hXSYzf1K9eqk7de5mnmxwSEiAh0zagvZ+lMYhWpayeo+xHvtoyzfTsLNyXKc6AYZxfoIVK6UuBfkDnXiAh+NuJDa3wKwig13gQX8GmdJXeSSatI6uuXI1IU5xKIXysaHeAOaHfni+cfDgvUZTtVbWc1qDcNOVEUSl9KsjOUUgdzvST1tJ1ezMNZFbhlrPB3t5y0XvM9QQh1GyyeABxHl8nH/Icrp2Shf5vBntNbRZ3PlzK7nVtgTxXaKhZnGobwY7uruPpahNfkEi83JvOOnHeHBMXrVMAr8GHDRi8099wzvJRHYcb2p6eWocQsDV1X6tcTLuxj3EHGwykWREkkTDQ5C/F40n97PP0U2cxSGJIMePUwgAYw5OFo0dJMsU1HvXjm+2JoO8DkdwPl3Bc9F22trvsA3QecUCKQDGMTuFrFxtlubtJYtVl7w3pBST0SCKx3G2QiycRz0FMWv2FJpazQl6jE4xEqeKf7fiUn/QIo4Levk745LPhfr2tzlXbkdZ2q9TtmSAs5hjpK7ndswbIbvV8Ju5V8mDJXSR0y0NKG2C/8/vTB0xfqYtW/Bv3cXj6do9UQzP6fOFC4SGvYh/l8yohJmCTFq0tETqvZr9Atw9ZOz2cIBFx76wlS/eR9iB/JZ3DGM+2THC6Mjv70ipWX32UW7620Bb5KONm3Vw0eeIHckUn6QaHGfFL/URT6mr7YCJhG5lZynWYZcLv/ffWuFcSmO9p0xCrwqqPEjdaaGs52mqmA4Ikt9MulKAEp6p65V1vxt7Tdy6m9UVjzbEy1zFuU9iOHBAAaj6A8Mj1EEUe6sNx3fLHnC2c0+2Zf3eUxMZPm5dQZPOUXLI28yoCliBIhTYTSh7ATULDDvcnNMs/ziuG7WT/U1wuIHkT5kEE73tnG1EZY4RDODbQobmpBegcuUEh64HEGS7+aK/KPYWxFxWW5oVd0Dc7kvpariXqEhlNdDY65b2T8uBw8bI/HrfvT8d0EnsPz26B1xKZYqyusWnlR+10KdYzPNoupx8vWk74PW8zI5qlcV497SPtvn12a3wvZ8adJzMuP4hsBoKHG/M2nf0lOMbo1gcbHbT0FqcHE3mixY3lU+UnNC5jpmNCs1tK8yqeQdVtHE3YM4Y5SsnBTJddUWVpUxZ6rlU+H2NW/uGcDLBs3HmERTn1l6E1mmqKB2kPA/+Y/YbILXNojbkgRE/3lki5kX4+pjHDxF/mWEEeXpjIl4yKG97mVS2J0dGoJ5CqLv6/CdHhtwu35UydBVDVGHywufVLwPgEiDA9RklM/bQw3ojdlTrn6+irDcz8/Tj7KmK2votLaN6yIEM8Ex2htyBlyX/47eEsh63nSNwSx+uPcTxjH9N5cJpWzJ2KcBMIqZsWOTgISBUndgRdoVTFySY2XwbHlDjh8RCLLBsYRhvOK+nvNqEBnrfzz81B/sqDO1whQDTKT3ZcFnZouaVImRGHcOt0sRioq/JGHAHzRjyc/V9Gb/zTlI8QQob5y5k7dfReAy1rGdkeIa3LXSwWGz8hDjEnGsGGIC4evdiefgoJHkhzEywi/QUEOOnqms/0BzexbLP+89qMgGMlEbA9iLAW/BZgsAkxm+NHqGNtz9HDJStpqewElgjMQ+wV3TUGbrmY0O/FyQn/CXyhXjdRC0/5S1tZnzBMyolHF2a5L5EAzGck2MuV7TgLs6LcvGm7kIeq0vmBCkiUB4IBHMhraU7Ba+cC+CW7tDK0Tkanri5KSMXSXamJpU869Jcsk1JLm69ATMl3eIb5rPx5+GbPUrRogEUP3HQeLMQP8jjq6fVwzGPQByF70t0fE+Z23NuCLzhVss0YkMmzcKK8GjKCJ0vnCA0qanxovpDgCOHjgxvy44N+QNWfUynIKVHS9m7FDE3RgKf7rOfSM9vJ7F/KWo7kywi36ajuFbWcON/MTvlpPUhGm5dboiz3vyfpTWkQbd9XX7SPVBWCkvGg+A87R7RSN8bsWbmYm5m2wt3jrkBVSDn5FV3rek6X0GSpTDTWJ9ktmjKtshplXn7fx7XAKtS4hpEMGhZwi/LWvfTsGqOJlqi2FwYPLI7SVunch2VSfssejrfwxJHPqF50wTv6ax28lp7wToqsVunZprdhyY++gds/LAz083dZLM3EYcbHuGVXiNRFxptpiQNjEnyjZX0fc8UF1W2icDt7Gd5Pp2ckaPERLE+tJ+ackMxomH2/HjFB3XRXlDCoKuljtJ2cbw/gVPmHtV7Qw2w6tWaCzYP3g1D47BlrIqBV4RWjcPRjthfcWPnwUSSHwlJ4dLMQ+cJ402ol+HUukAKpkh5lcjME0uaD8KKReD/Ee9r4kubIR7z9JViXjnJJl3Jxr6KtK3abrg8cG8qVFRr5NDhxbfs9NY/zGDvbgt0GMWXRTi4oMrSkDKthZSWjVezDzPk11AMQ1E+SJSoSXgwUl1rbWPg0O29prkQdfdKQmZcaO5oj7+f3kSPsIOE9+Qn43VOxOWWybkCzSvEbzLgmuov5C8EWYeJgh13qDcNSwNdt4PgAqIq+tikKNUo9qeM9/q20an+i20fatPAcvrRes+xxnIBXmlPDCj02THjX4EulV2KE+nNxFnCrNvFKYp2bEAegJ2neqfeefDDDhn+t7OK9/73v3O3qnEwSyBlt+pEyHfLjv3Cm7Ik7JA5NUQ/nsS3JdC8OYy2i1DWSvi1qsP3ixAVCR7qBVdoOF2Lv5y2GWrJ0EvVcGqaPBnUezMGMdozNjreschNJvRlp3D72dGGQgs00GHyHbIQ5wicC5p+PiZ2z1EUBN7DiDy9ShQPKEDJtISiSrSaPkDPKpW7SxmSfDaLOIxEy4daAupV0gj7yTtrkpEvJjRECpa0kuKFP3/eFVVp/nIjWDzFASfDvYiry90dDrvLxO3tosuvMVfhXcOy/zbyeCkObaFgc3OkO4z2r4X4Vwt18BoRAammiEfgCbnhywl/CmLrSwV1qSjUgALh/XUPkqXCkqerNjYTlZw5NdRUKmheUXHYGwo4Z+xPfDtiHk1N5vRgNL9/qXsgt813spju9kDMGQGiXlrOgIyhArHR5p2B4S3FjRQ/lEoP5+5wN+9tBKYrR79sZXNS8CwR0BPrOoY9GQCYFdxrBtyH6KOWg29FVXNodt2Yvot7ktofcen1zwQJOAr0KTyqF9/TIltO+hS7swSzZMjV368SEPYjrtXfnXNWYltOS2zJAWYeqr0XLrL+iHbbOQLC7Rk0mnizmUt9wdefz4MtfXZNcdKR4LPsOqYyIz5ux90XiCbvcNZJaRa2/dzecv/koLQPbKzFPGxKiUOsHAa5SEGgbWFZE4Y9CBFS4nCuEOgUnVz9XtFAEP4dazc2cxjYLVzaG5msOiOY1O5ZygYMeVZfdKaITg7gMPbkL3Lpzo7QBMXcHmT5YAUeNaSbHxvgg45Jn8r7W72EQP9tF7SPKiPvxo91xkB7MA3JOcZXC1qymTUWqjO038wSShK48kE+qgu7V9rjP5fOCDW3+3338eifxqS7Zq6FSO053c5W2c8wFR4iw==",
"encryptedKey": "OzSHFXzrXFC5wDvM5NPRkriY/NaC/USvFUPE+f4NZ30tiD2qb8sJM2XT2K7uNIZ05uDLfsJ6/BbEoYC1SOPXcFJMYqRiYFiI9RWrNgR4EtPWZ84RgrmxGcZZjzSqHzjuls8g++cuqJGRV+ePbTRH+z2OuZZu0vMKZiemaZpHL46Ewi9HUnbRDXvOlKFFHmQm5tayZ7m7Mv5iu4T5R3DPEAHlZnGqtP98ToLxUJUS2Eku/iLHXRmhmZXn55Qt5GYiyss8P5/miPqJCu1QG0CStn5Nsl4KvU+I4QYAOcMFWWUAGofOwPWtt8vPh8Bx+7t7BbayKpA4ZUEWWAjC+zASxg==",
"iv": "SHM0UHU5WXoyTG03TnExWA=="
}
```
```javascript theme={null}
const crypto = require('crypto');
/**
* Decrypts the symmetric key using the provided private key.
* @param {string} encryptedKey - Base64 encoded encrypted symmetric key
* @param {string} privateKey - RSA private key
* @returns {Buffer} Decrypted symmetric key
*/
function decryptSymmetricKey(encryptedKey, privateKey) {
try {
const encryptedSymmetricKey = Buffer.from(encryptedKey, 'base64');
const decryptedSymmetricKey = crypto.privateDecrypt(
{
key: `-----BEGIN RSA PRIVATE KEY-----\n${privateKey}\n-----END RSA PRIVATE KEY-----`,
padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
oaepHash: 'sha256',
},
encryptedSymmetricKey
);
return decryptedSymmetricKey;
} catch (error) {
console.error('Error decrypting symmetric key:', error);
throw new Error('Failed to decrypt symmetric key');
}
}
/**
* Decrypts the webhook data using the provided symmetric key and IV.
* @param {string} encryptedWebhookData - Base64 encoded encrypted webhook data
* @param {Buffer} symmetricKey - Decrypted symmetric key
* @param {string} payloadIv - Base64 encoded initialization vector
* @returns {Object} Decrypted webhook data as a JSON object
*/
function decryptWebhookData(encryptedWebhookData, symmetricKey, payloadIv) {
try {
const iv = Buffer.from(payloadIv, 'base64');
const decipher = crypto.createDecipheriv('aes-256-cbc', symmetricKey, iv);
let decryptedData = decipher.update(encryptedWebhookData, 'base64', 'utf8');
decryptedData += decipher.final('utf8');
return JSON.parse(decryptedData);
} catch (error) {
console.error('Error decrypting webhook data:', error);
throw new Error('Failed to decrypt webhook data');
}
}
// Example usage:
// const decryptedKey = decryptSymmetricKey(encryptedKey, privateKey);
// const decryptedData = decryptWebhookData(encryptedWebhookData, decryptedKey, payloadIv);
```
## Debugging
### Troubleshooting tips
There are some common reasons why your webhook endpoint is failing:
**Not using the raw payload body**
This is the most common issue. When generating the signed content, we use the raw string body of the message payload.
If you convert JSON payloads into strings using methods like stringify, different implementations may produce different string representations of the JSON object, which can lead to discrepancies when verifying the signature. It's crucial to verify the payload exactly as it was sent, byte-for-byte or string-for-string, to ensure accurate verification.
**Missing the secret key**
From time to time we see people using the wrong secret key. Remember that keys are unique to endpoints.
**Sending the wrong response codes**
When we receive a response with a 2xx status code, we interpret that as a successful delivery even if you indicate a failure in the response payload. Make sure to use the right response status codes so we know when message are supposed to succeed vs fail.
**Responses timing out**
We will consider any message that fails to send a response within 15 seconds a failed message. If your endpoint is also processing complicated workflows, it may timeout and result in failed messages.
We suggest having your endpoint simply receive the message and add it to a queue to be processed asynchronously so you can respond promptly and avoiding getting timed out.
### Failure Recovery
#### Re-enable a disabled endpoint
If all attempts to a specific endpoint fail for a period of 5 days, the endpoint will be disabled. To re-enable a disabled endpoint, go to the webhook dashboard, find the endpoint from the list and select "Enable Endpoint".
#### Recovering/Resending failed messages
If your service has downtime or if your endpoint was misconfigured, you probably want to recover any messages that failed during the downtime.
If you want to replay a single event, you can find the message from the UI and click the options menu next to any of the attempts.
From there, click "resend" to have the same message send to your endpoint again.
If you need to recover from a service outage and want to replay all the events since a given time, you can do so from the Endpoint page. On an endpoint's details page, click "Options > Recover Failed Messages".
From there, you can choose a time window to recover from.
For a more granular recovery - for example, if you know the exact timestamp that you want to recover from - you can click the options menu on any message from the endpoint page.
From there, you can click "Replay..." and choose to "Replay all failed messages since this time."
### Logs
You can see all of the activity logs for your endpoint in the "Logs" tab.
# Basic Webhooks
Source: https://docs.velt.dev/webhooks/basic
Set up a webhook endpoint to receive real-time notifications for the following Velt events:
* [Comments](#comments-events)
* [Huddle](#huddle-events)
* [CRDT](#crdt-events)
## Setting up a Webhook
To enable Webhooks go to the Configurations -> Webhook Service in the Velt Console, or [click here](https://console.velt.dev/dashboard/config/webhook)
### **Webhook Auth Token**
* Optional security feature to authenticate webhook requests.
* Set a unique auth token in your Velt console's webhook settings.
* We add this token to the Authorization header of each request as `Basic YOUR_AUTH_TOKEN`.
* Helps you verify that requests are from Velt, not from unauthorized sources.
### **Endpoint URL**
* This is the endpoint that we will send the webhook data to. This is usually hosted on your server.
### **Payload Encoding**
* Enable Base64 encoding for webhook payloads (disabled by default).
* Addresses issues with payloads containing HTML tags that may fail due to strict endpoint policies.
* If enabled, ensure your server can decode Base64 encoded payloads.
* Example of decoding a Base64 encoded payload:
```js theme={null}
const encodedData = "eyJ0ZXN0IjoxLCJ0ZXN0MSI6IjxkaXY+PC9kaXY+In0="
const decodedData = Buffer.from(encodedData, 'base64').toString('utf-8');
console.log(JSON.parse(decodedData));
```
### **Payload Encryption**
* Enable payload encryption for enhanced security (disabled by default).
* Configure this option in the [Velt Console](https://console.velt.dev/dashboard/config/webhook).
* Encryption details:
* Payload encryption: AES-256-CBC
* Key encryption: RSA with PKCS1 OAEP padding and SHA-256 hash
* Public key format:
* Provide only the base64-encoded key string, without PEM headers/footers
* Recommended key size: 2048 bits
* Example of setting up decryption for Node.js:
```js theme={null}
{
"encryptedData": "1rtsa9UVvXzkP+u0ax2TOlz6xKcwKXhmtHyQF1I4II8X4n9uYb944Q/6AfUNFc2zQj9+AWJIV1Gtoo0j+j5VI8qS4kCVnP4In6v0I3wVECldgZsNAwwD4wKp85OJZUJL4scQmJJK+XXmMNGOW094BcIIa6zKRqYKja5RBm5zEj3k1qsP3WZkUXpggJ4FNuHkWX2nkoDLP5Rby6CY186TEeBIxY+aKS6FyWmOiDDC6ZfuY++BFNJbksNvsbBogDqHB2qa30nK9oEcOKSsXdU4AYof/mPOG01fK2diK3vyk4qcL83mJ0cXm7+SbM+FBFeJpdR+A7iIez1XrdnGlAqppnSfDoNBv2WZ/lRyZJWOyW7QHySMNTn746+JDr8oltIBDVUx5c2m8A/YeQ6E3wWEjjRZcfz3GNSzpEx+jqeNxS0StN7BUXUyHt3786EaXiUtjb2OtrP56mlidXytdHhPZPOy7stRwHnwgXfm5aLsS2yJSs3gSSUubL+ka4fhaJsqxtgXQATSh0RtNXSmAbx930DKn2DipbP23fJRduju/GP1nHnKuy8bOuyB5Du//RrysvKVC4+lMd4mVIc7cSXe25qcPjJFZGpJtJdkNwOZoWCmxMSdR32HBgo7KWJeOWqnWyuLdjQOaxol+JtTu8lopeQk7qfncEXMLcT7YRVQ4t1LZ5T9o4pZEtaOg1LwyX58VQS1OHvgBFWlEPxLfdS1r4c1YzMXLNA4sfYEp06Z11IlEFVCtWobK5//tLc+sIpwfMzdJ3VtVl9Z2XB9kASlnHf88eOdtzvn5A0CRhVBY/v855CttAy/WlPINtXxXSxm9oVMjrBFueWAZ3LQiXDl25to62L5i0NR93zEBKj1BG8egy3F27o8s5kcvrwpc3NGrmDe7x3S11noDAFsxZRWpHnRIapHcsrLWOjWVEumvUxlApKGKL3Ax80XBoN+aTNG4SXGq3dRHSneIs/MNSb0BGWoOD5U5ow58R1tvpzJHtLLnmesL1Vhr23Cug8KHU2q7+e8AnGGPTJIRKfVXjocMDclhDAk5/nuvtUTYG/hRZEQ1yCx3T7H08I6GvyOv4ErtKr+r883hXSYzf1K9eqk7de5mnmxwSEiAh0zagvZ+lMYhWpayeo+xHvtoyzfTsLNyXKc6AYZxfoIVK6UuBfkDnXiAh+NuJDa3wKwig13gQX8GmdJXeSSatI6uuXI1IU5xKIXysaHeAOaHfni+cfDgvUZTtVbWc1qDcNOVEUSl9KsjOUUgdzvST1tJ1ezMNZFbhlrPB3t5y0XvM9QQh1GyyeABxHl8nH/Icrp2Shf5vBntNbRZ3PlzK7nVtgTxXaKhZnGobwY7uruPpahNfkEi83JvOOnHeHBMXrVMAr8GHDRi8099wzvJRHYcb2p6eWocQsDV1X6tcTLuxj3EHGwykWREkkTDQ5C/F40n97PP0U2cxSGJIMePUwgAYw5OFo0dJMsU1HvXjm+2JoO8DkdwPl3Bc9F22trvsA3QecUCKQDGMTuFrFxtlubtJYtVl7w3pBST0SCKx3G2QiycRz0FMWv2FJpazQl6jE4xEqeKf7fiUn/QIo4Levk745LPhfr2tzlXbkdZ2q9TtmSAs5hjpK7ndswbIbvV8Ju5V8mDJXSR0y0NKG2C/8/vTB0xfqYtW/Bv3cXj6do9UQzP6fOFC4SGvYh/l8yohJmCTFq0tETqvZr9Atw9ZOz2cIBFx76wlS/eR9iB/JZ3DGM+2THC6Mjv70ipWX32UW7620Bb5KONm3Vw0eeIHckUn6QaHGfFL/URT6mr7YCJhG5lZynWYZcLv/ffWuFcSmO9p0xCrwqqPEjdaaGs52mqmA4Ikt9MulKAEp6p65V1vxt7Tdy6m9UVjzbEy1zFuU9iOHBAAaj6A8Mj1EEUe6sNx3fLHnC2c0+2Zf3eUxMZPm5dQZPOUXLI28yoCliBIhTYTSh7ATULDDvcnNMs/ziuG7WT/U1wuIHkT5kEE73tnG1EZY4RDODbQobmpBegcuUEh64HEGS7+aK/KPYWxFxWW5oVd0Dc7kvpariXqEhlNdDY65b2T8uBw8bI/HrfvT8d0EnsPz26B1xKZYqyusWnlR+10KdYzPNoupx8vWk74PW8zI5qlcV497SPtvn12a3wvZ8adJzMuP4hsBoKHG/M2nf0lOMbo1gcbHbT0FqcHE3mixY3lU+UnNC5jpmNCs1tK8yqeQdVtHE3YM4Y5SsnBTJddUWVpUxZ6rlU+H2NW/uGcDLBs3HmERTn1l6E1mmqKB2kPA/+Y/YbILXNojbkgRE/3lki5kX4+pjHDxF/mWEEeXpjIl4yKG97mVS2J0dGoJ5CqLv6/CdHhtwu35UydBVDVGHywufVLwPgEiDA9RklM/bQw3ojdlTrn6+irDcz8/Tj7KmK2votLaN6yIEM8Ex2htyBlyX/47eEsh63nSNwSx+uPcTxjH9N5cJpWzJ2KcBMIqZsWOTgISBUndgRdoVTFySY2XwbHlDjh8RCLLBsYRhvOK+nvNqEBnrfzz81B/sqDO1whQDTKT3ZcFnZouaVImRGHcOt0sRioq/JGHAHzRjyc/V9Gb/zTlI8QQob5y5k7dfReAy1rGdkeIa3LXSwWGz8hDjEnGsGGIC4evdiefgoJHkhzEywi/QUEOOnqms/0BzexbLP+89qMgGMlEbA9iLAW/BZgsAkxm+NHqGNtz9HDJStpqewElgjMQ+wV3TUGbrmY0O/FyQn/CXyhXjdRC0/5S1tZnzBMyolHF2a5L5EAzGck2MuV7TgLs6LcvGm7kIeq0vmBCkiUB4IBHMhraU7Ba+cC+CW7tDK0Tkanri5KSMXSXamJpU869Jcsk1JLm69ATMl3eIb5rPx5+GbPUrRogEUP3HQeLMQP8jjq6fVwzGPQByF70t0fE+Z23NuCLzhVss0YkMmzcKK8GjKCJ0vnCA0qanxovpDgCOHjgxvy44N+QNWfUynIKVHS9m7FDE3RgKf7rOfSM9vJ7F/KWo7kywi36ajuFbWcON/MTvlpPUhGm5dboiz3vyfpTWkQbd9XX7SPVBWCkvGg+A87R7RSN8bsWbmYm5m2wt3jrkBVSDn5FV3rek6X0GSpTDTWJ9ktmjKtshplXn7fx7XAKtS4hpEMGhZwi/LWvfTsGqOJlqi2FwYPLI7SVunch2VSfssejrfwxJHPqF50wTv6ax28lp7wToqsVunZprdhyY++gds/LAz083dZLM3EYcbHuGVXiNRFxptpiQNjEnyjZX0fc8UF1W2icDt7Gd5Pp2ckaPERLE+tJ+ackMxomH2/HjFB3XRXlDCoKuljtJ2cbw/gVPmHtV7Qw2w6tWaCzYP3g1D47BlrIqBV4RWjcPRjthfcWPnwUSSHwlJ4dLMQ+cJ402ol+HUukAKpkh5lcjME0uaD8KKReD/Ee9r4kubIR7z9JViXjnJJl3Jxr6KtK3abrg8cG8qVFRr5NDhxbfs9NY/zGDvbgt0GMWXRTi4oMrSkDKthZSWjVezDzPk11AMQ1E+SJSoSXgwUl1rbWPg0O29prkQdfdKQmZcaO5oj7+f3kSPsIOE9+Qn43VOxOWWybkCzSvEbzLgmuov5C8EWYeJgh13qDcNSwNdt4PgAqIq+tikKNUo9qeM9/q20an+i20fatPAcvrRes+xxnIBXmlPDCj02THjX4EulV2KE+nNxFnCrNvFKYp2bEAegJ2neqfeefDDDhn+t7OK9/73v3O3qnEwSyBlt+pEyHfLjv3Cm7Ik7JA5NUQ/nsS3JdC8OYy2i1DWSvi1qsP3ixAVCR7qBVdoOF2Lv5y2GWrJ0EvVcGqaPBnUezMGMdozNjreschNJvRlp3D72dGGQgs00GHyHbIQ5wicC5p+PiZ2z1EUBN7DiDy9ShQPKEDJtISiSrSaPkDPKpW7SxmSfDaLOIxEy4daAupV0gj7yTtrkpEvJjRECpa0kuKFP3/eFVVp/nIjWDzFASfDvYiry90dDrvLxO3tosuvMVfhXcOy/zbyeCkObaFgc3OkO4z2r4X4Vwt18BoRAammiEfgCbnhywl/CmLrSwV1qSjUgALh/XUPkqXCkqerNjYTlZw5NdRUKmheUXHYGwo4Z+xPfDtiHk1N5vRgNL9/qXsgt813spju9kDMGQGiXlrOgIyhArHR5p2B4S3FjRQ/lEoP5+5wN+9tBKYrR79sZXNS8CwR0BPrOoY9GQCYFdxrBtyH6KOWg29FVXNodt2Yvot7ktofcen1zwQJOAr0KTyqF9/TIltO+hS7swSzZMjV368SEPYjrtXfnXNWYltOS2zJAWYeqr0XLrL+iHbbOQLC7Rk0mnizmUt9wdefz4MtfXZNcdKR4LPsOqYyIz5ux90XiCbvcNZJaRa2/dzecv/koLQPbKzFPGxKiUOsHAa5SEGgbWFZE4Y9CBFS4nCuEOgUnVz9XtFAEP4dazc2cxjYLVzaG5msOiOY1O5ZygYMeVZfdKaITg7gMPbkL3Lpzo7QBMXcHmT5YAUeNaSbHxvgg45Jn8r7W72EQP9tF7SPKiPvxo91xkB7MA3JOcZXC1qymTUWqjO038wSShK48kE+qgu7V9rjP5fOCDW3+3338eifxqS7Zq6FSO053c5W2c8wFR4iw==",
"encryptedKey": "OzSHFXzrXFC5wDvM5NPRkriY/NaC/USvFUPE+f4NZ30tiD2qb8sJM2XT2K7uNIZ05uDLfsJ6/BbEoYC1SOPXcFJMYqRiYFiI9RWrNgR4EtPWZ84RgrmxGcZZjzSqHzjuls8g++cuqJGRV+ePbTRH+z2OuZZu0vMKZiemaZpHL46Ewi9HUnbRDXvOlKFFHmQm5tayZ7m7Mv5iu4T5R3DPEAHlZnGqtP98ToLxUJUS2Eku/iLHXRmhmZXn55Qt5GYiyss8P5/miPqJCu1QG0CStn5Nsl4KvU+I4QYAOcMFWWUAGofOwPWtt8vPh8Bx+7t7BbayKpA4ZUEWWAjC+zASxg==",
"iv": "SHM0UHU5WXoyTG03TnExWA=="
}
```
```javascript theme={null}
const crypto = require('crypto');
/**
* Decrypts the symmetric key using the provided private key.
* @param {string} encryptedKey - Base64 encoded encrypted symmetric key
* @param {string} privateKey - RSA private key
* @returns {Buffer} Decrypted symmetric key
*/
function decryptSymmetricKey(encryptedKey, privateKey) {
try {
const encryptedSymmetricKey = Buffer.from(encryptedKey, 'base64');
const decryptedSymmetricKey = crypto.privateDecrypt(
{
key: `-----BEGIN RSA PRIVATE KEY-----\n${privateKey}\n-----END RSA PRIVATE KEY-----`,
padding: crypto.constants.RSA_PKCS1_OAEP_PADDING,
oaepHash: 'sha256',
},
encryptedSymmetricKey
);
return decryptedSymmetricKey;
} catch (error) {
console.error('Error decrypting symmetric key:', error);
throw new Error('Failed to decrypt symmetric key');
}
}
/**
* Decrypts the webhook data using the provided symmetric key and IV.
* @param {string} encryptedWebhookData - Base64 encoded encrypted webhook data
* @param {Buffer} symmetricKey - Decrypted symmetric key
* @param {string} payloadIv - Base64 encoded initialization vector
* @returns {Object} Decrypted webhook data as a JSON object
*/
function decryptWebhookData(encryptedWebhookData, symmetricKey, payloadIv) {
try {
const iv = Buffer.from(payloadIv, 'base64');
const decipher = crypto.createDecipheriv('aes-256-cbc', symmetricKey, iv);
let decryptedData = decipher.update(encryptedWebhookData, 'base64', 'utf8');
decryptedData += decipher.final('utf8');
return JSON.parse(decryptedData);
} catch (error) {
console.error('Error decrypting webhook data:', error);
throw new Error('Failed to decrypt webhook data');
}
}
// Example usage:
// const decryptedKey = decryptSymmetricKey(encryptedKey, privateKey);
// const decryptedData = decryptWebhookData(encryptedWebhookData, decryptedKey, payloadIv);
```
### **Payload Schema**
1. **Default payload**: [WebhookV1Payload](/api-reference/sdk/models/data-models#webhookv1payload) — common fields shared across all events
* [Comment Events](/api-reference/sdk/models/data-models#comment-events) — comment-specific fields
* [Huddle Events](/api-reference/sdk/models/data-models#huddle-events) — no additional fields
* [CRDT Events](/api-reference/sdk/models/data-models#crdt-events) — CRDT-specific fields
2. **Encoded payload**: If you have enabled payload encoding, you will receive the payload in this format: [WebhookV1PayloadEncoded](/api-reference/sdk/models/data-models#webhookv1payloadencoded)
3. **Encrypted payload**: If you have enabled payload encryption, you will receive the payload in this format: [WebhookV1PayloadEncrypted](/api-reference/sdk/models/data-models#webhookv1payloadencrypted)
If you have configured [notification settings](/async-collaboration/notifications/customize-behavior), per-user notification preferences (`usersOrganizationNotificationsConfig` or `usersDocumentNotificationsConfig`) will be included in the webhook payload.
## Comments Events
The `Comments` component will emit webhook notifications whenever an `action type` occurs on a comment.
**Payload Schema**: [WebhookV1Payload](/api-reference/sdk/models/data-models#webhookv1payload) + [Comment Events](/api-reference/sdk/models/data-models#comment-events)
### List of Action Types
| Action Type | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------ |
| `newlyAdded` | When the first comment in a thread is added |
| `added` | When a new comment is added. Not used for the first comment in a thread - see `newlyAdded` |
| `updated` | When an existing comment content gets updated |
| `deleted` | When an existing comments gets deleted |
| `approved` | When the comment is approved by the moderator. This is only applicable if you have turned on Moderator Mode. |
| `assigned` | When a comment gets assigned to a user |
| `statusChanged` | When a comment has its status changed (e.g. in progress, resolved, opened) |
| `priorityChanged` | When a comment has its priority changed (e.g. P0, P1, P2 or custom set priorities) |
| `accessModeChanged` | When a comment is changed from private to public or vice-versa |
| `accepted` | When a comment gets accepted by the moderator. This is only applicable if you have turned on Moderator Mode. |
| `rejected` | When a comment gets rejected by the moderator. This is only applicable if you have turned on Moderator Mode. |
| `reactionAdded` | When a reaction is added to a comment. |
| `reactionDeleted` | When a reaction is removed from a comment. |
| `subscribed` | When a user subscribes to a comment annotation using the option in the UI. |
| `unsubscribed` | When a user unsubscribes from a comment annotation using the option in the UI. |
```js Sample Webhook Data expandable lines theme={null}
{
"webhookId": "-Nvmw84XtUUHIsrcKAvI",
"commentAnnotation": {
"annotationId": "-O7Yi14ES3EPayuzQ54J",
"annotationIndex": 20,
"comments": [
{
"commentHtml": "@Jim Halpert can you take a look?",
"commentId": 822004,
"commentText": "@Jim Halpert can you take a look?",
"from": {
"clientOrganizationId": "velt-sample-app",
"color": "#67DBF4",
"email": "peppa.pig@velt.dev",
"initial": "P",
"isAdmin": false,
"name": "Peppa Pig",
"organizationId": "392580a690394bfadd823101f2b05513",
"photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Fpeppa_pig.svg?alt=media&token=a9fc83f7-b347-4868-8d52-0e888f0de73a&_gl=1*jzxghx*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMTQ5LjQyLjAuMA..",
"textColor": "#fff",
"type": "signedIn",
"userId": "user0",
"userSnippylyId": "195298461116078"
},
"lastUpdated": "2024-09-24T11:08:49.724Z",
"status": "added",
"taggedUserContacts": [
{
"contact": {
"email": "jim.halpert@dundermifflin.com",
"initial": "J",
"name": "Jim Halpert",
"photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Frosy_rabbit.svg?alt=media&token=4e65a9e3-080d-4416-839d-e761b6b37181&_gl=1*156om5t*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMjUzLjYwLjAuMA..",
"userId": "e54d19af-0e43-4364-819f-0a8b18a280fb",
"userSnippylyId": "5236622904561187"
},
"text": "@Jim Halpert",
"userId": "e54d19af-0e43-4364-819f-0a8b18a280fb"
}
],
"to": [
{
"email": "jim.halpert@dundermifflin.com",
"initial": "J",
"name": "Jim Halpert",
"photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Frosy_rabbit.svg?alt=media&token=4e65a9e3-080d-4416-839d-e761b6b37181&_gl=1*156om5t*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMjUzLjYwLjAuMA..",
"userId": "e54d19af-0e43-4364-819f-0a8b18a280fb",
"userSnippylyId": "5236622904561187"
}
],
"type": "text"
},
{
"commentHtml": "test",
"commentId": 719893,
"commentText": "test",
"from": {
"clientOrganizationId": "velt-sample-app",
"color": "#2c83fc",
"email": "freddy.froglet@velt.dev",
"initial": "F",
"isAdmin": false,
"name": "Freddy Froglet",
"organizationId": "392580a690394bfadd823101f2b05513",
"photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Ffreddy_froglet.svg?alt=media&token=e3b2e292-6480-4507-9da3-21a62a1346d4&_gl=1*s4yycs*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMDQzLjcuMC4w",
"textColor": "#fff",
"type": "signedIn",
"userId": "user8",
"userSnippylyId": "4291391246842733"
},
"lastUpdated": "2024-09-24T11:11:58.344Z",
"status": "added",
"type": "text"
}
],
"from": {
"clientOrganizationId": "velt-sample-app",
"color": "#67DBF4",
"email": "peppa.pig@velt.dev",
"initial": "P",
"isAdmin": false,
"name": "Peppa Pig",
"organizationId": "392580a690394bfadd823101f2b05513",
"photoUrl": "https://firebasestorage.googleapis.com/v0/b/snippyly-sdk-external/o/avatars%2Fpeppa_pig.svg?alt=media&token=a9fc83f7-b347-4868-8d52-0e888f0de73a&_gl=1*jzxghx*_ga*NTc3MjEzMjIwLjE2NjEwODkwMDU.*_ga_CW55HF8NVT*MTY5NzE0MTIzNC4zMzMuMS4xNjk3MTQyMTQ5LjQyLjAuMA..",
"textColor": "#fff",
"type": "signedIn",
"userId": "user0",
"userSnippylyId": "195298461116078"
},
"lastUpdated": 1727176311596,
"metadata": {
"apiKey": "AN5s6iaYIuLLXul0X4zf",
"documentId": "toolbar",
"organizationId": "velt-sample-app"
},
"pageInfo": {
"baseUrl": "https://velt-vercel-style-toolbar-demo.vercel.app",
"commentUrl": "https://velt-vercel-style-toolbar-demo.vercel.app/?scommentId=-O7Yi14ES3EPayuzQ54J",
"deviceInfo": {
"browserName": "Chrome",
"browserVersion": "128",
"deviceType": "Mobile",
"orientation": "landscape",
"osName": "Macintosh",
"osVersion": "10.15.7",
"screenHeight": 900,
"screenWidth": 1440,
"userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Safari/537.36"
},
"path": "/",
"screenWidth": 804,
"title": "Web App | Velt Demo",
"url": "https://velt-vercel-style-toolbar-demo.vercel.app/"
},
"status": {
"color": "#625DF5",
"id": "OPEN",
"lightColor": "#E7E8FA",
"name": "Open",
"svg": "\n \n
```js expandable lines theme={null}
{
"webhookId": "-Nvmw84XtUUHIsrcKAvI",
"actionType": "created",
"notificationSource": "huddle",
"actionUser": {
"clientOrganizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"color": "#19bcfe",
"email": "john@trysnippyly.com",
"organizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"name": "John Smith",
"plan": "free",
"type": "signedIn",
"userId": "1",
},
"metadata": {
"apiKey": "Emcfab4ysRXaC1CZ8hmG",
"clientDocumentId": "12-4-24",
"documentId": "1856907974154638",
"locations": {
"5638605251172150": {
"location": {
"id": "location1",
"locationName": "Location 1"
},
"locationId": 5638605251172150,
"pageInfo": {
"baseUrl": "http://localhost:3000",
"path": "/",
"title": "Velt React Demo",
"url": "http://localhost:3000/"
}
}
},
"pageInfo": {
"baseUrl": "http://localhost:3000",
"path": "/",
"title": "Velt React Demo",
"url": "http://localhost:3000/"
}
},
"platform": "sdk"
}
```
```js theme={null}
{
"webhookId": "-Nvmw84XtUUHIsrcKAvI",
"actionType": "joined",
"notificationSource": "huddle",
"actionUser": {
"clientOrganizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"color": "#ff7162",
"contacts": [
{
"email": "john@trysnippyly.com",
"name": "John Smith",
"userId": "1"
},
{
"email": "sarah@trysnippyly.com",
"name": "Sarah Wilson",
"userId": "3"
}
],
"email": "maria@trysnippyly.com",
"organizationId": "7e2aed5bc102d06f740ab92afdf58e78f9d34d409555d19a35389309c80f4b4f",
"name": "Maria Garcia",
"plan": "paid",
"type": "signedIn",
"userId": "2",
},
"metadata": {
"apiKey": "Emcfab4ysRXaC1CZ8hmG",
"clientDocumentId": "12-4-24",
"documentId": "1856907974154638",
"pageInfo": {
"baseUrl": "http://localhost:3000",
"path": "/",
"title": "Velt React Demo",
"url": "http://localhost:3000/"
}
},
"platform": "sdk"
}
```
## CRDT Events
The CRDT component will emit webhook notifications when data changes occur. Webhooks are enabled by default with a 5-second debounce.
**Payload Schema**: [WebhookV1Payload](/api-reference/sdk/models/data-models#webhookv1payload) + [CRDT Events](/api-reference/sdk/models/data-models#crdt-events)
Learn how to configure CRDT webhooks in the [CRDT Core Setup documentation](/realtime-collaboration/crdt/setup/core#webhooks).
### Action Type
| Action Type | Description |
| ------------ | ------------------------- |
| `updateData` | When CRDT data is updated |
```js Sample Webhook Data expandable lines theme={null}
{
"actionType": "updateData",
"notificationSource": "crdt",
"actionUser": {
"organizationId": "9eab9b808921fa1c682be3516bb49ab3",
"userSnippylyId": "6171441707478284",
"color": "#ffcb00",
"initial": "M",
"clientUserName": "Michael Scott",
"name": "Michael Scott",
"clientOrganizationId": "crdt-array-demo-org1",
"name_lowercase": "michaelscott",
"email_lowercase": "michael.scott@dundermifflin.com",
"textColor": "#FFFFFF",
"userId": "michael",
"email": "michael.scott@dundermifflin.com",
"photoUrl": null,
"isAdmin": false,
"type": "signedIn",
"contacts": []
},
"metadata": {
"apiKey": "VKabul7W2DJhLu1BiMaj",
"clientDocumentId": "crdt-array-demo-doc-1",
"clientOrganizationId": "crdt-array-demo-org1",
"documentId": "crdt-array-demo-doc-1",
"documentMetadata": {
"apiKey": "VKabul7W2DJhLu1BiMaj",
"clientDocumentId": "crdt-array-demo-doc-1",
"clientOrganizationId": "crdt-array-demo-org1",
"documentId": "crdt-array-demo-doc-1",
"documentName": "CRDT Array Demo",
"organizationId": "crdt-array-demo-org1",
"pageInfo": {
"baseUrl": "http://localhost:5225",
"path": "/",
"queryParams": "",
"title": "CRDT Array Demo",
"url": "http://localhost:5225/"
}
},
"documentName": "CRDT Array Demo",
"organizationId": "crdt-array-demo-org1",
"organizationMetadata": {
"apiKey": "VKabul7W2DJhLu1BiMaj",
"clientOrganizationId": "crdt-array-demo-org1",
"organizationId": "crdt-array-demo-org1"
},
"pageInfo": {
"baseUrl": "http://localhost:5225",
"path": "/",
"queryParams": "",
"title": "CRDT Array Demo",
"url": "http://localhost:5225/"
}
},
"platform": "sdk",
"crdtData": {
"data": [
{
"completed": false,
"id": "seed-1",
"text": "Welcome Todo - Edit me!"
},
{
"completed": false,
"id": "bmg6tpj7we",
"text": "Todo1"
},
{
"completed": false,
"id": "dt0vhs2t3os",
"text": "Todo2"
}
],
"id": "crdt-array-demo-todos-1",
"lastUpdate": "2026-03-17T06:23:24.514Z",
"lastUpdatedBy": "michael",
"sessionId": "tvLupvP0L2jiztlba4P0"
},
"webhookId": "-OnuSfG_ffGIwNkodE2a",
"accessDeniedUsers": []
}
```
