> ## Documentation Index > Fetch the complete documentation index at: https://docs.velt.dev/llms.txt > Use this file to discover all available pages before exploring further. # Data models # Comments ### Threads #### CommentAnnotation *** | Property | Type | Required | Description | | ------------------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `annotationId` | `string` | Yes | Unique identifier for the comment pin annotation. Auto generated | | `comments` | `Comment[]` | Yes | The list of all comments part of this annotation | | `commentCategories` | `CustomCategory[]` | Yes | The list of categories that this comment pin annotation belongs to | | `from` | `User` | Yes | The user who created this comment pin annotation | | `color` | `string` | No | Color used for the comment pin annotation | | `resolved` | `boolean` | No | Whether the comment annotation is marked resolved. Deprecated | | `inProgress` | `boolean` | No | Whether the comment annotation is marked as in progress. Deprecated | | `lastUpdated` | `any` | No | Timestamp when the comment annotation was last updated. Auto generated | | `createdAt` | `any` | No | Timestamp when the comment annotation was created. Auto generated | | `position` | `CursorPosition \| null` | No | Cursor position relative to the comment annotation | | `locationId` | `number \| null` | No | Unique location id generated from provided location | | `location` | `Location \| null` | No | Set location to identify user on sub document | | `type` | `string` | No | Type of the comment annotation | | `selectAllContent` | `boolean` | No | If true, sets text comment annotation on all the text content | | `approved` | `boolean` | No | Whether the comment annotation is approved | | `status` | `CustomStatus` | Yes | Status of the comment annotation. Default: CommentAnnotationStatusMap.OPEN | | `annotationIndex` | `number` | No | Index of current annotation in the list | | `annotationNumber` | `number` | No | Fixed annotation number that persists across sessions. Used for referencing specific comments | | `pageInfo` | `PageInfo` | No | Page information related to the comment annotation | | `assignedTo` | `User` | No | User to whom the comment annotation is assigned | | `priority` | `CustomPriority` | No | Priority level of the comment annotation | | `ghostComment` | `GhostComment \| null` | No | Placeholder for a non-existing comment | | `context` | `any` | No | Custom context data provided by the user | | `resolvedByUserId` | `string` | No | ID of the user who resolved the comment | | `resolvedByUser` | [`User`](#user) | No | User object who resolved the comment annotation | | `subscribedUsers` | `CommentAnnotationSubscribedUsers` | No | Users who explicitly subscribe to the comment | | `unsubscribedUsers` | `CommentAnnotationUnsubscribedUsers` | No | Users who explicitly unsubscribe to the comment | | `multiThreadAnnotationId` | `string` | No | ID of the multithread annotation group it belongs to, if created in multithread mode | | `isDraft` | `boolean` | No | Indicates if the comment annotation is in draft state | | `customList` | `CustomAnnotationDropdownItem[]` | No | Custom list of items for the comment annotation | | `targetElementId` | `string` | No | ID of the target element for the comment annotation if available | | `viewedBy` | [`Users[]`](#user) | No | List of users who have viewed/read this comment annotation | | `unread` | `boolean` | No | Whether the annotation is unread by current user | | `visibilityConfig` | [`CommentAnnotationVisibilityConfig`](#commentannotationvisibilityconfig) | No | Human-readable visibility configuration for the annotation. Contains type, organizationId, and userIds. Defaults to `{ type: 'public' }` for new annotations without explicit visibility. | #### Enum | Enum Name | Event Type | Description | | ------------------------------ | --------------------------- | --------------------------------------------------------------- | | `ADD_COMMENT_ANNOTATION` | `addCommentAnnotation` | Add a new comment annotation | | `ADD_COMMENT_ANNOTATION_DRAFT` | `addCommentAnnotationDraft` | Triggered when comment annotation draft is created | | `DELETE_COMMENT_ANNOTATION` | `deleteCommentAnnotation` | Delete a comment annotation | | `VISIBILITY_OPTION_CLICKED` | `visibilityOptionClicked` | Triggered when user selects a visibility option from the banner | | `COMMENT_SAVE_TRIGGERED` | `commentSaveTriggered` | Triggered when comment save is initiated | #### AddCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------------ | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `addContext` | `(context: any) => void` | Yes | Function to add custom metadata | | `elementRef` | `{ xpath: string }` | No | Reference to DOM element where comment annotation was added | #### AddCommentAnnotationDraftEvent *** | Property | Type | Required | Description | | ------------ | ---------------------------------------------------------- | -------- | --------------------------------------------- | | `addContext` | `(context:` [`CommentContext`](#commentcontext)`) => void` | No | Function to add context during draft creation | #### DeleteCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### CommentBubbleClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### CommentSavedEvent *** | Property | Type | Required | Description | | ------------------- | ----------------------------------------- | -------- | ----------------------------------- | | `annotationId` | `string` | Yes | ID of the saved annotation | | `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | The saved comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### VisibilityOptionClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation whose visibility was changed | | `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full annotation at the time of the visibility selection | | `visibility` | [`CommentVisibilityOptionType`](#commentvisibilityoptiontype) | Yes | Selected visibility level | | `users` | `any[]` | No | Populated only when `visibility === 'restricted'` | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### CommentSaveTriggeredEvent *** | Property | Type | Required | Description | | ------------------- | ----------------------------------------- | -------- | -------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation being saved | | `commentAnnotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full annotation at save time | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### CommentContext *** Custom context data for comment annotations. ```typescript theme={null} type CommentContext = any; ``` #### CommentContextProviderResponse *** Return type for context provider function. Can return context synchronously or asynchronously. ```typescript theme={null} type CommentContextProviderResponse = CommentContext | null | undefined; ``` #### CommentContextProvider *** Function type for providing context based on document and location. ```typescript theme={null} type CommentContextProvider = ( documentId: string, location?: Location, ) => CommentContextProviderResponse | Promise; ``` #### CommentVisibilityType *** Visibility level used by **API methods** such as [`updateVisibility()`](/api-reference/sdk/api/api-methods#updatevisibility) and [`enablePrivateMode()`](/api-reference/sdk/api/api-methods#enableprivatemode) via [`CommentVisibilityConfig`](#commentvisibilityconfig). ```typescript theme={null} type CommentVisibilityType = "public" | "organizationPrivate" | "restricted"; ``` | Value | Description | | ----------------------- | ----------------------------------------------------------- | | `'public'` | Comment visible to all users | | `'organizationPrivate'` | Comment visible only to users in the specified organization | | `'restricted'` | Comment visible only to specified users (private) | The visibility system uses two separate sets of values: - **API methods** use [`CommentVisibilityConfig`](#commentvisibilityconfig) with [`CommentVisibilityType`](#commentvisibilitytype) values: `'public'`, `'organizationPrivate'`, `'restricted'` (3 values — `'restricted'` covers both self-only and selected-people, distinguished by whether `userIds` is provided). - **UI wireframes** use the [`CommentVisibilityOption`](#commentvisibilityoption) enum with 4 values: `'restrictedSelf'`, `'restrictedSelectedPeople'`, `'organizationPrivate'`, `'public'`. These are the `type` prop values on visibility banner dropdown wireframe items. #### CommentVisibilityOption *** Enum for **UI wireframe** visibility levels, used as the `type` prop on visibility banner dropdown content items. These are more granular than the API-level [`CommentVisibilityType`](#commentvisibilitytype) — the API's single `'restricted'` value maps to two UI options (`'restrictedSelf'` and `'restrictedSelectedPeople'`). ```typescript theme={null} export declare enum CommentVisibilityOption { RESTRICTED_SELF = "restrictedSelf", RESTRICTED_SELECTED_PEOPLE = "restrictedSelectedPeople", ORGANIZATION_PRIVATE = "organizationPrivate", PUBLIC = "public", } ``` | Value | Description | API Equivalent | | ---------------------------- | ------------------------------------------- | ---------------------------------------------- | | `RESTRICTED_SELF` | Visible only to the comment author | `'restricted'` with `userIds: [currentUserId]` | | `RESTRICTED_SELECTED_PEOPLE` | Visible only to specifically selected users | `'restricted'` with `userIds: [...]` | | `ORGANIZATION_PRIVATE` | Visible to users in the organization | `'organizationPrivate'` | | `PUBLIC` | Visible to all users | `'public'` | #### CommentVisibilityOptionType *** String union type derived from [`CommentVisibilityOption`](#commentvisibilityoption) enum values. Used in UI wireframe components. ```typescript theme={null} export type CommentVisibilityOptionType = `${CommentVisibilityOption}`; // = 'restrictedSelf' | 'restrictedSelectedPeople' | 'organizationPrivate' | 'public' ``` #### CommentVisibilityConfig *** Configuration object for **API methods** that update comment visibility. Uses [`CommentVisibilityType`](#commentvisibilitytype) values — not [`CommentVisibilityOption`](#commentvisibilityoption) values. | Property | Type | Required | Description | | ---------------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | Visibility level: `'public'`, `'organizationPrivate'`, or `'restricted'`. | | `annotationId` | `string` | Yes | Annotation ID of the comment to update visibility. | | `organizationId` | `string` | No | Organization ID. Required when `type` is `'organizationPrivate'`. | | `userIds` | `string[]` | No | User IDs who can see the comment. Used when `type` is `'restricted'`. The current user is automatically appended if not present. | #### PrivateModeConfig *** Configuration for enabling private mode via **API methods**. Subset of [`CommentVisibilityConfig`](#commentvisibilityconfig) — excludes `annotationId` and `organizationId`. Uses [`CommentVisibilityType`](#commentvisibilitytype) values. ```typescript theme={null} type PrivateModeConfig = Omit< CommentVisibilityConfig, "annotationId" | "organizationId" >; ``` | Property | Type | Required | Description | | --------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | Visibility level applied when private mode is active. | | `userIds` | `string[]` | No | User IDs who can see comments. Used when `type` is `'restricted'`. The current user is automatically appended if not present. | #### CommentAnnotationVisibilityConfig *** Human-readable visibility configuration stored on a comment annotation. | Property | Type | Required | Description | | ---------------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- | | `type` | [`CommentVisibilityType`](#commentvisibilitytype) | Yes | The visibility type for the comment annotation. | | `organizationId` | `string` | No | The organization ID for organization-private visibility. | | `userIds` | `string[]` | No | The user IDs for restricted visibility. Always includes the current user when type is `'restricted'`. | #### CommentAnnotationSubscribedUsers *** | Property | Type | Required | Description | | ------------ | -------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userIdHash` | `string` | Yes | The user ID of the subscribed user | | `user` | `User` | Yes | The user object of the subscribed user | | `type` | `'manual' \| 'auto'` | Yes | Manual: if the user used the UI option to subscribe; Auto: When the system automatically adds the user to the subscribed list. eg: when the user creates a comment annotation | #### CommentAnnotationUnsubscribedUsers *** | Property | Type | Required | Description | | ------------ | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userIdHash` | `string` | Yes | The user ID of the unsubscribed user | | `user` | `User` | Yes | The user object of the unsubscribed user | | `type` | `'manual' \| 'auto'` | Yes | Manual: if the user used the UI option to unsubscribe; Auto: When the system automatically removes the user from the unsubscribed list. eg: when the comment where user was tagged is deleted | #### AddCommentAnnotationRequest *** | Property | Type | Required | Description | | ------------ | ------------------- | -------- | ------------------ | | `annotation` | `CommentAnnotation` | Yes | Comment annotation | | `options` | `RequestOptions` | No | Request options | #### DeleteCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### SubmitCommentRequest *** | Property | Type | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------- | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to submit | #### ClearComposerRequest *** | Property | Type | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------ | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to clear | #### GetComposerDataRequest *** | Property | Type | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------ | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer to query | #### PageModeComposerConfig *** | Property | Type | Required | Description | | ----------------- | -------------------------------- | -------- | --------------------------------------------------------------------- | | `context` | `{ [key: string]: any } \| null` | No | Custom context data for page mode composer | | `targetElementId` | `string \| null` | No | Target element ID to bind with comment annotation | | `clearContext` | `boolean` | No | When `false`, preserves context after submission. Defaults to `true`. | #### AssignToConfig *** | Property | Type | Required | Description | | -------- | -------------------------- | -------- | ------------------------------------------------------------------- | | `type` | `'dropdown' \| 'checkbox'` | Yes | Assignment UI mode: dropdown for menu, checkbox for self-assignment | #### FormatConfig *** Configuration for text formatting toolbar options in comment composers. | Property | Type | Required | Description | | --------------- | --------------------- | -------- | ------------------------------------------------- | | `bold` | `{ enable: boolean }` | No | Enable or disable bold formatting option | | `italic` | `{ enable: boolean }` | No | Enable or disable italic formatting option | | `underline` | `{ enable: boolean }` | No | Enable or disable underline formatting option | | `strikethrough` | `{ enable: boolean }` | No | Enable or disable strikethrough formatting option | #### CommentRequestQuery *** | Property | Type | Required | Description | | --------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- | | `organizationId` | `string` | No | Organization ID to filter comment annotations by organization | | `documentIds` | `string[]` | No | Array of document IDs to query. | | `locationIds` | `string[]` | No | Array of location IDs to filter by | | `statusIds` | `string[]` | No | Array of status IDs to filter by | | `folderId` | `string` | No | Folder ID to filter comment annotations by folder | | `allDocuments` | `boolean` | No | If true, includes all documents in the query | | `locationId` | `string` | No | Single location ID to filter by (alternative to `locationIds`) | | `aggregateDocuments` | `boolean` | No | If true, aggregates comment annotation counts across multiple documents | | `filterGhostComments` | `boolean` | No | If true, excludes ghost (deleted or orphaned) comments from the results | | `batchedPerDocument` | `boolean` | No | Enable batched listener for large document lists (50+ docs) | | `debounceMs` | `number` | No | Debounce delay for auto-batching updates in milliseconds (default: 5000ms) | | `agentFields` | `string[]` | No | Filters queries to annotations where `agent.agentFields` contains any provided value; when set, unread count equals total count | #### GetCommentAnnotationsCountResponse *** | Property | Type | Required | Description | | -------- | ------------------------------------------------- | -------- | --------------------------------------------------------------- | | `data` | `Record \| null` | Yes | Map of document IDs to their comment counts. Null while loading | #### GetCommentAnnotationsResponse *** | Property | Type | Required | Description | | -------- | --------------------------------------------- | -------- | ------------------------------------------------------------ | | `data` | `Record \| null` | Yes | Map of document IDs to their annotations. Null while loading | #### FetchCommentAnnotationsRequest *** | Property | Type | Required | Description | | ------------------ | ----------------- | -------- | -------------------------------------------------------------- | | `createdAfter` | `number` | No | Filter annotations created after this timestamp | | `createdBefore` | `number` | No | Filter annotations created before this timestamp | | `updatedAfter` | `number` | No | Filter annotations updated after this timestamp | | `updatedBefore` | `number` | No | Filter annotations updated before this timestamp | | `statusIds` | `string[]` | No | Filter annotations by status IDs | | `order` | `'asc' \| 'desc'` | No | Sort order for annotations | | `pageToken` | `string` | No | Token for fetching next page of results | | `allDocuments` | `boolean` | No | Whether to fetch annotations from all documents | | `pageSize` | `number` | No | Number of results per page | | `organizationId` | `string` | No | Organization ID to fetch annotations from | | `locationId` | `string` | No | Location ID to filter annotations by | | `documentIds` | `string[]` | No | Array of specific document IDs to fetch from | | `folderId` | `string` | No | Folder ID to fetch annotations from | | `resolvedBy` | `string` | No | Filter comments by user who resolved the comment | | `userIds` | `string[]` | No | Filter comments by comment annotation author | | `mentionedUserIds` | `string[]` | No | Filter comments where provided users are tagged in the comment | #### FetchCommentAnnotationsResponse *** | Property | Type | Required | Description | | --------------- | --------------------------------------------- | -------- | -------------------------------------------------------------- | | `data` | `Record \| null` | Yes | Map of document IDs to their annotations. `Null` while loading | | `nextPageToken` | `string` | Yes | Token for fetching next page of results | #### GetCommentResolverRequest *** | Property | Type | Required | Description | | ---------------------- | ---------- | -------- | -------------------------------------------------------------------- | | `organizationId` | `string` | Yes | Organization ID to fetch comments from | | `commentAnnotationIds` | `string[]` | No | Array of comment annotation IDs to fetch comments from | | `documentIds` | `string[]` | No | Array of document IDs to fetch comments from | | `folderId` | `string` | No | Folder ID to fetch comments from | | `allDocuments` | `boolean` | No | Whether to fetch comments from all documents within the given folder | #### SaveCommentResolverRequest *** | Property | Type | Required | Description | | ------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------- | | `commentAnnotation` | `{ [key: string]: PartialCommentAnnotation }` | Yes | Map of comment annotation data to save | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | `ResolverActions` | No | Event name that caused the save request | | `commentId` | `string` | No | ID of the comment to save | #### DeleteCommentResolverRequest *** | Property | Type | Required | Description | | --------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- | | `commentAnnotationId` | `string` | Yes | ID of the comment annotation to delete | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | `ResolverActions` | No | Event name that caused the delete request | #### CustomAnnotationDropdownData *** | Property | Type | Required | Description | | ------------- | -------------------------------- | -------- | ----------------------------------------------------------- | | `type` | `'multi' \| 'single'` | Yes | The type of the custom annotation dropdown | | `placeholder` | `string` | Yes | The placeholder text for the dropdown. Defaults to 'Select' | | `data` | `CustomAnnotationDropdownItem[]` | Yes | An array of dropdown items | #### CustomAnnotationDropdownItem *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------- | | `id` | `string` | Yes | The unique identifier for the dropdown item | | `label` | `string` | Yes | The display text for the dropdown item | #### GetCommentAnnotationsResponse *** | Property | Type | Required | Description | | -------- | ------------------------------------- | -------- | ------------------------------------------------ | | `data` | `Record` | Yes | Map of document IDs to their comment annotations | #### CommentAnnotationsCount *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------- | | `unread` | `number` | Yes | Number of unread comments | | `total` | `number` | Yes | Total number of comments | #### GetCommentAnnotationsCountResponse *** | Property | Type | Required | Description | | -------- | ----------------------------------------- | -------- | ------------------------------------------- | | `data` | `Record` | Yes | Map of document IDs to their comment counts | ### Slate #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | Slate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `unknown` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | Slate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### VeltCommentsElement *** Slate element type representing a comment with optional annotation ID. | Property | Type | Required | Description | | -------------- | --------------- | -------- | ---------------------------------------- | | `type` | `'veltComment'` | Yes | Discriminator for Velt comment elements. | | `children` | `Descendant[]` | Yes | Slate child nodes. | | `annotationId` | `string` | No | Associated CommentAnnotation ID. | ### Tiptap #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | Tiptap editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | Tiptap editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### TiptapVeltCommentsOptions *** | Property | Type | Required | Description | | ------------------ | --------------------- | -------- | ------------------------------------------------------------ | | `HTMLAttributes` | `Record` | No | Attributes applied to rendered comment nodes/marks. | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks across edits. Default: `true`. | | `editorId` | `string` | No | ID to scope Velt operations to a specific editor instance. | #### CommentAnnotationContext *** Context object for comment annotations. Contains text editor configuration and any additional custom metadata. | Property | Type | Required | Description | | ------------------ | ------------------ | -------- | ---------------------------------------------------------- | | `textEditorConfig` | `TextEditorConfig` | No | Text editor configuration (auto-generated by the library). | | `[key: string]` | `unknown` | No | Any additional custom properties you want to attach. | #### TextEditorConfig *** Nested in `CommentAnnotationContext`. | Property | Type | Required | Description | | ------------------ | -------- | -------- | ------------------------------------------------- | | `text` | `string` | Yes | The selected text content. | | `occurrence` | `number` | Yes | The occurrence index of the text in the document. | | `editorId` | `string` | No | The editor ID associated with this comment. | | `targetTextNodeId` | `string` | No | ID of the target text node container. | ### Lexical #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ---------------------------------------------------- | | `editor` | `Editor` | Yes | Lexical editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `unknown` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Editor` | Yes | Lexical editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### CommentNode *** Inline Lexical element representing a comment with optional annotation IDs. | Property | Type | Required | Description | | ------------------------- | ------------------------- | -------- | --------------------------------------------------- | | `type` | `'comment'` | Yes | Discriminator for Velt comment nodes. | | `children` | `SerializedLexicalNode[]` | Yes | Lexical child nodes (from `SerializedElementNode`). | | `annotationId` | `string` | No | Associated `CommentAnnotation` ID. | | `multiThreadAnnotationId` | `string` | No | Associated multi-thread annotation ID. | ### Plate #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `PlateEditor` | Yes | Plate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `PlateEditor` | Yes | Plate editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### VeltCommentsPluginConfig *** | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | #### VeltCommentsElement *** Plate element type representing a comment with optional annotation IDs. | Property | Type | Required | Description | | ------------------------- | --------------- | -------- | ----------------------------------------- | | `type` | `'veltComment'` | Yes | Element type identifier. | | `children` | `Descendant[]` | Yes | Child nodes (text content). | | `annotationId` | `string` | No | The Velt annotation ID. | | `multiThreadAnnotationId` | `string` | No | Multi-thread annotation ID if applicable. | ### CodeMirror #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `EditorView` | Yes | CodeMirror EditorView instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `EditorView` | Yes | CodeMirror EditorView instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### CodemirrorVeltCommentsConfig *** Configuration options for the `CodemirrorVeltComments()` extension. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | ### Ace #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Ace.Editor` | Yes | Ace Editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Ace.Editor` | Yes | Ace Editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### AceVeltCommentsConfig *** Configuration options for the `AceVeltComments()` function. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | ### Quill #### AddCommentRequest *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | ---------------------------------------------------- | | `editor` | `Quill` | Yes | Quill editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `context` | `CommentAnnotationContext` | No | Optional custom context to attach to the annotation. | #### RenderCommentsRequest *** | Property | Type | Required | Description | | -------------------- | --------------------- | -------- | -------------------------------------------- | | `editor` | `Quill` | Yes | Quill editor instance. | | `editorId` | `string` | No | Optional editor ID used to scope operations. | | `commentAnnotations` | `CommentAnnotation[]` | No | Annotations to render/highlight. | For the CommentAnnotation model referenced above, see [CommentAnnotation](#commentannotation). #### QuillVeltCommentsConfig *** Configuration options for the `QuillVeltComments` module. | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `editorId` | `string` | No | Unique identifier for this editor instance (for multi-editor scenarios). | | `persistVeltMarks` | `boolean` | No | Whether to persist Velt marks in the document. Default: `true`. | ### Messages #### ENUMs | Enum Name | Event Type | Description | | ---------------- | --------------- | -------------------------- | | `ADD_COMMENT` | `addComment` | Add a new comment | | `UPDATE_COMMENT` | `updateComment` | Update an existing comment | | `DELETE_COMMENT` | `deleteComment` | Delete a comment | #### Comment *** | Property | Type | Required | Description | | ----------------------- | -------------------------------------- | -------- | ----------------------------------------------------------------------- | | `commentId` | `number` | Yes | Unique identifier for the comment pin annotation. Auto generated. | | `type` | `'text' \| 'voice'` | Yes | This determines the comment content type. Default is 'text'. | | `commentText` | `string` | Yes | The actual text content of the comment. | | `commentHtml` | `string` | No | Same comment text but formatted in HTML. | | `replaceContentHtml` | `string` | No | HTML content to replace the comment text when user accepts the comment. | | `replaceContentText` | `string` | No | Text content to replace the comment text when user accepts the comment. | | `commentVoiceUrl` | `string` | No | URL of the voice recording for the comment, if available. | | `from` | `User` | Yes | The user who created this comment. | | `to` | `User[]` | No | List of users that were @mentioned in this comment. | | `lastUpdated` | `Date` | No | Timestamp of when this comment was last updated. Auto generated. | | `editedAt` | `any` | No | Timestamp of when this comment was edited. Auto generated. | | `createdAt` | `any` | No | Timestamp of when this comment was created. Auto generated. | | `isEdited` | `boolean` | No | Whether the comment has been edited. Auto generated. | | `status` | `'added' \| 'updated'` | Yes | Status of the comment indicating whether it was newly added or updated. | | `attachments` | `Attachment[]` | Yes | List of attachments associated with the comment. | | `recorders` | `RecordedData[]` | Yes | List of recorded data associated with the comment. | | `reactionAnnotationIds` | `string[]` | Yes | List of annotation IDs for reactions to the comment. | | `reactionAnnotations` | \[`ReactionAnnotation[]`] | No | List of reaction annotations associated with the comment. | | `taggedUserContacts` | `AutocompleteUserContactReplaceData[]` | Yes | List of users that were @mentioned in this comment with UI metadata. | | `customList` | `AutocompleteReplaceData[]` | Yes | List of custom list items added to the comment. | | `isDraft` | `boolean` | Yes | Whether the comment is in draft state. | #### AddCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `comment` | `Comment` | Yes | Comment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UpdateCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `comment` | `Comment` | Yes | Comment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### DeleteCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `comment` | `Comment` | Yes | Comment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AddCommentRequest *** | Property | Type | Required | Description | | -------------- | ----------------------------------------------------- | -------- | --------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `comment` | `Comment` | Yes | Comment object | | `assignedTo` | `User` | No | Assigned user | | `assigned` | `boolean` | No | Whether the comment is assigned | | `visibility` | [`CommentVisibilityConfig`](#commentvisibilityconfig) | No | Set visibility at comment creation time | | `options` | `RequestOptions` | No | Request options | #### UpdateCommentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `comment` | `Comment` | Yes | Comment object | | `merge` | `boolean` | No | Merge comments | | `options` | `RequestOptions` | No | Request options | #### DeleteCommentRequest *** | Property | Type | Required | Description | | ------------------------------ | ---------------- | -------- | ------------------------ | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `skipDeleteThreadConfirmation` | `boolean` | No | Skip delete confirmation | | `options` | `RequestOptions` | No | Request options | #### GetCommentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | ### @Mentions #### ENUMs | Enum Name | Event Type | Description | | -------------------------------- | ------------------------------ | ------------------------------------------------------------------ | | `ASSIGN_USER` | `assignUser` | Assign a user to a comment | | `SUBSCRIBE_COMMENT_ANNOTATION` | `subscribeCommentAnnotation` | Subscribe to a comment annotation | | `UNSUBSCRIBE_COMMENT_ANNOTATION` | `unsubscribeCommentAnnotation` | Unsubscribe from a comment annotation | | `AUTOCOMPLETE_SEARCH` | `autocompleteSearch` | When user starts searching for a contact in the @mentions dropdown | #### AssignUserRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `assignedTo` | `UserContact` | Yes | User to assign | | `options` | `RequestOptions` | No | Request options | #### GetContactListResponse *** | Property | Type | Required | Description | | -------------------- | ------------- | -------- | -------------------------------------------------- | | `organizationUsers` | `User[]` | No | List of users in the organization | | `folderUsers` | `User[]` | No | List of users added to the folder | | `documentUsers` | `User[]` | No | List of users added to the document | | `userGroups` | `UserGroup[]` | No | List of user groups in the organization | | `updatedContactList` | `User[]` | No | List of contacts updated via updateContactList API | #### SubscribeCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### UnsubscribeCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### AutocompleteItem *** | Property | Type | Required | Description | | ------------- | -------- | -------- | ------------------------- | | `id` | `string` | Yes | Unique identifier | | `name` | `string` | Yes | Name of the item | | `description` | `string` | No | Optional description | | `icon` | `object` | No | Optional icon information | | `icon.url` | `string` | No | URL of the icon | | `link` | `string` | No | Link associated with item | #### AutocompleteUserContactReplaceData *** | Property | Type | Required | Description | | --------- | -------- | -------- | ----------------------------------------------------------------- | | `text` | `string` | Yes | The text displayed in the comment that represents the tagged user | | `userId` | `string` | Yes | The user ID of the tagged user | | `contact` | `User` | No | The user object of the tagged user | #### AutocompleteReplaceData *** | Property | Type | Required | Description | | -------- | ------------------ | -------- | ----------------------------------------------------------------- | | `text` | `string` | Yes | The text displayed in the comment that represents the custom item | | `custom` | `AutocompleteItem` | Yes | The custom item object associated with this text | #### AutocompleteItem *** | Property | Type | Required | Description | | ------------- | -------------------------------- | -------- | -------------------------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the autocomplete item | | `name` | `string` | Yes | Name or label of the autocomplete item | | `description` | `string` | No | Additional description of the autocomplete item | | `icon` | `{ url?: string, svg?: string }` | No | Icon associated with the autocomplete item (URL or inline SVG) | | `groupId` | `string` | No | Optional group id to categorize this item | | `link` | `string` | No | Optional link associated with the autocomplete item | #### AutocompleteData *** | Property | Type | Required | Description | | ------------- | ---------------------------------- | -------- | -------------------------------------------------- | | `hotkey` | `string` | Yes | The hotkey or trigger for this autocomplete data | | `description` | `string` | No | Optional description of the autocomplete data | | `type` | `'custom' \| 'contact' \| 'group'` | Yes | The type of autocomplete data. Default is 'custom' | | `groups` | `AutocompleteGroup[]` | No | Optional groups used to categorize items | | `data` | `AutocompleteItem[]` | Yes | An array of AutocompleteItem objects | #### AutocompleteGroup *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------- | | `id` | `string` | Yes | Unique group id | | `name` | `string` | Yes | Display name of group | #### AutoCompleteScrollConfig *** Configuration for virtual scroll behavior in autocomplete dropdown. | Property | Type | Required | Description | | ------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `itemSize` | `number` | No | Specifies the fixed height of each item in pixels | | `minBufferPx` | `number` | No | The minimum amount of content buffer (in pixels) that must be rendered beyond the visible viewport. If the buffer falls below this amount, the viewport will render more items | | `maxBufferPx` | `number` | No | The maximum amount of content buffer (in pixels) to render when the `minBufferPx` threshold is crossed. The viewport renders items until the buffer reaches this size | | `templateCacheSize` | `number` | No | Adjusts the size of the view cache. By default, previously created views are cached for reuse; setting this to `0` disables caching, which can be useful if your templates are memory-intensive | #### AssignUserEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `assignedTo` | `UserContact` | Yes | User being assigned | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### SubscribeCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UnsubscribeCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AutocompleteSearchEvent *** | Property | Type | Required | Description | | ------------ | -------------------------------------- | -------- | -------------------------------------------------------------------- | | `event` | `KeyboardEvent \| InputEvent \| Event` | Yes | The triggering event | | `searchText` | `string` | Yes | The search text entered | | `type` | `'contact' \| 'custom'` | No | Type of autocomplete search. Whether is the @mentions or custom list | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### LinkClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | -------------------------------- | | `text` | `string` | Yes | The clicked link text | | `link` | `string` | Yes | The clicked URL | | `commentAnnotation` | `CommentAnnotation` | Yes | Related comment annotation | | `commentId` | `number` | Yes | The comment id within the thread | | `metadata` | `VeltEventMetadata` | No | Event metadata | ### Custom List #### ENUMs | Enum Name | Event Type | Description | | --------------------- | -------------------- | ---------------------------------------------------------------------- | | `AUTOCOMPLETE_SEARCH` | `autocompleteSearch` | When user starts searching for a list item in the custom list dropdown | #### AutocompleteSearchEvent *** | Property | Type | Required | Description | | ------------ | -------------------------------------- | -------- | -------------------------------------------------------------------- | | `event` | `KeyboardEvent \| InputEvent \| Event` | Yes | The triggering event | | `searchText` | `string` | Yes | The search text entered | | `type` | `'contact' \| 'custom'` | No | Type of autocomplete search. Whether is the @mentions or custom list | | `metadata` | `VeltEventMetadata` | No | Event metadata | ### Attachments #### ENUMs | Enum Name | Event Type | Description | | ----------------------------- | --------------------------- | ---------------------------------------------------- | | `ADD_ATTACHMENT` | `addAttachment` | Add an attachment to a comment | | `DELETE_ATTACHMENT` | `deleteAttachment` | Delete an attachment from a comment | | `ATTACHMENT_DOWNLOAD_CLICKED` | `attachmentDownloadClicked` | Triggered when attachment download button is clicked | #### Attachment *** | Property | Type | Required | Description | | -------------------------- | -------- | -------- | ---------------------------------------------------- | | `attachmentId` | `number` | Yes | Unique identifier for the attachment. Auto-generated | | `name` | `string` | No | File name of the attachment | | `bucketPath` | `string` | No | Path to the file in storage bucket | | `size` | `number` | No | File size of the attachment | | `type` | `string` | No | File type of the attachment | | `url` | `string` | No | Download URL of the attachment | | `thumbnail` | `string` | No | Thumbnail image in base64 format | | `thumbnailWithPlayIconUrl` | `string` | No | URL of the thumbnail with a play icon overlay | | `metadata` | `any` | No | Additional metadata of the attachment | | `mimeType` | `any` | No | MIME type of the attachment | #### AddAttachmentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `files` | `File[]` | Yes | Array of files | | `options` | `RequestOptions` | No | Request options | #### DeleteAttachmentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `attachmentId` | `number` | Yes | ID of the attachment | | `options` | `RequestOptions` | No | Request options | #### GetAttachmentRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `options` | `RequestOptions` | No | Request options | #### UploadFileData *** Configuration object for programmatically adding file attachments to the comment composer. | Property | Type | Required | Description | | ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `files` | `File[]` | Yes | Array of File objects to attach to the comment composer | | `annotationId` | `string` | No | ID of the target comment annotation. Use this to add attachments to an existing comment thread | | `targetElementId` | `string` | No | ID of the target element where the comment composer is attached. Use this to add attachments to a specific element | #### AddAttachmentResponse *** | Property | Type | Required | Description | | ---------------- | ------------ | -------- | ----------------- | | `valid` | `boolean` | Yes | Validity status | | `file` | `File` | No | File object | | `maxAllowedSize` | `number` | Yes | Max allowed size | | `error` | `string` | No | Error message | | `attachment` | `Attachment` | No | Attachment object | #### DeleteAttachmentResolverRequest *** | Property | Type | Required | Description | | -------------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `attachmentId` | `number` | Yes | ID of the attachment | | `metadata` | `AttachmentResolverMetadata` | No | Metadata for the request. Contains only: `apiKey`, `documentId`, `organizationId`, and `folderId` (when present). Internal fields are stripped (v5.0.2-beta.11+). | | `event` | `ResolverActions` | No | Event that triggered the delete | #### SaveAttachmentResolverRequest *** | Property | Type | Required | Description | | ------------ | ---------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `attachment` | `ResolverAttachment` | Yes | Attachment object to save | | `metadata` | `AttachmentResolverMetadata` | No | Metadata for the request. Contains: `apiKey`, `documentId`, `organizationId`, `folderId` (when present), `attachmentId`, and `commentAnnotationId`. | | `event` | `ResolverActions` | No | Event that triggered the save | #### AddAttachmentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `attachments` | `AddAttachmentResponse[]` | Yes | Array of attachment responses | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AddAttachmentResponse *** | Property | Type | Required | Description | | ---------------- | ------------ | -------- | --------------------------- | | `valid` | `boolean` | Yes | Whether attachment is valid | | `file` | `File` | No | File object | | `maxAllowedSize` | `number` | Yes | Maximum allowed file size | | `error` | `string` | No | Error message if invalid | | `attachment` | `Attachment` | No | Attachment object | #### DeleteAttachmentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `attachment` | `Attachment` | Yes | Attachment Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AttachmentDownloadClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------------- | | `annotationId` | `string` | Yes | ID of the comment annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Full comment annotation object | | `attachment` | `Attachment` | Yes | The attachment that was clicked | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | ### Reactions #### ENUMs | Enum Name | Event Type | Description | | ----------------- | ---------------- | -------------------------------- | | `ADD_REACTION` | `addReaction` | Add a reaction to a comment | | `DELETE_REACTION` | `deleteReaction` | Delete a reaction from a comment | | `TOGGLE_REACTION` | `toggleReaction` | Toggle a reaction on a comment | #### AddReactionRequest *** | Property | Type | Required | Description | | -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction | | `options` | `RequestOptions` | No | Request options | #### DeleteReactionRequest *** | Property | Type | Required | Description | | -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction | | `options` | `RequestOptions` | No | Request options | #### ToggleReactionRequest *** | Property | Type | Required | Description | | -------------- | -------------------------------------------------------- | -------- | ----------------------------------------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `{ reactionId: string; customReaction?: ReactionItem; }` | Yes | Reaction object with reactionId and optional customReaction | | `options` | `RequestOptions` | No | Request options | #### ReactionItem *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------- | | `url` | `string` | No | URL of the reaction image | | `emoji` | `string` | No | Emoji character | #### GetReactionResolverRequest *** | Property | Type | Required | Description | | ----------------------- | ---------- | -------- | ------------------------------------------------------------------- | | `organizationId` | `string` | Yes | ID of the organization to fetch reactions from | | `reactionAnnotationIds` | `string[]` | No | Array of reaction annotation IDs to fetch reactions from | | `documentIds` | `string[]` | No | Array of document IDs to fetch reactions from | | `folderId` | `string` | No | ID of the folder to fetch reactions from | | `allDocuments` | `boolean` | No | Whether to get reactions from all documents within the given folder | #### SaveReactionResolverRequest *** | Property | Type | Required | Description | | -------------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------- | | `reactionAnnotation` | `{ [key: string]: PartialReactionAnnotation }` | Yes | Map of reaction annotation id to reaction annotation data | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | `ResolverActions` | No | Event name that caused the save request | #### DeleteReactionResolverRequest *** | Property | Type | Required | Description | | ---------------------- | ----------------- | -------- | --------------------------------------------------------------------------------- | | `reactionAnnotationId` | `string` | Yes | ID of the reaction annotation | | `metadata` | `BaseMetadata` | No | Additional metadata for the request. eg: apikey, organizationId, documentId, etc. | | `event` | `ResolverActions` | No | Event name that caused the delete request | #### AddReactionEvent *** | Property | Type | Required | Description | | ------------------- | -------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `ReactionAnnotation` | Yes | Reaction Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### DeleteReactionEvent *** | Property | Type | Required | Description | | ------------------- | -------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `ReactionAnnotation` | Yes | Reaction Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ToggleReactionEvent *** | Property | Type | Required | Description | | ------------------- | -------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `reaction` | `ReactionAnnotation` | Yes | Reaction Object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ReactionPinType *** Display location for pinned reactions. ```typescript theme={null} type ReactionPinType = "timeline" | "comment" | "standalone"; ``` * `'timeline'`: Pin reaction to timeline view * `'comment'`: Pin reaction to comment context * `'standalone'`: Display reaction independently ### Status & Priority #### ENUMs | Enum Name | Event Type | Description | | ---------------------------- | -------------------------- | -------------------------------- | | `UPDATE_STATUS` | `updateStatus` | Update the status of a comment | | `RESOLVE_COMMENT` | `resolveComment` | Resolve a comment | | `UPDATE_PRIORITY` | `updatePriority` | Update the priority of a comment | | `APPROVE_COMMENT_ANNOTATION` | `approveCommentAnnotation` | Approve a comment annotation | | `ACCEPT_COMMENT_ANNOTATION` | `acceptCommentAnnotation` | Accept a comment annotation | | `REJECT_COMMENT_ANNOTATION` | `rejectCommentAnnotation` | Reject a comment annotation | #### UpdateStatusRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `status` | `CustomStatus` | Yes | Status value | | `options` | `RequestOptions` | No | Request options | #### ResolveCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### UpdatePriorityRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `priority` | `CustomPriority` | No | Priority object | | `options` | `RequestOptions` | No | Request options | #### ApproveCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### AcceptCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### RejectCommentAnnotationRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### CustomPriority *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom priority | | `color` | `string` | Yes | Color associated with the custom priority | | `name` | `string` | Yes | Name or label of the custom priority | | `lightColor` | `string` | No | Light color variant for the custom priority | #### CustomStatus *** | Property | Type | Required | Description | | ------------ | ------------ | -------- | -------------------------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom status | | `color` | `string` | Yes | Text and comment pin color associated with the custom status | | `name` | `string` | Yes | Name or label of the custom status | | `type` | `StatusType` | Yes | Type of the status (`default`, `ongoing`, or `terminal`) | | `lightColor` | `string` | No | Background color on the status indicator for the custom status | | `iconUrl` | `string` | No | URL to an icon image for the custom status | #### UpdateStatusEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `newStatus` | `CustomStatus` | Yes | New status object | | `oldStatus` | `CustomStatus` | Yes | Previous status object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ResolveCommentEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UpdatePriorityEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `newPriority` | `CustomPriority` | No | New Priority object | | `oldPriority` | `CustomPriority` | No | Previous Priority object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ApproveCommentAnnotationEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### AcceptCommentAnnotationEvent *** | Property | Type | Required | Description | | -------------------- | ------------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `actionUser` | `User` | Yes | User who performed the action | | `replaceContentHtml` | `string` | No | HTML content to replace with | | `replaceContentText` | `string` | No | Text content to replace with | #### RejectCommentAnnotationEvent *** | Property | Type | Required | Description | | -------------------- | ------------------- | -------- | ----------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `actionUser` | `User` | Yes | User who performed the action | | `replaceContentHtml` | `string` | No | HTML content to replace with | | `replaceContentText` | `string` | No | Text content to replace with | ### Comment Dialog Primitives Types for the 92+ primitive components used to build custom comment dialog interfaces. See [Comment Dialog Primitives Overview](/ui-customization/features/async/comments/comment-dialog/primitives) for usage examples and [API Methods](/api-reference/sdk/api/api-methods#comment-dialog-primitives) for component documentation. #### CommentDialogCommonProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#common-inputs) Base props inherited by all Comment Dialog primitive components. | Property | Type | Required | Description | | -------------------------- | --------- | -------- | -------------------------------------------------- | | `annotationId` | `string` | No | Annotation ID (required in standalone mode) | | `defaultCondition` | `boolean` | No | When false, always shows component (default: true) | | `inlineCommentSectionMode` | `boolean` | No | Enables inline comment section mode | | `commentPinSelected` | `boolean` | No | Comment pin selection state | | `fullExpanded` | `boolean` | No | Full expansion state | #### CommentDialogContextWrapperProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcontextwrapper) Props for the VeltCommentDialogContextWrapper component. | Property | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------ | | `annotationId` | `string` | Yes | Annotation ID for children | | `commentId` | `string` | No | Comment ID for children | | `attachmentId` | `string` | No | Attachment ID for children | | `commentPinSelected` | `boolean` | No | Selection state for children | | `[key: string]` | `any` | No | Custom attributes passed via context | #### ThreadCardProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcard) Props for VeltCommentDialogThreadCard with priority-based comment lookup. | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------ | | `commentObj` | `object` | No | Direct comment object (Priority 1) | | `commentId` | `number` | No | Comment ID for lookup (Priority 2) | | `commentIndex` | `number` | No | Index in comments array (Priority 3) | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### CommentIndexProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogthreadcardavatar) Props for thread card sub-components that require a comment index. | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------- | | `commentIndex` | `number` | No | Index of comment in array | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### ComposerProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposer) Props for VeltCommentDialogComposer with placeholder and edit mode options. | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ----------------------------------------------------------------- | | `placeholder` | `string` | No | Primary placeholder (Priority 1) | | `commentPlaceholder` | `string` | No | Placeholder for new comment | | `replyPlaceholder` | `string` | No | Placeholder for reply | | `editPlaceholder` | `string` | No | Placeholder for edit mode | | `editMode` | `boolean` | No | Enables edit mode | | `commentObj` | `object` | No | Comment object for edit mode | | `commentIndex` | `number` | No | Index of comment being edited | | `targetComposerElementId` | `string` | No | Unique identifier for programmatic submission via submitComment() | | `context` | `object` | No | Custom context data to attach to comment | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### ComposerInputProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcomposerinput) Props for VeltCommentDialogComposerInput. | Property | Type | Required | Description | | ------------- | -------- | -------- | ---------------------- | | `placeholder` | `string` | No | Input placeholder text | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### StatusDropdownItemProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogstatusdropdowncontentitem) Props for VeltCommentDialogStatusDropdownContentItem with priority-based status lookup. | Property | Type | Required | Description | | ------------- | -------- | -------- | ------------------------------------ | | `statusObj` | `object` | No | Direct status object (Priority 1) | | `statusId` | `string` | No | Status ID for lookup (Priority 2) | | `statusIndex` | `number` | No | Index in statuses array (Priority 3) | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### PriorityDropdownItemProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogprioritydropdowncontentitem) Props for VeltCommentDialogPriorityDropdownContentItem with priority-based priority lookup. | Property | Type | Required | Description | | --------------- | -------- | -------- | -------------------------------------- | | `priorityObj` | `object` | No | Direct priority object (Priority 1) | | `priorityId` | `string` | No | Priority ID for lookup (Priority 2) | | `priorityIndex` | `number` | No | Index in priorities array (Priority 3) | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### OptionsDropdownProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogoptionsdropdown) Props for VeltCommentDialogOptionsDropdown with feature enable flags. | Property | Type | Required | Description | | ------------------------------ | --------- | -------- | -------------------------------- | | `commentIndex` | `number` | No | Index of comment for options | | `enableAssignment` | `boolean` | No | Enable assignment option | | `allowAssignment` | `boolean` | No | V4 alias for enableAssignment | | `enableEdit` | `boolean` | No | Enable edit option | | `allowEdit` | `boolean` | No | V4 alias for enableEdit | | `enableNotifications` | `boolean` | No | Enable notifications option | | `allowNotifications` | `boolean` | No | V4 alias for enableNotifications | | `allowToggleNotification` | `boolean` | No | V4 alias for enableNotifications | | `enablePrivateMode` | `boolean` | No | Enable private mode option | | `allowPrivateMode` | `boolean` | No | V4 alias for enablePrivateMode | | `allowChangeCommentAccessMode` | `boolean` | No | V4 alias for enablePrivateMode | | `enableMarkAsRead` | `boolean` | No | Enable mark as read option | | `allowMarkAsRead` | `boolean` | No | V4 alias for enableMarkAsRead | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### CustomAnnotationItemProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogcustomannotationdropdowntriggerlistitem) Props for custom annotation dropdown items. | Property | Type | Required | Description | | -------- | -------- | -------- | ---------------- | | `item` | `object` | No | Item data object | | `index` | `number` | No | Item index | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### ReplyAvatarsListItemProps ## [Usage Examples →](/ui-customization/features/async/comments/comment-dialog/primitives#veltcommentdialogreplyavatarslistitem) Props for VeltCommentDialogReplyAvatarsListItem. | Property | Type | Required | Description | | -------- | --------------- | -------- | --------------------- | | `user` | [`User`](#user) | Yes | User data object | | `index` | `number` | Yes | Index of user in list | Inherits all properties from [`CommentDialogCommonProps`](#commentdialogcommonprops). #### IVeltCommentDialogThreadCardReactionPinProps *** Props for VeltCommentDialogThreadCard.ReactionPin to display specific pinned reactions. | Property | Type | Required | Description | | ------------ | -------- | -------- | --------------------------------------------- | | `reactionId` | `string` | No | Unique reaction identifier to pin and display | #### IVeltCommentDialogThreadCardReactionsProps *** Props for VeltCommentDialogThreadCard.Reactions to filter displayed reactions. | Property | Type | Required | Description | | -------------------- | ---------- | -------- | ------------------------------------ | | `excludeReactionIds` | `string[]` | No | Reaction IDs to exclude from display | #### IVeltCommentDialogThreadCardReactionToolProps *** Props for VeltCommentDialogThreadCard.ReactionTool to filter reaction picker options. | Property | Type | Required | Description | | -------------------- | ---------- | -------- | ----------------------------------- | | `excludeReactionIds` | `string[]` | No | Reaction IDs to exclude from picker | ### Recordings #### ENUMs | Enum Name | Event Type | Description | | ------------------ | ----------------- | --------------------------------- | | `DELETE_RECORDING` | `deleteRecording` | Delete a recording from a comment | #### GetRecordingRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `options` | `RequestOptions` | No | Request options | #### DeleteRecordingRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentId` | `number` | Yes | ID of the comment | | `recorderId` | `string` | Yes | ID of the recorder | | `options` | `RequestOptions` | No | Request options | #### DeleteRecordingEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `commentId` | `number` | Yes | ID of the comment | | `recording` | `RecordedData` | Yes | Recording data | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | ### Deep Links #### ENUMs | Enum Name | Event Type | Description | | ----------- | ---------- | ----------------------------- | | `COPY_LINK` | `copyLink` | Copy a deep link to a comment | #### GetLinkRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### CopyLinkRequest *** | Property | Type | Required | Description | | -------------- | ---------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `options` | `RequestOptions` | No | Request options | #### CopyLinkEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `link` | `string` | Yes | Copied link | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### GetLinkResponse *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `link` | `string \| null` | Yes | Generated link | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | ### Access #### ENUMs | Enum Name | Event Type | Description | | --------------- | -------------- | ------------------------------------ | | `UPDATE_ACCESS` | `updateAccess` | Update access settings for a comment | #### UpdateAccessRequest *** | Property | Type | Required | Description | | -------------- | ------------------- | -------- | -------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `accessMode` | `CommentAccessMode` | Yes | Access mode | | `options` | `RequestOptions` | No | Request options | #### UpdateAccessEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `newAccessMode` | `CommentAccessMode` | No | New access mode | | `oldAccessMode` | `CommentAccessMode` | No | Previous access mode | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### UserPermissionAccessRole *** Type: `'editor' | 'viewer'` * editor: Write access * viewer: Read-only access #### UserPermissionAccessRoleResult *** Type: `'does_not_exist' | 'permission_denied' | 'something_went_wrong'` Error codes returned when permission resolution fails: * `does_not_exist`: The requested resource (organization, folder, or document) does not exist * `permission_denied`: The user does not have permission to access the requested resource * `something_went_wrong`: An unexpected error occurred during permission resolution #### GetUserPermissionsRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------------------------- | | `organizationId` | `string` | No | Organization to scope the permission lookup. | | `folderIds` | `string[]` | No | Folder IDs to include in the lookup. | | `documentIds` | `string[]` | No | Document IDs to include in the lookup. | #### UserPermissionInfo *** | Property | Type | Required | Description | | ------------ | -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `accessRole` | `UserPermissionAccessRole` | No | Access role for the resource. | | `accessType` | `string` | No | The effective access type for the resource: `'public'`, `'restricted'`, or `'organizationPrivate'`. Documents inside folders inherit the folder's `accessType`. Also present on `PERMISSION_DENIED` entries. | | `expiresAt` | `number` | No | Expiry (Unix ms) for temporary access, if applicable. | | `error` | `string` | No | Error message if permission resolution failed. | | `errorCode` | `UserPermissionAccessRoleResult` | No | Error code indicating the type of permission resolution failure. | | `context` | `{ accessFields?: string[] }` | No | Context access information with accessFields array. | #### GetUserPermissionsResponse *** Map of user IDs to their resolved permissions across organization, folders, and documents. | Property | Type | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------- | | `[userId: string]` | `{ folders?: Record; organization?: Record; documents?: Record; }` | Yes | Permissions for a user, keyed by resource scope and ID. | ### UI #### AssignToType *** UI mode for assignment functionality. ```typescript theme={null} type AssignToType = "dropdown" | "checkbox"; ``` * `'dropdown'`: Default assignment menu with team member selection * `'checkbox'`: Quick self-assignment toggle mode #### ENUMs | Enum Name | Event Type | Description | | ------------------------ | ---------------------- | -------------------------------------------------------------------- | | `COMPOSER_CLICKED` | `composerClicked` | Triggered when comment composer is clicked | | `COMMENT_PIN_CLICKED` | `commentPinClicked` | Triggered when a comment pin is clicked | | `COMPOSER_TEXT_CHANGE` | `composerTextChange` | Triggered when text changes in a comment composer | | `COMMENT_TOOL_CLICKED` | `commentToolClicked` | Past-tense alias for `commentToolClick` | | `SIDEBAR_BUTTON_CLICKED` | `sidebarButtonClicked` | Past-tense alias for `sidebarButtonClick` | | `COMMENT_SAVE_TRIGGERED` | `commentSaveTriggered` | Triggered immediately when save button is clicked, before async save | #### ComposerClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | --------------------------------------------------------------------------------------- | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object. This is `undefined` if it's a new comment annotation object. | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | #### ComposerTextChangeEvent *** | Property | Type | Required | Description | | ------------------------- | ----------------------------------------- | -------- | ---------------------------------------------------------------- | | `text` | `string` | Yes | Current text content in the composer | | `annotation` | [`CommentAnnotation`](#commentannotation) | Yes | Full draft annotation with attachments, recordings, tagged users | | `targetComposerElementId` | `string` | Yes | Unique identifier of the composer that triggered the event | | `metadata` | [`VeltEventMetadata`](#velteventmetadata) | No | Event metadata including document and location context | #### CommentPinClickedEvent *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------- | | `annotationId` | `string` | Yes | ID of the annotation | | `commentAnnotation` | `CommentAnnotation` | Yes | Comment annotation object | | `metadata` | `VeltEventMetadata` | No | Event metadata | #### CommentToolClickedEvent *** | Property | Type | Required | Description | | ----------------- | -------------------------------- | -------- | ------------------------------------------------ | | `context` | `{ [key: string]: any } \| null` | No | Custom context data when comment tool is clicked | | `metadata` | `VeltEventMetadata` | No | Event metadata | | `targetElementId` | `string` | No | ID of the target element if available | #### SidebarButtonClickedEvent *** | Property | Type | Required | Description | | ---------- | ------------------- | -------- | -------------- | | `metadata` | `VeltEventMetadata` | No | Event metadata | ### Comment Sidebar #### CommentCountType *** Union type for specifying comment count display mode. ```typescript theme={null} type CommentCountType = "total" | "unread"; ``` * `'total'`: Shows total count of all comments * `'unread'`: Shows count of unread comments only #### SidebarFilterCriteria *** Filter criteria for minimal filter dropdown in sidebar. ```typescript theme={null} type SidebarFilterCriteria = | "status" | "priority" | "category" | "people" | "assignedToMe"; ``` Available filter criteria for sidebar filtering. #### ENUMs | Enum Name | Event Type | Description | | ----------------------------- | -------------------------- | --------------------------------------------------- | | `COMMENT_SIDEBAR_DATA_INIT` | `commentSidebarDataInit` | Triggered when comment sidebar data is first loaded | | `COMMENT_SIDEBAR_DATA_UPDATE` | `commentSidebarDataUpdate` | Triggered when comment sidebar data is updated | #### CommentStatus *** | Property | Type | Required | Description | | ------------ | -------- | -------- | -------------------------------------------- | | `color` | `string` | Yes | Primary color for the status. | | `id` | `string` | Yes | Unique identifier for the status. | | `lightColor` | `string` | Yes | Light variant of the status color. | | `name` | `string` | Yes | Display name of the status. | | `svg` | `string` | Yes | SVG icon for the status. | | `type` | `string` | No | Optional type classification for the status. | #### CommentPriority *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------ | | `color` | `string` | Yes | Primary color for the priority. | | `id` | `string` | Yes | Unique identifier for the priority. | | `lightColor` | `string` | Yes | Light variant of the priority color. | | `name` | `string` | Yes | Display name of the priority. | #### CustomFilter *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom filter | | `color` | `string` | Yes | Color associated with the custom filter | | `name` | `string` | Yes | Name or label of the custom filter | #### CustomCategory *** | Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------- | | `id` | `string` | Yes | Unique identifier for the custom category | | `color` | `string` | Yes | Color associated with the custom category | | `name` | `string` | Yes | Name or label of the custom category | #### CommentSidebarDataInitEvent *** | Property | Type | Required | Description | | ----------------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `buttonContext` | `VeltButtonContext` | Yes | Button context | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object | | `comment` | `Comment` | No | Comment object | | `index` | `number` | No | Index value | | `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations | | `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations | | `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts | | `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used. | #### CommentSidebarDataUpdateEvent *** | Property | Type | Required | Description | | ----------------------------- | ------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `buttonContext` | `VeltButtonContext` | Yes | Button context | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object | | `comment` | `Comment` | No | Comment object | | `index` | `number` | No | Index value | | `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations | | `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations | | `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts | | `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used. | #### CommentSidebarFilterConfig *** | Property | Type | Required | Description | | --------------- | ------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `location` | `FilterTypeConfig` | No | Configuration for the location filter type. | | `document` | `FilterTypeConfig` | No | Configuration for the document filter type. Only use it if you are using multiple documents or folders | | `people` | `FilterTypeConfig` | No | Configuration for the author filter type. | | `tagged` | `FilterTypeConfig` | No | Configuration for the tagged/mentioned filter type. | | `assigned` | `FilterTypeConfig` | No | Configuration for the assigned filter type. | | `involved` | `FilterTypeConfig` | No | Configuration for the involved filter type (author, mentioned, assigned). | | `priority` | `FilterTypeConfig` | No | Configuration for the priority filter type. | | `category` | `FilterTypeConfig` | No | Configuration for the category filter type. | | `commentType` | `FilterTypeConfig` | No | Configuration for the comment type filter. | | `version` | `FilterTypeConfig` | No | Configuration for the version filter type. | | `status` | `FilterTypeConfig` | No | Configuration for the status filter type. | | `[key: string]` | `FilterTypeConfig \| undefined` | No | Custom filter type configurations. | #### FilterTypeConfig *** | Property | Type | Required | Description | | ---------------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------- | | `name` | `string` | No | The name of the filter type | | `enable` | `boolean` | No | Enables or disables the filter type | | `multiSelection` | `boolean` | No | Allows multiple selections if set to true | | `enableGrouping` | `boolean` | No | Enables grouping within the filter type if set to true | | `placeholder` | `string` | No | The placeholder text for the filter type. Used when `filterOptionLayout` is set to `dropdown` | | `id` | `string` | No | The unique identifier for the filter type | | `type` | `'custom' \| 'system'` | No | The type of filter - custom or system | | `options` | `FilterOption[]` | No | Array of filter options available for this filter type | #### CommentSidebarGroupConfig *** | Property | Type | Required | Description | | --------------- | ----------------------------------------------------------- | -------- | ---------------------------- | | `enable` | `boolean` | No | Enables or disables grouping | | `name` | `string` | No | The name of the group | | `[key: string]` | `{ id?: string, name?: string }[] \| string[] \| undefined` | No | Custom filter configurations | #### CommentSidebarFilters *** | Property | Type | Required | Description | | ---------- | -------------------- | -------- | ---------------------------------------------------------------------------------------- | | `location` | `{id: string}[]` | No | Filter by location Ids | | `document` | `{id: string}[]` | No | Filter by document Ids | | `people` | `{userId: string}[]` | No | Filter by author of comment annotation | | `tagged` | `{userId: string}[]` | No | Filter by users who were tagged/mentioned in the comment | | `assigned` | `{userId: string}[]` | No | Filter by users who were assigned to the comment annotation | | `involved` | `{userId: string}[]` | No | Filter by users who are involved in the comment annotation (author, mentioned, assigned) | | `priority` | `string[]` | No | Filter by priority ids | | `status` | `string[]` | No | Filter by status ids | | `category` | `string[]` | No | Filter by category ids | | `version` | `{id: string}[]` | No | Filter by version Ids | #### CommentSidebarData *** | Property | Type | Required | Description | | ------------- | --------------------- | -------- | ----------------------------------------------- | | `groupId` | `string` | No | ID of the group. Defaults to 'others' | | `groupName` | `string` | No | Name of the group. Defaults to 'Others' | | `isExpanded` | `boolean` | No | Whether the group is expanded. Defaults to true | | `annotations` | `CommentAnnotation[]` | Yes | List of CommentAnnotations in the group | #### Options *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ------------------------------------------- | | `grouping` | `boolean` | No | Whether to group the data. Defaults to true | #### CustomFilterOption *** | Property | Type | Required | Description | | ---------- | --------- | -------- | ----------------------------------------------- | | `id` | `string` | Yes | Unique identifier for the filter option | | `name` | `string` | Yes | Display name for the filter option | | `selected` | `boolean` | Yes | Whether the filter option is currently selected | #### CustomFilters *** | Property | Type | Required | Description | | --------------- | ---------------------- | -------- | ------------------------------------------------- | | `[key: string]` | `CustomFilterOption[]` | No | Custom filter configurations mapped by filter key | #### FilterOption *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------- | | `id` | `string` | Yes | Unique identifier for the filter option | | `name` | `string` | Yes | Display name for the filter option | #### CustomFilter *** | Property | Type | Required | Description | | -------- | ------ | -------- | ---------------------------------------- | | `id` | string | Yes | Unique identifier for the custom filter. | | `color` | string | Yes | Color associated with the custom filter. | | `name` | string | Yes | Name or label of the custom filter. | #### CustomPriority *** | Property | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------------------- | | `id` | string | Yes | Unique identifier for the custom priority. | | `color` | string | Yes | Color associated with the custom priority. | | `name` | string | Yes | Name or label of the custom priority. | | `lightColor` | string | No | Light color variant for the custom priority. | #### CustomStatus *** | Property | Type | Required | Description | | ------------ | ---------- | -------- | --------------------------------------------------------- | | `id` | string | Yes | Unique identifier for the custom status. | | `color` | string | Yes | Color associated with the custom status. | | `name` | string | Yes | Name or label of the custom status. | | `type` | StatusType | Yes | Type of the status (`default`, `ongoing`, or `terminal`). | | `lightColor` | string | No | Light color for the custom status. | | `iconUrl` | string | No | URL to an icon image for the custom status. | #### CustomCategory *** | Property | Type | Required | Description | | -------- | ------ | -------- | ------------------------------------------ | | `id` | string | Yes | Unique identifier for the custom category. | | `color` | string | Yes | Color associated with the custom category. | | `name` | string | Yes | Name or label of the custom category. | ### Component Props #### VeltCommentsProps *** | Property | Type | Required | Description | | -------------- | ------------------------------- | -------- | ------------------------------------------------------ | | `assignToType` | [`AssignToType`](#assigntotype) | No | Assignment UI mode: 'dropdown' (default) or 'checkbox' | #### VeltCommentToolProps *** | Property | Type | Required | Description | | --------------------------- | --------- | -------- | -------------------------------------------- | | `contextInPageModeComposer` | `boolean` | No | Enable passing context to page mode composer | | `context` | `any` | No | Context data to pass when sidebar opens | #### VeltCommentComposerProps *** | Property | Type | Required | Description | | ------------------------- | --------- | -------- | ----------------------------------------------------------------- | | `context` | `any` | No | Custom context data for the comment composer | | `locationId` | `string` | No | Location identifier for the comment | | `documentId` | `string` | No | Document identifier for the comment | | `folderId` | `string` | No | Folder identifier for the comment | | `placeholder` | `string` | No | Custom placeholder text for composer input | | `targetComposerElementId` | `string` | No | Unique identifier for programmatic submission via submitComment() | | `readOnly` | `boolean` | No | Enable read-only mode for composer | #### VeltCommentsSidebarProps *** | Property | Type | Required | Description | | --------------------------- | --------- | -------- | --------------------------------------------------------------------------------------- | | `openAnnotationInFocusMode` | `boolean` | No | Opens annotation in focus mode when enabled. Requires `focusedThreadMode` to be enabled | | `commentPlaceholder` | `string` | No | Custom placeholder text for comment input field | | `replyPlaceholder` | `string` | No | Custom placeholder text for reply input field | | `pageModePlaceholder` | `string` | No | Custom placeholder text for page mode input | | `version` | `string` | No | When set to `"2"`, renders the V2 sidebar implementation | #### VeltCommentsSidebarV2Props *** | Property | Type | Required | Description | | -------------------------------- | --------------------- | -------- | ----------------------------------------------------------------- | | `pageMode` | `boolean` | No | Enable page-mode composer | | `focusedThreadMode` | `boolean` | No | Enable focused-thread view on comment click | | `readOnly` | `boolean` | No | Enable read-only mode | | `embedMode` | `string \| null` | No | Embeds the sidebar inline within a container | | `floatingMode` | `boolean` | No | Renders the sidebar as a floating overlay | | `position` | `string` | No | Sidebar position, e.g., `'right'`, `'left'` | | `variant` | `string` | No | Sidebar variant, e.g., `'sidebar'`, `'inline'` | | `forceClose` | `boolean` | No | Force-close the sidebar | | `version` | `string` | No | When `"2"`, routes `VeltCommentsSidebar` to the V2 implementation | | `onSidebarOpen` | `(data: any) => void` | No | Callback when sidebar opens | | `onSidebarClose` | `(data: any) => void` | No | Callback when sidebar closes | | `onCommentClick` | `(data: any) => void` | No | Callback when a comment is clicked | | `onCommentNavigationButtonClick` | `(data: any) => void` | No | Callback when navigation button is clicked | #### 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_LOCAL` | `recordingDoneLocal` | Triggered immediately after a recording annotation is saved locally — before cloud upload and transcription begin. Only fires when `sourceFeature === 'recording'`. | | `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). | #### RecordingDoneLocalEvent *** | 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. The URL in `assets[0].url` is a local blob URL at this point — the permanent CDN URL is not yet available. | | `assetsAllVersions` | `RecorderDataAsset[]` | Yes | Array of all versions of recording assets | | `transcription` | `RecorderDataTranscription` | Yes | Transcription data for the recording | | `sourceFeature` | `string` | No | The feature that triggered the event. Always `'recording'` for this event. | #### 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` | 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 | | `isNotificationResolverUsed` | `boolean` | No | `true` when the notification was enriched via the notification resolver | #### NotificationMetadata *** | Property | Type | Required | Description | | ---------------------- | ---------- | -------- | -------------------------------------------------- | | `apiKey` | `string` | No | Your API key | | `clientOrganizationId` | `string` | No | The organization ID that you set | | `organizationId` | `string` | No | The organization ID generated by us | | `clientDocumentId` | `string` | No | The document ID that you set | | `documentId` | `string` | No | The document ID generated by us | | `locationId` | `number` | No | The unique location ID | | `location` | `Location` | No | The location object | | `documentMetadata` | `Object` | No | Contains the complete document metadata object | | `organizationMetadata` | `Object` | No | Contains the complete organization metadata object | #### SettingsUpdatedEvent *** | Property | Type | Required | Description | | ------------ | ---------------------------- | -------- | ------------------------------------------------ | | `settings` | `NotificationSettingsConfig` | Yes | The updated notification settings configuration. | | `isMutedAll` | `boolean` | Yes | Whether all notifications are muted. | | Enum Name | Event Type | Description | | ------------------ | ----------------- | ---------------------------------------------------- | | `SETTINGS_UPDATED` | `settingsUpdated` | Triggered when the notification settings are updated | #### NotificationSettingsConfig *** Sets what notifications the user will receive on the provided channel. | Property | Type | Required | Description | | --------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `[key: string]` | `NotificationSettingsItemType` | No | Dynamic key-value pairs for notification settings configuration. The key represents the channel ID and the value represents the one of the NotificationSettingsItemType. | #### NotificationSettingsItemType *** Decides what notifications the user will receive on the current channel. Type: `'ALL' | 'MINE' | 'NONE' | string` **Description:** * `ALL`: Subscribes the user to all notifications whether or not the user is involved in the notification on the current document. * `MINE`: Subscribes the user to notifications that are related to the current user on the current document. * `NONE`: Subscribes the user to no notifications on this channel on the current document. #### NotificationInitialSettingsConfig *** | Property | Type | Required | Description | | --------- | --------------------------- | -------- | ------------------------------------------------------ | | `name` | `string` | No | Display name for the notification channel. | | `id` | `string` | Yes | Unique channel ID for the notification channel. | | `default` | `string` | No | Default value for the notification channel. | | `enable` | `boolean` | No | Whether the notification channel is enabled. | | `values` | `NotificationConfigValue[]` | No | Array of possible values for the notification channel. | #### NotificationConfigValue *** | Property | Type | Required | Description | | -------- | ------------------------------ | -------- | ----------------------------------------- | | `id` | `NotificationSettingsItemType` | Yes | Unique id for the configuration value. | | `name` | `string` | No | Display name for the configuration value. | #### GetNotificationsDataQuery *** | Property | Type | Required | Description | | -------- | ---------------------------------- | -------- | --------------------------------------------------------- | | `type` | `'all' \| 'forYou' \| 'documents'` | No | Filter for notification type: all, for you, or documents. | #### NotificationSettingsLayout *** Layout mode for notification settings UI. Type: `'accordion' | 'dropdown'` **Description:** * `accordion`: Settings displayed in expandable accordion (default) * `dropdown`: Settings displayed in dropdown menu #### NotificationServiceConfig *** Top-level org-scoped config for notification delay and batching. Set in the Velt Console under workspace notification settings. | Property | Type | Required | Description | | ------------- | ----------------------------- | -------- | -------------------------------------------------------- | | `delayConfig` | [`DelayConfig`](#delayconfig) | No | Controls whether notifications are held before delivery. | | `batchConfig` | [`BatchConfig`](#batchconfig) | No | Controls grouping of notifications into batched digests. | #### DelayConfig *** Controls the hold period applied to notifications before they are evaluated for batching or delivery. | Property | Type | Required | Default | Description | | -------------- | --------- | -------- | ------- | ------------------------------------------------------------------ | | `isEnabled` | `boolean` | No | `false` | Enables the delay pipeline for this organization. | | `delaySeconds` | `number` | No | — | Seconds to hold a notification before proceeding to batch or send. | #### BatchConfig *** Configures batching windows per grouping scope. Each scope is independently configured via [`BatchWindowConfig`](#batchwindowconfig). | Property | Type | Required | Description | | ---------- | ----------------------------------------- | -------- | ------------------------------------------------------ | | `document` | [`BatchWindowConfig`](#batchwindowconfig) | No | Batching window applied per document. | | `user` | [`BatchWindowConfig`](#batchwindowconfig) | No | Batching window applied per user across all documents. | #### BatchWindowConfig *** Defines the time window and activity cap for a single batching scope. | Property | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------------------------------------------------ | | `isEnabled` | `boolean` | No | Enables batching for this scope. | | `batchWindowSeconds` | `number` | No | Duration in seconds to collect activities before flushing the batch. | | `maxActivities` | `number` | No | Maximum activities per batch; flush triggers early when this count is reached. | ### Notification Primitives Types for the primitive components used to build custom notification interfaces. See [Notifications Primitives](/ui-customization/features/async/notifications/notifications-primitives) for usage examples. #### NotificationsPrimitiveCommonProps ## [Usage Examples →](/ui-customization/features/async/notifications/notifications-primitives#common-inputs) Base props inherited by all Notification primitive components. | Property | Type | Required | Description | | -------------------- | --------- | -------- | ------------------------------------------------------------ | | `variant` | `string` | No | Visual variant of the primitive component | | `darkMode` | `boolean` | No | Renders the component in dark mode when true | | `shadowDom` | `boolean` | No | Renders the component inside a Shadow DOM when true | | `parentLocalUIState` | `object` | No | Local UI state passed down from a parent primitive component | # Activity Logs #### ActivityFeatureType *** Feature area that generated an activity log record. ```typescript theme={null} type ActivityFeatureType = | "comment" | "reaction" | "recorder" | "crdt" | "custom"; ``` | Value | Description | | ------------ | --------------------------------------------------------- | | `'comment'` | Activity log from the Comments feature | | `'reaction'` | Activity log from the Reactions feature | | `'recorder'` | Activity log from the Recorder feature | | `'crdt'` | Activity log from the CRDT (collaborative editor) feature | | `'custom'` | Activity log created by the host application | #### ActivitySubscribeConfig *** Filter config passed to `getAllActivities()` to scope the activity log feed. | Property | Type | Required | Description | | --------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------- | | `organizationId` | `string` | No | Scope feed to a specific organization ID | | `documentIds` | `string[]` | No | Filter to specific document IDs | | `currentDocumentOnly` | `boolean` | No | When `true`, limits feed to the current document. Auto-switches when `setDocument()` is called | | `maxDays` | `number` | No | Maximum age in days for returned activity logs (default: 30) | | `featureTypes` | [`ActivityFeatureType[]`](#activityfeaturetype) | No | Filter by feature area | | `excludeFeatureTypes` | [`ActivityFeatureType[]`](#activityfeaturetype) | No | Exclude specific feature areas | | `actionTypes` | `string[]` | No | Filter by action type; use the exported action type constants | | `excludeActionTypes` | `string[]` | No | Exclude specific action types | | `userIds` | `string[]` | No | Filter to activity logs by specific user IDs | | `excludeUserIds` | `string[]` | No | Exclude activity logs by specific user IDs | #### ActivityRecord *** Core activity log object returned from the activity log feed. Generic params: `TEntity` (entity data shape), `TTarget` (target entity data shape). | Property | Type | Required | Description | | ---------------------------- | --------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | Unique activity log ID | | `featureType` | [`ActivityFeatureType`](#activityfeaturetype) | Yes | Feature area that generated this activity log | | `actionType` | `string` | Yes | Specific action that occurred | | `eventType` | `string` | No | Sub-event type within the action | | `actionUser` | [`User`](#user) | Yes | User who performed the action | | `timestamp` | `number` | Yes | Unix timestamp of the activity log | | `metadata` | [`ActivityMetadata`](#activitymetadata) | Yes | Feature-specific extensible metadata | | `targetEntityId` | `string` | No | ID of the entity this activity log targets | | `targetSubEntityId` | `string \| null` | No | ID of a sub-entity within the target | | `changes` | [`ActivityChanges`](#activitychanges) | No | Before/after field changes | | `entityData` | `TEntity` | No | Full entity object at time of action | | `entityTargetData` | `TTarget` | No | Full target entity object at time of action | | `displayMessageTemplate` | `string` | No | Template string with `{{variable}}` placeholders | | `displayMessageTemplateData` | `Record` | No | Data to resolve the display message template | | `displayMessage` | `string` | No | Resolved human-readable display message. Computed client-side — never stored in Firestore | | `actionIcon` | `string` | No | Icon URL or identifier for the action | | `immutable` | `boolean` | No | When `true`, the record cannot be updated or deleted via REST API | | `isActivityResolverUsed` | `boolean` | No | `true` when PII was stripped by the activity data provider. Can be used to show a loading state while resolver re-hydration is pending. | #### ActivityChanges *** Map of field names to their before/after change values. ```typescript theme={null} interface ActivityChanges { [key: string]: ActivityChange | undefined; } ``` #### ActivityChange *** Before/after values for a single changed field. Generic param `T` is the field value type. | Property | Type | Required | Description | | -------- | ----------- | -------- | ----------------------------- | | `from` | `T \| null` | No | Field value before the action | | `to` | `T \| null` | No | Field value after the action | #### ActivityMetadata *** Extensible metadata attached to an activity log record. Extends `BaseMetadata` with open index signature for feature-specific fields. | Property | Type | Required | Description | | ---------------------- | ------------------ | -------- | --------------------------------- | | `apiKey` | `string` | No | Inherited from `BaseMetadata` | | `documentId` | `string` | No | Inherited from `BaseMetadata` | | `organizationId` | `string` | No | Inherited from `BaseMetadata` | | `clientOrganizationId` | `string` | No | Inherited from `BaseMetadata` | | `folderId` | `string` | No | Inherited from `BaseMetadata` | | `veltFolderId` | `string` | No | Inherited from `BaseMetadata` | | `documentMetadata` | `DocumentMetadata` | No | Inherited from `BaseMetadata` | | `sdkVersion` | `string \| null` | No | Inherited from `BaseMetadata` | | `[key: string]` | `any` | No | Feature-specific extension fields | #### CreateActivityData *** Payload for `createActivity()`. Use `featureType: 'custom'` and `actionType: 'custom'` for non-Velt events. Generic params: `TEntity` (entity data shape), `TTarget` (target entity data shape). | Property | Type | Required | Description | | ---------------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `id` | `string` | No | Optional Firestore document ID for idempotent writes | | `featureType` | [`ActivityFeatureType`](#activityfeaturetype) | Yes | Feature type; use `'custom'` for non-Velt events | | `actionType` | `string` | Yes | Action identifier; use `'custom'` for non-Velt events | | `eventType` | `string` | No | Sub-event type within the action | | `targetEntityId` | `string` | No | Required only when `featureType` is `'custom'`. Optional for `comment`, `reaction`, `recorder`, `crdt`. | | `targetSubEntityId` | `string \| null` | No | ID of a sub-entity within the target | | `changes` | [`ActivityChanges`](#activitychanges) | No | Before/after field changes to record | | `entityData` | `TEntity` | No | Full entity object at time of action | | `entityTargetData` | `TTarget` | No | Full target entity object at time of action | | `actionIcon` | `string` | No | Icon URL or identifier — typically for custom activities | | `displayMessageTemplate` | `string` | No | Template string with `{{variable}}` placeholders — only for custom activities | | `displayMessageTemplateData` | `Record` | No | Template variable values — only for custom activities | ### Activity Log Action Type Constants Pre-defined `actionType` string constants for each feature's activity log records. Import these to build type-safe `actionTypes` filters in [`ActivitySubscribeConfig`](#activitysubscribeconfig). #### CommentActivityActionTypes *** Action type constants for Comment feature activity logs. Union type: `CommentActivityActionType`. | Constant | Value | Description | | -------------------- | ----------------------------------------- | ------------------------------------------- | | `ANNOTATION_ADD` | `'comment_annotation.add'` | A comment annotation was added | | `ANNOTATION_DELETE` | `'comment_annotation.delete'` | A comment annotation was deleted | | `COMMENT_ADD` | `'comment.add'` | A comment was added | | `COMMENT_UPDATE` | `'comment.update'` | A comment was updated | | `COMMENT_DELETE` | `'comment.delete'` | A comment was deleted | | `STATUS_CHANGE` | `'comment_annotation.status_change'` | Comment annotation status changed | | `PRIORITY_CHANGE` | `'comment_annotation.priority_change'` | Comment annotation priority changed | | `ASSIGN` | `'comment_annotation.assign'` | Comment annotation was assigned | | `ACCESS_MODE_CHANGE` | `'comment_annotation.access_mode_change'` | Comment annotation access mode changed | | `CUSTOM_LIST_CHANGE` | `'comment_annotation.custom_list_change'` | Comment annotation custom list changed | | `APPROVE` | `'comment_annotation.approve'` | Comment annotation was approved | | `ACCEPT` | `'comment.accept'` | A comment was accepted | | `REJECT` | `'comment.reject'` | A comment was rejected | | `REACTION_ADD` | `'comment.reaction_add'` | A reaction was added to a comment | | `REACTION_DELETE` | `'comment.reaction_delete'` | A reaction was removed from a comment | | `SUBSCRIBE` | `'comment_annotation.subscribe'` | User subscribed to a comment annotation | | `UNSUBSCRIBE` | `'comment_annotation.unsubscribe'` | User unsubscribed from a comment annotation | #### RecorderActivityActionTypes *** Action type constants for Recorder feature activity logs. Union type: `RecorderActivityActionType`. | Constant | Value | Description | | ------------------ | -------------------- | ----------------------- | | `RECORDING_ADD` | `'recording.add'` | A recording was added | | `RECORDING_DELETE` | `'recording.delete'` | A recording was deleted | #### ReactionActivityActionTypes *** Action type constants for Reaction feature activity logs. Union type: `ReactionActivityActionType`. | Constant | Value | Description | | ----------------- | ------------------- | ---------------------- | | `REACTION_ADD` | `'reaction.add'` | A reaction was added | | `REACTION_DELETE` | `'reaction.delete'` | A reaction was deleted | #### CrdtActivityActionTypes *** Action type constants for CRDT feature activity logs. Union type: `CrdtActivityActionType`. | Constant | Value | Description | | ------------- | -------------------- | --------------------------- | | `EDITOR_EDIT` | `'crdt.editor_edit'` | A CRDT editor edit occurred | # Single Editor Mode #### AccessRequestEvent *** This event object is related to requests for editor access. It is emitted for `accessRequested`, `accessRequestCanceled`, `accessAccepted`, and `accessRejected` events. | Property | Type | Required | Description | | ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------ | | `viewer` | `User` | No | The user who is the current viewer and is involved in the access request. | | `editor` | `User` | No | The user who is the current editor at the time of the event. | | `timestamp` | `number` | No | UNIX timestamp (in milliseconds) of when the event occurred. | | `status` | `string` | No | The status of the access request (e.g., "requested", "canceled", "accepted", "rejected" ). | | `totalUsers` | `number` | No | Total number of users currently present on the document. | | `presenceSnippylyUserIds` | `string[]` | No | Velt internal user IDs of currently present users. | | `presenceClientUserIds` | `string[]` | No | Client-provided user IDs of currently present users. | #### SEMEvent *** This event object is related to editor/viewer assignments and editor status changes. It is emitted for `editorAssigned`, `viewerAssigned`, and `editorOnDifferentTabDetected` events. | Property | Type | Required | Description | | ------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------- | | `viewer` | `User` | No | The user who is the current viewer at the time of the event. | | `editor` | `User` | No | The user who is the current editor at the time of the event. | | `timestamp` | `number` | No | UNIX timestamp (in milliseconds) of when the event occurred. | | `role` | `string` | No | The role relevant to the event, typically "editor" or "viewer" for assignment events. | | `totalUsers` | `number` | No | Total number of users currently present on the document. | | `presenceSnippylyUserIds` | `string[]` | No | Velt internal user IDs of currently present users. | | `presenceClientUserIds` | `string[]` | No | Client-provided user IDs of currently present users. | #### SingleEditorLiveStateData *** | Property | Type | Required | Description | | --------------------- | ---------------- | -------- | ----------------------------------------- | | `editor` | `User \| null` | No | The user who is currently editing, if any | | `requestEditorAccess` | `Object \| null` | No | Details about a request for editor access | | `tabId` | `string \| null` | No | The identifier of the tab, if applicable | #### RequestEditorAccess *** | Property | Type | Required | Description | | --------------------- | ------------------------------------------------------ | -------- | ------------------------------------------------------- | | `user` | `User` | Yes | The user requesting editor access | | `requestedAt` | `any` | Yes | The timestamp when the access was requested | | `status` | `'pending' \| 'accepted' \| 'rejected' \| 'cancelled'` | Yes | The status of the access request | | `editorAccessTimeout` | `number` | Yes | Timeout duration for the editor access | | `tabId` | `string \| null` | No | The identifier of the tab related to the access request | #### SingleEditorConfig *** | Property | Type | Required | Description | | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------- | | `customMode` | `boolean` | No | Enables/disables custom mode. In custom mode, input elements are not disabled for the viewer | | `singleTabEditor` | `boolean` | Yes | Enables/disables editor mode on a single tab only | #### UserEditorAccess *** | Property | Type | Required | Description | | ---------------------- | --------- | -------- | ---------------------------------------------------------- | | `isEditor` | `boolean` | No | Indicates whether the user has editor privileges | | `isEditorOnCurrentTab` | `boolean` | No | Indicates whether the user is an editor on the current tab | #### EditorAccessTimer *** | Property | Type | Required | Description | | -------------- | --------------------------------------- | -------- | ---------------------------------------------------------- | | `state` | `'idle' \| 'inProgress' \| 'completed'` | Yes | The state of the Editor Access Request timer | | `durationLeft` | `number` | No | Duration left for the editor access timer to be completed. | # Live State Data #### LiveStateData *** | Property | Type | Required | Description | | ----------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | A unique identifier likely used for quick reference and indexing. It's an MD5 hash of `liveStateDataId` | | `liveStateDataId` | `string` | Yes | A unique identifier for the state data being synced | | `data` | `string \| number \| boolean \| JSON` | Yes | The actual data you want to synchronize across clients | | `lastUpdated` | `any` | Yes | A timestamp or similar data indicating the last time the state data was updated | | `updatedBy` | `User` | Yes | The user who last updated the state data | | `tabId` | `string \| null` | No | An identifier that could be used to associate the state data with a specific tab or instance | #### LiveStateDataMap *** | Property | Type | Required | Description | | ------------------------------- | ----------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | | `custom` | `{ [liveStateDataId: string]: LiveStateData; }` | No | Map of all unique LiveStateData set by you on the given document. | | `default` | Object | No | Map of all unique LiveStateData set by the default editor on the given document. | | `default.singleEditor` | `SingleEditorLiveStateData` | No | Part of `default`, representing single editor live state data. | | `default.autoSyncState` | Object | | Part of `default`, representing auto synchronization state. | | `default.autoSyncState.current` | `LiveStateData` | No | Part of `autoSyncState`, current live state data. | | `default.autoSyncState.history` | `[liveStateDataId: string]: LiveStateData` | No | Part of `autoSyncState`, map of historical live state data keyed by live state data ID. | #### LiveStateData *** | Property | Type | Required | Description | | --------------- | ------- | -------- | ----------------------------------------- | | `id` | string | Yes | Unique identifier for the live state data | | `locationName` | string | Yes | Name of the location | | `version` | Version | Yes | Version information | | `[key: string]` | any | Yes | Additional dynamic properties | #### SetLiveStateDataConfig *** | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------------- | | `merge` | `boolean` | No | Whether to merge data with existing data. Default is `false`. | #### FetchLiveStateDataRequest *** | Property | Type | Required | Description | | ----------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ | | `liveStateDataId` | `string` | No | Unique identifier for the specific live state data to fetch. If not provided, all live state data will be fetched. | #### ServerConnectionState *** | Property | Type | Required | Description | | -------------- | ------ | -------- | ----------------------------------------------------------------- | | `ONLINE` | string | Yes | Server connection is online and active. Value: 'online' | | `OFFLINE` | string | Yes | Server connection is offline. Value: 'offline' | | `PENDING_INIT` | string | Yes | Server connection initialization is pending. Value: 'pendingInit' | | `PENDING_DATA` | string | Yes | Server is waiting for data. Value: 'pendingData' | # Client #### Client Events | Event Type | Event Name | Description | Event Object | | --------------------- | -------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------- | | `USER_UPDATE` | `userUpdate` | Fired when the Velt user logs in, logs out, or changes. | [UserUpdateEvent](#userupdateevent) | | `INIT_UPDATE` | `initUpdate` | Initialization lifecycle updates (documents/locations set/unset, user init). | [InitUpdateEvent](#initupdateevent) | | `DOCUMENT_INIT` | `documentInit` | Document initialization status changes. | [DocumentInitEvent](#documentinitevent) | | `ERROR` | `error` | Error events emitted by the SDK (e.g., token issues, retry limits). | [ErrorEvent](#errorevent) | | `VELT_BUTTON_CLICK` | `veltButtonClick` | Fired when a Velt Button is clicked. | [VeltButtonClickEvent](#veltbuttonclickevent) | | `PERMISSION_PROVIDER` | `permissionProvider` | Permission Provider events for access requests, results, and errors. | [PermissionProviderEvent](#permissionproviderevent) | | `DATA_PROVIDER` | `dataProvider` | Data Provider events for debugging get, save, and delete operations. | [DataProviderEvent](#dataproviderevent) | #### InitUpdateEvent *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------------------------------------ | | `event` | `string` | Yes | The event name (see sub-events table below) | | `methodName` | `string` | No | The method that triggered this event (see `InitUpdateMethodNames` below) | | `source` | `string` | No | Source of the event | | `payload` | `any` | No | Additional event payload data | **InitUpdateMethodNames:** | Method Name | Description | | ------------------------ | ----------------------------------- | | `setDocuments` | `setDocuments()` was called | | `setRootDocument` | `setRootDocument()` was called | | `setDocumentId` | `setDocumentId()` was called | | `unsetDocumentId` | `unsetDocumentId()` was called | | `unsetDocuments` | `unsetDocuments()` was called | | `setLocation` | `setLocation()` was called | | `setLocations` | `setLocations()` was called | | `setRootLocation` | `setRootLocation()` was called | | `addLocation` | `addLocation()` was called | | `removeLocation` | `removeLocation()` was called | | `removeLocations` | `removeLocations()` was called | | `unsetLocationIds` | `unsetLocationIds()` was called | | `removeLocationsSuccess` | Locations were successfully removed | **Sub-events (event field values):** | Sub-event (string) | Description | | -------------------------- | --------------------------------------------------------------------------------------- | | `userUpdate` | User initialized or updated as part of init | | `setDocumentsTriggered` | A document(s) set action was triggered (`setDocument`, `setDocuments`, `setDocumentId`) | | `setRootDocumentTriggered` | Root document set was triggered (`setRootDocument`) | | `setDocumentsSuccess` | Documents successfully set | | `unsetDocumentsTriggered` | Unset document(s) was triggered (`unsetDocumentId`, `unsetDocuments`) | | `unsetDocumentsSuccess` | Documents successfully unset | | `setLocationsTriggered` | A location(s) set action was triggered (`setLocation`, `setLocations`) | | `setRootLocationTriggered` | Root location set was triggered (`setRootLocation`) | | `setLocationsSuccess` | Locations successfully set | | `unsetLocationsTriggered` | Unsetting location IDs was triggered (`unsetLocationIds`) | #### PermissionProviderEvent *** This event follows the `BaseResolverEvent` structure (see [DataProviderEvent](#dataproviderevent) for the base structure). | Event Type | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------ | | `resourceAccessRequestFormed` | Triggered when a permission request is formed internally before being sent | | `resourceAccessRequestTriggered` | Triggered when a permission request is actually triggered and sent | | `resourceAccessResult` | Triggered when a permission check result is received from your server | | `resourceAccessError` | Triggered when an error occurs during permission checking | | `resourceAccessResultFromCache` | Triggered when a permission result is retrieved from cache instead of making a new request | | `revokeAccessOnDocumentUnsetTriggered` | Triggered when permissions are automatically revoked due to document unset trigger | | `revokeAccessOnDocumentUnsetFormed` | Triggered when a revoke access on document unset request is formed | | `revokeAccessOnDocumentUnsetResult` | Triggered when revoke access on document unset completes successfully | | `revokeAccessOnDocumentUnsetError` | Triggered when an error occurs during revoke access on document unset | | `revokeAccessOnUserLogoutTriggered` | Triggered when permissions are automatically revoked due to user logout trigger | | `revokeAccessOnUserLogoutFormed` | Triggered when a revoke access on user logout request is formed | | `revokeAccessOnUserLogoutResult` | Triggered when revoke access on user logout completes successfully | | `revokeAccessOnUserLogoutError` | Triggered when an error occurs during revoke access on user logout | #### DataProviderEvent *** The `dataProvider` event emits different resolver event types depending on the data provider being used. All resolver events share a common base structure: **BaseResolverEvent Structure:** | Property | Type | Required | Description | | ------------ | -------- | -------- | ------------------------------------------ | | `event` | `object` | Yes | The event type object (varies by resolver) | | `methodName` | `string` | No | The method that triggered this event | | `moduleName` | `string` | No | The module that triggered this event | | `source` | `string` | No | `'internal'` or `'external'` | | `timestamp` | `number` | No | Timestamp of the event | | `uniqueId` | `string` | No | Unique identifier for the event | | `payload` | `any` | No | Additional event payload data | *** #### UserResolverEvent | Event Type | Description | | -------------------------------- | --------------------------------------------------------------- | | `userResolutionRequestFormed` | Triggered when a user resolution request is formed internally | | `userResolutionRequestTriggered` | Triggered when a user resolution request is sent | | `userResolutionResult` | Triggered when user resolution completes successfully | | `userResolutionError` | Triggered when an error occurs during user resolution | | `userResolutionResultFromCache` | Triggered when a user resolution result is retrieved from cache | **UserResolverModuleName:** | Module Name | Description | | ----------------------- | -------------------------------- | | `identify/authProvider` | From identify or auth provider | | `getTemporaryUsers` | From getting temporary users | | `getUsers` | From getting users | | `getHuddleUsers` | From getting huddle users | | `getSingleEditorUsers` | From getting single editor users | *** #### CommentResolverEvent | Event Type | Description | | ----------------------------------- | ------------------------------------------------------------------ | | `commentResolutionRequestFormed` | Triggered when a comment resolution request is formed internally | | `commentResolutionRequestTriggered` | Triggered when a comment resolution request is sent | | `commentResolutionResult` | Triggered when comment resolution completes successfully | | `commentResolutionError` | Triggered when an error occurs during comment resolution | | `commentResolutionResultFromCache` | Triggered when a comment resolution result is retrieved from cache | | `commentSaveRequestFormed` | Triggered when a comment save request is formed internally | | `commentSaveRequestTriggered` | Triggered when a comment save request is sent | | `commentSaveResult` | Triggered when comment save completes successfully | | `commentSaveError` | Triggered when an error occurs during comment save | | `commentDeleteRequestFormed` | Triggered when a comment delete request is formed internally | | `commentDeleteRequestTriggered` | Triggered when a comment delete request is sent | | `commentDeleteResult` | Triggered when comment delete completes successfully | | `commentDeleteError` | Triggered when an error occurs during comment delete | **CommentResolverModuleName:** | Module Name | Description | | ----------------------- | -------------------------------- | | `setDocuments` | From setDocuments call | | `getCommentAnnotations` | From getting comment annotations | | `getNotifications` | From getting notifications | *** #### AttachmentResolverEvent | Event Type | Description | | ---------------------------------- | ---------------------------------------------------------------- | | `attachmentSaveRequestFormed` | Triggered when an attachment save request is formed internally | | `attachmentSaveRequestTriggered` | Triggered when an attachment save request is sent | | `attachmentSaveResult` | Triggered when attachment save completes successfully | | `attachmentSaveError` | Triggered when an error occurs during attachment save | | `attachmentDeleteRequestFormed` | Triggered when an attachment delete request is formed internally | | `attachmentDeleteRequestTriggered` | Triggered when an attachment delete request is sent | | `attachmentDeleteResult` | Triggered when attachment delete completes successfully | | `attachmentDeleteError` | Triggered when an error occurs during attachment delete | *** #### ReactionResolverEvent | Event Type | Description | | ------------------------------------ | ------------------------------------------------------------------- | | `reactionResolutionRequestFormed` | Triggered when a reaction resolution request is formed internally | | `reactionResolutionRequestTriggered` | Triggered when a reaction resolution request is sent | | `reactionResolutionResult` | Triggered when reaction resolution completes successfully | | `reactionResolutionError` | Triggered when an error occurs during reaction resolution | | `reactionResolutionResultFromCache` | Triggered when a reaction resolution result is retrieved from cache | | `reactionSaveRequestFormed` | Triggered when a reaction save request is formed internally | | `reactionSaveRequestTriggered` | Triggered when a reaction save request is sent | | `reactionSaveResult` | Triggered when reaction save completes successfully | | `reactionSaveError` | Triggered when an error occurs during reaction save | | `reactionDeleteRequestFormed` | Triggered when a reaction delete request is formed internally | | `reactionDeleteRequestTriggered` | Triggered when a reaction delete request is sent | | `reactionDeleteResult` | Triggered when reaction delete completes successfully | | `reactionDeleteError` | Triggered when an error occurs during reaction delete | **ReactionResolverModuleName:** | Module Name | Description | | ------------------------ | --------------------------------- | | `setDocuments` | From setDocuments call | | `getReactionAnnotations` | From getting reaction annotations | *** #### 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 \| null` | Yes | Map of folder IDs to their metadata. `Null` while loading | | `nextPageToken` | `string` | Yes | Token for fetching next page of results | ### Documents #### FetchDocumentsRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------------------------------------------ | | `organizationId` | `string` | No | Organization ID to fetch documents from | | `documentIds` | `string[]` | No | Array of specific document IDs to fetch | | `folderId` | `string` | No | Folder ID to fetch documents from | | `allDocuments` | `boolean` | No | Whether to fetch all documents. Use with `organizationId` or `folderId`. | #### FetchDocumentsResponse *** | Property | Type | Required | Description | | --------------- | -------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `Record \| null` | Yes | Map of document groups to arrays of [DocumentMetadata](/api-reference/sdk/models/data-models#documentmetadata). `null` while loading. | | `nextPageToken` | `string` | Yes | Token for fetching next page of results. Default page size is 1000. | #### DocumentInitEvent *** * `DocumentInitEvent` can be of type: `boolean | undefined` * This represents the document initialization status. #### ErrorEvent *** | Property | Type | Required | Description | | -------------- | ---------- | -------- | -------------------------------------- | | `event` | `string` | No | The error event name | | `sourceMethod` | `string` | No | The method that triggered the error | | `documentIds` | `string[]` | No | Document IDs associated with the error | | `userId` | `string` | No | User ID associated with the error | | `timestamp` | `number` | No | Timestamp of the error | | `error` | `string` | No | Error details | | `code` | `string` | No | Error code | | `message` | `string` | No | Error message | | `source` | `string` | No | Source of the error | #### List of error codes: | Code | Description | | -------------------------------- | -------------------------------------------- | | `token_expired` | The JWT token has expired | | `same_user_editor_current_tab` | Same user is already editor in current tab | | `same_user_editor_different_tab` | Same user is already editor in different tab | | `another_user_editor` | Another user is already editor | #### SetUserAsEditorResponse *** | Property | Type | Required | Description | | -------- | ------------ | -------- | ----------------------------------------- | | `error` | `ErrorEvent` | No | Present when the action cannot be applied | #### LiveStateSingleEditorExternalUserPresence *** | Property | Type | Required | Description | | --------------------------- | ---------- | -------- | ------------------------------------------------------ | | `sameUserPresentOnTab` | `boolean` | No | True if the same user is present on a different tab | | `differentUserPresentOnTab` | `boolean` | No | True if a different user is present on a different tab | | `userIds` | `string[]` | No | User IDs of users present on a different tab | #### UserUpdateEvent *** * `UserUpdateEvent` will return data of type: `User | null` * If there is no user, it will return `null` else it will return the user object. #### VeltButtonClickEvent *** | Property | Type | Required | Description | | ----------------------------- | ------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `buttonContext` | `VeltButtonContext` | Yes | Button context | | `metadata` | `VeltEventMetadata` | Yes | Event metadata | | `commentAnnotation` | `CommentAnnotation` | No | Comment annotation object | | `comment` | `Comment` | No | Comment object | | `index` | `number` | No | Index of the repeated component the button is in. eg: Comment, Notification component. | | `commentAnnotations` | `CommentAnnotation[]` | No | Array of comment annotations | | `systemFilteredAnnotations` | `CommentAnnotation[]` | No | Filtered comment annotations | | `unreadCommentAnnotationsMap` | `{ [commentAnnotationId: string]: number }` | No | Map of unread comment counts | | `notification` | `Notification` | No | Notification object | | `notifications` | `Notification[]` | No | Array of notifications | | `customFilters` | `CustomFilters` | No | Custom filters applied in the Comment Sidebar. Only available when custom sidebar filters are used and when the button is in the sidebar. | #### PermissionProviderEvent *** | Property | Type | Required | Description | | ---------- | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- | | `type` | `string` | Yes | Event type: `'request'`, `'result'`, or `'error'` | | `userId` | `string` | Yes | User ID making the permission request | | `resource` | `{ id: string; type: string; context?: { access: { [key: string]: string \| number } } }` | Yes | Resource being accessed. Includes optional `context` field with access information set during setDocuments. | | `result` | `boolean` | No | Permission result (present when type is `'result'`) | | `error` | `string` | No | Error message (present when type is `'error'`) | #### RevokeAccessEvent *** | Property | Type | Required | Description | | -------------- | -------- | -------- | --------------------------------------------------------------- | | `userId` | `string` | Yes | User ID whose access is being revoked | | `resourceType` | `string` | Yes | Type of resource: `'document'`, `'folder'`, or `'organization'` | | `resourceId` | `string` | Yes | ID of the resource | | `trigger` | `string` | Yes | Trigger type: `'documentUnset'` or `'userLogout'` | | `timestamp` | `number` | Yes | Unix timestamp when revocation occurred | #### Config | Property | Type | Required | Description | | ----------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | `urlAllowList` | string\[] | No | Restricts Velt features to specific pages by specifying partial URL strings. | | `featureAllowList` | FeatureType\[] | No | Only allows the provided Velt features to run. | | `userPlanAllowList` | string\[] | No | Restricts Velt features to specific user plans. | | `userIdAllowList` | string\[] | No | Restricts Velt features to specific users. | | `usePrefersColorScheme` | boolean | No | If set to true, listens to changes on the `prefers-color-scheme` media query to set the global theme of Velt components. | | `globalStyles` | boolean | No | Controls whether Velt's global CSS styles are loaded. Default: true | #### Features *** | Property | Type | Required | Description | | ----------------- | ----------------- | -------- | -------------------------------------------------- | | `AREA` | `'area'` | No | Area feature for drawing areas/rectangles | | `ARROW` | `'arrow'` | No | Arrow feature for drawing arrows | | `AUDIO_HUDDLE` | `'audioHuddle'` | No | Audio huddle feature for voice conversations | | `COMMENT` | `'comment'` | No | Comment feature for adding comments | | `CURSOR` | `'cursor'` | No | Cursor feature for showing user cursors | | `HUDDLE` | `'huddle'` | No | Huddle feature for video conversations | | `LIVE_STATE_SYNC` | `'liveStateSync'` | No | Live state sync feature | | `PRESENCE` | `'presence'` | No | Presence feature for showing online users | | `TAG` | `'tag'` | No | Tag feature for adding tags | | `RECORDER` | `'recorder'` | No | Recorder feature for recording sessions | | `REWRITER` | `'rewriter'` | No | Rewriter feature for text rewriting | | `LIVE_SELECTION` | `'liveSelection'` | No | Live selection feature for showing user selections | #### VeltEventMetadata *** | Property | Type | Required | Description | | ---------------------- | -------------------------------- | -------- | --------------------- | | `organizationMetadata` | `OrganizationMetadata` \| `null` | No | Organization metadata | | `documentMetadata` | `DocumentMetadata` \| `null` | No | Document metadata | | `location` | `Location` \| `null` | No | Location information | #### VeltButtonContext *** | Property | Type | Required | Description | | ----------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------ | | `type` | `'button' \| 'button-toggle' \| 'multi-select' \| 'single-select'` | No | Type of button (default: 'button') | | `groupId` | `string` | No | ID of the button group | | `selections` | `VeltButtonSelectionMap` | No | Map of button selections grouped by button groupIds. For buttons without a group, the groupdId will be 'ungrouped' | | `clickedButtonId` | `string` | No | ID of the clicked button | #### VeltButtonSelectionMap *** | Property | Type | Required | Description | | ------------------- | --------------------------------- | -------- | ------------------------------------ | | `[groupId: string]` | `{ [buttonId: string]: boolean }` | No | Map of button selections for a group | #### UpdateDocumentsRequest *** | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | --------------------------------------------- | | `organizationId` | `string` | No | Unique identifier for the organization. | | `folderId` | `string` | No | Unique identifier for the folder. | | `documents` | `UpdateDocumentMetadata[]` | No | Array of document metadata objects to update. | #### UpdateDocumentMetadata *** \| Property | Type | Required | Description | \| --------------- | -------- | -------- | ----------------------------------- | ------------------------------------------------------- | \| `documentId` | `string` | Yes | Unique identifier for the document. | \| `[key: string]` | `T | string` | No | Additional custom properties for the document metadata. | #### Metadata *** | Property | Type | Required | Description | | --------------- | ---------------------- | -------- | ------------------------------------------------------- | | `apiKey` | `string` | Yes | API key associated with the event. | | `pageInfo` | `PageInfo` | No | Information about the page where the event occurred. | | `folderId` | `string` | No | Unique identifier for the folder. | | `locations` | `object` | No | Object containing location data indexed by location ID. | | `document` | `DocumentMetadata` | No | Document metadata associated with the event. | | `organization` | `OrganizationMetadata` | No | Organization metadata associated with the event. | | `[key: string]` | `any` | No | Additional custom properties. | #### DocumentMetadata *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------- | | `documentId` | `string` | Yes | Unique identifier for the document. | | `documentName` | `string` | No | Name of the document. | | `organizationId` | `string` | No | Unique identifier for the organization. | | `folderId` | `string` | No | Unique identifier for the folder. | | `[key: string]` | `any` | No | Additional custom properties. | #### OrganizationMetadata *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------- | | `organizationId` | `string` | Yes | Unique identifier for the organization. | | `[key: string]` | `any` | No | Additional custom properties. | #### PageInfo *** | Property | Type | Required | Description | | ------------- | -------- | -------- | --------------------------------- | | `baseUrl` | `string` | Yes | Base URL of the page. | | `path` | `string` | Yes | Path of the page. | | `queryParams` | `string` | No | Query parameters of the page URL. | | `title` | `string` | Yes | Title of the page. | | `url` | `string` | Yes | Full URL of the page. | #### VeltAuthTokenRequest *** | Property | Type | Required | Description | | ---------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `apiKey` | `string` | Yes | **API Key**. Must be provided, cannot be empty or whitespace only. | | `userId` | `string` | Yes | **User ID**. Must be provided, cannot be empty or whitespace only. | | `userProperties` | `UserProperties` | No | Additional user information to embed in the auth token. See below for details. | | `permissions` | `{ resources: Resource[] }` | No | Permissions configuration. Defines what resources the user can access and their access levels. If not provided, defaults to no resource access. | #### UserProperties *** | Property | Type | Required | Description | | --------------- | --------- | -------- | ------------------------------------------------------------------------------------ | | `isAdmin` | `boolean` | No | Whether the user is an admin. | | `name` | `string` | No | User's display name. If provided, cannot be empty or whitespace only. | | `email` | `string` | No | User's email address. If provided, cannot be empty and must be a valid email format. | | `[key: string]` | `any` | No | Allows flexibility for custom user attributes. | #### Permissions *** | Property | Type | Required | Description | | ----------- | ------------ | -------- | ----------------------------------------------------------------------------------------- | | `resources` | `Resource[]` | No | Array of resources the user has permission to access. Defaults to empty array if not set. | #### Resource *** Each resource represents something the user can access (organization, folder, or document). | Property | Type | Required | Description | | ---------------- | ------------------------------------------ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | `'organization' \| 'folder' \| 'document'` | Yes | Resource type. Must be one of: 'organization', 'folder', or 'document'. Determines the scope and level of access. | | `id` | `string` | Yes | Unique identifier for the specific resource. Cannot be whitespace only. For organization: the organization ID. For folder: the folder ID. For document: the document ID. | | `organizationId` | `string` | Conditionally | Organization ID. **Required** for `folder` and `document` types. Optional for `organization` type. Must be provided and non-empty for folder/document resources. Links the resource to a specific organization. | | `expiresAt` | `number` | No | Expiration timestamp (Unix timestamp). If provided, must be a positive integer, greater than the current time, and a valid number. Used for temporary access grants. | #### BaseMetadata *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------- | | `apiKey` | `string` | No | API key associated with the request. | | `documentId` | `string` | No | Unique identifier for the document. | | `organizationId` | `string` | No | Unique identifier for the organization. | | `folderId` | `string` | No | Unique identifier for the folder. | #### Document *** | Property | Type | Required | Description | | ---------- | ------------------ | -------- | ------------------------------------- | | `id` | `string` | Yes | Unique identifier for the document | | `metadata` | `DocumentMetadata` | Yes | Metadata associated with the document | #### SetDocumentsRequestOptions *** | Property | Type | Required | Description | | ----------------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `organizationId` | `string` | No | Organization ID for the documents | | `folderId` | `string` | No | Subscribe to all or provided documents in the given folder | | `locationId` | `string` | No | Filter and subscribe to document data for a specific location | | `allDocuments` | `boolean` | No | Subscribe to all documents in the folder. Use this when folderId is provided | | `rootDocumentId` | `string` | No | The unique identifier of the root document. Used to specify the root document when multiple documents are subscribed. | | `context` | [`SetDocumentsContext`](#setdocumentscontext) | No | Filter comments by custom context fields. Fetches comments matching all provided field values (AND logic across fields). When Permission Provider is enabled with `isContextEnabled: true`, each context value triggers a separate permission request. | | `debounceTime` | `number` | No | Per-call override for the debounce window (in ms) before emitting the document subscription. Overrides the global default for this call only. | | `optimisticPermissions` | `boolean` | No | When `false`, waits for permission validation to complete before returning. Defaults to `true` (optimistic). | #### FolderMetadata *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------------ | | `folderId` | `string` | No | Unique identifier for the folder | | `parentFolderId` | `string` | No | ID of the parent folder | | `folderName` | `string` | No | Display name of the folder | | `createdAt` | `number` | No | Timestamp when folder was created | | `lastUpdated` | `number` | No | Timestamp when folder was last updated | | `apiKey` | `string` | No | API key associated with the folder | | `organizationId` | `string` | No | Organization ID that the folder belongs to | #### CustomCss *** | Property | Type | Required | Description | | -------- | ------------------ | -------- | --------------------------------------------------------------------- | | `type` | 'link' \| 'styles' | Yes | The type of custom CSS, either a link to a CSS file or inline styles. | | `value` | string | Yes | The value of the custom CSS, either a URL or CSS styles. | ### Debug Info #### VeltDebugInfo *** | Property | Type | Required | Description | | ------------- | -------------------------------------------------------------------- | -------- | ---------------------------------------------- | | `veltVersion` | `string` | No | The version of the Velt SDK currently running | | `apiKey` | `string` | No | The API key used to initialize the Velt client | | `serverMap` | [`DebugInfoMap`](/api-reference/sdk/models/data-models#debuginfomap) | No | Debug information from the server-side state | | `clientMap` | [`DebugInfoMap`](/api-reference/sdk/models/data-models#debuginfomap) | No | Debug information from the client-side state | #### DebugInfoMap *** | Property | Type | Required | Description | | -------------- | ------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------ | | `organization` | [`OrganizationMetadata`](/api-reference/sdk/models/data-models#organizationmetadata) | No | Metadata about the current organization | | `documents` | [`DocumentMetadata[]`](/api-reference/sdk/models/data-models#documentmetadata) | No | Array of document metadata for all active documents | | `locations` | [`Location[]`](/api-reference/sdk/models/data-models#location) | No | Array of location information for all active locations | | `folder` | [`FolderMetadata`](/api-reference/sdk/models/data-models#foldermetadata) | No | Metadata about the current folder | | `user` | [`User`](/api-reference/sdk/models/data-models#user) | No | The currently authenticated user | ## Location #### Location | Property | Type | Required | Description | | --------------- | --------- | -------- | ----------------------------------------------- | | `id` | `string` | No | Unique identifier for the location. | | `locationName` | `string` | No | Name of the location. | | `version` | `Version` | No | Version information provided by the user. | | `[key: string]` | `any` | No | Additional dynamic properties for the location. | #### UpdateLocationsRequest *** | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | ---------------------------------------------- | | `organizationId` | `string` | No | Unique identifier for the organization. | | `documentIds` | `string[]` | No | Array of document IDs to update locations for. | | `locations` | `UpdateLocationMetadata[]` | No | Array of location metadata objects to update. | #### UpdateLocationMetadata *** \| Property | Type | Required | Description | \| --------------- | -------- | -------- | ----------------------------------- | ------------------------------------------------------- | \| `id` | `string` | Yes | Unique identifier for the location. | \| `[key: string]` | `T | string` | No | Additional custom properties for the location metadata. | #### LocationMetadata *** | Property | Type | Required | Description | | ------------ | ------------------ | -------- | ------------------------------------------------------------- | | `locationId` | number | No | Unique location id generated from client location information | | `location` | `Location` \| null | No | Location object provided by a client | #### SetLocationsRequestOptions *** | Property | Type | Required | Description | | ---------------- | --------- | -------- | ---------------- | | `rootLocationId` | `string` | No | Root location. | | `appendLocation` | `boolean` | No | Merge locations. | # Self Hosting #### PartialUser *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------------ | | `userId` | `string` | Yes | Unique identifier for the user | #### PartialReactionAnnotation *** | Property | Type | Required | Description | | -------------- | -------------- | -------- | ---------------------------------------- | | `annotationId` | `string` | Yes | ID of the reaction annotation | | `metadata` | `BaseMetadata` | No | Additional metadata | | `icon` | `string` | No | Icon for the reaction | | `from` | `PartialUser` | No | User who created the reaction annotation | #### ResolverActions *** An enum that defines the different types of actions that can trigger resolver events. | Name | Value | Description | | ---------------------------- | ------------------------------ | ------------------------------------------------------ | | `COMMENT_ANNOTATION_ADD` | `'comment_annotation.add'` | Triggered when a new comment annotation is added | | `COMMENT_ANNOTATION_DELETE` | `'comment_annotation.delete'` | Triggered when a comment annotation is deleted | | `COMMENT_ADD` | `'comment.add'` | Triggered when a new comment is added to an annotation | | `COMMENT_DELETE` | `'comment.delete'` | Triggered when a comment is deleted from an annotation | | `COMMENT_UPDATE` | `'comment.update'` | Triggered when a comment is updated | | `REACTION_ADD` | `'reaction.add'` | Triggered when a reaction is added to a comment | | `REACTION_DELETE` | `'reaction.delete'` | Triggered when a reaction is removed from a comment | | `ATTACHMENT_ADD` | `'attachment.add'` | Triggered when an attachment is added to a comment | | `ATTACHMENT_DELETE` | `'attachment.delete'` | Triggered when an attachment is deleted from a comment | | `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 →](/self-host-data/users#debugging) | Name | Value | Description | | ------------------------- | ------------------------- | -------------------------------------------------------- | | `IDENTIFY` | `'identify/authProvider'` | Resolver module for identifying and authenticating users | | `GET_TEMPORARY_USERS` | `'getTemporaryUsers'` | Resolver module for fetching temporary user data | | `GET_USERS` | `'getUsers'` | Resolver module for fetching user data | | `GET_HUDDLE_USERS` | `'getHuddleUsers'` | Resolver module for fetching huddle participant data | | `GET_SINGLE_EDITOR_USERS` | `'getSingleEditorUsers'` | Resolver module for fetching single editor user data | #### CommentResolverModuleName *** Enum defining module names for comment-related resolver operations. Used in data provider events to identify which module triggered the resolver call. [Self-Host Comment Data →](/self-host-data/comments#debugging) | Name | Value | Description | | ------------------------- | ------------------------- | -------------------------------------------------- | | `SET_DOCUMENTS` | `'setDocuments'` | Resolver module for setting comment documents | | `GET_COMMENT_ANNOTATIONS` | `'getCommentAnnotations'` | Resolver module for fetching comment annotations | | `GET_NOTIFICATIONS` | `'getNotifications'` | Resolver module for fetching comment notifications | #### ReactionResolverModuleName *** Enum defining module names for reaction-related resolver operations. Used in data provider events to identify which module triggered the resolver call. [Self-Host Reaction Data →](/self-host-data/reactions#debugging) | Name | Value | Description | | -------------------------- | -------------------------- | ------------------------------------------------- | | `SET_DOCUMENTS` | `'setDocuments'` | Resolver module for setting reaction documents | | `GET_REACTION_ANNOTATIONS` | `'getReactionAnnotations'` | Resolver module for fetching reaction annotations | #### 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 →](/self-host-data/recordings#debugging) | 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` | 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 *** As of v5.0.2-beta.11, the `metadata` object passed to `AttachmentDataProvider.delete()` contains only `apiKey`, `documentId`, `organizationId`, and `folderId`. The `attachmentId` and `commentAnnotationId` fields are no longer forwarded to the delete callback. They remain available in the `save()` callback metadata. | 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` | No | ID of the attachment. Not present in `delete()` callbacks (v5.0.2-beta.11+). | | `commentAnnotationId` | `string \| null` | No | ID of the comment annotation. Not present in `delete()` callbacks (v5.0.2-beta.11+). | | `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 | | `activity` | [`ActivityAnnotationDataProvider`](#activityannotationdataprovider) | No | Provider for activity log PII data | | `notification` | [`NotificationDataProvider`](#notificationdataprovider) | No | Provider for custom notification PII data | | `anonymousUser` | [`AnonymousUserDataProvider`](#anonymoususerdataprovider) | No | Provider to resolve email → userId mappings for anonymous users tagged by email in comments. | #### ResolverEndpointConfig *** Config-based resolver endpoint configuration. SDK handles HTTP requests, headers, and response formatting automatically. | Property | Type | Required | Description | | --------- | ------------------------ | -------- | ------------------------------------------- | | `url` | `string` | Yes | Backend endpoint URL for resolver operation | | `headers` | `Record` | No | Custom HTTP headers for the request | #### ResolverConfig *** | Property | Type | Required | Description | | -------------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------- | | `resolveTimeout` | `number` | No | Timeout duration (in milliseconds) for resolver operations | | `saveRetryConfig` | `RetryConfig` | No | Retry configuration for save operations | | `deleteRetryConfig` | `RetryConfig` | No | Retry configuration for delete operations | | `getRetryConfig` | `RetryConfig` | No | Retry configuration for get operations. Currently not supported for UserDataProvider. | | `resolveUsersConfig` | `ResolveUsersConfig` | No | Configuration for resolving users | | `getConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for fetch operations | | `saveConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for save operations | | `deleteConfig` | `ResolverEndpointConfig` | No | Config-based endpoint for delete operations | | `additionalFields` | `string[]` | No | Custom fields copied to resolver payloads but retained in Velt's storage | | `fieldsToRemove` | `string[]` | No | Fields stripped from Velt's storage before writing to your resolver endpoint | #### 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>>` | No | Function to fetch comment annotations | | `save` | `(request: SaveCommentResolverRequest) => Promise>` | No | Function to save comment annotations | | `delete` | `(request: DeleteCommentResolverRequest) => Promise>` | No | Function to delete comment annotations | | `config` | `ResolverConfig` | No | Configuration for the data provider | #### ReactionAnnotationDataProvider *** | Property | Type | Required | Description | | -------- | --------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------- | | `get` | `(request: GetReactionResolverRequest) => Promise>>` | No | Function to fetch reaction annotations | | `save` | `(request: SaveReactionResolverRequest) => Promise>` | No | Function to save reaction annotations | | `delete` | `(request: DeleteReactionResolverRequest) => Promise>` | No | Function to delete reaction annotations | | `config` | `ResolverConfig` | No | Configuration for the data provider | #### UserDataProvider *** | Property | Type | Required | Description | | -------- | ------------------------------------------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------- | | `get` | `(userIds: string[]) => Promise \| ResolverResponse>>` | No | Function to fetch user data by user IDs. Both response formats are supported for backward compatibility. | | `config` | `ResolverConfig` | No | Configuration for the data provider. Use `getConfig` for config-based approach. | #### GetUserResolverRequest *** Request format used by config-based user resolver endpoints. | Property | Type | Required | Description | | ---------------- | ---------- | -------- | -------------------------- | | `organizationId` | `string` | Yes | ID of the organization | | `userIds` | `string[]` | Yes | Array of user IDs to fetch | #### AttachmentDataProvider *** | Property | Type | Required | Description | | -------- | --------------------------------------------------------------------------------------------------- | -------- | ----------------------------------- | | `save` | `(request: SaveAttachmentResolverRequest) => Promise>` | No | Function to save attachment data | | `delete` | `(request: DeleteAttachmentResolverRequest) => Promise>` | 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>>` | No | Function to fetch recorder annotation PII data | | `save` | `(request: SaveRecorderResolverRequest) => Promise>` | No | Function to save recorder annotation PII data | | `delete` | `(request: DeleteRecorderResolverRequest) => Promise>` | 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 | #### NotificationDataProvider *** Provider for custom notification PII data. Only `notificationSource === 'custom'` notifications are routed through this resolver. | Property | Type | Required | Description | | -------- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------ | | `get` | `(request: GetNotificationResolverRequest) => Promise>>` | No | Fetch notification data from your backend | | `delete` | `(request: DeleteNotificationResolverRequest) => Promise>` | No | Delete notification data from your backend | | `config` | [`NotificationResolverConfig`](#notificationresolverconfig) | No | Configuration for the data provider | #### NotificationResolverConfig *** | Property | Type | Required | Description | | ------------------- | --------------------------------------------------- | -------- | ----------------------------------------------- | | `resolveTimeout` | `number` | No | Timeout in milliseconds for resolver operations | | `getRetryConfig` | [`RetryConfig`](#retryconfig) | No | Retry configuration for get operations | | `deleteRetryConfig` | [`RetryConfig`](#retryconfig) | No | Retry configuration for delete operations | | `getConfig` | [`ResolverEndpointConfig`](#resolverendpointconfig) | No | Config-based endpoint for fetch operations | | `deleteConfig` | [`ResolverEndpointConfig`](#resolverendpointconfig) | No | Config-based endpoint for delete operations | #### GetNotificationResolverRequest *** | Property | Type | Required | Description | | ----------------- | ---------- | -------- | ---------------------------------- | | `organizationId` | `string` | Yes | ID of the organization | | `notificationIds` | `string[]` | Yes | Array of notification IDs to fetch | #### DeleteNotificationResolverRequest *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------- | | `notificationId` | `string` | Yes | ID of the notification to delete | | `organizationId` | `string` | Yes | ID of the organization | #### PartialNotification *** Partial notification data returned by the notification resolver. All fields are optional except `notificationId`. | Property | Type | Required | Description | | ------------------------------------ | ----------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------- | | `notificationId` | `string` | Yes | ID of the notification | | `displayHeadlineMessageTemplate` | `string` | No | Template string for the notification headline message | | `displayHeadlineMessageTemplateData` | `{ actionUser?: User; recipientUser?: User; actionMessage?: string; [key: string]: any }` | No | Data to populate the headline message template | | `displayBodyMessage` | `string` | No | Body message of the notification | | `displayBodyMessageTemplate` | `string` | No | Template string for the notification body message | | `displayBodyMessageTemplateData` | `{ [key: string]: any }` | No | Data to populate the body message template | | `notificationSourceData` | `any` | No | Custom source data for the notification | | `[key: string]` | `any` | No | Additional custom fields | #### 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` | 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` | No | Map of chunk index to chunk URL for chunked uploads | | `recordingEditVersions` | `Record` | 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 \| 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 | #### ActivityAnnotationDataProvider *** | Property | Type | Required | Description | | -------- | ----------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ | | `get` | `(request: GetActivityResolverRequest) => Promise>>` | No | Function to fetch activity PII from your backend for re-hydration | | `save` | `(request: SaveActivityResolverRequest) => Promise>` | No | Function to store activity PII fields stripped before Velt writes to its backend | | `config` | `ResolverConfig` | No | Configuration for the data provider. Supports `resolveTimeout` and `fieldsToRemove`. | #### GetActivityResolverRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------------ | | `organizationId` | `string` | No | ID of the organization | | `activityIds` | `string[]` | No | Activity record IDs to fetch PII for | | `documentIds` | `string[]` | No | Document IDs to filter activity records by | #### SaveActivityResolverRequest *** | Property | Type | Required | Description | | ---------- | --------------------------------------- | -------- | ------------------------------------------------------- | | `activity` | `Record` | Yes | Map of activity record IDs to their stripped PII fields | | `event` | `string` | No | Resolver action that triggered the save | | `metadata` | `BaseMetadata` | No | Additional metadata | #### PartialActivityRecord *** Stripped activity record containing only PII fields routed to your data provider. | Property | Type | Required | Description | | ---------------------------- | ------------------------- | -------- | -------------------------------------------------------- | | `id` | `string` | Yes | Activity record ID | | `metadata` | `BaseMetadata` | No | Additional metadata attached to the activity record | | `changes` | `ActivityChanges` | No | Change snapshot captured at the time of the activity | | `entityData` | `unknown` | No | Feature-specific entity snapshot (e.g., comment body) | | `entityTargetData` | `unknown` | No | Target entity snapshot (e.g., the element commented on) | | `displayMessageTemplateData` | `Record` | No | Template variable values | | `[key: string]` | `any` | No | Additional custom fields configured via `fieldsToRemove` | #### AnonymousUserDataProvider *** | Property | Type | Required | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------ | | `resolveUserIdsByEmail` | `(request:` [`ResolveUserIdsByEmailRequest`](#resolveuseridsbyemailrequest)`) => Promise>>` | Yes | Callback to resolve email addresses to user IDs. | | `config` | [`AnonymousUserDataProviderConfig`](#anonymoususerdataproviderconfig) | No | Optional configuration for timeout and retry. | #### AnonymousUserDataProviderConfig *** | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | ------------------------------------------------------- | | `resolveTimeout` | `number` | No | Timeout in milliseconds for the resolve call. | | `getRetryConfig` | [`RetryConfig`](#retryconfig) | No | Retry configuration with `retryCount` and `retryDelay`. | #### ResolveUserIdsByEmailRequest *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ------------------------------------ | | `organizationId` | `string` | Yes | The organization ID. | | `documentId` | `string` | No | The document ID. | | `folderId` | `string` | No | The folder ID. | | `emails` | `string[]` | Yes | Array of email addresses to resolve. | # Presence #### PresenceUser *** | Property | Type | Required | Description | | ------------------ | ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | Unique user identifier | | `name` | `string` | No | User's full name (Default: Random avatar name) | | `email` | `string` | No | User's email address | | `photoUrl` | `string` | No | User's display picture URL (Default: Random avatar image) | | `onlineStatus` | `string` | Yes | Online status (active, away, offline) (Auto generated) | | `color` | `string` | No | Assigned color for the user (Auto generated) | | `timestamp` | `any` | Yes | Server Timestamp | | `type` | `string` | No | User type | | `selections` | `any` | No | User selections | | `documentParamsId` | `number \| null` | No | Deprecated unique document params ID | | `documentParams` | `object \| null` | No | Deprecated document params | | `locationId` | `number \| null` | No | Unique location ID | | `location` | `Location \| null` | No | Location of user on sub document | | `isReadOnly` | `boolean` | No | Indicates if user is readonly | | `isAnonymous` | `boolean` | No | If user can only view comments (Anonymous) | | `pageInfo` | `PageInfo` | Yes | Information about the page | | `isUserIdle` | `boolean` | No | Indicates if user is idle. This is based on the `inactivityTime` configured in the Presence feature. (Auto generated) | | `isTabAway` | `boolean` | No | Indicates if user's tab is unfocused. (Auto generated) | | `localOnly` | `boolean` | No | Whether this custom user is local-only (not persisted to DB). Only applicable to users added via addUser API. | | `initial` | `string` | No | Avatar initial. Defaults to first character of name, uppercased. Only applicable to users added via addUser API. | #### PresenceUserStateChangeEvent *** This event object is emitted when a user's online status changes to online. | Property | Type | Required | Description | | -------- | -------------- | -------- | ----------------------------------------------------------------------- | | `user` | `PresenceUser` | Yes | The current user's Presence object. | | `state` | `string` | Yes | The new presence state of the user (e.g., `online`, `offline`, `away`). | #### ENUMs | Enum Name | Event Type | Description | | ------------------- | ----------------- | ------------------------------------------------------------------------- | | `USER_STATE_CHANGE` | `userStateChange` | Triggered when a user's online status changes to online, offline, or away | #### PresenceRequestQuery *** | Property | Type | Required | Description | | ---------------- | ---------- | -------- | ---------------------------------------------------------------------------- | | `documentId` | `string` | No | ID of the document to query presence for. | | `organizationId` | `string` | No | ID of the organization to query presence for. | | `statuses` | `string[]` | No | Array of user statuses to filter by (e.g., `['online', 'away', 'offline']`). | #### GetPresenceDataResponse *** | Property | Type | Required | Description | | -------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------------------------- | | `data` | `PresenceUser[] \| null` | Yes | Array of [PresenceUser](/api-reference/sdk/models/data-models#presenceuser) objects. `null` while loading. | #### HeartbeatConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------------------------------------------------------------------- | | `userId` | `string` | No | User ID to retrieve heartbeat data for. If not provided, returns heartbeat data for the current user. | #### GetHeartbeatResponse *** | Property | Type | Required | Description | | -------- | --------------------- | -------- | ----------------------------------------------------------------------------------------------- | | `data` | `Heartbeat[] \| null` | Yes | Array of heartbeat data for the specified user. Returns null if no heartbeat data is available. | # Webhooks #### WebhookV2Payload *** | Property | Type | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------- | | `event` | `string` | Yes | The event type that triggered the webhook. | | `actionType` | `string` | Yes | The specific action that occurred. | | `source` | `string` | Yes | The source of the event. | | `data` | `CommentPayload \| HuddlePayload \| CRDTPayload \| RecorderPayload` | Yes | The payload data containing event-specific information. | | `webhookId` | `string` | Yes | Unique identifier for the webhook. | | `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences keyed by userId. | | `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences keyed by userId. | #### WebhookV2PayloadEncoded *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------- | | `encodedPayload` | `string` | Yes | Base64 encoded webhook payload. | #### WebhookV2PayloadEncrypted *** | Property | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------- | | `encryptedData` | `string` | Yes | Encrypted webhook data. | | `encryptedKey` | `string` | Yes | Encrypted encryption key. | | `iv` | `string` | Yes | Initialization vector for decryption. | #### CommentPayload *** | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ---------------------------------------------------------- | | `commentAnnotation` | `CommentAnnotation` | No | The comment annotation associated with the event. | | `targetComment` | `Comment` | No | The target comment for the event. | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata about the event context. | | `oldStatus` | `CommentStatus` | No | Previous status of the comment (for status change events). | | `newStatus` | `CommentStatus` | No | New status of the comment (for status change events). | | `newPriority` | `CommentPriority` | No | New priority of the comment (for priority change events). | #### HuddlePayload *** | Property | Type | Required | Description | | ------------ | ---------- | -------- | -------------------------------------------- | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata about the event context. | #### CRDTPayload *** | Property | Type | Required | Description | | ------------------------ | ---------------- | -------- | ---------------------------------------------------------------------------- | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata about the event context. | | `crdtData` | `object` | Yes | Contains the CRDT data and update information. | | `crdtData.id` | `string` | Yes | The editor/store ID for the CRDT instance. | | `crdtData.data` | `unknown` | Yes | The CRDT data. Can be any supported type: array, map, text, xml, or xmltext. | | `crdtData.lastUpdatedBy` | `string` | Yes | User ID who made the update. | | `crdtData.sessionId` | `string \| null` | No | Session ID if available. | | `crdtData.lastUpdate` | `string` | Yes | Timestamp of the last update. | #### RecorderPayload *** Payload delivered with `recorder.done` webhook events. | Property | Type | Required | Description | | ------------------- | --------------------------------------------------------- | -------- | ------------------------------------------------ | | `actionUser` | `User` | No | The user who triggered the recording action. | | `metadata` | `MetadataExternal` | No | Additional metadata about the event context. | | `recorderId` | `string` | No | The ID of the recorder instance. | | `from` | `User \| null` | No | The user who created the recording. | | `assets` | [`RecorderDataAsset[]`](#recorderdataasset) | No | The latest processed assets for the recording. | | `assetsAllVersions` | [`RecorderDataAsset[]`](#recorderdataasset) | No | All historical asset versions for the recording. | | `transcription` | [`RecorderDataTranscription`](#recorderdatatranscription) | No | Top-level transcription data for the recording. | #### RecorderDataAsset *** | Property | Type | Required | Description | | ----------------- | --------------------------------------------------------- | -------- | ------------------------------------------- | | `version` | `number` | No | Asset version number. | | `url` | `string` | Yes | Download URL for the recording asset. | | `mimeType` | `string` | No | MIME type of the asset (e.g., `video/mp4`). | | `fileName` | `string` | No | File name of the asset. | | `fileSizeInBytes` | `number` | No | File size in bytes. | | `fileFormat` | `'mp3' \| 'mp4' \| 'webm'` | No | File format of the asset. | | `thumbnailUrl` | `string` | No | URL for the recording thumbnail. | | `transcription` | [`RecorderDataTranscription`](#recorderdatatranscription) | Yes | Transcription data for this asset version. | #### RecorderDataTranscription *** | Property | Type | Required | Description | | -------------------- | ------------------------------------------------------------------- | -------- | ---------------------------------------------- | | `transcriptSegments` | [`RecorderDataTranscriptSegment[]`](#recorderdatatranscriptsegment) | No | Time-coded transcript segments. | | `vttFileUrl` | `string` | No | URL of the VTT subtitle file. | | `contentSummary` | `string` | No | AI-generated summary of the recording content. | #### RecorderDataTranscriptSegment *** | Property | Type | Required | Description | | -------------------- | -------- | -------- | ----------------------------------------- | | `startTime` | `string` | Yes | Segment start time as a formatted string. | | `endTime` | `string` | Yes | Segment end time as a formatted string. | | `startTimeInSeconds` | `number` | Yes | Segment start time in seconds. | | `endTimeInSeconds` | `number` | Yes | Segment end time in seconds. | | `text` | `string` | Yes | Transcript text for this segment. | #### RecorderTrigger *** Controls which Recorder webhook events fire for a workspace. Set via `triggers.recorder` in your workspace configuration. | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------------------------------------- | | `done` | `boolean` | No | Whether to fire the `recorder.done` event when a recording finishes. Default: `true`. | #### TriggersConfig *** Controls which webhook events fire for a workspace. Each property maps to a feature-specific trigger configuration. | Property | Type | Required | Description | | ---------- | ------------------------------------- | -------- | -------------------------------------------------- | | `comment` | [`CommentTrigger`](#commenttrigger) | No | Trigger configuration for comment webhook events. | | `huddle` | [`HuddleTrigger`](#huddletrigger) | No | Trigger configuration for huddle webhook events. | | `recorder` | [`RecorderTrigger`](#recordertrigger) | No | Trigger configuration for recorder webhook events. | #### CommentTrigger *** Controls which Comment webhook events fire for a workspace. | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------- | | `add` | `boolean` | No | Whether to fire comment add events. Default: `true`. | | `update` | `boolean` | No | Whether to fire comment update events. Default: `true`. | | `delete` | `boolean` | No | Whether to fire comment delete events. Default: `true`. | #### HuddleTrigger *** Controls which Huddle webhook events fire for a workspace. | Property | Type | Required | Description | | -------- | --------- | -------- | ------------------------------------------------------ | | `add` | `boolean` | No | Whether to fire huddle add events. Default: `true`. | | `update` | `boolean` | No | Whether to fire huddle update events. Default: `true`. | | `delete` | `boolean` | No | Whether to fire huddle delete events. Default: `true`. | #### 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`, `crdt`, or `recorder`. | | `actionUser` | `User` | No | The user who performed the action. | | `metadata` | `Metadata` | No | Additional metadata providing context for the event. | | `platform` | `'sdk'` | No | Set to `'sdk'` if the event originated from SDK actions. | | `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences keyed by userId. | | `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences keyed by userId. | #### WebhookV1PayloadEncoded *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------- | | `encodedPayload` | `string` | Yes | Base64 encoded webhook payload. | #### WebhookV1PayloadEncrypted *** | Property | Type | Required | Description | | --------------- | -------- | -------- | ------------------------------------- | | `encryptedData` | `string` | Yes | Encrypted webhook data. | | `encryptedKey` | `string` | Yes | Encrypted encryption key. | | `iv` | `string` | Yes | Initialization vector for decryption. | **Comment Basic Webhook Payload** Additional fields present when `notificationSource` is `comment`: | Property | Type | Required | Description | | ------------------- | ------------------- | -------- | ------------------------------------------------------------------------------------------- | | `commentAnnotation` | `CommentAnnotation` | Yes | The comment annotation associated with the event. | | `targetComment` | `Comment` | No | The target comment. Not present for annotation-level events (e.g., resolve, delete thread). | | `newPriority` | `CommentPriority` | No | New priority. Present on `priorityChanged` events. | | `oldStatus` | `CommentStatus` | No | Previous status. Present on `statusChanged` events. | | `newStatus` | `CommentStatus` | No | New status. Present on `statusChanged` events. | | `assigned` | `boolean` | No | Whether the comment is assigned. Present on `assigned` events. | **Huddle Basic Webhook Payload** No additional fields beyond the common fields when `notificationSource` is `huddle`. **CRDT Basic Webhook Payload** Additional fields present when `notificationSource` is `crdt`: | Property | Type | Required | Description | | ------------------------ | ---------------- | -------- | ---------------------------------------------------------------------------- | | `crdtData` | `object` | Yes | Contains the CRDT data and update information. | | `crdtData.id` | `string` | Yes | The editor/store ID for the CRDT instance. | | `crdtData.data` | `unknown` | Yes | The CRDT data. Can be any supported type: array, map, text, xml, or xmltext. | | `crdtData.lastUpdatedBy` | `string` | Yes | User ID who made the update. | | `crdtData.sessionId` | `string \| null` | No | Session ID if available. | | `crdtData.lastUpdate` | `string` | Yes | Timestamp of the last update. | | `accessDeniedUsers` | `array` | No | List of users denied access. | #### UserNotificationsConfig *** Per-user notification preferences included in webhook payloads when a notification config scope is active. Exactly one of the two fields is present per payload depending on whether org-level or document-level config is in use. | Property | Type | Required | Description | | -------------------------------------- | ------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------ | | `usersOrganizationNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user org-level notification preferences, keyed by userId. | | `usersDocumentNotificationsConfig` | [`Record`](#notificationchannelconfig) | No | Per-user document-level notification preferences, keyed by userId. | #### NotificationChannelConfig *** Per-channel notification preference map for a single user. Keys are channel identifiers; values are the preference level for that channel. ```typescript theme={null} type NotificationChannelConfig = Record; ``` | Key (channel) | Value | Description | | ------------- | --------------------------- | ------------------------------------- | | `inbox` | `'ALL' \| 'MINE' \| 'NONE'` | In-app inbox notification preference. | | `email` | `'ALL' \| 'MINE' \| 'NONE'` | Email notification preference. | | Value | Description | | ------ | -------------------------------------------------------------------- | | `ALL` | Receive notifications for all activity. | | `MINE` | Receive notifications only for activity directly involving the user. | | `NONE` | Receive no notifications for this channel. | # Misc #### RequestOptions *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ----------- | | `documentId` | `string` | No | Document ID | #### CommentSelectionChangeData *** | Property | Type | Required | Description | | ------------ | ------------------- | -------- | -------------------------------------- | | `selected` | `boolean` | Yes | Whether a comment is selected | | `annotation` | `CommentAnnotation` | Yes | Object data of the selected annotation | #### ContactListScopeForOrganizationUsers Enum *** | Enum Name | Event Type | Description | | ------------------------- | ----------------------- | ------------------------------ | | `ALL` | `all` | Show all the contacts | | `ORGANIZATION` | `organization` | Show organization contacts. | | `ORGANIZATION_USER_GROUP` | `organizationUserGroup` | Show organization user groups. | | `DOCUMENT` | `document` | Show document contacts. | #### CursorUser *** | Property | Type | Required | Description | | -------------- | ------------------------ | -------- | --------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | Unique user identifier that you use to identify your user. | | `name` | `string` | No | Your user's full name. Default: Random avatar name. | | `email` | `string` | No | Your user's email address. | | `photoUrl` | `string` | No | Your user's display picture URL. Default: Random avatar image. | | `comment` | `string` | No | Short comment that user can add to their live cursor. | | `onlineStatus` | `string` | Yes | User's online status (active, inactive, offline). Auto generated. | | `color` | `string` | No | A random color assigned to the user for the session, used on avatar border/live cursor. | | `timestamp` | `any` | Yes | Server Timestamp. | | `type` | `string` | No | User type. | | `locationId` | `number \| null` | No | Unique location id from provided location. | | `location` | `Location \| null` | No | Location to identify user on sub document. | | `position` | `CursorPosition \| null` | No | User's cursor position on their screen. | | `isReadOnly` | `boolean` | No | Indicates if user is readonly. | | `isAnonymous` | `boolean` | No | Indicates if user is anonymous and can only view comments. | #### FlockOptions *** | Property | Type | Required | Description | | -------------------------- | ------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `useHistoryAPI` | `boolean` | Yes | Indicates whether the application should use the HTML5 History API for navigation | | `onNavigate` | `(url: PageInfo) => void` | No | A callback function that is called when navigation occurs. It takes a `PageInfo` object as its argument, which contains details about the new page | | `disableDefaultNavigation` | `boolean` | Yes | If `true`, the application's default navigation handling is disabled, perhaps to be managed manually or by another system | | `darkMode` | `boolean` | Yes | A flag indicating whether the application should display in dark mode, a display preference that may be more comfortable for users in low-light conditions | #### Version *** | Property | Type | Required | Description | | -------- | ------ | -------- | --------------------------------- | | `id` | string | Yes | Unique identifier for the version | | `name` | string | Yes | Name of the version | #### displayHeadlineMessageTemplateData *** | Property | Type | Required | Description | | --------------- | -------- | -------- | --------------------------------------- | | `actionUser` | `User` | No | The user who performed the action | | `recipientUser` | `User` | No | The user receiving the notification | | `actionMessage` | `string` | No | The message describing the action | | `project` | `string` | No | The project related to the notification | | `[key: string]` | `any` | No | Any additional custom properties | #### PageInfo *** | Property | Type | Required | Description | | ------------- | -------- | -------- | -------------------------------------- | | `url` | `string` | No | URL of the webpage | | `path` | `string` | No | Path of the webpage excluding base url | | `baseUrl` | `string` | No | Base URL (domain) of a webpage | | `title` | `string` | No | Title of the webpage | | `commentUrl` | `string` | No | Reference url of a comment annotation | | `recorderUrl` | `string` | No | Reference url of a recorder annotation | | `screenWidth` | `number` | No | User's screen width. Auto generated. | #### `getThumbnailTag` Method The `getThumbnailTag` method takes an optional `url` parameter and returns an HTML string. It creates an anchor tag linking to the `videoPlayerUrl` and embeds an image tag using either the provided `url`, `thumbnailWithPlayIconUrl`, or `thumbnailUrl` (in that order of preference). #### RewriterAnnotation *** | Property | Type | Required | Description | | ------------------------ | ----------------------- | -------- | ------------------------------------------------------------------------------------- | | `annotationId` | String | Yes | Unique identifier for the rewriter annotation, automatically generated. | | `from` | `User` | Yes | The user who created this rewriter annotation. | | `color` | String | No | Color used for the rewriter annotation. | | `lastUpdated` | Any | No | Timestamp when the rewriter annotation was last updated, automatically generated. | | `documentParamsId` | Number \| null | No | Unique document params ID, deprecated, use `locationId` instead. | | `documentParams` | `Location` \| null | No | Document params to identify user on sub document, deprecated, use `location` instead. | | `locationId` | Number \| null | No | Unique location ID generated from provided location. | | `location` | Location \| null | No | Set location to identify user on sub document. | | `type` | String | No | Type of annotation. | | `rewriterType` | String | Yes | Type of rewriter for the annotation, either 'generic' or 'copywriter'. | | `targetTextRange` | TargetTextRange \| null | No | Selected text range of rewriter annotation. | | `annotationIndex` | Number | No | Index of the current annotation in the list of annotations. | | `pageInfo` | `PageInfo` | No | Information about the page where the annotation is made. | | `selectedRewriterOption` | String | No | Selected rewriter option used in the annotation. | #### TextSelectedEvent *** Emitted by `rewriterElement.on('textSelected')` when the user selects text in a Rewriter-enabled region. | Property | Type | Required | Description | | ----------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `selectionId` | `string` | Yes | Unique identifier for this selection instance. | | `text` | `string` | Yes | The raw text content of the user's selection. | | `targetTextRange` | `TargetTextRange` | Yes | DOM range describing the selected text position. Same type as [`RewriterAnnotation.targetTextRange`](#rewriterannotation). | #### RewriterAskAiRequest *** Request object for `rewriterElement.askAi()`. Proxies a text-generation call through Velt's backend. | Property | Type | Required | Description | | -------------- | --------------------- | -------- | --------------------------------------------------------------------------- | | `model` | [`AiModel`](#aimodel) | Yes | AI model identifier. Use a known string literal or any custom model string. | | `prompt` | `string` | Yes | Instruction or system prompt sent to the model. | | `selectedText` | `string` | Yes | The text the model should act on. | #### RewriterAskAiResponse *** Response from `rewriterElement.askAi()`. | Property | Type | Required | Description | | --------- | --------- | -------- | -------------------------------------------- | | `text` | `string` | Yes | Generated text returned by the AI model. | | `success` | `boolean` | Yes | Whether the request completed without error. | | `error` | `string` | No | Error message if `success` is `false`. | #### AiModel *** Open union type for AI model identifiers. Accepts any `OpenAiModel`, `AnthropicModel`, or `GeminiModel` string literal, or any arbitrary string for unlisted models. ```typescript theme={null} type AiModel = OpenAiModel | AnthropicModel | GeminiModel | (string & NonNullable); ``` #### OpenAiModel *** Known OpenAI model identifiers accepted by [`RewriterAskAiRequest`](#rewriteraskairequest). ```typescript theme={null} type OpenAiModel = | 'gpt-5.4' | 'gpt-5.4-pro' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-5' | 'gpt-4.1' | 'gpt-4o' | 'gpt-4o-mini' | 'gpt-4-turbo' | 'o3-pro' | 'o3' | 'o3-mini' | 'o4-mini'; ``` #### AnthropicModel *** Known Anthropic model identifiers accepted by [`RewriterAskAiRequest`](#rewriteraskairequest). ```typescript theme={null} type AnthropicModel = | 'claude-opus-4-6' | 'claude-sonnet-4-6' | 'claude-haiku-4-5' | 'claude-sonnet-4-5' | 'claude-opus-4-5' | 'claude-opus-4-1' | 'claude-sonnet-4-0' | 'claude-opus-4-0'; ``` #### GeminiModel *** Known Google Gemini model identifiers accepted by [`RewriterAskAiRequest`](#rewriteraskairequest). ```typescript theme={null} type GeminiModel = | 'gemini-3.1-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-flash-lite-preview' | 'gemini-2.5-flash' | 'gemini-2.5-flash-lite' | 'gemini-2.5-pro'; ``` #### RewriterReplaceTextRequest *** Request object for `rewriterElement.replaceText()`. | Property | Type | Required | Description | | -------- | ----------------------------------------- | -------- | ---------------------------------------------- | | `text` | `string` | Yes | Replacement text to insert into the DOM. | | `event` | [`TextSelectedEvent`](#textselectedevent) | Yes | The selection event that identifies the range. | #### RewriterReplaceTextResponse *** Response from `rewriterElement.replaceText()`. | Property | Type | Required | Description | | -------------- | --------- | -------- | -------------------------------------- | | `success` | `boolean` | Yes | Whether the replacement succeeded. | | `originalText` | `string` | Yes | The text that was replaced. | | `replacedText` | `string` | Yes | The text that was inserted. | | `error` | `string` | No | Error message if `success` is `false`. | #### RewriterAddCommentRequest *** Request object for `rewriterElement.addComment()`. | Property | Type | Required | Description | | -------- | ----------------------------------------- | -------- | -------------------------------------------------------- | | `text` | `string` | Yes | Initial comment body text. | | `event` | [`TextSelectedEvent`](#textselectedevent) | Yes | The selection event that anchors the comment annotation. | #### RewriterAddCommentResponse *** Response from `rewriterElement.addComment()`. | Property | Type | Required | Description | | -------------- | --------- | -------- | --------------------------------------------- | | `success` | `boolean` | Yes | Whether the comment was created successfully. | | `annotationId` | `string` | No | ID of the created comment annotation. | | `commentText` | `string` | No | The text stored on the created comment. | | `error` | `string` | No | Error message if `success` is `false`. | #### RewriterEventTypesMap *** Maps Rewriter event action names to their corresponding event payload types. Used internally by the `on()` method to provide typed event subscriptions. | Property | Type | Required | Description | | -------------- | ----------------------------------------- | -------- | ----------------------------------------- | | `textSelected` | [`TextSelectedEvent`](#textselectedevent) | Yes | Payload emitted when a user selects text. | #### SyncVideoPlayer *** | Property | Type | Required | Description | | ------------------ | -------------------- | -------- | ----------------------------------------------------- | | `playerId` | String | No | The identifier for the video player instance. | | `src` | String | No | The source URL of the video. | | `sources` | String\[] | No | An array of source URLs for the video. | | `lastUpdated` | Number | No | The timestamp of when the player was last updated. | | `lastUpdatedBy` | `User` | No | The user who last updated the player. | | `lastUpdatedEvent` | String | No | The name of the event that triggered the last update. | | `playerState` | SyncVideoPlayerState | Yes | The state object of the video player. | #### SyncVideoPlayerState *** | Property | Type | Required | Description | | ------------- | ------- | -------- | -------------------------------------------- | | `playing` | Boolean | No | Indicates if the video is currently playing. | | `currentTime` | Number | No | The current playback time of the video. | | `muted` | Boolean | No | Indicates if the video is muted. | | `volume` | Number | No | The volume level of the video. | | `speed` | Number | No | The playback rate of the video. | #### Toast *** | Property | Type | Required | Default Value | Description | | ---------- | -------------------- | -------- | ------------- | ------------------------------------------------------------------------ | | `id` | Number | No | None | A unique identifier for the toast notification. | | `message` | String | Yes | None | The message content displayed in the toast notification. | | `type` | 'success' \| 'error' | Yes | None | The type of toast notification, indicating success or error. | | `duration` | Number | No | 3000 | The length of time the toast notification is displayed, in milliseconds. | #### Transcription *** | Property | Type | Required | Description | | ------------------ | ------ | -------- | ----------------------------------------------------- | | `from` | User | Yes | The user who created the transcription. | | `lastUpdated` | Number | No | Timestamp of when the transcription was last updated. | | `transcriptedText` | String | No | The text that has been transcribed. | #### User *** | Property | Type | Required | Description | | ---------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- | | `userId` | string | Yes | Unique user identifier used to identify your user. | | `name` | string | No | The full name of your user. Defaults to a random avatar name if not provided. | | `photoUrl` | string | No | The display picture URL of your user. Defaults to a random avatar image if not provided. | | `email` | string | No | Required for sending email or Slack notifications to users about comments and mentions. | | `plan` | string | No | The product plan the user is on. | | `organizationId` | string | Yes | organizationId to which the user belongs. | | `color` | string | No | A color assigned to the user for the current session, used for avatar border, live cursor, selection etc. | | `textColor` | string | No | Used in the text color of the user's intial when photoUrl is not present. | | `type` | string | No | The type of user. | | `isReadOnly` | boolean | No | Indicates if the user has read-only access. | | `isAnonymous` | boolean | No | Indicates if the user is anonymous and can only view comments. | | `isGuest` | boolean | No | Indicates if the user is a guest. | | `isAdmin` | boolean | No | Use this to set the user as an admin. You also need to ensure that the jwt token you generate also has this property set to true. | | `groupId` | string | No | \[DEPRECATED] A domain name or identifier used to cluster a group of users who work together. | | `clientGroupId` | string | No | \[DEPRECATED] The original groupId provided by the user. | | `initial` | string | No | First letter of the user's first name. | | `accessRole` | "viewer" \| "editor" | No | Optional access role for this resource. Allowed values: “viewer” \| “editor”. Default: "editor". | **Access Control** - Set `accessRole` to `viewer` (read-only) or `editor` (read/write) on each resource to define the user's capabilities for that resource. - `accessRole` can only be set via the v2 Users and Auth Permissions REST APIs. Frontend SDK methods do not accept or change `accessRole`. - Relevant endpoints: `/v2/users/add`, `/v2/users/update`, `/v2/auth/permissions/add`, `/v2/auth/generate_token`. - See the [Access Control overview](/key-concepts/overview#access-control) for concepts and detailed guidance. #### UserOptions *** | Property | Type | Required | Description | | ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- | | `replaceContacts` | boolean | No | If set to true, it will replace the user's personal and group contacts with the ones provided. | | `authToken` | string | No | The authentication token of the user. | | `throwError` | boolean | No | If true, throws error if user authentication fails. Default: false. | #### UserContact *** A user object in a contact-selection context, such as autocomplete panels and assignment pickers. Shares the same shape as [`User`](#user). #### UserContactSelectedPayload *** | Property | Type | Required | Description | | ----------------------- | ----------------------------- | -------- | ------------------------------------- | | `contact` | [`UserContact`](#usercontact) | Yes | Selected user contact details. | | `isOrganizationContact` | boolean | Yes | Is user part of organization contact. | | `isDocumentContact` | boolean | Yes | Is user part of document contact. | | `documentAccessType` | string | Yes | Document access type. | #### UserContactUs *** | Property | Type | Required | Description | | ------------- | ------------------------ | -------- | ------------------------------------------------ | | `id` | string | No | Unique identifier of the feedback. | | `apiKey` | string \| null | No | API key of the client. | | `emailId` | string | No | Email address of the feedback provider. | | `message` | string | No | Content of the user's feedback message. | | `from` | User \| null | No | User who submitted the feedback. | | `lastUpdated` | any | No | Timestamp of when the feedback was last updated. | | `metadata` | DocumentMetadata \| null | No | Metadata associated with the document. | | `pageInfo` | PageInfo | No | Information about the user's current page. | #### UserFeedback *** | Property | Type | Required | Description | | ------------- | ------------------------ | -------- | ------------------------------------------------ | | `id` | string | No | Unique identifier of the feedback. | | `apiKey` | string \| null | No | API key of the client. | | `emailId` | string | No | Email address of the feedback provider. | | `message` | string | No | Content of the user's feedback message. | | `from` | User \| null | No | User who submitted the feedback. | | `lastUpdated` | any | No | Timestamp of when the feedback was last updated. | | `metadata` | DocumentMetadata \| null | No | Metadata associated with the document. | | `pageInfo` | PageInfo | No | Information about the user's current page. | #### UnreadCommentsCount *** | Property | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------- | | `count` | `number` | Yes | The number of unread comments or threads. | #### UserGroup *** | Property | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------- | | `groupId` | `string` | Yes | Unique identifier for the user group | | `groupName` | `string` | Yes | Display name of the user group | | `users` | `User[]` | No | Array of users that belong to this group | #### VeltResetButtonStateConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | ------------------------------------------------------------------------------- | | `id` | `string` | No | The ID of the button to reset. If not provided, resets all buttons | | `group` | `string` | No | The group ID of buttons to reset. If not provided, resets buttons in all groups | #### VeltAuthProvider *** | Property | Type | Required | Description | | --------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `user` | `User` | Yes | The user object to authenticate. | | `options` | `Options` | No | Additional options for authentication (e.g., `authToken`, `forceReset`). | | `retryConfig` | `{ retryCount?: number; retryDelay?: number; }` | No | Configuration for retrying token generation (number of retries and delay in ms). | | `generateToken` | `() => Promise` | No | Async function to generate a Velt JWT token. Called automatically when a token is required. | #### AuthRetryConfig *** | Property | Type | Required | Description | | ------------ | -------- | -------- | ----------------------------------------------------- | | `retryCount` | `number` | No | Number of times to retry token generation on failure. | | `retryDelay` | `number` | No | Delay in milliseconds between retry attempts. | #### RevokeAccessOn *** Configuration for automatic access revocation triggers. | Property | Type | Required | Description | | -------------------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------- | | `type` | [RevokeAccessOnType](#revokeaccessontype) | Yes | Type of trigger that will revoke access. Options: `document_unset` or `user_logout` | | `revokeOrganizationAccess` | `boolean` | No | Whether to also revoke organization-level permissions when triggered. Default: `false` | #### RevokeAccessOnType *** Enum specifying when to automatically revoke permissions. | Value | Description | | ---------------- | ---------------------------------------------------- | | `DOCUMENT_UNSET` | Revoke access when user unsets or leaves a document | | `USER_LOGOUT` | Revoke access when user logs out of the organization | #### PermissionSource *** Enum identifying which SDK method triggered the permission check. This helps debug and trace permission request origins. | Value | Description | | ------------------- | ----------------------------------------------------- | | `SET_DOCUMENTS` | Permission check triggered by `setDocuments()` method | | `IDENTIFY` | Permission check triggered by `identify()` method | | `GET_NOTIFICATIONS` | Permission check triggered by notifications fetching | | `SET_NOTIFICATIONS` | Permission check triggered by notifications setting | #### PermissionResourceType *** Enum defining the types of resources that can be validated through Permission Provider. Used in permission queries to identify the resource type being accessed. | Value | Description | | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `ORGANIZATION` | `organization`: Organization-level resource permissions | | `DOCUMENT` | `document`: Document-level resource permissions | | `LOCATION` | `location`: Location-specific resource permissions within a document | | `CONTEXT` | `context`: Context-based resource permissions. Added in v4.5.8-beta.4 for granular context-level access control when `isContextEnabled: true` | #### VeltPermissionProvider *** Configuration interface for Permission Provider. Velt validates access requests in real-time by querying your backend endpoint configured in the [Velt Console](https://console.velt.dev). The SDK automatically handles permission caching, validation, and synchronization. | Property | Type | Required | Description | | ------------------ | ------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `isContextEnabled` | `boolean` | No | Enable context-based permission requests. When enabled, the backend receives individual permission requests for each context value when using context filtering. Default: `false`. Added in v4.5.8-beta.4. | | `retryConfig` | [AuthRetryConfig](#authretryconfig) | No | Configuration for retrying failed permission requests. Defaults to 3 retries with 2000ms delay. | | `forceRefresh` | `boolean` | No | Set to `true` if access control changes frequently. Forces re-validation on each access check in the current session. Default: `false` | | `revokeAccessOn` | [RevokeAccessOn\[\]](#revokeaccesson) | No | Configure automatic access revocation triggers. Revokes permissions when specified events occur (e.g., document unset or user logout). | #### PermissionQuery *** Request structure for permission queries sent to the Permission Provider. | Property | Type | Required | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | ID of the user requesting access to the resource. | | `resource` | `{ type:` [PermissionResourceType](#permissionresourcetype)`; id: string; source:` [PermissionSource](#permissionsource)`; organizationId: string; context?:` [Context](#context) `}` | Yes | Resource the user is requesting access to. The `type` uses [`PermissionResourceType`](#permissionresourcetype) enum. The `source` field identifies which SDK method triggered the permission check. The optional `context` field is present only when `isContextEnabled: true` and contains context values set during setDocuments. Includes `organizationId` for context. | #### PermissionResult *** Individual permission decision for a user's access to a specific resource. | Property | Type | Required | Description | | ---------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | Unique identifier of the user requesting access. | | `resourceId` | `string` | Yes | Unique identifier of the resource being accessed. | | `type` | [PermissionResourceType](#permissionresourcetype) | Yes | Type of resource being accessed. Can be `organization`, `document`, `location`, or `context`. | | `organizationId` | `string` | Yes | Organization ID associated with the resource. | | `accessRole` | [UserPermissionAccessRole](#userpermissionaccessrole) | No | Access role granted to the user for this resource. | | `expiresAt` | `number` | No | Unix timestamp (in milliseconds) when the permission expires. | | `hasAccess` | `boolean` | Yes | Whether the user has access to the requested resource. | #### SignatureResult *** Response structure returned from the [Generate Signature API](/api-reference/rest-apis/v2/auth/generate-signature). | Property | Type | Required | Description | | ----------------------- | -------- | -------- | ------------------------------------------- | | `result.status` | `string` | Yes | Status of the response. Always `"success"`. | | `result.message` | `string` | Yes | Success message. | | `result.data.signature` | `string` | Yes | Generated authorization signature string. | **Example:** ```json theme={null} { "result": { "status": "success", "message": "Signature generated successfully.", "data": { "signature": "03638f2191bf59c0e536e5b31cbde86df5f44b03fc8e82ee9a8bed7eb324f252" } } } ``` #### PermissionData *** Individual permission decision for a user-resource pair. | Property | Type | Required | Description | | ------------ | ------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------- | | `userId` | `string` | Yes | ID of the user this permission applies to. | | `resourceId` | `string` | Yes | ID of the resource (document, folder, or organization). | | `type` | `'document' \| 'folder' \| 'organization'` | Yes | Type of the resource. | | `hasAccess` | `boolean` | Yes | Whether the user has access to the resource. | | `accessRole` | `'viewer' \| 'editor'` | No | Access role for the user. Only applicable for document resources. `viewer` can view and comment, `editor` can edit content. | | `expiresAt` | `number` | No | UTC timestamp in milliseconds when this permission expires. Velt will revalidate access after expiration. | #### Context *** The `Context` interface is used in Permission Provider backend requests for context-based permission validation. Each context value is sent as an individual permission request. | Property | Type | Required | Description | | -------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access` | `{ [key: string]: string \| number }` | Yes | Key-value pairs for context-based permissions. Keys are custom field names, values are single strings or numbers representing the specific context value being validated. | **Usage:** The `Context` interface is used in: * Backend Permission Provider requests when `isContextEnabled: true` * Each context value from frontend methods triggers a separate permission request with this format **Integration with Permission Provider:** When you enable context-based permissions (`isContextEnabled: true`), Velt automatically converts array values from [`SetDocumentsContext`](#setdocumentscontext) into individual permission requests using the `Context` interface format. #### SetDocumentsContext *** The `SetDocumentsContext` interface is used for filtering comments and notifications based on custom context fields when calling frontend SDK methods. This enables precise filtering based on your application's data model. | Property | Type | Required | Description | | -------- | -------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access` | `{ [key: string]: Array }` | Yes | Key-value pairs for filtering. Keys are custom field names, values are arrays of strings or numbers to filter by. Multiple values in an array use OR logic. | **Usage:** The `SetDocumentsContext` interface is used in: * `setDocuments()` method to fetch comments filtered by context * `identify()` method to filter notifications by context * Frontend SDK methods that require context filtering **Filtering Logic:** * **Within a field (OR logic)**: When multiple values are provided for a single field, comments/notifications matching any value are returned * **Across fields (AND logic)**: When multiple fields are provided, comments/notifications must match all field values **Permission Provider Integration:** When Permission Provider is enabled with `isContextEnabled: true`, each value in the arrays is sent as a separate permission request to your backend using the [`Context`](#context) interface format. This allows granular access control at the context value level. #### Options *** | Property | Type | Required | Description | | ------------ | --------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `authToken` | `string` | No | The authentication token for the user. | | `forceReset` | `boolean` | No | If true, forces the user to re-login. | | `throwError` | `boolean` | No | If true, throws error if user authentication fails. Default: false. | | `context` | [`SetDocumentsContext`](#setdocumentscontext) | No | Filter notifications by custom context fields. Fetches notifications matching any of the provided values (OR logic within a field). When Permission Provider is enabled with `isContextEnabled: true`, each context value triggers a separate permission request. | # React Flow Collaboration #### VeltReactFlowCrdtExtensionConfig *** Configuration for the `useVeltReactFlowCrdtExtension` React hook. | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialNodes` | `Node[]` | Yes | Initial set of nodes. Applied only when no server-side data exists. | | `initialEdges` | `Edge[]` | Yes | Initial set of edges. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. | #### VeltReactFlowCrdtExtensionResponse *** Interface extending [`VeltReactFlowAppState`](#appstate). | Property | Type | Description | | --------------- | ------------------------- | -------------------------------------- | | `store` | `Store` | ReactFlow CRDT store instance. | | `nodes` | `Node[]` | Array of nodes in the flow diagram. | | `edges` | `Edge[]` | Array of edges connecting the nodes. | | `onNodesChange` | `OnNodesChange` | Callback for handling node changes. | | `onEdgesChange` | `OnEdgesChange` | Callback for handling edge changes. | | `onConnect` | `OnConnect` | Callback for handling new connections. | | `setNodes` | `(nodes: Node[]) => void` | Function to set all nodes at once. | | `setEdges` | `(edges: Edge[]) => void` | Function to set all edges at once. | #### VeltReactFlowStoreConfig *** | Property | Type | Required | Description | | -------------- | -------- | -------- | ------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique ID for this collaborative React Flow instance. | | `veltClient` | `Velt` | Yes | Client from `useVeltClient()` for auth/session and syncing. | | `initialNodes` | `Node[]` | Yes | Initial set of nodes. Applied only when no server-side data exists. | | `initialEdges` | `Edge[]` | Yes | Initial set of edges. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for updates (milliseconds). | #### AppState *** | Property | Type | Description | | --------------- | ------------------------- | -------------------------------------- | | `nodes` | `Node[]` | Array of nodes in the flow diagram. | | `edges` | `Edge[]` | Array of edges connecting the nodes. | | `onNodesChange` | `OnNodesChange` | Callback for handling node changes. | | `onEdgesChange` | `OnEdgesChange` | Callback for handling edge changes. | | `onConnect` | `OnConnect` | Callback for handling new connections. | | `setNodes` | `(nodes: Node[]) => void` | Function to set all nodes at once. | | `setEdges` | `(edges: Edge[]) => void` | Function to set all edges at once. | #### Node (React Flow) *** | Property | Type | Required | Description | | ---------- | -------------------------- | -------- | -------------------------------------------- | | `id` | `string` | Yes | Unique node identifier. | | `type` | `string` | No | React Flow node type (e.g., `"input"`). | | `data` | `{ label?: string }` | No | Freeform node data (label used in examples). | | `position` | `{ x: number; y: number }` | Yes | Canvas position in px. | | `origin` | `[number, number]` | No | Optional anchor origin used in examples. | #### Edge (React Flow) *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------- | | `id` | `string` | Yes | Unique edge id. | | `source` | `string` | Yes | Source node id. | | `target` | `string` | Yes | Target node id. | #### NodeChange *** | Property | Type | Required | Description | | -------- | ------------------------------- | --------------- | ----------------------------- | | `type` | `'add' \| 'update' \| 'remove'` | Yes | Kind of change. | | `item` | `Node` | Yes (for `add`) | Node to add (as in examples). | #### EdgeChange *** | Property | Type | Required | Description | | -------- | ------------------------------- | --------------- | ----------------------------- | | `type` | `'add' \| 'update' \| 'remove'` | Yes | Kind of change. | | `item` | `Edge` | Yes (for `add`) | Edge to add (as in examples). | #### Connection *** | Property | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------- | | `source` | `string` | Yes | Source node id. | | `target` | `string` | Yes | Target node id. | | *…* | *varies* | No | Other React Flow fields as applicable. | #### ConnectionState (used in onConnectEnd) *** | Property | Type | Required | Description | | ---------- | ---------------- | -------- | -------------------------------------------- | | `isValid` | `boolean` | Yes | Whether the provisional connection is valid. | | `fromNode` | `{ id: string }` | Yes | Node the drag originated from. | # CodeMirror Collaboration #### VeltCodeMirrorCrdtExtensionConfig *** Configuration for the `useVeltCodeMirrorCrdtExtension` React hook. | Property | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialContent` | `string` | No | Initial CodeMirror document. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. | #### VeltCodeMirrorCrdtExtensionResponse *** Response returned by `useVeltCodeMirrorCrdtExtension`. | Property | Type | Description | | ----------- | ----------------------------- | ----------------------------------------------------- | | `store` | `VeltCodeMirrorStore \| null` | CodeMirror CRDT store instance. | | `isLoading` | `boolean` | `false` once store is initialized, `true` by default. | #### VeltCodeMirrorStoreConfig *** | Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `veltClient` | `Velt` | Yes | Velt client for Velt SDK integration. | | `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for updates (milliseconds). | # BlockNote Collaboration #### VeltBlockNoteCrdtExtensionConfig *** Configuration for the `useVeltBlockNoteCrdtExtension` React hook. | Property | Type | Required | Description | | ---------------- | -------- | -------- | ----------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialContent` | `string` | No | Initial BlockNote document (JSON string of blocks). | | `debounceMs` | `number` | No | Debounce time for update propagation in milliseconds. | #### VeltBlockNoteCrdtExtensionResponse *** Response returned by `useVeltBlockNoteCrdtExtension`. | Property | Type | Description | | --------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `collaborationConfig` | `{ fragment: any; provider: any; user: { name: string; color: string } } \| null` | Configuration object to pass into BlockNote’s `useCreateBlockNote({ collaboration })`. | | `store` | `VeltBlockNoteStore \| null` | BlockNote CRDT store instance. | | `isLoading` | `boolean` | `false` once store is initialized, `true` by default. | #### VeltBlockNoteStoreConfig *** Configuration for creating a BlockNote collaboration store. | Property | Type | Required | Description | | ------------------- | ------------------------ | -------- | ---------------------------------------------------------------------------------------- | | `editorId` | string | Yes | Unique document identifier used for syncing. | | `initialContent` | string | No | JSON string representing an array of blocks to seed the doc (parsed into Y.XmlFragment). | | `collection` | string | No | Backend collection name (e.g., persistence). Defaults internally. | | `debounceMs` | number | No | Debounce (ms) for update batching. | | `onSynced` | `(doc?: Y.Doc) => void` | No | Called after initial sync completes. | | `onConnectionError` | `(error: Error) => void` | No | Called if a connection error occurs. | | `veltClient` | `Velt` | No | Velt client used for auth/session context and user resolution. | # Tiptap Collaboration #### VeltTiptapCrdtExtensionConfig *** Configuration for the Tiptap CRDT extension that enables real-time collaborative editing. | Property | Type | Required | Description | | ---------------- | -------- | -------- | --------------------------------------------------------------------- | | `editorId` | `string` | Yes | Unique document identifier for synchronization. | | `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for update propagation (ms). | #### VeltTiptapCrdtExtensionResponse *** | Property | Type | Description | | ----------- | ---------------------------- | ----------------------------------------------------- | | `VeltCrdt` | `Extension \| null` | Tiptap Velt CRDT Extension. | | `store` | `VeltTipTapStore \| null` | Tiptap CRDT store instance. | | `isLoading` | `boolean` | `false` once store is initialized, `true` by default. | #### VeltTipTapStoreConfig *** Configuration for creating a Tiptap collaboration store. | Property | Type | Required | Description | | ---------------- | -------- | -------- | ------------------------------------------------------------------------------ | | `editorId` | `string` | Yes | Unique document identifier for synchronization. Use a different ID per editor. | | `veltClient` | `Velt` | Yes | Velt client for velt sdk integration | | `initialContent` | `string` | No | Initial editor content. Applied only when no server-side data exists. | | `debounceMs` | `number` | No | Debounce time for updates in milliseconds | #### VeltTipTapStore *** Represents the Tiptap collaboration store instance. Public API surface only; all other fields are private. | Method / Property | Type / Signature | Description | | ------------------------- | ------------------------------------- | --------------------------------------------------------- | | `constructor` | `(config: VeltTipTapStoreConfig)` | Creates a new store wrapper over Yjs + persistence. | | `initialize()` | `Promise` | Initializes the underlying Store and triggers callbacks. | | `getStore()` | `Store` | Returns the underlying CRDT store instance. | | `getYText()` (deprecated) | `Y.Text \| null` | Legacy text accessor; usually returns null (XML is used). | | `getYXml()` | `Y.XmlFragment \| null` | Accessor for XML fragment in the Yjs document. | | `getYDoc()` | `Y.Doc` | Accessor for the Yjs document. | | `isConnected()` | `boolean` | Collaboration readiness flag (initialized). | | `setStateFromVersion()` | `(version: Version) => Promise` | Restores document to a specific version. | | `destroy()` | `void` | Cleans up resources and marks instance uninitialized. | | `getCollabExtension()` | `Extension` | Tiptap Extension configured with current Yjs doc. | #### createVeltTipTapStore *** Factory method that constructs a `VeltTipTapStore`, calls `initialize()`, and returns it. | Parameter | Type | Required | Description | | --------- | ----------------------- | -------- | ------------------------------------ | | `config` | `VeltTipTapStoreConfig` | Yes | Configuration options for the store. | | Returns | Type | Description | | ------- | ---------------------------------- | --------------------------------------- | | result | `Promise` | Initialized store or `null` on failure. | # Core Collaboration #### StoreConfig``; *** | Property | Type | Required | Description | | ---------------- | ------------------------------------- | -------- | ------------------------------------------------------------------ | | `id` | `string` | Yes | Unique identifier for the collaborative store (e.g., document ID). | | `veltClient` | `Velt` | Yes | Velt client for SDK integration. | | `type` | `'array' \| 'map' \| 'text' \| 'xml'` | Yes | Backing CRDT data type for the store. | | `initialValue` | `T` | No | Optional initial value (e.g., `''` for text, `[]` for array). | | `enablePresence` | `boolean` | No | Enable realtime presence tracking (default: `true`). | | `debounceMs` | `number` | No | Debounce interval in ms for batching local updates before syncing. | #### YjsType *** `'array' | 'map' | 'text' | 'xml'` #### useVeltCrdtStore *** | Property | Type | Description | | --------------------- | ------------------------------------------ | ------------------------------------------- | | `value` | `T \| null` | Current value of the store. | | `versions` | `Version[]` | List of all stored versions. | | `store` | `Store \| null` | The underlying Velt Store instance. | | `update` | `(newValue: T) => void` | Updates the store value. | | `saveVersion` | `(name: string) => Promise` | Saves a new version and returns its ID. | | `getVersions` | `() => Promise` | Fetches all versions. | | `getVersionById` | `(id: string) => Promise` | Fetches a specific version by ID. | | `restoreVersion` | `(id: string) => Promise` | Restores the store to a specific version. | | `setStateFromVersion` | `(version: Version) => Promise` | Sets the store state from a version object. | # Encryption #### EncryptConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | ---------------------------------------------------- | | `data` | `T` | Yes | The payload to encrypt. | | `type` | `string` | No | Optional type hint to select an encryption strategy. | #### DecryptConfig *** | Property | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------------------- | | `data` | `R` | Yes | The payload to decrypt. | | `type` | `string` | No | Optional type hint to select a decryption strategy. | #### VeltEncryptionProvider *** | Property | Type | Required | Description | | --------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------- | | `encrypt` | `(config: EncryptConfig) => Promise` | Yes | Asynchronous function that encrypts data and returns the encrypted result. | | `decrypt` | `(config: DecryptConfig) => Promise` | Yes | Asynchronous function that decrypts data and returns the original value. | #### CrdtUpdateDataEvent *** Event emitted when CRDT data changes occur, triggered by webhook notifications. | Property | Type | Required | Description | | ------------ | ------------------------------------------------- | -------- | -------------------------------- | | `methodName` | `string` | Yes | Method that triggered the update | | `uniqueId` | `string` | Yes | Unique identifier for the event | | `timestamp` | `number` | Yes | Unix timestamp of the event | | `source` | `string` | Yes | Source of the data change | | `payload` | [`CrdtUpdateDataPayload`](#crdtupdatedatapayload) | Yes | Data change payload | #### CrdtUpdateDataPayload *** Payload containing details of the CRDT data update. | Property | Type | Required | Description | | --------------- | ---------------- | -------- | -------------------------------- | | `id` | `string` | Yes | Store identifier | | `data` | `unknown` | Yes | Updated data value | | `lastUpdatedBy` | `string` | Yes | User ID who made the last update | | `sessionId` | `string \| null` | Yes | Session ID or null | | `lastUpdate` | `string` | Yes | ISO timestamp of last update | #### 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 | # Provider Configuration #### VeltProviderConfig *** Configuration object passed to `VeltProvider` (React) or `initVelt()` (other frameworks) to customize SDK behavior, proxy routing, and security. | Property | Type | Required | Description | | ---------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------- | | `proxyDomain` | `string` | No | Base URL for proxying the Velt SDK via your own CDN or server. | | `proxyConfig` | [`ProxyConfig`](#proxyconfig) | No | Fine-grained proxy routing for individual Velt service hosts. Replaces `apiProxyDomain`. | | `apiProxyDomain` | `string` | No | **Deprecated.** Use `proxyConfig.apiHost` instead. Single proxy URL for all Velt API calls. | | `integrity` | `boolean` | No | Enable Subresource Integrity (SRI) check on the SDK bundle. Default: `false`. | #### ProxyConfig *** Fine-grained proxy routing configuration for individual Velt service hosts. Introduced in v5.0.2-beta.11. Replaces the single `apiProxyDomain` field. ```typescript theme={null} export interface ProxyConfig { cdnHost?: string; apiHost?: string; v2DbHost?: string; v1DbHost?: string; storageHost?: string; authHost?: string; forceLongPolling?: boolean; } ``` | Property | Type | Required | Description | | ------------------ | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cdnHost` | `string` | No | Proxy host for Velt CDN assets (SDK bundle, static resources). Replaces `https://cdn.velt.dev`. | | `apiHost` | `string` | No | Proxy host for Velt API calls. Replaces the deprecated `apiProxyDomain` field. Forwards to `https://api.velt.dev`. | | `v2DbHost` | `string` | No | Proxy host for persistence (Velt v2 database). Your proxy should forward to the persistence endpoint. | | `v1DbHost` | `string` | No | Proxy host for ephemeral Database (Velt v1 database). Replaces the `firebaseio.com` domain. When set, the SDK host-locks RTDB to prevent redirect to shard servers. See [Proxy Server](/security/proxy-server#proxying-realtime-database). | | `storageHost` | `string` | No | Proxy host for File Storage. Replaces `firebasestorage.googleapis.com`. | | `authHost` | `string` | No | Proxy host for Auth. Replaces `identitytoolkit.googleapis.com` and `securetoken.googleapis.com`. Cached in `localStorage` at init time to apply before token refresh on page reload. | | `forceLongPolling` | `boolean` | No | Force long-polling for persistence and Realtime Database connections instead of WebSockets. Default: `false`. | `apiProxyDomain` is deprecated as of v5.0.2-beta.11. Migrate to `proxyConfig.apiHost` for equivalent behavior. All other host overrides require the new `proxyConfig` fields.