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`	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[]`	No	List of users who have viewed/read this comment annotation
`unread`	`boolean`	No	Whether the annotation is unread by current user
`visibilityConfig`	`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) => 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`	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`	Yes	Full annotation at the time of the visibility selection
`visibility`	`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`	Yes	Full annotation at save time
`metadata`	`VeltEventMetadata`	Yes	Event metadata

CommentContext

Custom context data for comment annotations.

type CommentContext = any;

CommentContextProviderResponse

Return type for context provider function. Can return context synchronously or asynchronously.

type CommentContextProviderResponse = CommentContext | null | undefined;

CommentContextProvider

Function type for providing context based on document and location.

type CommentContextProvider = (documentId: string, location?: Location) => CommentContextProviderResponse | Promise<CommentContextProviderResponse>;

CommentVisibilityType

Visibility level used by API methods such as updateVisibility() and enablePrivateMode() via CommentVisibilityConfig.

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 with 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 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 — the API’s single 'restricted' value maps to two UI options ('restrictedSelf' and 'restrictedSelectedPeople').

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 enum values. Used in UI wireframe components.

export type CommentVisibilityOptionType = `${CommentVisibilityOption}`;
// = 'restrictedSelf' | 'restrictedSelectedPeople' | 'organizationPrivate' | 'public'

CommentVisibilityConfig

Configuration object for API methods that update comment visibility. Uses CommentVisibilityType values — not CommentVisibilityOption values.

Property	Type	Required	Description
`type`	`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 — excludes annotationId and organizationId. Uses CommentVisibilityType values.

type PrivateModeConfig = Omit<CommentVisibilityConfig, 'annotationId' | 'organizationId'>;

Property	Type	Required	Description
`type`	`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`	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<string, CommentAnnotationsCount> \| null`	Yes	Map of document IDs to their comment counts. Null while loading

GetCommentAnnotationsResponse

Property	Type	Required	Description
`data`	`Record<string, CommentAnnotation[]> \| 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<string, CommentAnnotation[]> \| 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<string, CommentAnnotation[]>`	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<string, CommentAnnotationsCount>`	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.

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.

TiptapVeltCommentsOptions

Property	Type	Required	Description
`HTMLAttributes`	`Record<string, any>`	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.

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.

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.

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.

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.

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

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 for usage examples and API Methods for component documentation.

CommentDialogCommonProps

Usage Examples →

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 →

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 →

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.

CommentIndexProps

Usage Examples →

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.

ComposerProps

Usage Examples →

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.

ComposerInputProps

Usage Examples →

Props for VeltCommentDialogComposerInput.

Property	Type	Required	Description
`placeholder`	`string`	No	Input placeholder text

Inherits all properties from CommentDialogCommonProps.

StatusDropdownItemProps

Usage Examples →

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.

PriorityDropdownItemProps

Usage Examples →

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.

OptionsDropdownProps

Usage Examples →

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.

CustomAnnotationItemProps

Usage Examples →

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.

ReplyAvatarsListItemProps

Usage Examples →

Props for VeltCommentDialogReplyAvatarsListItem.

Property	Type	Required	Description
`user`	`User`	Yes	User data object
`index`	`number`	Yes	Index of user in list

Inherits all properties from 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<string, UserPermissionInfo>; organization?: Record<string, UserPermissionInfo>; documents?: Record<string, UserPermissionInfo>; }`	Yes	Permissions for a user, keyed by resource scope and ID.

UI

AssignToType

UI mode for assignment functionality.

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`	Yes	Full draft annotation with attachments, recordings, tagged users
`targetComposerElementId`	`string`	Yes	Unique identifier of the composer that triggered the event
`metadata`	`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.

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.

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

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`	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.
`isRecorderResolverUsed`	`boolean`	No	True while PII is being fetched from the recorder resolver; use for loading states.
`isUrlAvailable`	`boolean`	No	True once the recording URL is available (not a local blob); use for upload progress.

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<void>`	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`	No	Controls whether notifications are held before delivery.
`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.

Property	Type	Required	Description
`document`	`BatchWindowConfig`	No	Batching window applied per document.
`user`	`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.

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[]`	No	Filter by feature area
`excludeFeatureTypes`	`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`	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`	Yes	User who performed the action
`timestamp`	`number`	Yes	Unix timestamp of the activity log
`metadata`	`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`	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<string, unknown>`	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.

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`	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`	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<string, unknown>`	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.

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
`INIT_UPDATE`	`initUpdate`	Initialization lifecycle updates (documents/locations set/unset, user init).	InitUpdateEvent
`DOCUMENT_INIT`	`documentInit`	Document initialization status changes.	DocumentInitEvent
`ERROR`	`error`	Error events emitted by the SDK (e.g., token issues, retry limits).	ErrorEvent
`VELT_BUTTON_CLICK`	`veltButtonClick`	Fired when a Velt Button is clicked.	VeltButtonClickEvent
`PERMISSION_PROVIDER`	`permissionProvider`	Permission Provider events for access requests, results, and errors.	PermissionProviderEvent
`DATA_PROVIDER`	`dataProvider`	Data Provider events for debugging get, save, and delete operations.	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 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

