This is currently only compatible with setDocuments method.
Ensure that the data providers are set prior to calling identify method.
The data provider methods must return the correct status code (e.g. 200 for success, 500 for errors) and success boolean in the response object. This ensures proper error handling and retries.

Overview

Velt supports self-hosting your reactions and related data:

Reactions can be stored on your own infrastructure, with only necessary identifiers on Velt servers.
Velt Components automatically hydrate reaction data in the frontend by fetching from your configured data provider.
This gives you full control over reaction data while maintaining all Velt collaboration features.
This automatically also ensures that the in-app notifications content related to reactions is not stored on Velt servers. The content is generated using the reactions data in the frontend.

How does it work?

When users add or remove reactions:

The SDK uses your configured ReactionAnnotationDataProvider to handle storage
Your data provider implements three key methods:
- get: Fetches reactions from your database
- save: Stores reactions and returns success/error
- delete: Removes reactions from your database

The process works as follows: When a reaction operation occurs:

The SDK first attempts to save/delete the reaction on your database
If successful:
- The SDK updates Velt’s servers with minimal metadata
- The PartialReactionAnnotation object is updated with the reaction details including emoji, user, and metadata
- When the reaction is saved, this information is stored on your end
- Velt servers only store necessary identifiers, not the actual reaction content
If the operation fails, no changes are made to Velt’s servers and the operation is retried if you have configured retries.

You can configure retries, timeouts, etc. for the data provider. Here are the methods that you need to implement on the data provider:

get

Method to fetch reactions from your database. On error we will retry.

Frontend Example
Backend Endpoint Example (MongoDB)
Backend Endpoint Example (PostgreSQL)

