- This feature is currently in beta and is subject to change.
- This is currently only compatible with
setDocuments
method. - Ensure that the data providers are set prior to calling
identify
method. - The data provider methods must return the correct status code (e.g. 200 for success, 500 for errors) and success boolean in the response object. This ensures proper error handling and retries.
- If you are using REST API to add or update comments, ensure that you set
isCommentResolverUsed
andisCommentTextAvailable
fields in the request object. Learn more
Overview
Velt supports self-hosting your comments and related data:- Comments can be stored on your own infrastructure, with only necessary identifiers on Velt servers.
- Velt Components automatically hydrate comment data in the frontend by fetching from your configured data provider.
- This gives you full control over comment data while maintaining all Velt collaboration features.
- This automatically also ensures that the in-app notifications content is not stored on Velt servers. The content is generated using the comments data in the frontend.
Email notifications via Velt’s SendGrid integration are not available when you self-host comment content. Since the content lives on your infrastructure, Velt cannot construct and send emails via the sendgrid integration. Instead, use Webhooks to receive events (e.g., mentions, replies), fetch the relevant comment/notification content from your database, and send emails from your own email provider.
How does it work?
- When comments are created, updated, deleted or requested, the SDK uses your configured
CommentAnnotationDataProvider
to handle storage and retrieval - The data provider implements
get
,save
, anddelete
methods to interact with your database - Velt handles the data mapping and realtime synchronization while delegating persistence of actual content to your infrastructure
- The data provider works at the Comment Annotation (Thread) level not at the individual Comment (Message) level.
- For write requests (save, delete), the operation is first performed on your database and only if we get a success response, the SDK will perform the operation on the Velt server. If the operation fails on your database, the SDK will not perform the operation on the Velt server.
- You can configure retries, timeouts, etc. for the data provider.
get
Method to fetch comments from your database. On error we will retry.- Param:
GetCommentResolverRequest
- Return:
Promise<ResolverResponse<Record<string, PartialCommentAnnotation>>>
save
Save comments to your database. Return a success or error response. On error we will retry.- Param:
SaveCommentResolverRequest
- Note in the
SaveCommentResolverRequest
object, you will receive the event name that triggered the save.
- Note in the
- Return:
Promise<ResolverResponse<T>>
If you are using REST API to add or update comments, ensure that you set
isCommentResolverUsed
and isCommentTextAvailable
fields in the request object. Learn moredelete
Delete comments from your database. Return a success or error response. On error we will retry.- Param:
DeleteCommentResolverRequest
- Return:
Promise<ResolverResponse<T>>
config
Configuration for the comment data provider.- Type:
ResolverConfig
Example Implementation
- React / Next.js
- Other Frameworks
Triggering Email Notifications when Self-Hosting
When you self-host content, use Webhooks to trigger emails from your own system:1
Enable relevant webhooks
Subscribe to comment-related events (e.g., user mentions, replies). See Webhooks basics.
2
Receive webhook and fetch content from your DB
Your server receives the webhook event. Use IDs from the payload (e.g.,
annotationId
, commentId
) to query your own comment and notification content from your database via your Data Provider.3
Assemble email content and recipients
Combine the webhook event context with the self-hosted content to build the subject, body, and list of recipients (e.g., mentioned users).
4
Send email via your provider
Use your own email service (SendGrid under your account, SES, Postmark, etc.) to send the email.
If you previously configured SendGrid in Velt Console, that configuration will not be used for self-hosted content. Use your own SendGrid account or another email provider from your server.
You now send email notifications from your own infrastructure while keeping content self-hosted.
Sample Data
- Stored on your database
- Stored on Velt servers