FastComments Image Chat enables interactive discussions on images by allowing users to click anywhere on an image to create discussion points. Users can click on specific parts of images to start conversations about those areas, creating visual markers that show where discussions are located.
This feature is perfect for design feedback, product reviews, educational materials with diagrams, photo galleries with commentary, and any scenario where you want contextual discussions anchored to specific image locations.
Getting Started 
Use Cases
Image Chat works great for design feedback where teams need to discuss specific elements in mockups or screenshots. Product review sites can let customers discuss specific features visible in product photos. Educational platforms can use it for discussing diagrams, maps, or scientific images. Photo galleries can become interactive with location-specific commentary. Real estate sites can let viewers discuss specific features visible in property photos.
Quick Start
Getting started with Image Chat is simple. You need the FastComments Image Chat script, an image element or container with an image, and a configuration object with your Tenant ID.
Installation
Add the Image 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 click anywhere on the image. When a click occurs, a visual square marker appears at that location and a chat window opens. Other users can see all the markers and click them to view or participate in those discussions. All discussions sync in real-time across all visitors.
The widget uses percentage-based positioning, so markers stay in the correct location even when the image resizes or is viewed on different screen sizes.
Live Demo
You can see Image 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 Responsive Design guide to understand how percentage-based positioning 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 Image Chat.
Examples
Basic Example
The simplest way to use Image Chat is to target a single image element. This example shows how to enable interactive discussions on an image:
Run Example with Container Element
You can also pass a container element that has an image inside it:
Run Example with Custom URL ID
By default, Image Chat uses the page URL combined with the image source and coordinates to identify conversations. You can provide a custom urlId:
Run This is useful if your URL structure changes but you want to maintain the same conversations, or if you want to share the same discussion points across multiple pages.
Example with Dark Mode
If your site has a dark background and the widget is not auto detecting it like it should, we can manually enable dark mode support:
Run Example with Custom Chat Square Size
You can adjust the size of the clickable squares that appear on the image. The size is specified as a percentage of the image width:
Run Example with Comment Count Callback
Track when comments are added or updated using the commentCountUpdated callback:
Example with Multiple Images
You can initialize Image Chat on multiple images. Each image will have its own independent discussion points:
Run Configuration Options
Overview
FastComments Image Chat extends the standard FastComments commenting widget, so it inherits all the configuration options from the base widget while adding a few specific to image annotations.
Required Configuration
tenantId
Your FastComments Tenant ID is required. You can find this in your FastComments dashboard.
FastCommentsImageChat(imageElement, {
tenantId: 'demo'
});Image Chat Specific Options
urlId
By default, Image Chat generates a unique identifier for each conversation based on the page URL, the image source, and the X/Y coordinates. You can override this with a custom urlId.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
urlId: 'my-custom-image-id'
});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.
chatSquarePercentage
Controls the size of the clickable chat markers as a percentage of the image width. The default is 5%, meaning each marker is 5% of the image width.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 8 // Larger, more visible markers
});Smaller values create less intrusive markers that work better for detailed images. Larger values make markers easier to see and click on busy images or for users on mobile devices.
hasDarkBackground
Enable dark mode styling when your page has a dark background.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});commentCountUpdated
A callback function that fires whenever the comment count changes. This is useful for updating UI elements like badges or page titles.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
commentCountUpdated: function(count) {
console.log('Total comments:', count);
document.getElementById('badge').textContent = count;
}
});Inherited Configuration Options
Since Image 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.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'es' // Spanish
});readonly
Make all conversations read-only. Users can view existing markers and discussions but cannot create new ones or reply.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
readonly: true
});sso and simpleSSO
Integrate with your authentication system using Single Sign-On.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
sso: {
// SSO configuration
}
});See the SSO documentation for full details on authentication options.
maxReplyDepth
Control how many levels deep replies can go. By default, Image Chat sets this to 0, meaning all comments are flat (no nested replies). You can change this if you want threaded conversations.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
maxReplyDepth: 3 // Allow 3 levels of nesting
});Internal Configuration
These options are automatically set by Image Chat and should not be overridden:
The productId is automatically set to 2 for Image 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 with fullscreen chat windows.
Target Element Flexibility
The first parameter to FastCommentsImageChat can be either an <img> element directly or a container element with an image inside:
// Direct image element
FastCommentsImageChat(document.getElementById('my-image'), config);
// Container with image inside
FastCommentsImageChat(document.querySelector('.image-wrapper'), config);The widget will find the image automatically if you pass a container element.
Complete Example
Here's an example showing multiple configuration options together:
FastCommentsImageChat(document.getElementById('product-image'), {
tenantId: 'demo',
urlId: 'product-v2-main',
chatSquarePercentage: 6,
hasDarkBackground: false,
locale: 'en',
commentCountUpdated: function(count) {
document.title = count > 0 ? `(${count}) Product Photo` : 'Product Photo';
},
sso: {
// Your SSO config
},
maxReplyDepth: 1
});For a complete list of all available configuration options inherited from the base widget, see the main FastComments configuration documentation.
Responsive Design
Percentage-Based Positioning
Image Chat uses percentage-based coordinates instead of pixel coordinates to position chat markers on images. When a user clicks on an image, the widget converts the pixel coordinates of the click into percentages of the image width and height. This approach ensures that markers remain in the correct location regardless of how the image is displayed.
For example, if a user clicks 250 pixels from the left edge of a 1000px wide image, the widget stores this as 25% from the left. When another user views the same image at 500px wide on a mobile device, the marker appears at 125 pixels from the left, which is still 25% of the width.
Benefits for Responsive Layouts
This percentage system makes Image Chat work seamlessly across all device sizes and orientations. Your images might be displayed at different sizes depending on screen width, CSS rules, or container constraints, but the markers always align correctly with the intended locations.
Users on desktop computers with large monitors see markers in the same relative positions as users on smartphones with small screens. The markers scale proportionally with the image itself.
Image Scaling and Aspect Ratio
As long as your image maintains its aspect ratio when scaling (which is the default browser behavior), the percentage-based markers will remain perfectly aligned. The widget assumes that images scale proportionally and calculates positions based on this assumption.
If you apply CSS that distorts the image aspect ratio (like using object-fit: cover with specific dimensions), the marker positions may not align correctly. For best results, allow images to scale naturally or use object-fit: contain to maintain aspect ratio.
Chat Square Sizing
The visual size of chat markers is also percentage-based. The chatSquarePercentage configuration option defaults to 5%, meaning each square is 5% of the image width. This ensures consistent visual weight across different image sizes.
On a 1000px wide image with the default 5% setting, markers are 50px square. On a 500px wide image, the same markers are 25px square. They remain proportional to the image size.
Mobile Behavior
On screens under 768px wide, Image Chat switches to a mobile-optimized layout. Chat windows open fullscreen instead of floating next to the marker. This provides better usability on small screens where floating windows would obscure too much of the image.
The markers themselves remain visible and clickable at their percentage-based positions. Users can still see where all discussions are located and tap markers to open the fullscreen chat interface.
Dynamic Image Loading
The percentage-based system works correctly even when images load asynchronously or change size after the page loads. The widget monitors the image element and recalculates marker positions whenever the image dimensions change.
If you're lazy-loading images or implementing responsive images with different sizes at different breakpoints, the markers automatically adjust when the image size changes.
Cross-Device Consistency
Because coordinates are stored as percentages in the database, a discussion created on a desktop computer appears at the exact same relative location when viewed on a tablet or phone. Users can collaborate across devices without any positioning inconsistencies.
This works bidirectionally. A discussion created by tapping a specific spot on a mobile device appears at the same relative position when viewed on a large desktop monitor.
Viewport Considerations
The widget calculates percentages relative to the image element itself, not the viewport. This means scrolling the page or changing the browser window size doesn't affect marker positions. Markers remain anchored to their locations on the image regardless of viewport changes.
Future-Proofing Content
The percentage-based approach makes your image discussions resilient to changes in layout, design, or device ecosystem. As new screen sizes and devices emerge, the existing discussions will continue to display correctly without requiring any updates or migrations.
Customization
Dark Mode Support
Image Chat includes built-in dark mode support. When you set hasDarkBackground: true in your configuration, the chat windows and UI elements automatically adjust to work well on dark backgrounds.
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
hasDarkBackground: true
});The dark mode styling applies to chat windows, marker squares, and all interactive elements. If your site has a dark mode toggle, you can reinitialize the widget when the mode changes, or use the body class approach described below.
Dynamic Dark Mode
If your site's dark mode is controlled by adding a .dark class to the body element, the Image Chat UI will automatically respect this without requiring reinitialization. The widget's styles are designed to respond to the presence of this class.
/* Your dark mode CSS */
body.dark {
background: #1a1a1a;
color: #ffffff;
}Custom Styling with CSS
You can customize the appearance of markers, chat windows, and other elements using CSS. The widget adds specific classes that you can target in your stylesheet.
The chat squares and windows use the FastComments comment bubble styling system, so any customizations you've applied to the standard commenting widget will also affect Image Chat.
Chat Square Sizing
The chatSquarePercentage option controls the size of the clickable markers. The default is 5% of the image width:
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
chatSquarePercentage: 7 // Larger, more visible squares
});Smaller values create more subtle markers that blend into the image. Larger values make markers more prominent and easier to click, especially on mobile devices or for accessibility purposes.
Mobile Behavior
On screens under 768px wide, Image Chat automatically switches to a mobile-optimized layout. Chat windows appear fullscreen instead of floating next to the markers, providing better usability on small screens.
The markers remain visible at their responsive positions on the image. Users can tap any marker to open the fullscreen chat interface. This behavior is built-in and doesn't require any configuration.
Chat Window Appearance
Chat windows are 300px wide on desktop with a 16px arrow pointing to the marker. 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.
Lazy Initialization
Chat windows initialize on hover for desktop users or immediately when created. This reduces the initial load overhead by only rendering the chat interface when users actually interact with a marker.
The lazy initialization happens transparently. Users don't notice any delay, but the browser doesn't need to render dozens of hidden chat windows if you have many markers on an image.
Localization
Image Chat supports all the same localization options as the standard FastComments widget. Set the locale option to display UI text in different languages:
FastCommentsImageChat(imageElement, {
tenantId: 'demo',
locale: 'fr' // French
});FastComments supports dozens of languages. The locale setting affects all UI text including prompts, buttons, and placeholder text.
Inherited Customization Options
Since Image 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 Image Chat UI will inherit those fonts from your page's CSS. The chat windows render inside your page's DOM and respect your existing typography settings.
For best results, ensure your custom fonts are loaded before initializing Image Chat, or accept that there may be a brief flash of unstyled text while fonts load.
Marker Visual Design
The square markers have a subtle visual design that makes them noticeable without overwhelming the image. You can customize their appearance with CSS if you want a different visual treatment.
The markers include hover states that provide feedback when users move their mouse over them. On touch devices, the tap interaction provides immediate feedback by opening the chat window.
Live Sync
Real-Time Updates
Image Chat uses WebSocket connections to sync all conversations in real-time across all connected users. When someone creates a new marker, adds a comment, or deletes a discussion, all other users viewing the same image see the update immediately without refreshing.
How WebSocket Sync Works
When you initialize Image 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 image.
The WebSocket system uses three types of broadcast messages for Image Chat. The new-image-chat event fires when someone creates a new marker on the image. The image-chat-updated event fires when someone updates an existing conversation. The deleted-image-chat event fires when someone deletes a marker.
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 a marker, 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.
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 markers, 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 marker 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.
Users can have your site open on multiple devices simultaneously, and all of them will stay in sync. A marker created on a desktop computer appears instantly on the user's tablet if both devices are viewing the same image.
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.
Offline Behavior
When users are completely offline, they can still view existing markers but cannot create new ones or see updates from others. The widget detects the offline state and displays appropriate messaging.
If a user attempts to create a marker while offline and then comes back online, the operation will fail rather than queue, ensuring data consistency. Users should retry the operation once their connection is restored.
Performance Impact
The WebSocket connection has minimal performance impact. The connection remains idle when no updates are occurring and only processes messages when activity happens. On a typical image with moderate marker activity, the WebSocket uses less CPU than rendering the image itself.
For pages with hundreds of simultaneous users and high marker creation activity, the system scales horizontally to maintain performance without impacting individual client connections.
Collaborative Use Cases
The real-time sync makes Image Chat particularly powerful for collaborative workflows. Design teams can review mockups together with everyone seeing marker placements in real-time. Customer support teams can collaboratively annotate screenshots to identify issues. Educational groups can discuss diagrams with all participants seeing each other's markers as they're created.
The immediate feedback creates a more engaging and productive collaborative experience compared to traditional comment systems where users need to refresh to see updates.
API Reference
API Overview
Image Chat provides three REST API endpoints for managing image conversations programmatically. These endpoints allow you to retrieve, create, and delete markers without using the browser widget.
All API endpoints require authentication and follow the standard FastComments API patterns. These are public endpoints that authenticate via browser cookies, not API keys.
Base URL
All Image Chat API endpoints are under:
https://fastcomments.com/comment-image-chatsAuthentication
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 image conversations for a specific image.
Endpoint
GET /comment-image-chats/:tenantId?urlId=<urlId>Parameters
tenantId (path parameter, required) is your FastComments Tenant ID.
urlId (query parameter, required) is the image 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 X/Y coordinates, 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
curl "https://fastcomments.com/comment-image-chats/demo?urlId=my-product-image" \
--cookie "your-session-cookie"Example Response
{
"status": "success",
"user": {
"id": "user123",
"username": "john_doe"
},
"conversations": [
{
"_id": "conv123",
"urlId": "my-product-image:/images/product.jpg:25:30",
"x": 25.5,
"y": 30.2
},
{
"_id": "conv456",
"urlId": "my-product-image:/images/product.jpg:60:45",
"x": 60.8,
"y": 45.1
}
],
"urlIdClean": "my-product-image",
"isSiteAdmin": false,
"tenantIdWS": "demo",
"urlIdWS": "my-product-image",
"userIdWS": "user123"
}Create Conversation
Create a new image conversation for a specific location on an image.
Endpoint
POST /comment-image-chats/:tenantIdParameters
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.
windowUrlId (string, required) is the URL combined with the image source and coordinates, for example my-page:/images/photo.jpg:25.5:30.2.
pageTitle (string, required) is the title of the page.
src (string, required) is the image source URL.
x (number, required) is the X coordinate as a percentage (0-100).
y (number, required) is the Y coordinate as a percentage (0-100).
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
curl -X POST "https://fastcomments.com/comment-image-chats/demo" \
--cookie "your-session-cookie" \
-H "Content-Type: application/json" \
-d '{
"urlId": "my-product-image",
"windowUrlId": "my-product-image:/images/product.jpg:25.5:30.2",
"pageTitle": "Product Gallery",
"src": "/images/product.jpg",
"x": 25.5,
"y": 30.2,
"createdFromCommentId": "comment789",
"broadcastId": "550e8400-e29b-41d4-a716-446655440000"
}'Example Response
{
"status": "success",
"createdChatId": "conv789"
}Delete Conversation
Delete an existing image conversation. This endpoint requires admin or moderator permissions, or the conversation must have been created by the authenticated user.
Endpoint
DELETE /comment-image-chats/:tenantId/:chatIdParameters
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
curl -X DELETE "https://fastcomments.com/comment-image-chats/demo/conv789" \
--cookie "your-session-cookie" \
-H "Content-Type: application/json" \
-d '{
"broadcastId": "550e8400-e29b-41d4-a716-446655440001"
}'Example Response
{
"status": "success"
}Coordinate System
The X and Y coordinates are stored as percentages of the image dimensions. X represents the horizontal position from the left edge (0 = left edge, 100 = right edge). Y represents the vertical position from the top edge (0 = top edge, 100 = bottom edge).
These percentage values can include decimals for precision. For example, x: 25.5 means 25.5% from the left edge of the image.
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:
{
"status": "error",
"message": "Conversation not found"
}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 Image 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.
Check out the live demo on our demo page to see Image Chat in action.