Chat & Messaging
Production-ready messaging for web and mobile, ready to drop into your stack.
Building with an AI agent? Install this skill and start building instantly.
```bash theme={null}
npx @cometchat/skills add
```
### Step 1
Toggle mentions, reactions, media sharing, and more through our visual interface.
Get production-ready React code that plugs directly into your existing app.
It's based on our UI Kits—edit layouts, styles, or workflows as needed.
No manual component wiring required.
User/group info, moderation, and more included by default.
Same powerful UI Kits under the hood.
# CometChat CLI
Source: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/cli
Authenticate against the CometChat dashboard, provision app credentials, toggle features, and manage the AI agent skills — all from your terminal, with JSON output for scripting and CI.
CometChat ships two complementary command-line tools:
| Tool | Package | What it does |
| - | - | - |
| **Credentials CLI** (`cometchat`) | `@cometchat/skills-cli` | Dashboard authentication + app-credential provisioning + feature toggles |
| **Skills installer** | `@cometchat/skills` | Install, list, and verify the [AI Agent Skills](/agent-skills) |
Add CometChat to Your Frontend
Use our pre-built UI kits or SDKs to add chat to your website or mobile app instantly.
### UI Kit Builder
RECOMMENDED
Get a fully functional chat interface in minutes. Configure via our ui kit builder — no complex setup required.
### UI Kits - Components
Choose only what you need from the comprehensive UI Kit.
Compose your desired layout; apply custom styling or theming.
Each component includes its own chat logic—no SDK wiring per part.
No manual component wiring required.
User/group info, moderation, and more included by default.
Same powerful UI Kits under the hood.
Build your own chat interface using individual components. Each component includes built-in chat logic.
### SDKs
Initialize and connect to CometChat in your frontend application.
Create UI and flows from the ground up—exactly how you want them.
Full control over every aspect of the chat experience.
Live in minutes, not days.
No framework lock‑in or build steps.
Configure without code; theme when needed.
Build your own UI from scratch with our complete SDK feature set.
### Chat Widgets
Paste a single script into your site or CMS.
Toggle features, colors, and behavior from CometChat.
The widget appears instantly across your pages.
Live in minutes, not days.
No framework lock‑in or build steps.
Configure without code; theme when needed.
### Step 2
Add chat to any website with a simple script tag. Perfect for customer support and community chat.
## Sync Your Users
Sync your user database with CometChat for a seamless experience.
-
* Add users directly from the CometChat Dashboard.
* Ideal for quick testing or small teams.
-
* Create users via the SDK methods.
* Perfect for auto-provisioning during sign-up or login.
-
* Create users using the REST API.
* Best for batch imports or admin workflows.
## Sample Apps & Demos
See CometChat in action. Clone these sample apps to get started quickly.
## Products
Explore our core offerings to power your in-app communication needs.
## Features
Enhance your app with these powerful communication features.
More
Additional solutions to customize your CometChat experience.
## Resources
Search our comprehensive knowledge base for all your CometChat questions.
Experience CometChat in action with our live demo.
Stay ahead of the curve with the latest features.
Stay informed of any service interruptions.
Quick links to deeper integration guides, API references, and community support.
Dashboards & Visualization] Prometheus[Prometheus
Metrics Store] Loki[Loki
Log Store] NodeExporter[Node Exporter
Host Metrics] cAdvisor[cAdvisor
Container Metrics] Promtail[Promtail
Log Collection] Swarm[Docker Swarm
CometChat Services] Grafana -->|Query Metrics| Prometheus Grafana -->|Query Logs| Loki Prometheus -->|Scrape /metrics| NodeExporter Prometheus -->|Scrape /metrics| cAdvisor Promtail -->|Push Logs| Loki NodeExporter -->|Monitor| Swarm cAdvisor -->|Monitor| Swarm Promtail -->|Collect Logs| Swarm ``` ## Key metrics to monitor ### Infrastructure * CPU usage per node * Memory usage per node * Disk space and I/O * Network traffic * Container resource usage ### Application services * WebSocket active connections * Chat API request rate and latency * API error rates (4xx, 5xx) * Service uptime ### Data stores * **Kafka**: Consumer lag, message throughput * **Redis**: Memory usage, cache hit ratio, connected clients * **MongoDB**: Operation latency, connections, replication lag * **TiDB**: Query duration, region health, storage capacity ### Load balancer * NGINX request rate * Response status codes * Active connections ## Alerting Alerts should focus on user impact, capacity risks, and data integrity rather than raw metric noise. Set up alerts for these critical conditions: * CPU usage > 80% for 5 minutes * Memory usage > 85% for 5 minutes * Disk space \< 15% * Service down for 2 minutes * Database query latency > 100ms * Kafka consumer lag > 10,000 messages * Redis memory > 90% * WebSocket connection errors > 10/second * API error rate > 5% * Container restarts These thresholds are recommended starting points and should be adjusted based on workload characteristics and environment scale. ## Grafana dashboards Create dashboards to visualize: 1. **Overview**: System health, active users, request rates, error rates 2. **Infrastructure**: CPU, memory, disk, network per node 3. **WebSocket**: Active connections, message throughput, errors 4. **API**: Request rate, latency, error rates by endpoint 5. **Databases**: Query performance, connections, replication status 6. **Kafka**: Consumer lag, throughput, partition health 7. **Logs & Error Analysis**: Error aggregation, log volume, search, and correlation with metrics ### Logs & Error Analysis Dashboard This dashboard provides centralized visibility into application errors, log patterns, and system anomalies for rapid troubleshooting and incident investigation. **Key Visualizations:** * **Error Volume by Service**: Time-series graph showing error log count per service, helping identify which components are experiencing issues * **Top Error Messages**: Table displaying the most frequent error messages with occurrence counts, enabling quick identification of recurring problems * **Log Volume Trends**: Track total log volume over time to detect unusual spikes that may indicate issues or attacks * **Error Rate by Severity**: Breakdown of errors by severity level (CRITICAL, ERROR, WARNING) for prioritization * **Service Health Correlation**: Side-by-side view of error logs and service metrics (CPU, memory, latency) to correlate errors with resource constraints * **Search & Filter**: Interactive LogQL query panel for ad-hoc log searches and pattern matching * **Recent Critical Errors**: Live feed of the latest critical errors across all services for immediate awareness ## Log queries Use Loki's LogQL to search and filter logs across all services: ```logql theme={null} # View all errors {service="chat-api"} |= "error" # WebSocket connection issues {service="websocket"} |~ "connection.*failed" # API 5xx errors {service="nginx"} |~ "HTTP/[0-9.]+ 5[0-9]{2}" # High latency requests {service="chat-api"} | json | latency > 1000 ``` ## Troubleshooting ### First check Grafana dashboards Start with the Overview dashboard to determine blast radius before drilling into component-level dashboards. Confirm whether the issue is node-level, service-level, or data-store related before diving into individual components. ### Check Prometheus targets ```bash theme={null} curl http://localhost:9090/api/v1/targets ``` ### Check Loki status ```bash theme={null} curl http://localhost:3100/ready ``` ### View Promtail logs ```bash theme={null} docker service logs promtail ``` ### Check service metrics ```bash theme={null} # Node Exporter curl http://localhost:9100/metrics # cAdvisor curl http://localhost:8080/metrics ``` # On-Premise Deployment Overview Source: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/on-premise-deployment/docker/overview Deploy CometChat on-premise for self-hosted messaging, data sovereignty, compliance, predictable performance, and enterprise control. CometChat on-premise delivers an enterprise-grade, self-hosted real-time messaging platform engineered for mission-critical applications requiring complete data sovereignty, regulatory compliance, and predictable performance at scale. Built on battle-tested open-source technologies and cloud-native principles, this deployment architecture supports workloads from 10,000 to 250,000+ monthly active users with linear scalability and sub-100ms message latency. **This guide covers Docker Swarm deployments.** For Kubernetes deployments (recommended for 200k+ MAU or multi-region requirements), see the [Kubernetes deployment guide](../kubernetes/overview) or [contact us](https://www.cometchat.com/contact-sales) for enterprise support. **Enterprise Value Proposition** * **Data Sovereignty**: Complete control over data residency, encryption, and access policies to meet GDPR, HIPAA, SOC 2, and industry-specific compliance requirements * **Predictable Economics**: Eliminate per-user SaaS pricing with fixed infrastructure costs and transparent capacity planning * **Operational Control**: Full visibility into system behavior, customizable monitoring, and direct access to all components for troubleshooting and optimization * **Security Posture**: Deploy within your existing security perimeter with private networks, custom authentication integration, and air-gapped deployment options * **Performance Guarantees**: Achieve consistent sub-100ms latency with dedicated resources and optimized data locality ## Who this guide is for This comprehensive deployment guide is designed for technical decision-makers and implementation teams responsible for enterprise infrastructure: * **DevOps & SRE Teams**: Operations professionals managing production uptime, incident response, capacity planning, and continuous deployment pipelines * **Platform & Backend Engineers**: Technical leads architecting scalable systems, optimizing performance, and integrating real-time messaging into existing application ecosystems * **Infrastructure Architects**: Strategic planners designing multi-region deployments, disaster recovery strategies, compliance frameworks, and long-term scalability roadmaps * **Security & Compliance Officers**: Stakeholders ensuring data protection, access controls, audit logging, and regulatory adherence across all system components ## Platform capabilities CometChat on-premise provides a comprehensive suite of real-time communication features designed for enterprise applications: **Core Messaging Infrastructure** * **1:1 and Group Conversations**: Scalable messaging architecture supporting unlimited conversation threads with persistent message history, rich media attachments, and message threading * **Real-time Event Streaming**: WebSocket-based bi-directional communication delivering instant presence updates, typing indicators, delivery receipts, read receipts, and custom event propagation * **Message Delivery Guarantees**: Effectively-once message delivery semantics using idempotent producers, automatic retry logic, offline message queuing, and synchronization across multiple devices **Enterprise Features** * **Distributed Event Pipeline**: Apache Kafka-powered event backbone enabling decoupled microservices architecture, guaranteed message ordering, and fault-tolerant event processing at scale * **Push Notifications**: Multi-provider notification delivery supporting Firebase Cloud Messaging (FCM), Apple Push Notification Service (APNs), and custom webhook integrations with intelligent batching and delivery optimization * **Content Moderation**: Configurable policy engine with real-time profanity filtering, spam detection, image moderation, and extensible AI/ML adapter framework for custom moderation workflows * **Webhooks & Integrations**: Reliable outbound event delivery system with configurable retry policies, secure authentication, and comprehensive audit trails for third-party system integration **API & Developer Experience** * **RESTful APIs**: Comprehensive HTTP APIs for user management, conversation operations, group administration, metadata queries, and administrative functions with OpenAPI documentation * **Horizontal Scalability**: Stateless service design enabling linear scaling by adding compute resources without architectural changes or data migration * **Multi-tenancy Support**: Logical isolation of tenant data with tenant-specific configurations, rate limits, and resource quotas ## Data architecture & storage The platform employs a polyglot persistence strategy with multiple storage technologies optimized for specific data access patterns and consistency requirements: **Primary Data Stores** * **TiDB Cluster**: Horizontally scalable, MySQL-compatible distributed SQL database providing ACID transactions, automatic sharding, and multi-region replication. Composed of three components: * **Placement Driver (PD)**: Cluster metadata management and intelligent data placement * **TiKV**: Distributed key-value storage engine with Raft consensus for strong consistency * **TiDB SQL Layer**: MySQL-compatible query interface with distributed transaction coordination * **MongoDB**: Document-oriented database optimized for flexible schema evolution and semi-structured data with native JSON support and rich query capabilities * **Redis Clusters**: Dedicated in-memory data structure stores providing sub-millisecond latency for high-frequency operations: * **Cache Cluster**: Application-level caching, query result caching, and frequently accessed data * **Session & Rate Limiting Cluster**: User session management, authentication tokens, and distributed rate limiting counters **Event Streaming Platform** * **Apache Kafka**: Distributed commit log serving as the central event backbone for asynchronous communication between microservices * **Guarantees**: 100% real-time message delivery with sub-second latency, guaranteed message delivery with no message loss, configurable retention policies, and horizontal scalability **Optional Storage Systems** * **Object Storage**: S3-compatible storage (Amazon S3, MinIO, Ceph, or Google Cloud Storage) for unstructured data and large binary objects * **Features**: Lifecycle policies, versioning, encryption at rest, and cost-optimized storage tiers **Data Durability & Backup** * Automated backup strategies with point-in-time recovery capabilities * Configurable retention policies aligned with compliance requirements ## Deployment models CometChat on-premise supports multiple deployment architectures to match your operational maturity, scale requirements, and infrastructure preferences: ### Docker Swarm (Recommended: 10k-200k MAU) **Target Environment**: Production deployments up to \~200,000 monthly active users and \~20,000 peak concurrent connections **Characteristics**: * Lightweight orchestration with native Docker integration and minimal operational overhead * Predictable service placement with node constraints and resource reservations * Secure overlay networking with encrypted service-to-service communication * Rolling updates with configurable health checks and automatic rollback capabilities * Built-in load balancing and service discovery without external dependencies **Enterprise Benefits**: * Lower operational complexity compared to Kubernetes while maintaining production-grade reliability * Faster deployment cycles with straightforward configuration management * Reduced infrastructure costs with efficient resource utilization * Proven architecture supporting hundreds of production deployments **Recommended For**: Mid-market enterprises, SaaS platforms, healthcare applications, financial services, and organizations prioritizing operational simplicity *** ### Kubernetes (Enterprise & Multi-Region) For large-scale deployments exceeding 200,000 MAU, multi-region architectures, or advanced orchestration requirements, see the [Kubernetes deployment guide](../kubernetes/overview). ## High-level architecture The CometChat on-premise platform employs a modern, microservices-based architecture designed for enterprise-grade reliability, security, and performance. The system is built on proven open-source technologies and follows cloud-native principles to ensure operational excellence at scale.
Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to `false`, the widget does not automatically open the first conversation on load. Defaults to `true`. | ## 2. Create + Log In User On The Fly **Use this when:** * Every person already has an ID inside your product (email, username etc.) * You want that ID to drive their chat identity automatically ### Copy this into `` ```html theme={null} ``` ### Copy this into `` ```html lines highlight={8-9, 11, 14, 16, 20-22, 27-29} theme={null} ``` ### Update these values | Setting | What to enter / where to find it | | - | - | | `appID`, `region`, `authKey` | Copy from **[Dashboard](https://app.cometchat.com)** | | `uid` | Pass the unique ID from your page (for example `customer.id`). CometChat creates the user the first time it sees that ID. | | `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. | | `user.name`, `user.avatar`, `user.link` | Optional profile info you already store for that person. | | `mode` | Keep this as `"uid"` so the widget knows you’re logging in with IDs. | | `width`, `height`, `isDocked` |Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to `false`, the widget does not automatically open the first conversation on load. Defaults to `true`. | ## 3. Backend-Created User (Auth Token Login) **Use this when:** * People sign in through your backend, and you generate their CometChat auth token server-side. **Server-side flow (auth token login):** 1. Authenticate the user in your app. 2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call. 3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token. 4. Send the token to the browser and place it in the widget config below. 5. The same token works for the CometChat Widget, UI Kit, or SDK. Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31). ### Copy this into `` ```html theme={null} ``` ### Copy this into `` ```html lines highlight={8-9, 11, 13, 15, 19-20} theme={null} ``` ### Update these values | Setting | What to enter / where to find it | | - | - | | `appID`, `region` | Copy from **[Dashboard](https://app.cometchat.com)** | | `mode` | Keep as `"authToken"` so the widget expects a server-issued token. | | `authToken` | Generate on your **server**: (1) call the CometChat Auth Token API with your API key, (2) get the token for that user, (3) send it to the page and place it here. | | `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. | | `width`, `height`, `isDocked` |Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to `false`, the widget does not automatically open the first conversation on load. Defaults to `true`. | # CometChat Widget Builder For HTML Source: https://cometchat-22654f5b-docs-llms-scoped-indexes.mintlify.site/widget/html/overview CometChat Widget Builder for HTML is a no-code solution that lets you embed a fully functional chat interface into any HTML website using a simple code snippet. It provides a ready-to-use chat widget backed by CometChat's real-time infrastructure — no frontend framework required. With CometChat Widget Builder, you can: * Embed chat and calling into any HTML page * Customize themes, colors, and typography * Toggle features on and off * Go live with a simple embed code snippet The widget connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling.Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. | *** ## 2. Create + Log In User On The Fly **Use this when:** you already have user IDs (email, username, member ID) and want to log people in with that ID automatically. CometChat creates the user the first time it sees the ID. ### Add this to Site Settings → Custom Code → Head Code ```html theme={null} ``` ### Paste this into the Webflow Embed ```html theme={null} ``` ### Update these values | Setting | What to enter / where to find it | | - | - | | `appID`, `region`, `authKey` | Copy from **[Dashboard](https://app.cometchat.com)** | | `uid` | Pass the unique ID from your page (for example `member.id`, email, or a UUID). CometChat creates the user the first time it sees that ID. | | `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. | | `user.name`, `user.avatar`, `user.link` | Optional profile info you already store for that person. | | `mode` | Keep this as `"uid"` so the widget knows you’re logging in with IDs. | | `width`, `height`, `isDocked` |Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. | ### Memberstack auto-login (Webflow + Memberstack, still UID flow) Use this when your Webflow site uses Memberstack and you want the widget to log members in automatically (with a persistent guest fallback). **Step 1 — add Memberstack to Head (Site Settings → Custom Code → Head):** ```html theme={null} ``` **Step 2 — add the chat widget (Site Settings → Custom Code → Footer, or a page Embed):** ```html theme={null} ``` **Optional (without reload):** listen for Memberstack auth changes and swap users/guests. ```html theme={null} ``` *** ## 3. Backend-Created User (Auth Token Login) **Use this when:** people sign in through your backend and you generate their CometChat auth token server-side. This keeps your Auth Key off the page. **Server-side flow (auth token login):** 1. Authenticate the user in your app. 2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call. 3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token. 4. Send the token to the browser and place it in the widget config below. 5. The same token works for the CometChat Widget, UI Kit, or SDK. Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31). ### Paste this into the Webflow Embed ```html theme={null} ``` ### Update these values | Setting | What to enter / where to find it | | - | - | | `appID`, `region` | Copy from **[Dashboard](https://app.cometchat.com)** | | `mode` | Keep as `"authToken"` so the widget expects a server-issued token. | | `authToken` | Generate on your **server**: (1) call the CometChat Auth Token API with your API key, (2) get the token for that user, (3) send it to the page and place it here. | | `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. | | `width`, `height`, `isDocked` |Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. | *** ### Troubleshooting * **Widget not appearing?** Ensure the Embed is set to **Code** and the script loads (`chat-embed@1.x.x`). Publish the site after adding the snippet. * **Login/auth errors?** For UID mode, ensure the `uid` is unique and you’re using an **App Auth Key** (not REST API key). For auth token mode, make sure the token matches the logged-in user. * **Only guests showing?** Confirm you’re providing `uid` or `authToken` in the snippet and that your page logic passes the right IDs. * **Embed clipped?** Resize the Embed element to give the widget enough space (`width`/`height` also configurable in the config). *** ## Advanced JavaScript Controls The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly. ### Before you follow advanced setup steps 1. Keep the standard widget snippet (from the Integration guide) on your page. 2. Add another ` ``` ### Update these values | Setting | What to enter / where to find it | | - | - | | `appID`, `region`, `authKey` | Copy from **[Dashboard](https://app.cometchat.com)** | | `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. | | `user.name`, `user.avatar`, `user.link` | Optional guest display info—leave blank if you don’t need it. | | `width`, `height`, `isDocked` |Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. | *** ## 2. Create + Log In User On The Fly **Use this when:** you already have user IDs (email, username, member ID) and want to log people in with that ID automatically. CometChat creates the user the first time it sees the ID. ### Paste this into the Wix Embed HTML element ```html theme={null} ``` ### Update these values | Setting | What to enter / where to find it | | - | - | | `appID`, `region`, `authKey` | Copy from **[Dashboard](https://app.cometchat.com)** | | `uid` | Pass the unique ID from your page (for example `member.id`, email, or a UUID). CometChat creates the user the first time it sees that ID. | | `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. | | `user.name`, `user.avatar`, `user.link` | Optional profile info you already store for that person. | | `mode` | Keep this as `"uid"` so the widget knows you’re logging in with IDs. | | `width`, `height`, `isDocked` |Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. | *** ## 3. Backend-Created User (Auth Token Login) **Use this when:** people sign in through your backend and you generate their CometChat auth token server-side. This keeps your Auth Key off the page. **Server-side flow (auth token login):** 1. Authenticate the user in your app. 2. If it’s their first time, call **Create User** ([https://www.cometchat.com/docs/rest-api/users/create](https://www.cometchat.com/docs/rest-api/users/create)) — you can also request an auth token in that call. 3. For returning users, call **Create Auth Token** ([https://www.cometchat.com/docs/rest-api/auth-tokens/create](https://www.cometchat.com/docs/rest-api/auth-tokens/create)) to issue a fresh token. 4. Send the token to the browser and place it in the widget config below. 5. The same token works for the CometChat Widget, UI Kit, or SDK. Full walkthrough: [How to properly log in and create users in CometChat](https://community.cometchat.com/t/how-to-properly-log-in-and-create-users-in-cometchat/31). ### Paste this into the Wix Embed HTML element ```html theme={null} ``` ### Update these values | Setting | What to enter / where to find it | | - | - | | `appID`, `region` | Copy from **[Dashboard](https://app.cometchat.com)** | | `mode` | Keep as `"authToken"` so the widget expects a server-issued token. | | `authToken` | Generate on your **server**: (1) call the CometChat Auth Token API with your API key, (2) get the token for that user, (3) send it to the page and place it here. | | `language` | Optional locale for the widget UI. Defaults to `en-US`. Supported: `en-US`, `en-GB`, `fr`, `de`, `es`, `hi`, `ja`, `zh`, `zh-TW`, `pt`, `ru`, `it`, `nl`, `tr`, `ko`, `sv`, `ms`, `lt`, `hu`. | | `width`, `height`, `isDocked` |Adjust the widget width & height.
**isDocked = true** - appears as icon on page and expands when clicked.
**isDocked = false** - appears embedded on the page.
| | `variantID` | Specifies a particular version or snapshot of your widget configuration. If omitted, the first available variant is used. | | `chatType` | Determines the type of conversation the widget initiates by default (one-on-one user chat or a group chat). | | `defaultChatID` | The specific chat with user (`uid`) or group (`guid`) that should automatically open when the widget loads. | | `dockedAlignment` | Controls the position of the docked widget interface on the page (left side or right side). | | `autoOpenFirstItem` | When set to false, the widget does not automatically open the first conversation on load. Defaults to true. | *** ### Troubleshooting * **Widget not appearing?** Confirm the HTML Embed is set to **Code** and the script loads (`chat-embed@1.x.x`). Resize the embed box if it’s too small. * **Login/auth errors?** For UID mode, ensure the `uid` is unique and you’re using an **App Auth Key** (not REST API key). For auth token mode, make sure the token matches the logged-in user. * **Still showing guests only?** Make sure you’re actually providing `uid` or `authToken` in the snippet (and that your page logic passes the right IDs). * **Page preview vs published:** Test on a published page if preview blocks scripts. *** ## Advanced JavaScript Controls The embed works out of the box. Use the helpers below only if you need to open a specific chat, listen for widget events, or change settings on the fly. ### Before you follow advanced setup steps 1. Keep the standard widget snippet (from the Integration guide) on your page. 2. Add another `