diff --git a/ai-chatbots/custom-agents.mdx b/ai-chatbots/custom-agents.mdx index 0f67328e2..eb590b686 100644 --- a/ai-chatbots/custom-agents.mdx +++ b/ai-chatbots/custom-agents.mdx @@ -7,6 +7,24 @@ In CometChat, custom agents are unique users capable of autonomously sending and Users can interact with agents through private one-on-one conversations or within group chats. When an agent receives a message, whether from an individual chat or a group, CometChat relays that message to a `Callback URL` that you configure. Upon receiving the message, you can process it according to your business logic and send a response using CometChat's API. + +A **custom agent** lets you bring your own backend and AI logic — CometChat only forwards messages to your callback URL and posts your responses back. If you would rather configure an agent (tools, knowledge base, MCP servers) without running your own orchestration, use CometChat's native [Agent Builder APIs](/rest-api/ai-agents-apis/overview) instead. + + +The flow at a glance: + +```mermaid +sequenceDiagram + participant User + participant CometChat + participant Your Server + User->>CometChat: Sends a message to the agent + CometChat->>Your Server: HTTP POST to your Callback URL (JSON) + Your Server->>Your Server: Apply your business logic + Your Server->>CometChat: Send Bot Message REST API (agent's reply) + CometChat->>User: Delivers the agent's reply +``` + ## Create a callback endpoint ### Callback endpoint requirements @@ -57,4 +75,25 @@ The actual development and behavior of the agent are completely in your hands. A ### Responding as an agent -After your bot's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so. +After your agent's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so. This API posts a message authored by the agent's UID (`POST /bots/{uid}/messages`). + + +The exact JSON shape CometChat POSTs to your Callback URL is not documented on this page. Log the incoming request body from your endpoint to inspect it, or contact the CometChat team for the current payload reference. + + +## Next steps + + + + Configure a custom bot the same way as a custom agent. + + + Post the agent's reply back into the conversation. + + + Create the user account that backs the agent. + + + Build native agents with tools and knowledge bases instead. + + diff --git a/ai-chatbots/custom-bots.mdx b/ai-chatbots/custom-bots.mdx index 0fa867f2c..fe3ce996c 100644 --- a/ai-chatbots/custom-bots.mdx +++ b/ai-chatbots/custom-bots.mdx @@ -7,6 +7,24 @@ In CometChat, Custom bots are unique users capable of autonomously sending and r Users can interact with bots through private one-on-one conversations or within group chats. When a bot receives a message, whether from an individual chat or a group, CometChat relays that message to a `Callback URL` that you configure. Upon receiving the message, you can process it according to your business logic and send a response using CometChat's API. + +A **custom bot** lets you bring your own backend and logic — CometChat only forwards messages to your callback URL and posts your responses back. If you would rather configure an agent (tools, knowledge base, MCP servers) without running your own orchestration, use CometChat's native [Agent Builder APIs](/rest-api/ai-agents-apis/overview) instead. + + +The flow at a glance: + +```mermaid +sequenceDiagram + participant User + participant CometChat + participant Your Server + User->>CometChat: Sends a message to the bot + CometChat->>Your Server: HTTP POST to your Callback URL (JSON) + Your Server->>Your Server: Apply your business logic + Your Server->>CometChat: Send Bot Message REST API (bot's reply) + CometChat->>User: Delivers the bot's reply +``` + ## Create a callback endpoint ### Callback endpoint requirements @@ -57,4 +75,25 @@ The actual development and behavior of the bot are completely in your hands. All ### Responding as a bot -After your bot's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so. +After your bot's callback endpoint has received and processed a message, and you're ready to send a response back, make use of CometChat's [Send Bot Message](/rest-api/messages/send-bot-message) REST API to do so. This API posts a message authored by the bot's UID (`POST /bots/{uid}/messages`). + + +The exact JSON shape CometChat POSTs to your Callback URL is not documented on this page. Log the incoming request body from your endpoint to inspect it, or contact the CometChat team for the current payload reference. + + +## Next steps + + + + Configure a custom agent the same way as a custom bot. + + + Post the bot's reply back into the conversation. + + + Create the user account that backs the bot. + + + Build native agents with tools and knowledge bases instead. + + diff --git a/articles/docker.mdx b/articles/docker.mdx index 6d7a9717e..fd50b310f 100644 --- a/articles/docker.mdx +++ b/articles/docker.mdx @@ -3,22 +3,32 @@ title: "Docker" description: "Docker — CometChat documentation." --- -It is suggested to be familiar with the various kinds of roles for the on-premise deployment. +This guide describes how to deploy CometChat on-premise as a **Docker Swarm** cluster. The deployment spans several machines, each running a specific role (master, storage, calling, websocket, worker nodes, and extensions). Before you begin, it is suggested to be familiar with these roles. + + +On-premise deployment relies on artifacts and an On-Premise Token provided directly by CometChat (the bootstrap scripts and the `cometchatpro-onprem-dockerswarm` folder referenced below). If you do not have these yet, contact CometChat to start the on-premise process. + + +## Prerequisites + +- Machines provisioned to meet the hardware requirements in the table below, with network connectivity between them. +- Docker with Docker Compose installed on every machine (see step 3). +- The on-premise package and On-Premise Token shared by CometChat (see steps 4 and 5). ## 1. Hardware required for Docker Swarm -Below is the list of hardware required that you will need to provision. +Below is the list of machines you will need to provision. Each row is a **role** in the Swarm cluster; the *Requires Public IP* and *Open Public Ports* columns indicate which machines must be reachable from the internet. -| Minimum CPU | Minimum RAM | Minimum Storage | Requires Public IP | VM | Open Public Ports | -| ----------- | ----------- | --------------- | ------------------ | --- | ----------------------------------------- | -| master | 8 core | 32GB | 250GB | Yes | TCP: 80,443 | -| storage1 | 8 core | 32GB | 250GB | No | | -| storage2 | 8 core | 32GB | 250GB | No | | -| calling | 8 core | 32GB | 50GB | Yes | TCP: 80,443, 10000-20000 UDP: 10000-20000 | -| websocket | 8 core | 32GB | 50GB | Yes | TCP: 80,443,7070,5222,5223 | -| node1 | 4 core | 8GB | 50GB | No | | -| node2 | 4 core | 8GB | 50GB | No | | -| extensions | 4 core | 8GB | 50GB | Yes | TCP: 80, 443 | +| Role / Machine | Minimum CPU | Minimum RAM | Minimum Storage | Requires Public IP | Open Public Ports | +| -------------- | ----------- | ----------- | --------------- | ------------------ | ----------------------------------------- | +| master | 8 core | 32GB | 250GB | Yes | TCP: 80,443 | +| storage1 | 8 core | 32GB | 250GB | No | | +| storage2 | 8 core | 32GB | 250GB | No | | +| calling | 8 core | 32GB | 50GB | Yes | TCP: 80,443, 10000-20000 UDP: 10000-20000 | +| websocket | 8 core | 32GB | 50GB | Yes | TCP: 80,443,7070,5222,5223 | +| node1 | 4 core | 8GB | 50GB | No | | +| node2 | 4 core | 8GB | 50GB | No | | +| extensions | 4 core | 8GB | 50GB | Yes | TCP: 80, 443 | ## 2. Once the hardware and public IP's are ready @@ -89,3 +99,12 @@ cd cometchatpro-onprem-dockerswarm-1.0.0 #on extensions ._extensions_bootstrap.sh ``` + + +Run the bootstrap script that matches each machine's role, using the exact script names included in the on-premise package shared by CometChat. If a script name in the package differs from what is shown here, follow the package. Once every machine is bootstrapped, return to the **master** node to complete the final bootstrap step with CometChat. + + +## Related + +- [Properties and Constraints](/articles/properties-and-constraints) +- [Rate Limits](/articles/rate-limits) diff --git a/chat-builder/android/builder-customisations.mdx b/chat-builder/android/builder-customisations.mdx index 964830e85..eb519a114 100644 --- a/chat-builder/android/builder-customisations.mdx +++ b/chat-builder/android/builder-customisations.mdx @@ -19,9 +19,13 @@ The Android UI Kit Builder uses two main files for customization: | `BuilderSettingsHelper.kt` | Utility class that applies settings to UI components | Component-level customizations | - `CometChatBuilderSettings.kt` is auto-generated by the Builder plugin from your `cometchat-builder-settings.json` file. You can modify the values directly in the Kotlin file, but changes will be overwritten if you rebuild with the plugin. + `CometChatBuilderSettings.kt` is auto-generated by the Builder plugin from your `cometchat-builder-settings.json` file. You can modify the values directly in the Kotlin file, but changes will be overwritten if you rebuild with the plugin. For changes that should survive a rebuild, edit `cometchat-builder-settings.json` (feature toggles) or `themes.xml` (styling) instead. + + The two files above cover Builder-level customization. Because the Builder sits on top of the standard [CometChat Android UI Kit](/ui-kit/android/getting-started), you can go further using the UI Kit's own customization layers — **Message Templates**, **View Slots**, and **DataSource decorators**. See [Beyond Builder Settings](#beyond-builder-settings-deeper-ui-kit-customization) below. + + --- ## Using BuilderSettingsHelper @@ -379,6 +383,27 @@ You can customize individual component styles by overriding their style attribut --- +## Beyond Builder Settings: Deeper UI Kit Customization + +`BuilderSettingsHelper` and `themes.xml` cover feature toggles and broad styling. When you need to change the *structure* or *behavior* of a component — not just whether a feature is on — use the standard UI Kit customization layers. The Builder applies its settings to the same UI Kit components, so these layers compose with it. + +| Layer | Use it when you want to… | Reference | +| ----- | ------------------------ | --------- | +| **Message Templates** | Change a message bubble's structure, content/header/reply views, or bubble interactions | [Message Template](/ui-kit/android/message-template) | +| **View Slots** | Replace a specific region of a list item — avatar, title, subtitle, trailing section, or the entire row | [View Slots](/ui-kit/android/customization-view-slots) | +| **DataSource & ChatConfigurator** | Globally override how messages render, which options appear on bubbles, and which attachment actions appear in the composer | [DataSource & ChatConfigurator](/ui-kit/android/customization-datasource) | +| **Style classes & attributes** | Override individual component style attributes beyond the brand color and font themes | [Component Styling](/ui-kit/android/component-styling) | + + + Read the [Customization Overview](/ui-kit/android/customization-overview) first. It explains the View + ViewModel + Adapter architecture that all of these layers build on. + + + + These layers belong to the underlying UI Kit, not the Builder plugin. Apply them in the same Activity/Fragment where you call `BuilderSettingsHelper`, after the component is inflated. Call order generally does not matter for visibility flags, but if a template or slot and a Builder setting target the same region, the more specific UI Kit customization wins. Verify the exact precedence for your case against the linked reference pages. + + +--- + ## Next Steps diff --git a/chat-builder/android/builder-dir-structure.mdx b/chat-builder/android/builder-dir-structure.mdx index 015a200ab..148cd10f2 100644 --- a/chat-builder/android/builder-dir-structure.mdx +++ b/chat-builder/android/builder-dir-structure.mdx @@ -178,6 +178,10 @@ Drawable resources including icons, shapes, and backgrounds. Prefer using `CometChatBuilderSettings.kt` for feature toggles and `themes.xml` for styling. For extensive changes, extend existing components instead of modifying core files directly. + + `CometChatBuilderSettings.kt` is regenerated from `cometchat-builder-settings.json` on every Gradle build, so edits there are not preserved across rebuilds. Keep feature changes in the JSON and visual changes in `themes.xml`. For structural changes to components (custom bubbles, list-item regions, global message overrides), use the underlying UI Kit's [Message Templates](/ui-kit/android/message-template), [View Slots](/ui-kit/android/customization-view-slots), and [DataSource](/ui-kit/android/customization-datasource) layers rather than editing generated files. + + --- ## Next Steps diff --git a/chat-builder/android/builder-settings.mdx b/chat-builder/android/builder-settings.mdx index d35f9b363..127dbbf58 100644 --- a/chat-builder/android/builder-settings.mdx +++ b/chat-builder/android/builder-settings.mdx @@ -7,9 +7,13 @@ description: "Configure Android UI Kit Builder settings for messaging, AI helper The `CometChatBuilderSettings` object controls everything the Android UI Kit Builder renders—messaging, AI helpers, calls, layout, theming, and more. This object is auto-generated by the UI Kit Builder Settings Gradle plugin from your `cometchat-builder-settings.json` configuration file. - **For developers customizing their chat UI**: The `CometChatBuilderSettings.kt` file is generated automatically when you build your project. Edit the `cometchat-builder-settings.json` file to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/chat-builder/android/integration) for setup. + **For developers customizing their chat UI**: The `CometChatBuilderSettings.kt` file is generated automatically when you build your project. Edit the `cometchat-builder-settings.json` file to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/chat-builder/android/integration) for setup, and [Customizations](/chat-builder/android/builder-customisations) for how the generated constants are applied to components via `BuilderSettingsHelper`. + + These settings control feature toggles, layout, and broad styling. For structural or behavioral customization beyond what the JSON exposes — custom bubbles, list-item regions, or global message overrides — use the underlying UI Kit's [Message Templates](/ui-kit/android/message-template), [View Slots](/ui-kit/android/customization-view-slots), and [DataSource](/ui-kit/android/customization-datasource) layers. The Builder applies its settings to the same UI Kit components, so these layers compose with it. + + ## Top-level Structure The generated `CometChatBuilderSettings` object in Kotlin follows this structure: @@ -401,4 +405,16 @@ Some features require additional configuration in the [CometChat Dashboard](http > Modify component props, styling, and behavior for deeper customization. + + Go beyond brand color and font with full colors, typography, and style attributes. + + + Learn the UI Kit architecture and all deeper customization entry points. + diff --git a/chat-builder/android/integration.mdx b/chat-builder/android/integration.mdx index 13199375e..32e3c740d 100644 --- a/chat-builder/android/integration.mdx +++ b/chat-builder/android/integration.mdx @@ -56,6 +56,10 @@ Choose one of the following integration methods based on your needs: This method gives you full control over customization and is recommended for most projects. + + All Gradle snippets below use the **Kotlin DSL** (`build.gradle.kts`, `settings.gradle.kts`), matching the exported sample app. If your project uses the **Groovy DSL** (`build.gradle`, `settings.gradle`), apply the same repositories, plugin, and dependencies using Groovy syntax. The exported sample app ships Kotlin DSL files; Groovy equivalents are not generated, so confirm the exact Groovy syntax against the [Gradle plugin documentation](https://docs.gradle.org/current/userguide/plugins.html) if you convert them. + + ### Step 1: Add CometChat Repository Add the CometChat Maven repository to your project-level `settings.gradle.kts` file in both `pluginManagement` and `dependencyResolutionManagement`: @@ -144,7 +148,7 @@ The Builder plugin will automatically generate: ### Step 7: Copy BuilderSettingsHelper -Copy the `BuilderSettingsHelper.kt` file from the sample app to your project: +The "sample app" referenced below is the exported code package you downloaded from the UI Kit Builder in your Dashboard (see [Launch the UI Kit Builder](#launch-the-ui-kit-builder)). Copy the `BuilderSettingsHelper.kt` file from that package to your project: - **Source:** `src/main/java/com/cometchat/builder/BuilderSettingsHelper.kt` - **Destination:** `src/main/java/com/yourpackage/BuilderSettingsHelper.kt` @@ -437,6 +441,33 @@ CometChat.getGroup(GUID, object : CometChat.CallbackListener() { --- +## Customize Further + +Once the Builder is integrated, you can keep configuring features through the JSON, or drop down to the same customization layers the standalone UI Kit exposes: + + + + Every feature toggle, layout option, and style key in `cometchat-builder-settings.json`. + + + Apply settings to components via `BuilderSettingsHelper` and tweak styles in `themes.xml`. + + + Change bubble structure, content/header/reply views, and bubble interactions. + + + Replace specific regions of a list item (avatar, title, subtitle, trailing). + + + Globally override message rendering, options, and formatting. + + + Customize colors, typography, and component style attributes. + + + +--- + ## Important Guidelines for Changes @@ -471,6 +502,14 @@ For any updates related to UI, such as colors, fonts, and styles, you should app - Check that all `CometChatBuilderSettings` imports are correct - Ensure the Builder plugin has generated the settings file +### Re-exporting After Changing the Builder + +If you change feature toggles or styling in the Builder and re-export, the regenerated `cometchat-builder-settings.json` reflects your new configuration. Replace your existing JSON with the new file and rebuild so the plugin regenerates `CometChatBuilderSettings.kt`. + + + `CometChatBuilderSettings.kt` is regenerated from the JSON on each build, so manual edits to that file are not preserved. Whether re-exporting overwrites your customized `BuilderSettingsHelper.kt`, `themes.xml`, or other hand-edited files depends on how you copy the exported package into your project — back up your customizations before replacing exported files. Keep functional toggles in the JSON and visual changes in `themes.xml` so they survive regeneration. See [Customizations](/chat-builder/android/builder-customisations) for the recommended split. + + --- ## Next Steps diff --git a/chat-builder/android/overview.mdx b/chat-builder/android/overview.mdx index a0c14e0f9..67875d44f 100644 --- a/chat-builder/android/overview.mdx +++ b/chat-builder/android/overview.mdx @@ -16,6 +16,12 @@ The CometChat UI Kit Builder for Android provides a pre-built user interface kit UI Kit Builder is CometChat's configuration system that allows you to customize chat features, UI components, and styling through a simple JSON configuration file. The builder plugin automatically generates Kotlin constants and applies styling based on your configuration. +When you design your experience in the Builder and export the code, you receive a `cometchat-builder-settings.json` file plus a sample Android module. During a Gradle build, the `com.cometchat.builder.settings` plugin reads that JSON and generates `CometChatBuilderSettings.kt` — an object of type-safe Kotlin constants. A helper class, `BuilderSettingsHelper.kt`, then reads those constants and applies them to the standard [CometChat Android UI Kit](/ui-kit/android/getting-started) components (`CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`, and others). + + + The Builder is a configuration layer on top of the regular Android UI Kit — it does not replace it. Anything you can do with the UI Kit directly (custom message templates, view slots, themes) is still available after you integrate the Builder. See [Where the Builder fits](#where-the-builder-fits) below. + + --- ## Benefits of Using UI Kit Builder @@ -46,6 +52,24 @@ The Builder configuration supports the following categories: --- +## Where the Builder Fits + +The Builder gives you fast, JSON-driven control over **which features are on** and **broad styling**. For anything more granular, you drop down to the same customization layers the standalone UI Kit exposes. These layers stack — the Builder configures the components, and you can still customize those components further. + +| Layer | What it controls | Where to configure | +| ----- | ---------------- | ------------------ | +| **Builder feature toggles** | Enable/disable features, layout, tabs, brand color, font | [Builder Settings](/chat-builder/android/builder-settings) (`cometchat-builder-settings.json`) | +| **Theme overrides** | Colors, typography, component style attributes | [Theme Introduction](/ui-kit/android/theme-introduction) (`themes.xml`) | +| **Message Templates** | Custom bubble structure, content/header/reply views, bubble interactions | [Message Template](/ui-kit/android/message-template) | +| **Component View Slots** | Replace specific regions of a list item (avatar, title, subtitle, trailing) | [View Slots](/ui-kit/android/customization-view-slots) | +| **DataSource decorators** | Global, message-level overrides (options, attachments, formatting) | [DataSource & ChatConfigurator](/ui-kit/android/customization-datasource) | + + + Start with the [Customization Overview](/ui-kit/android/customization-overview) to understand the View + ViewModel + Adapter architecture before reaching for the deeper layers. + + +--- + ## Try Live Demo Experience the CometChat UI Kit Builder in action: diff --git a/chat-builder/flutter/builder-dir-structure.mdx b/chat-builder/flutter/builder-dir-structure.mdx index 7a947325f..610cd4188 100644 --- a/chat-builder/flutter/builder-dir-structure.mdx +++ b/chat-builder/flutter/builder-dir-structure.mdx @@ -237,4 +237,10 @@ flutter: Explore available UI components. + + Customize message bubble content, headers, footers, and status views. + + + Replace specific regions of a component's UI with your own views. + diff --git a/chat-builder/flutter/builder-settings.mdx b/chat-builder/flutter/builder-settings.mdx index 1e44caadc..ae978806b 100644 --- a/chat-builder/flutter/builder-settings.mdx +++ b/chat-builder/flutter/builder-settings.mdx @@ -356,3 +356,36 @@ Some features require additional configuration in the [CometChat Dashboard](http **Moderation** - Requires moderation rules to be configured in the Dashboard under **Moderation > Rules** + +--- + +## Customize Beyond Settings + +The settings JSON controls feature toggles, layout, and theme tokens. When you need finer control over what individual components render, the exported module is built on the standard CometChat Flutter UI Kit, so you can use its customization layers directly: + + + + Customize message bubble content, headers, footers, and status views. + + + Replace specific regions of a component's UI using builder callbacks. + + + Override color palettes, typography, and spacing tokens. + + + Wire the exported module into your Flutter app. + + diff --git a/chat-builder/flutter/integration.mdx b/chat-builder/flutter/integration.mdx index e09c1102d..67730182b 100644 --- a/chat-builder/flutter/integration.mdx +++ b/chat-builder/flutter/integration.mdx @@ -159,7 +159,36 @@ Future main() async { This ensures generated constants, themes, and resources are ready when your widgets build. -### Step 7: Launch UI Kit Builder Screens +### Step 7: Authenticate Your User + +The exported module uses the standard CometChat Flutter UI Kit underneath, so the SDK must be initialized and a user logged in before chat screens can load. The Builder reads your `APP_ID`, `AUTH_KEY`, and `REGION` from `chat_builder/lib/utils/app_constants.dart` (see [Directory Structure](/chat-builder/flutter/builder-dir-structure)). + +You have two ways to get a logged-in user: + +- **Let the Builder handle login.** `ChatBuilder.launchBuilder(context)` opens the Builder's own flow, which includes a login screen when no user is signed in (see Step 8). This is the fastest path for prototyping. +- **Authenticate from your own app.** If your app already manages users, initialize and log in with the standard UI Kit APIs before opening the chat screens directly. + +For development you can log in with an Auth Key: + +```dart +CometChatUIKit.login( + "cometchat-uid-1", // Replace with a valid UID + onSuccess: (user) { + debugPrint('CometChat login success'); + }, + onError: (error) { + debugPrint('CometChat login error'); + }, +); +``` + + + Auth Key login is intended for development only. For production, mint an Auth Token on your server and call `CometChatUIKit.loginWithAuthToken()` instead, so your Auth Key is never shipped in the client. See [Login using Auth Token](/ui-kit/flutter/methods#login-using-auth-token). + + +For the full initialization and login reference, see [Getting Started](/ui-kit/flutter/getting-started) and [Methods](/ui-kit/flutter/methods). + +### Step 8: Launch UI Kit Builder Screens Use the `ChatBuilder` APIs to open preconfigured experiences. @@ -191,12 +220,28 @@ ChatBuilder.launchMessages( ); ``` -### Step 8: Refresh Settings After Updates +### Step 9: Refresh Settings After Updates Whenever you export a new Builder configuration, replace the generated JSON, fonts, and assets in your project, then rerun `flutter pub get` to pick up changes. --- +## Light & Dark Theme + +The Builder exports a `theme` value in `cometchat-builder-settings.json` that controls the chat UI's appearance: + +| Value | Behavior | +| ----- | -------- | +| `'light'` | Always renders the light theme | +| `'dark'` | Always renders the dark theme | +| `'system'` | Follows the device's light/dark setting | + +To switch modes, change the `theme` value in the exported settings JSON (or pick it in the Builder and re-export), then rerun `flutter pub get`. Brand and text colors for each mode are configured alongside it. See [UI Kit Builder Settings → Style](/chat-builder/flutter/builder-settings) for the full color and typography schema. + +For theming beyond what the Builder exposes—custom color palettes, typography, spacing tokens, and `ThemeExtension`—use the UI Kit's theming system directly. See [Theming](/ui-kit/flutter/theme-introduction). + +--- + ## Enable Features in CometChat Dashboard If your app needs any of these features, enable them from your [Dashboard](https://app.cometchat.com): @@ -286,4 +331,16 @@ For any updates related to UI, such as colors, fonts, and styles, modify the the > Customize colors, typography, and styling to match your brand. + + Customize message bubble content, headers, footers, and status views. + + + Replace specific regions of a component's UI with your own views. + diff --git a/chat-builder/flutter/overview.mdx b/chat-builder/flutter/overview.mdx index 5a4d7a35a..69483dfee 100644 --- a/chat-builder/flutter/overview.mdx +++ b/chat-builder/flutter/overview.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Overview" description: "CometChat UI Kit Builder for Flutter provides a pre-built interface to integrate a reliable, fully-featured chat experience into new or existing apps." --- -It provides a set of prebuilt, production-ready messaging components backed by CometChat's real-time infrastructure. +The **CometChat UI Kit Builder for Flutter** is a visual tool that lets you configure a complete chat experience in the CometChat Dashboard and export it as a ready-to-run Flutter module. It provides a set of prebuilt, production-ready messaging components backed by CometChat's real-time infrastructure, so you can add chat and calling to a new or existing Flutter app without building each screen by hand. With CometChat UI Kit Builder, you can: @@ -119,6 +119,39 @@ Experience the CometChat UI Kit Builder in action: --- +## Customize Beyond the Builder + +The Builder covers feature toggles, layout, and theming. When you need to change what individual components render, the exported module is built on the standard CometChat Flutter UI Kit, so you can drop down to its customization layers: + + + + Customize message bubble content, headers, footers, and status views. + + + Replace specific regions of a component's UI using builder callbacks. + + + Override color palettes, typography, and spacing tokens. + + + See all UI Kit customization layers and when to use each. + + + +--- + ## Helpful Resources diff --git a/chat-builder/ios/builder-customisations.mdx b/chat-builder/ios/builder-customisations.mdx index 74ff10579..9acb8dc23 100644 --- a/chat-builder/ios/builder-customisations.mdx +++ b/chat-builder/ios/builder-customisations.mdx @@ -197,30 +197,32 @@ import CometChatUIKitSwift // Set custom font family CometChatTypography.customFontFamilyName = "Helvetica" - -// Or use system fonts -CometChatTypography.customFontFamilyName = nil // Uses system default ``` + +This is the same `CometChatTypography.customFontFamilyName` property the JSON loader sets from `style.typography.font`. For the full typography and font-scaling API, see [Theming](/ui-kit/ios/theme-introduction). + + --- ## Component-Level Customizations ### Message List Configuration +Map Builder feature flags onto the message list's visibility properties. Reactions and in-thread replies are controlled by `hideReactionOption` and `hideReplyInThreadOption`: + ```swift import CometChatUIKitSwift let messageListConfiguration = MessageListConfiguration() -// Configure based on Builder settings -if CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.threadConversationAndReplies { - messageListConfiguration.showThreadReplies = true -} +// Hide the reaction option when reactions are disabled in the Builder +messageListConfiguration.hideReactionOption = + !CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions -if CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.reactions { - messageListConfiguration.showReactions = true -} +// Hide the "reply in thread" option when threads are disabled in the Builder +messageListConfiguration.hideReplyInThreadOption = + !CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.threadConversationAndReplies let messagesVC = CometChatMessages() messagesVC.set(messageListConfiguration: messageListConfiguration) @@ -233,21 +235,25 @@ import CometChatUIKitSwift let composerConfiguration = MessageComposerConfiguration() -// Configure attachments based on Builder settings +// Hide the attachment button when no media sharing is enabled in the Builder composerConfiguration.hideAttachmentButton = !( CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.photosSharing || CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.videoSharing || CometChatBuilderSettings.shared.chatFeatures.coreMessagingExperience.fileSharing ) -if CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.voiceNotes { - composerConfiguration.hideVoiceRecording = false -} +// Hide the voice recording button when voice notes are disabled in the Builder +composerConfiguration.hideVoiceRecordingButton = + !CometChatBuilderSettings.shared.chatFeatures.deeperUserEngagement.voiceNotes let messagesVC = CometChatMessages() messagesVC.set(messageComposerConfiguration: composerConfiguration) ``` + +These properties are part of the standard iOS UI Kit. For the full list of configurable options on each component, see [Message List](/ui-kit/ios/message-list) and [Message Composer](/ui-kit/ios/message-composer). + + --- ## Modifying the JSON Configuration @@ -284,6 +290,27 @@ To change feature settings, edit your `cometchat-builder-settings.json` file: --- +## Parallel Customization Layers + +The Builder settings sit on top of the standard CometChat iOS UI Kit, so every UI Kit customization layer is still available to you. Reach for these when the JSON `style` block and feature toggles aren't enough: + + + + Global colors, typography, and dark mode via `CometChatTheme` and `CometChatTypography`. + + + Style individual components (header, list, composer) with style classes, globally or per instance. + + + Define custom message bubbles with your own content, header, and reply views. + + + Every prebuilt component and its configuration object. + + + +--- + ## Next Steps diff --git a/chat-builder/ios/builder-dir-structure.mdx b/chat-builder/ios/builder-dir-structure.mdx index c6d9077a1..3ae5a75e0 100644 --- a/chat-builder/ios/builder-dir-structure.mdx +++ b/chat-builder/ios/builder-dir-structure.mdx @@ -107,25 +107,48 @@ All view controllers organized by feature. ### `cometchat-builder-settings.json` -The main configuration file containing all Builder settings: +The main configuration file exported from the UI Kit Builder. It contains all feature toggles, layout, and styling under a single `settings` object: ```json { "builderId": "your-builder-id", "settings": { - "chatFeatures": { ... }, - "callFeatures": { ... }, - "layout": { ... }, - "style": { ... } + "chatFeatures": { + "coreMessagingExperience": { }, + "deeperUserEngagement": { }, + "aiUserCopilot": { }, + "userManagement": { }, + "groupManagement": { }, + "moderatorControls": { }, + "privateMessagingWithinGroups": { }, + "inAppSounds": { } + }, + "callFeatures": { + "voiceAndVideoCalling": { } + }, + "layout": { + "withSideBar": true, + "tabs": ["chats", "calls", "users", "groups"], + "chatType": "user" + }, + "style": { + "theme": "system", + "color": { }, + "typography": { } + } } } ``` + +This shows the top-level shape only. For every key, its type, default value, and the complete populated JSON, see [UI Kit Builder Settings](/chat-builder/ios/builder-settings). + + ### `AppConstants.swift` -Contains CometChat credentials: +Contains your CometChat credentials: -```swift +```swift title="AppConstants.swift" struct AppConstants { static let APP_ID = "YOUR_APP_ID" static let AUTH_KEY = "YOUR_AUTH_KEY" @@ -133,6 +156,10 @@ struct AppConstants { } ``` + +The **Auth Key** is for development only. For production, authenticate with server-generated **Auth Tokens** via [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-auth-token) and keep credentials out of source control. See the [Integration guide](/chat-builder/ios/integration#configure-your-cometchat-credentials) for details. + + --- ## Quick Reference: Where to Customize diff --git a/chat-builder/ios/builder-settings.mdx b/chat-builder/ios/builder-settings.mdx index a41ef511a..cc83226b9 100644 --- a/chat-builder/ios/builder-settings.mdx +++ b/chat-builder/ios/builder-settings.mdx @@ -10,6 +10,10 @@ The `CometChatBuilderSettings` object controls everything the iOS UI Kit Builder **For developers customizing their chat UI**: Edit `cometchat-builder-settings.json` to enable/disable features like messaging, calls, AI copilot, and theming. See the [Integration Guide](/chat-builder/ios/integration) for setup. + + `cometchat-builder-settings.json` is exported from the UI Kit Builder (Dashboard → **Chat & Messaging** → **Integrate** → **iOS** → **Launch UI Kit Builder**) inside the downloaded project zip. The exported project loads it at launch via `CometChatBuilderSettings.loadFromJSON()`. See [Where to find it](/chat-builder/ios/builder-dir-structure#cometchat-builder-settings-json) in the directory structure. + + ## Top-level Structure The `CometChatBuilderSettings` object in Swift follows this structure: diff --git a/chat-builder/ios/integration.mdx b/chat-builder/ios/integration.mdx index 6e92ad542..4e79247d6 100644 --- a/chat-builder/ios/integration.mdx +++ b/chat-builder/ios/integration.mdx @@ -19,8 +19,9 @@ Before running this project on iOS, make sure you have: - **Xcode** (latest version recommended) - **macOS device** with macOS 12.0 or above - **iOS Device or Simulator** with iOS 13.0 or above -- **CocoaPods** (latest version installed) +- **CocoaPods** (latest version installed) — required for the exported sample project; Swift Package Manager is also supported when integrating into your own app - **Internet connection** (required for CometChat services) +- Your **App ID**, **Auth Key**, and **Region** from the [CometChat Dashboard](https://app.cometchat.com) → Your App → Credentials --- @@ -40,6 +41,12 @@ Before running this project on iOS, make sure you have: 3. Navigate to **Chat & Messaging** → **Get Started**. 4. Navigate to **Integrate** → **iOS** → **Launch UI Kit Builder**. +In the Builder, customize features, layout, and theme, then download the generated project zip. The zip includes your `cometchat-builder-settings.json` file, which captures every toggle and style you selected. + + +The `cometchat-builder-settings.json` file is exported from the UI Kit Builder along with the rest of the project. It is the single source of truth for your feature toggles, layout, and styling. For the full list of keys it contains, see [UI Kit Builder Settings](/chat-builder/ios/builder-settings). + + --- ## Integration Options @@ -95,30 +102,70 @@ Build and run the project in Xcode. ## Option 2: Integrate Builder Configuration into Your iOS App -This method gives you full control over customization and is recommended for production apps. +This method gives you full control over customization and is recommended for production apps. You take the exported `cometchat-builder-settings.json` file and the CometChat UI Kit, then wire them together inside your own app. + +### Install the CometChat UI Kit + +The Builder configuration is applied on top of the standard CometChat iOS UI Kit. Install the UI Kit using either CocoaPods or Swift Package Manager. -### Installation (CometChatBuilder) + + +Add CometChat to your `Podfile`: -### CocoaPods +```ruby title="Podfile" +platform :ios, '13.0' +use_frameworks! -Add to your `Podfile`: +target 'YourApp' do + pod 'CometChatUIKitSwift' -```ruby -pod 'CometChatBuilder' + # Optional: Voice/Video Calling + pod 'CometChatCallsSDK' +end ``` Then run: ```bash -pod install +pod install --repo-update ``` -### Swift Package Manager (SPM) +Open the `.xcworkspace` file (not `.xcodeproj`) from now on. + -1. Open your Xcode project. -2. Go to **File → Add Packages**. -3. Enter the URL of your Git repository (or local path) where `CometChatBuilder` code is hosted. -4. Select the `CometChatBuilder` package and add it to your app target. + +1. In Xcode, go to **File → Add Package Dependencies**. +2. Enter the official UI Kit repository URL: + +``` +https://github.com/cometchat/cometchat-uikit-ios +``` + +3. Select the package and add it to your app target. + + + + +For pinned versions, requirements, and the full UI Kit install reference, see the [iOS UI Kit Getting Started guide](/ui-kit/ios/getting-started). The exported Builder project ships with a `Podfile` already configured, so for that project you only need to run `pod install`. + + +--- + +## Configure Your CometChat Credentials + +The exported project keeps your CometChat credentials in `AppConstants.swift` (App ID, Auth Key, and Region). Set these before the app initializes CometChat. + +```swift title="AppConstants.swift" +struct AppConstants { + static let APP_ID = "YOUR_APP_ID" + static let AUTH_KEY = "YOUR_AUTH_KEY" + static let REGION = "YOUR_REGION" +} +``` + + +The **Auth Key** is intended for development and proof-of-concept work only. Do not ship Auth Keys in production builds — anyone who extracts your app binary can read them. For production, generate short-lived **Auth Tokens** server-side via the [REST API](/rest-api/chat-apis) and authenticate with [`loginWithAuthToken()`](/ui-kit/ios/methods#login-using-auth-token). Keep credentials out of source control (for example, inject them via an `.xcconfig` file or your CI secrets store). + --- @@ -268,6 +315,18 @@ Toggle these features on or off directly in the UI Kit Builder. For a full refer --- +## Going Beyond Builder Settings + +The Builder JSON covers feature toggles, layout, and brand styling. When you need finer control, the exported code is the standard CometChat iOS UI Kit, so you can layer the UI Kit's own customization APIs on top: + +| Layer | Use it for | Reference | +| ----- | ---------- | --------- | +| Theme overrides | Global colors, fonts, dark mode beyond the JSON `style` block | [Theme](/ui-kit/ios/theme-introduction) | +| Component styling | Per-component or global style classes (headers, lists, composer) | [Component Styling](/ui-kit/ios/component-styling) | +| Message templates | Custom message bubbles, content/header/reply views | [Message Template](/ui-kit/ios/message-template) | + +--- + ## Next Steps diff --git a/chat-builder/ios/overview.mdx b/chat-builder/ios/overview.mdx index 1313ec220..c2ccdd68c 100644 --- a/chat-builder/ios/overview.mdx +++ b/chat-builder/ios/overview.mdx @@ -14,7 +14,9 @@ The CometChat iOS UI Kit provides a pre-built user interface that developers can ## What is UI Kit Builder? -UI Kit Builder is CometChat's configuration system that allows you to customize chat features, UI components, and styling through a simple JSON configuration file. The configuration can be loaded into your app using a local JSON file. +UI Kit Builder is CometChat's configuration system that allows you to customize chat features, UI components, and styling through a simple JSON configuration file. You design your chat experience visually in the Builder, then export a project that includes a `cometchat-builder-settings.json` file. Your app loads that file at launch to render the experience you configured. + +See [UI Kit Builder Settings](/chat-builder/ios/builder-settings) for the complete JSON schema and every available toggle. --- diff --git a/chat-builder/nextjs/builder-customisations.mdx b/chat-builder/nextjs/builder-customisations.mdx index 4f1a22635..97a5898fe 100644 --- a/chat-builder/nextjs/builder-customisations.mdx +++ b/chat-builder/nextjs/builder-customisations.mdx @@ -6,6 +6,46 @@ description: "Customize Next.js UI Kit Builder components by adjusting CometChat The `CometChatSettings.ts` file handles basic feature toggles. For deeper customizations, modify component props or source code directly. + + The exported code uses the [React UI Kit](/ui-kit/react/overview), so every + React UI Kit component, prop, and customization layer applies here. In + Next.js, any file that renders these components or calls the CometChat SDK + must be a Client Component — add `"use client";` as the first line, and keep + it inside the SSR-disabled boundary set up in the + [Integration Guide](/chat-builder/nextjs/integration). The `chatUser` variable + in the examples below is a `CometChat.User` you fetch from the SDK, as shown + in the next section. + + +--- + +## **Getting a `chatUser` Reference** + +Several examples below pass a `chatUser` prop. This is a `CometChat.User` object +you fetch from the SDK after login. Fetch it in a Client Component with +`CometChat.getUser()`: + +```tsx lines +"use client"; + +import { useEffect, useState } from "react"; +import { CometChat } from "@cometchat/chat-sdk-javascript"; + +function useChatUser(uid: string) { + const [chatUser, setChatUser] = useState(); + + useEffect(() => { + CometChat.getUser(uid).then((user) => setChatUser(user)); + }, [uid]); + + return chatUser; +} +``` + +Render the component only once `chatUser` is defined, for example +`chatUser ? : null`. The same applies +to a `group` prop fetched with `CometChat.getGroup()`. + --- ## **App-Level Customizations** @@ -55,6 +95,8 @@ Customize how sticky date headers appear in the message list. **Component**: [Message List](/ui-kit/react/message-list) → [`stickyDateTimeFormat`](/ui-kit/react/message-list#sticky-datetime-format) ```jsx lines +"use client"; + import { CometChatMessageList, CalendarObject, @@ -154,6 +196,21 @@ const brandedSendButton = ( --- +## **Customization Layers** + +Component props are one of several ways to tailor the exported chat. Each layer +operates independently, so you can combine them: + +| Layer | What it changes | Where | +| ----- | --------------- | ----- | +| Feature toggles | Enable/disable features | [`CometChatSettings.ts`](/chat-builder/nextjs/builder-settings) | +| Component props & slot views | Per-component behavior and custom views (the examples above) | [Components Overview](/ui-kit/react/components-overview) | +| Message templates | How individual message bubbles render | [Message Template](/ui-kit/react/message-template) | +| Theme overrides | Colors, fonts, dark mode via the theme system | [Theming](/ui-kit/react/theme) | +| CSS variables | Fine-grained styling via `--cometchat-*` tokens | [Color Resources](/ui-kit/react/theme/color-resources) | + +--- + ## **Next Steps** Explore all available UI components + + Customize how message bubbles render + Customize colors, typography, and styling + + Override `--cometchat-*` design tokens + Add multi-language support diff --git a/chat-builder/nextjs/builder-dir-structure.mdx b/chat-builder/nextjs/builder-dir-structure.mdx index b2654fc18..088acaa6f 100644 --- a/chat-builder/nextjs/builder-dir-structure.mdx +++ b/chat-builder/nextjs/builder-dir-structure.mdx @@ -6,6 +6,16 @@ description: "Overview of the CometChat UI Kit Builder directory layout for Next The exported UI Kit Builder code lives in `src/CometChat/`. This guide helps you navigate the structure so you know exactly where to make changes. + + These paths come from the [React UI Kit](/ui-kit/react/overview) export + (`cometchat-app-react`). In a Next.js App Router project, you copy the + `CometChat/` folder under `src/app/` instead of `src/`, and the React entry + files (`App.tsx` / `index.tsx`) are replaced by the `CometChatNoSSR` and + wrapper Client Components from the + [Integration Guide](/chat-builder/nextjs/integration). Everything inside the + `CometChat/` folder is identical across both frameworks. + + diff --git a/chat-builder/nextjs/builder-settings.mdx b/chat-builder/nextjs/builder-settings.mdx index 1e54c0163..a6feae533 100644 --- a/chat-builder/nextjs/builder-settings.mdx +++ b/chat-builder/nextjs/builder-settings.mdx @@ -349,4 +349,10 @@ Below is the complete settings structure with default values. Update these in `C > Modify component props, styling, and behavior for deeper customization. + + Customize colors, typography, and dark mode beyond the `style` settings. + + + Control how individual message bubbles render. + diff --git a/chat-builder/nextjs/integration.mdx b/chat-builder/nextjs/integration.mdx index 52647b38d..8a7492046 100644 --- a/chat-builder/nextjs/integration.mdx +++ b/chat-builder/nextjs/integration.mdx @@ -94,6 +94,17 @@ npm install @cometchat/chat-uikit-react@6.3.11 @cometchat/calls-sdk-javascript Copy the `cometchat-app-react/src/CometChat` folder inside your `src/app` directory. + + The exported package is built on the [React UI Kit](/ui-kit/react/overview), so + its folder is named `cometchat-app-react` and the + [Directory Structure](/chat-builder/nextjs/builder-dir-structure) reference + uses React paths (e.g. `src/CometChat/`). In a Next.js App Router project you + place this same `CometChat/` folder under `src/app/`, and the React entry files + (`App.tsx` / `index.tsx`) are replaced by the `CometChatNoSSR` and wrapper + files created in the following steps. All component, prop, and customization + references throughout these guides apply unchanged. + + --- ### **Step 3: Create & Initialize `CometChatNoSSR.tsx`** diff --git a/chat-builder/nextjs/overview.mdx b/chat-builder/nextjs/overview.mdx index 281600a4f..37ede2653 100644 --- a/chat-builder/nextjs/overview.mdx +++ b/chat-builder/nextjs/overview.mdx @@ -14,6 +14,14 @@ With CometChat UI Kit Builder, you can: The exported UI connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling. + + The exported Next.js code is built on the [React UI Kit](/ui-kit/react/overview). + Because Next.js renders on the server by default, the chat components are loaded + client-side only — the [Integration Guide](/chat-builder/nextjs/integration) + shows the `"use client"` and SSR-disabling setup. Every React UI Kit component, + prop, and customization layer applies unchanged. + + ## What You Can Configure Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/chat-builder/nextjs/builder-settings). @@ -74,6 +82,27 @@ Drop the exported code into your Next.js project, add your CometChat credentials --- +## Customize Further + +After exporting and integrating, tailor the chat through several independent layers: + + + + Toggle features in `CometChatSettings.ts` + + + Adjust component props and slot views + + + Find where each part of the exported code lives + + + Customize colors, typography, and dark mode + + + +--- + ## Try Live Demo Experience the CometChat UI Kit Builder in action: diff --git a/chat-builder/react-native/builder-customisations.mdx b/chat-builder/react-native/builder-customisations.mdx index d51646bfb..98b6449fe 100644 --- a/chat-builder/react-native/builder-customisations.mdx +++ b/chat-builder/react-native/builder-customisations.mdx @@ -78,15 +78,17 @@ const updateFeature = () => { ### Applying Builder Theme to UI Kit -The Builder configuration includes style settings that should be applied to the CometChat UI Kit theme: +The Builder configuration includes style settings that should be applied to the CometChat UI Kit theme. The `getFontFamily` helper used below is defined in [Custom Font Integration](#custom-font-integration); import it from wherever you place that utility. ```tsx import React from 'react'; import { CometChatThemeProvider } from '@cometchat/chat-uikit-react-native'; import { useConfig } from './src/config/store'; +import { getFontFamily } from './src/utils/fonts'; // defined in "Custom Font Integration" below const App = () => { const styleConfig = useConfig((state) => state.settings.style); + const fontFamily = getFontFamily(styleConfig.typography.font); const theme = { light: { @@ -97,9 +99,6 @@ const App = () => { background: '#FFFFFF', border: '#E8E8E8', }, - typography: { - fontFamily: getFontFamily(styleConfig.typography.font), - }, }, dark: { color: { @@ -109,9 +108,6 @@ const App = () => { background: '#141414', border: '#3D3D3D', }, - typography: { - fontFamily: getFontFamily(styleConfig.typography.font), - }, }, }; @@ -123,6 +119,10 @@ const App = () => { }; ``` + + The UI Kit's `typography` theme tokens are keyed by named text styles (for example `heading4`) and each has `bold`, `medium`, and `regular` variants whose `fontFamily` is a string—not a single top-level `fontFamily`. To apply a Builder-selected font across the UI, set the `fontFamily` on the relevant typography tokens. See [Component Styling](/ui-kit/react-native/component-styling) for the exact token structure and [Theming](/ui-kit/react-native/theme) for the theme provider overview. + + ### Custom Color Palette Override the default colors by modifying the theme object: @@ -158,57 +158,58 @@ const customTheme = { ### Step 1: Add Font Files -Add your custom font files to the appropriate platform directories: +Add your custom font files to the project's `assets/fonts/` directory (and reference them from the platform font folders described in the [Directory Structure](/chat-builder/react-native/builder-dir-structure) guide): - **iOS:** `ios//Resources/Fonts/` - **Android:** `android/app/src/main/assets/fonts/` -### Step 2: Link Fonts (React Native CLI) +### Step 2: Register Fonts -For React Native CLI projects, create or update `react-native.config.js`: + + + Native modules in React Native 0.60+ are linked automatically by autolinking, so the legacy `react-native link` command is no longer used. To copy your font assets into the native projects, declare them in `react-native.config.js`: -```js -module.exports = { - assets: ['./assets/fonts'], -}; -``` + ```js + module.exports = { + assets: ['./assets/fonts'], + }; + ``` -Then run: + Then run: -```bash -npx react-native-asset -``` + ```bash + npx react-native-asset + ``` + + Rebuild the app (`npm run ios` / `npm run android`) so the fonts are bundled. + + + In an Expo development build, register fonts with the `expo-font` config plugin in `app.json` instead of `react-native-asset`, then rebuild the development client. Refer to the [Expo Integration](/ui-kit/react-native/expo-integration) guide for the native setup CometChat requires under Expo. + + ### Step 3: Map Font Family -Create a font mapping utility: +Create a font mapping utility. `getFontFamily` returns the base font-family **string** for a given Builder font name, so it can be assigned to the UI Kit's `fontFamily` typography tokens: ```tsx import { Platform } from 'react-native'; -const FONT_MAP = { - 'roboto': { - regular: Platform.OS === 'ios' ? 'Roboto-Regular' : 'roboto_regular', - medium: Platform.OS === 'ios' ? 'Roboto-Medium' : 'roboto_medium', - bold: Platform.OS === 'ios' ? 'Roboto-Bold' : 'roboto_bold', - }, - 'inter': { - regular: Platform.OS === 'ios' ? 'Inter-Regular' : 'inter_regular', - medium: Platform.OS === 'ios' ? 'Inter-Medium' : 'inter_medium', - bold: Platform.OS === 'ios' ? 'Inter-Bold' : 'inter_bold', - }, - 'your-custom-font': { - regular: Platform.OS === 'ios' ? 'YourFont-Regular' : 'your_font_regular', - medium: Platform.OS === 'ios' ? 'YourFont-Medium' : 'your_font_medium', - bold: Platform.OS === 'ios' ? 'YourFont-Bold' : 'your_font_bold', - }, +const FONT_MAP: Record = { + 'roboto': Platform.OS === 'ios' ? 'Roboto-Regular' : 'roboto_regular', + 'inter': Platform.OS === 'ios' ? 'Inter-Regular' : 'inter_regular', + 'your-custom-font': Platform.OS === 'ios' ? 'YourFont-Regular' : 'your_font_regular', }; -export const getFontFamily = (fontName: string) => { +export const getFontFamily = (fontName: string): string => { return FONT_MAP[fontName] || FONT_MAP['roboto']; }; ``` + + The exact font-family name must match the PostScript name of the installed font (iOS) or the file name without extension (Android). Verify the registered names after running the registration step above. + + --- ## Component-Level Customizations @@ -379,4 +380,25 @@ const TabNavigator = () => { ); }; -``` \ No newline at end of file +``` + +--- + +## Going Beyond the Builder + +The Builder config covers feature toggles, layout, and high-level theme tokens. For deeper customization, drop down to the UI Kit's own customization layers—these work the same whether or not you use the Builder: + + + + Override how message bubbles render with `CometChatMessageTemplate` and the `templates` prop on the message list. + + + Style individual components and inject custom views (headers, subtitles, list items) via theme overrides and slot props. + + + Customize colors, typography tokens, and light/dark modes through `CometChatThemeProvider`. + + + Full schema for every `config.json` key the Builder exports. + + \ No newline at end of file diff --git a/chat-builder/react-native/builder-settings.mdx b/chat-builder/react-native/builder-settings.mdx index 997e69aff..3f6d536e2 100644 --- a/chat-builder/react-native/builder-settings.mdx +++ b/chat-builder/react-native/builder-settings.mdx @@ -359,3 +359,22 @@ Some features require additional configuration in the [CometChat Dashboard](http **Moderation** - Requires moderation rules to be configured in the Dashboard under **Moderation > Rules** + +--- + +## Next Steps + + + + Export this `config.json` from the Builder and wire it into your app. + + + Read settings at runtime, override the theme, and add custom fonts. + + + See where `config.json` and the Zustand store live in the project. + + + Map Builder style tokens onto the UI Kit theme provider. + + diff --git a/chat-builder/react-native/integration.mdx b/chat-builder/react-native/integration.mdx index b1410125c..6c4142734 100644 --- a/chat-builder/react-native/integration.mdx +++ b/chat-builder/react-native/integration.mdx @@ -23,6 +23,10 @@ Before getting started, make sure you have: - **Internet connection** (required for CometChat services) - An active CometChat app (App ID, Auth Key, and Region) + + **Expo vs. bare React Native.** The Builder sample app is a bare React Native (CLI) project, so the iOS steps below use CocoaPods (`pod install`). If your production app is built with Expo, you cannot use Expo Go—the CometChat React Native UI Kit requires native modules, so you need an [Expo development build](/ui-kit/react-native/expo-integration). The Builder configuration (`config.json` and the Zustand store) is plain JavaScript and works in both bare and Expo projects; only the native setup (pods, fonts) differs. See [React Native CLI Integration](/ui-kit/react-native/react-native-cli-integration) and [Expo Integration](/ui-kit/react-native/expo-integration) for the underlying UI Kit setup each workflow requires. + + --- ## Complete Integration Workflow @@ -86,12 +90,17 @@ export const AppConstants = { ### Step 4: Run the Builder Sample +Start the Metro bundler in one terminal: + ```bash -# Start Metro npm start +``` -# Launch iOS or Android +Then build and launch the app in a second terminal (pick your platform): + +```bash npm run ios +# or npm run android ``` @@ -111,6 +120,10 @@ npm install zustand @react-native-async-storage/async-storage ### Step 2: Copy Configuration Files + + The `config.json` you ship is produced by the UI Kit Builder itself. After you finish designing in the Builder (see [Launch the UI Kit Builder](#launch-the-ui-kit-builder) above), export the configuration—either scan the QR code from the running [sample app](#option-1-run-the-cometchat-uikit-builder-sample-app) or download the generated JSON—and replace the default `src/config/config.json` template with it. For the full schema of this file, see [UI Kit Builder Settings](/chat-builder/react-native/builder-settings). + + From the sample project, copy these essential files to your existing React Native project: - **Source:** `src/config/store.ts` (Zustand store that manages Builder settings) diff --git a/chat-builder/react-native/overview.mdx b/chat-builder/react-native/overview.mdx index 68b527da8..2918ff182 100644 --- a/chat-builder/react-native/overview.mdx +++ b/chat-builder/react-native/overview.mdx @@ -14,6 +14,10 @@ With CometChat UI Kit Builder, you can: The exported UI connects to CometChat's SDK and infrastructure, which manages message transport, sync, and backend scaling. + + The Builder works with both bare React Native (CLI) and Expo projects. Because the CometChat React Native UI Kit relies on native modules, Expo apps must use a [development build](/ui-kit/react-native/expo-integration) rather than Expo Go. See [React Native CLI Integration](/ui-kit/react-native/react-native-cli-integration) and [Expo Integration](/ui-kit/react-native/expo-integration) for the underlying UI Kit setup. + + ## What You Can Configure Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/chat-builder/react-native/builder-settings). @@ -119,6 +123,24 @@ Drop the configuration into your React Native project, add your CometChat creden --- +## Customize Beyond the Builder + +The Builder handles feature toggles, layout, and theme tokens. For deeper changes, use the UI Kit's own customization layers: + + + + Custom message bubble rendering via `CometChatMessageTemplate`. + + + Per-component style and view-slot overrides. + + + Colors, typography, and dark mode via the theme provider. + + + +--- + ## Helpful Resources diff --git a/fundamentals/ai-user-copilot/conversation-starter.mdx b/fundamentals/ai-user-copilot/conversation-starter.mdx index 558b8737c..01a93028b 100644 --- a/fundamentals/ai-user-copilot/conversation-starter.mdx +++ b/fundamentals/ai-user-copilot/conversation-starter.mdx @@ -49,8 +49,8 @@ const receiverType = 'user/group'; const configuration = {lastNMessages: 100}; CometChat.getConversationStarter(receiverId, receiverType, configuration).then( - (conversation-starter) => { - console.log("Conversation Starter", conversation-starter); + (conversationStarter) => { + console.log("Conversation Starter", conversationStarter); }, (error) => { console.log("An error occurred while fetching conversation starter", error); @@ -150,4 +150,23 @@ CometChat.getConversationStarter(receiverId: "cometchat-uid-1", receiverType: .u ### UI Kits -Assuming the necessary prerequisites are met, Conversation Starter functions seamlessly starting from v4 of the Chat UI Kits. Similarly, Conversation Starter is triggered automatically when there are no messages in a conversation. +Assuming the necessary prerequisites are met, Conversation Starter functions seamlessly starting from v4 of the Chat UI Kits. No additional code is required: once you enable Conversation Starter in the dashboard, the UI Kit renders the suggestions automatically. It is triggered when there are no messages in a conversation, and in the React UI Kit it appears inside the [Message List](/ui-kit/react/message-list) component. + +For details on how each AI feature maps to a UI Kit component, see [Smart Chat Features in the React UI Kit](/ui-kit/react/ai-features). + +## Related + + + + AI-generated reply suggestions for an ongoing conversation. + + + A short recap of a long or unread conversation. + + + Configure your OpenAI model and key, then enable AI features. + + + See which UI Kit component renders each AI feature. + + diff --git a/fundamentals/ai-user-copilot/overview.mdx b/fundamentals/ai-user-copilot/overview.mdx index c9ebb9d08..297c65e71 100644 --- a/fundamentals/ai-user-copilot/overview.mdx +++ b/fundamentals/ai-user-copilot/overview.mdx @@ -10,6 +10,20 @@ Picture a chat that effortlessly starts and flows, like catching up with your be For those who require a concise overview of their discussions, the **Conversation Summary** feature is available to provide a succinct recap. +These features are powered by OpenAI. You configure your OpenAI model and API key once in the CometChat dashboard (below), enable each feature, and then either let the [UI Kits](/ui-kit/react/ai-features) render them automatically or fetch them yourself through the SDK. + + + + AI-generated opening lines for a new conversation. + + + Contextual positive, negative, and neutral reply suggestions. + + + A short recap of a long or unread conversation. + + + ## Pre-requisite * Login to your [CometChat dashboard](https://app.cometchat.com/login) and choose your app. @@ -21,11 +35,15 @@ For those who require a concise overview of their discussions, the **Conversatio ### Set the GPT Model -Enter the name of the Open AI ChatGPT model that you intend to use. +Enter the name of the OpenAI model that you intend to use. + + +Enter the exact OpenAI model name as it appears in OpenAI's documentation (for example, the value you would pass as the `model` parameter to the OpenAI API). For the current list of supported model names, refer to [OpenAI's models documentation](https://platform.openai.com/docs/models). If a model name is not accepted, confirm it is available on your OpenAI account. + -### Save the Open AI Key +### Save the OpenAI Key -You can get the Open AI Key from your [Open AI Account](https://platform.openai.com/account/api-keys). This will be used by CometChat to interact with the Open AI APIs. +You can get the OpenAI Key from your [OpenAI account](https://platform.openai.com/account/api-keys). This will be used by CometChat to interact with the OpenAI APIs. ### Set a Custom Instruction @@ -40,3 +58,10 @@ Lower values for temperature result in more consistent outputs, while higher val ### Enable AI Toggle on AI. + +## Rendering AI features in your app + +After the settings above are saved and AI is enabled, turn on the individual features you want (**Conversation Starter**, **Smart Replies**, **Conversation Summary**) and surface them in your app in one of two ways: + +- **UI Kits (no extra code):** Enable each feature from the dashboard and the UI Kit renders it automatically — Conversation Starter appears in the message list, while Smart Replies and Conversation Summary appear in the composer's action sheet. See [Smart Chat Features in the React UI Kit](/ui-kit/react/ai-features) for exactly which component shows each feature. +- **SDK methods (full control):** Fetch suggestions yourself and render your own UI. Each feature page documents its SDK method and configuration — see [Conversation Starter](/fundamentals/ai-user-copilot/conversation-starter), [Smart Replies](/fundamentals/ai-user-copilot/smart-replies), and [Conversation Summary](/fundamentals/ai-user-copilot/conversation-summary). For the JavaScript SDK reference, see the [AI User Copilot SDK overview](/sdk/javascript/ai-user-copilot-overview). diff --git a/fundamentals/ai-user-copilot/smart-replies.mdx b/fundamentals/ai-user-copilot/smart-replies.mdx index 11c8feb75..bfb7a956a 100644 --- a/fundamentals/ai-user-copilot/smart-replies.mdx +++ b/fundamentals/ai-user-copilot/smart-replies.mdx @@ -66,8 +66,8 @@ CometChat.getSmartReplies(receiverId, receiverType, configuration).then( ```java -String receiverId = 'UID/GUID'; -String receiverType = 'user/group'; +String receiverId = "UID/GUID"; +String receiverType = "user/group"; JSONObject configuration = new JSONObject(); try { configuration.put("lastNMessages", 100); @@ -95,8 +95,8 @@ CometChat.getSmartReplies(receiverId, CometChatConstants.RECEIVER_TYPE_USER, con ```kotlin -val receiverId: String = 'UID/GUID' -val receiverType: String = 'user/group' +val receiverId: String = "UID/GUID" +val receiverType: String = "user/group" val configuration = JSONObject() try { configuration.put("lastNMessages", 100) @@ -160,4 +160,23 @@ CometChat.getSmartReplies(receiveId, receiverType, configuration: configuration, ### UI Kits -Assuming the necessary prerequisites are met, Smart Replies function seamlessly starting from v4 of the Chat UI Kits. In v4, Smart Replies are accessible manually, whereas in v5, they work automatically. +Assuming the necessary prerequisites are met, Smart Replies function seamlessly starting from v4 of the Chat UI Kits. In v4, Smart Replies are accessible manually, whereas from v5 onward they work automatically — no additional code is required once the feature is enabled in the dashboard. In the React UI Kit, Smart Replies are surfaced in the action sheet of the [Message Composer](/ui-kit/react/message-composer) component. + +For details on how each AI feature maps to a UI Kit component, see [Smart Chat Features in the React UI Kit](/ui-kit/react/ai-features). + +## Related + + + + AI-generated opening lines for a new conversation. + + + A short recap of a long or unread conversation. + + + Configure your OpenAI model and key, then enable AI features. + + + See which UI Kit component renders each AI feature. + + diff --git a/fundamentals/avatars.mdx b/fundamentals/avatars.mdx index 089d2b6d5..464ffc38a 100644 --- a/fundamentals/avatars.mdx +++ b/fundamentals/avatars.mdx @@ -5,7 +5,7 @@ description: "Upload and update CometChat user avatar images with base64 files, -Deprecated: This extension is no longer maintained and will not receive further updates. +**Deprecated.** This extension is no longer maintained and will not receive further updates. To set a user's avatar, update the `avatar` field with the SDK's [User Management](/sdk/javascript/user-management) APIs. To display avatars in your UI, use the UI Kit's [Avatar element](/web-elements/avatar). diff --git a/fundamentals/data-import-and-migration.mdx b/fundamentals/data-import-and-migration.mdx index fbc7210b7..48623ca48 100644 --- a/fundamentals/data-import-and-migration.mdx +++ b/fundamentals/data-import-and-migration.mdx @@ -27,7 +27,15 @@ Import all your existing data at rest—stored messages, users, and groups—int - You want all historical data available from day one - Your migration can happen during a maintenance window -The Data Import APIs handle bulk ingestion of historical chat data, allowing you to transfer large volumes of users, messages, and group information efficiently. +The Data Import APIs handle bulk ingestion of historical chat data through four endpoints — [users](/rest-api/data-import-apis/users/import-users), [groups](/rest-api/data-import-apis/groups/import-groups), [group members](/rest-api/data-import-apis/groups/import-group-members), and [messages](/rest-api/data-import-apis/messages/import-messages). + +**Import in dependency order** so every reference resolves: users → groups → members → messages. + +**Throughput and batching.** Each request accepts up to **50 entities**, and the data-import endpoints are rate-limited to **60 requests per minute** (see [Rate Limits](/rest-api/rate-limits)). To ingest large volumes, batch your records into groups of 50 and pace requests to stay under the limit; a `ERR_TOO_MANY_REQUESTS` response tells you to retry after the indicated time. + +**Timestamps are preserved.** Each imported message carries a required `sentAt` field (a 10-digit UNIX timestamp), so conversation ordering and history reflect the original send times rather than the ingestion time. + +**Media.** Message media and attachments are supplied in the message's `data.attachments` object. For the full per-entity schema and field limits, see the [Import Messages reference](/rest-api/data-import-apis/messages/import-messages) and [Properties and Constraints](/articles/properties-and-constraints). ### Live Data Migration @@ -41,6 +49,45 @@ Live migration bridges both systems during the upgrade cycle, ensuring no messag ## Getting Started -**For Historical Data Import**: Use the [Data Import REST APIs](/rest-api/data-import) to programmatically import your users, messages, and groups. +### Historical Data Import + +All [Data Import REST API](/rest-api/data-import) requests go to your app's region-specific base URL and authenticate with the `apikey` header: + +```text +https://.api-.cometchat.io/v3/data_import +``` + +A message import request wraps each message by its unique `muid`. The minimum required fields per message are `muid`, `sender`, `receiverType`, `receiver`, and `sentAt`: + +```bash +curl -X POST "https://.api-.cometchat.io/v3/data_import/messages" \ + -H "apikey: YOUR_REST_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "guid": "support-group", + "name": "Support Group", + "type": "group", + "messages": { + "msg-1001": { + "muid": "msg-1001", + "sender": "cometchat-uid-1", + "receiverType": "group", + "receiver": "support-group", + "category": "message", + "type": "text", + "sentAt": 1700000000, + "data": { "text": "Hello from the migrated history" } + } + } + }' +``` + +Import in order — [users](/rest-api/data-import-apis/users/import-users) → [groups](/rest-api/data-import-apis/groups/import-groups) → [members](/rest-api/data-import-apis/groups/import-group-members) → [messages](/rest-api/data-import-apis/messages/import-messages) — batching up to 50 entities per request. + +### Live Data Migration + +[Contact our Sales team](https://www.cometchat.com/contact-sales) to scope your migration and set up the bridge that keeps your old system and CometChat in sync during a gradual rollout. -**For Live Data Migration**: [Contact our Sales team](https://www.cometchat.com/contact-sales) to discuss your migration requirements and set up the live migration process. + +Looking to upgrade an existing CometChat app from v2 to v3 (rather than import from another provider)? See the [Migration Guide](/articles/migration-guide). + diff --git a/fundamentals/disappearing-messages.mdx b/fundamentals/disappearing-messages.mdx index 96fd4efd7..64da63a61 100644 --- a/fundamentals/disappearing-messages.mdx +++ b/fundamentals/disappearing-messages.mdx @@ -22,7 +22,7 @@ The value of timeInMS should strictly be less than 1 year -This extension uses the `callExtension` method provided by the CometChat SDK. +This extension uses the `callExtension` method provided by the CometChat SDK. If you have not initialized and logged in to the SDK yet, complete that first via the [CometChat overview](/fundamentals/overview). diff --git a/fundamentals/end-to-end-encryption.mdx b/fundamentals/end-to-end-encryption.mdx index 0eaf9a2ec..50ea7714e 100644 --- a/fundamentals/end-to-end-encryption.mdx +++ b/fundamentals/end-to-end-encryption.mdx @@ -5,7 +5,7 @@ description: "Configure CometChat end-to-end encryption with Virgil Security key -Deprecated: This extension is no longer maintained and will not receive further updates. +**Deprecated.** This extension is no longer maintained and will not receive further updates. For the current set of available features, see the [Extensions overview](/fundamentals/extensions-overview) and the [CometChat overview](/fundamentals/overview). diff --git a/fundamentals/extensions-overview.mdx b/fundamentals/extensions-overview.mdx index a0d9e4393..f75c48c80 100644 --- a/fundamentals/extensions-overview.mdx +++ b/fundamentals/extensions-overview.mdx @@ -8,6 +8,28 @@ We believe that building a great chat product does not consist of just voice, vi Extensions pickup where our core leaves. They help extend the functionality of CometChat. +## How to enable an extension + +Every extension is turned on the same way — from the **Extensions** section of your CometChat dashboard. No reinstall or redeploy is required; once enabled, the extension is available to your app immediately. + + + + Log in to the [CometChat dashboard](https://app.cometchat.com/login) and select your app. + + + Go to the **Extensions** section, find the extension you want, and toggle it on. Some extensions (such as Giphy, Tenor, or Bitly) ask for additional configuration, like a third-party API key, before they can be used. + + + Many extensions are surfaced automatically by the [UI Kits](/ui-kit/react/overview). When you need to interact with an extension directly from the SDK, you call it through the `callExtension` method — for example, the [Polls](/fundamentals/polls) extension is created and voted on via `callExtension`. Each extension page below documents its exact request format and response. + + + + +Each extension's own page (linked below) lists its dashboard settings, any required keys, and the SDK calls or UI Kit behavior specific to that extension. Start there once the extension is enabled. + + +## Available extensions + ### User Experience Extensions that help improve the user messaging experience. *Recommended for most apps.* diff --git a/fundamentals/mentions.mdx b/fundamentals/mentions.mdx index 1d2c6294a..a1996b2d5 100644 --- a/fundamentals/mentions.mdx +++ b/fundamentals/mentions.mdx @@ -3,13 +3,11 @@ title: "Mentions (Legacy)" description: "Add CometChat mentions with @ user formatting, group member lookup, message rendering, and mention fetch calls." --- - + -**Legacy Notice**: This extension is already included as part of the core messaging experience and is scheduled for deprecation in the near future. +**Legacy.** Mentions are now built into the core messaging experience and no longer require this extension. Legacy extensions are not actively maintained and will not receive feature updates. For the current approach, see [Mentions in the JavaScript SDK](/sdk/javascript/mentions) (also available for [Android](/sdk/android/mentions), [iOS](/sdk/ios/mentions), [React Native](/sdk/react-native/mentions), and [Flutter](/sdk/flutter/mentions)), or the [React UI Kit Mentions Formatter guide](/ui-kit/react/v6/mentions-formatter-guide). -Please note: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements. - - + Mentions are a great way to get someone's attention in a conversation. Mentions start with the @ symbol followed by a name. diff --git a/fundamentals/overview.mdx b/fundamentals/overview.mdx index 4e4be0416..4d2543345 100644 --- a/fundamentals/overview.mdx +++ b/fundamentals/overview.mdx @@ -38,17 +38,31 @@ With a few lines of code, you can have CometChat integrated into any app written ## Build with tools of your choice +CometChat offers three integration paths. Pick the one that matches how much control you need and how fast you want to ship. + + + + Copy and paste a few lines of code to add text, voice, and video to your website in minutes — no frontend framework required. + + + Reduce your time to market with prebuilt, customizable chat and calling components. Available for React, React Native, Angular, iOS, Android, and Flutter. + + + Fully customizable and easy to use, with our SDKs and APIs for in-app messaging and voice & video calling. + + + ### No-code widget -Simply copy and paste a few lines of code to add text, voice, and video to your web app in minutes. +Simply copy and paste a few lines of code to add text, voice, and video to your web app in minutes. The widget works on plain HTML pages and popular CMS platforms. See the [Widget Builder for HTML](/widget/html/overview) to get started. -### Low-code UI Kits +### UI Kits -Reduce your time to market and give your users the modern chat experience they expect with UI kits. +Reduce your time to market and give your users the modern chat experience they expect with UI Kits. Choose the UI Kit for your stack: [React](/ui-kit/react/overview), [React Native](/ui-kit/react-native/overview), [Angular](/ui-kit/angular/overview), [iOS](/ui-kit/ios/overview), [Android](/ui-kit/android/overview), or [Flutter](/ui-kit/flutter/overview). ### SDKs & APIs -Fully customizable and easy to use? Yes, it's possible, with our SDKs and APIs for in-app messaging and voice & video calling. +Fully customizable and easy to use? Yes, it's possible, with our SDKs and APIs for in-app messaging and voice & video calling. Start with the [JavaScript SDK](/sdk/javascript/overview). ## Compliances @@ -129,4 +143,19 @@ CometChat is fully compliant with the following security standards: ## Moving forward -Next, have a look at the Implementation checklist to quickly integrate chat functionality into your app and prepare for a successful launch. +Next, have a look at the resources below to quickly integrate chat functionality into your app and prepare for a successful launch. + + + + A step-by-step path from signup to launch. + + + Understand apps, users, UIDs, groups, messages, and calls. + + + Add polls, reactions, translation, and more to your chat. + + + Conversation Starter, Smart Replies, and Conversation Summary. + + diff --git a/fundamentals/reactions.mdx b/fundamentals/reactions.mdx index f32811749..e9c2afded 100644 --- a/fundamentals/reactions.mdx +++ b/fundamentals/reactions.mdx @@ -3,13 +3,11 @@ title: "Reactions (Legacy)" description: "Add, remove, and fetch CometChat message reactions with emoji metadata and reaction extension calls." --- - + -**Legacy Notice**: This extension is already included as part of the core messaging experience and is scheduled for deprecation in the near future. +**Legacy.** Reactions are now built into the core messaging experience and no longer require this extension. Legacy extensions are not actively maintained and will not receive feature updates. For the current approach, see [Reactions in the JavaScript SDK](/sdk/javascript/reactions) (also available for [Android](/sdk/android/reactions), [iOS](/sdk/ios/reactions), [React Native](/sdk/react-native/reactions), and [Flutter](/sdk/flutter/reactions)), or the [React UI Kit Reactions component](/ui-kit/react/v7/components/reactions). -Please note: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements. - - + Reactions are the ability to react to an individual message with a specific emotion, quickly showing acknowledgment or expressing how you feel in a lightweight way. diff --git a/fundamentals/smart-replies.mdx b/fundamentals/smart-replies.mdx index 3499be07d..8b303406c 100644 --- a/fundamentals/smart-replies.mdx +++ b/fundamentals/smart-replies.mdx @@ -3,13 +3,11 @@ title: "Smart Replies (Legacy)" description: "Show CometChat smart reply suggestions with positive, neutral, and negative responses injected into message metadata." --- - + -**Legacy Notice**: This extension is already included as part of the core messaging experience (AI) and is scheduled for deprecation in the near future. +**Legacy.** Smart Replies are now part of the AI User Copilot in the core messaging experience and no longer require this extension. Legacy extensions are not actively maintained and will not receive feature updates. For the current approach, see [Smart Replies (AI User Copilot)](/fundamentals/ai-user-copilot/smart-replies) and the [AI User Copilot overview](/fundamentals/ai-user-copilot/overview). -Please note: Legacy extensions are no longer actively maintained and will not receive feature updates or enhancements. - - + The Smart Reply extension allows you to show quick reply options to a user so that they can easily respond to a message. We will always suggest 3 options; one positive, one neutral and one negative. We also add a category, in case you want to skip some suggestions. diff --git a/fundamentals/stickers-stipop.mdx b/fundamentals/stickers-stipop.mdx index f713f012c..f04a7af6e 100644 --- a/fundamentals/stickers-stipop.mdx +++ b/fundamentals/stickers-stipop.mdx @@ -3,6 +3,12 @@ title: "Stipop" description: "Add Stipop stickers to CometChat conversations with trending sticker packs, search, API keys, and extension calls." --- + + +**Legacy.** Stipop is a third-party sticker integration that is no longer actively maintained. For the maintained, dashboard-managed sticker experience, use the built-in [Stickers extension](/fundamentals/stickers) instead. + + + *Learn how to integrate stickers by Stipop in your app.* Stipop is the world's trendiest sticker platform and creator community. diff --git a/fundamentals/user-auth.mdx b/fundamentals/user-auth.mdx index b3414baef..5e8f9d7b7 100644 --- a/fundamentals/user-auth.mdx +++ b/fundamentals/user-auth.mdx @@ -25,15 +25,39 @@ Once the user is successfully logged into CometChat, we can proceed to request o ## Create Chat User in CometChat -1. Handle the user creation endpoint in your application. -2. Add the user to your database. -3. Invoke the [CometChat API endpoint to create a user](/rest-api/chat-apis). +When a new user signs up in your app, create a matching CometChat user **from your server** using the [Create User API](/rest-api/users/create). Pass `withAuthToken: true` to also mint a login token in the same call. - * Optionally, pass a parameter to generate an authentication token for this user. +1. In your own sign-up flow, create the user in your database. +2. From your **backend**, call `POST /v3/users` with the user's `uid` and `name`. +3. CometChat returns the created user (and an auth token when `withAuthToken` is set). +4. Return that auth token to your front-end to log the user in. -4. CometChat will respond with the authentication token to your server. -5. Your server will send the successful user creation response to your front-end application. -6. Utilize the CometChat auth token to log the user into the [CometChat SDK / UI Kit](https://www.cometchat.com/docs/javascript-chat-sdk/authentication#login-using-auth-token), or [Widget](/widget/html/integration#3-backend-created-user-auth-token-login). +```bash +curl -X POST "https://.api-.cometchat.io/v3/users" \ + -H "apikey: YOUR_REST_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "uid": "cometchat-uid-1", + "name": "Andrew Joseph", + "withAuthToken": true + }' +``` + + +Call this from your **server only** — it requires the `fullAccess` REST API Key, which must never ship in client-side code. See [REST API Authentication](/rest-api/authentication) for key scopes. + + +The `uid` must be unique, **≤ 100 characters**, alphanumeric with dashes (no spaces), and **cannot be changed** after creation. For the full field list and limits, see the [Create User reference](/rest-api/users/create). + +Then log the user into the [SDK / UI Kit](/sdk/javascript/authentication-overview) or [Widget](/widget/html/integration#3-backend-created-user-auth-token-login) with the returned token: + +```javascript +// SDK +CometChat.login(authToken).then(user => { /* logged in */ }); + +// UI Kit +CometChatUIKit.loginWithAuthToken(authToken); +``` CometChat - Create Chat User @@ -41,11 +65,23 @@ Once the user is successfully logged into CometChat, we can proceed to request o ## Log In an Existing User -1. Authenticate the user within your application. -2. Your API will then request a CometChat auth token for the user. You can call the [create auth token API endpoint](/rest-api/chat-apis) to create a new one. -3. Your server responds with the successful retrieval of the CometChat auth token to your front-end application. -4. Utilize the CometChat auth token to log the user into the [CometChat SDK / UI Kit](https://www.cometchat.com/docs/javascript-chat-sdk/authentication#login-using-auth-token), -5. If you’re using the **Widget Builder**, refer to the documentation on **[auth token–based user login](/widget/html/integration#3-backend-created-user-auth-token-login)**. +The user already exists in CometChat, so you only need a fresh auth token each time they sign in to your app. + +1. Authenticate the user with your own backend. +2. From your server, generate a token via the [Create Auth Token API](/rest-api/auth-tokens/create) — `POST /v3/users/{uid}/auth_tokens`. +3. Return the token to your front-end. +4. Log in with `CometChat.login(authToken)` (SDK) or `CometChatUIKit.loginWithAuthToken(authToken)` (UI Kit). For the **Widget Builder**, see [auth token–based login](/widget/html/integration#3-backend-created-user-auth-token-login). + +```bash +curl -X POST "https://.api-.cometchat.io/v3/users/cometchat-uid-1/auth_tokens" \ + -H "apikey: YOUR_REST_API_KEY" +``` + +### Auth token lifecycle + +- **Expiry:** auth tokens **do not expire by default**, which keeps users signed in across devices. Generating a new token does not invalidate older ones on their own. +- **Retention:** CometChat keeps only the **100 most recent** auth tokens per user; older tokens are automatically archived and invalidated. +- **Revoking sessions:** delete one token with [Delete Auth Token](/rest-api/auth-tokens/delete), or sign a user out everywhere with [Flush Auth Tokens](/rest-api/auth-tokens/flush) (`DELETE /v3/users/{uid}/auth_tokens`). CometChat - Logging On a User @@ -53,4 +89,4 @@ Once the user is successfully logged into CometChat, we can proceed to request o ## Migrate Existing Users to CometChat -If you need to migrate the existing users, refer to the [Data Import Guide](https://www.cometchat.com/docs/rest-api/data-import) \ No newline at end of file +If you need to migrate existing users in bulk, see [Data Import and Migration](/fundamentals/data-import-and-migration). \ No newline at end of file diff --git a/fundamentals/video-broadcasting.mdx b/fundamentals/video-broadcasting.mdx index 6e277246a..d4f588746 100644 --- a/fundamentals/video-broadcasting.mdx +++ b/fundamentals/video-broadcasting.mdx @@ -5,7 +5,7 @@ description: "Set up CometChat live streaming with api.video, OBS broadcast deta -Deprecated: This extension is no longer maintained and will not receive further updates. +**Deprecated.** This extension is no longer maintained and will not receive further updates. For real-time audio/video sessions, use CometChat's [Voice & Video Calling](/calls/javascript/overview) instead. diff --git a/fundamentals/webhooks-overview.mdx b/fundamentals/webhooks-overview.mdx index 184619b43..b4055240c 100644 --- a/fundamentals/webhooks-overview.mdx +++ b/fundamentals/webhooks-overview.mdx @@ -7,6 +7,8 @@ CometChat Webhooks enable real-time, event-driven communication with your server You can use webhooks to build custom workflows such as sending SMS or email notifications, logging activity, syncing with external systems, or triggering automation. +This page is an **event reference** — it lists every webhook trigger and links to its payload. If you are setting up webhooks for the first time, start with the [Webhooks guide](/fundamentals/webhooks), which walks through creating an endpoint, testing it locally with a tunnel, registering the webhook, and the `before_message` / `after_message` triggers. To create and manage webhooks programmatically, see the [Webhooks REST APIs](/rest-api/management-apis/webhooks/overview). + *** ## Setting Up Your Webhook Endpoint @@ -173,3 +175,22 @@ CometChat supports webhook triggers for different categories of events. Click ea *** By following this guide, you can seamlessly integrate CometChat webhooks into your system and build event-driven experiences at scale. + +*** + +## Where to go next + + + + Create an endpoint, test it locally, register the webhook, and use message triggers. + + + Create webhooks programmatically. + + + Attach event triggers to an existing webhook. + + + Full reference for managing webhooks. + + diff --git a/fundamentals/webhooks.mdx b/fundamentals/webhooks.mdx index 80dbdae3c..4d274ead0 100644 --- a/fundamentals/webhooks.mdx +++ b/fundamentals/webhooks.mdx @@ -62,8 +62,59 @@ CometChat supports **Basic Authentication** to secure your webhook endpoints. Wh - **Log everything**: Maintain detailed logs for debugging and monitoring - **Test thoroughly**: Simulate various conditions before going to production -## Getting Started +## Message Triggers + +For message events you choose **when** CometChat calls your endpoint: + +| Trigger | When it fires | Typical use | +| --- | --- | --- | +| `after_message` | After a message has been sent and delivered. | Notifications, analytics, syncing external systems. | +| `before_message` | While a message is in-flight, before it reaches the recipient. | Enrich, validate, or block a message before delivery. | + +A `before_message` endpoint can **add metadata** to the message by returning a JSON object. CometChat merges your response into the message under `@injected.webhooks`: -You can configure webhooks through the CometChat Dashboard or programmatically via the Management APIs. +```json +{ + "@injected": { + "webhooks": { + "webhook-id": { + // JSON object returned from your endpoint + } + } + } +} +``` + +It can also **drop the message** entirely by returning: + +```json +{ + "action": "do_not_propagate" +} +``` + +## Getting Started -For detailed setup instructions and API documentation, refer to the [Webhooks REST APIs](/rest-api/management-apis/webhooks/overview). + + + Add a route that accepts an **HTTP POST** with a JSON body and returns **200 OK**. This is no different from adding any other route in your web framework. + + + Expose your local server with a tunneling tool such as [ngrok](https://ngrok.com) so CometChat can reach it during development: + + ```bash + ngrok http 8000 + ``` + + Use the HTTPS forwarding URL it prints (e.g. `https://xxxx.ngrok.io`) as your webhook destination. + + + In the Dashboard's **Webhooks** section choose **Create Webhook**, enter your endpoint URL, then open **View/Update** to add a trigger. You can also create webhooks programmatically with the [Create Webhook REST API](/rest-api/management-apis/webhooks/create-webhook). + + + +For the full setup walkthrough and per-platform payloads, see the SDK webhooks guides — for example [JavaScript](/sdk/javascript/webhooks) or [Android](/sdk/android/v5/webhooks-overview) — and the [Webhooks REST APIs](/rest-api/management-apis/webhooks/overview). + + +Retry/backoff behaviour and request-signature verification beyond Basic Authentication are not documented here — confirm the current behaviour with the CometChat team before relying on it in production. + diff --git a/moderation/open-ai/openai-overview.mdx b/moderation/open-ai/openai-overview.mdx index 6ab9a100b..7170a2f3c 100644 --- a/moderation/open-ai/openai-overview.mdx +++ b/moderation/open-ai/openai-overview.mdx @@ -3,7 +3,7 @@ title: "Overview" description: "Use OpenAI moderation with CometChat to detect harmful messages, configure prompts, choose models, and apply moderation actions." --- -CometChat offers AI-powered message moderation to help maintain a safe and respectful chat environment. You can choose between two moderation options: +CometChat offers AI-powered message moderation to help maintain a safe and respectful chat environment. You can choose between two AI moderation options: **OpenAI Moderation** (configured entirely in the dashboard, described below) and the [Custom API](/moderation/custom/custom-api-overview) approach, which lets you bring your own moderation service or model. OpenAI moderation is one of the rule types available in CometChat's [moderation rules engine](/moderation/rules-management) — if you are new to moderation, start with the [moderation Getting Started guide](/moderation/getting-started). ### **OpenAI Moderation** Leverage OpenAI’s AI models to automatically detect and filter offensive, harmful, or inappropriate messages in real time. This option allows you to: @@ -13,4 +13,31 @@ Leverage OpenAI’s AI models to automatically detect and filter offensive, harm - **Flexible Moderation Actions** – Block, allow, or take fallback actions if the API request fails. - **Secure API Management** – Provide and manage OpenAI credentials directly in the CometChat dashboard. -This moderation provide flexibility to enhance user safety and compliance within your chat platform. +This moderation provides flexibility to enhance user safety and compliance within your chat platform. + +## How it works + +When a message is sent, CometChat evaluates it against your enabled moderation rules. For an OpenAI rule, CometChat sends the message (optionally with recent conversation history for context) to OpenAI using the prompt and model you configured, then applies the action you defined — block, flag for review, or allow — based on the confidence threshold. If the OpenAI request fails, CometChat falls back to the behavior you selected (approve or block). + +Setting OpenAI moderation up involves three dashboard steps: creating an **OpenAI Prompt** list, configuring the **OpenAI model and API key** in Advanced Settings, and mapping the list to a **moderation rule**. + + + Step-by-step configuration: create the prompt list, set the model and API key, and create the rule. + + +## Next steps + + + + Understand the full moderation feature set. + + + Set up moderation rules and integration. + + + Create and manage moderation rules. + + + Bring your own moderation service or model. + + diff --git a/notifications/react-native-push-notifications-ios.mdx b/notifications/react-native-push-notifications-ios.mdx index f5489fc6e..3b54b9bec 100644 --- a/notifications/react-native-push-notifications-ios.mdx +++ b/notifications/react-native-push-notifications-ios.mdx @@ -23,6 +23,8 @@ description: "Bring the SampleAppWithPushNotifications experience—APNs + VoIP Reference implementation of React Native UI Kit and APNs Push Notification setup. +New to CometChat notifications? Read the [Push Notifications Overview](/notifications/push-overview) first for how providers, tokens, and the Notifications API fit together. For the Android counterpart of this guide, see [React Native Push Notifications (Android)](/notifications/react-native-push-notifications-android). + ## What this guide covers - CometChat Dashboard setup (enable push, add APNs provider). @@ -569,9 +571,11 @@ Send a VoIP push with `push_type=voip` via APNs using a payload shaped like: ## 6. Handling notification taps and navigation -To handle notification taps and navigate to the appropriate chat screen, you need to set up handlers for both foreground and background notifications. +To handle notification taps and navigate to the appropriate chat screen, you need to set up handlers for both foreground and background notifications. The `PushNotificationIOS` notification listener shown in [Section 7.4](#7-4-register-notification-listener) is where you read the tapped payload (for example `data.userInteraction === 1` and `data.conversationId`) and route to the matching conversation. -{/* :TODO: Add code snippets and explanation for setting up Notifee handlers and navigation logic. */} + +A complete navigation example (wiring a navigation ref and routing on tap) is not included here. See the reference [SampleAppWithPushNotifications](https://github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleAppWithPushNotifications) for an end-to-end implementation. + ## 7. Badge Count Implementation @@ -837,6 +841,9 @@ Set up FCM push notifications for Android Strip HTML tags and customize notification content + +Configure and manage unread badge counts + Learn how to send different types of messages diff --git a/widget/squarespace/overview.mdx b/widget/squarespace/overview.mdx index 91fc1809d..27625c0ba 100644 --- a/widget/squarespace/overview.mdx +++ b/widget/squarespace/overview.mdx @@ -57,14 +57,23 @@ Once configured, get the embed code snippet for your widget. 2. Note your app credentials (App ID, Auth Key, Region, Variant ID) 3. Copy the code snippet +#### What these credentials mean + +| Credential | What it is | +| --- | --- | +| **App ID** | The unique identifier of your CometChat app, from the [Dashboard](https://app.cometchat.com). | +| **Region** | The region your app is provisioned in (for example `us`, `eu`, `in`). | +| **Auth Key** | An app-level key used to log users in directly from the page. Convenient for development, but it is visible to anyone who views your page source — see [Authenticating users](#authenticating-users) below. | +| **Variant ID** | Identifies a specific saved version (snapshot) of your Widget Builder configuration. If you omit it, the first available variant is used. | + ### 3. Integrate Add the embed code to your Squarespace website and go live. 1. **Open Code Injection** — Go to Settings → Advanced → Code Injection in your Squarespace dashboard 2. **Paste the code snippet** into the Footer section of Code Injection -3. **Configure credentials** — Set your App ID, Region, and Auth Key -4. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality. +3. **Configure credentials** — Set your App ID, Region, and Auth Key in the snippet +4. **Authenticate users** — Choose a sign-in mode so CometChat knows who each visitor is (see [Authenticating users](#authenticating-users) below) 5. **Launch** — Save and the chat widget is live on your Squarespace site + + `mode: "guest"` lets anyone chat without an account. CometChat assigns a temporary identity. Best for marketing pages, help centers, and demos. + + + `mode: "uid"` logs people in with an ID you already have (member ID, email, etc.). CometChat creates the user the first time it sees that UID. No backend required. + + + `mode: "authToken"` logs people in with a short-lived token your **server** generates. This keeps your Auth Key off the page and is the recommended choice for production. + + + + +**Do not ship your Auth Key in production.** In guest and UID modes the Auth Key is embedded in the page and is visible to anyone who views the source. For production, generate a per-user **auth token on your server** and log in with `mode: "authToken"` instead. See [Authentication and User Management](/fundamentals/user-auth) for the server-side flow. + + +The full Squarespace [Integration Guide](/widget/squarespace/integration) includes copy-paste snippets for all three modes, including a Squarespace Members auto-login example and the [auth token login flow](/widget/squarespace/integration#3-backend-created-user-auth-token-login). + + +Squarespace's member-identity APIs are owned by Squarespace and are outside CometChat's control. To map logged-in Squarespace members to CometChat UIDs, consult [Squarespace's own developer documentation](https://developers.squarespace.com/) for the member object available on your plan, then pass that ID as the `uid` (UID mode) or use it server-side to mint an auth token. + + +--- + ## Try Live Demo Experience the CometChat Widget Builder in action: @@ -126,15 +163,15 @@ Experience the CometChat Widget Builder in action: ## Related Resources + + Create users and issue server-generated auth tokens + Learn more about the CometChat JavaScript SDK Widget Builder for HTML websites - - Widget Builder for Wix websites - Widget Builder for Webflow websites diff --git a/widget/webflow/integration.mdx b/widget/webflow/integration.mdx index 8d9e2c7c0..e15d858b4 100644 --- a/widget/webflow/integration.mdx +++ b/widget/webflow/integration.mdx @@ -8,6 +8,8 @@ import AdvancedJSAPIs from "/snippets/widget/advanced-js-apis.mdx"; Add the CometChat Widget with a single snippet in a Webflow **Embed** element. Pick the sign-in flow that matches your site: guests, auto-created users from your IDs, or backend-issued auth tokens. +CometChat identifies every person by a **UID** (User ID) — a unique, unchangeable string such as `user_123`, an email, or a member ID. Each flow below is just a different way of telling the widget which UID to log in. For the underlying user-creation and token model, see [Authentication and User Management](/fundamentals/user-auth). + **Choose how visitors sign in:** @@ -381,6 +383,10 @@ Use this when your Webflow site uses Memberstack and you want the widget to log **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. + +This is the **recommended flow for production**. Guest and UID modes embed your Auth Key in the page, where it is visible to anyone viewing the source. Auth tokens are minted per user on your server, so the Auth Key never reaches the browser. See [Authentication and User Management](/fundamentals/user-auth) for the create-user and token-generation details. + + **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) — you can also request an auth token in that call. diff --git a/widget/webflow/overview.mdx b/widget/webflow/overview.mdx index 5a0bfe11e..85124b5d5 100644 --- a/widget/webflow/overview.mdx +++ b/widget/webflow/overview.mdx @@ -57,14 +57,23 @@ Once configured, get the embed code snippet for your widget. 2. Note your app credentials (App ID, Auth Key, Region, Variant ID) 3. Copy the code snippet +#### What these credentials mean + +| Credential | What it is | +| --- | --- | +| **App ID** | The unique identifier of your CometChat app, from the [Dashboard](https://app.cometchat.com). | +| **Region** | The region your app is provisioned in (for example `us`, `eu`, `in`). | +| **Auth Key** | An app-level key used to log users in directly from the page. Convenient for development, but it is visible to anyone who views your page source — see [Authenticating users](#authenticating-users) below. | +| **Variant ID** | Identifies a specific saved version (snapshot) of your Widget Builder configuration. If you omit it, the first available variant is used. | + ### 3. Integrate Add the embed code to your Webflow website and go live. 1. **Add a custom code embed** — In the Webflow Designer, add an Embed element to your page 2. **Paste the code snippet** into the Embed element -3. **Configure credentials** — Set your App ID, Region, and Auth Key -4. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality. +3. **Configure credentials** — Set your App ID, Region, and Auth Key in the snippet +4. **Authenticate users** — Choose a sign-in mode so CometChat knows who each visitor is (see [Authenticating users](#authenticating-users) below) 5. **Launch** — Publish your Webflow site and the chat widget is live + + `mode: "guest"` lets anyone chat without an account. CometChat assigns a temporary identity. Best for marketing pages, help centers, and demos. + + + `mode: "uid"` logs people in with an ID you already have (member ID, email, etc.). CometChat creates the user the first time it sees that UID. No backend required. + + + `mode: "authToken"` logs people in with a short-lived token your **server** generates. This keeps your Auth Key off the page and is the recommended choice for production. + + + + +**Do not ship your Auth Key in production.** In guest and UID modes the Auth Key is embedded in the page and is visible to anyone who views the source. For production, generate a per-user **auth token on your server** and log in with `mode: "authToken"` instead. See [Authentication and User Management](/fundamentals/user-auth) for the server-side flow. + + +The full Webflow [Integration Guide](/widget/webflow/integration) includes copy-paste snippets for all three modes, including a Memberstack auto-login example and the [auth token login flow](/widget/webflow/integration#3-backend-created-user-auth-token-login). + + +Webflow's member-identity APIs (such as Memberstack) are owned by those platforms and are outside CometChat's control. To map a logged-in member to a CometChat UID, consult that platform's own documentation for the member object, then pass that ID as the `uid` (UID mode) or use it server-side to mint an auth token. The Integration Guide shows a worked Memberstack example. + + +--- + ## Try Live Demo Experience the CometChat Widget Builder in action: @@ -126,15 +163,15 @@ Experience the CometChat Widget Builder in action: ## Related Resources + + Create users and issue server-generated auth tokens + Learn more about the CometChat JavaScript SDK Widget Builder for HTML websites - - Widget Builder for Shopify stores - Widget Builder for Squarespace websites diff --git a/widget/wordpress/overview.mdx b/widget/wordpress/overview.mdx index 0a37b9759..d8b2eb58c 100644 --- a/widget/wordpress/overview.mdx +++ b/widget/wordpress/overview.mdx @@ -61,13 +61,22 @@ Once configured, get the embed code snippet for your widget. 2. Note your app credentials (App ID, Auth Key, Region, Variant ID) 3. Copy the code snippet +#### What these credentials mean + +| Credential | What it is | +| --- | --- | +| **App ID** | The unique identifier of your CometChat app, from the [Dashboard](https://app.cometchat.com). | +| **Region** | The region your app is provisioned in (for example `us`, `eu`, `in`). | +| **Auth Key** | An app-level key used to log users in. The plugin stores it in its settings — see [Authenticating users](#authenticating-users) below for production guidance. | +| **Variant ID** | Identifies a specific saved version (snapshot) of your Widget Builder configuration, set with the `variant-id` shortcode attribute. If you omit it, the first available variant is used. | + ### 3. Integrate Install the CometChat plugin on your WordPress site and go live. 1. **Install the plugin** — Download and activate the CometChat WordPress plugin 2. **Configure credentials** — Set your App ID, Region, and Auth Key in the plugin settings -3. **User Authentication** — CometChat uses a UID (User ID) to identify each user. Authenticate users to enable chat functionality. +3. **Authenticate users** — Identify each visitor with a UID so they can send and receive messages (see [Authenticating users](#authenticating-users) below) 4. **Launch** — Use shortcodes or the plugin settings to display the chat widget on your site +**The Auth Key logs users in directly and should not be used to authenticate real users in production.** For production, create users and generate a per-user **auth token on your server**, then log users in with that token. This is the same pattern used across CometChat's UI Kit, SDK, and Widget. See [Authentication and User Management](/fundamentals/user-auth) for the full server-side flow, and the [auth token login example](/widget/html/integration#3-backend-created-user-auth-token-login) for a worked widget snippet. + + + +Mapping logged-in WordPress accounts to CometChat UIDs (for example, deriving the UID from the WordPress user) depends on your theme and plugin setup. The shortcode and plugin settings in the [Integration Guide](/widget/wordpress/integration) show where the UID is configured. + + +--- + ## Try Live Demo Experience the CometChat Widget Builder in action: @@ -129,15 +152,15 @@ Experience the CometChat Widget Builder in action: ## Related Resources + + Create users and issue server-generated auth tokens + Learn more about the CometChat JavaScript SDK Widget Builder for HTML websites - - Widget Builder for Shopify stores - Widget Builder for Wix websites