RecorderResolverEvent

Event Type	Description
`recorderResolutionRequestFormed`	Triggered when a recorder get request is formed internally
`recorderResolutionRequestTriggered`	Triggered when a recorder get request is sent
`recorderResolutionResult`	Triggered when recorder get completes successfully
`recorderResolutionError`	Triggered when an error occurs during recorder get
`recorderResolutionResultFromCache`	Triggered when a recorder get result is retrieved from cache
`recorderSaveRequestFormed`	Triggered when a recorder save request is formed internally
`recorderSaveRequestTriggered`	Triggered when a recorder save request is sent
`recorderSaveResult`	Triggered when recorder save completes successfully
`recorderSaveError`	Triggered when an error occurs during recorder save
`recorderDeleteRequestFormed`	Triggered when a recorder delete request is formed internally
`recorderDeleteRequestTriggered`	Triggered when a recorder delete request is sent
`recorderDeleteResult`	Triggered when recorder delete completes successfully
`recorderDeleteError`	Triggered when an error occurs during recorder delete

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<string, FolderMetadata> \| 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<string, DocumentMetadata[]> \| null`	Yes	Map of document groups to arrays of 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<T>[]`	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`	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`	No	Debug information from the server-side state
`clientMap`	`DebugInfoMap`	No	Debug information from the client-side state

DebugInfoMap