const fetchReactionsFromDB = async (request) => {
  const response = await fetch('/api/velt/reactions/get', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const reactionDataProvider = {
  get: fetchReactionsFromDB,
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ reaction: reactionDataProvider }}
>
</VeltProvider>

// Build query from request
const { reactionAnnotationIds, documentIds, organizationId } = req.body;
const query = {};
if (reactionAnnotationIds?.length) {
  query.annotationId = { $in: reactionAnnotationIds };
}
if (documentIds?.length) {
  query.documentId = { $in: documentIds };
}
if (organizationId) {
  query.organizationId = organizationId;
}

const annotations = await collection.find(query).toArray();

// Convert to Record<annotationId, annotation>
const result = {};
for (const annotation of annotations) {
  result[annotation.annotationId] = annotation;
}

// Return response in required format
res.json({ data: result, success: true, statusCode: 200 });

// Build parameterized query
const { reactionAnnotationIds, documentIds, organizationId } = req.body;
const conditions = [];
const values = [];
let paramIndex = 1;

if (reactionAnnotationIds?.length) {
  conditions.push(`annotation_id = ANY($${paramIndex++})`);
  values.push(reactionAnnotationIds);
}
if (documentIds?.length) {
  conditions.push(`document_id = ANY($${paramIndex++})`);
  values.push(documentIds);
}
if (organizationId) {
  conditions.push(`organization_id = $${paramIndex++}`);
  values.push(organizationId);
}

const whereClause = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
const { rows } = await client.query(
  `SELECT annotation_id, data FROM reaction_annotations ${whereClause}`,
  values
);

// Convert to Record<annotationId, annotation>
const result = {};
for (const row of rows) {
  result[row.annotation_id] = row.data;
}

// Return response in required format
res.json({ data: result, success: true, statusCode: 200 });

save

Save reactions to your database. Return a success or error response. On error we will retry.

Param: SaveReactionResolverRequest
Return: Promise<ResolverResponse<T>>

Frontend Example
Backend Endpoint Example (MongoDB)
Backend Endpoint Example (PostgreSQL)

const saveReactionsToDB = async (request) => {
  const response = await fetch('/api/velt/reactions/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const reactionDataProvider = {
  save: saveReactionsToDB,
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ reaction: reactionDataProvider }}
>
</VeltProvider>

const { annotations, context } = req.body;

// Bulk upsert annotations
const operations = Object.entries(annotations).map(([id, annotation]) => ({
  updateOne: {
    filter: { annotationId: id },
    update: {
      $set: {
        ...annotation,
        annotationId: id,
        documentId: context?.documentId || annotation.documentId,
        organizationId: context?.organizationId || annotation.organizationId,
      }
    },
    upsert: true
  }
}));

if (operations.length > 0) {
  await collection.bulkWrite(operations);
}

// Return response in required format
res.json({ success: true, statusCode: 200 });

const { annotations, context } = req.body;

// Transaction-based upsert
await client.query('BEGIN');

for (const [id, annotation] of Object.entries(annotations)) {
  const data = { ...annotation, annotationId: id };

  await client.query(
    `INSERT INTO reaction_annotations (annotation_id, document_id, organization_id, data, updated_at)
     VALUES ($1, $2, $3, $4, NOW())
     ON CONFLICT (annotation_id)
     DO UPDATE SET data = EXCLUDED.data, updated_at = NOW()`,
    [id, annotation.documentId, annotation.organizationId, JSON.stringify(data)]
  );
}

await client.query('COMMIT');

// Return response in required format
res.json({ success: true, statusCode: 200 });

delete

Delete reactions from your database. Return a success or error response. On error we will retry.

Param: DeleteReactionResolverRequest
Return: Promise<ResolverResponse<T>>

Frontend Example
Backend Endpoint Example (MongoDB)
Backend Endpoint Example (PostgreSQL)

const deleteReactionsFromDB = async (request) => {
  const response = await fetch('/api/velt/reactions/delete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const reactionDataProvider = {
  delete: deleteReactionsFromDB,
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ reaction: reactionDataProvider }}
>
</VeltProvider>

const { annotationId } = req.body;

await collection.deleteOne({ annotationId });

// Return response in required format
res.json({ success: true, statusCode: 200 });

const { annotationId } = req.body;

await client.query(
  'DELETE FROM reaction_annotations WHERE annotation_id = $1',
  [annotationId]
);

// Return response in required format
res.json({ success: true, statusCode: 200 });

config

Configuration for the reaction data provider.

Type: ResolverConfig

const reactionResolverConfig = {
  resolveTimeout: 2000,
  saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
  deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};

Example Implementation

React / Next.js
Other Frameworks

const fetchReactionsFromDB = async (request) => {
  const response = await fetch('/api/velt/reactions/get', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const saveReactionsToDB = async (request) => {
  const response = await fetch('/api/velt/reactions/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const deleteReactionsFromDB = async (request) => {
  const response = await fetch('/api/velt/reactions/delete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const reactionResolverConfig = {
  resolveTimeout: 2000,
  saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
  deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};

const reactionDataProvider = {
  get: fetchReactionsFromDB,
  save: saveReactionsToDB,
  delete: deleteReactionsFromDB,
  config: reactionResolverConfig
};

<VeltProvider
  apiKey='YOUR_API_KEY'
  dataProviders={{ reaction: reactionDataProvider }}
>
</VeltProvider>

const fetchReactionsFromDB = async (request) => {
  const response = await fetch('/api/velt/reactions/get', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const saveReactionsToDB = async (request) => {
  const response = await fetch('/api/velt/reactions/save', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const deleteReactionsFromDB = async (request) => {
  const response = await fetch('/api/velt/reactions/delete', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(request)
  });
  return await response.json();
};

const reactionResolverConfig = {
  resolveTimeout: 2000,
  saveRetryConfig: { retryCount: 3, retryDelay: 2000 },
  deleteRetryConfig: { retryCount: 3, retryDelay: 2000 }
};

const reactionDataProvider = {
  get: fetchReactionsFromDB,
  save: saveReactionsToDB,
  delete: deleteReactionsFromDB,
  config: reactionResolverConfig
};

Velt.setDataProviders({ reaction: reactionDataProvider });

Sample Data

Reaction annotation stored on your database
Comment object stored on your database
Stored on Velt servers

{
    "ANNOTATION_ID": {
        "annotationId": "ANNOTATION_ID",
        "metadata": {
            "apiKey": "API_KEY",
            "documentId": "DOCUMENT_ID",
            "organizationId": "ORGANIZATION_ID",
            "folderId": "FOLDER_ID"
        },
        "reactions": {
            "REACTION_ID": {
                "reactionId": "REACTION_ID",
                "emoji": "thumbsup",
                "from": {
                    "userId": "USER_ID"
                },
                "createdAt": 1752638419744
            }
        },
        "from": {
            "userId": "USER_ID"
        }
    }
}

{
    "annotationId": "COMMENT_ANNOTATION_ID",
    "comments": {
        "COMMENT_ID": {
            "commentId": 123,
            "commentHtml": "<p>Great work on this feature!</p>",
            "commentText": "Great work on this feature!",
            "from": {
                "userId": "USER_ID"
            },
            "to": [
                {
                    "userId": "MENTIONED_USER_ID"
                }
            ],
            "taggedUserContacts": [
                {
                    "userId": "MENTIONED_USER_ID",
                    "contact": {
                        "userId": "MENTIONED_USER_ID"
                    },
                    "text": "@John"
                }
            ],
            "reactions": [
                {
                    "reactionId": "REACTION_ID",
                    "emoji": "thumbsup",
                    "from": {
                        "userId": "REACTOR_USER_ID"
                    },
                    "createdAt": 1752638419744
                },
                {
                    "reactionId": "REACTION_ID_2",
                    "emoji": "heart",
                    "from": {
                        "userId": "REACTOR_USER_ID_2"
                    },
                    "createdAt": 1752638420000
                }
            ]
        }
    },
    "metadata": {
        "documentId": "DOCUMENT_ID",
        "organizationId": "ORGANIZATION_ID"
    }
}

When a reaction is added to a comment, the comment object is updated with the reaction details including the emoji and user information.

{
    "reactions": [
        {
            "reactionId": "REACTION_ID",
            "type": "emoji",
            "lastUpdated": "2025-07-16T04:00:19.770Z",
            "createdAt": 1752638419744,
            "from": {
                "userId": "USER_ID"
            }
        }
    ],
    "from": {
        "userId": "USER_ID"
    },
    "lastUpdated": 1752638419745,
    "createdAt": 1752638412635,
    "annotationId": "ANNOTATION_ID",
    "metadata": {
        "apiKey": "API_KEY",
        "documentId": "DOCUMENT_ID",
        "organizationId": "ORGANIZATION_ID",
        "folderId": "FOLDER_ID"
    }
}

Only reaction identifiers and metadata are stored on Velt servers. The actual reaction content (emoji, user details) remains on your infrastructure.

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

Reactions

Overview

How does it work?

get

save

delete

config

Example Implementation

Sample Data

Get Started

Key Concepts

Async Collaboration

Realtime Collaboration

Self-Host Data

Model Context Protocol

Webhooks

Security

Miscellaneous

​Overview

​How does it work?

​get

​save

​delete

​config

​Example Implementation

​Sample Data

Overview

How does it work?

get

save

delete

config

Example Implementation

Sample Data