Add Inline Live Comments To Documents, Books, Etc
FastComments Collab Chat enables users to highlight and annotate any text content on your website, creating threaded discussions tied to specific text selections. Users can select words, sentences, or entire paragraphs to start collaborative conversations directly within your content.
This feature is perfect for editorial feedback, collaborative reading environments, educational platforms, document review, and any scenario where you want contextual discussions anchored to specific text.
Note that these docs are specific to the Collab Chat functionality. You can add commenting for content with lots of pages, like Books, with thread-per-page, without using collab chat. FastComments also does not charge per-page or per-thread. Collab Chat is specifically when you want to allow users to select text and comment on the highlighted section of text.
You can see an example here.
Getting Started 
Quick Start
Getting started with Collab Chat is simple. You need the FastComments Collab Chat script, an HTML element containing the text you want to annotate, and a configuration object with your Tenant ID.
Installation
Add the Collab Chat script to your page:
Basic Implementation
Here's a minimal example:
Run 
Replace 'demo' with your actual FastComments Tenant ID if it's not already, which you can find in your FastComments dashboard.
How It Works
Once initialized, users can select any text within the target element. After a brief delay (3.5 seconds on desktop), a prompt appears allowing them to start a discussion. When a discussion is created, a visual highlight appears on the text. Other users can hover over or click the highlight to view and participate in the discussion. All discussions sync in real-time across all visitors.
Live Demo
You can see Collab Chat in action on our live demo page.
Next Steps
Now that you have the basics working, you can customize the appearance and behavior in the Configuration Options guide. Check out the Text Selection Behavior guide to understand how text selection works. Learn about styling and dark mode support in the Customization guide. For advanced integrations, explore the API Reference.
Frontend Libraries
All FastComments frontend libraries (react, vue, angular, etc) have Collab Chat.
Examples
Basic Example
The simplest way to use Collab Chat is to target a single content container. This example shows how to enable text annotations on an article:
Run Example with Custom URL ID (Per Book Page, Article, etc)
By default, Collab Chat uses the page URL combined with the element path and text range to identify conversations. You can provide a custom urlId to have more control over how conversations are grouped:
This is useful if your URL structure changes but you want to maintain the same conversations, or if you want to share the same conversation annotations across multiple pages.
Example with Dark Mode
If your site has a dark background, enable dark mode support to ensure the chat UI looks correct:
Run Example with Top Bar Disabled
By default, Collab Chat shows a top bar with user count and discussion count. You can disable it:
Run Example with Comment Count Callback
You can track when comments are added or updated using the commentCountUpdated callback:
Example with Multiple Sections
You can initialize Collab Chat on multiple separate sections of your page. Each section will have its own independent annotations:
Adding Live Commenting to Online Books
You can initialize Collab Chat per page if desired, and have separate threads per page, simply pass the urlId parameter
a value like book-one-page1. This configuration also works for the normal commenting widget.
Configuration Options
Overview
FastComments Collab Chat extends the standard FastComments commenting widget, so it inherits all the configuration options from the base widget while adding a few specific to text annotations.
Required Configuration
tenantId
Your FastComments Tenant ID is required. You can find this in your FastComments dashboard.
Collab Chat Specific Options
urlId
By default, Collab Chat generates a unique identifier for each conversation based on the page URL, the DOM path to the element, and the selected text range. You can override this with a custom urlId.
This is useful when your URL structure might change but you want to keep the same conversations, or when you want to share annotations across multiple pages.
topBarTarget
Controls the display of the top bar which shows user count and discussion count. Set to null to disable the top bar entirely, or provide a DOM element to render it in a specific location.
hasDarkBackground
Enable dark mode styling when your page has a dark background. This detection is automatic, but it may be desirable to override it.
commentCountUpdated
A callback function that fires whenever the comment count changes. This is useful for updating UI elements like badges or page titles.
Inherited Configuration Options
Since Collab Chat extends the standard commenting widget, you can use any configuration option from the base FastComments widget. Here are some commonly used options:
locale
Set the language for the widget UI. FastComments supports dozens of languages.
readonly
Make all conversations read-only. Users can view existing annotations but cannot create new ones or reply.
sso and simpleSSO
Integrate with your authentication system using Single Sign-On.
See the SSO documentation for full details on authentication options.
maxReplyDepth
Control how many levels deep replies can go. By default, Collab Chat sets this to 0, meaning all comments are flat (no nested replies). You can change this if you want threaded conversations.
Internal Configuration
These options are automatically set by Collab Chat and should not be overridden:
The productId is automatically set to 3 for Collab Chat. The floating-chat extension is automatically loaded to provide the chat window functionality. The widget automatically detects mobile devices (screens under 768px wide) and adjusts the UI accordingly.
Complete Example
Here's an example showing multiple configuration options together:
For a complete list of all available configuration options inherited from the base widget, see the main FastComments configuration documentation.
Text Selection Behavior
How Text Selection Works
When users select text within the Collab Chat container, the widget captures that selection and allows them to start a discussion. The selection can be as small as a single word or as large as multiple paragraphs spanning different elements.
Selection Delay
On desktop devices, there's a 3.5 second delay between when a user selects text and when the discussion prompt appears. This prevents the UI from flickering when users are simply highlighting text to copy or read. On mobile devices, the prompt appears immediately since text selection is more deliberate on touch screens.
Unique Conversation IDs
Each conversation gets a unique urlId that combines the page URL, the DOM element path, and the serialized text range. This ensures that each text selection creates a distinct conversation that can be found again later.
If you provide a custom urlId in your configuration, it will be combined with the element path and text range to create the final identifier.
Visual Highlights
When a discussion exists for a particular text selection, that text receives a visual highlight. The highlight is implemented using background colors and appears on hover or when the associated chat window is open.
The highlighting system works by wrapping the selected text in a special element that can be styled. This approach ensures that highlights remain accurate even when the underlying HTML structure is complex.
Chat Window Positioning
When a user clicks on a highlight or creates a new annotation, a chat window appears near the selected text. The widget automatically calculates the best position for this window based on available viewport space.
The positioning system uses CSS classes like to-right, to-left, to-top, and to-bottom to indicate which direction the chat window should extend from the highlight. On mobile devices (screens under 768px wide), the chat window always appears fullscreen for better usability.
Chat Window Dimensions
Chat windows are 410px wide on desktop with 20px spacing and a 16px visual arrow pointing to the highlighted text. These dimensions are fixed to ensure consistent behavior, but you can customize the appearance with CSS.
Cross-Element Selections
Users can select text that spans multiple HTML elements, such as highlighting from the middle of one paragraph through the start of another. The range serialization system handles this correctly and will highlight all the selected text even across element boundaries.
Browser Compatibility
The text selection system uses the standard window.getSelection() API which is supported in all modern browsers. For older versions of Internet Explorer, it falls back to document.selection for compatibility.
Selection Persistence
Once a conversation is created for a text selection, that annotation persists even if the page is reloaded. The serialized range and DOM path allow the widget to restore highlights in the exact same location when users return to the page.
This works reliably as long as your page content remains stable. If you change the text content or restructure your HTML, existing annotations may no longer align correctly with the text. For this reason, it's best to avoid major content changes on pages with active annotations, or consider migrating annotations when content changes are necessary.
Customization
Dark Mode Support
Dynamic Dark Mode
If your site's dark mode is controlled by adding a .dark class to the body element, the Collab Chat UI will automatically respect this without requiring reinitialization. The widget's styles are designed to respond to the presence of this class.
Custom Styling with CSS
You can customize the appearance of highlights, chat windows, and other elements using CSS. The widget adds specific classes that you can target in your stylesheet.
Text highlights use the FastComments comment bubble styling system, so any customizations you've applied to the standard commenting widget will also affect Collab Chat.
Top Bar Customization
The top bar shows the number of users online and the number of discussions. You can customize its position by providing a custom element as the topBarTarget:
Or disable it entirely by setting it to null:
Mobile Behavior
On screens under 768px wide, Collab Chat automatically switches to a mobile-optimized layout. Chat windows appear fullscreen instead of floating next to the text, and the selection delay is removed for more immediate interaction.
This behavior is built-in and doesn't require any configuration. The widget detects screen size automatically and adjusts accordingly.
Chat Window Appearance
Chat windows are 410px wide on desktop with a 16px arrow pointing to the highlighted text. The windows position themselves automatically based on available viewport space, using positioning classes like to-right, to-left, to-top, and to-bottom.
You can add custom CSS to adjust colors, fonts, spacing, or other visual properties of these windows. The chat windows use the same component structure as the standard FastComments widget, so they inherit any global customizations you've applied.
Localization
Collab Chat supports all the same localization options as the standard FastComments widget. Set the locale option to display UI text in different languages:
FastComments supports dozens of languages. The locale setting affects all UI text including prompts, buttons, and placeholder text.
Inherited Customization Options
Since Collab Chat extends the standard commenting widget, it inherits all customization options from the base widget. This includes custom CSS classes, custom translations, avatar customization, date formatting, and much more.
See the main FastComments customization documentation for the complete list of customization options available.
Working with Custom Fonts
If your site uses custom fonts, the Collab Chat UI will inherit those fonts from your page's CSS. You may have to create a widget customization rule and @import any fonts in the custom CSS in that rule if you
want the floating chat window to use the same fonts.
Live Sync
Real-Time Updates
Collab Chat uses WebSocket connections to sync all conversations in real-time across all connected users. When someone creates a new annotation, adds a comment, or deletes a discussion, all other users viewing the same page see the update immediately without refreshing.
How WebSocket Sync Works
When you initialize Collab Chat, the widget establishes a WebSocket connection to the FastComments servers. This connection remains open for the duration of the user's session and listens for updates related to the current page.
The WebSocket system uses three types of broadcast messages for Collab Chat. The new-text-chat event fires when someone creates a new annotation on the page. The updated-text-chat event fires when someone updates an existing conversation. The deleted-text-chat event fires when someone deletes an annotation.
Broadcast ID System
To prevent echo effects where users see their own actions broadcast back to them, each update includes a unique broadcastId. When a user creates or updates an annotation, their client generates a UUID for that operation. When the WebSocket broadcasts the update back to all clients, the originating client ignores the update because it matches its own broadcastId.
This ensures smooth interaction where users see their changes immediately in the UI without waiting for the round-trip through the server, while still ensuring all other users get the update.
Live User Count
The top bar displays the number of users currently viewing the page. This count updates in real-time as users join and leave. The user count is provided through the same WebSocket connection and increments/decrements automatically based on connection and disconnection events.
Connection Resilience
If the WebSocket connection drops due to network issues or server maintenance, the widget automatically attempts to reconnect. During the reconnection period, users can still interact with existing annotations, but they won't see real-time updates from other users until the connection is reestablished.
Once reconnected, the widget resynchronizes to ensure no updates were missed. This happens transparently without requiring user intervention.
Bandwidth Considerations
WebSocket messages are lightweight and contain only the essential information needed to sync state. Creating a new annotation typically uses less than 1KB of bandwidth. The system also includes intelligent batching to reduce message frequency during high-activity periods.
Your usage metrics in the FastComments dashboard track pubSubMessageCount and pubSubBandwidth so you can monitor real-time sync activity across your sites.
Cross-Tab Synchronization
If a user has the same page open in multiple browser tabs, updates in one tab appear immediately in the other tabs. This works through the same WebSocket sync mechanism and doesn't require any additional configuration.
Security
WebSocket messages are transmitted over secure connections (WSS) and include tenant validation to ensure users only receive updates for conversations they're authorized to see. The server validates all operations before broadcasting them to prevent unauthorized access or manipulation.
API Reference
API Overview
Collab Chat provides three REST API endpoints for managing text conversations programmatically. These endpoints allow you to retrieve, create, and delete annotations without using the browser widget.
These are public endpoints that authenticate users via browser cookies. They do not use API keys. Users must be logged into FastComments in their browser to access these endpoints.
Base URL
All Collab Chat API endpoints are under:
Authentication
These endpoints authenticate users via browser cookies. They do not use API keys. Users must be logged into FastComments in their browser to access these endpoints.
Get All Conversations
Retrieve all text conversations for a specific page.
Endpoint
Parameters
tenantId (path parameter, required) is your FastComments Tenant ID.
urlId (query parameter, required) is the page identifier you want to retrieve conversations for.
Response
The response includes the API status, current user session information if authenticated, an array of conversations with their IDs, URLs, and text ranges, a cleaned URL identifier, a flag indicating if the current user is a site admin or moderator, and WebSocket connection details for live sync including tenantIdWS, urlIdWS, and userIdWS.
Example Request
Example Response
Create Conversation
Create a new text conversation for a specific text selection.
Endpoint
Parameters
tenantId (path parameter, required) is your FastComments Tenant ID.
The request body must be JSON and include these required fields.
urlId (string, required) is the base page identifier.
urlIdWithRange (string, required) is the URL combined with the text range, for example my-page:p:0:15,0:45{abc123}.
pageTitle (string, required) is the title of the page.
selector (string, required) is the DOM path to the element containing the selected text.
range (string, required) is the serialized text range in the format startOffset:endOffset,startOffset:endOffset{checksum}.
createdFromCommentId (string, required) is the ID of the comment that initiated this chat.
broadcastId (string, required) is a UUID for live synchronization to prevent echo effects.
Response
The response includes the API status and the ID of the newly created conversation.
Example Request
Example Response
Delete Conversation
Delete an existing text conversation. This endpoint requires admin or moderator permissions, or the conversation must have been created by the authenticated user.
Endpoint
Parameters
tenantId (path parameter, required) is your FastComments Tenant ID.
chatId (path parameter, required) is the ID of the conversation to delete.
broadcastId (request body, required) is a UUID for live synchronization.
Example Request
Example Response
Rate Limiting
These endpoints are subject to standard FastComments API rate limiting. The rate limit middleware applies per-tenant to prevent abuse while allowing normal usage patterns.
Error Responses
All endpoints return standard HTTP status codes. A 400 response indicates invalid request parameters. A 401 response means authentication failed. A 403 response indicates insufficient permissions. A 404 response means the conversation was not found. A 429 response indicates rate limit exceeded.
Error responses include a JSON body with details:
Usage Tracking
Creating conversations increments your conversationCreateCount usage metric. All WebSocket sync activity increments pubSubMessageCount and pubSubBandwidth. You can monitor these metrics in your FastComments dashboard under usage analytics.
Got Questions?
That's it for FastComments Collab Chat! If you have any questions, need help with implementation, or have feature suggestions, please let us know below or reach out to our support team.
For live examples, check out Govscent.org which uses Collab Chat in production.