Property	Type	Required	Description
`organization`	`OrganizationMetadata`	No	Metadata about the current organization
`documents`	`DocumentMetadata[]`	No	Array of document metadata for all active documents
`locations`	`Location[]`	No	Array of location information for all active locations
`folder`	`FolderMetadata`	No	Metadata about the current folder
`user`	`User`	No	The currently authenticated user

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<T>[]`	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
`RECORDER_ANNOTATION_ADD`	`'recorder_annotation.add'`	Triggered when a recorder annotation is added
`RECORDER_ANNOTATION_UPDATE`	`'recorder_annotation.update'`	Triggered when a recorder annotation is updated
`RECORDER_ANNOTATION_DELETE`	`'recorder_annotation.delete'`	Triggered when a recorder annotation is deleted

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 →

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 →

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 →

Name	Value	Description
`SET_DOCUMENTS`	`'setDocuments'`	Resolver module for setting reaction documents
`GET_REACTION_ANNOTATIONS`	`'getReactionAnnotations'`	Resolver module for fetching reaction annotations

RecorderResolverModuleName

Enum defining module names for recorder-related resolver operations. Used in data provider events to identify which module triggered the resolver call. Self-Host Recording Data →

Name	Value	Description
`GET_RECORDER_ANNOTATIONS`	`'getRecorderAnnotations'`	Resolver module for fetching recorder annotations

RecorderResolverSource

Enum defining the source of a recorder resolver lifecycle event.

Name	Value	Description
`RESOLVE_RECORDER_ANNOTATIONS`	`'resolveRecorderAnnotations'`	Source for resolving (fetching) recorder annotations
`SAVE_RECORDER_ANNOTATION`	`'saveRecorderAnnotation'`	Source for saving a recorder annotation
`DELETE_RECORDER_ANNOTATION`	`'deleteRecorderAnnotation'`	Source for deleting a recorder annotation
`FORMAT_RESPONSE`	`'formatResponse'`	Source for formatting the resolver response
`INIT_DOCUMENTS`	`'initDocuments'`	Source for initializing documents
`SET_DATA`	`'setData'`	Source for setting recorder data
`UPDATE_DATA`	`'updateData'`	Source for updating recorder data
`DELETE_DATA`	`'deleteData'`	Source for deleting recorder data

RecorderResolverEventType

Union type for all recorder resolver lifecycle event type strings.

Value	Description
`'recorderResolutionRequestFormed'`	A recorder get request was formed internally
`'recorderResolutionRequestTriggered'`	A recorder get request was sent
`'recorderResolutionResult'`	Recorder get completed successfully
`'recorderResolutionError'`	An error occurred during recorder get
`'recorderResolutionResultFromCache'`	A recorder get result was retrieved from cache
`'recorderSaveRequestFormed'`	A recorder save request was formed internally
`'recorderSaveRequestTriggered'`	A recorder save request was sent
`'recorderSaveResult'`	Recorder save completed successfully
`'recorderSaveError'`	An error occurred during recorder save
`'recorderDeleteRequestFormed'`	A recorder delete request was formed internally
`'recorderDeleteRequestTriggered'`	A recorder delete request was sent
`'recorderDeleteResult'`	Recorder delete completed successfully
`'recorderDeleteError'`	An error occurred during recorder delete

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<string, PartialComment>`	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
`recorder`	`RecorderAnnotationDataProvider`	No	Provider for recording annotation PII data
`anonymousUser`	`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<string, string>`	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
`additionalFields`	`string[]`	No	Additional fields from the feature’s data object (e.g., `CommentAnnotation`, `RecorderAnnotation`) to include in resolver request payloads sent to your backend. By default, only core content/PII fields are sent.

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<ResolverResponse<Record<string, PartialCommentAnnotation>>>`	No	Function to fetch comment annotations
`save`	`(request: SaveCommentResolverRequest) => Promise<ResolverResponse<T>>`	No	Function to save comment annotations
`delete`	`(request: DeleteCommentResolverRequest) => Promise<ResolverResponse<undefined>>`	No	Function to delete comment annotations
`config`	`ResolverConfig`	No	Configuration for the data provider

ReactionAnnotationDataProvider

Property	Type	Required	Description
`get`	`(request: GetReactionResolverRequest) => Promise<ResolverResponse<Record<string, PartialReactionAnnotation>>>`	No	Function to fetch reaction annotations
`save`	`(request: SaveReactionResolverRequest) => Promise<ResolverResponse<T>>`	No	Function to save reaction annotations
`delete`	`(request: DeleteReactionResolverRequest) => Promise<ResolverResponse<undefined>>`	No	Function to delete reaction annotations
`config`	`ResolverConfig`	No	Configuration for the data provider

UserDataProvider

Property	Type	Required	Description
`get`	`(userIds: string[]) => Promise<Record<string, User> \| ResolverResponse<Record<string, User>>>`	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<ResolverResponse<SaveAttachmentResolverData>>`	No	Function to save attachment data
`delete`	`(request: DeleteAttachmentResolverRequest) => Promise<ResolverResponse<undefined>>`	No	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

UploadFileOptions

Property	Type	Required	Description
`file`	`File`	Yes	File object to upload
`useAttachmentResolver`	`boolean`	No	Whether to route upload through the attachment resolver
`metadata`	`any`	No	Custom metadata to pass to the upload handler
`attachmentScope`	`string`	No	Routes upload to the named `AttachmentDataProvider` scope (e.g., `'default'`, `'recorder'`)

RecorderAnnotationDataProvider

Property	Type	Required	Description
`get`	`(request: GetRecorderResolverRequest) => Promise<ResolverResponse<Record<string, PartialRecorderAnnotation>>>`	No	Function to fetch recorder annotation PII data
`save`	`(request: SaveRecorderResolverRequest) => Promise<ResolverResponse<SaveRecorderResolverData \| undefined>>`	No	Function to save recorder annotation PII data
`delete`	`(request: DeleteRecorderResolverRequest) => Promise<ResolverResponse<undefined>>`	No	Function to delete recorder annotation PII data
`config`	`ResolverConfig`	No	Configuration for the data provider
`uploadChunks`	`boolean`	No	Whether to upload recording in chunks
`storage`	`AttachmentDataProvider`	No	Storage provider for recording media files

GetRecorderResolverRequest

Property	Type	Required	Description
`organizationId`	`string`	Yes	ID of the organization
`recorderAnnotationIds`	`string[]`	No	Recorder annotation IDs to fetch
`documentIds`	`string[]`	No	Document IDs to filter annotations by

SaveRecorderResolverRequest

Property	Type	Required	Description
`recorderAnnotation`	`Record<string, PartialRecorderAnnotation>`	Yes	Map of annotation IDs to partial recorder annotation data
`event`	`ResolverActions`	No	Resolver action that triggered the save
`metadata`	`BaseMetadata`	No	Additional metadata

SaveRecorderResolverData

Property	Type	Required	Description
`transcription`	`Transcription`	No	Updated transcription for the recording
`attachment`	`Attachment \| null`	No	Primary attachment (deprecated; use `attachments`)
`attachments`	`Attachment[]`	No	List of updated attachments for the recording

DeleteRecorderResolverRequest

Property	Type	Required	Description
`recorderAnnotationId`	`string`	Yes	ID of the recorder annotation to delete
`metadata`	`BaseMetadata`	No	Additional metadata
`event`	`ResolverActions`	No	Resolver action that triggered the delete

PartialRecorderAnnotation

Property	Type	Required	Description
`annotationId`	`string`	Yes	ID of the recorder annotation
`metadata`	`BaseMetadata`	No	Additional metadata
`from`	`User`	No	User who created the recorder annotation
`transcription`	`Transcription`	No	Transcription of the recorded media
`attachment`	`Attachment \| null`	No	Primary attachment (deprecated; use `attachments`)
`attachments`	`Attachment[]`	No	List of attachments for the recording
`chunkUrls`	`Record<number, string>`	No	Map of chunk index to chunk URL for chunked uploads
`recordingEditVersions`	`Record<number, PartialRecorderAnnotationEditVersion>`	No	Map of edit version index to edit version data
`[key: string]`	`any`	No	Additional custom fields

PartialRecorderAnnotationEditVersion

Property	Type	Required	Description
`from`	`User`	No	User who created this edit version
`attachment`	`Attachment \| null`	No	Attachment for this edit version
`attachments`	`Attachment[]`	No	List of attachments for this edit version
`transcription`	`Transcription`	No	Transcription for this edit version

PartialRecorderAnnotationResult

Property	Type	Required	Description
`strippedData`	`Record<string, PartialRecorderAnnotation> \| null`	Yes	Annotation data with PII stripped
`originalData`	`RecorderAnnotation \| null`	Yes	Original annotation data before PII stripping
`eventType`	`ResolverActions`	No	Resolver action that produced this result

AnonymousUserDataProvider

Property	Type	Required	Description
`resolveUserIdsByEmail`	`(request:` `ResolveUserIdsByEmailRequest) => Promise<ResolverResponse<Record<string, string>>>`	Yes	Callback to resolve email addresses to user IDs.
`config`	`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`	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 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<string, NotificationChannelConfig>`	No	Per-user org-level notification preferences keyed by userId.
`usersDocumentNotificationsConfig`	`Record<string, 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<string, NotificationChannelConfig>`	No	Per-user org-level notification preferences keyed by userId.
`usersDocumentNotificationsConfig`	`Record<string, 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<string, NotificationChannelConfig>`	No	Per-user org-level notification preferences, keyed by userId.
`usersDocumentNotificationsConfig`	`Record<string, 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.

type NotificationChannelConfig = Record<string, 'ALL' | 'MINE' | 'NONE'>;

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

UserContactSelectedPayload

Property	Type	Required	Description
`contact`	`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<string>`	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	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. 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	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[]	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`; id: string; source:` PermissionSource`; organizationId: string; context?:` Context `}`	Yes	Resource the user is requesting access to. The `type` uses `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	Yes	Type of resource being accessed. Can be `organization`, `document`, `location`, or `context`.
`organizationId`	`string`	Yes	Organization ID associated with the resource.
`accessRole`	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.

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:

{
    "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 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<string \| number> }`	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 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`	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.

Property	Type	Description
`store`	`Store<FlowState>`	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<unknown> \| 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<void>`	Initializes the underlying Store and triggers callbacks.
`getStore()`	`Store<string>`	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<void>`	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<VeltTipTapStore \| null>`	Initialized store or `null` on failure.

Core Collaboration

StoreConfig`<T>`;

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<T> \| null`	The underlying Velt Store instance.
`update`	`(newValue: T) => void`	Updates the store value.
`saveVersion`	`(name: string) => Promise<string>`	Saves a new version and returns its ID.
`getVersions`	`() => Promise<Version[]>`	Fetches all versions.
`getVersionById`	`(id: string) => Promise<Version \| null>`	Fetches a specific version by ID.
`restoreVersion`	`(id: string) => Promise<boolean>`	Restores the store to a specific version.
`setStateFromVersion`	`(version: Version) => Promise<void>`	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<T>) => Promise<R>`	Yes	Asynchronous function that encrypts data and returns the encrypted result.
`decrypt`	`(config: DecryptConfig<R>) => Promise<T>`	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`	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

CrdtPushMessageQuery

Query to push a raw Yjs message into the unified message stream for a given document.

Property	Type	Required	Description
`id`	`string`	Yes	Document or store identifier
`data`	`number[]`	Yes	Raw Yjs message bytes
`yjsClientId`	`number`	Yes	Yjs client ID of the sender
`messageType`	`'sync' \| 'awareness'`	No	Message type; defaults to `'sync'`
`eventData`	`unknown`	No	Optional arbitrary event payload
`type`	`string`	No	Yjs data type: `'text'`, `'map'`, `'array'`, `'xml'`, `'xmltext'`
`contentKey`	`string`	No	Content key used in Y.Doc shared types
`source`	`string`	No	Editor/library source identifier (e.g., `'tiptap'`, `'plate'`, `'codemirror'`)

CrdtOnMessageQuery

Query to subscribe to incoming messages on the unified message stream.

Property	Type	Required	Description
`id`	`string`	Yes	Document or store identifier
`callback`	`(message: CrdtMessageData) => void`	Yes	Called with each received message
`afterTs`	`number`	No	Only deliver messages with timestamp after this value

CrdtMessageData

Data object representing a single message received from the unified message stream.

Property	Type	Required	Description
`data`	`number[]`	Yes	Raw Yjs message bytes
`yjsClientId`	`number`	Yes	Yjs client ID of the sender
`timestamp`	`number`	Yes	Unix timestamp when the message was persisted

CrdtGetMessagesQuery

Query to retrieve historical messages from the unified message stream.

Property	Type	Required	Description
`id`	`string`	Yes	Document or store identifier
`afterTs`	`number`	No	Only return messages with timestamp after this value

CrdtGetSnapshotQuery

Query to retrieve the latest CRDT state snapshot for a document.

Property	Type	Required	Description
`id`	`string`	Yes	Document or store identifier

CrdtSnapshotData

Snapshot of the CRDT document state at a point in time.

Property	Type	Required	Description
`state`	`Uint8Array \| number[]`	No	Encoded Yjs document state
`vector`	`Uint8Array \| number[]`	No	Encoded Yjs state vector
`timestamp`	`number`	No	Unix timestamp when the snapshot was saved

CrdtSaveSnapshotQuery

Query to persist a CRDT state snapshot for a document.

Property	Type	Required	Description
`id`	`string`	Yes	Document or store identifier
`state`	`Uint8Array \| number[]`	Yes	Encoded Yjs document state to persist
`vector`	`Uint8Array \| number[]`	Yes	Encoded Yjs state vector to persist
`type`	`string`	No	Custom type label for the snapshot
`contentKey`	`string`	No	Key identifying a sub-section of the document content
`source`	`string`	No	Identifies the origin of this snapshot

CrdtPruneMessagesQuery

Query to delete historical messages older than a given timestamp from the message stream.

Property	Type	Required	Description
`id`	`string`	Yes	Document or store identifier
`beforeTs`	`number`	Yes	Delete all messages with timestamp before this value

REST APIs

SDK

​Comments

​Threads

​CommentAnnotation

​Enum

​AddCommentAnnotationEvent

​AddCommentAnnotationDraftEvent

​DeleteCommentAnnotationEvent

​CommentBubbleClickedEvent

​CommentSavedEvent

​VisibilityOptionClickedEvent

​CommentSaveTriggeredEvent

​CommentContext

​CommentContextProviderResponse

​CommentContextProvider

​CommentVisibilityType

​CommentVisibilityOption

​CommentVisibilityOptionType

​CommentVisibilityConfig

​PrivateModeConfig

​CommentAnnotationVisibilityConfig

​CommentAnnotationSubscribedUsers

​CommentAnnotationUnsubscribedUsers

​AddCommentAnnotationRequest

​DeleteCommentAnnotationRequest

​SubmitCommentRequest

​ClearComposerRequest

​GetComposerDataRequest

​PageModeComposerConfig

​AssignToConfig

​FormatConfig

​CommentRequestQuery

​GetCommentAnnotationsCountResponse

​GetCommentAnnotationsResponse

​FetchCommentAnnotationsRequest

​FetchCommentAnnotationsResponse

​GetCommentResolverRequest

​SaveCommentResolverRequest

​DeleteCommentResolverRequest

​CustomAnnotationDropdownData

​CustomAnnotationDropdownItem

​GetCommentAnnotationsResponse

​CommentAnnotationsCount

​GetCommentAnnotationsCountResponse

​Slate

​AddCommentRequest

​RenderCommentsRequest

​VeltCommentsElement

​Tiptap

​AddCommentRequest

​RenderCommentsRequest

​TiptapVeltCommentsOptions

​CommentAnnotationContext

​TextEditorConfig

​Lexical

​AddCommentRequest

​RenderCommentsRequest

​CommentNode

​Plate

​AddCommentRequest

​RenderCommentsRequest

​VeltCommentsPluginConfig

​VeltCommentsElement

​CodeMirror

​AddCommentRequest

​RenderCommentsRequest

​CodemirrorVeltCommentsConfig

​Ace

​AddCommentRequest

​RenderCommentsRequest

​AceVeltCommentsConfig

​Quill

​AddCommentRequest

​RenderCommentsRequest

​QuillVeltCommentsConfig

​Messages

​ENUMs

​Comment

​AddCommentEvent

Comments

Threads

CommentAnnotation

Enum

AddCommentAnnotationEvent

AddCommentAnnotationDraftEvent

DeleteCommentAnnotationEvent

CommentBubbleClickedEvent

CommentSavedEvent

VisibilityOptionClickedEvent

CommentSaveTriggeredEvent

CommentContext

CommentContextProviderResponse

CommentContextProvider

CommentVisibilityType

CommentVisibilityOption

CommentVisibilityOptionType

CommentVisibilityConfig

PrivateModeConfig

CommentAnnotationVisibilityConfig

CommentAnnotationSubscribedUsers

CommentAnnotationUnsubscribedUsers

AddCommentAnnotationRequest

DeleteCommentAnnotationRequest

SubmitCommentRequest

ClearComposerRequest

GetComposerDataRequest

PageModeComposerConfig

AssignToConfig

FormatConfig

CommentRequestQuery

GetCommentAnnotationsCountResponse

GetCommentAnnotationsResponse

FetchCommentAnnotationsRequest

FetchCommentAnnotationsResponse

GetCommentResolverRequest

SaveCommentResolverRequest

DeleteCommentResolverRequest

CustomAnnotationDropdownData

CustomAnnotationDropdownItem

GetCommentAnnotationsResponse

CommentAnnotationsCount

GetCommentAnnotationsCountResponse

Slate

AddCommentRequest

RenderCommentsRequest

VeltCommentsElement

Tiptap

AddCommentRequest

RenderCommentsRequest

TiptapVeltCommentsOptions

CommentAnnotationContext

TextEditorConfig

Lexical

AddCommentRequest

RenderCommentsRequest

CommentNode

Plate

AddCommentRequest

RenderCommentsRequest

VeltCommentsPluginConfig

VeltCommentsElement

CodeMirror

AddCommentRequest

RenderCommentsRequest

CodemirrorVeltCommentsConfig

Ace

AddCommentRequest

RenderCommentsRequest

AceVeltCommentsConfig

Quill

AddCommentRequest

RenderCommentsRequest

QuillVeltCommentsConfig

Messages

ENUMs

Comment

AddCommentEvent

UpdateCommentEvent

DeleteCommentEvent