diff --git a/docs.json b/docs.json index 0eacee627..266f1340a 100644 --- a/docs.json +++ b/docs.json @@ -44,7 +44,9 @@ { "group": "Docs MCP", "hidden": true, - "pages": ["mcp-server"] + "pages": [ + "mcp-server" + ] } ] }, @@ -96,7 +98,9 @@ { "dropdown": "Kubernetes", "icon": "/images/icons/kubernetes.svg", - "pages": ["on-premise-deployment/kubernetes/overview"] + "pages": [ + "on-premise-deployment/kubernetes/overview" + ] } ] } @@ -107,7 +111,9 @@ "tabs": [ { "tab": "Chat & Calling", - "pages": ["chat-call"] + "pages": [ + "chat-call" + ] }, { "tab": "Platform", @@ -220,11 +226,15 @@ }, { "group": "User-Roles", - "pages": ["fundamentals/user-roles-and-permissions"] + "pages": [ + "fundamentals/user-roles-and-permissions" + ] }, { "group": "Guides", - "pages": ["fundamentals/user-auth"] + "pages": [ + "fundamentals/user-auth" + ] } ] }, @@ -279,7 +289,10 @@ { "dropdown": "Wix", "icon": "/images/icons/wix.svg", - "pages": ["/widget/wix/overview", "/widget/wix/integration"] + "pages": [ + "/widget/wix/overview", + "/widget/wix/integration" + ] }, { "dropdown": "Webflow", @@ -1017,9 +1030,9 @@ { "group": "Migration Guide", "pages": [ - "ui-kit/react-native/upgrading-from-v4" + "ui-kit/react-native/upgrading-from-v4" ] - }, + }, "ui-kit/react-native/troubleshooting", "ui-kit/react-native/link/sample", "ui-kit/react-native/link/changelog" @@ -1305,7 +1318,10 @@ }, { "group": "Reference", - "pages": ["ui-kit/ios/methods", "ui-kit/ios/events"] + "pages": [ + "ui-kit/ios/methods", + "ui-kit/ios/events" + ] }, { "group": "Advanced", @@ -2552,33 +2568,15 @@ { "group": " ", "pages": [ - { - "group": "Overview", - "pages": [ - "sdk/javascript/overview", - "sdk/javascript/key-concepts", - "sdk/javascript/message-structure-and-hierarchy", - "sdk/javascript/rate-limits" - ] - }, - { - "group": "Setup", - "pages": ["sdk/javascript/setup-sdk"] - }, - { - "group": "Authentication", - "pages": [ - "sdk/javascript/authentication-overview", - "sdk/javascript/login-listener" - ] - }, + "sdk/javascript/overview", + "sdk/javascript/setup-sdk", + "sdk/javascript/authentication-overview", { "group": "Messaging", "pages": [ - "sdk/javascript/messaging-overview", "sdk/javascript/send-message", "sdk/javascript/receive-message", - "sdk/javascript/additional-message-filtering", + "sdk/javascript/message-filtering", "sdk/javascript/retrieve-conversations", "sdk/javascript/threaded-messages", "sdk/javascript/edit-message", @@ -2621,7 +2619,9 @@ }, { "group": "User Presence", - "pages": ["sdk/javascript/user-presence"] + "pages": [ + "sdk/javascript/user-presence" + ] }, { "group": "Groups", @@ -2645,17 +2645,21 @@ { "group": "Resources", "pages": [ - "sdk/javascript/resources-overview", "sdk/javascript/all-real-time-listeners", - "sdk/javascript/upgrading-from-v3" + "sdk/javascript/key-concepts", + "sdk/javascript/message-structure-and-hierarchy", + "sdk/javascript/rate-limits", + "sdk/javascript/connection-status", + "sdk/javascript/managing-web-sockets-connections-manually" ] }, { - "group": "Advanced", + "group": "Reference", "pages": [ - "sdk/javascript/advanced-overview", - "sdk/javascript/connection-status", - "sdk/javascript/managing-web-sockets-connections-manually" + "sdk/reference/messages", + "sdk/reference/entities", + "sdk/reference/auxiliary", + "sdk/reference/calls" ] }, { @@ -2666,10 +2670,13 @@ "sdk/javascript/angular-overview" ] }, + "sdk/javascript/best-practices", + "sdk/javascript/troubleshooting", "sdk/javascript/extensions-overview", "sdk/javascript/ai-user-copilot-overview", "sdk/javascript/ai-chatbots-overview", "sdk/javascript/webhooks-overview", + "sdk/javascript/upgrading-from-v3", "sdk/javascript/changelog" ] } @@ -4746,7 +4753,9 @@ }, { "group": "Users", - "pages": ["rest-api/data-import-apis/users/import-users"] + "pages": [ + "rest-api/data-import-apis/users/import-users" + ] }, { "group": "Groups", @@ -5266,7 +5275,9 @@ "tabs": [ { "tab": "AI Agents", - "pages": ["ai-agents"] + "pages": [ + "ai-agents" + ] }, { "tab": "Agent Builder", @@ -5329,11 +5340,15 @@ "/ai-agents/crew-ai-tools", { "group": "Guides", - "pages": ["/ai-agents/crew-ai-knowledge-agent"] + "pages": [ + "/ai-agents/crew-ai-knowledge-agent" + ] }, { "group": "Tutorials", - "pages": ["/ai-agents/crew-ai-product-hunt-agent"] + "pages": [ + "/ai-agents/crew-ai-product-hunt-agent" + ] } ] }, @@ -5346,11 +5361,15 @@ "/ai-agents/agno-tools", { "group": "Guides", - "pages": ["/ai-agents/agno-knowledge-agent"] + "pages": [ + "/ai-agents/agno-knowledge-agent" + ] }, { "group": "Tutorials", - "pages": ["/ai-agents/agno-product-hunt-agent"] + "pages": [ + "/ai-agents/agno-product-hunt-agent" + ] } ] }, @@ -5363,11 +5382,15 @@ "/ai-agents/vercel-tools", { "group": "Guides", - "pages": ["/ai-agents/vercel-knowledge-agent"] + "pages": [ + "/ai-agents/vercel-knowledge-agent" + ] }, { "group": "Tutorials", - "pages": ["/ai-agents/vercel-product-hunt-agent"] + "pages": [ + "/ai-agents/vercel-product-hunt-agent" + ] } ] }, @@ -5378,11 +5401,15 @@ "/ai-agents/langgraph", { "group": "Guides", - "pages": ["/ai-agents/langgraph-knowledge-agent"] + "pages": [ + "/ai-agents/langgraph-knowledge-agent" + ] }, { "group": "Tutorials", - "pages": ["/ai-agents/langgraph-product-hunt-agent"] + "pages": [ + "/ai-agents/langgraph-product-hunt-agent" + ] } ] }, @@ -5395,11 +5422,15 @@ "/ai-agents/ag2-tools", { "group": "Guides", - "pages": ["/ai-agents/ag2-knowledge-agent"] + "pages": [ + "/ai-agents/ag2-knowledge-agent" + ] }, { "group": "Tutorials", - "pages": ["/ai-agents/ag2-product-hunt-agent"] + "pages": [ + "/ai-agents/ag2-product-hunt-agent" + ] } ] }, @@ -5412,7 +5443,9 @@ "/ai-agents/ag-ui-tools", { "group": "Guides", - "pages": ["/ai-agents/cometchat-ag-ui-byoa"] + "pages": [ + "/ai-agents/cometchat-ag-ui-byoa" + ] }, { "group": "Implementation", @@ -5428,12 +5461,16 @@ { "tab": "Widget Builder", "tab-id": "ai-agent-chat-builder", - "pages": ["/ai-agents/chat-widget"] + "pages": [ + "/ai-agents/chat-widget" + ] }, { "tab": "Custom Bots", "hidden": true, - "pages": ["/ai-chatbots/custom-bots"] + "pages": [ + "/ai-chatbots/custom-bots" + ] }, { "tab": "AI Bots (Legacy)", @@ -5631,7 +5668,9 @@ "tabs": [ { "tab": "Notifications", - "pages": ["notifications"] + "pages": [ + "notifications" + ] }, { "tab": "Push", @@ -5663,7 +5702,9 @@ }, { "group": " ", - "pages": ["notifications/push-notifications-extension-legacy"] + "pages": [ + "notifications/push-notifications-extension-legacy" + ] } ] }, @@ -5677,7 +5718,9 @@ "notifications/email-custom-providers", { "group": " ", - "pages": ["notifications/email-notifications-extension-legacy"] + "pages": [ + "notifications/email-notifications-extension-legacy" + ] } ] }, @@ -5691,7 +5734,9 @@ "notifications/sms-custom-providers", { "group": " ", - "pages": ["notifications/sms-notifications-extension-legacy"] + "pages": [ + "notifications/sms-notifications-extension-legacy" + ] } ] } @@ -5702,7 +5747,9 @@ "tabs": [ { "tab": "Insights", - "pages": ["insights"] + "pages": [ + "insights" + ] } ] } @@ -6447,7 +6494,7 @@ }, { "source": "/notifications/react-native-push-notifications", - "destination": "/notifications/react-native-push-notifications-android" + "destination": "/notifications/react-native-push-notifications-android" }, { "source": "/sdk/ionic/overview", diff --git a/sdk/ionic-legacy/additional-message-filtering.mdx b/sdk/ionic-legacy/additional-message-filtering.mdx index 343228c3b..feab05e15 100644 --- a/sdk/ionic-legacy/additional-message-filtering.mdx +++ b/sdk/ionic-legacy/additional-message-filtering.mdx @@ -23,6 +23,8 @@ Once you have an object of the `MessagesRequest` class, you can call either the 1. fetchNext() - Calling this method will return the messages after the specified parameters. 2. fetchPrevious() - Calling this method will give you messages before the specified parameters. +Both `fetchPrevious()` and `fetchNext()` return an array of [`BaseMessage`](/sdk/reference/messages#basemessage) objects (which may be [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), [`CustomMessage`](/sdk/reference/messages#custommessage), or other subclasses depending on the filters applied). + Since messages are obtained in a paginated manner, a `maximum of 100` messages can be pulled in a single iteration. Calling the `fetchPrevious()`/`fetchNext()` method on the same `MessagesRequest` object will get you the next set of messages. Now that you are clear how to use the `MessagesRequest` class, below are the various options available: diff --git a/sdk/javascript/advanced-overview.mdx b/sdk/javascript/advanced-overview.mdx index 7a8e791f6..d38b93f35 100644 --- a/sdk/javascript/advanced-overview.mdx +++ b/sdk/javascript/advanced-overview.mdx @@ -1,8 +1,47 @@ --- title: "Advanced" sidebarTitle: "Overview" +description: "Advanced SDK features including connection management, real-time listeners, login listeners, and WebSocket configuration." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Check connection status +CometChat.getConnectionStatus(); // "connected" | "connecting" | "disconnected" + +// Listen for connection changes +CometChat.addConnectionListener("LISTENER_ID", new CometChat.ConnectionListener({ + onConnected: () => console.log("Connected"), + onDisconnected: () => console.log("Disconnected") +})); + +// Listen for login events +CometChat.addLoginListener("LISTENER_ID", new CometChat.LoginListener({ + onLoginSuccess: (user) => console.log("Logged in:", user), + onLogoutSuccess: () => console.log("Logged out") +})); +``` + This section helps you to know about the Connection Listeners. + +--- + +## Next Steps + + + + Monitor and respond to connection state changes + + + Manually manage WebSocket connections + + + Listen for login and logout events + + + Complete reference for all SDK listeners + + diff --git a/sdk/javascript/ai-agents.mdx b/sdk/javascript/ai-agents.mdx index f4b88d96a..7c089a64c 100644 --- a/sdk/javascript/ai-agents.mdx +++ b/sdk/javascript/ai-agents.mdx @@ -1,57 +1,76 @@ --- title: "AI Agents" +sidebarTitle: "AI Agents" +description: "Integrate AI Agents, AI Moderation, and AI User Copilot into your app using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + + +| Feature | Description | +| --- | --- | +| [AI Agents](#agent-run-lifecycle-and-message-flow) | Intelligent automated conversations with real-time streaming | +| [AI Moderation](/sdk/javascript/ai-moderation) | Automatic content moderation with `PENDING` → `APPROVED` / `DISAPPROVED` flow | +| [AI User Copilot](/fundamentals/ai-user-copilot/overview) | Smart Replies, Conversation Starter, Conversation Summary (Dashboard-enabled) | + +```javascript +// Listen for real-time AI Agent events (streaming) +CometChat.addAIAssistantListener("LISTENER_ID", { + onAIAssistantEventReceived: (event) => console.log("Event:", event) +}); + +// Listen for persisted agentic messages +CometChat.addMessageListener("LISTENER_ID", { + onAIAssistantMessageReceived: (msg) => console.log("Assistant reply:", msg), + onAIToolResultReceived: (msg) => console.log("Tool result:", msg), + onAIToolArgumentsReceived: (msg) => console.log("Tool args:", msg) +}); + +// Cleanup +CometChat.removeAIAssistantListener("LISTENER_ID"); +CometChat.removeMessageListener("LISTENER_ID"); +``` + +**Prerequisites:** `CometChat.init()` + `CometChat.login()` completed, AI features enabled in [Dashboard](https://app.cometchat.com) +**Event flow:** Run Start → Tool Call(s) → Text Message Stream → Run Finished + + # AI Agents Overview -AI Agents enable intelligent, automated interactions within your application. They can process user messages, trigger tools, and respond with contextually relevant information. For a broader introduction, see the [AI Agents section](/ai-agents). +AI Agents enable intelligent, automated interactions within your application. They process user messages, trigger tools, and respond with contextually relevant information. For a broader introduction, see the [AI Agents section](/ai-agents). -> **Note:** -> Currently, an Agent only responds to **Text Messages**. + +Agents only respond to text messages. + ## Agent Run Lifecycle and Message Flow -This section explains how a user’s text message to an Agent becomes a structured "run" which emits real-time events and then produces agentic messages for historical retrieval. -- A user sends a text message to an Agent. -- The platform starts a run and streams real-time events via the **`AIAssistantListener`**. -- After the run completes, persisted Agentic Messages arrive via the **`MessageListener`**. +When a user sends a text message to an Agent: +1. The platform starts a run and streams real-time events via `AIAssistantListener` +2. After the run completes, persisted Agentic Messages arrive via `MessageListener` ### Real-time Events -Events are received via the **`onAIAssistantEventReceived`** method of the **`AIAssistantListener`** class in this general order: - -1. Run Start -2. Zero or more tool call cycles (repeats for each tool invocation): - - Tool Call Start - - Tool Call Arguments - - Tool Call End - - Tool Call Result -3. One or more assistant reply streams: - - Text Message Start - - Text Message Content (multiple times; token/char streaming) - - Text Message End -4. Run Finished - -Notes: -- `Run Start` and `Run Finished` are always emitted. -- `Tool Call` events appear only when a backend or frontend tool is invoked. There can be multiple tool calls in a single run. -- `Text Message` events are always emitted and carry the assistant’s reply incrementally. +Events are received via the **`onAIAssistantEventReceived`** method of the **`AIAssistantListener`** class as [`AIAssistantBaseEvent`](/sdk/reference/messages#aiassistantbaseevent) objects, in this general order: + +Events arrive via `onAIAssistantEventReceived` in this order: + +| Order | Event | Description | +|-------|-------|-------------| +| 1 | Run Start | A new run has begun | +| 2 | Tool Call Start | Agent decided to invoke a tool | +| 3 | Tool Call Arguments | Arguments being passed to the tool | +| 4 | Tool Call End | Tool execution completed | +| 5 | Tool Call Result | Tool's output is available | +| 6 | Text Message Start | Agent started composing a reply | +| 7 | Text Message Content | Streaming content chunks (multiple) | +| 8 | Text Message End | Agent reply is complete | +| 9 | Run Finished | Run finalized; persisted messages follow | + + +`Run Start` and `Run Finished` are always emitted. Tool Call events only appear when tools are invoked. + - - ```js - const listnerId = "unique_listener_id"; - - // Adding the AIAssistantListener - CometChat.addAIAssistantListener(listnerId, { - onAIAssistantEventReceived: (message) => { - console.log("AIAssistant event received successfully", message); - } - }); - - // Removing the AIAssistantListener - CometChat.removeAIAssistantListener(listnerId); - ``` - ```ts const listnerId: string = "unique_listener_id"; @@ -83,24 +102,53 @@ Notes: ### Agentic Messages These events are received via the **`MessageListener`** after the run completes. -- `AIAssistantMessage`: The full assistant reply. -- `AIToolResultMessage`: The final output of a tool call. -- `AIToolArgumentMessage`: The arguments that were passed to a tool. +- [`AIAssistantMessage`](/sdk/reference/messages#aiassistantmessage): The full assistant reply. +- [`AIToolResultMessage`](/sdk/reference/messages#aitoolresultmessage): The final output of a tool call. +- [`AIToolArgumentMessage`](/sdk/reference/messages#aitoolargumentmessage): The arguments that were passed to a tool. ```js const listnerId = "unique_listener_id"; + // Adding the AIAssistantListener + CometChat.addAIAssistantListener(listnerId, { + onAIAssistantEventReceived: (message) => { + console.log("AIAssistant event received successfully", message); + } + }); + + // Removing the AIAssistantListener + CometChat.removeAIAssistantListener(listnerId); + ``` + + + +### Agentic Messages + +After the run completes, these messages arrive via `MessageListener`: + +| Message Type | Description | +|--------------|-------------| +| `AIAssistantMessage` | The full assistant reply | +| `AIToolResultMessage` | The final output of a tool call | +| `AIToolArgumentMessage` | The arguments passed to a tool | + + + + + ```ts + const listnerId: string = "unique_listener_id"; + // Adding the MessageListener CometChat.addMessageListener(listnerId, { - onAIAssistantMessageReceived: (message) => { + onAIAssistantMessageReceived: (message: CometChat.AIAssistantMessage) => { console.log("AI Assistant message received successfully", message); }, - onAIToolResultReceived: (message) => { + onAIToolResultReceived: (message: CometChat.AIToolResultMessage) => { console.log("AI Tool result message received successfully", message); }, - onAIToolArgumentsReceived: (message) => { + onAIToolArgumentsReceived: (message: CometChat.AIToolArgumentMessage) => { console.log("AI Tool argument message received successfully", message); }, }); @@ -109,20 +157,19 @@ These events are received via the **`MessageListener`** after the run completes. CometChat.removeMessageListener(listnerId); ``` - - - ```ts - const listnerId: string = "unique_listener_id"; + + ```js + const listnerId = "unique_listener_id"; // Adding the MessageListener CometChat.addMessageListener(listnerId, { - onAIAssistantMessageReceived: (message: CometChat.AIAssistantMessage) => { + onAIAssistantMessageReceived: (message) => { console.log("AI Assistant message received successfully", message); }, - onAIToolResultReceived: (message: CometChat.AIToolResultMessage) => { + onAIToolResultReceived: (message) => { console.log("AI Tool result message received successfully", message); }, - onAIToolArgumentsReceived: (message: CometChat.AIToolArgumentMessage) => { + onAIToolArgumentsReceived: (message) => { console.log("AI Tool argument message received successfully", message); }, }); @@ -131,4 +178,28 @@ These events are received via the **`MessageListener`** after the run completes. CometChat.removeMessageListener(listnerId); ``` - \ No newline at end of file + + + + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + +--- + +## Next Steps + + + + Set up AI-powered chatbots for automated conversations + + + Automatically moderate messages with AI + + + AI-powered features like smart replies and conversation summaries + + + Send text messages that trigger AI Agent responses + + diff --git a/sdk/javascript/ai-integration-quick-reference.mdx b/sdk/javascript/ai-integration-quick-reference.mdx new file mode 100644 index 000000000..e2ce6b1dd --- /dev/null +++ b/sdk/javascript/ai-integration-quick-reference.mdx @@ -0,0 +1,258 @@ +--- +title: "AI Integration Quick Reference" +sidebarTitle: "AI Quick Reference" +description: "Quick reference for AI features in the CometChat JavaScript SDK: AI Agents, AI Moderation, and AI User Copilot." +--- + + + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| AI Features | AI Agents, AI Moderation, AI User Copilot | +| Activation | Enable from [CometChat Dashboard](https://app.cometchat.com) | +| Prerequisites | `CometChat.init()` + `CometChat.login()` completed | +| AI Agents | Real-time streaming via `AIAssistantListener`, persisted messages via `MessageListener` | +| AI Moderation | Automatic content moderation with `PENDING` → `APPROVED` / `DISAPPROVED` flow | +| AI User Copilot | Smart Replies, Conversation Starter, Conversation Summary (Dashboard-enabled) | + + + +## Overview + +CometChat provides three AI-powered features to enhance your chat application: + +| Feature | Description | Use Case | +| --- | --- | --- | +| [AI Agents](/sdk/javascript/ai-agents) | Intelligent automated conversations with real-time streaming | Chatbots, virtual assistants, automated support | +| [AI Moderation](/sdk/javascript/ai-moderation) | Automatic content moderation for text, image, and video messages | Safety, compliance, content filtering | +| [AI User Copilot](/fundamentals/ai-user-copilot/overview) | Smart replies, conversation starters, and summaries | Enhanced user experience, productivity | + +## AI Features Summary + +### AI Agents + +AI Agents enable intelligent, automated interactions. They process user messages, trigger tools, and respond with contextually relevant information. + +**Key Points:** +- Agents only respond to text messages +- Real-time events via `AIAssistantListener` +- Persisted messages via `MessageListener` +- Event flow: Run Start → Tool Call(s) → Text Message Stream → Run Finished + + + + ```typescript + const listnerId: string = "unique_listener_id"; + + // Adding the AIAssistantListener for real-time events + CometChat.addAIAssistantListener(listnerId, { + onAIAssistantEventReceived: (message: CometChat.AIAssistantBaseEvent) => { + console.log("AIAssistant event received successfully", message); + } + }); + + // Adding the MessageListener for persisted agentic messages + CometChat.addMessageListener(listnerId, { + onAIAssistantMessageReceived: (message: CometChat.AIAssistantMessage) => { + console.log("AI Assistant message received successfully", message); + }, + onAIToolResultReceived: (message: CometChat.AIToolResultMessage) => { + console.log("AI Tool result message received successfully", message); + }, + onAIToolArgumentsReceived: (message: CometChat.AIToolArgumentMessage) => { + console.log("AI Tool argument message received successfully", message); + }, + }); + + // Cleanup - always remove listeners when done + CometChat.removeAIAssistantListener(listnerId); + CometChat.removeMessageListener(listnerId); + ``` + + + ```javascript + const listnerId = "unique_listener_id"; + + // Adding the AIAssistantListener for real-time events + CometChat.addAIAssistantListener(listnerId, { + onAIAssistantEventReceived: (message) => { + console.log("AIAssistant event received successfully", message); + } + }); + + // Adding the MessageListener for persisted agentic messages + CometChat.addMessageListener(listnerId, { + onAIAssistantMessageReceived: (message) => { + console.log("AI Assistant message received successfully", message); + }, + onAIToolResultReceived: (message) => { + console.log("AI Tool result message received successfully", message); + }, + onAIToolArgumentsReceived: (message) => { + console.log("AI Tool argument message received successfully", message); + }, + }); + + // Cleanup - always remove listeners when done + CometChat.removeAIAssistantListener(listnerId); + CometChat.removeMessageListener(listnerId); + ``` + + + +### AI Moderation + +AI Moderation automatically reviews messages for inappropriate content in real-time. + +**Key Points:** +- Supports Text, Image, and Video messages only +- Moderation statuses: `PENDING` → `APPROVED` or `DISAPPROVED` +- Enable and configure rules in the CometChat Dashboard + + + + ```typescript + // Send message and check initial moderation status + const textMessage = new CometChat.TextMessage( + receiverUID, + "Hello, how are you?", + CometChat.RECEIVER_TYPE.USER + ); + + CometChat.sendMessage(textMessage).then( + (message: CometChat.TextMessage) => { + const status: string = message.getModerationStatus(); + + if (status === CometChat.ModerationStatus.PENDING) { + console.log("Message is under moderation review"); + } + }, + (error: CometChat.CometChatException) => { + console.log("Message sending failed:", error); + } + ); + + // Listen for moderation results + const listenerID: string = "MODERATION_LISTENER"; + + CometChat.addMessageListener( + listenerID, + new CometChat.MessageListener({ + onMessageModerated: (message: CometChat.BaseMessage) => { + const status: string = message.getModerationStatus(); + const messageId: number = message.getId(); + + switch (status) { + case CometChat.ModerationStatus.APPROVED: + console.log(`Message ${messageId} approved`); + break; + case CometChat.ModerationStatus.DISAPPROVED: + console.log(`Message ${messageId} blocked`); + break; + } + } + }) + ); + ``` + + + ```javascript + // Send message and check initial moderation status + const textMessage = new CometChat.TextMessage( + receiverUID, + "Hello, how are you?", + CometChat.RECEIVER_TYPE.USER + ); + + CometChat.sendMessage(textMessage).then( + (message) => { + const status = message.getModerationStatus(); + + if (status === CometChat.ModerationStatus.PENDING) { + console.log("Message is under moderation review"); + } + }, + (error) => { + console.log("Message sending failed:", error); + } + ); + + // Listen for moderation results + const listenerID = "MODERATION_LISTENER"; + + CometChat.addMessageListener( + listenerID, + new CometChat.MessageListener({ + onMessageModerated: (message) => { + const status = message.getModerationStatus(); + const messageId = message.getId(); + + switch (status) { + case CometChat.ModerationStatus.APPROVED: + console.log(`Message ${messageId} approved`); + break; + case CometChat.ModerationStatus.DISAPPROVED: + console.log(`Message ${messageId} blocked`); + break; + } + } + }) + ); + ``` + + + +### AI User Copilot + +AI User Copilot provides smart features that enhance user productivity. These features are enabled in the Dashboard and auto-integrate with UI Kits. + +| Feature | Description | Documentation | +| --- | --- | --- | +| Conversation Starter | AI-generated opening lines for new chats | [Learn more](/fundamentals/ai-user-copilot/conversation-starter) | +| Smart Replies | AI-generated response suggestions | [Learn more](/fundamentals/ai-user-copilot/smart-replies) | +| Conversation Summary | AI-generated recap of long conversations | [Learn more](/fundamentals/ai-user-copilot/conversation-summary) | + +## Configuration Options + +### AI Agents Configuration + +| Parameter | Type | Description | +| --- | --- | --- | +| `listenerId` | `string` | Unique identifier for the listener | +| `onAIAssistantEventReceived` | `function` | Callback for real-time streaming events | +| `onAIAssistantMessageReceived` | `function` | Callback for persisted assistant messages | +| `onAIToolResultReceived` | `function` | Callback for tool execution results | +| `onAIToolArgumentsReceived` | `function` | Callback for tool arguments | + +### AI Moderation Configuration + +| Parameter | Type | Description | +| --- | --- | --- | +| `listenerID` | `string` | Unique identifier for the listener | +| `onMessageModerated` | `function` | Callback when moderation result is available | + +### Moderation Status Values + +| Status | Enum | Description | +| --- | --- | --- | +| Pending | `CometChat.ModerationStatus.PENDING` | Message is being processed | +| Approved | `CometChat.ModerationStatus.APPROVED` | Message passed moderation | +| Disapproved | `CometChat.ModerationStatus.DISAPPROVED` | Message was blocked | + +## Next Steps + + + + Full documentation for AI Agents integration + + + Complete AI Moderation implementation guide + + + Smart Replies, Conversation Starter, and Summary + + + Common issues and fixes + + diff --git a/sdk/javascript/ai-moderation.mdx b/sdk/javascript/ai-moderation.mdx index 768de5403..44f8a4482 100644 --- a/sdk/javascript/ai-moderation.mdx +++ b/sdk/javascript/ai-moderation.mdx @@ -1,10 +1,35 @@ --- title: "AI Moderation" +sidebarTitle: "AI Moderation" +description: "Automatically moderate chat messages using AI to detect and block inappropriate content in real-time." --- +{/* TL;DR for Agents and Quick Reference */} + + +```javascript +// Send message — check moderation status +CometChat.sendMessage(textMessage).then(message => { + const status = message.getModerationStatus(); + // CometChat.ModerationStatus.PENDING | APPROVED | DISAPPROVED +}); + +// Listen for moderation results +CometChat.addMessageListener("MOD_LISTENER", new CometChat.MessageListener({ + onMessageModerated: (message) => { + const status = message.getModerationStatus(); + // Handle APPROVED or DISAPPROVED + } +})); +``` + +**Supported types:** Text, Image, Video messages only +**Statuses:** `PENDING` → `APPROVED` or `DISAPPROVED` + + ## Overview -AI Moderation in the CometChat SDK helps ensure that your chat application remains safe and compliant by automatically reviewing messages for inappropriate content. This feature leverages AI to moderate messages in real-time, reducing manual intervention and improving user experience. +AI Moderation automatically reviews messages for inappropriate content in real-time, reducing manual intervention and improving user experience. For a broader understanding of moderation features, configuring rules, and managing flagged messages, see the [Moderation Overview](/moderation/overview). @@ -12,11 +37,9 @@ For a broader understanding of moderation features, configuring rules, and manag ## Prerequisites -Before using AI Moderation, ensure the following: - -1. Moderation is enabled for your app in the [CometChat Dashboard](https://app.cometchat.com) -2. Moderation rules are configured under **Moderation > Rules** -3. You're using CometChat SDK version that supports moderation +1. Moderation enabled in the [CometChat Dashboard](https://app.cometchat.com) +2. Moderation rules configured under **Moderation > Rules** +3. CometChat SDK version that supports moderation ## How It Works @@ -73,8 +96,8 @@ The `getModerationStatus()` method returns one of the following values: When you send a text, image, or video message, check the initial moderation status: - - ```javascript + + ```typescript const textMessage = new CometChat.TextMessage( receiverUID, "Hello, how are you?", @@ -82,23 +105,23 @@ When you send a text, image, or video message, check the initial moderation stat ); CometChat.sendMessage(textMessage).then( - (message) => { + (message: CometChat.TextMessage) => { // Check moderation status - const status = message.getModerationStatus(); + const status: string = message.getModerationStatus(); if (status === CometChat.ModerationStatus.PENDING) { console.log("Message is under moderation review"); // Show pending indicator in UI } }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Message sending failed:", error); } ); ``` - - ```typescript + + ```javascript const textMessage = new CometChat.TextMessage( receiverUID, "Hello, how are you?", @@ -106,16 +129,16 @@ When you send a text, image, or video message, check the initial moderation stat ); CometChat.sendMessage(textMessage).then( - (message: CometChat.TextMessage) => { + (message) => { // Check moderation status - const status: string = message.getModerationStatus(); + const status = message.getModerationStatus(); if (status === CometChat.ModerationStatus.PENDING) { console.log("Message is under moderation review"); // Show pending indicator in UI } }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Message sending failed:", error); } ); @@ -128,20 +151,20 @@ When you send a text, image, or video message, check the initial moderation stat Register a message listener to receive moderation results in real-time: - - ```javascript - const listenerID = "MODERATION_LISTENER"; + + ```typescript + const listenerID: string = "MODERATION_LISTENER"; CometChat.addMessageListener( listenerID, new CometChat.MessageListener({ - onMessageModerated: (message) => { + onMessageModerated: (message: CometChat.BaseMessage) => { if ( message instanceof CometChat.TextMessage || message instanceof CometChat.MediaMessage ) { - const status = message.getModerationStatus(); - const messageId = message.getId(); + const status: string = message.getModerationStatus(); + const messageId: number = message.getId(); switch (status) { case CometChat.ModerationStatus.APPROVED: @@ -164,20 +187,20 @@ Register a message listener to receive moderation results in real-time: // CometChat.removeMessageListener(listenerID); ``` - - ```typescript - const listenerID: string = "MODERATION_LISTENER"; + + ```javascript + const listenerID = "MODERATION_LISTENER"; CometChat.addMessageListener( listenerID, new CometChat.MessageListener({ - onMessageModerated: (message: CometChat.BaseMessage) => { + onMessageModerated: (message) => { if ( message instanceof CometChat.TextMessage || message instanceof CometChat.MediaMessage ) { - const status: string = message.getModerationStatus(); - const messageId: number = message.getId(); + const status = message.getModerationStatus(); + const messageId = message.getId(); switch (status) { case CometChat.ModerationStatus.APPROVED: @@ -300,5 +323,23 @@ Here's a complete implementation showing the full moderation flow: + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + ## Next Steps -After implementing AI Moderation, consider adding a reporting feature to allow users to flag messages they find inappropriate. For more details, see the [Flag Message](/sdk/javascript/flag-message) documentation. + + + + Allow users to report inappropriate messages manually + + + Build intelligent automated conversations with AI Agents + + + Smart replies, conversation summaries, and more + + + Send text, media, and custom messages + + diff --git a/sdk/javascript/all-real-time-listeners.mdx b/sdk/javascript/all-real-time-listeners.mdx index a70adfb54..1fde0de5b 100644 --- a/sdk/javascript/all-real-time-listeners.mdx +++ b/sdk/javascript/all-real-time-listeners.mdx @@ -1,8 +1,43 @@ --- title: "All Real Time Listeners" +description: "Complete reference for all CometChat real-time listeners including User, Group, Message, Call, AI Assistant, and Ongoing Call (Calls SDK) listeners." --- +{/* TL;DR for Agents and Quick Reference */} + + +```javascript +// User Listener — online/offline presence +CometChat.addUserListener("ID", new CometChat.UserListener({ + onUserOnline: (user) => { }, + onUserOffline: (user) => { } +})); + +// Message Listener — messages, typing, receipts, reactions +CometChat.addMessageListener("ID", new CometChat.MessageListener({ + onTextMessageReceived: (msg) => { }, + onMediaMessageReceived: (msg) => { }, + onTypingStarted: (indicator) => { }, + onMessagesRead: (receipt) => { } +})); + +// Group Listener — member join/leave/kick/ban/scope changes +CometChat.addGroupListener("ID", new CometChat.GroupListener({ ... })); + +// Call Listener — incoming/outgoing call events +CometChat.addCallListener("ID", new CometChat.CallListener({ ... })); + +// Always clean up +CometChat.removeUserListener("ID"); +CometChat.removeMessageListener("ID"); +CometChat.removeGroupListener("ID"); +CometChat.removeCallListener("ID"); +``` + + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + CometChat provides 4 listeners viz. @@ -10,6 +45,8 @@ CometChat provides 4 listeners viz. 2. [Group Listener](/sdk/javascript/all-real-time-listeners#group-listener) 3. [Message Listener](/sdk/javascript/all-real-time-listeners#message-listener) 4. [Call Listener](/sdk/javascript/all-real-time-listeners#call-listener) +5. [AI Assistant Listener](/sdk/javascript/all-real-time-listeners#ai-assistant-listener) +6. [Ongoing Call Listener (Calls SDK)](/sdk/javascript/all-real-time-listeners#ongoing-call-listener-calls-sdk) ## User Listener @@ -23,16 +60,18 @@ The `UserListener` class provides you with live events related to users. Below a To add the `UserListener`, you need to use the `addUserListener()` method provided by the `CometChat` class. - -```js -var listenerID = "UNIQUE_LISTENER_ID"; + +```typescript +const listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.addUserListener( listenerID, new CometChat.UserListener({ - onUserOnline: (onlineUser) => { + onUserOnline: (onlineUser: CometChat.User) => { + /* when someuser/friend comes online, user will be received here */ console.log("On User Online:", { onlineUser }); }, - onUserOffline: (offlineUser) => { + onUserOffline: (offlineUser: CometChat.User) => { + /* when someuser/friend went offline, user will be received here */ console.log("On User Offline:", { offlineUser }); }, }) @@ -41,18 +80,16 @@ CometChat.addUserListener( - -```typescript -var listenerID: string = "UNIQUE_LISTENER_ID"; + +```js +const listenerID = "UNIQUE_LISTENER_ID"; CometChat.addUserListener( listenerID, new CometChat.UserListener({ - onUserOnline: (onlineUser: CometChat.User) => { - /* when someuser/friend comes online, user will be received here */ + onUserOnline: (onlineUser) => { console.log("On User Online:", { onlineUser }); }, - onUserOffline: (offlineUser: CometChat.User) => { - /* when someuser/friend went offline, user will be received here */ + onUserOffline: (offlineUser) => { console.log("On User Offline:", { offlineUser }); }, }) @@ -68,13 +105,6 @@ where `UNIQUE_LISTENER_ID` is the unique identifier for the listener. Please mak Once the `UserListener` is not in use, you need to remove the listener using the `removeUserListener()` method which takes the id of the listener to be removed as the parameter. - -```js -CometChat.removeUserListener(UNIQUE_LISTENER_ID); -``` - - - ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; @@ -83,6 +113,13 @@ CometChat.removeUserListener(listenerID); + +```js +CometChat.removeUserListener(UNIQUE_LISTENER_ID); +``` + + + ## Group Listener @@ -102,18 +139,31 @@ The `GroupListener` class provides you with all the real-time events related to To add the `GroupListener`, you need to use the `addGroupListener()` method provided by the `CometChat` class. - -```js + +```typescript CometChat.addGroupListener( "UNIQUE_LISTENER_ID", new CometChat.GroupListener({ - onGroupMemberJoined: (message, joinedUser, joinedGroup) => { + onGroupMemberJoined: ( + message: CometChat.Action, + joinedUser: CometChat.User, + joinedGroup: CometChat.Group + ) => { console.log("onGroupMemberJoined", { message, joinedUser, joinedGroup }); }, - onGroupMemberLeft: (message, leftUser, leftGroup) => { + onGroupMemberLeft: ( + message: CometChat.Action, + leftUser: CometChat.User, + leftGroup: CometChat.Group + ) => { console.log("onGroupMemberLeft", { message, leftUser, leftGroup }); }, - onGroupMemberKicked: (message, kickedUser, kickedBy, kickedFrom) => { + onGroupMemberKicked: ( + message: CometChat.Action, + kickedUser: CometChat.User, + kickedBy: CometChat.User, + kickedFrom: CometChat.Group + ) => { console.log("onGroupMemberKicked", { message, kickedUser, @@ -121,7 +171,12 @@ CometChat.addGroupListener( kickedFrom, }); }, - onGroupMemberBanned: (message, bannedUser, bannedBy, bannedFrom) => { + onGroupMemberBanned: ( + message: CometChat.Action, + bannedUser: CometChat.User, + bannedBy: CometChat.User, + bannedFrom: CometChat.Group + ) => { console.log("onGroupMemberBanned", { message, bannedUser, @@ -130,10 +185,10 @@ CometChat.addGroupListener( }); }, onGroupMemberUnbanned: ( - message, - unbannedUser, - unbannedBy, - unbannedFrom + message: CometChat.Action, + unbannedUser: CometChat.User, + unbannedBy: CometChat.User, + unbannedFrom: CometChat.Group ) => { console.log("onGroupMemberUnbanned", { message, @@ -143,11 +198,11 @@ CometChat.addGroupListener( }); }, onGroupMemberScopeChanged: ( - message, - changedUser, - newScope, - oldScope, - changedGroup + message: CometChat.Action, + changedUser: CometChat.User, + newScope: string, + oldScope: string, + changedGroup: CometChat.Group ) => { console.log("onGroupMemberScopeChanged", { message, @@ -157,7 +212,12 @@ CometChat.addGroupListener( changedGroup, }); }, - onMemberAddedToGroup: (message, userAdded, addedby, addedTo) => { + onMemberAddedToGroup: ( + message: CometChat.Action, + userAdded: CometChat.User, + addedby: CometChat.User, + addedTo: CometChat.Group + ) => { console.log("onMemberAddedToGroup", { message, userAdded, @@ -171,31 +231,18 @@ CometChat.addGroupListener( - -```typescript + +```js CometChat.addGroupListener( "UNIQUE_LISTENER_ID", new CometChat.GroupListener({ - onGroupMemberJoined: ( - message: CometChat.Action, - joinedUser: CometChat.User, - joinedGroup: CometChat.Group - ) => { + onGroupMemberJoined: (message, joinedUser, joinedGroup) => { console.log("onGroupMemberJoined", { message, joinedUser, joinedGroup }); }, - onGroupMemberLeft: ( - message: CometChat.Action, - leftUser: CometChat.User, - leftGroup: CometChat.Group - ) => { + onGroupMemberLeft: (message, leftUser, leftGroup) => { console.log("onGroupMemberLeft", { message, leftUser, leftGroup }); }, - onGroupMemberKicked: ( - message: CometChat.Action, - kickedUser: CometChat.User, - kickedBy: CometChat.User, - kickedFrom: CometChat.Group - ) => { + onGroupMemberKicked: (message, kickedUser, kickedBy, kickedFrom) => { console.log("onGroupMemberKicked", { message, kickedUser, @@ -203,12 +250,7 @@ CometChat.addGroupListener( kickedFrom, }); }, - onGroupMemberBanned: ( - message: CometChat.Action, - bannedUser: CometChat.User, - bannedBy: CometChat.User, - bannedFrom: CometChat.Group - ) => { + onGroupMemberBanned: (message, bannedUser, bannedBy, bannedFrom) => { console.log("onGroupMemberBanned", { message, bannedUser, @@ -217,10 +259,10 @@ CometChat.addGroupListener( }); }, onGroupMemberUnbanned: ( - message: CometChat.Action, - unbannedUser: CometChat.User, - unbannedBy: CometChat.User, - unbannedFrom: CometChat.Group + message, + unbannedUser, + unbannedBy, + unbannedFrom ) => { console.log("onGroupMemberUnbanned", { message, @@ -230,11 +272,11 @@ CometChat.addGroupListener( }); }, onGroupMemberScopeChanged: ( - message: CometChat.Action, - changedUser: CometChat.User, - newScope: string, - oldScope: string, - changedGroup: CometChat.Group + message, + changedUser, + newScope, + oldScope, + changedGroup ) => { console.log("onGroupMemberScopeChanged", { message, @@ -244,12 +286,7 @@ CometChat.addGroupListener( changedGroup, }); }, - onMemberAddedToGroup: ( - message: CometChat.Action, - userAdded: CometChat.User, - addedby: CometChat.User, - addedTo: CometChat.Group - ) => { + onMemberAddedToGroup: (message, userAdded, addedby, addedTo) => { console.log("onMemberAddedToGroup", { message, userAdded, @@ -270,13 +307,6 @@ where `UNIQUE_LISTENER_ID` is the unique identifier for the listener. Please mak Once the `GroupListener` is not in use, you need to remove the listener using the `removeGroupListener()` method which takes the id of the listener to be removed as the parameter. - -```js -CometChat.removeGroupListener(UNIQUE_LISTENER_ID); -``` - - - ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; @@ -285,6 +315,13 @@ CometChat.removeGroupListener(listenerID); + +```js +CometChat.removeGroupListener(UNIQUE_LISTENER_ID); +``` + + + ## Message Listener @@ -308,6 +345,11 @@ The `MessageListener` class provides you with live events related to messages. B | **onMessageReactionAdded(receipt: CometChat.ReactionEvent)** | This event is triggered when a reaction is added to a message in a user/group conversation. | | **onMessageReactionRemoved(receipt: CometChat.ReactionEvent)** | This event is triggered when a reaction is remove from a message in a user/group conversation. | | **onMessageModerated(message: CometChat.BaseMessage)** | This event is triggered when a message sent by the logged-in user is successfully processed by moderation and receives either an `approved` or `disapproved` status. | +| **onMessagesDeliveredToAll(receipt: CometChat.MessageReceipt)** | This event is triggered when a group message is delivered to all members. Group conversations only. | +| **onMessagesReadByAll(receipt: CometChat.MessageReceipt)** | This event is triggered when a group message is read by all members. Group conversations only. | +| **onAIAssistantMessageReceived(message: CometChat.AIAssistantMessage)** | This event is triggered when a persisted AI assistant reply is received after an agent run completes. | +| **onAIToolResultReceived(message: CometChat.AIToolResultMessage)** | This event is triggered when a persisted AI tool result message is received after an agent run completes. | +| **onAIToolArgumentsReceived(message: CometChat.AIToolArgumentMessage)** | This event is triggered when a persisted AI tool argument message is received after an agent run completes. | To add the `MessageListener`, you need to use the `addMessageListener()` method provided by the `CometChat` class. @@ -361,6 +403,21 @@ CometChat.addMessageListener( onMessageModerated: (message) => { console.log("Message Moderated", message); }, + onMessagesDeliveredToAll: (messageReceipt) => { + console.log("Message Delivered to All", messageReceipt); + }, + onMessagesReadByAll: (messageReceipt) => { + console.log("Message Read by All", messageReceipt); + }, + onAIAssistantMessageReceived: (message) => { + console.log("AI Assistant message received", message); + }, + onAIToolResultReceived: (message) => { + console.log("AI Tool result received", message); + }, + onAIToolArgumentsReceived: (message) => { + console.log("AI Tool arguments received", message); + }, }) ); ``` @@ -417,6 +474,77 @@ CometChat.addMessageListener( onMessageModerated: (message: CometChat.BaseMessage) => { console.log("Message Moderated", message); }, + onMessagesDeliveredToAll: (messageReceipt: CometChat.MessageReceipt) => { + console.log("Message Delivered to All", messageReceipt); + }, + onMessagesReadByAll: (messageReceipt: CometChat.MessageReceipt) => { + console.log("Message Read by All", messageReceipt); + }, + onAIAssistantMessageReceived: (message: CometChat.AIAssistantMessage) => { + console.log("AI Assistant message received", message); + }, + onAIToolResultReceived: (message: CometChat.AIToolResultMessage) => { + console.log("AI Tool result received", message); + }, + onAIToolArgumentsReceived: (message: CometChat.AIToolArgumentMessage) => { + console.log("AI Tool arguments received", message); + }, + }) +); +``` + + + + +```js +CometChat.addMessageListener( + "UNIQUE_LISTENER_ID", + new CometChat.MessageListener({ + onTextMessageReceived: (textMessage) => { + console.log("Text message received successfully", textMessage); + }, + onMediaMessageReceived: (mediaMessage) => { + console.log("Media message received successfully", mediaMessage); + }, + onCustomMessageReceived: (customMessage) => { + console.log("Custom message received successfully", customMessage); + }, + onMessagesDelivered: (messageReceipt) => { + console.log("Message Delivered", messageReceipt); + }, + onMessagesRead: (messageReceipt) => { + console.log("Message Read", messageReceipt); + }, + onTypingStarted: (typingIndicator) => { + console.log("Typing Started", typingIndicator); + }, + onTypingEnded: (typingIndicator) => { + console.log("Typing Ended", typingIndicator); + }, + onMessagesDeleted: (message) => { + console.log("Message Deleted", message); + }, + onMessageEdited: (message) => { + console.log("Message Edited", message); + }, + onInteractiveMessageReceived: (message) => { + console.log("interactive Message received", message); + }, + onInteractionGoalCompleted: (message) => { + console.log("Message interaction goal completed", message); + }, + onTransientMessageReceived: (message) => { + console.log("Transient Message received", message); + }, + onMessageReactionAdded: (reaction) => { + console.log("Message Reaction added", reaction); + }, + onMessageReactionRemoved: (reaction) => { + console.log("Message Reaction removed", reaction); + }, + onMessageModerated: (message) => { + console.log("Message Moderated", message); + }, }) ); ``` @@ -430,13 +558,6 @@ where `UNIQUE_LISTENER_ID` is the unique identifier for the listener. Please mak Once the `MessageListener` is not in use, you need to remove the listener using the `removeMessageListener()` method which takes the id of the listener to be removed as the parameter. - -```js -CometChat.removeMessageListener(UNIQUE_LISTENER_ID); -``` - - - ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; @@ -445,6 +566,13 @@ CometChat.removeMessageListener(listenerID); + +```js +CometChat.removeMessageListener(UNIQUE_LISTENER_ID); +``` + + + ## Call Listener @@ -457,6 +585,7 @@ The `CallListener` class provides you with live events related to calls. Below a | **onOutgoingCallAccepted(call: CometChat.Call)** | This event is triggered when the call initiated by the logged-in user is accepted by the recipient. The details of the call can be obtained from the Call object received as the method parameter. | | **onOutgoingCallRejected(call: CometChat.Call)** | This event is triggered when the call initiated by the logged-in user is rejected by the recipient. The details of the call can be obtained from the Call object received as the method parameter | | **onIncomingCallCancelled(call: CometChat.Call)** | This event is triggered when an incoming call is canceled by the initiator of the call. The details of the call can be obtained from the Call object received as the method parameter | +| **onCallEndedMessageReceived(call: CometChat.Call)** | This event is triggered when a call ends. The call object contains the final status and duration. | To add the `CallListener`, you need to use the `addCallListener()` method provided by the `CometChat` class. @@ -478,6 +607,9 @@ CometChat.addCallListener( onIncomingCallCancelled(call) { console.log("Incoming call canceled:", call); }, + onCallEndedMessageReceived(call) { + console.log("Call ended message:", call); + }, }) ); ``` @@ -501,6 +633,32 @@ CometChat.addCallListener( onIncomingCallCancelled: (call: CometChat.Call) => { console.log("Incoming call canceled:", call); }, + onCallEndedMessageReceived: (call: CometChat.Call) => { + console.log("Call ended message:", call); + }, + }) +); +``` + + + + +```js +CometChat.addCallListener( + "UNIQUE_LISTENER_ID", + new CometChat.CallListener({ + onIncomingCallReceived(call) { + console.log("Incoming call:", call); + }, + onOutgoingCallAccepted(call) { + console.log("Outgoing call accepted:", call); + }, + onOutgoingCallRejected(call) { + console.log("Outgoing call rejected:", call); + }, + onIncomingCallCancelled(call) { + console.log("Incoming call canceled:", call); + }, }) ); ``` @@ -514,6 +672,14 @@ where `UNIQUE_LISTENER_ID` is the unique identifier for the listener. Please mak Once the `CallListener` is not in use, you need to remove the listener using the `removeCallListener()` method which takes the id of the listener to be removed as the parameter. + +```typescript +let listenerID: string = "UNIQUE_LISTENER_ID"; +CometChat.removeCallListener(listenerID); +``` + + + ```js CometChat.removeCallListener(UNIQUE_LISTENER_ID); @@ -521,12 +687,208 @@ CometChat.removeCallListener(UNIQUE_LISTENER_ID); + + + +--- + +## AI Assistant Listener + +The `AIAssistantListener` provides real-time streaming events from AI Agent runs. These events are received as the agent processes a user's message, before the final persisted messages arrive via the `MessageListener`. + +| Method | Information | +| ------ | ----------- | +| **onAIAssistantEventReceived(event: CometChat.AIAssistantBaseEvent)** | This event is triggered for each streaming event during an AI Agent run (run start, tool calls, text message streaming, run finished). See [`AIAssistantBaseEvent`](/sdk/reference/messages#aiassistantbaseevent) for the event structure. | + + + +```js +const listenerID = "UNIQUE_LISTENER_ID"; +CometChat.addAIAssistantListener( + listenerID, + { + onAIAssistantEventReceived: (event) => { + console.log("AI Assistant event:", event.getType(), event); + }, + } +); +``` + ```typescript -let listenerID: string = "UNIQUE_LISTENER_ID"; -CometChat.removeCallListener(listenerID); +const listenerID: string = "UNIQUE_LISTENER_ID"; +CometChat.addAIAssistantListener( + listenerID, + { + onAIAssistantEventReceived: (event: CometChat.AIAssistantBaseEvent) => { + console.log("AI Assistant event:", event.getType(), event); + }, + } +); ``` + + + +To remove the listener: + + +```js +CometChat.removeAIAssistantListener("UNIQUE_LISTENER_ID"); +``` + +```typescript +CometChat.removeAIAssistantListener("UNIQUE_LISTENER_ID"); +``` + + + +## Ongoing Call Listener (Calls SDK) + +The `OngoingCallListener` provides real-time callbacks for active call session events. It is part of the CometChat Calls SDK (not the Chat SDK) and is used with `CallSettingsBuilder.setCallListener()` or `CometChatCalls.addCallEventListener()`. + +All three calling flows — [Call Session](/sdk/javascript/direct-call), [Standalone Calling](/sdk/javascript/standalone-calling), and [Presenter Mode](/sdk/javascript/presenter-mode) — use the same `OngoingCallListener`. + +### Callbacks + +| Callback | Parameter | Description | +|----------|-----------|-------------| +| `onUserJoined(user)` | `user` object | A remote participant joined the call | +| `onUserLeft(user)` | `user` object | A remote participant left the call | +| `onUserListUpdated(userList)` | Array of `user` objects | The participant list changed (join or leave) | +| `onCallEnded()` | — | The call session terminated (1:1 calls only, fires for both participants) | +| `onCallEndButtonPressed()` | — | The local user clicked the end call button | +| `onSessionTimeout()` | — | The call was auto-terminated due to inactivity. *v4.1.0+* | +| `onScreenShareStarted()` | — | The local user started sharing their screen | +| `onScreenShareStopped()` | — | The local user stopped sharing their screen | +| `onUserMuted(event)` | `event` object | A participant's mute state changed | +| `onCallSwitchedToVideo(event)` | `event` object | An audio call was upgraded to video | +| `onMediaDeviceListUpdated(deviceList)` | `deviceList` object | Available audio/video devices changed | +| `onRecordingStarted(event)` | `event` object | A user started recording the call | +| `onRecordingStopped()` | — | Recording was stopped | +| `onError(error)` | [`CometChatCallsException`](/sdk/reference/calls#cometchatcallsexception) | An error occurred during the call session | + +### Callback Parameter Shapes + +**`user` object** (received by `onUserJoined`, `onUserLeft`): + +| Property | Type | Description | +|----------|------|-------------| +| `name` | `string` | Display name of the user | +| `avatar` | `string` | URL of the user's avatar | +| `uid` | `string` | UID of the user | + +**`onUserListUpdated(userList)`** — receives an array of `user` objects with the same shape as above. + +**`onUserMuted(event)`**: +| Property | Type | Description | +|----------|------|-------------| +| `event.muted.name` | `string` | Name of the muted user | +| `event.muted.uid` | `string` | UID of the muted user | +| `event.muted.isAudioMuted` | `boolean` | Whether audio is muted | +| `event.muted.isVideoMuted` | `boolean` | Whether video is muted | +| `event.mutedBy.name` | `string` | Name of the user who muted | +| `event.mutedBy.uid` | `string` | UID of the user who muted | + +**`onCallSwitchedToVideo(event)`**: + +| Property | Type | Description | +|----------|------|-------------| +| `event.sessionId` | `string` | Session ID of the call | +| `event.initiator.name` | `string` | Name of the user who initiated the switch | +| `event.initiator.uid` | `string` | UID of the initiator | +| `event.responder.name` | `string` | Name of the responder | +| `event.responder.uid` | `string` | UID of the responder | + +**`onMediaDeviceListUpdated(deviceList)`**: + +| Property | Type | Description | +|----------|------|-------------| +| `deviceList.videoInputDevices` | [`MediaDeviceInfo[]`](/sdk/reference/calls#mediadeviceinfo) | Available cameras | +| `deviceList.audioInputDevices` | [`MediaDeviceInfo[]`](/sdk/reference/calls#mediadeviceinfo) | Available microphones | +| `deviceList.audioOutputDevices` | [`MediaDeviceInfo[]`](/sdk/reference/calls#mediadeviceinfo) | Available speakers/headphones | + +**`onRecordingStarted(event)`**: + +| Property | Type | Description | +|----------|------|-------------| +| `event.user.name` | `string` | Name of the user who started recording | +| `event.user.uid` | `string` | UID of the user who started recording | + +**`onRecordingStopped()`**, **`onCallEnded()`**, **`onSessionTimeout()`**, **`onCallEndButtonPressed()`**, **`onScreenShareStarted()`**, **`onScreenShareStopped()`** — receive no arguments. + + + +```js +const listenerId = "UNIQUE_LISTENER_ID"; + +CometChatCalls.addCallEventListener(listenerId, { + onUserJoined: (user) => { + console.log("User joined:", user); + }, + onUserLeft: (user) => { + console.log("User left:", user); + }, + onCallEnded: () => { + console.log("Call ended"); + }, + onCallEndButtonPressed: () => { + console.log("End call button pressed"); + }, + onError: (error) => { + console.log("Call error:", error); + }, +}); + +// Remove listener when done +CometChatCalls.removeCallEventListener(listenerId); +``` + + +```typescript +const listenerId: string = "UNIQUE_LISTENER_ID"; + +CometChatCalls.addCallEventListener(listenerId, { + onUserJoined: (user: any) => { + console.log("User joined:", user); + }, + onUserLeft: (user: any) => { + console.log("User left:", user); + }, + onCallEnded: () => { + console.log("Call ended"); + }, + onCallEndButtonPressed: () => { + console.log("End call button pressed"); + }, + onError: (error: any) => { + console.log("Call error:", error); + }, +}); + +// Remove listener when done +CometChatCalls.removeCallEventListener(listenerId); +``` + + +--- + +## Next Steps + + + + Handle incoming messages in real-time + + + Show when users are typing + + + Track online/offline status of users + + + Monitor SDK connection state changes + + diff --git a/sdk/javascript/authentication-overview.mdx b/sdk/javascript/authentication-overview.mdx index 1df057175..c300206e9 100644 --- a/sdk/javascript/authentication-overview.mdx +++ b/sdk/javascript/authentication-overview.mdx @@ -1,171 +1,256 @@ --- title: "Authentication" -sidebarTitle: "Overview" +sidebarTitle: "Authentication" +description: "Create users, log in with Auth Key or Auth Token, check login status, and log out using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Check existing session +const user = await CometChat.getLoggedinUser(); -## Create User +// Login with Auth Key (development only) +CometChat.login("cometchat-uid-1", "AUTH_KEY").then(user => console.log("Logged in:", user)); -Before you log in a user, you must add the user to CometChat. +// Login with Auth Token (production) +CometChat.login("AUTH_TOKEN").then(user => console.log("Logged in:", user)); -1. **For proof of concept/MVPs**: Create the user using the [CometChat Dashboard](https://app.cometchat.com). -2. **For production apps**: Use the CometChat [Create User API](https://api-explorer.cometchat.com/reference/creates-user) to create the user when your user signs up in your app. +// Logout +CometChat.logout().then(() => console.log("Logged out")); +``` - +**Create users via:** [Dashboard](https://app.cometchat.com) (testing) | [REST API](https://api-explorer.cometchat.com/reference/creates-user) (production) +**Test UIDs:** `cometchat-uid-1` through `cometchat-uid-5` + + +After [initializing](/sdk/javascript/initialization) the SDK, the next step is to authenticate your user. CometChat provides two login methods — Auth Key for quick development, and Auth Token for production — both accessed through the `login()` method. + +### How It Works + +```mermaid +sequenceDiagram + participant User + participant YourApp as Your App + participant YourServer as Your Server + participant CometChat as CometChat + + User->>YourApp: Signs up / Logs in + YourApp->>YourServer: Authenticate user + YourServer->>CometChat: Create user (REST API, first time only) + CometChat-->>YourServer: User created + YourServer->>CometChat: Create Auth Token (REST API) + CometChat-->>YourServer: Auth Token + YourServer-->>YourApp: Return Auth Token + YourApp->>CometChat: CometChat.login(authToken) + CometChat-->>YourApp: User object (logged in) +``` -We have setup 5 users for testing having UIDs: `cometchat-uid-1`, `cometchat-uid-2`, `cometchat-uid-3`, `cometchat-uid-4` and `cometchat-uid-5`. +## Before You Log In - +### Create a User -Once initialization is successful, you will need to log the user into CometChat using the `login()` method. +A user must exist in CometChat before they can log in. -We recommend you call the CometChat login method once your user logs into your app. The `login()` method needs to be called only once. +- **During development:** Create users from the [CometChat Dashboard](https://app.cometchat.com). Five test users are already available with UIDs `cometchat-uid-1` through `cometchat-uid-5`. +- **In production:** Call the [Create User REST API](https://api-explorer.cometchat.com/reference/creates-user) when a user signs up in your app. - +### Check for an Existing Session -The CometChat SDK maintains the session of the logged-in user within the SDK. Thus you do not need to call the login method for every session. You can use the CometChat.getLoggedinUser() method to check if there is any existing session in the SDK. This method should return the details of the logged-in user. If this method returns null, it implies there is no session present within the SDK and you need to log the user into CometChat. +The SDK persists the logged-in user's session locally. Before calling `login()`, always check whether a session already exists — this avoids unnecessary login calls and keeps your app responsive. - +```javascript +const user = await CometChat.getLoggedinUser(); +if (user) { + // User is already logged in — proceed to your app +} +``` + +If `getLoggedinUser()` returns `null`, no active session exists and you need to call `login()`. -## Login using Auth Key +## Login with Auth Key -This straightforward authentication method is ideal for proof-of-concept (POC) development or during the early stages of application development. For production environments, however, we strongly recommend using an [AuthToken](#login-using-auth-token) instead of an Auth Key to ensure enhanced security. +Auth Key login is the simplest way to get started. Pass a UID and your Auth Key directly from the client. + + +Auth Keys are meant for development and testing only. For production, use [Auth Token login](#login-with-auth-token) instead. Never ship Auth Keys in client-side code. + - -```js -var UID = "UID"; -var authKey = "AUTH_KEY"; + +```typescript +const UID: string = "cometchat-uid-1"; +const authKey: string = "AUTH_KEY"; CometChat.getLoggedinUser().then( - (user) => { + (user: CometChat.User) => { if (!user) { CometChat.login(UID, authKey).then( - (user) => { + (user: CometChat.User) => { console.log("Login Successful:", { user }); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Login failed with exception:", { error }); } ); } }, - (error) => { - console.log("Something went wrong", error); + (error: CometChat.CometChatException) => { + console.log("Some Error Occurred", { error }); } ); ``` - - -```typescript -var UID: string = "cometchat-uid-1", - authKey: string = "AUTH_KEY"; + +```js +const UID = "cometchat-uid-1"; +const authKey = "AUTH_KEY"; CometChat.getLoggedinUser().then( - (user: CometChat.User) => { + (user) => { if (!user) { CometChat.login(UID, authKey).then( - (user: CometChat.User) => { + (user) => { console.log("Login Successful:", { user }); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Login failed with exception:", { error }); } ); } }, - (error: CometChat.CometChatException) => { - console.log("Some Error Occured", { error }); + (error) => { + console.log("Some Error Occurred", { error }); } ); ``` - + +```javascript +const UID = "cometchat-uid-1"; +const authKey = "AUTH_KEY"; + +try { + const loggedInUser = await CometChat.getLoggedinUser(); + if (!loggedInUser) { + const user = await CometChat.login(UID, authKey); + console.log("Login Successful:", { user }); + } +} catch (error) { + console.log("Login failed with exception:", { error }); +} +``` + -| Parameters | Description | -| ---------- | ------------------------------------------------ | -| UID | The UID of the user that you would like to login | -| authKey | CometChat Auth Key | +| Parameter | Description | +| --------- | ----------- | +| UID | The UID of the user to log in | +| authKey | Your CometChat Auth Key | -After the user logs in, their information is returned in the `User` object on `Promise` resolved. +On success, the `Promise` resolves with a [`User`](/sdk/reference/entities#user) object containing the logged-in user's details. -## Login using Auth Token +## Login with Auth Token -This advanced authentication procedure does not use the Auth Key directly in your client code thus ensuring safety. +Auth Token login keeps your Auth Key off the client entirely. Your server generates a token via the REST API and passes it to the client. -1. [Create a User](https://api-explorer.cometchat.com/reference/creates-user) via the CometChat API when the user signs up in your app. -2. [Create an Auth Token](https://api-explorer.cometchat.com/reference/create-authtoken) via the CometChat API for the new user and save the token in your database. -3. Load the Auth Token in your client and pass it to the `login()` method. +1. [Create the user](https://api-explorer.cometchat.com/reference/creates-user) via the REST API when they sign up (first time only). +2. [Generate an Auth Token](https://api-explorer.cometchat.com/reference/create-authtoken) on your server and return it to the client. +3. Pass the token to `login()`. - -```js -var authToken = "AUTH_TOKEN"; + +```typescript +const authToken: string = "AUTH_TOKEN"; CometChat.getLoggedinUser().then( - (user) => { + (user: CometChat.User) => { if (!user) { CometChat.login(authToken).then( - (user) => { + (user: CometChat.User) => { console.log("Login Successful:", { user }); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Login failed with exception:", { error }); } ); } }, - (error) => { - console.log("Something went wrong", error); + (error: CometChat.CometChatException) => { + console.log("Some Error Occurred", { error }); } ); ``` - - -```typescript -var authToken: string = "AUTH_TOKEN"; + +```js +const authToken = "AUTH_TOKEN"; CometChat.getLoggedinUser().then( - (user: CometChat.User) => { + (user) => { if (!user) { CometChat.login(authToken).then( - (user: CometChat.User) => { + (user) => { console.log("Login Successful:", { user }); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Login failed with exception:", { error }); } ); } }, - (error: CometChat.CometChatException) => { - console.log("Some Error Occured", { error }); + (error) => { + console.log("Some Error Occurred", { error }); } ); ``` - + +```javascript +const authToken = "AUTH_TOKEN"; + +try { + const loggedInUser = await CometChat.getLoggedinUser(); + if (!loggedInUser) { + const user = await CometChat.login(authToken); + console.log("Login Successful:", { user }); + } +} catch (error) { + console.log("Login failed with exception:", { error }); +} +``` + -| Parameter | Description | -| --------- | ---------------------------------------------- | -| authToken | Auth Token of the user you would like to login | +| Parameter | Description | +| --------- | ----------- | +| authToken | Auth Token generated on your server for the user | -After the user logs in, their information is returned in the `User` object on the `Promise` resolved. +On success, the `Promise` resolves with a [`User`](/sdk/reference/entities#user) object containing the logged-in user's details. ## Logout -You can use the `logout()` method to log out the user from CometChat. We suggest you call this method once your user has been successfully logged out from your app. +Call `logout()` when your user logs out of your app. This clears the local session. + +```typescript +CometChat.logout().then( + (loggedOut: Object) => { + console.log("Logout completed successfully"); + }, + (error: CometChat.CometChatException) => { + console.log("Logout failed with exception:", { error }); + } +); +``` + + ```js CometChat.logout().then( @@ -177,21 +262,108 @@ CometChat.logout().then( } ); ``` + + +```javascript +try { + await CometChat.logout(); + console.log("Logout completed successfully"); +} catch (error) { + console.log("Logout failed with exception:", { error }); +} +``` + +--- + +## Login Listener + +You can listen for login and logout events in real time using `LoginListener`. This is useful for updating UI state or triggering side effects when the auth state changes. + +| Callback | Description | +| --- | --- | +| `loginSuccess(event)` | User logged in successfully. Provides the `User` object. | +| `loginFailure(event)` | Login failed. Provides a `CometChatException`. | +| `logoutSuccess()` | User logged out successfully. | +| `logoutFailure(event)` | Logout failed. Provides a `CometChatException`. | + +### Add a Listener + + ```typescript -CometChat.logout().then( - (loggedOut: Object) => { - console.log("Logout completed successfully"); - }, - (error: CometChat.CometChatException) => { - console.log("Logout failed with exception:", { error }); - } +const listenerID: string = "UNIQUE_LISTENER_ID"; +CometChat.addLoginListener( + listenerID, + new CometChat.LoginListener({ + loginSuccess: (user: CometChat.User) => { + console.log("LoginListener :: loginSuccess", user); + }, + loginFailure: (error: CometChat.CometChatException) => { + console.log("LoginListener :: loginFailure", error); + }, + logoutSuccess: () => { + console.log("LoginListener :: logoutSuccess"); + }, + logoutFailure: (error: CometChat.CometChatException) => { + console.log("LoginListener :: logoutFailure", error); + } + }) ); ``` - + +```js +let listenerID = "UNIQUE_LISTENER_ID"; +CometChat.addLoginListener( + listenerID, + new CometChat.LoginListener({ + loginSuccess: (e) => { + console.log("LoginListener :: loginSuccess", e); + }, + loginFailure: (e) => { + console.log("LoginListener :: loginFailure", e); + }, + logoutSuccess: () => { + console.log("LoginListener :: logoutSuccess"); + }, + logoutFailure: (e) => { + console.log("LoginListener :: logoutFailure", e); + } + }) +); +``` + + +### Remove a Listener + +```javascript +CometChat.removeLoginListener("UNIQUE_LISTENER_ID"); +``` + + +Always remove login listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + +--- + +## Next Steps + + + + Send your first text, media, or custom message + + + Create, update, and delete users programmatically + + + Monitor the SDK connection state in real time + + + Complete reference for all SDK event listeners + + diff --git a/sdk/javascript/best-practices.mdx b/sdk/javascript/best-practices.mdx new file mode 100644 index 000000000..fbaebfcea --- /dev/null +++ b/sdk/javascript/best-practices.mdx @@ -0,0 +1,175 @@ +--- +title: "Best Practices" +sidebarTitle: "Best Practices" +description: "Recommended patterns and practices for building with the CometChat JavaScript SDK." +--- + +Follow these best practices to build reliable, performant, and secure applications with the CometChat JavaScript SDK. + +## Initialization & Authentication + +| Practice | Description | +|----------|-------------| +| Initialize once at startup | Call `CometChat.init()` in your entry file (`index.js`, `main.js`, or `App.js`). It only needs to be called once per session. | +| Use environment variables | Store App ID, Region, and Auth Key in environment variables rather than hardcoding them. | +| Check for existing sessions | Before calling `login()`, use `CometChat.getLoggedinUser()` to check if a session already exists. | +| Use Auth Tokens in production | Auth Keys are for development only. Generate Auth Tokens server-side using the [REST API](https://api-explorer.cometchat.com/reference/create-authtoken). | +| Handle token expiry | Implement a mechanism to detect login failures due to expired tokens. Use the [Login Listener](/sdk/javascript/authentication-overview#login-listener) to detect session changes. | +| Logout on sign-out | Always call `CometChat.logout()` when your user signs out to clear the SDK session and stop real-time events. | + +## Listeners + +| Practice | Description | +|----------|-------------| +| Use unique listener IDs | Use descriptive IDs like `"MESSAGE_LISTENER_CHAT_SCREEN"` to avoid accidental overwrites. | +| Register early, remove on cleanup | Register listeners after `login()`. Remove them when the component is destroyed to prevent memory leaks. | +| Keep callbacks lightweight | Avoid heavy processing inside listener callbacks. Dispatch events to your state management layer. | +| Use specific listeners | Only register the listener types you need. Don't register a `GroupListener` if your page only handles messages. | + +## Pagination & Caching + +| Practice | Description | +|----------|-------------| +| Use reasonable limits | Set `setLimit()` to 30-50 for users, messages, and group members. | +| Reuse request objects | Call `fetchNext()`/`fetchPrevious()` on the same request instance. Creating a new object resets the cursor. | +| Cache frequently accessed data | Store user and group objects locally to reduce API calls. | + +## Rate Limits + +| Practice | Description | +|----------|-------------| +| Batch operations | Space out bulk operations using a queue or throttle mechanism. | +| Monitor rate limit headers | Check `X-Rate-Limit-Remaining` in REST API responses to slow down before hitting limits. | +| Distinguish operation types | Core operations (login, create/delete user) share a 10,000/min limit. Standard operations have 20,000/min. Avoid frequent login/logout cycles. | + +## SSR Frameworks + +| Practice | Description | +|----------|-------------| +| Initialize client-side only | CometChat requires browser APIs. Use dynamic imports or `useEffect` for Next.js, Nuxt, etc. | +| Use loading states | Show a loading indicator while the SDK initializes to prevent hydration mismatches. | + +## Messaging + +| Practice | Description | +|----------|-------------| +| Use appropriate message types | Choose text, media, or custom messages based on your content. | +| Add metadata for context | Use `setMetadata()` to attach location, device info, or other contextual data. | +| Handle errors gracefully | Always implement error callbacks to handle network issues or invalid parameters. | +| Validate file types | Before sending media messages, verify the file type matches the message type. | +| Hide deleted/blocked content | Use `hideDeletedMessages(true)` and `hideMessagesFromBlockedUsers(true)` for cleaner lists. | + +## Threaded Messages + +| Practice | Description | +|----------|-------------| +| Track active thread ID | Store the current thread's `parentMessageId` to filter incoming messages. | +| Use hideReplies(true) | Exclude thread replies from main conversation to avoid clutter. | +| Show reply count | Display the number of replies on parent messages to indicate thread activity. | + +## Reactions & Mentions + +| Practice | Description | +|----------|-------------| +| Update UI optimistically | Show reactions immediately, then sync with server response. | +| Use correct mention format | Always use `<@uid:UID>` format for mentions in message text. | +| Highlight mentions in UI | Parse message text and style mentions differently. | + +## Typing Indicators + +| Practice | Description | +|----------|-------------| +| Debounce typing events | Don't call `startTyping()` on every keystroke - debounce to ~300ms intervals. | +| Auto-stop typing | Call `endTyping()` after 3-5 seconds of inactivity or when the user sends a message. | + +## Delivery & Read Receipts + +| Practice | Description | +|----------|-------------| +| Mark as delivered on fetch | Call `markAsDelivered()` when messages are fetched and displayed. | +| Mark as read on view | Call `markAsRead()` when the user actually views/scrolls to a message. | +| Batch receipts | Mark the last message in a batch - all previous messages are automatically marked. | + +## Groups + +| Practice | Description | +|----------|-------------| +| Use meaningful GUIDs | Choose descriptive, unique GUIDs (e.g., `"project-alpha-team"`). | +| Set group type carefully | Group type cannot be changed after creation. Choose between PUBLIC, PASSWORD, and PRIVATE. | +| Add members at creation | Use `createGroupWithMembers()` to add initial members in a single API call. | +| Check hasJoined before joining | Avoid unnecessary API calls by checking the group's `hasJoined` property first. | +| Transfer ownership before leaving | Owners must transfer ownership to another member before they can leave. | +| Use joinedOnly(true) | Filter to joined groups when building sidebars or group lists. | + +## Group Members + +| Practice | Description | +|----------|-------------| +| Batch member additions | Add multiple members in a single `addMembersToGroup()` call. | +| Set appropriate scopes | Assign `PARTICIPANT` by default. Only use `ADMIN` or `MODERATOR` when needed. | +| Handle partial failures | Check each entry in the response array for `"success"` or an error message. | +| Use scope constants | Use `CometChat.GROUP_MEMBER_SCOPE.ADMIN` instead of raw strings. | +| Kick vs. Ban | Use kick when the user can rejoin. Use ban for permanent removal until unbanned. | + +## Calling + +| Practice | Description | +|----------|-------------| +| Initialize Calls SDK after Chat SDK | Always initialize Chat SDK (`CometChat.init()`) before Calls SDK (`CometChatCalls.init()`). | +| Store session ID immediately | Save the session ID from `initiateCall()` response - you'll need it for accept, reject, cancel. | +| Handle all call states | Implement handlers for all listener events (accepted, rejected, cancelled, busy, ended). | +| Generate tokens just-in-time | Generate call tokens immediately before starting a session rather than caching them. | +| Clean up on session end | Always call `CometChatCalls.endSession()` in both `onCallEnded` and `onCallEndButtonPressed` callbacks. | +| Inform users about recording | Always notify participants when recording starts - this is often a legal requirement. | +| Limit presenters to 5 | Additional users should join as viewers. | + +## Custom CSS (Calling) + +| Practice | Description | +|----------|-------------| +| Only use documented CSS classes | Undocumented internal classes may break with SDK updates. | +| Don't resize the grid container | Only customize colors, borders, and visibility. | +| Test across modes | CSS changes may look different in `DEFAULT`, `TILE`, and `SPOTLIGHT` modes. | +| Keep button sizes accessible | Minimum 44x44px for touch targets. | + +## Connection & WebSocket + +| Practice | Description | +|----------|-------------| +| Register connection listener early | Add the listener right after `CometChat.init()` succeeds. | +| Show connection status in UI | Display a banner when disconnected so users know messages may be delayed. | +| Queue actions during disconnection | Queue user actions and retry once `onConnected` fires. | +| Don't poll getConnectionStatus() | Use the listener-based approach instead. | +| Reconnect on app foreground | If you disconnect in background, call `CometChat.connect()` when returning to foreground. | + +## AI Features + +| Practice | Description | +|----------|-------------| +| Register both listeners for AI Agents | Use `AIAssistantListener` for streaming events and `MessageListener` for persisted messages. | +| Handle streaming progressively | Render the assistant's reply token-by-token using `Text Message Content` events. | +| Show pending state for moderation | Display a visual indicator when `getModerationStatus()` returns `PENDING`. | +| Handle disapproved messages gracefully | Show a placeholder or notification so the sender understands what happened. | +| Track pending messages | Maintain a local map of pending message IDs to update UI when moderation results arrive. | + +## Upgrading from V3 + +| Practice | Description | +|----------|-------------| +| Follow the setup guide first | Complete the v4 [setup instructions](/sdk/javascript/setup-sdk) before changing imports. | +| Update all imports at once | Use find-and-replace to change all `@cometchat-pro/chat` imports to `@cometchat/chat-sdk-javascript`. | +| Test incrementally | Test each feature area (messaging, calling, groups) individually after updating. | +| Remove old packages | Uninstall v3 packages (`npm uninstall @cometchat-pro/chat`) to avoid conflicts. | + +--- + +## Next Steps + + + + Common issues and solutions + + + Installation and initialization guide + + diff --git a/sdk/javascript/block-users.mdx b/sdk/javascript/block-users.mdx index 738e07ab1..7f214da6f 100644 --- a/sdk/javascript/block-users.mdx +++ b/sdk/javascript/block-users.mdx @@ -1,19 +1,50 @@ --- title: "Block Users" +sidebarTitle: "Block Users" +description: "Block and unblock users, and retrieve the list of blocked users using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Block users +await CometChat.blockUsers(["UID1", "UID2"]); -## Block Users +// Unblock users +await CometChat.unblockUsers(["UID1", "UID2"]); -*In other words, as a logged-in user, how do I block a user from sending me messages?* +// Get blocked users list +let request = new CometChat.BlockedUsersRequestBuilder().setLimit(30).build(); +let blockedUsers = await request.fetchNext(); +``` -You can block users using the `blockUsers()` method. Once any user is blocked, all the communication to and from the respective user will be completely blocked. You can block multiple users in a single operation. The `blockUsers()` method takes a `Array` as a parameter which holds the list of `UID's` to be blocked. +**Directions:** `BLOCKED_BY_ME` | `HAS_BLOCKED_ME` | `BOTH` (default) + + +## Block Users + +Block users to prevent all communication with them. Use `blockUsers()` with an array of UIDs. - + +```typescript +const usersList: String[] = ["UID1", "UID2", "UID3"]; + +CometChat.blockUsers(usersList).then( + (list: Object) => { + console.log("users list blocked", { list }); + }, (error: CometChat.CometChatException) => { + console.log("Blocking user fails with error", error); + } +); +``` + + + + ```javascript -var usersList = ["UID1", "UID2", "UID3"]; +const usersList = ["UID1", "UID2", "UID3"]; CometChat.blockUsers(usersList).then( list => { @@ -26,35 +57,45 @@ list => { + +```javascript +const usersList = ["UID1", "UID2", "UID3"]; + +try { + const list = await CometChat.blockUsers(usersList); + console.log("users list blocked", { list }); +} catch (error) { + console.log("Blocking user fails with error", error); +} +``` + + + + + +Returns an object with UIDs as keys and `"success"` or `"fail"` as values. Each [`User`](/sdk/reference/entities#user) in the request is processed independently. + +Unblock previously blocked users using `unblockUsers()` with an array of UIDs. + + ```typescript -var usersList: String[] = ["UID1", "UID2", "UID3"]; +const usersList: String[] = ["UID1", "UID2", "UID3"]; -CometChat.blockUsers(usersList).then( +CometChat.unblockUsers(usersList).then( (list: Object) => { console.log("users list blocked", { list }); }, (error: CometChat.CometChatException) => { console.log("Blocking user fails with error", error); } -); +); ``` - - -It returns a Array which contains `UID's` as the keys and "success" or "fail" as the value based on if the block operation for the `UID` was successful or not. - -## Unblock Users - -*In other words, as a logged-in user, how do I unblock a user I previously blocked?* - -You can unblock the already blocked users using the `unblockUsers()` method. You can unblock multiple users in a single operation. The `unblockUsers()` method takes a `Array` as a parameter which holds the list of `UID's` to be unblocked. - - - + ```javascript -var usersList = ["UID1", "UID2", "UID3"]; +const usersList = ["UID1", "UID2", "UID3"]; CometChat.unblockUsers(usersList).then( list => { @@ -67,39 +108,44 @@ list => { - -```typescript -var usersList: String[] = ["UID1", "UID2", "UID3"]; + +```javascript +const usersList = ["UID1", "UID2", "UID3"]; -CometChat.unblockUsers(usersList).then( - (list: Object) => { - console.log("users list blocked", { list }); - }, (error: CometChat.CometChatException) => { - console.log("Blocking user fails with error", error); - } -); +try { + const list = await CometChat.unblockUsers(usersList); + console.log("users list unblocked", { list }); +} catch (error) { + console.log("unblocking user fails with error", error); +} ``` -It returns a Array which contains `UID's` as the keys and `success` or `fail` as the value based on if the unblock operation for the `UID` was successful or not. +Returns an object with UIDs as keys and `"success"` or `"fail"` as values. Each [`User`](/sdk/reference/entities#user) in the request is processed independently. ## Get List of Blocked Users -*In other words, as a logged-in user, how do I get a list of all users I've blocked?* - -In order to fetch the list of blocked users, you can use the `BlockedUsersRequest` class. To use this class i.e to create an object of the `BlockedUsersRequest class`, you need to use the `BlockedUsersRequestBuilder` class. The `BlockedUsersRequestBuilder` class allows you to set the parameters based on which the blocked users are to be fetched. - -The `BlockedUsersRequestBuilder` class allows you to set the below parameters: +Use `BlockedUsersRequestBuilder` to fetch blocked users with filtering and pagination. ### Set Limit -This method sets the limit i.e. the number of blocked users that should be fetched in a single iteration. +Sets the number of blocked users to fetch per request. - + +```typescript +let limit: number = 30; +let blockedUsersRequest: CometChat.BlockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() + .setLimit(limit) + .build(); +``` + + + + ```javascript let limit = 30; let blockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() @@ -109,24 +155,26 @@ let blockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() + + +### Set Search Keyword + +Filters blocked users by a search string. + + ```typescript let limit: number = 30; +let searchKeyword: string = "super"; let blockedUsersRequest: CometChat.BlockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() .setLimit(limit) + .setSearchKeyword(searchKeyword) .build(); ``` - - -### Set Search Keyword - -This method allows you to set the search string based on which the blocked users are to be fetched. - - - + ```javascript let limit = 30; let searchKeyword = "super"; @@ -138,13 +186,23 @@ let blockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() + + +### Set Direction + +Filters by block direction: + +- `BLOCKED_BY_ME` — Users blocked by the logged-in user +- `HAS_BLOCKED_ME` — Users who have blocked the logged-in user +- `BOTH` — Both directions (default) + + ```typescript let limit: number = 30; -let searchKeyword: string = "super"; let blockedUsersRequest: CometChat.BlockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() .setLimit(limit) - .setSearchKeyword(searchKeyword) + .setDirection(CometChat.BlockedUsersRequest.directions.BLOCKED_BY_ME) .build(); ``` @@ -152,14 +210,12 @@ let blockedUsersRequest: CometChat.BlockedUsersRequest = new CometChat.BlockedUs -### Set Direction +Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the `BlockedUsersRequest` class. -* CometChat.BlockedUsersRequest.directions.BLOCKED\_BY\_ME - This will ensure that the list of blocked users only contains the users blocked by the logged in user. -* CometChat.BlockedUsersRequest.directions.HAS\_BLOCKED\_ME - This will ensure that the list of blocked users only contains the users that have blocked the logged in user. -* CometChat.BlockedUsersRequest.directions.BOTH - This will make sure the list of users includes both the above cases. This is the default value for the direction variable if it is not set. +Once you have the object of the `BlockedUsersRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of [`User`](/sdk/reference/entities#user) objects containing n number of blocked users where N is the limit set in the builder class. - + ```javascript let limit = 30; let blockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() @@ -170,28 +226,33 @@ let blockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() + + +After configuring the builder, call `build()` to get the `BlockedUsersRequest` object, then call `fetchNext()` to retrieve blocked users. + + ```typescript let limit: number = 30; let blockedUsersRequest: CometChat.BlockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() .setLimit(limit) - .setDirection(CometChat.BlockedUsersRequest.directions.BLOCKED_BY_ME) .build(); + +blockedUsersRequest.fetchNext().then( + (userList: CometChat.User[]) => { + console.log("Blocked user list received:", userList); + }, (error: CometChat.CometChatException) => { + console.log("Blocked user list fetching failed with error:", error); + } +); ``` - - -Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the `BlockedUsersRequest` class. - -Once you have the object of the `BlockedUsersRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of `User` objects containing n number of blocked users where N is the limit set in the builder class. - - - + ```javascript -var limit = 30; -var blockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() +const limit = 30; +const blockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() .setLimit(limit) .build(); blockedUsersRequest.fetchNext().then( @@ -205,22 +266,32 @@ userList => { - -```typescript -let limit: number = 30; -let blockedUsersRequest: CometChat.BlockedUsersRequest = new CometChat.BlockedUsersRequestBuilder() - .setLimit(limit) - .build(); + -blockedUsersRequest.fetchNext().then( - (userList: CometChat.User[]) => { - console.log("Blocked user list received:", userList); - }, (error: CometChat.CometChatException) => { - console.log("Blocked user list fetching failed with error:", error); - } -); -``` +The `fetchNext()` method returns an array of [`User`](/sdk/reference/entities#user) objects representing blocked users. - +Relevant fields to access on returned users: - +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| blockedByMe | `getBlockedByMe()` | `boolean` | Whether the logged-in user has blocked this user | +| hasBlockedMe | `getHasBlockedMe()` | `boolean` | Whether this user has blocked the logged-in user | + +--- + +## Next Steps + + + + Fetch and filter user lists + + + Track online/offline status of users + + + Create, update, and delete users + + + Report inappropriate messages from users + + diff --git a/sdk/javascript/call-logs.mdx b/sdk/javascript/call-logs.mdx index 74f2b87af..cc0ad9c2c 100644 --- a/sdk/javascript/call-logs.mdx +++ b/sdk/javascript/call-logs.mdx @@ -1,20 +1,35 @@ --- title: "Call Logs" +sidebarTitle: "Call Logs" +description: "Fetch, filter, and retrieve call history including duration, participants, and recording status using the CometChat Calls SDK." --- + +```javascript +// Fetch call logs +let request = new CometChatCalls.CallLogRequestBuilder() + .setLimit(30) + .setAuthToken(loggedInUser.getAuthToken()) + .setCallCategory("call") + .build(); + +let logs = await request.fetchNext(); -## Overview +// Get details for a specific call session +let details = await CometChatCalls.getCallDetails("SESSION_ID", authToken); +``` -CometChat's Web Call SDK provides a comprehensive way to integrate call logs into your application, enhancing your user experience by allowing users to effortlessly keep track of their communication history. Call logs provide crucial information such as call duration, participants, and more. +**Filters:** `setCallType()`, `setCallStatus()`, `setCallCategory()`, `setCallDirection()`, `setHasRecording()`, `setUid()`, `setGuid()` + -This feature not only allows users to review their past interactions but it also serves as an effective tool to revisit important conversation details. With the flexibility of fetching call logs, filtering them according to specific parameters, and obtaining detailed information of individual calls, application developers can use this feature to build a more robust and interactive communication framework. +Call logs let you retrieve and display call history — who called whom, when, how long, and whether it was recorded. Use `CallLogRequestBuilder` to fetch and filter logs, and `getCallDetails()` to get details for a specific session. -In the following sections, we will guide you through the process of working with call logs, offering a deeper insight into how to optimally use this feature in your Web application. +Before you begin, make sure you've completed the [Calls SDK Setup](/sdk/javascript/calling-setup). -## Fetching Call Logs +## Fetch Call Logs -To fetch all call logs in your 23b application, you should use the `CallLogRequestBuilder`, This builder allows you to customize the call logs fetching process according to your needs. +Build a request with `CallLogRequestBuilder`, then call `fetchNext()` or `fetchPrevious()` to retrieve logs. Call either method repeatedly on the same builder instance to paginate through results. ```javascript let callLogRequestBuilder = new CometChatCalls.CallLogRequestBuilder() @@ -24,7 +39,7 @@ let callLogRequestBuilder = new CometChatCalls.CallLogRequestBuilder() .build() ``` -`CallLogRequestBuilder` has the following settings available. +### Builder Settings | Setting | Description | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | @@ -40,7 +55,7 @@ let callLogRequestBuilder = new CometChatCalls.CallLogRequestBuilder() ### Fetch Next -The**`fetchNext()`**method retrieves the next set of call logs. +Retrieves the next set of call logs: ```javascript let callLogRequestBuilder = new CometChatCalls.CallLogRequestBuilder() @@ -60,7 +75,7 @@ callLogRequestBuilder.fetchNext() ### Fetch Previous -The**`fetchPrevious()`**method retrieves the previous set of call logs. +Retrieves the previous set of call logs: ```javascript let callLogRequestBuilder = new CometChatCalls.CallLogRequestBuilder() @@ -78,19 +93,69 @@ callLogRequestBuilder.fetchPrevious() }); ``` -## Get Call Details +The `fetchNext()` and `fetchPrevious()` methods return an array of [`CallLog`](/sdk/reference/calls#calllog) objects. -To retrieve the specific details of a call, use the**`getCallDetails()`**method. This method requires the Auth token of the logged-in user and the session ID along with a callback listener. +## Get Call Details +Retrieve details for a specific call session using `getCallDetails()`: + + + +```typescript +const sessionID: string = "SESSION_ID"; +CometChatCalls.getCallDetails(sessionID, authToken).then( + (callLogs: Array) => { + console.log("Call details:", callLogs); + }, + (error: any) => { + console.log("Error fetching call details:", error); + } +); +``` + + ```javascript -var sessionID = "SESSION_ID"; -CometChatCalls.getCallDetails(sessionID, authToken) -.then((callLogs: Array) => { - console.log(callLogs); - }) - .catch(err => { - console.log(err); - }); +const sessionID = "SESSION_ID"; +CometChatCalls.getCallDetails(sessionID, authToken).then( + (callLogs) => { + console.log("Call details:", callLogs); + }, + (error) => { + console.log("Error fetching call details:", error); + } +); +``` + + +```javascript +const sessionID = "SESSION_ID"; +try { + const callLogs = await CometChatCalls.getCallDetails(sessionID, authToken); + console.log("Call details:", callLogs); +} catch (error) { + console.log("Error fetching call details:", error); +} ``` + + + +Note: Replace `"SESSION_ID"` with the ID of the session you are interested in. + +--- -Note: Replace**`"SESSION_ID"`**with the ID of the session you are interested in. +## Next Steps + + + + Implement the complete ringing call flow + + + Record audio and video calls + + + Start call sessions without the ringing flow + + + Install and initialize the Calls SDK + + diff --git a/sdk/javascript/calling-overview.mdx b/sdk/javascript/calling-overview.mdx index 18bc0ea62..2abcdd6ad 100644 --- a/sdk/javascript/calling-overview.mdx +++ b/sdk/javascript/calling-overview.mdx @@ -1,15 +1,29 @@ --- title: "Calling" sidebarTitle: "Overview" +description: "Overview of CometChat voice and video calling capabilities including ringing, direct call sessions, and standalone calling." --- -## Overview + -CometChat provides voice and video calling capabilities for your web application. This guide helps you choose the right implementation approach based on your use case. +Choose your calling approach: +- **Ringing** → [Default Call](/sdk/javascript/default-call) — Full call flow with notifications, accept/reject +- **Call Session** → [Direct Call](/sdk/javascript/direct-call) — Session-based calling with custom UI +- **Standalone** → [Standalone Calling](/sdk/javascript/standalone-calling) — Calls SDK only, no Chat SDK needed + +```bash +# Install Calls SDK +npm install @cometchat/calls-sdk-javascript +``` + +**Features:** Recording, Virtual Background, Screen Sharing, Custom CSS, Call Logs, Session Timeout + + +CometChat provides three ways to add voice and video calling to your web app. Which one you pick depends on how much of the call flow you want CometChat to handle vs. building yourself. ## Prerequisites -1. CometChat SDK installed and configured. See the [Setup](/sdk/javascript/setup) guide. +1. CometChat Chat SDK installed and configured. See the [Setup](/sdk/javascript/setup-sdk) guide. 2. CometChat Calls SDK added to your project: ```bash @@ -18,58 +32,53 @@ npm install @cometchat/calls-sdk-javascript For detailed setup instructions, see the [Calls SDK Setup](/sdk/javascript/calling-setup) guide. -## Choose Your Implementation +## Choose Your Approach -CometChat offers three approaches to implement calling: +### Ringing (Full Call Flow) - - - Complete calling flow with incoming/outgoing call UI, accept/reject functionality, and call notifications. - - - Direct call session management. Use with Ringing flow or for custom call initiation logic. - - - Calls SDK only implementation without the Chat SDK dependency. - - - -### Ringing - -Use this when you need a complete calling experience with: -- Incoming and outgoing call UI -- Call accept/reject/cancel functionality -- Call notifications via push notifications -- Integration with CometChat messaging +The complete calling experience — incoming/outgoing call UI, accept/reject/cancel, push notifications, and integration with CometChat messaging. Use this when you want CometChat to handle the entire call lifecycle. **Flow:** Initiate call → Receiver gets notified → Accept/Reject → Start session -[Get started with Ringing →](/sdk/javascript/default-call) + + Implement the complete ringing call flow + -### Call Session +### Call Session (Session Management) -Use this when you need to: -- Start a call session after the Ringing flow completes -- Implement custom call initiation logic with your own UI -- Join participants to a shared session using a session ID +Manages the actual call session — generating tokens, starting/ending sessions, configuring the call UI, and handling in-call events. The Ringing flow uses this under the hood after a call is accepted. You can also use it directly if you want to build your own call initiation logic. **Flow:** Generate token → Start session → Manage call → End session -[Get started with Call Session →](/sdk/javascript/direct-call) + + Start and manage call sessions + -### Standalone Calling +### Standalone Calling (No Chat SDK) -Use this when you want: -- Calling functionality without the Chat SDK -- Your own user authentication system -- Minimal SDK footprint +Calling without the Chat SDK. You handle user authentication via the REST API and use only the Calls SDK. Ideal when you need voice/video but not the full chat infrastructure. **Flow:** Get auth token via REST API → Generate call token → Start session -[Get started with Standalone Calling →](/sdk/javascript/standalone-calling) + + Implement calling without the Chat SDK + + +### How They Relate + +```mermaid +flowchart LR + A[Ringing Flow] -->|call accepted| B[Call Session] + C[Custom UI] -->|your logic| B + D[Standalone] -->|REST API auth| B +``` + +All three approaches converge on the Call Session layer to manage the actual media connection. The difference is how you get there — CometChat's ringing flow, your own UI, or standalone without the Chat SDK. ## Features +Once you have calling working, you can add these capabilities: + Record audio and video calls for playback, compliance, or archival purposes. diff --git a/sdk/javascript/calling-setup.mdx b/sdk/javascript/calling-setup.mdx index 7cd07247e..febf85a63 100644 --- a/sdk/javascript/calling-setup.mdx +++ b/sdk/javascript/calling-setup.mdx @@ -1,69 +1,86 @@ --- -title: "Setup" +title: "Calls SDK Setup" +sidebarTitle: "Setup" +description: "Install and initialize the CometChat Calls SDK for JavaScript to enable voice and video calling in your application." --- + +```bash +npm install @cometchat/calls-sdk-javascript +``` + +```javascript +import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; + +const callAppSetting = new CometChatCalls.CallAppSettingsBuilder() + .setAppId("APP_ID") + .setRegion("REGION") + .build(); -## Get your Application Keys +CometChatCalls.init(callAppSetting).then(() => console.log("Calls SDK ready")); +``` + +**Required:** App ID, Region from [CometChat Dashboard](https://app.cometchat.com) + -[Signup for CometChat](https://app.cometchat.com) and then: +The Calls SDK handles the media layer for voice and video calls — camera, microphone, screen sharing, and the call UI. It's a separate package from the Chat SDK and requires its own initialization. -1. Create a new app -2. Head over to the **Credentials** section and note the **App ID, Auth Key** & **Region** +## Prerequisites -## Add the CometChatCalls Dependency +You need your App ID and Region from the [CometChat Dashboard](https://app.cometchat.com). If you haven't created an app yet, [sign up](https://app.cometchat.com) and create one. -Install the package as NPM module: +If you're using the Chat SDK alongside (i.e., not [Standalone Calling](/sdk/javascript/standalone-calling)), make sure `CometChat.init()` completes before calling `CometChatCalls.init()`. + +## Installation ```bash npm install @cometchat/calls-sdk-javascript ``` - ```bash yarn add @cometchat/calls-sdk-javascript ``` - - -Then, import the `CometChatCalls` class wherever you want to use `CometChatCalls`. +Then import wherever needed: - - -```js +```javascript import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; ``` - +## Initialization +Call `CometChatCalls.init()` on app startup, after the Chat SDK has initialized (if you're using it). The method takes a `CallAppSettings` object built with `CallAppSettingsBuilder`. + + ```typescript -import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; -``` - - +let appID: string = "APP_ID"; +let region: string = "REGION"; - - -### Initialize CometChatCalls - -The `init()` method initialises the settings required for `CometChatCalls`. The `init()` method takes a single paramater, that is the instance of `CallAppSettings` class. - -The `CallAppSettingsBuilder` class allows you to configure three settings: +const callAppSetting: CometChatCalls.CallAppSettings = + new CometChatCalls.CallAppSettingsBuilder() + .setAppId(appID) + .setRegion(region) + .build(); -1. **appID:** You CometChat App ID -2. **region**: The region where your app was created -3. **host:** This method takes the client URL as input and uses this client URL instead of the default client URL. This can be used in case of dedicated deployment of CometChat. - -You need to call init() before calling any other method from `CometChatCalls`. We suggest you call the init() method on app startup, preferably in the index.js file. +CometChatCalls.init(callAppSetting).then( + () => { + console.log("CometChatCalls initialization completed successfully"); + }, + (error: unknown) => { + console.log("CometChatCalls initialization failed with error:", error); + } +); +``` + - ```js let appID = "APP_ID"; @@ -83,35 +100,59 @@ CometChatCalls.init(callAppSetting).then( } ); ``` - + - -```typescript -let appID = "APP_ID"; -let region = "REGION"; +Replace `APP_ID` and `REGION` with your credentials from the [Dashboard](https://app.cometchat.com). + + +`CometChatCalls.init()` must be called before any other Calls SDK method. Calling `generateToken()`, `startSession()`, or registering listeners before `init()` will fail. + + +### CallAppSettings Options + +| Method | Description | +| --- | --- | +| `setAppId(appID)` | Your CometChat App ID. Required. | +| `setRegion(region)` | The region where your app was created. Required. | +| `setHost(host)` | Custom client URL for dedicated deployments. Optional. | +### Initialization Order + +If you're using both the Chat SDK and Calls SDK, initialize them in sequence: + +```javascript +// 1. Chat SDK first +await CometChat.init(appID, appSettings); + +// 2. Then Calls SDK const callAppSetting = new CometChatCalls.CallAppSettingsBuilder() .setAppId(appID) .setRegion(region) .build(); -CometChatCalls.init(callAppSetting).then( - () => { - console.log("CometChatCalls initialization completed successfully"); - }, - (error) => { - console.log("CometChatCalls initialization failed with error:", error); - } -); -``` +await CometChatCalls.init(callAppSetting); - +// 3. Now both SDKs are ready +``` - +For [Standalone Calling](/sdk/javascript/standalone-calling), you only need `CometChatCalls.init()` — no Chat SDK required. -Make sure you replace the `APP_ID` with your CometChat **App ID** and `REGION` with your **App Region** in the above code. +--- -| Parameter | Description | -| ----------------- | ---------------------------------------- | -| `callAppSettings` | An object of the `CallAppSettings` class | +## Next Steps + + + + Implement the complete ringing call flow + + + Start and manage call sessions + + + Use Calls SDK without the Chat SDK + + + Compare calling approaches and features + + diff --git a/sdk/javascript/connection-status.mdx b/sdk/javascript/connection-status.mdx index 7c67128bb..8080128f4 100644 --- a/sdk/javascript/connection-status.mdx +++ b/sdk/javascript/connection-status.mdx @@ -1,8 +1,26 @@ --- title: "Connection Status" +description: "Monitor real-time WebSocket connection status and respond to connectivity changes using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Get current status: "connecting" | "connected" | "disconnected" +const status = CometChat.getConnectionStatus(); + +// Listen for connection changes +CometChat.addConnectionListener("LISTENER_ID", new CometChat.ConnectionListener({ + onConnected: () => console.log("Connected"), + inConnecting: () => console.log("Connecting..."), + onDisconnected: () => console.log("Disconnected") +})); + +// Cleanup +CometChat.removeConnectionListener("LISTENER_ID"); +``` + CometChat SDK provides you with a mechanism to get real-time status of the connection to CometChat web-socket servers. @@ -19,9 +37,9 @@ Once the connection is broken, the disconnected callback is triggered, the SDK a To receive real-time connection status, you need to register `ConnectionListener` wherever you wish to receive the real-time status. You can use the `addConnectionListener()` method to do so. - -```javascript -let listenerID = "UNIQUE_LISTENER_ID"; + +```typescript +let listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.addConnectionListener( listenerID, new CometChat.ConnectionListener({ @@ -40,9 +58,9 @@ CometChat.addConnectionListener( - -```typescript -let listenerID: string = "UNIQUE_LISTENER_ID"; + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; CometChat.addConnectionListener( listenerID, new CometChat.ConnectionListener({ @@ -72,16 +90,16 @@ We recommend you to add the Connection Listener in your method on app startup, p You can also get the current connection status by using `getConnectionStatus` property provided by CometChat SDK - -```javascript -var connectionStatus = CometChat.getConnectionStatus(); + +```typescript +const connectionStatus: string = CometChat.getConnectionStatus(); ``` - -```typescript -var connectionStatus: string = CometChat.getConnectionStatus(); + +```javascript +const connectionStatus = CometChat.getConnectionStatus(); ``` @@ -93,3 +111,36 @@ The `CometChat.getConnectionStatus` method will return either of the below 3 val 1. connecting 2. connected 3. disconnected + +The connection listener callbacks and `getConnectionStatus()` return string enum values representing the current WebSocket connection state: + +| Value | Callback | Description | +|-------|----------|-------------| +| `"connected"` | `onConnected()` | SDK has an active connection to CometChat servers | +| `"connecting"` | `inConnecting()` | SDK is attempting to establish or re-establish a connection | +| `"disconnected"` | `onDisconnected()` | SDK is disconnected due to network issues or other errors | +| `"featureThrottled"` | — | A feature has been throttled due to rate limiting | + + + +Always remove connection listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + +--- + +## Next Steps + + + + Manually manage WebSocket connections + + + Listen for login and logout events + + + Complete reference for all SDK listeners + + + Install and initialize the CometChat SDK + + diff --git a/sdk/javascript/create-group.mdx b/sdk/javascript/create-group.mdx index 29eed3de5..4d4ce92ad 100644 --- a/sdk/javascript/create-group.mdx +++ b/sdk/javascript/create-group.mdx @@ -1,37 +1,68 @@ --- title: "Create A Group" +sidebarTitle: "Create Group" +description: "Create public, private, or password-protected groups and optionally add members during creation using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Create a group +let group = new CometChat.Group("GUID", "Group Name", CometChat.GROUP_TYPE.PUBLIC, ""); +let createdGroup = await CometChat.createGroup(group); -## Create a Group +// Create group with members +let members = [new CometChat.GroupMember("UID", CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT)]; +let result = await CometChat.createGroupWithMembers(group, members, []); +``` -*In other words, as a logged-in user, how do I create a public, private or password-protected group?* +**Group types:** `PUBLIC` | `PASSWORD` | `PRIVATE` +**Member scopes:** `ADMIN` | `MODERATOR` | `PARTICIPANT` + -You can create a group using `createGroup()` method. This method takes a `Group` object as input. +## Create a Group -To create an object of `Group` class, you can use either of the below two constructors: +Use `createGroup()` to create a new group. Pass a `Group` object with the group details. -1. `new Group(String GUID, String name, String groupType, String password)` -2. `new Group(String GUID, String name, String groupType, String password, String icon, String description)` +Group constructors: +- `new Group(GUID, name, groupType, password)` +- `new Group(GUID, name, groupType, password, icon, description)` -The `groupType` needs to be either of the below 3 values: +Group types: +- `CometChat.GROUP_TYPE.PUBLIC` +- `CometChat.GROUP_TYPE.PASSWORD` +- `CometChat.GROUP_TYPE.PRIVATE` -1.`CometChat.GROUP_TYPE.PUBLIC` + + +```typescript +const GUID: string = "GUID"; +const groupName: string = "Hello Group!"; +const groupType: string = CometChat.GROUP_TYPE.PUBLIC; +const password: string = ""; -2.`CometChat.GROUP_TYPE.PASSWORD` +const group: CometChat.Group = new CometChat.Group(GUID, groupName, groupType, password); -3.`CometChat.GROUP_TYPE.PRIVATE` +CometChat.createGroup(group).then( + (group: CometChat.Group) => { + console.log("Group created successfully:", group); + }, (error: CometChat.CometChatException) => { + console.log("Group creation failed with exception:", error); + } +); +``` - - + + + ```javascript -var GUID = "GUID"; -var groupName = "Hello Group!"; -var groupType = CometChat.GROUP_TYPE.PUBLIC; -var password = ""; +const GUID = "GUID"; +const groupName = "Hello Group!"; +const groupType = CometChat.GROUP_TYPE.PUBLIC; +const password = ""; -var group = new CometChat.Group(GUID, groupName, groupType, password); +const group = new CometChat.Group(GUID, groupName, groupType, password); CometChat.createGroup(group).then( group => { @@ -44,35 +75,32 @@ CometChat.createGroup(group).then( - -```typescript -var GUID: string = "GUID"; -var groupName: string = "Hello Group!"; -var groupType: string = CometChat.GROUP_TYPE.PUBLIC; -var password: string = ""; - -var group: CometChat.Group = new CometChat.Group(GUID, groupName, groupType, password); - -CometChat.createGroup(group).then( - (group: CometChat.Group) => { - console.log("Group created successfully:", group); - }, (error: CometChat.CometChatException) => { - console.log("Group creation failed with exception:", error); - } -); + +```javascript +const GUID = "GUID"; +const groupName = "Hello Group!"; +const groupType = CometChat.GROUP_TYPE.PUBLIC; +const password = ""; + +const group = new CometChat.Group(GUID, groupName, groupType, password); + +try { + const createdGroup = await CometChat.createGroup(group); + console.log("Group created successfully:", createdGroup); +} catch (error) { + console.log("Group creation failed with exception:", error); +} ``` -The createGroup() method takes the following parameters: - -| Parameter | Description | -| --------- | ---------------------------- | -| `group` | An instance of `Group` class | +| Parameter | Description | +| --------- | ----------- | +| `group` | An instance of `Group` class | -After successful creation of the group, you will receive an instance of `Group` class which contains all the information about the particular group. +On success, returns a [`Group`](/sdk/reference/entities#group) object with the created group's details. @@ -80,26 +108,42 @@ GUID can be alphanumeric with underscore and hyphen. Spaces, punctuation and oth -## Add members while creating a group +## Add Members While Creating a Group -You can create a group and add members at the same time using the `createGroupWithMembers()` method. This method takes the `Group` Object, Array of `Group Member` Object to be added & Array of `UIDs` to be banned. +Use `createGroupWithMembers()` to create a group and add members in one operation. -To create an object of `Group` class, you can use either of the below two constructors: +Parameters: +- `group` — The `Group` object +- `members` — Array of `GroupMember` objects to add +- `bannedMembers` — Array of UIDs to ban (can be empty) -1. `new Group(String GUID, String name, String groupType, String password)` -2. `new Group(String GUID, String name, String groupType, String password, String icon, String description)` +Create a `GroupMember` with: `new CometChat.GroupMember(UID, scope)` -The `groupType` needs to be either of the below 3 values: + + +```typescript +let GUID: string = "cometchat-guid-11"; +let UID: string = "cometchat-uid-1"; +let groupName: string = "Hello Group!"; +let groupType: string = CometChat.GROUP_TYPE.PUBLIC; -1. `CometChat.GROUP_TYPE.PUBLIC` -2. `CometChat.GROUP_TYPE.PASSWORD` -3. `CometChat.GROUP_TYPE.PRIVATE` +let group: CometChat.Group = new CometChat.Group(GUID, groupName, groupType); +let members: Array = [ +new CometChat.GroupMember(UID, CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT) +]; +let banMembers: Array = ["cometchat-uid-2"]; -To create an object of `Group Member` class, you can use the below constructor: +CometChat.createGroupWithMembers(group, members, banMembers).then( + (response: Object) => { + console.log("Group created successfully", response); + }, (error: CometChat.CometChatException) => { + console.log("Some error occured while creating group", error) + } +); +``` -* new CometChat.GroupMember(String UID, String scope) + - ```js let GUID = "cometchat-guid-11"; @@ -124,33 +168,34 @@ CometChat.createGroupWithMembers(group, members, banMembers).then( - -```typescript -let GUID: string = "cometchat-guid-11"; -let UID: string = "cometchat-uid-1"; -let groupName: string = "Hello Group!"; -let groupType: string = CometChat.GROUP_TYPE.PUBLIC; + +```javascript +let GUID = "cometchat-guid-11"; +let UID = "cometchat-uid-1"; +let groupName = "Hello Group!"; +let groupType = CometChat.GROUP_TYPE.PUBLIC; -let group: CometChat.Group = new CometChat.Group(GUID, groupName, groupType); -let members: Array = [ -new CometChat.GroupMember(UID, CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT) +let group = new CometChat.Group(GUID, groupName, groupType); +let members = [ + new CometChat.GroupMember(UID, CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT) ]; -let banMembers: Array = ["cometchat-uid-2"]; +let banMembers = ["cometchat-uid-2"]; -CometChat.createGroupWithMembers(group, members, banMembers).then( - (response: Object) => { - console.log("Group created successfully", response); - }, (error: CometChat.CometChatException) => { - console.log("Some error occured while creating group", error) - } -); +try { + const response = await CometChat.createGroupWithMembers(group, members, banMembers); + console.log("Group created successfully", response); +} catch (error) { + console.log("Some error occured while creating group", error); +} ``` -This method returns an Object which has two keys: `group` & `members` . The group key has the Group Object which contains all the information of the group which is created. The members key has the `UID` of the users and the value will either be `success` or an `error` message describing why the operation to add/ban the user failed. +Returns an object with two keys: +- `group` — The created [`Group`](/sdk/reference/entities#group) object +- `members` — Object with UIDs as keys and `"success"` or error message as values ## Group Class @@ -171,3 +216,23 @@ This method returns an Object which has two keys: `group` & `members` . The grou | scope | Yes | Scope of the logged in user. Can be: 1. Admin 2. Moderator 3. Participant | | membersCount | No | The number of members in the groups | | tags | Yes | A list of tags to identify specific groups. | + + +--- + +## Next Steps + + + + Join public, private, or password-protected groups + + + Add users to an existing group + + + Fetch and filter group lists + + + Overview of all group management features + + diff --git a/sdk/javascript/custom-css.mdx b/sdk/javascript/custom-css.mdx index 56698ccf3..59d7637e0 100644 --- a/sdk/javascript/custom-css.mdx +++ b/sdk/javascript/custom-css.mdx @@ -1,39 +1,63 @@ --- title: "Custom CSS" +sidebarTitle: "Custom CSS" +description: "Customize the CometChat calling UI with custom CSS classes for buttons, video containers, name labels, and grid layouts." --- + +```css +/* Key CSS classes for call UI customization */ +.cc-main-container { } /* Outermost call container */ +.cc-bottom-buttons-container { } /* Bottom action buttons bar */ +.cc-name-label { } /* User name text */ +.cc-video-container { } /* Video feed container */ +.cc-end-call-icon-container { } /* End call button */ +.cc-audio-icon-container { } /* Audio toggle button */ +.cc-video-icon-container { } /* Video toggle button */ +.cc-screen-share-icon-container { } /* Screen share button */ +``` -Passing custom CSS allows you to personalize and enhance the user interface of the call screen. +**Modes:** `DEFAULT` | `TILE` | `SPOTLIGHT` + -## Common CSS Classes +The CometChat calling UI exposes CSS classes you can target to style buttons, video containers, labels, and layouts. Your CSS is applied globally — any styles you write for these classes will affect the call UI across all modes (DEFAULT, TILE, SPOTLIGHT). -There are a few common classes used for different modes in the call screen +Before you begin, make sure you've set up [Ringing](/sdk/javascript/default-call) or [Call Session](/sdk/javascript/direct-call). -1. **cc-main-container** - The outermost component of the calling component is represented by a white border in the screenshots above, indicating that it acts as a container for other components. + +Only use CSS classes documented here — targeting undocumented classes may cause UI issues. Avoid resizing the grid container to prevent layout distortions. + -2. **cc-bottom-buttons-container** - The container located at the very bottom of the interface houses various action buttons, such as the mute/unmute audio and video, end call, settings icon, and participants icon, among others. It is represented by the red border in above screenshot. +## CSS Class Reference -3. **cc-name-label** - This class is passed in user name text container in all modes. It is represented by green border in the above screenshots. +### Layout Containers -4. **cc-video-container** - This class is passed to the video container in all modes. It is represented by orange border in the above screenshots. +| Class | Description | +| ----- | ----------- | +| `cc-main-container` | Outermost container for the calling component | +| `cc-video-container` | Video feed container | +| `cc-name-label` | User name text container | -## Bottom Buttons +### Action Buttons -1. **cc-bottom-buttons-container** - This is the container of all the buttons in calling. -2. **cc-bottom-buttons-icon-container** - This is the div of every button in the button bar. +| Class | Description | +| ----- | ----------- | +| `cc-bottom-buttons-container` | Bottom bar containing action buttons (mute, end call, etc.) | +| `cc-bottom-buttons-icon-container` | Individual button wrapper | +| `cc-audio-icon-container` | Audio toggle button | +| `cc-audio-icon-container-muted` | Audio button (muted state) | +| `cc-video-icon-container` | Video toggle button | +| `cc-video-icon-container-muted` | Video button (muted state) | +| `cc-screen-share-icon-container` | Screen share button | +| `cc-switch-video-icon-container` | Switch camera button | +| `cc-end-call-icon-container` | End call button | -### Individual bottom buttons CSS classes +## Examples -* `cc-audio-icon-container` -* `cc-audio-icon-container-muted` -* `cc-video-icon-container` -* `cc-video-icon-container-muted` -* `cc-screen-share-icon-container` -* `cc-switch-video-icon-container` -* `cc-end-call-icon-container` +### Basic Styling -### **Example** +This example applies colored backgrounds to buttons and dotted borders to containers to visualize the layout structure: @@ -77,7 +101,7 @@ There are a few common classes used for different modes in the call screen -The above example results in the below output:- +Here's how it looks across the three call modes: **Mode: `DEFAULT`** @@ -153,20 +177,28 @@ The above example results in the below output:- -The above example results in the below output:- +### Polished UI + +This example shows a more refined customization with rounded buttons, custom spacing, and a patterned video background: +--- -### Guidelines for Customizing the Grid Layout - -* **CSS Classes:** - - * Please ensure that you only apply CSS classes specified in this documentation. Introducing CSS classes not covered here may cause unexpected UI issues. - -* **Grid Container Resizing:** - - * Avoid resizing the grid container. Altering the grid container’s dimensions can negatively impact the grid layout, leading to undesirable visual distortions. - -By following these recommendations, you can maintain a stable and visually consistent grid layout. +## Next Steps + + + + Customize video call layout and participant tiles + + + Apply blur or custom image backgrounds during calls + + + Enable screen sharing and presentation mode + + + Overview of all calling features and approaches + + diff --git a/sdk/javascript/default-call.mdx b/sdk/javascript/default-call.mdx index 180de4d73..5743c6231 100644 --- a/sdk/javascript/default-call.mdx +++ b/sdk/javascript/default-call.mdx @@ -1,7 +1,34 @@ --- title: "Ringing" +sidebarTitle: "Ringing" +description: "Implement a complete calling workflow with ringing, incoming/outgoing call UI, accept/reject/cancel functionality, and call session management." --- +{/* TL;DR for Agents and Quick Reference */} + + +```javascript +// Initiate a call +const call = new CometChat.Call("UID", CometChat.CALL_TYPE.VIDEO, CometChat.RECEIVER_TYPE.USER); +await CometChat.initiateCall(call); + +// Listen for call events +CometChat.addCallListener("ID", new CometChat.CallListener({ + onIncomingCallReceived: (call) => { /* show incoming UI */ }, + onOutgoingCallAccepted: (call) => { /* start session */ }, + onOutgoingCallRejected: (call) => { /* dismiss UI */ }, + onIncomingCallCancelled: (call) => { /* dismiss UI */ } +})); + +// Accept / Reject / Cancel +await CometChat.acceptCall(sessionId); +await CometChat.rejectCall(sessionId, CometChat.CALL_STATUS.REJECTED); +await CometChat.rejectCall(sessionId, CometChat.CALL_STATUS.CANCELLED); +``` + +**Flow:** Initiate → Receiver notified → Accept/Reject → Start session + + ## Overview This section explains how to implement a complete calling workflow with ringing functionality, including incoming/outgoing call UI, call acceptance, rejection, and cancellation. Previously known as **Default Calling**. @@ -108,40 +135,36 @@ CometChat.initiateCall(call).then( | `receiverType` | `CometChat.RECEIVER_TYPE.USER` or `CometChat.RECEIVER_TYPE.GROUP` | | `callType` | `CometChat.CALL_TYPE.AUDIO` or `CometChat.CALL_TYPE.VIDEO` | -On success, a `Call` object is returned containing the call details including a unique `sessionId` required for starting the call session. +On success, a [`Call`](/sdk/reference/messages#call) object is returned containing the call details including a unique `sessionId` required for starting the call session. + ## Call Listeners Register the `CallListener` to receive real-time call events. Each listener requires a unique `listenerId` string to prevent duplicate registrations and enable targeted removal. - -```javascript -const listenerId = "UNIQUE_LISTENER_ID"; + +```typescript +const listenerId: string = "UNIQUE_LISTENER_ID"; // Register listener CometChat.addCallListener( listenerId, new CometChat.CallListener({ - onIncomingCallReceived: (call) => { + onIncomingCallReceived: (call: CometChat.Call) => { console.log("Incoming call:", call); - // Show incoming call UI }, - onOutgoingCallAccepted: (call) => { + onOutgoingCallAccepted: (call: CometChat.Call) => { console.log("Outgoing call accepted:", call); - // Receiver accepted, start the call session }, - onOutgoingCallRejected: (call) => { + onOutgoingCallRejected: (call: CometChat.Call) => { console.log("Outgoing call rejected:", call); - // Receiver rejected, dismiss outgoing call UI }, - onIncomingCallCancelled: (call) => { + onIncomingCallCancelled: (call: CometChat.Call) => { console.log("Incoming call cancelled:", call); - // Caller cancelled, dismiss incoming call UI }, - onCallEndedMessageReceived: (call) => { + onCallEndedMessageReceived: (call: CometChat.Call) => { console.log("Call ended message:", call); - // Call ended by remote participant } }) ); @@ -150,28 +173,33 @@ CometChat.addCallListener( CometChat.removeCallListener(listenerId); ``` - -```typescript -const listenerId: string = "UNIQUE_LISTENER_ID"; + +```javascript +const listenerId = "UNIQUE_LISTENER_ID"; // Register listener CometChat.addCallListener( listenerId, new CometChat.CallListener({ - onIncomingCallReceived: (call: CometChat.Call) => { + onIncomingCallReceived: (call) => { console.log("Incoming call:", call); + // Show incoming call UI }, - onOutgoingCallAccepted: (call: CometChat.Call) => { + onOutgoingCallAccepted: (call) => { console.log("Outgoing call accepted:", call); + // Receiver accepted, start the call session }, - onOutgoingCallRejected: (call: CometChat.Call) => { + onOutgoingCallRejected: (call) => { console.log("Outgoing call rejected:", call); + // Receiver rejected, dismiss outgoing call UI }, - onIncomingCallCancelled: (call: CometChat.Call) => { + onIncomingCallCancelled: (call) => { console.log("Incoming call cancelled:", call); + // Caller cancelled, dismiss incoming call UI }, - onCallEndedMessageReceived: (call: CometChat.Call) => { + onCallEndedMessageReceived: (call) => { console.log("Call ended message:", call); + // Call ended by remote participant } }) ); @@ -192,11 +220,27 @@ CometChat.removeCallListener(listenerId); | `onIncomingCallCancelled(call)` | Invoked on the receiver's device when the caller cancels before answering. Dismiss incoming call UI here. | | `onCallEndedMessageReceived(call)` | Invoked when a call ends. The `call` contains final status and duration. Update call history here. | +All call listener callbacks receive a [`Call`](/sdk/reference/messages#call) object. + ## Accept Call When an incoming call is received via `onIncomingCallReceived()`, use `acceptCall()` to accept it. On success, start the call session. + +```typescript +const sessionId: string = call.getSessionId(); // From onIncomingCallReceived + +CometChat.acceptCall(sessionId).then( + (call: CometChat.Call) => { + console.log("Call accepted:", call); + }, + (error: CometChat.CometChatException) => { + console.log("Accept call failed:", error); + } +); +``` + ```javascript const sessionId = call.getSessionId(); // From onIncomingCallReceived @@ -213,27 +257,28 @@ CometChat.acceptCall(sessionId).then( ); ``` + + +## Reject Call + +Use `rejectCall()` to reject an incoming call. Set the status to `CALL_STATUS_REJECTED`. + + ```typescript -const sessionId: string = call.getSessionId(); // From onIncomingCallReceived +const sessionId: string = call.getSessionId(); +const status: string = CometChat.CALL_STATUS.REJECTED; -CometChat.acceptCall(sessionId).then( +CometChat.rejectCall(sessionId, status).then( (call: CometChat.Call) => { - console.log("Call accepted:", call); + console.log("Call rejected:", call); }, (error: CometChat.CometChatException) => { - console.log("Accept call failed:", error); + console.log("Reject call failed:", error); } ); ``` - - -## Reject Call - -Use `rejectCall()` to reject an incoming call. Set the status to `CALL_STATUS_REJECTED`. - - ```javascript const sessionId = call.getSessionId(); @@ -250,28 +295,28 @@ CometChat.rejectCall(sessionId, status).then( ); ``` + + +## Cancel Call + +The caller can cancel an outgoing call before it's answered using `rejectCall()` with status `CALL_STATUS_CANCELLED`. + + ```typescript const sessionId: string = call.getSessionId(); -const status: string = CometChat.CALL_STATUS.REJECTED; +const status: string = CometChat.CALL_STATUS.CANCELLED; CometChat.rejectCall(sessionId, status).then( (call: CometChat.Call) => { - console.log("Call rejected:", call); + console.log("Call cancelled:", call); }, (error: CometChat.CometChatException) => { - console.log("Reject call failed:", error); + console.log("Cancel call failed:", error); } ); ``` - - -## Cancel Call - -The caller can cancel an outgoing call before it's answered using `rejectCall()` with status `CALL_STATUS_CANCELLED`. - - ```javascript const sessionId = call.getSessionId(); @@ -288,21 +333,6 @@ CometChat.rejectCall(sessionId, status).then( ); ``` - -```typescript -const sessionId: string = call.getSessionId(); -const status: string = CometChat.CALL_STATUS.CANCELLED; - -CometChat.rejectCall(sessionId, status).then( - (call: CometChat.Call) => { - console.log("Call cancelled:", call); - }, - (error: CometChat.CometChatException) => { - console.log("Cancel call failed:", error); - } -); -``` - ## Start Call Session @@ -314,15 +344,15 @@ Once the call is accepted, both participants need to start the call session. **Receiver flow:** In the `acceptCall()` success callback, generate a token and start the session. - -```javascript -const sessionId = call.getSessionId(); + +```typescript +const sessionId: string = call.getSessionId(); const loggedInUser = await CometChat.getLoggedinUser(); -const authToken = loggedInUser.getAuthToken(); +const authToken: string = loggedInUser.getAuthToken(); // Step 1: Generate call token CometChatCalls.generateToken(sessionId, authToken).then( - (callToken) => { + (callToken: any) => { // Step 2: Configure call settings const callListener = new CometChatCalls.OngoingCallListener({ onCallEnded: () => { @@ -337,12 +367,12 @@ CometChatCalls.generateToken(sessionId, authToken).then( CometChatCalls.endSession(); // Close calling screen }, - (error) => console.log("End call failed:", error) + (error: CometChat.CometChatException) => console.log("End call failed:", error) ); }, - onUserJoined: (user) => console.log("User joined:", user), - onUserLeft: (user) => console.log("User left:", user), - onError: (error) => console.log("Call error:", error) + onUserJoined: (user: any) => console.log("User joined:", user), + onUserLeft: (user: any) => console.log("User left:", user), + onError: (error: any) => console.log("Call error:", error) }); const callSettings = new CometChatCalls.CallSettingsBuilder() @@ -352,24 +382,24 @@ CometChatCalls.generateToken(sessionId, authToken).then( .build(); // Step 3: Start the session - const htmlElement = document.getElementById("call-container"); + const htmlElement = document.getElementById("call-container") as HTMLElement; CometChatCalls.startSession(callToken, callSettings, htmlElement); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Token generation failed:", error); } ); ``` - -```typescript -const sessionId: string = call.getSessionId(); + +```javascript +const sessionId = call.getSessionId(); const loggedInUser = await CometChat.getLoggedinUser(); -const authToken: string = loggedInUser.getAuthToken(); +const authToken = loggedInUser.getAuthToken(); // Step 1: Generate call token CometChatCalls.generateToken(sessionId, authToken).then( - (callToken: any) => { + (callToken) => { // Step 2: Configure call settings const callListener = new CometChatCalls.OngoingCallListener({ onCallEnded: () => { @@ -384,12 +414,12 @@ CometChatCalls.generateToken(sessionId, authToken).then( CometChatCalls.endSession(); // Close calling screen }, - (error: CometChat.CometChatException) => console.log("End call failed:", error) + (error) => console.log("End call failed:", error) ); }, - onUserJoined: (user: any) => console.log("User joined:", user), - onUserLeft: (user: any) => console.log("User left:", user), - onError: (error: any) => console.log("Call error:", error) + onUserJoined: (user) => console.log("User joined:", user), + onUserLeft: (user) => console.log("User left:", user), + onError: (error) => console.log("Call error:", error) }); const callSettings = new CometChatCalls.CallSettingsBuilder() @@ -399,10 +429,10 @@ CometChatCalls.generateToken(sessionId, authToken).then( .build(); // Step 3: Start the session - const htmlElement = document.getElementById("call-container") as HTMLElement; + const htmlElement = document.getElementById("call-container"); CometChatCalls.startSession(callToken, callSettings, htmlElement); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Token generation failed:", error); } ); @@ -421,34 +451,34 @@ To end an active call in the ringing flow, the process differs based on who ends When the user clicks the end call button, the `onCallEndButtonPressed()` callback is triggered. Inside this callback, call `CometChat.endCall()` to notify other participants. On success, call `CometChat.clearActiveCall()` and `CometChatCalls.endSession()` to release resources. - -```javascript + +```typescript onCallEndButtonPressed: () => { CometChat.endCall(sessionId).then( - (call) => { + (call: CometChat.Call) => { console.log("Call ended successfully"); CometChat.clearActiveCall(); CometChatCalls.endSession(); // Close the calling screen }, - (error) => { + (error: CometChat.CometChatException) => { console.log("End call failed:", error); } ); } ``` - -```typescript + +```javascript onCallEndButtonPressed: () => { CometChat.endCall(sessionId).then( - (call: CometChat.Call) => { + (call) => { console.log("Call ended successfully"); CometChat.clearActiveCall(); CometChatCalls.endSession(); // Close the calling screen }, - (error: CometChat.CometChatException) => { + (error) => { console.log("End call failed:", error); } ); @@ -460,8 +490,8 @@ onCallEndButtonPressed: () => { **Remote participant** (receives `onCallEnded()` callback): - -```javascript + +```typescript onCallEnded: () => { CometChat.clearActiveCall(); CometChatCalls.endSession(); @@ -469,8 +499,8 @@ onCallEnded: () => { } ``` - -```typescript + +```javascript onCallEnded: () => { CometChat.clearActiveCall(); CometChatCalls.endSession(); @@ -487,34 +517,58 @@ For more details, see the [End Call Session](/sdk/javascript/direct-call#end-cal If the receiver is already on another call, you can reject the incoming call with `CALL_STATUS_BUSY` status. - -```javascript -const sessionId = call.getSessionId(); -const status = CometChat.CALL_STATUS.BUSY; + +```typescript +const sessionId: string = call.getSessionId(); +const status: string = CometChat.CALL_STATUS.BUSY; CometChat.rejectCall(sessionId, status).then( - (call) => { + (call: CometChat.Call) => { console.log("Busy status sent:", call); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Busy rejection failed:", error); } ); ``` - -```typescript -const sessionId: string = call.getSessionId(); -const status: string = CometChat.CALL_STATUS.BUSY; + +```javascript +const sessionId = call.getSessionId(); +const status = CometChat.CALL_STATUS.BUSY; CometChat.rejectCall(sessionId, status).then( - (call: CometChat.Call) => { + (call) => { console.log("Busy status sent:", call); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Busy rejection failed:", error); } ); ``` + + + +Always remove call listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + +--- + +## Next Steps + + + + Manage call sessions, tokens, and settings + + + Retrieve and display call history + + + Record audio and video calls + + + Install and initialize the Calls SDK + + diff --git a/sdk/javascript/delete-conversation.mdx b/sdk/javascript/delete-conversation.mdx index b91669f6a..3b99dce50 100644 --- a/sdk/javascript/delete-conversation.mdx +++ b/sdk/javascript/delete-conversation.mdx @@ -1,12 +1,28 @@ --- -title: "Delete A Conversation" +title: "Delete Conversation" +sidebarTitle: "Delete Conversation" +description: "Delete user or group conversations using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Delete user conversation +await CometChat.deleteConversation("UID", "user"); + +// Delete group conversation +await CometChat.deleteConversation("GUID", "group"); +``` + +**Note:** Deletes only for the logged-in user. Use [REST API](https://api-explorer.cometchat.com/reference/resets-user-conversation) to delete for all participants. + -In case you want to delete a conversation, you can use the `deleteConversation()` method. + +This operation is irreversible. Deleted conversations cannot be recovered for the logged-in user. + -This method takes two parameters. The unique id (UID/GUID) of the conversation to be deleted & the type (user/group) of conversation to be deleted. +Use `deleteConversation()` to delete a conversation for the logged-in user. @@ -39,7 +55,7 @@ CometChat.deleteConversation(GUID, type).then( - + ```typescript let UID: string = "UID"; let type: string = "user"; @@ -71,11 +87,30 @@ CometChat.deleteConversation(GUID, type).then( -This method deletes the conversation only for the logged-in user. To delete a conversation for all the users of the conversation, please refer to our REST API documentation [here](https://api-explorer.cometchat.com/reference/resets-user-conversation). +This deletes the conversation only for the logged-in user. To delete for all participants, use the [REST API](https://api-explorer.cometchat.com/reference/resets-user-conversation). -The `deleteConversation()` method takes the following parameters: +| Parameter | Description | Required | +| --- | --- | --- | +| conversationWith | UID or GUID of the conversation to delete | Yes | +| conversationType | `user` or `group` | Yes | + +On success, returns a confirmation message string. + +--- -| Parameter | Description | Required | -| ---------------- | --------------------------------------------------------------------------------- | -------- | -| conversationWith | `UID` of the user or `GUID` of the group whose conversation you want to delete. | YES | -| conversationType | The type of conversation you want to delete . It can be either `user` or `group`. | YES | +## Next Steps + + + + Fetch and filter conversation lists + + + Delete individual messages from conversations + + + Show when users are typing in conversations + + + Track message delivery and read status + + diff --git a/sdk/javascript/delete-group.mdx b/sdk/javascript/delete-group.mdx index 54bcf4137..b2b25382d 100644 --- a/sdk/javascript/delete-group.mdx +++ b/sdk/javascript/delete-group.mdx @@ -1,17 +1,47 @@ --- title: "Delete A Group" +sidebarTitle: "Delete Group" +description: "Delete a group permanently using the CometChat JavaScript SDK. Only group admins can perform this operation." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Delete a group (admin only) +await CometChat.deleteGroup("GUID"); +``` + +**Requirement:** Logged-in user must be an Admin of the group. + + + +This operation is irreversible. Deleted groups and their messages cannot be recovered. + ## Delete a Group -To delete a group you need to use the `deleteGroup()` method. The user must be an `Admin` of the group they are trying to delete. +Use `deleteGroup()` to permanently delete a group. Only group admins can perform this operation. - + +```typescript +const GUID: string = "GUID"; + +CometChat.deleteGroup(GUID).then( + (response: boolean) => { + console.log("Group deleted successfully:", response); + }, (error: CometChat.CometChatException) => { + console.log("Group delete failed with exception:", error); + } +); +``` + + + + ```javascript -var GUID = "GUID"; +const GUID = "GUID"; CometChat.deleteGroup(GUID).then( response => { @@ -24,17 +54,16 @@ response => { - -```typescript -var GUID: string = "GUID"; + +```javascript +const GUID = "GUID"; -CometChat.deleteGroup(GUID).then( - (response: boolean) => { - console.log("Group deleted successfully:", response); - }, (error: CometChat.CometChatException) => { - console.log("Group delete failed with exception:", error); - } -); +try { + const response = await CometChat.deleteGroup(GUID); + console.log("Group deleted successfully:", response); +} catch (error) { + console.log("Group delete failed with exception:", error); +} ``` @@ -46,3 +75,25 @@ The `deleteGroup()` method takes the following parameters: | Parameter | Description | | --------- | ---------------------------------------------- | | `GUID` | The GUID of the group you would like to delete | + +On success, the method resolves with a success message string confirming the operation. + + +--- + +## Next Steps + + + + Update group name, icon, description, and metadata + + + Leave a group you are a member of + + + Create public, private, or password-protected groups + + + Overview of all group management features + + diff --git a/sdk/javascript/delete-message.mdx b/sdk/javascript/delete-message.mdx index d84b07614..c0bc598c9 100644 --- a/sdk/javascript/delete-message.mdx +++ b/sdk/javascript/delete-message.mdx @@ -1,22 +1,58 @@ --- -title: "Delete A Message" +title: "Delete Message" +sidebarTitle: "Delete Message" +description: "Delete messages using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Delete a message +await CometChat.deleteMessage(messageId); -While [deleting a message](/sdk/javascript/delete-message#delete-a-message) is straightforward, receiving events for deleted messages with CometChat has two parts: +// Listen for real-time deletions +CometChat.addMessageListener("ID", new CometChat.MessageListener({ + onMessageDeleted: (message) => { + console.log("Deleted:", message.getId(), message.getDeletedAt()); + } +})); +``` -1. Adding a listener to receive [real-time message deletes](/sdk/javascript/delete-message#real-time-message-delete-events) when your app is running. -2. Calling a method to retrieve [missed message deletes](/sdk/javascript/delete-message#missed-message-delete-events) when your app was not running. +**Who can delete:** Message sender, Group admin, Group moderator +**Deleted fields:** `deletedAt` (timestamp), `deletedBy` (user who deleted) + -## Delete a Message + +This operation is irreversible. Deleted messages cannot be recovered. + + +Deleting a message is straightforward. Receiving delete events has two parts: -*In other words, as a sender, how do I delete a message?* +1. Adding a listener for [real-time deletes](#real-time-message-delete-events) when your app is running +2. Fetching [missed deletes](#missed-message-delete-events) when your app was offline -In case you have to delete a message, you can use the `deleteMessage()` method. This method takes the message ID of the message to be deleted. +## Delete a Message + +Use `deleteMessage()` with the message ID. - + +```typescript +let messageId: number = 1; + +CometChat.deleteMessage(messageId).then( + (message: CometChat.BaseMessage) => { + console.log("Message deleted", message); + }, (error: CometChat.CometChatException) => { + console.log("Message delete failed with error:", error); + } +); +``` + + + + ```javascript let messageId = "ID_OF_THE_MESSAGE_YOU_WANT_TO_DELETE"; @@ -31,24 +67,32 @@ message => { - -```typescript -let messageId: number = 1; + +```javascript +let messageId = "ID_OF_THE_MESSAGE_YOU_WANT_TO_DELETE"; -CometChat.deleteMessage(messageId).then( - (message: CometChat.BaseMessage) => { - console.log("Message deleted", message); - }, (error: CometChat.CometChatException) => { - console.log("Message delete failed with error:", error); - } -); +try { + const message = await CometChat.deleteMessage(messageId); + console.log("Message deleted", message); +} catch (error) { + console.log("Message delete failed with error:", error); +} ``` -Once the message is deleted, In the `onSuccess()` callback, you get an object of the `BaseMessage` class, with the `deletedAt` field set with the timestamp of the time the message was deleted. Also, the `deletedBy` field is set. These two fields can be used to identify if the message is deleted while iterating through a list of messages. +The deleted message object is returned with `deletedAt` (timestamp) and `deletedBy` (UID of deleter) fields set. + +The `deleteMessage()` method returns a [`BaseMessage`](/sdk/reference/messages#basemessage) object. + +Relevant fields to access on the returned message: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| deletedAt | `getDeletedAt()` | `number` | Timestamp when the message was deleted | +| deletedBy | `getDeletedBy()` | `string` | UID of the user who deleted the message | By default, CometChat allows certain roles to delete a message. @@ -61,27 +105,9 @@ By default, CometChat allows certain roles to delete a message. ## Real-time Message Delete Events -*In other words, as a recipient, how do I know when someone deletes a message when my app is running?* - -In order to receive real-time events for a message being deleted, you need to override the `onMessageDeleted()` method of the `MessageListener` class. +Use `onMessageDeleted` in `MessageListener` to receive real-time delete events. - -```javascript -let listenerID = "UNIQUE_LISTENER_ID"; - -CometChat.addMessageListener( -listenerID, -new CometChat.MessageListener({ - onMessageDeleted: message => { - console.log("Deleted Message", message); - } -}) -); -``` - - - ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; @@ -98,23 +124,66 @@ CometChat.addMessageListener( + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; + +CometChat.addMessageListener( +listenerID, +new CometChat.MessageListener({ + onMessageDeleted: message => { + console.log("Deleted Message", message); + } +}) +); +``` + + + -## Missed Message Delete Events +The `onMessageDeleted` callback receives a [`BaseMessage`](/sdk/reference/messages#basemessage) object with the `deletedAt` and `deletedBy` fields set. -*In other words, as a recipient, how do I know if someone deleted a message when my app was not running?* +Relevant fields to access on the returned message: -When you retrieve the list of previous messages, for the messages that were deleted, the `deletedAt` and the `deletedBy` fields will be set. Also, for example, of the total number of messages for a conversation are 100, and the message with message ID 50 was deleted. Now the message with id 50 will have the `deletedAt` and the `deletedBy` fields set whenever it is pulled from the history. Also, the 101st message will be an Actionc message informing you that the message with id 50 has been deleted. +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| deletedAt | `getDeletedAt()` | `number` | Timestamp when the message was deleted | +| deletedBy | `getDeletedBy()` | `string` | UID of the user who deleted the message | + +## Missed Message Delete Events -For the message deleted event, in the `Action` object received, the following fields can help you get the relevant information- +When fetching message history, deleted messages have `deletedAt` and `deletedBy` fields set. Additionally, an `Action` message is created when a message is deleted. -1. `action` - `deleted` -2. `actionOn` - Updated message object which was deleted. -3. `actionBy` - User object containing the details of the user who has deleted the message. -4. `actionFor` - User/group object having the details of the receiver to which the message was sent. +The `Action` object contains: +- `action` — `deleted` +- `actionOn` — Deleted message object +- `actionBy` — User who deleted the message +- `actionFor` — Receiver (User/Group) +You must be the message sender or a group admin/moderator to delete a message. + -In order to edit or delete a message you need to be either the sender of the message or the admin/moderator of the group in which the message was sent. + +Always remove message listeners when they're no longer needed to prevent memory leaks. + - +--- + +## Next Steps + + + + Edit sent messages in conversations + + + Send text, media, and custom messages + + + Listen for incoming messages in real-time + + + Report inappropriate messages + + diff --git a/sdk/javascript/delivery-read-receipts.mdx b/sdk/javascript/delivery-read-receipts.mdx index 464e319fd..9f5dc643b 100644 --- a/sdk/javascript/delivery-read-receipts.mdx +++ b/sdk/javascript/delivery-read-receipts.mdx @@ -1,729 +1,479 @@ --- title: "Delivery & Read Receipts" +sidebarTitle: "Delivery & Read Receipts" +description: "Mark messages as delivered, read, or unread and receive real-time receipt events using the CometChat JavaScript SDK." --- + +| Method | Description | +| --- | --- | +| `markAsDelivered(message)` | Mark a message as delivered | +| `markAsRead(message)` | Mark a message as read | +| `markConversationAsDelivered(id, type)` | Mark entire conversation as delivered | +| `markConversationAsRead(id, type)` | Mark entire conversation as read | +| `markMessageAsUnread(message)` | Mark a message as unread | +| `getMessageReceipts(messageId)` | Get delivery/read receipts for a message | -## Mark Messages as Delivered - -*In other words, as a recipient, how do I inform the sender that I've received a message?* - -You can mark the messages for a particular conversation as read using the `markAsDelivered()` method. This method takes the below parameters as input: - -| Parameter | Information | -| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messageId` | The ID of the message above which all the messages for a particular conversation are to be marked as read. | -| `receiverId` | In case of one to one conversation message's sender `UID` will be the receipt's receiver Id. In case of group conversation message's receiver Id will be the receipt's receiver Id. | -| `receiverType` | Type of the receiver. Could be either of the two values( user or group). | -| `senderId` | The `UID` of the sender of the message. | - -Messages for both user & group conversations can be marked as read using this method. - -Ideally, you would like to mark all the messages as delivered for any conversation when the user opens the chat window for that conversation. This includes two scenarios: - -1. **When the list of messages for the conversation is fetched**: In this case you need to obtain the last message in the list of messages and pass the message ID of that message to the markAsDelivered() method. -2. **When the user is on the chat window and a real-time message is received:** In this case you need to obtain the message ID of the message and pass it to the markAsDelivered() method. - - - ```javascript -var messageId = "MESSAGE_ID"; -var receiverId = "MESSAGE_RECEIVER_UID"; -var receiverType = "user"; -var senderId = "MESSAGE_SENDER_UID"; -CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId); -``` - - - - -```javascript -var messageId = "MESSAGE_ID"; -var receiverId = "MESSAGE_RECEIVER_GUID"; -var receiverType = "group"; -var senderId = "MESSAGE_SENDER_UID"; -CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId); -``` - - - - -```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_RECEIVER_UID"; -var receiverType: string = "user"; -var senderId: string = "MESSAGE_SENDER_UID"; -CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId); -``` +// Mark as delivered/read (pass message object) +CometChat.markAsDelivered(message); +CometChat.markAsRead(message); - +// Mark entire conversation +CometChat.markConversationAsRead("UID", "user"); - -```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_RECEIVER_GUID"; -var receiverType: string = "group"; -var senderId: string = "MESSAGE_SENDER_UID"; -CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId); +// Listen for receipt events +CometChat.addMessageListener("LISTENER_ID", new CometChat.MessageListener({ + onMessagesDelivered: (receipt) => { }, + onMessagesRead: (receipt) => { }, + onMessagesDeliveredToAll: (receipt) => { }, // Groups only + onMessagesReadByAll: (receipt) => { } // Groups only +})); ``` + - +Delivery and read receipts track whether messages have been delivered to and read by recipients. - +## Mark as Delivered -This method will mark all the messages before the messageId specified, for the conversation with receiverId and receiverType(user/group) as delivered. +Use `markAsDelivered()` to mark messages as delivered. You can pass either a message object or individual parameters. -In case you would like to be notified of an error if the receipts fail to go through you can use `.then(successCallback, failureCallback)` of the `markAsDelivered` method. +### Using Message Object - -```javascript -CometChat.markAsDelivered( - message.getId(), - message.getSender().getUid(), - "user", - message.getSender().getUid() -).then( + +```typescript +CometChat.markAsDelivered(message).then( () => { - console.log("mark as delivered success."); + console.log("Marked as delivered successfully"); }, - (error) => { - console.log( - "An error occurred when marking the message as delivered.", - error - ); + (error: CometChat.CometChatException) => { + console.log("Error marking as delivered:", error); } ); ``` - - - + ```javascript -CometChat.markAsDelivered( - message.getId(), - message.getReceiverUid(), - "group", - message.getSender().getUid() -).then( +CometChat.markAsDelivered(message).then( () => { - console.log("mark as delivered success."); + console.log("Marked as delivered successfully"); }, (error) => { - console.log( - "An error occurred when marking the message as delivered.", - error - ); + console.log("Error marking as delivered:", error); } ); ``` - + + +### Using Parameters + +| Parameter | Description | +| --- | --- | +| `messageId` | ID of the message to mark as delivered | +| `receiverId` | For user chats: sender's UID. For groups: group GUID | +| `receiverType` | `"user"` or `"group"` | +| `senderId` | UID of the message sender | + + + +```javascript +let messageId = "MESSAGE_ID"; +let receiverId = "MESSAGE_SENDER_UID"; +let receiverType = "user"; +let senderId = "MESSAGE_SENDER_UID"; - -```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_SENDER_UID"; -var receiverType: string = "user"; -var senderId: string = "MESSAGE_SENDER_UID"; CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as delivered success."); + console.log("Marked as delivered successfully"); }, - (error: CometChat.CometChatException) => { - console.log( - "An error occurred when marking the message as delivered.", - error - ); + (error) => { + console.log("Error marking as delivered:", error); } ); ``` - + +```javascript +let messageId = "MESSAGE_ID"; +let receiverId = "GROUP_GUID"; +let receiverType = "group"; +let senderId = "MESSAGE_SENDER_UID"; - -```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_RECEIVER_GUID"; -var receiverType: string = "group"; -var senderId: string = "MESSAGE_SENDER_UID"; CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as delivered success."); + console.log("Marked as delivered successfully"); }, - (error: CometChat.CometChatException) => { - console.log( - "An error occurred when marking the message as delivered.", - error - ); + (error) => { + console.log("Error marking as delivered:", error); } ); ``` - - - - - -Another option the CometChat SDK provides is to pass the entire message object to the markAsDelivered() method. - - - -```javascript -CometChat.markAsDelivered(message); -``` - - - + ```typescript -let message: CometChat.BaseMessage; -CometChat.markAsDelivered(message); -``` - - +let messageId: string = "MESSAGE_ID"; +let receiverId: string = "MESSAGE_SENDER_UID"; +let receiverType: string = "user"; +let senderId: string = "MESSAGE_SENDER_UID"; - - -In case you would like to be notified of an error if the receipts fail to go through you can use `.then(successCallback, failureCallback)` of the `markAsDelivered` method. - - - -```javascript -CometChat.markAsDelivered(message).then( +CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as delivered success."); + console.log("Marked as delivered successfully"); }, - (error) => { - console.log( - "An error occurred when marking the message as delivered.", - error - ); + (error: CometChat.CometChatException) => { + console.log("Error marking as delivered:", error); } ); ``` - - - + ```typescript -let message: CometChat.BaseMessage; -CometChat.markAsDelivered(message).then( +let messageId: string = "MESSAGE_ID"; +let receiverId: string = "GROUP_GUID"; +let receiverType: string = "group"; +let senderId: string = "MESSAGE_SENDER_UID"; + +CometChat.markAsDelivered(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as delivered success."); + console.log("Marked as delivered successfully"); }, (error: CometChat.CometChatException) => { - console.log( - "An error occurred when marking the message as delivered.", - error - ); + console.log("Error marking as delivered:", error); } ); ``` - - ## Mark Conversation as Delivered -You can mark an entire conversation as delivered for a user or group using the `markConversationAsDelivered()` method. This method takes the below parameters as input: +Use `markConversationAsDelivered()` to mark all messages in a conversation as delivered. -| Parameter | Information | -| ------------------ | ------------------------------------------------------------------------------ | -| `conversationWith` | The ID of the user (UID) or group (GUID) for the conversation. | -| `conversationType` | Type of the conversation. Could be either `user` or `group`. | - -This method will mark all messages in the conversation as delivered. +`markConversationAsDelivered()` resolves with a `string` on success. ```javascript -var conversationWith = "USER_UID"; -var conversationType = "user"; +let conversationWith = "USER_UID"; +let conversationType = "user"; CometChat.markConversationAsDelivered(conversationWith, conversationType).then( (response) => { console.log("Conversation marked as delivered", response); }, (error) => { - console.log("Error marking conversation as delivered", error); + console.log("Error:", error); } ); ``` - ```javascript -var conversationWith = "GROUP_GUID"; -var conversationType = "group"; +let conversationWith = "GROUP_GUID"; +let conversationType = "group"; CometChat.markConversationAsDelivered(conversationWith, conversationType).then( (response) => { console.log("Conversation marked as delivered", response); }, (error) => { - console.log("Error marking conversation as delivered", error); + console.log("Error:", error); } ); ``` - - + ```typescript -var conversationWith: string = "USER_UID"; -var conversationType: string = "user"; +let conversationWith: string = "USER_UID"; +let conversationType: string = "user"; CometChat.markConversationAsDelivered(conversationWith, conversationType).then( (response: string) => { console.log("Conversation marked as delivered", response); }, (error: CometChat.CometChatException) => { - console.log("Error marking conversation as delivered", error); + console.log("Error:", error); } ); ``` - - + ```typescript -var conversationWith: string = "GROUP_GUID"; -var conversationType: string = "group"; +let conversationWith: string = "GROUP_GUID"; +let conversationType: string = "group"; CometChat.markConversationAsDelivered(conversationWith, conversationType).then( (response: string) => { console.log("Conversation marked as delivered", response); }, (error: CometChat.CometChatException) => { - console.log("Error marking conversation as delivered", error); + console.log("Error:", error); } ); ``` -## Mark Messages as Read - -*In other words, as a recipient, how do I inform the sender I've read a message?* - -You can mark the messages for a particular conversation as read using the `markAsRead()` method. This method takes the below parameters as input: +## Mark as Read -| Parameter | Information | -| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `messageId` | The ID of the message above which all the messages for a particular conversation are to be marked as read. | -| `receiverId` | In case of one to one conversation message's sender `UID` will be the receipt's receiver Id. In case of group conversation message's receiver Id will be the receipt's receiver Id | -| `receiverType` | Type of the receiver. Could be either of the two values( user or group) | -| `senderId` | The `UID` of the sender of the message. | +Use `markAsRead()` to mark messages as read. You can pass either a message object or individual parameters. -Messages for both user and group conversations can be marked as read using this method. - -Ideally, you would like to mark all the messages as read for any conversation when the user opens the chat window for that conversation. This includes two scenarios: - -1. **When the list of messages for the conversation is fetched**: In this case you need to obtain the last message in the list of messages and pass the message ID of that message to the markAsRead() method. -2. **When the user is on the chat window and a real-time message is received:** In this case you need to obtain the message ID of the message and pass it to the markAsRead() method +### Using Message Object - -```javascript -var messageId = "MESSAGE_ID"; -var receiverId = "MESSAGE_SENDER_UID"; -var receiverType = "user"; -var senderId = "MESSAGE_SENDER_UID"; -CometChat.markAsRead(messageId, receiverId, receiverType, senderId); -``` - - - - -```javascript -var receiverId = "MESSAGE_RECEIVER_GUID"; -var receiverType = "group"; -var senderId = "MESSAGE_SENDER_UID"; -CometChat.markAsRead(messageId, receiverId, receiverType, senderId); -``` - - - - -```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_SENDER_UID"; -var receiverType: string = "user"; -var senderId: string = "MESSAGE_SENDER_UID"; -CometChat.markAsRead(messageId, receiverId, receiverType, senderId); -``` - - - - + ```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_RECEIVER_GUID"; -var receiverType: string = "group"; -var senderId: string = "MESSAGE_SENDER_UID"; -CometChat.markAsRead(messageId, receiverId, receiverType, senderId); -``` - - - - - -This method will mark all the messages before the messageId specified, for the conversation with receiverId and receiverType(user/group) as read. - -In case you would like to be notified of an error if the receipts fail to go through you can use `.then(successCallback, failureCallback)` of the `markAsDelivered` method. - - - -```javascript -CometChat.markAsRead( - message.getId(), - message.getSender().getUid(), - "user", - message.getSender().getUid() -).then( +CometChat.markAsRead(message).then( () => { - console.log("mark as read success."); + console.log("Marked as read successfully"); }, - (error) => { - console.log("An error occurred when marking the message as read.", error); + (error: CometChat.CometChatException) => { + console.log("Error marking as read:", error); } ); ``` - - - + ```javascript -CometChat.markAsRead( - message.getId(), - message.getReceiverUid(), - "group", - message.getSender().getUid() -).then( +CometChat.markAsRead(message).then( () => { - console.log("mark as read success."); + console.log("Marked as read successfully"); }, (error) => { - console.log("An error occurred when marking the message as read.", error); + console.log("Error marking as read:", error); } ); ``` - + + +### Using Parameters + + + +```javascript +let messageId = "MESSAGE_ID"; +let receiverId = "MESSAGE_SENDER_UID"; +let receiverType = "user"; +let senderId = "MESSAGE_SENDER_UID"; - -```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_SENDER_UID"; -var receiverType: string = "user"; -var senderId: string = "MESSAGE_SENDER_UID"; CometChat.markAsRead(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as read success."); + console.log("Marked as read successfully"); }, - (error: CometChat.CometChatException) => { - console.log("An error occurred when marking the message as read.", error); + (error) => { + console.log("Error marking as read:", error); } ); ``` - + +```javascript +let messageId = "MESSAGE_ID"; +let receiverId = "GROUP_GUID"; +let receiverType = "group"; +let senderId = "MESSAGE_SENDER_UID"; - -```typescript -var messageId: string = "MESSAGE_ID"; -var receiverId: string = "MESSAGE_RECEIVER_GUID"; -var receiverType: string = "group"; -var senderId: string = "MESSAGE_SENDER_UID"; CometChat.markAsRead(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as read success."); + console.log("Marked as read successfully"); }, - (error: CometChat.CometChatException) => { - console.log("An error occurred when marking the message as read.", error); + (error) => { + console.log("Error marking as read:", error); } ); ``` - - - - -Another option the CometChat SDK provides is to pass the entire message object to the markAsRead() method. - - - -```javascript -CometChat.markAsRead(message); -``` - - - - + ```typescript -let message: CometChat.BaseMessage; -CometChat.markAsRead(message); -``` +let messageId: string = "MESSAGE_ID"; +let receiverId: string = "MESSAGE_SENDER_UID"; +let receiverType: string = "user"; +let senderId: string = "MESSAGE_SENDER_UID"; - - - - -In case you would like to be notified of an error if the receipts fail to go through you can use `.then(successCallback, failureCallback)` of the `markAsDelivered` method. - - - -```javascript -CometChat.markAsRead(message).then( +CometChat.markAsRead(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as read success."); + console.log("Marked as read successfully"); }, - (error) => { - console.log("An error occurred when marking the message as read.", error); + (error: CometChat.CometChatException) => { + console.log("Error marking as read:", error); } ); ``` - - - + ```typescript -let message: CometChat.BaseMessage; -CometChat.markAsRead(message).then( +let messageId: string = "MESSAGE_ID"; +let receiverId: string = "GROUP_GUID"; +let receiverType: string = "group"; +let senderId: string = "MESSAGE_SENDER_UID"; + +CometChat.markAsRead(messageId, receiverId, receiverType, senderId).then( () => { - console.log("mark as read success."); + console.log("Marked as read successfully"); }, (error: CometChat.CometChatException) => { - console.log("An error occurred when marking the message as read.", error); + console.log("Error marking as read:", error); } ); ``` - - ## Mark Conversation as Read -You can mark an entire conversation as read for a user or group using the `markConversationAsRead()` method. This method takes the below parameters as input: - -| Parameter | Information | -| ------------------ | ------------------------------------------------------------------------------ | -| `conversationWith` | The ID of the user (UID) or group (GUID) for the conversation. | -| `conversationType` | Type of the conversation. Could be either `user` or `group`. | - -This method will mark all messages in the conversation as read. +Use `markConversationAsRead()` to mark all messages in a conversation as read. ```javascript -var conversationWith = "USER_UID"; -var conversationType = "user"; +let conversationWith = "USER_UID"; +let conversationType = "user"; CometChat.markConversationAsRead(conversationWith, conversationType).then( (response) => { console.log("Conversation marked as read", response); }, (error) => { - console.log("Error marking conversation as read", error); + console.log("Error:", error); } ); ``` - ```javascript -var conversationWith = "GROUP_GUID"; -var conversationType = "group"; +let conversationWith = "GROUP_GUID"; +let conversationType = "group"; CometChat.markConversationAsRead(conversationWith, conversationType).then( (response) => { console.log("Conversation marked as read", response); }, (error) => { - console.log("Error marking conversation as read", error); + console.log("Error:", error); } ); ``` - - + ```typescript -var conversationWith: string = "USER_UID"; -var conversationType: string = "user"; +let conversationWith: string = "USER_UID"; +let conversationType: string = "user"; CometChat.markConversationAsRead(conversationWith, conversationType).then( (response: string) => { console.log("Conversation marked as read", response); }, (error: CometChat.CometChatException) => { - console.log("Error marking conversation as read", error); + console.log("Error:", error); } ); ``` - - + ```typescript -var conversationWith: string = "GROUP_GUID"; -var conversationType: string = "group"; +let conversationWith: string = "GROUP_GUID"; +let conversationType: string = "group"; CometChat.markConversationAsRead(conversationWith, conversationType).then( (response: string) => { console.log("Conversation marked as read", response); }, (error: CometChat.CometChatException) => { - console.log("Error marking conversation as read", error); + console.log("Error:", error); } ); ``` -## Mark Messages as Unread - -The Mark messages as Unread feature allows users to designate specific messages or conversations as unread, even if they have been previously viewed. +## Mark as Unread -This feature is valuable for users who want to revisit and respond to important messages or conversations later, ensuring they don't forget or overlook them. - -In other words, how I can mark a message as unread? - -You can mark the messages for a particular conversation as unread using the `markMessageAsUnread()` method. This method takes the below parameters as input: - -| Parameter | Information | -| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| message | To mark a message as unread, pass a non-null `BaseMessage` instance to the `markMessageAsUnread()` function. All messages below that message in the conversation will contribute to the unread messages count. Example: When User B sends User A a total of 10 messages, and User A invokes the `markMessageAsUnread()` method on the fifth message, all messages located below the fifth message within the conversation list will be designated as unread. This results in a notification indicating there are 5 unread messages in the conversation list. | +Use `markMessageAsUnread()` to mark a message as unread. All messages below that message will contribute to the unread count. You cannot mark your own messages as unread. This method only works for messages received from other users. - -```javascript -CometChat.markMessageAsUnread(message); -``` - - - ```typescript -let message: CometChat.BaseMessage; -CometChat.markMessageAsUnread(message); +CometChat.markMessageAsUnread(message).then( + (conversation: CometChat.Conversation) => { + console.log("Marked as unread successfully", conversation); + console.log("Unread count:", conversation.getUnreadMessageCount()); + }, + (error: CometChat.CometChatException) => { + console.log("Error marking as unread:", error); + } +); ``` - -In case you would like to be notified of an error if the receipts fail to go through you can use `.then(successCallback, failureCallback).` On success, this method returns an updated `Conversation` object with the updated unread message count and other conversation data. +In case you would like to be notified of an error if the receipts fail to go through you can use `.then(successCallback, failureCallback).` On success, this method returns an updated [`Conversation`](/sdk/reference/entities#conversation) object with the updated unread message count and other conversation data. - + ```javascript CometChat.markMessageAsUnread(message).then( (conversation) => { - console.log("mark messages as unread success.", conversation); - console.log("Unread message count:", conversation.getUnreadMessageCount()); + console.log("Marked as unread successfully", conversation); + console.log("Unread count:", conversation.getUnreadMessageCount()); }, (error) => { - console.log("An error occurred when marking the message as unread.", error); - } -); -``` - - - - -```typescript -let message: CometChat.BaseMessage; -CometChat.markMessageAsUnread(message).then( - (conversation: CometChat.Conversation) => { - console.log("mark messages as unread success.", conversation); - console.log("Unread message count:", conversation.getUnreadMessageCount()); - }, - (error: CometChat.CometChatException) => { - console.log("An error occurred when marking the message as unread.", error); + console.log("Error marking as unread:", error); } ); ``` - - -Receive Delivery & Read Receipts +On success, returns an updated [`Conversation`](/sdk/reference/entities#conversation) object with the new unread message count. -*In other words, as a recipient, how do I know when a message I sent has been delivered or read by someone?* +## Real-Time Receipt Events -### Real-time events +Register a `MessageListener` to receive delivery and read receipt events. -1. `onMessagesDelivered()` - This event is triggered when a message is delivered to a user. -2. `onMessagesRead()` - This event is triggered when a message is read by a user. -3. `onMessagesDeliveredToAll()` - This event is triggered when a group message is delivered to all members of the group. This event is only for Group conversations. -4. `onMessagesReadByAll()` - This event is triggered when a group message is read by all members of the group. This event is only for Group conversations. +| Callback | Description | +| --- | --- | +| `onMessagesDelivered` | Message delivered to a user | +| `onMessagesRead` | Message read by a user | +| `onMessagesDeliveredToAll` | Group message delivered to all members | +| `onMessagesReadByAll` | Group message read by all members | - -```javascript -let listenerId = "UNIQUE_LISTENER_ID"; - -CometChat.addMessageListener( - "listenerId", - new CometChat.MessageListener({ - onMessagesDelivered: (messageReceipt) => { - console.log("Message is delivered to a user: ", { messageReceipt }); - }, - onMessagesRead: (messageReceipt) => { - console.log("Message is read by a user: ", { messageReceipt }); - }, - /** This event is only for Group Conversation. */ - onMessagesDeliveredToAll: (messageReceipt) => { - console.log("Message delivered to all members of group: ", { - messageReceipt, - }); - }, - /** This event is only for Group Conversation. */ - onMessagesReadByAll: (messageReceipt) => { - console.log("Message read by all members of group: ", { messageReceipt }); - }, - }) -); -``` - - - ```typescript -let listenerId: string = "UNIQUE_LISTENER_ID"; +let listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.addMessageListener( - listenerId, + listenerID, new CometChat.MessageListener({ onMessagesDelivered: (messageReceipt: CometChat.MessageReceipt) => { - console.log("Message is delivered to a user: ", { messageReceipt }); + console.log("Message delivered:", messageReceipt); }, onMessagesRead: (messageReceipt: CometChat.MessageReceipt) => { - console.log("Message is read by a user: ", { messageReceipt }); + console.log("Message read:", messageReceipt); }, - /** This event is only for Group Conversation. */ onMessagesDeliveredToAll: (messageReceipt: CometChat.MessageReceipt) => { - console.log("Message delivered to all members of group: ", { - messageReceipt, - }); + console.log("Message delivered to all group members:", messageReceipt); }, - /** This event is only for Group Conversation. */ onMessagesReadByAll: (messageReceipt: CometChat.MessageReceipt) => { - console.log("Message read by all members of group: ", { messageReceipt }); - }, + console.log("Message read by all group members:", messageReceipt); + } }) ); ``` - -You will receive events in the form of `MessageReceipt` objects. The message receipt contains the below parameters: +You will receive events in the form of [`MessageReceipt`](/sdk/reference/auxiliary#messagereceipt) objects. The message receipt contains the below parameters: | Parameter | Information | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | @@ -735,6 +485,8 @@ You will receive events in the form of `MessageReceipt` objects. The message rec | `deliveredAt` | The timestamp of the time when the message was delivered. This will only be present if the receiptType is delivered. | | `readAt` | The timestamp of the time when the message was read. This will only be present when the receiptType is read. | +The `markAsDelivered()` and `markAsRead()` methods are fire-and-forget — they do not return a `MessageReceipt` object. Use the listener callbacks above to receive delivery and read confirmations. + ### Missed Receipts You will receive message receipts when you load offline messages. While fetching messages in bulk, the message object will have two fields i.e. `deliveredAt` and `readAt` which hold the timestamp for the time the message was delivered and read respectively. Using these two variables, the delivery and read status for a message can be obtained. @@ -746,48 +498,137 @@ However, for a group message, if you wish to fetch the `deliveredAt` and `readAt To fetch the message receipts, you can use the `getMessageReceipts()` method. - + ```javascript -let messageId = msgId; -CometChat.getMessageReceipts(messageId).then( - (receipts) => { - console.log("Message details fetched:", receipts); - }, - (error) => { - console.log("Error in getting messag details ", error); - } +let listenerID = "UNIQUE_LISTENER_ID"; + +CometChat.addMessageListener( + listenerID, + new CometChat.MessageListener({ + onMessagesDelivered: (messageReceipt) => { + console.log("Message delivered:", messageReceipt); + }, + onMessagesRead: (messageReceipt) => { + console.log("Message read:", messageReceipt); + }, + onMessagesDeliveredToAll: (messageReceipt) => { + console.log("Message delivered to all group members:", messageReceipt); + }, + onMessagesReadByAll: (messageReceipt) => { + console.log("Message read by all group members:", messageReceipt); + } + }) ); ``` - + + +You will receive a list of [`MessageReceipt`](/sdk/reference/auxiliary#messagereceipt) objects. + + +The following features will be available only if the **Enhanced Messaging Status** feature is enabled for your app. + +* `onMessagesDeliveredToAll` event, +* `onMessagesReadByAll` event, +* `deliveredAt` field in a group message, +* `readAt` field in a group message. +* `markMessageAsUnread` method. + + + + +Always remove listeners when no longer needed to prevent memory leaks. + +```javascript +CometChat.removeMessageListener("UNIQUE_LISTENER_ID"); +``` + + +### MessageReceipt Object + +The listener callbacks receive a [`MessageReceipt`](/sdk/reference/auxiliary#messagereceipt) object: + +| Field | Getter | Return Type | Description | +| --- | --- | --- | --- | +| messageId | `getMessageId()` | `string` | ID of the message | +| sender | `getSender()` | [`User`](/sdk/reference/entities#user) | User who triggered the receipt | +| receiverId | `getReceiverId()` | `string` | ID of the receiver | +| receiverType | `getReceiverType()` | `string` | `"user"` or `"group"` | +| receiptType | `getReceiptType()` | `string` | `"delivery"` or `"read"` | +| deliveredAt | `getDeliveredAt()` | `number` | Timestamp when delivered | +| readAt | `getReadAt()` | `number` | Timestamp when read | + +## Get Receipt History + +Use `getMessageReceipts()` to fetch delivery and read receipts for a specific message. Useful for group messages to see which members have received/read the message. + + ```typescript -let messageId: number = 1; +let messageId: number = 123; + CometChat.getMessageReceipts(messageId).then( (receipts: CometChat.MessageReceipt[]) => { - console.log("Message details fetched:", receipts); + console.log("Message receipts:", receipts); }, (error: CometChat.CometChatException) => { - console.log("Error in getting messag details ", error); + console.log("Error fetching receipts:", error); } ); ``` - + +```javascript +let messageId = 123; +CometChat.getMessageReceipts(messageId).then( + (receipts) => { + console.log("Message receipts:", receipts); + }, + (error) => { + console.log("Error fetching receipts:", error); + } +); +``` + -You will receive a list of `MessageReceipt` objects. +Returns an array of [`MessageReceipt`](/sdk/reference/auxiliary#messagereceipt) objects. - +## Missed Receipts -The following features will be available only if the **Enhanced Messaging Status** feature is enabled for your app. +When fetching messages, each message object includes `deliveredAt` and `readAt` timestamps indicating when the message was delivered and read. -* `onMessagesDeliveredToAll` event, -* `onMessagesReadByAll` event, -* `deliveredAt` field in a group message, -* `readAt` field in a group message. -* `markMessageAsUnread` method. +```javascript +let deliveredAt = message.getDeliveredAt(); +let readAt = message.getReadAt(); +``` - + +The following features require **Enhanced Messaging Status** to be enabled for your app: +- `onMessagesDeliveredToAll` event +- `onMessagesReadByAll` event +- `deliveredAt` field in group messages +- `readAt` field in group messages +- `markMessageAsUnread()` method + + +--- + +## Next Steps + + + + Show real-time typing status in conversations + + + Listen for incoming messages in real time + + + Fetch conversation list with unread counts + + + Complete reference for all SDK event listeners + + diff --git a/sdk/javascript/direct-call.mdx b/sdk/javascript/direct-call.mdx index 0bedb0234..4e2518e91 100644 --- a/sdk/javascript/direct-call.mdx +++ b/sdk/javascript/direct-call.mdx @@ -1,18 +1,33 @@ --- title: "Call Session" +sidebarTitle: "Call Session" +description: "Learn how to generate call tokens, start and manage call sessions, configure call settings, and handle call events using the CometChat JavaScript Calls SDK." --- -## Overview + -This section demonstrates how to start a call session in a web application. Previously known as **Direct Calling**. +```javascript +// Generate call token +const callToken = await CometChatCalls.generateToken(sessionId, authToken); -Before you begin, we strongly recommend you read the [calling setup guide](/sdk/javascript/calling-setup). +// Build call settings +const callSettings = new CometChatCalls.CallSettingsBuilder() + .enableDefaultLayout(true) + .setIsAudioOnlyCall(false) + .setCallListener(callListener) + .build(); - +// Start call session +CometChatCalls.startSession(callToken.token, callSettings, htmlElement); -If you want to implement a complete calling experience with ringing functionality (incoming/outgoing call UI), follow the [Ringing](/sdk/javascript/default-call) guide first. Once the call is accepted, return here to start the call session. +// End call session +CometChatCalls.endSession(); +``` + - +A call session is the active media connection between participants — camera, microphone, screen sharing, and the call UI. Whether you arrive here from the [Ringing flow](/sdk/javascript/default-call), your own custom UI, or [Standalone Calling](/sdk/javascript/standalone-calling), this page covers how to manage the session itself. + +Before you begin, make sure you've completed the [Calls SDK Setup](/sdk/javascript/calling-setup). ## Generate Call Token @@ -20,38 +35,39 @@ A call token is required for secure access to a call session. Each token is uniq You can generate the token just before starting the call, or generate and store it ahead of time based on your use case. -Use the `generateToken()` method to create a call token: +- In the Ringing flow, the session ID comes from the [`Call`](/sdk/reference/messages#call) object after the call is accepted. +- For direct sessions, generate your own unique session ID. - -```javascript + +```typescript const loggedInUser = await CometChat.getLoggedinUser(); const authToken = loggedInUser.getAuthToken(); -const sessionId = "SESSION_ID"; // Random or from Call object in ringing flow +const sessionId: string = "SESSION_ID"; // Random or from Call object in ringing flow CometChatCalls.generateToken(sessionId, authToken).then( - (callToken) => { + (callToken: any) => { console.log("Call token generated:", callToken.token); // Use callToken to start the session }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Token generation failed:", error); } ); ``` - -```typescript + +```javascript const loggedInUser = await CometChat.getLoggedinUser(); const authToken = loggedInUser.getAuthToken(); -const sessionId: string = "SESSION_ID"; // Random or from Call object in ringing flow +const sessionId = "SESSION_ID"; // Random or from Call object in ringing flow CometChatCalls.generateToken(sessionId, authToken).then( - (callToken: any) => { + (callToken) => { console.log("Call token generated:", callToken.token); // Use callToken to start the session }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Token generation failed:", error); } ); @@ -64,6 +80,8 @@ CometChatCalls.generateToken(sessionId, authToken).then( | `sessionId` | The unique random session ID. In case you are using the ringing flow, the session ID is available in the `Call` object. | | `authToken` | The user auth token is the logged-in user auth token which you can get by calling `CometChat.getLoggedinUser().getAuthToken()` | +The `Promise` resolves with an object containing a `token` property (string) that you pass to `startSession()`. + ## Start Call Session Use the `startSession()` method to join a call session. This method requires: @@ -72,16 +90,16 @@ Use the `startSession()` method to join a call session. This method requires: 3. An HTML element where the call UI will be rendered - -```javascript + +```typescript const callListener = new CometChatCalls.OngoingCallListener({ - onUserJoined: (user) => { + onUserJoined: (user: any) => { console.log("User joined:", user); }, - onUserLeft: (user) => { + onUserLeft: (user: any) => { console.log("User left:", user); }, - onUserListUpdated: (userList) => { + onUserListUpdated: (userList: any[]) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -91,13 +109,13 @@ const callListener = new CometChatCalls.OngoingCallListener({ console.log("End call button pressed"); // Handle end call - see End Call Session section }, - onError: (error) => { + onError: (error: any) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList) => { + onMediaDeviceListUpdated: (deviceList: any[]) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event) => { + onUserMuted: (event: any) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -106,7 +124,7 @@ const callListener = new CometChatCalls.OngoingCallListener({ onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event) => { + onCallSwitchedToVideo: (event: any) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -120,20 +138,20 @@ const callSettings = new CometChatCalls.CallSettingsBuilder() .setCallListener(callListener) .build(); -const htmlElement = document.getElementById("call-container"); +const htmlElement = document.getElementById("call-container") as HTMLElement; CometChatCalls.startSession(callToken, callSettings, htmlElement); ``` - -```typescript + +```javascript const callListener = new CometChatCalls.OngoingCallListener({ - onUserJoined: (user: any) => { + onUserJoined: (user) => { console.log("User joined:", user); }, - onUserLeft: (user: any) => { + onUserLeft: (user) => { console.log("User left:", user); }, - onUserListUpdated: (userList: any[]) => { + onUserListUpdated: (userList) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -143,13 +161,13 @@ const callListener = new CometChatCalls.OngoingCallListener({ console.log("End call button pressed"); // Handle end call - see End Call Session section }, - onError: (error: any) => { + onError: (error) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList: any[]) => { + onMediaDeviceListUpdated: (deviceList) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event: any) => { + onUserMuted: (event) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -158,7 +176,7 @@ const callListener = new CometChatCalls.OngoingCallListener({ onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event: any) => { + onCallSwitchedToVideo: (event) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -172,7 +190,7 @@ const callSettings = new CometChatCalls.CallSettingsBuilder() .setCallListener(callListener) .build(); -const htmlElement = document.getElementById("call-container") as HTMLElement; +const htmlElement = document.getElementById("call-container"); CometChatCalls.startSession(callToken, callSettings, htmlElement); ``` @@ -205,6 +223,111 @@ Configure the call experience using the following `CallSettingsBuilder` methods: | `setMainVideoContainerSetting(MainVideoContainerSetting)` | Customizes the main video container. See [Video View Customization](/sdk/javascript/video-view-customisation). | | `setIdleTimeoutPeriod(number)` | Sets idle timeout in seconds. Warning appears 60 seconds before auto-termination. Default: `180` seconds. *v4.1.0+* | +## End Call Session + +How you end a call depends on whether you're using the Ringing flow or a direct session. + +### Ringing Flow + +When using the [Ringing](/sdk/javascript/default-call) flow, you must coordinate between the CometChat Chat SDK and the Calls SDK to properly terminate the call and notify all participants. + + +The Ringing flow requires calling methods from both the Chat SDK (`CometChat.endCall()`) and the Calls SDK (`CometChatCalls.endSession()`) to ensure proper call termination and participant notification. + + + + + + +**User who initiates the end call:** + +When the user clicks the end call button in the UI, the `onCallEndButtonPressed()` callback is triggered. You must call `CometChat.endCall()` inside this callback to properly terminate the call and notify other participants. On success, call `CometChat.clearActiveCall()` and `CometChatCalls.endSession()` to release resources. + + + +```typescript +onCallEndButtonPressed: () => { + CometChat.endCall(sessionId).then( + (call: CometChat.Call) => { + console.log("Call ended successfully"); + CometChat.clearActiveCall(); + CometChatCalls.endSession(); + // Close the calling screen + }, + (error: CometChat.CometChatException) => { + console.log("End call failed:", error); + } + ); +} +``` + + +```javascript +onCallEndButtonPressed: () => { + CometChat.endCall(sessionId).then( + (call) => { + console.log("Call ended successfully"); + CometChat.clearActiveCall(); + CometChatCalls.endSession(); + // Close the calling screen + }, + (error) => { + console.log("End call failed:", error); + } + ); +} +``` + + + +**Remote participant** (receives the `onCallEnded()` callback): + +Call `CometChat.clearActiveCall()` to clear the local call state, then call `CometChatCalls.endSession()` to release media resources. + + + +```typescript +onCallEnded: () => { + CometChat.clearActiveCall(); + CometChatCalls.endSession(); + // Close the calling screen +} +``` + + +```javascript +onCallEnded: () => { + CometChat.clearActiveCall(); + CometChatCalls.endSession(); + // Close the calling screen +} +``` + + + +### Session Only Flow + +When using the Session Only flow (direct call without ringing), you only need to call the Calls SDK method to end the session. There's no need to notify the Chat SDK since no call signaling was involved. + + + +```typescript +onCallEndButtonPressed: () => { + CometChatCalls.endSession(); + // Close the calling screen +} +``` + + +```javascript +onCallEndButtonPressed: () => { + CometChatCalls.endSession(); + // Close the calling screen +} +``` + + + ## Call Listeners The `OngoingCallListener` provides real-time callbacks for call session events, including participant changes, call state updates, and error conditions. @@ -219,18 +342,18 @@ Each listener requires a unique `listenerId` string. This ID is used to: - **Enable targeted removal** — Remove specific listeners without affecting others - -```javascript -const listenerId = "UNIQUE_LISTENER_ID"; + +```typescript +const listenerId: string = "UNIQUE_LISTENER_ID"; CometChatCalls.addCallEventListener(listenerId, { - onUserJoined: (user) => { + onUserJoined: (user: any) => { console.log("User joined:", user); }, - onUserLeft: (user) => { + onUserLeft: (user: any) => { console.log("User left:", user); }, - onUserListUpdated: (userList) => { + onUserListUpdated: (userList: any[]) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -239,13 +362,13 @@ CometChatCalls.addCallEventListener(listenerId, { onCallEndButtonPressed: () => { console.log("End call button pressed"); }, - onError: (error) => { + onError: (error: any) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList) => { + onMediaDeviceListUpdated: (deviceList: any[]) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event) => { + onUserMuted: (event: any) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -254,7 +377,7 @@ CometChatCalls.addCallEventListener(listenerId, { onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event) => { + onCallSwitchedToVideo: (event: any) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -266,18 +389,18 @@ CometChatCalls.addCallEventListener(listenerId, { CometChatCalls.removeCallEventListener(listenerId); ``` - -```typescript -const listenerId: string = "UNIQUE_LISTENER_ID"; + +```javascript +const listenerId = "UNIQUE_LISTENER_ID"; CometChatCalls.addCallEventListener(listenerId, { - onUserJoined: (user: any) => { + onUserJoined: (user) => { console.log("User joined:", user); }, - onUserLeft: (user: any) => { + onUserLeft: (user) => { console.log("User left:", user); }, - onUserListUpdated: (userList: any[]) => { + onUserListUpdated: (userList) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -286,13 +409,13 @@ CometChatCalls.addCallEventListener(listenerId, { onCallEndButtonPressed: () => { console.log("End call button pressed"); }, - onError: (error: any) => { + onError: (error) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList: any[]) => { + onMediaDeviceListUpdated: (deviceList) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event: any) => { + onUserMuted: (event) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -301,7 +424,7 @@ CometChatCalls.addCallEventListener(listenerId, { onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event: any) => { + onCallSwitchedToVideo: (event) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -315,133 +438,21 @@ CometChatCalls.removeCallEventListener(listenerId); -### Events + +Always remove call event listeners when they're no longer needed (e.g., on component unmount or when the call screen is closed). Failing to remove listeners can cause memory leaks and duplicate event handling. -| Event | Description | -| ----- | ----------- | -| `onCallEnded()` | Invoked when the call session terminates for a 1:1 call. Both participants receive this callback. Only fires for calls with exactly 2 participants. | -| `onSessionTimeout()` | Invoked when the call is auto-terminated due to inactivity (default: 180 seconds). Warning appears 60 seconds before. *v4.1.0+* | -| `onCallEndButtonPressed()` | Invoked when the local user clicks the end call button. For ringing flow, call `CometChat.endCall()`. For standalone, call `CometChatCalls.endSession()`. | -| `onUserJoined(user)` | Invoked when a remote participant joins. The `user` contains UID, name, and avatar. | -| `onUserLeft(user)` | Invoked when a remote participant leaves the call session. | -| `onUserListUpdated(userList)` | Invoked whenever the participant list changes (join or leave events). | -| `onMediaDeviceListUpdated(deviceList)` | Invoked when available audio/video devices change (e.g., new microphone connected). | -| `onUserMuted(event)` | Invoked when a participant's mute state changes. Contains `muted` and `mutedBy` properties. | -| `onScreenShareStarted()` | Invoked when the local user starts sharing their screen. | -| `onScreenShareStopped()` | Invoked when the local user stops sharing their screen. | -| `onCallSwitchedToVideo(event)` | Invoked when an audio call is upgraded to a video call. Contains `sessionId`, `initiator`, and `responder`. | -| `onError(error)` | Invoked when an error occurs during the call session. | - -## End Call Session - -Ending a call session properly is essential to release media resources (camera, microphone, network connections) and update call state across all participants. The termination process differs based on whether you're using the Ringing flow or Session Only flow. - -### Ringing Flow - -When using the [Ringing](/sdk/javascript/default-call) flow, you must coordinate between the CometChat Chat SDK and the Calls SDK to properly terminate the call and notify all participants. - - - -The Ringing flow requires calling methods from both the Chat SDK (`CometChat.endCall()`) and the Calls SDK (`CometChatCalls.endSession()`) to ensure proper call termination and participant notification. - - - - - - - -**User who initiates the end call:** - -When the user clicks the end call button in the UI, the `onCallEndButtonPressed()` callback is triggered. You must call `CometChat.endCall()` inside this callback to properly terminate the call and notify other participants. On success, call `CometChat.clearActiveCall()` and `CometChatCalls.endSession()` to release resources. - - - -```javascript -onCallEndButtonPressed: () => { - CometChat.endCall(sessionId).then( - (call) => { - console.log("Call ended successfully"); - CometChat.clearActiveCall(); - CometChatCalls.endSession(); - // Close the calling screen - }, - (error) => { - console.log("End call failed:", error); - } - ); -} -``` - - -```typescript -onCallEndButtonPressed: () => { - CometChat.endCall(sessionId).then( - (call: CometChat.Call) => { - console.log("Call ended successfully"); - CometChat.clearActiveCall(); - CometChatCalls.endSession(); - // Close the calling screen - }, - (error: CometChat.CometChatException) => { - console.log("End call failed:", error); - } - ); -} -``` - - - -**Remote participant** (receives the `onCallEnded()` callback): - -Call `CometChat.clearActiveCall()` to clear the local call state, then call `CometChatCalls.endSession()` to release media resources. - - - ```javascript -onCallEnded: () => { - CometChat.clearActiveCall(); - CometChatCalls.endSession(); - // Close the calling screen -} +CometChatCalls.removeCallEventListener("UNIQUE_LISTENER_ID"); ``` - - -```typescript -onCallEnded: () => { - CometChat.clearActiveCall(); - CometChatCalls.endSession(); - // Close the calling screen -} -``` - - + -### Session Only Flow +### Events -When using the Session Only flow (direct call without ringing), you only need to call the Calls SDK method to end the session. There's no need to notify the Chat SDK since no call signaling was involved. +For the full list of callbacks, their descriptions, and parameter shapes, see the [`OngoingCallListener`](/sdk/javascript/all-real-time-listeners#ongoing-call-listener-calls-sdk) reference. -Call `CometChatCalls.endSession()` in the `onCallEndButtonPressed()` callback to release all media resources and disconnect from the call session. +The ringing flow methods (`initiateCall()`, `acceptCall()`, `rejectCall()`, `endCall()`) return [`Call`](/sdk/reference/messages#call) objects. - - -```javascript -onCallEndButtonPressed: () => { - CometChatCalls.endSession(); - // Close the calling screen -} -``` - - -```typescript -onCallEndButtonPressed: () => { - CometChatCalls.endSession(); - // Close the calling screen -} -``` - - - -## Methods +## In-Call Methods These methods are available for performing custom actions during an active call session. Use them to build custom UI controls or implement specific behaviors based on your use case. @@ -454,13 +465,13 @@ These methods can only be called when a call session is active. Toggles between the front and rear camera during a video call. Only supported on mobile browsers. - -```javascript + +```typescript CometChatCalls.switchCamera(); ``` - -```typescript + +```javascript CometChatCalls.switchCamera(); ``` @@ -478,13 +489,13 @@ Controls the local audio stream transmission. When muted, other participants can - `false` — Unmutes the microphone, resumes audio transmission - -```javascript + +```typescript CometChatCalls.muteAudio(true); ``` - -```typescript + +```javascript CometChatCalls.muteAudio(true); ``` @@ -498,13 +509,13 @@ Controls the local video stream transmission. When paused, other participants se - `false` — Resumes the camera, continues video transmission - -```javascript + +```typescript CometChatCalls.pauseVideo(true); ``` - -```typescript + +```javascript CometChatCalls.pauseVideo(true); ``` @@ -515,13 +526,13 @@ CometChatCalls.pauseVideo(true); Starts sharing your screen or a specific application window with other participants. - -```javascript + +```typescript CometChatCalls.startScreenShare(); ``` - -```typescript + +```javascript CometChatCalls.startScreenShare(); ``` @@ -532,13 +543,13 @@ CometChatCalls.startScreenShare(); Stops the current screen sharing session. - -```javascript + +```typescript CometChatCalls.stopScreenShare(); ``` - -```typescript + +```javascript CometChatCalls.stopScreenShare(); ``` @@ -553,13 +564,13 @@ Changes the call UI layout mode dynamically during the call. - `CometChat.CALL_MODE.SPOTLIGHT` — Focus on the active speaker - -```javascript + +```typescript CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ``` - -```typescript + +```javascript CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ``` @@ -567,17 +578,17 @@ CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ### Get Audio Input Devices -Returns a list of available audio input devices (microphones). +Returns a list of available audio input devices (microphones) as [`MediaDeviceInfo[]`](/sdk/reference/calls#mediadeviceinfo). - -```javascript + +```typescript const audioInputDevices = CometChatCalls.getAudioInputDevices(); console.log("Available microphones:", audioInputDevices); ``` - -```typescript + +```javascript const audioInputDevices = CometChatCalls.getAudioInputDevices(); console.log("Available microphones:", audioInputDevices); ``` @@ -586,17 +597,17 @@ console.log("Available microphones:", audioInputDevices); ### Get Audio Output Devices -Returns a list of available audio output devices (speakers/headphones). +Returns a list of available audio output devices (speakers/headphones) as [`MediaDeviceInfo[]`](/sdk/reference/calls#mediadeviceinfo). - -```javascript + +```typescript const audioOutputDevices = CometChatCalls.getAudioOutputDevices(); console.log("Available speakers:", audioOutputDevices); ``` - -```typescript + +```javascript const audioOutputDevices = CometChatCalls.getAudioOutputDevices(); console.log("Available speakers:", audioOutputDevices); ``` @@ -605,17 +616,17 @@ console.log("Available speakers:", audioOutputDevices); ### Get Video Input Devices -Returns a list of available video input devices (cameras). +Returns a list of available video input devices (cameras) as [`MediaDeviceInfo[]`](/sdk/reference/calls#mediadeviceinfo). - -```javascript + +```typescript const videoInputDevices = CometChatCalls.getVideoInputDevices(); console.log("Available cameras:", videoInputDevices); ``` - -```typescript + +```javascript const videoInputDevices = CometChatCalls.getVideoInputDevices(); console.log("Available cameras:", videoInputDevices); ``` @@ -627,13 +638,13 @@ console.log("Available cameras:", videoInputDevices); Sets the active audio input device (microphone) by device ID. - -```javascript + +```typescript CometChatCalls.setAudioInputDevice(deviceId); ``` - -```typescript + +```javascript CometChatCalls.setAudioInputDevice(deviceId); ``` @@ -644,13 +655,13 @@ CometChatCalls.setAudioInputDevice(deviceId); Sets the active audio output device (speaker/headphones) by device ID. - -```javascript + +```typescript CometChatCalls.setAudioOutputDevice(deviceId); ``` - -```typescript + +```javascript CometChatCalls.setAudioOutputDevice(deviceId); ``` @@ -661,13 +672,13 @@ CometChatCalls.setAudioOutputDevice(deviceId); Sets the active video input device (camera) by device ID. - -```javascript + +```typescript CometChatCalls.setVideoInputDevice(deviceId); ``` - -```typescript + +```javascript CometChatCalls.setVideoInputDevice(deviceId); ``` @@ -678,13 +689,13 @@ CometChatCalls.setVideoInputDevice(deviceId); Upgrades an ongoing audio call to a video call. This enables the camera and starts transmitting video to other participants. The remote participant receives the `onCallSwitchedToVideo()` callback. - -```javascript + +```typescript CometChatCalls.switchToVideoCall(); ``` - -```typescript + +```javascript CometChatCalls.switchToVideoCall(); ``` @@ -695,14 +706,28 @@ CometChatCalls.switchToVideoCall(); Terminates the current call session and releases all media resources (camera, microphone, network connections). After calling this method, the call view should be closed. - + ```javascript CometChatCalls.endSession(); ``` - -```typescript -CometChatCalls.endSession(); -``` - + +--- + +## Next Steps + + + + Implement calls with incoming/outgoing ringing UI + + + Record call sessions for playback + + + Customize the video layout and main video container + + + Retrieve and display call history + + diff --git a/sdk/javascript/edit-message.mdx b/sdk/javascript/edit-message.mdx index 8b91b4aea..6f704b825 100644 --- a/sdk/javascript/edit-message.mdx +++ b/sdk/javascript/edit-message.mdx @@ -1,23 +1,37 @@ --- -title: "Edit A Message" +title: "Edit Message" +sidebarTitle: "Edit Message" +description: "Edit text and custom messages using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Edit a text message +const textMessage = new CometChat.TextMessage(receiverID, "Updated text", receiverType); +textMessage.setId(messageId); +await CometChat.editMessage(textMessage); -While [editing a message](/sdk/javascript/edit-message#edit-a-message) is straightforward, receiving events for edited messages with CometChat has two parts: +// Listen for real-time edits +CometChat.addMessageListener("edits", new CometChat.MessageListener({ + onMessageEdited: (message) => console.log("Edited:", message) +})); +``` + -1. Adding a listener to receive [real-time message edits](/sdk/javascript/edit-message#real-time-message-edit-events) when your app is running -2. Calling a method to retrieve [missed message edits](/sdk/javascript/edit-message#missed-message-edit-events) when your app was not running +Editing a message is straightforward. Receiving edit events has two parts: -## Edit a Message +1. Adding a listener for [real-time edits](#real-time-message-edit-events) when your app is running +2. Fetching [missed edits](#missed-message-edit-events) when your app was offline -*In other words, as a sender, how do I edit a message?* +## Edit a Message -In order to edit a message, you can use the `editMessage()` method. This method takes an object of the `BaseMessage` class. At the moment, you are only allowed to edit `TextMessage` and `CustomMessage`. Thus, the `BaseMessage` object must either be a Text or a Custom Message. +Use `editMessage()` with a [`TextMessage`](/sdk/reference/messages#textmessage) or [`CustomMessage`](/sdk/reference/messages#custommessage) object. Set the message ID using `setId()`. ### Add/Update Tags -While editing a message, you can update the tags associated with the Message. You can use the `setTags()` method to do so. The tags added while editing a message will replace the tags set when the message was sent. +Use `setTags()` to update tags when editing. New tags replace existing ones. @@ -58,10 +72,31 @@ customMessage.setTags(tags); -Once the message object is ready, you can use the `editMessage()` method and pass the message object to it. +Once the message object is ready, call `editMessage()`. - + +```typescript +let receiverID: string = "RECEIVER_UID"; +let messageText: string = "Hello world!"; +let receiverType: string = CometChat.RECEIVER_TYPE.USER; +let messageId: number = 1; +let textMessage: CometChat.TextMessage = new CometChat.TextMessage(receiverID, messageText, receiverType); + +textMessage.setId(messageId); + +CometChat.editMessage(textMessage).then( + (message: CometChat.TextMessage) => { + console.log("Message Edited", message); + }, (error: CometChat.CometChatException) => { + console.log("Message editing failed with error:", error); + } +); +``` + + + + ```javascript let receiverID = "RECEIVER_UID"; let messageText = "Hello world!"; @@ -82,30 +117,38 @@ message => { - -```typescript -let receiverID: string = "RECEIVER_UID"; -let messageText: string = "Hello world!"; -let receiverType: string = CometChat.RECEIVER_TYPE.USER; -let messageId: number = 1; -let textMessage: CometChat.TextMessage = new CometChat.TextMessage(receiverID, messageText, receiverType); + +```javascript +try { + let receiverID = "RECEIVER_UID"; + let messageText = "Hello world!"; + let receiverType = CometChat.RECEIVER_TYPE.USER; + let messageId = "MESSAGE_ID_OF_THE_MESSAGE_TO_BE_EDITED"; + let textMessage = new CometChat.TextMessage(receiverID, messageText, receiverType); -textMessage.setId(messageId); + textMessage.setId(messageId); -CometChat.editMessage(textMessage).then( - (message: CometChat.TextMessage) => { - console.log("Message Edited", message); - }, (error: CometChat.CometChatException) => { - console.log("Message editing failed with error:", error); - } -); + const message = await CometChat.editMessage(textMessage); + console.log("Message Edited", message); +} catch (error) { + console.log("Message editing failed with error:", error); +} ``` -The object of the edited message will be returned in the `onSuccess()` callback method of the listener. The message object will contain the `editedAt` field set with the timestamp of the time the message was edited. This will help you identify if the message was edited while iterating through the list of messages. The `editedBy` field is also set to the UID of the user who edited the message. +The edited message object is returned with `editedAt` (timestamp) and `editedBy` (UID of editor) fields set. + +The `editMessage()` method returns a [`BaseMessage`](/sdk/reference/messages#basemessage) object (or a subclass like [`TextMessage`](/sdk/reference/messages#textmessage)). + +Relevant fields to access on the returned message: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| editedAt | `getEditedAt()` | `number` | Timestamp when the message was edited | +| editedBy | `getEditedBy()` | `string` | UID of the user who edited the message | By default, CometChat allows certain roles to edit a message. @@ -118,19 +161,17 @@ By default, CometChat allows certain roles to edit a message. ## Real-time Message Edit Events -*In other words, as a recipient, how do I know when someone has edited their message when my app is running?* - -In order to receive real-time events for message being edited, you need to override the `onMessageEdited()` method of the `MessageListener` class. +Use `onMessageEdited` in `MessageListener` to receive real-time edit events. - -```javascript -let listenerID = "UNIQUE_LISTENER_ID"; + +```typescript +let listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.addMessageListener( listenerID, new CometChat.MessageListener({ - onMessageEdited: message => { + onMessageEdited: (message: CometChat.BaseMessage) => { console.log("Edited Message", message); } }) @@ -139,14 +180,14 @@ new CometChat.MessageListener({ - -```typescript -let listenerID: string = "UNIQUE_LISTENER_ID"; + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; CometChat.addMessageListener( listenerID, new CometChat.MessageListener({ - onMessageEdited: (message: CometChat.BaseMessage) => { + onMessageEdited: message => { console.log("Edited Message", message); } }) @@ -157,21 +198,52 @@ new CometChat.MessageListener({ -## Missed Message Edit Events + +Always remove message listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. -*In other words, as a recipient, how do I know when someone edited their message when my app was not running?* +```javascript +CometChat.removeMessageListener("UNIQUE_LISTENER_ID"); +``` + -When you retrieve the list of previous messages, for the message that was edited, the `editedAt` and the `editedBy` fields will be set. Also, for example, of the total number of messages for a conversation are 100, and the message with message ID 50 was edited. Now the message with id 50 will have the `editedAt` and the `editedBy` fields set whenever it is pulled from the history. Also, the 101st message will be and \[Action] message informing you that the message with id 50 has been edited. +The `onMessageEdited` callback receives a [`BaseMessage`](/sdk/reference/messages#basemessage) object with the `editedAt` and `editedBy` fields set. -For the message edited event, in the `Action` object received, the following fields can help you get the relevant information- +Relevant fields to access on the returned message: -1. `action` - `edited` -2. `actionOn` - Updated message object with the edited details. -3. `actionBy` - User object containing the details of the user who has edited the message. -4. `actionFor` - User/group object having the details of the receiver to which the message was sent. +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| editedAt | `getEditedAt()` | `number` | Timestamp when the message was edited | +| editedBy | `getEditedBy()` | `string` | UID of the user who edited the message | - +## Missed Message Edit Events + +When fetching message history, edited messages have `editedAt` and `editedBy` fields set. Additionally, an `Action` message is created when a message is edited. -In order to edit a message, you need to be either the sender of the message or the admin/moderator of the group in which the message was sent. +The `Action` object contains: +- `action` — `edited` +- `actionOn` — Updated message object +- `actionBy` — User who edited the message +- `actionFor` — Receiver (User/Group) + +You must be the message sender or a group admin/moderator to edit a message. + +--- + +## Next Steps + + + + Remove messages from conversations + + + Send text, media, and custom messages + + + Organize conversations with message threads + + + Listen for incoming messages in real time + + diff --git a/sdk/javascript/flag-message.mdx b/sdk/javascript/flag-message.mdx index 350149f5d..e0dd7c2b6 100644 --- a/sdk/javascript/flag-message.mdx +++ b/sdk/javascript/flag-message.mdx @@ -1,7 +1,24 @@ --- title: "Flag Message" +sidebarTitle: "Flag Message" +description: "Flag inappropriate messages for moderation review using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + + +```javascript +// Get available flag reasons +const reasons = await CometChat.getFlagReasons(); + +// Flag a message +await CometChat.flagMessage("MESSAGE_ID", { + reasonId: "spam", + remark: "Promotional content" +}); +``` + + ## Overview Flagging messages allows users to report inappropriate content to moderators or administrators. When a message is flagged, it appears in the [CometChat Dashboard](https://app.cometchat.com) under **Moderation > Flagged Messages** for review. @@ -44,29 +61,29 @@ sequenceDiagram Before flagging a message, retrieve the list of available flag reasons configured in your Dashboard: - - ```javascript + + ```typescript CometChat.getFlagReasons().then( - (reasons) => { + (reasons: CometChat.FlagReason[]) => { console.log("Flag reasons retrieved:", reasons); // reasons is an array of { id, reason } objects // Use these to populate your report dialog UI }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Failed to get flag reasons:", error); } ); ``` - - ```typescript + + ```javascript CometChat.getFlagReasons().then( - (reasons: CometChat.FlagReason[]) => { + (reasons) => { console.log("Flag reasons retrieved:", reasons); // reasons is an array of { id, reason } objects // Use these to populate your report dialog UI }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Failed to get flag reasons:", error); } ); @@ -76,7 +93,7 @@ Before flagging a message, retrieve the list of available flag reasons configure ### Response -The response is an array of flag reason objects: +The response is an array of `FlagReason` objects, each with an `id` and `reason` string: ```javascript [ @@ -94,37 +111,37 @@ The response is an array of flag reason objects: To flag a message, use the `flagMessage()` method with the message ID and a payload containing the reason: - - ```javascript - const messageId = "MESSAGE_ID_TO_FLAG"; - const payload = { - reasonId: "spam", // Required: ID from getFlagReasons() - remark: "This message contains promotional content" // Optional + + ```typescript + const messageId: string = "MESSAGE_ID_TO_FLAG"; + const payload: { reasonId: string; remark?: string } = { + reasonId: "spam", + remark: "This message contains promotional content" }; CometChat.flagMessage(messageId, payload).then( - (response) => { + (response: CometChat.FlagMessageResponse) => { console.log("Message flagged successfully:", response); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Message flagging failed:", error); } ); ``` - - ```typescript - const messageId: string = "MESSAGE_ID_TO_FLAG"; - const payload: { reasonId: string; remark?: string } = { - reasonId: "spam", - remark: "This message contains promotional content" + + ```javascript + const messageId = "MESSAGE_ID_TO_FLAG"; + const payload = { + reasonId: "spam", // Required: ID from getFlagReasons() + remark: "This message contains promotional content" // Optional }; CometChat.flagMessage(messageId, payload).then( - (response: CometChat.FlagMessageResponse) => { + (response) => { console.log("Message flagged successfully:", response); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Message flagging failed:", error); } ); @@ -142,6 +159,8 @@ To flag a message, use the `flagMessage()` method with the message ID and a payl ### Response +The `Promise` resolves with a success confirmation object: + ```javascript { "success": true, @@ -149,6 +168,8 @@ To flag a message, use the `flagMessage()` method with the message ID and a payl } ``` +The flagged message is a [`BaseMessage`](/sdk/reference/messages#basemessage) object. You can identify it using `getId()`, `getSender()` (returns a [`User`](/sdk/reference/entities#user)), and `getType()`. + ## Complete Example Here's a complete implementation showing how to build a report message flow: @@ -218,3 +239,22 @@ if (result.success) { showToast("Message reported successfully"); } ``` + +--- + +## Next Steps + + + + Automate content moderation with AI + + + Remove messages from conversations + + + Listen for incoming messages in real time + + + Send text, media, and custom messages + + diff --git a/sdk/javascript/group-add-members.mdx b/sdk/javascript/group-add-members.mdx index 98170bf0b..a08ae2526 100644 --- a/sdk/javascript/group-add-members.mdx +++ b/sdk/javascript/group-add-members.mdx @@ -1,31 +1,52 @@ --- title: "Add Members To A Group" +sidebarTitle: "Add Members" +description: "Learn how to add members to a group, receive real-time member added events, and handle missed events using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Add members to a group +const members = [ + new CometChat.GroupMember("UID", CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT) +]; +await CometChat.addMembersToGroup("GUID", members, []); + +// Listen for member added events +CometChat.addGroupListener("listener", new CometChat.GroupListener({ + onMemberAddedToGroup: (message, userAdded, userAddedBy, userAddedIn) => { } +})); +``` + + +You can add members to a group programmatically and listen for real-time events when members are added. ## Add Members to Group -You can add members to the group using the `addMembersToGroup()` method. This method takes the below parameters: +Use `addMembersToGroup()` to add members to a [Group](/sdk/reference/entities#group). -1. `GUID` - GUID of the group the members are to be added to. -2. `members` - This is a list of `GroupMember` objects. In order to add members, you need to create an object of the `GroupMember` class. The UID and the scope of the `GroupMember` are mandatory. -3. `bannedMembers` - This is the list of `UID's` that need to be banned from the Group. This can be set to `null` if there are no members to be banned. +| Parameter | Description | +|-----------|-------------| +| `GUID` | The group to add members to | +| `members` | Array of [GroupMember](/sdk/reference/entities#groupmember) objects (UID and scope required) | +| `bannedMembers` | Array of UIDs to ban (can be empty) | - -```javascript -let GUID = "GUID"; -let UID = "UID"; -let membersList = [ + +```typescript +let GUID: string = "GUID"; +let UID: string = "UID"; +let membersList: CometChat.GroupMember[] = [ new CometChat.GroupMember(UID, CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT), ]; CometChat.addMembersToGroup(GUID, membersList, []).then( - (response) => { + (response: Object) => { console.log("response", response); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Something went wrong", error); } ); @@ -33,19 +54,19 @@ CometChat.addMembersToGroup(GUID, membersList, []).then( - -```typescript -let GUID: string = "GUID"; -let UID: string = "UID"; -let membersList: CometChat.GroupMember[] = [ + +```javascript +let GUID = "GUID"; +let UID = "UID"; +let membersList = [ new CometChat.GroupMember(UID, CometChat.GROUP_MEMBER_SCOPE.PARTICIPANT), ]; CometChat.addMembersToGroup(GUID, membersList, []).then( - (response: Object) => { + (response) => { console.log("response", response); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Something went wrong", error); } ); @@ -57,29 +78,30 @@ CometChat.addMembersToGroup(GUID, membersList, []).then( It will return a Array which will contain the `UID` of the users and the value will either be `success` or an error message describing why the operation to add the user to the group. -## Real-Time Group Member Added Events +The method returns a response object where each key is a `UID` and the value is either `"success"` or an error message. -*In other words, as a member of a group, how do I know when someone is added to the group when my app is running?* +## Real-Time Group Member Added Events - When a group member is added by another member, this event is triggered. When a user joins a group on their own, the joined event is triggered. - -To receive real-time events whenever a new member is added to a group, you need to implement the `onMemberAddedToGroup()` methods of the `GroupListener` class. - -`onMemberAddedToGroup()` - This method is triggered when any user is added to the group so that the logged in user is informed of the other members added to the group. +Implement `onMemberAddedToGroup()` in `GroupListener` to receive real-time notifications when members are added. - -```javascript -var listenerID = "UNIQUE_LISTENER_ID"; + +```typescript +const listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.addGroupListener( listenerID, new CometChat.GroupListener({ - onMemberAddedToGroup: (message, userAdded, userAddedBy, userAddedIn) => { + onMemberAddedToGroup: ( + message: CometChat.Action, + userAdded: CometChat.User, + userAddedBy: CometChat.User, + userAddedIn: CometChat.Group + ) => { console.log("User joined", { message, userAdded, @@ -93,19 +115,14 @@ CometChat.addGroupListener( - -```typescript -var listenerID: string = "UNIQUE_LISTENER_ID"; + +```javascript +const listenerID = "UNIQUE_LISTENER_ID"; CometChat.addGroupListener( listenerID, new CometChat.GroupListener({ - onMemberAddedToGroup: ( - message: CometChat.Action, - userAdded: CometChat.User, - userAddedBy: CometChat.User, - userAddedIn: CometChat.Group - ) => { + onMemberAddedToGroup: (message, userAdded, userAddedBy, userAddedIn) => { console.log("User joined", { message, userAdded, @@ -121,15 +138,40 @@ CometChat.addGroupListener( + +Always remove group listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + +```javascript +CometChat.removeGroupListener("UNIQUE_LISTENER_ID"); +``` + + ## Member Added to Group event in Message History -*In other words, as a member of a group, how do I know when someone is added to the group when my app is not running?* +When fetching previous messages, member additions appear as [Action](/sdk/reference/messages#action) messages (a subclass of `BaseMessage`). -When you retrieve the list of previous messages if a member has been added to any group that the logged-in user is a member of, the list of messages will contain an `Action` message. An `Action` message is a sub-class of `BaseMessage` class. +| Field | Value/Type | Description | +|-------|------------|-------------| +| `action` | `"added"` | The action type | +| `actionOn` | [User](/sdk/reference/entities#user) | The user who was added | +| `actionBy` | [User](/sdk/reference/entities#user) | The user who added the member | +| `actionFor` | [Group](/sdk/reference/entities#group) | The group the member was added to | -For the group member added event, in the `Action` object received, the following fields can help you get the relevant information- +--- -1. `action` - `added` -2. `actionOn` - User object containing the details of the user who was added to the group -3. `actionBy` - User object containing the details of the user who added the member to the group -4. `actionFor` - Group object containing the details of the group to which the member was added +## Next Steps + + + + Remove or ban members from a group + + + Promote or demote group members + + + Fetch the list of members in a group + + + Allow users to join public or password-protected groups + + diff --git a/sdk/javascript/group-change-member-scope.mdx b/sdk/javascript/group-change-member-scope.mdx index 422ae34b8..8b19506db 100644 --- a/sdk/javascript/group-change-member-scope.mdx +++ b/sdk/javascript/group-change-member-scope.mdx @@ -1,31 +1,30 @@ --- title: "Change Member Scope" +sidebarTitle: "Change Scope" +description: "Learn how to change group member roles (admin, moderator, participant) and receive real-time scope change events using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + - -## Change Scope of a Group Member - -In order to change the scope of a group member, you can use the `changeGroupMemberScope()`. - - - ```javascript -let GUID = "GUID"; -let UID = "UID"; -let scope = CometChat.GROUP_MEMBER_SCOPE.ADMIN; +// Change member scope to admin +await CometChat.updateGroupMemberScope("GUID", "UID", CometChat.GROUP_MEMBER_SCOPE.ADMIN); -CometChat.updateGroupMemberScope(GUID, UID, scope).then( -response => { - console.log("Group member scopped changed", response); -}, error => { - console.log("Group member scopped changed failed", error); -} -); +// Listen for scope change events +CometChat.addGroupListener("listener", new CometChat.GroupListener({ + onGroupMemberScopeChanged: (message, changedUser, newScope, oldScope, changedGroup) => { } +})); ``` + - +You can change the role of a group member between admin, moderator, and participant. + +## Change Scope of a Group Member + +Use `updateGroupMemberScope()` to change a member's role within a [Group](/sdk/reference/entities#group). + ```typescript let GUID: string = "GUID"; @@ -43,41 +42,42 @@ CometChat.updateGroupMemberScope(GUID, UID, CometChat.GroupMemberScope.Admin).th + +```javascript +let GUID = "GUID"; +let UID = "UID"; +let scope = CometChat.GROUP_MEMBER_SCOPE.ADMIN; + +CometChat.updateGroupMemberScope(GUID, UID, scope).then( +response => { + console.log("Group member scopped changed", response); +}, error => { + console.log("Group member scopped changed failed", error); +} +); +``` + + + This method takes the below parameters: | Parameter | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `UID` | The UID of the member whose scope you would like to change | -| `GUID` | The GUID of the group for which the member's scope needs to be changed | -| `scope` | The updated scope of the member. This can be either of the 3 values: 1.`CometChat.SCOPE.ADMIN`2.`CometChat.SCOPE.MODERATOR` 3.`CometChat.SCOPE.PARTICIPANT` | +| `UID` | The UID of the member whose scope you want to change | +| `GUID` | The GUID of the group | +| `scope` | The new scope: `CometChat.SCOPE.ADMIN`, `CometChat.SCOPE.MODERATOR`, or `CometChat.SCOPE.PARTICIPANT` | -The default scope of any member is `participant`. Only the **Admin** of the group can change the scope of any participant in the group. +The default scope is `participant`. Only Admins can change member scopes. -## Real-Time Group Member Scope Changed Events +On success, the method resolves with a success message string. -*In other words, as a member of a group, how do I know when someone's scope is changed when my app is running?* +## Real-Time Group Member Scope Changed Events -In order to receive real-time events for the change member scope event, you will need to override the `onGroupMemberScopeChanged()` method of the `GroupListener` class +Implement `onGroupMemberScopeChanged()` in `GroupListener` to receive real-time notifications when a member's scope changes. - -```javascript -let listenerID = "UNIQUE_LISTENER_ID"; - -CometChat.addGroupListener( -listenerID, -new CometChat.GroupListener({ - onGroupMemberScopeChanged: (message, changedUser, newScope, oldScope, changedGroup) => { - console.log("User joined", {message, changedUser, newScope, oldScope, changedGroup}); - } -}) -); -``` - - - ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; @@ -94,19 +94,60 @@ CometChat.addGroupListener( + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; + +CometChat.addGroupListener( +listenerID, +new CometChat.GroupListener({ + onGroupMemberScopeChanged: (message, changedUser, newScope, oldScope, changedGroup) => { + console.log("User joined", {message, changedUser, newScope, oldScope, changedGroup}); + } +}) +); +``` + + + + +Always remove group listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + +```javascript +CometChat.removeGroupListener("UNIQUE_LISTENER_ID"); +``` + + ## Missed Group Member Scope Changed Events -*In other words, as a member of a group, how do I know when someone's scope is changed when my app is not running?* +When fetching previous messages, scope changes appear as [Action](/sdk/reference/messages#action) messages (a subclass of `BaseMessage`). -When you retrieve the list of previous messages if a member's scope has been changed for any group that the logged-in user is a member of, the list of messages will contain an `Action` message. An `Action` message is a sub-class of `BaseMessage` class. +| Field | Value/Type | Description | +|-------|------------|-------------| +| `action` | `"scopeChanged"` | The action type | +| `actionOn` | [User](/sdk/reference/entities#user) | The user whose scope changed | +| `actionBy` | [User](/sdk/reference/entities#user) | The user who changed the scope | +| `actionFor` | [Group](/sdk/reference/entities#group) | The group | +| `oldScope` | `string` | The previous scope | +| `newScope` | `string` | The new scope | -For the group member scope changed event, in the `Action` object received, the following fields can help you get the relevant information- +--- -1. `action` - `scopeChanged` -2. `actionOn` - User object containing the details of the user whose scope has been changed -3. `actionBy` - User object containing the details of the user who changed the scope of the member -4. `actionFor` - Group object containing the details of the group in which the member scope was changed -5. `oldScope` - The original scope of the member -6. `newScope` - The updated scope of the member +## Next Steps + + + + Transfer ownership of a group to another member + + + Remove or ban members from a group + + + Add new members to a group + + + Fetch the list of members in a group + + diff --git a/sdk/javascript/group-kick-ban-members.mdx b/sdk/javascript/group-kick-ban-members.mdx index 7433686cd..4050f3a31 100644 --- a/sdk/javascript/group-kick-ban-members.mdx +++ b/sdk/javascript/group-kick-ban-members.mdx @@ -1,8 +1,27 @@ --- title: "Ban Or Kick Member From A Group" +sidebarTitle: "Kick & Ban Members" +description: "Learn how to kick, ban, and unban group members, fetch banned member lists, and receive real-time events using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Kick a member +await CometChat.kickGroupMember("GUID", "UID"); + +// Ban a member +await CometChat.banGroupMember("GUID", "UID"); + +// Unban a member +await CometChat.unbanGroupMember("GUID", "UID"); + +// Fetch banned members +const request = new CometChat.BannedMembersRequestBuilder("GUID").setLimit(30).build(); +const bannedMembers = await request.fetchNext(); +``` + There are certain actions that can be performed on the group members: @@ -11,36 +30,20 @@ There are certain actions that can be performed on the group members: 3. Unban a member from the group 4. Update the scope of the member of the group -All the above actions can only be performed by the **Admin** or the **Moderator** of the group. +Only Admins or Moderators can perform these actions. ## Kick a Group Member -The Admin or Moderator of a group can kick a member out of the group using the `kickGroupMember()` method. +Admins or Moderators can remove a member using `kickGroupMember()`. The kicked user can rejoin the group later. - -```javascript -var GUID = "GUID"; -var UID = "UID"; - -CometChat.kickGroupMember(GUID, UID).then( -response => { - console.log("Group member kicked successfully", response); -}, error => { - console.log("Group member kicking failed with error", error); -} -); -``` - - - ```typescript let GUID: string = "GUID"; let UID: string = "UID"; CometChat.kickGroupMember(GUID, UID).then( - (response: Object) => { + (response: boolean) => { console.log("Group member kicked successfully", response); }, (error: CometChat.CometChatException) => { console.log("Group member kicking failed with error", error); @@ -61,34 +64,52 @@ The `kickGroupMember()` takes following parameters The kicked user will be no longer part of the group and can not perform any actions in the group, but the kicked user can rejoin the group. +On success, the method resolves with a `boolean` value (`true`) confirming the operation. + ## Ban a Group Member The Admin or Moderator of the group can ban a member from the group using the `banGroupMember()` method. - + ```javascript -var GUID = "GUID"; -var UID = "UID"; +const GUID = "GUID"; +const UID = "UID"; -CometChat.banGroupMember(GUID, UID).then( +CometChat.kickGroupMember(GUID, UID).then( response => { - console.log("Group member banned successfully", response); + console.log("Group member kicked successfully", response); }, error => { - console.log("Group member banning failed with error", error); + console.log("Group member kicking failed with error", error); } -); +); ``` + + +The `kickGroupMember()` method takes the following parameters: + +| Parameter | Description | +| --------- | ----------------------------------------------------- | +| `UID` | The UID of the user to be kicked | +| `GUID` | The GUID of the group from which user is to be kicked | + +On success, the method resolves with a success message string. + +## Ban a Group Member + +Admins or Moderators can ban a member using `banGroupMember()`. Unlike kicked users, banned users cannot rejoin until unbanned. + + ```typescript let GUID: string = "GUID"; let UID: string = "UID"; CometChat.banGroupMember(GUID, UID).then( - (response: Object) => { + (response: boolean) => { console.log("Group member banned successfully", response); }, (error: CometChat.CometChatException) => { console.log("Group member banning failed with error", error); @@ -98,45 +119,47 @@ CometChat.banGroupMember(GUID, UID).then( + +```javascript +const GUID = "GUID"; +const UID = "UID"; + +CometChat.banGroupMember(GUID, UID).then( +response => { + console.log("Group member banned successfully", response); +}, error => { + console.log("Group member banning failed with error", error); +} +); +``` + + + The `banGroupMember()` method takes the following parameters: | Parameter | Description | | --------- | ------------------------------------------------------ | -| `UID` | The UID of the user to be banned. | -| `GUID` | The GUID of the group from which user is to be banned. | +| `UID` | The UID of the user to be banned | +| `GUID` | The GUID of the group from which user is to be banned | The banned user will be no longer part of the group and can not perform any actions in the group. A banned user cannot rejoin the same group without being unbanned. +On success, the method resolves with a `boolean` value (`true`) confirming the operation. + ## Unban a Banned Group Member from a Group -Only Admin or Moderators of the group can unban a previously banned member from the group using the `unbanGroupMember()` method. +Admins or Moderators can unban a previously banned member using `unbanGroupMember()`. - -```javascript -var GUID = "GUID"; -var UID = "UID"; - -CometChat.unbanGroupMember(GUID, UID).then( -response => { - console.log("Group member unbanned successfully", response); -}, error => { - console.log("Group member unbanning failed with error", error); -} -); -``` - - - ```typescript let GUID: string = "GUID"; let UID: string = "UID"; CometChat.unbanGroupMember(GUID, UID).then( - (response: Object) => { + (response: boolean) => { console.log("Group member unbanned successfully", response); }, (error: CometChat.CometChatException) => { console.log("Group member unbanning failed with error", error); @@ -146,41 +169,44 @@ CometChat.unbanGroupMember(GUID, UID).then( + +```javascript +const GUID = "GUID"; +const UID = "UID"; + +CometChat.unbanGroupMember(GUID, UID).then( +response => { + console.log("Group member unbanned successfully", response); +}, error => { + console.log("Group member unbanning failed with error", error); +} +); +``` + + + The `unbanGroupMember()` method takes the following parameters | Parameter | Description | | --------- | ---------------------------------------------------- | -| `UID` | The UID of the user to be unbanned. | -| `GUID` | The UID of the group from which user is to be banned | +| `UID` | The UID of the user to be unbanned | +| `GUID` | The GUID of the group from which user is to be unbanned | -The unbanned user can now rejoin the group. +Once unbanned, the user can rejoin the group. -## Get List of Banned Members for a Group - -In order to fetch the list of banned groups members for a group, you can use the `BannedGroupMembersRequest` class. To use this class i.e to create an object of the BannedGroupMembersRequest class, you need to use the `BannedGroupMembersRequestBuilder` class. The `BannedGroupMembersRequestBuilder` class allows you to set the parameters based on which the banned group members are to be fetched. +On success, the method resolves with a `boolean` value (`true`) confirming the operation. -The `BannedGroupMembersRequestBuilder` class allows you to set the below parameters: +## Get List of Banned Members for a Group -The `GUID` of the group for which the banned members are to be fetched must be specified in the constructor of the `GroupMembersRequestBuilder` class. +Use `BannedMembersRequestBuilder` to fetch banned members of a [Group](/sdk/reference/entities#group). The GUID must be specified in the constructor. ### Set Limit -This method sets the limit i.e. the number of banned members that should be fetched in a single iteration. +Sets the number of banned members to fetch per request. - -```javascript -let GUID = "GUID"; -let limit = 30; -let bannedGroupMembersRequest = new CometChat.BannedMembersRequestBuilder(GUID) - .setLimit(limit) - .build(); -``` - - - ```typescript let GUID: string = "GUID"; @@ -192,26 +218,24 @@ let bannedGroupMembersRequest: CometChat.BannedMembersRequest = new CometChat.Ba - - -### Set Search Keyword - -This method allows you to set the search string based on which the banned group members are to be fetched. - - - + ```javascript let GUID = "GUID"; let limit = 30; -let searchKeyword = "super"; let bannedGroupMembersRequest = new CometChat.BannedMembersRequestBuilder(GUID) .setLimit(limit) - .setSearchKeyword(searchKeyword) .build(); ``` + + +### Set Search Keyword + +Filters banned members by a search string. + + ```typescript let GUID: string = "GUID"; @@ -225,32 +249,24 @@ let bannedGroupMembersRequest: CometChat.BannedMembersRequest = new CometChat.Ba - - -Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the `BannedGroupMembersRequest` class. - -Once you have the object of the `BannedGroupMembersRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of `GroupMember` objects containing n number of banned members where n is the limit set in the builder class. - - - + ```javascript let GUID = "GUID"; let limit = 30; -let bannedMembersRequest = new CometChat.BannedMembersRequestBuilder(GUID) - .setLimit(limit) - .build(); - -bannedMembersRequest.fetchNext().then( -bannedMembers => { - console.log("Banned Group Member list fetched successfully:", bannedMembers); -}, error => { - console.log("Banned Group Member list fetching failed with exception:", error); -} -); +let searchKeyword = "super"; +let bannedGroupMembersRequest = new CometChat.BannedMembersRequestBuilder(GUID) + .setLimit(limit) + .setSearchKeyword(searchKeyword) + .build(); ``` + + +Once configured, call `build()` to create the request, then `fetchNext()` to retrieve banned members. + + ```typescript let GUID: string = "GUID"; @@ -272,6 +288,8 @@ bannedGroupMembersRequest.fetchNext().then( +The `fetchNext()` method returns an array of [`GroupMember`](/sdk/reference/entities#groupmember) objects representing the banned members of the group. + ## Real-Time Group Member Kicked/Banned Events *In other words, as a member of a group, how do I know when someone is banned/kicked when my app is running?* @@ -283,28 +301,38 @@ In order to get real-time events for the kick/ban/unban group members you need t 3. `onGroupMemberUnbanned()` - triggered when any group member has been unbanned. - + ```javascript -let listenerID = "UNIQUE_LISTENER_ID"; +let GUID = "GUID"; +let limit = 30; +let bannedMembersRequest = new CometChat.BannedMembersRequestBuilder(GUID) + .setLimit(limit) + .build(); -CometChat.addGroupListener( -listenerID, -new CometChat.GroupListener({ - onGroupMemberKicked: (message, kickedUser, kickedBy, kickedFrom) => { - console.log("User kicked", { message, kickedUser, kickedBy, kickedFrom }); - }, - onGroupMemberBanned: (message, bannedUser, bannedBy, bannedFrom) => { - console.log("User banned", { message, bannedUser, bannedBy, bannedFrom }); - }, - onGroupMemberUnbanned: (message, unbannedUser, unbannedBy,unbannedFrom) => { - console.log("User unbanned", {message, unbannedUser, unbannedBy, unbannedFrom}); - } -}) -); +bannedMembersRequest.fetchNext().then( +bannedMembers => { + console.log("Banned Group Member list fetched successfully:", bannedMembers); +}, error => { + console.log("Banned Group Member list fetching failed with exception:", error); +} +); ``` + + +## Real-Time Group Member Kicked/Banned Events + +Implement these `GroupListener` methods to receive real-time notifications: + +| Method | Triggered When | +|--------|----------------| +| `onGroupMemberKicked()` | A member is kicked | +| `onGroupMemberBanned()` | A member is banned | +| `onGroupMemberUnbanned()` | A member is unbanned | + + ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; @@ -327,31 +355,84 @@ CometChat.addGroupListener( + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; + +CometChat.addGroupListener( +listenerID, +new CometChat.GroupListener({ + onGroupMemberKicked: (message, kickedUser, kickedBy, kickedFrom) => { + console.log("User kicked", { message, kickedUser, kickedBy, kickedFrom }); + }, + onGroupMemberBanned: (message, bannedUser, bannedBy, bannedFrom) => { + console.log("User banned", { message, bannedUser, bannedBy, bannedFrom }); + }, + onGroupMemberUnbanned: (message, unbannedUser, unbannedBy,unbannedFrom) => { + console.log("User unbanned", {message, unbannedUser, unbannedBy, unbannedFrom}); + } +}) +); +``` + + + + +Always remove group listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + +```javascript +CometChat.removeGroupListener("UNIQUE_LISTENER_ID"); +``` + + ## Missed Group Member Kicked/Banned Events -*In other words, as a member of a group, how do I know when someone is banned/kicked when my app is not running?* +When fetching previous messages, kick/ban/unban actions appear as [Action](/sdk/reference/messages#action) messages (a subclass of `BaseMessage`). + +**Kicked event:** -When you retrieve the list of previous messages if a member has been kicked/banned/unbanned from any group that the logged-in user is a member of, the list of messages will contain an `Action` message. An `Action` message is a sub-class of `BaseMessage` class. +| Field | Value/Type | Description | +|-------|------------|-------------| +| `action` | `"kicked"` | The action type | +| `actionBy` | [User](/sdk/reference/entities#user) | The user who kicked the member | +| `actionOn` | [User](/sdk/reference/entities#user) | The member who was kicked | +| `actionFor` | [Group](/sdk/reference/entities#group) | The group | -For group member kicked event, the details can be obtained using the below fields of the `Action` class- +**Banned event:** -1. `action` - `kicked` -2. `actionBy` - User object containing the details of the user who has kicked the member -3. `actionOn` - User object containing the details of the member that has been kicked -4. `actionFor` - Group object containing the details of the Group from which the member was kicked +| Field | Value/Type | Description | +|-------|------------|-------------| +| `action` | `"banned"` | The action type | +| `actionBy` | [User](/sdk/reference/entities#user) | The user who banned the member | +| `actionOn` | [User](/sdk/reference/entities#user) | The member who was banned | +| `actionFor` | [Group](/sdk/reference/entities#group) | The group | -For group member banned event, the details can be obtained using the below fields of the `Action` class- +**Unbanned event:** -1. `action` - `banned` -2. `actionBy` - User object containing the details of the user who has banned the member -3. `actionOn` - User object containing the details of the member that has been banned -4. `actionFor` - Group object containing the details of the Group from which the member was banned +| Field | Value/Type | Description | +|-------|------------|-------------| +| `action` | `"unbanned"` | The action type | +| `actionBy` | [User](/sdk/reference/entities#user) | The user who unbanned the member | +| `actionOn` | [User](/sdk/reference/entities#user) | The member who was unbanned | +| `actionFor` | [Group](/sdk/reference/entities#group) | The group | -For group member unbanned event, the details can be obtained using the below fields of the `Action` class- +--- -1. `action` - `unbanned` -2. `actionBy` - User object containing the details of the user who has unbanned the member -3. `actionOn` - User object containing the details of the member that has been unbanned -4. `actionFor` - Group object containing the details of the Group from which the member was unbanned +## Next Steps + + + + Add new members to a group + + + Promote or demote group members + + + Fetch the list of members in a group + + + Allow members to leave a group + + diff --git a/sdk/javascript/groups-overview.mdx b/sdk/javascript/groups-overview.mdx index 4f3d1c363..df477b297 100644 --- a/sdk/javascript/groups-overview.mdx +++ b/sdk/javascript/groups-overview.mdx @@ -1,10 +1,59 @@ --- title: "Groups" sidebarTitle: "Overview" +description: "Overview of group management in the CometChat JavaScript SDK including group types, member roles, and available operations." --- + +| Field | Value | +| --- | --- | +| Package | `@cometchat/chat-sdk-javascript` | +| Key Classes | `CometChat.Group` | +| Group Types | `PUBLIC`, `PRIVATE`, `PASSWORD` | +| Member Roles | `owner`, `admin`, `moderator`, `participant` | +| Key Methods | `createGroup()`, `joinGroup()`, `leaveGroup()`, `deleteGroup()` | +| Prerequisites | SDK initialized, user logged in | +| Related | [Create Group](/sdk/javascript/create-group), [Join Group](/sdk/javascript/join-group), [Retrieve Groups](/sdk/javascript/retrieve-groups) | + + Groups help your users to converse together in a single space. You can have three types of groups- private, public and password protected. Each group includes three kinds of users- owner, moderator, member. + +## Group Types + +| Type | Description | Join Behavior | +|------|-------------|---------------| +| **Public** | Open to all users | Any user can join without approval | +| **Private** | Invite-only | Users must be added by admin/moderator | +| **Password** | Protected by password | Users must provide correct password to join | + +## Member Roles + +| Role | Permissions | +|------|-------------| +| **Owner** | Full control: manage members, settings, delete group. Cannot leave without transferring ownership. | +| **Admin** | Manage members (add, kick, ban), change member scope, update group settings | +| **Moderator** | Kick and ban members, moderate content | +| **Member** | Send/receive messages, leave group | + +--- + +## Next Steps + + + + Create public, private, or password-protected groups + + + Join existing groups as a participant + + + Fetch and filter the list of groups + + + Get the member list for a group + + diff --git a/sdk/javascript/initialization.mdx b/sdk/javascript/initialization.mdx new file mode 100644 index 000000000..f66032036 --- /dev/null +++ b/sdk/javascript/initialization.mdx @@ -0,0 +1,167 @@ +--- +title: "Initialization" +description: "Configure and initialize the CometChat JavaScript SDK with your App ID and settings." +--- + +The `init()` method initializes the SDK and must be called before any other CometChat method. Call it once at app startup, typically in your entry file (`index.js`, `main.js`, or `App.js`). + +## Basic Initialization + + + +```typescript +let appID: string = "APP_ID"; +let region: string = "APP_REGION"; + +let appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .autoEstablishSocketConnection(true) + .build(); + +CometChat.init(appID, appSetting).then( + (initialized: boolean) => { + console.log("Initialization completed successfully", initialized); + }, + (error: CometChat.CometChatException) => { + console.log("Initialization failed with error:", error); + } +); +``` + + + + +```javascript +let appID = "APP_ID"; +let region = "APP_REGION"; + +let appSetting = new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .autoEstablishSocketConnection(true) + .build(); + +CometChat.init(appID, appSetting).then( + () => { + console.log("Initialization completed successfully"); + }, + (error) => { + console.log("Initialization failed with error:", error); + } +); +``` + + + + +```javascript +let appID = "APP_ID"; +let region = "APP_REGION"; + +let appSetting = new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .autoEstablishSocketConnection(true) + .build(); + +try { + await CometChat.init(appID, appSetting); + console.log("Initialization completed successfully"); +} catch (error) { + console.log("Initialization failed with error:", error); +} +``` + + + + + +Replace `APP_ID` with your CometChat App ID and `APP_REGION` with your Region from the [Dashboard](https://app.cometchat.com). + + +`CometChat.init()` must be called before any other SDK method. Calling `login()`, `sendMessage()`, or registering listeners before `init()` will fail. + + +## Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| appID | string | Your CometChat App ID | +| appSetting | AppSettings | Configuration object built with AppSettingsBuilder | + +## AppSettings Options + +| Method | Description | Default | +|--------|-------------|---------| +| `setRegion(region)` | Region where your app was created (`us`, `eu`, `in`, `in-private`) | Required | +| `subscribePresenceForAllUsers()` | Subscribe to presence events for all users | — | +| `subscribePresenceForRoles(roles)` | Subscribe to presence for specific roles | — | +| `subscribePresenceForFriends()` | Subscribe to presence for friends only | — | +| `autoEstablishSocketConnection(bool)` | Let SDK manage WebSocket connections | `true` | +| `overrideAdminHost(adminHost)` | Custom admin URL (dedicated deployment) | — | +| `overrideClientHost(clientHost)` | Custom client URL (dedicated deployment) | — | +| `setStorageMode(storageMode)` | Local storage mode (`CometChat.StorageMode.SESSION` for session storage) | — | + +### Presence Subscription + +Choose how to subscribe to user presence (online/offline status): + +```javascript +// All users +new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .build(); + +// Specific roles +new CometChat.AppSettingsBuilder() + .subscribePresenceForRoles(["admin", "moderator"]) + .setRegion(region) + .build(); + +// Friends only +new CometChat.AppSettingsBuilder() + .subscribePresenceForFriends() + .setRegion(region) + .build(); +``` + +See [User Presence](/sdk/javascript/user-presence) for more details. + +### WebSocket Connection + +By default, the SDK manages WebSocket connections automatically. To manage them manually: + +```javascript +let appSetting = new CometChat.AppSettingsBuilder() + .setRegion(region) + .autoEstablishSocketConnection(false) + .build(); +``` + +See [Managing WebSocket Connections](/sdk/javascript/managing-web-sockets-connections-manually) for manual control. + +### Session Storage + +Use session storage instead of local storage (data clears when browser closes): + +```javascript +let appSetting = new CometChat.AppSettingsBuilder() + .setRegion(region) + .setStorageMode(CometChat.StorageMode.SESSION) + .build(); +``` + +--- + +## Next Steps + + + + Log in users with Auth Key or Auth Token + + + Setup for Next.js, Nuxt, and Ionic + + diff --git a/sdk/javascript/installation.mdx b/sdk/javascript/installation.mdx new file mode 100644 index 000000000..c0ece3d34 --- /dev/null +++ b/sdk/javascript/installation.mdx @@ -0,0 +1,59 @@ +--- +title: "Installation" +description: "Add the CometChat JavaScript SDK to your project using npm or CDN." +--- + +## Package Manager + +Install the SDK using npm: + +```bash +npm install @cometchat/chat-sdk-javascript +``` + +Then import the `CometChat` object wherever you need it: + +```javascript +import { CometChat } from "@cometchat/chat-sdk-javascript"; +``` + +## CDN + +Include the CometChat JavaScript library directly in your HTML: + +```html + +``` + +When using the CDN, `CometChat` is available as a global variable. + +## Get Your Credentials + +Before initializing the SDK, get your credentials from the [CometChat Dashboard](https://app.cometchat.com): + +1. Sign up or log in +2. Create a new app (or use an existing one) +3. Go to **API & Auth Keys** and note your: + - App ID + - Region + - Auth Key + + +**Auth Key** is for development/testing only. In production, generate **Auth Tokens** on your server using the REST API. Never expose Auth Keys in production client code. + + +--- + +## Next Steps + + + + Configure and initialize the SDK + + + Setup for Next.js, Nuxt, and Ionic + + diff --git a/sdk/javascript/interactive-messages.mdx b/sdk/javascript/interactive-messages.mdx index 2f083f734..b7890c99b 100644 --- a/sdk/javascript/interactive-messages.mdx +++ b/sdk/javascript/interactive-messages.mdx @@ -1,203 +1,544 @@ --- title: "Interactive Messages" +sidebarTitle: "Interactive Messages" +description: "Send and receive interactive messages with embedded forms, buttons, and other UI elements using the CometChat JavaScript SDK." --- + + +| Component | Description | +| --- | --- | +| `InteractiveMessage` | Message containing interactive UI elements (forms, buttons, etc.) | +| `InteractionGoal` | Defines the desired outcome of user interactions | +| `Interaction` | Represents a single user action on an interactive element | + +```javascript +// Create and send an interactive form +const interactiveMessage = new CometChat.InteractiveMessage( + receiverId, + receiverType, + "form", + interactiveData +); +await CometChat.sendInteractiveMessage(interactiveMessage); +// Listen for interactive messages +CometChat.addMessageListener("LISTENER_ID", new CometChat.MessageListener({ + onInteractiveMessageReceived: (message) => console.log("Received:", message), + onInteractionGoalCompleted: (receipt) => console.log("Goal completed:", receipt) +})); +``` + -An InteractiveMessage is a specialised object that encapsulates an interactive unit within a chat message, such as an embedded form that users can fill out directly within the chat interface. This enhances user engagement by making the chat experience more interactive and responsive to user input. +Interactive messages embed UI elements like forms, buttons, and dropdowns directly within chat messages. Users can interact with these elements without leaving the conversation, enabling surveys, quick actions, and data collection. ## InteractiveMessage -`InteractiveMessage` is a chat message with embedded interactive content. It can contain various properties: +The [`InteractiveMessage`](/sdk/reference/messages#interactivemessage) class represents a message with embedded interactive content. -| Parameter | Description | Required | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -| receiverId | The UID or GUID of the recipient | Yes | -| receiverType | The type of the receiver to whom the message is to be sent i.e CometChatConstants.RECEIVER\_TYPE\_USER (user) or CometChatConstants.RECEIVER\_TYPE\_GROUP (group) | Yes | -| messageType | The type of the message that needs to be sent | Yes | -| interactiveData | A JSONObject holding structured data for the interactive element. | Yes | -| allowSenderInteraction | A boolean determining whether the message sender can interact with the message by default it is set to false. | Optional (Default: false) | -| interactionGoal | An InteractionGoal object encapsulating the intended outcome of interacting with the InteractiveMessage by default it is set to none | Optional (Default: none) | +| Parameter | Type | Description | Required | +| --- | --- | --- | --- | +| `receiverId` | `string` | UID of user or GUID of group | Yes | +| `receiverType` | `string` | `CometChat.RECEIVER_TYPE.USER` or `GROUP` | Yes | +| `messageType` | `string` | Type identifier (e.g., `"form"`, `"card"`) | Yes | +| `interactiveData` | `Object` | JSON structure defining the interactive elements | Yes | +| `allowSenderInteraction` | `boolean` | Whether sender can interact with the message | No (default: `false`) | +| `interactionGoal` | `InteractionGoal` | Defines when the interaction is considered complete | No (default: `none`) | -## Interaction +## Send an Interactive Message -An `Interaction` represents a user action involved with an `InteractiveMessage`. It includes: +Use `sendInteractiveMessage()` to send an interactive message. -* `elementId`: An identifier for a specific interactive element. -* `interactedAt`: A timestamp indicating when the interaction occurred. + + +```typescript +let receiverId: string = "UID"; +let receiverType: string = CometChat.RECEIVER_TYPE.USER; + +let interactiveData: Object = { + title: "Survey", + formFields: [ + { + elementType: "textInput", + elementId: "name", + optional: false, + label: "Name", + placeholder: { text: "Enter your name" } + }, + { + elementType: "textInput", + elementId: "age", + optional: true, + label: "Age", + maxLines: 1, + placeholder: { text: "Enter your age" } + }, + { + elementType: "dropdown", + elementId: "gender", + optional: false, + label: "Gender", + defaultValue: "male", + options: [ + { label: "Male", value: "male" }, + { label: "Female", value: "female" } + ] + }, + { + elementType: "Select", + elementId: "interests", + optional: true, + label: "Interests", + defaultValue: ["tech"], + options: [ + { label: "Technology", value: "tech" }, + { label: "Sports", value: "sports" }, + { label: "Music", value: "music" } + ] + } + ], + submitElement: { + elementType: "button", + elementId: "submitButton", + buttonText: "Submit", + disableAfterInteracted: true, + action: { + actionType: "urlNavigation", + url: "https://www.cometchat.com/" + } + } +}; -## Goal Completion +let interactiveMessage: CometChat.InteractiveMessage = new CometChat.InteractiveMessage( + receiverId, + receiverType, + "form", + interactiveData +); -A key feature of `InteractiveMessage` is checking whether a user's interactions with the message meet the defined `InteractionGoal` +CometChat.sendInteractiveMessage(interactiveMessage).then( + (message: CometChat.InteractiveMessage) => { + console.log("Interactive message sent successfully", message); + }, + (error: CometChat.CometChatException) => { + console.log("Interactive message sending failed with error:", error); + } +); +``` + + +```javascript +let receiverId = "UID"; +let receiverType = CometChat.RECEIVER_TYPE.USER; + +let interactiveData = { + title: "Survey", + formFields: [ + { + elementType: "textInput", + elementId: "name", + optional: false, + label: "Name", + placeholder: { text: "Enter your name" } + }, + { + elementType: "textInput", + elementId: "age", + optional: true, + label: "Age", + maxLines: 1, + placeholder: { text: "Enter your age" } + }, + { + elementType: "dropdown", + elementId: "gender", + optional: false, + label: "Gender", + defaultValue: "male", + options: [ + { label: "Male", value: "male" }, + { label: "Female", value: "female" } + ] + }, + { + elementType: "Select", + elementId: "interests", + optional: true, + label: "Interests", + defaultValue: ["tech"], + options: [ + { label: "Technology", value: "tech" }, + { label: "Sports", value: "sports" }, + { label: "Music", value: "music" } + ] + } + ], + submitElement: { + elementType: "button", + elementId: "submitButton", + buttonText: "Submit", + disableAfterInteracted: true, + action: { + actionType: "urlNavigation", + url: "https://www.cometchat.com/" + } + } +}; -You would be tracking every interaction users perform on an `InteractiveMessage` (captured as `Interaction` objects) and comparing those with the defined `InteractionGoal`. The completion of a goal can vary depending on the goal type: +let interactiveMessage = new CometChat.InteractiveMessage( + receiverId, + receiverType, + "form", + interactiveData +); -| Goals | Description | Keys | -| -------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------- | -| **Any Interaction** | The goal is considered completed if there is at least one interaction. | CometChatConstants.INTERACTION\_TYPE\_ANY | -| **Any of Specific Interactions** | The goal is achieved if any of the specified interactions occurred. | CometChatConstants.INTERACTION\_TYPE\_ANY\_OF | -| **All of Specific Interactions** | The goal is completed when all specified interactions occur. | CometChatConstants.INTERACTION\_TYPE\_ALL\_OF | -| **None** | The goal is never completed. | CometChatConstants.INTERACTION\_TYPE\_NONE | +CometChat.sendInteractiveMessage(interactiveMessage).then( + (message) => { + console.log("Interactive message sent successfully", message); + }, + (error) => { + console.log("Interactive message sending failed with error:", error); + } +); +``` + + -This user interaction tracking mechanism provides a flexible and efficient way to monitor user engagement within an interactive chat session. By defining clear interaction goals and checking user interactions against these goals, you can manage user engagement and improve the overall chat experience in your CometChat-enabled application. +The `sendInteractiveMessage()` method returns an [`InteractiveMessage`](/sdk/reference/messages#interactivemessage) object. -## InteractionGoal +## Interactive Elements -The `InteractionGoal` represents the desired outcome of an interaction with an `InteractiveMessage`. It includes: +The `interactiveData` object defines the UI elements. Common element types: -* `elementIds`: A list of identifiers for the interactive elements. -* `type`: The type of interaction goal from the `CometChatConstants`. +| Element Type | Description | +| --- | --- | +| `textInput` | Single or multi-line text field | +| `dropdown` | Single-select dropdown menu | +| `Select` | Multi-select checkbox group | +| `button` | Clickable button with action | -## Sending InteractiveMessages +### Text Input -The `InteractiveMessage` can be sent using the `sendInteractiveMessage` method of the `CometChat` class. The method requires an `InteractiveMessage` object and a `CallbackListener` for handling the response. +```javascript +{ + elementType: "textInput", + elementId: "name", + optional: false, + label: "Name", + maxLines: 1, // Optional: limit to single line + placeholder: { text: "Enter text here" } +} +``` -Here is an example of how to use it: +### Dropdown (Single Select) + +```javascript +{ + elementType: "dropdown", + elementId: "country", + optional: false, + label: "Country", + defaultValue: "us", + options: [ + { label: "United States", value: "us" }, + { label: "United Kingdom", value: "uk" }, + { label: "Canada", value: "ca" } + ] +} +``` - - -```js -const interactiveData = { -title: "Survey", -formFields: [ - { - elementType: "textInput", - elementId: "name", - optional: false, - label: "Name", - placeholder: { - text: "Enter text here" - } - }, - { - elementType: "textInput", - elementId: "age", - optional: true, - label: "Age", - maxLines: 1, - placeholder: { - text: "Enter text here" - } - }, - { - elementType: "Select", - elementId: "checkBox1", - optional: true, - label: "Check box element", - defaultValue: ["chk_option_2"], - options: [ - { - label: "Option 1", - value: "chk_option_1" - }, - { - label: "Option 2", - value: "chk_option_2" - } - ] - }, - { - elementType: "dropdown", - elementId: "gender", - optional: false, - label: "Gender", - defaultValue: "male", - options: [ - { - label: "Male", - value: "male" - }, - { - label: "Female", - value: "female" - } - ] - } -], -submitElement: { +### Checkbox (Multi Select) + +```javascript +{ + elementType: "Select", + elementId: "preferences", + optional: true, + label: "Preferences", + defaultValue: ["email"], + options: [ + { label: "Email notifications", value: "email" }, + { label: "SMS notifications", value: "sms" }, + { label: "Push notifications", value: "push" } + ] +} +``` + +### Submit Button + +```javascript +{ elementType: "button", - elementId: "submitButton", + elementId: "submitBtn", buttonText: "Submit", - disableAfterInteracted: false, + disableAfterInteracted: true, action: { actionType: "urlNavigation", - url: "https://www.cometchat.com/" + url: "https://example.com/submit" } } -}; +``` +## Interaction Goals +An `InteractionGoal` defines when the user's interaction with the message is considered complete. Use this to track engagement and trigger follow-up actions. -const interactiveMessage = new CometChat.InteractiveMessage(receiverId,receiverType,"form", interactiveData); +| Goal Type | Constant | Description | +| --- | --- | --- | +| Any Interaction | `CometChat.GoalType.ANY_ACTION` | Complete when any element is interacted with | +| Any of Specific | `CometChat.GoalType.ANY_OF` | Complete when any of the specified elements is interacted with | +| All of Specific | `CometChat.GoalType.ALL_OF` | Complete when all specified elements are interacted with | +| None | `CometChat.GoalType.NONE` | Never considered complete (default) | +### Set an Interaction Goal -CometChat.sendInteractiveMessage(interactiveMessage) - .then((message: CometChat.InteractiveMessage) => { - // This block is executed when the InteractiveMessage is sent successfully. - }) - .catch((error: CometChat.CometChatException) => { - // This block is executed if an error occurs while sending the InteractiveMessage. - }); -``` + + +```typescript +let elementIds: Array = ["name", "gender", "submitButton"]; +let interactionGoal: CometChat.InteractionGoal = new CometChat.InteractionGoal( + CometChat.GoalType.ALL_OF, + elementIds +); +let interactiveMessage: CometChat.InteractiveMessage = new CometChat.InteractiveMessage( + receiverId, + receiverType, + "form", + interactiveData +); +interactiveMessage.setInteractionGoal(interactionGoal); + +CometChat.sendInteractiveMessage(interactiveMessage).then( + (message: CometChat.InteractiveMessage) => { + console.log("Interactive message sent successfully", message); + }, + (error: CometChat.CometChatException) => { + console.log("Interactive message sending failed with error:", error); + } +); +``` + +```javascript +let elementIds = ["name", "gender", "submitButton"]; +let interactionGoal = new CometChat.InteractionGoal( + CometChat.GoalType.ALL_OF, + elementIds +); +let interactiveMessage = new CometChat.InteractiveMessage( + receiverId, + receiverType, + "form", + interactiveData +); +interactiveMessage.setInteractionGoal(interactionGoal); + +CometChat.sendInteractiveMessage(interactiveMessage).then( + (message) => { + console.log("Interactive message sent successfully", message); + }, + (error) => { + console.log("Interactive message sending failed with error:", error); + } +); +``` + -## Event Listeners +## Interactions -CometChat SDK provides event listeners to handle real-time events related to `InteractiveMessage`. +An `Interaction` represents a single user action on an interactive element. -## On InteractiveMessage Received +| Property | Type | Description | +| --- | --- | --- | +| `elementId` | `string` | Identifier of the interacted element | +| `interactedAt` | `number` | Unix timestamp of the interaction | -The `onInteractiveMessageReceived` event listener is triggered when an `InteractiveMessage` is received. +## Mark as Interacted -Here is an example: +Use `markAsInteracted()` to record when a user interacts with an element. + +```typescript +let messageId: number = 123; +let elementId: string = "submitButton"; + +CometChat.markAsInteracted(messageId, elementId).then( + (response: string) => { + console.log("Marked as interacted successfully", response); + }, + (error: CometChat.CometChatException) => { + console.log("Failed to mark as interacted:", error); + } +); +``` + -```js +```javascript +let messageId = 123; +let elementId = "submitButton"; + +CometChat.markAsInteracted(messageId, elementId).then( + (response) => { + console.log("Marked as interacted successfully", response); + }, + (error) => { + console.log("Failed to mark as interacted:", error); + } +); +``` + + + +## Real-Time Events + +Register a `MessageListener` to receive interactive message events. + +### Receive Interactive Messages + + + +```typescript +let listenerID: string = "UNIQUE_LISTENER_ID"; + CometChat.addMessageListener( - "UNIQUE_ID", + listenerID, new CometChat.MessageListener({ - onInteractiveMessageReceived: (message: CometChat.InteractiveMessage) => { - // This block is executed when an InteractiveMessage is received. - // Here you can define logic to handle the received InteractiveMessage and display it in your chat interface. - }, + onInteractiveMessageReceived: (message: CometChat.InteractiveMessage) => { + console.log("Interactive message received", message); + // Render the interactive UI based on message.getInteractiveData() + } }) ); ``` - + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; +CometChat.addMessageListener( + listenerID, + new CometChat.MessageListener({ + onInteractiveMessageReceived: (message) => { + console.log("Interactive message received", message); + // Render the interactive UI based on message.getInteractiveData() + } + }) +); +``` + -On Interaction Goal Completed - -The `onInteractionGoalCompleted` event listener is invoked when an interaction goal is achieved. +### Interaction Goal Completed -Here is an example: +Triggered when a user's interactions satisfy the defined `InteractionGoal`. + +```typescript +let listenerID: string = "UNIQUE_LISTENER_ID"; + +CometChat.addMessageListener( + listenerID, + new CometChat.MessageListener({ + onInteractionGoalCompleted: (receipt: CometChat.InteractionReceipt) => { + console.log("Interaction goal completed", receipt); + // Handle goal completion (e.g., show confirmation, trigger next step) + } + }) +); +``` + -```js +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; + CometChat.addMessageListener( - "UNIQUE_ID", + listenerID, new CometChat.MessageListener({ - onInteractionGoalCompleted: (receipt: CometChat.InteractionReceipt) => { - // This block is executed when an interaction goal is completed. - // Here you can specify the actions your application should take once an interaction goal is achieved, such as updating the UI or notifying the user. - }, + onInteractionGoalCompleted: (receipt) => { + console.log("Interaction goal completed", receipt); + // Handle goal completion (e.g., show confirmation, trigger next step) + } }) ); ``` + + + + +Always remove listeners when they're no longer needed to prevent memory leaks. + +```javascript +CometChat.removeMessageListener("UNIQUE_LISTENER_ID"); +``` + + +## Allow Sender Interaction + +By default, the sender cannot interact with their own interactive message. Enable sender interaction: + + + +```typescript +let interactiveMessage: CometChat.InteractiveMessage = new CometChat.InteractiveMessage( + receiverId, + receiverType, + "form", + interactiveData +); +interactiveMessage.setIsSenderInteractionAllowed(true); +CometChat.sendInteractiveMessage(interactiveMessage).then( + (message: CometChat.InteractiveMessage) => { + console.log("Interactive message sent successfully", message); + }, + (error: CometChat.CometChatException) => { + console.log("Interactive message sending failed with error:", error); + } +); +``` + +```javascript +let interactiveMessage = new CometChat.InteractiveMessage( + receiverId, + receiverType, + "form", + interactiveData +); +interactiveMessage.setIsSenderInteractionAllowed(true); +CometChat.sendInteractiveMessage(interactiveMessage).then( + (message) => { + console.log("Interactive message sent successfully", message); + }, + (error) => { + console.log("Interactive message sending failed with error:", error); + } +); +``` + -These event listeners offer your application a way to provide real-time updates in response to incoming interactive messages and goal completions, contributing to a more dynamic and responsive user chat experience. - -## Usage +--- -An InteractiveMessage is constructed with the receiver's UID, the receiver type, the interactive type, and interactive data as a JSONObject. Once created, the InteractiveMessage can be sent using CometChat's sendInteractiveMessage() method. Incoming InteractiveMessages can be received and processed via CometChat's message listener framework. +## Next Steps + + + + Send text, media, and custom messages + + + Listen for incoming messages in real time + + + Send ephemeral messages that aren't stored + + + Understand message types and hierarchy + + diff --git a/sdk/javascript/join-group.mdx b/sdk/javascript/join-group.mdx index 744f9e723..2d7e85894 100644 --- a/sdk/javascript/join-group.mdx +++ b/sdk/javascript/join-group.mdx @@ -1,34 +1,36 @@ --- title: "Join A Group" +sidebarTitle: "Join Group" +description: "Learn how to join public, password-protected, and private groups, and receive real-time join events using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Join a public group +await CometChat.joinGroup("GUID", CometChat.GROUP_TYPE.PUBLIC, ""); -## Join a Group +// Join a password-protected group +await CometChat.joinGroup("GUID", CometChat.GROUP_TYPE.PASSWORD, "password123"); -In order to start participating in group conversations, you will have to join a group. You can do so using the `joinGroup()` method. +// Listen for member joined events +CometChat.addGroupListener("listener", new CometChat.GroupListener({ + onGroupMemberJoined: (message, joinedUser, joinedGroup) => { } +})); +``` + - - -```javascript -var GUID = "GUID"; -var password = ""; -var groupType = CometChat.GROUP_TYPE.PUBLIC; +Join groups to participate in group conversations and receive real-time events when members join. -CometChat.joinGroup(GUID, groupType, password).then( -group => { - console.log("Group joined successfully:", group); -}, error => { - console.log("Group joining failed with exception:", error); -} -); -``` +## Join a Group - +Use `joinGroup()` to join a group. + ```typescript -var GUID: string = "GUID"; +const GUID: string = "GUID"; CometChat.joinGroup(GUID, CometChat.GroupType.Public).then( (group: CometChat.Group) => { @@ -41,35 +43,46 @@ CometChat.joinGroup(GUID, CometChat.GroupType.Public).then( - + +```javascript +const GUID = "GUID"; +const password = ""; +const groupType = CometChat.GROUP_TYPE.PUBLIC; + +CometChat.joinGroup(GUID, groupType, password).then( +group => { + console.log("Group joined successfully:", group); +}, error => { + console.log("Group joining failed with exception:", error); +} +); +``` -The `joinGroup()` method takes the below parameters + -| Parameter | Description | -| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GUID` | The GUID of the group you would like to join. | -| `groupType` | Type of the group. CometChat provides 3 types of groups viz. 1. CometChat.GROUP\_TYPE.PUBLIC 2. CometChat.GROUP\_TYPE.PASSWORD 3. CometChats.GROUP\_TYPE.PRIVATE | -| `password` | Password is mandatory in case of a password protected group. | + -Once you have joined a group successfully, you can send and receive messages in that group. +| Parameter | Description | +| --------- | ----------- | +| `GUID` | The GUID of the group to join | +| `groupType` | `CometChat.GROUP_TYPE.PUBLIC`, `PASSWORD`, or `PRIVATE` | +| `password` | Required for password-protected groups | -CometChat keeps a track of the groups joined and you do not need to join the group every time you want to communicate in the group. +Once joined, you can send and receive messages in the group. CometChat tracks joined groups — you don't need to rejoin each session. Check `hasJoined` on the `Group` object to verify membership. -You can identify if a group is joined using the `hasJoined` parameter in the `Group` object. +The method returns a [`Group`](/sdk/reference/entities#group) object with `hasJoined` set to `true`. ## Real-time Group Member Joined Events -*In other words, as a member of a group, how do I know if someone joins the group when my app is running?* - -If a user joins any group, the members of the group receive a real-time event in the `onGroupMemberJoined()` method of the `GroupListener` class. +Register a `GroupListener` to receive events when members join. - -```javascript + +```typescript CometChat.addGroupListener( "UNIQUE_LISTNER_ID", new CometChat.GroupListener({ - onGroupMemberJoined: (message, joinedUser, joinedGroup) => { + onGroupMemberJoined: (message: CometChat.Action, joinedUser: CometChat.User, joinedGroup: CometChat.Group) => { console.log("User joined", { message, joinedUser, joinedGroup }); } }) @@ -78,12 +91,12 @@ CometChat.addGroupListener( - -```typescript + +```javascript CometChat.addGroupListener( "UNIQUE_LISTNER_ID", new CometChat.GroupListener({ - onGroupMemberJoined: (message: CometChat.Action, joinedUser: CometChat.User, joinedGroup: CometChat.Group) => { + onGroupMemberJoined: (message, joinedUser, joinedGroup) => { console.log("User joined", { message, joinedUser, joinedGroup }); } }) @@ -94,14 +107,36 @@ CometChat.addGroupListener( -## Missed Group Member Joined Events + +Always remove group listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. -*In other words, as a member of a group, how do I know if someone joins the group when my app is not running?* +```javascript +CometChat.removeGroupListener("UNIQUE_LISTNER_ID"); +``` + -When you retrieve the list of previous messages if a member has joined any group that the logged-in user is a member of, the list of messages will contain an `Action` message. An `Action` message is a sub-class of `BaseMessage` class. +## Missed Group Member Joined Events -For the group member joined event, in the `Action` object received, the following fields can help you get the relevant information- +When fetching message history, join events appear as `Action` messages with: +- `action` — `"joined"` +- `actionBy` — [`User`](/sdk/reference/entities#user) who joined +- `actionFor` — [`Group`](/sdk/reference/entities#group) that was joined + +--- -1. `action` - `joined` -2. `actionBy` - User object containing the details of the user who joined the group -3. `actionFor`- Group object containing the details of the group the user has joined +## Next Steps + + + + Allow members to leave a group + + + Fetch the list of members in a group + + + Send messages to group conversations + + + Programmatically add members to a group + + diff --git a/sdk/javascript/key-concepts.mdx b/sdk/javascript/key-concepts.mdx index 37e5885f1..9a26ab643 100644 --- a/sdk/javascript/key-concepts.mdx +++ b/sdk/javascript/key-concepts.mdx @@ -1,127 +1,151 @@ --- title: "Key Concepts" +description: "Understand the core concepts of CometChat including users, groups, messaging categories, authentication, and member roles." --- + +Key identifiers: +- **UID** — Unique User Identifier (alphanumeric, underscore, hyphen) +- **GUID** — Group Unique Identifier (alphanumeric, underscore, hyphen) +- **Auth Key** — Development-only credential for quick testing +- **Auth Token** — Secure per-user token for production use +- **REST API Key** — Server-side credential, never expose in client code -### CometChat Dashboard +Group types: `Public` | `Password` | `Private` +Member scopes: `Admin` | `Moderator` | `Participant` +Message categories: `message` | `custom` | `action` | `call` + -The CometChat Dashboard enables you to create new apps (projects) and manage your existing apps. +This guide covers the fundamental concepts you need to understand when building with CometChat. - -How many apps to create? +## CometChat Dashboard -Ideally, you should create two apps- one for development and one for production. And you should use a single app irrespective of the number of platforms. +The [CometChat Dashboard](https://app.cometchat.com) enables you to create new apps (projects) and manage your existing apps. -Do not create separate apps for every platform; if you do, your users on different platforms will not be able to communicate with each other! +- For every app, a unique App ID is generated. This App ID is required when integrating CometChat within your app. +- Along with the App ID, you will need to create an Auth Key (from the Dashboard) which can be used for user authentication. + +Ideally, create two apps — one for development and one for production. Use a single app regardless of the number of platforms. Do not create separate apps for every platform; if you do, your users on different platforms will not be able to communicate with each other. -* For every app, a unique App ID is generated. This App ID will be required when integrating CometChat within your app. -* Along with the App ID, you will need to create an Auth Key (from the Dashboard) which can be used for user authentication. - -### Auth & Rest API Keys - -You can generate two types of keys from the dashboard. +## API Keys -| Type | Privileges | Recommended Use | -| ------------ | ---------------------------------------------------------------- | --------------------------------------------- | -| Auth Key | The Auth Key can be used to create & login users. | In your client side code (during development) | -| Rest API Key | The Rest API Key can be used to perform any CometChat operation. | In your server side code | +You can generate two types of keys from the dashboard: -### Users - -A user is anyone who uses CometChat. - -### UID - -* Each user is uniquely identified using UID. -* The UID is typically the primary ID of the user from your database. +| Type | Privileges | Recommended Use | +| --- | --- | --- | +| Auth Key | Create & login users | Client-side code (development only) | +| REST API Key | Perform any CometChat operation | Server-side code only | - -UID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed. - +Never expose your REST API Key in client-side code. Use Auth Tokens for production authentication. -### Auth Token - -* A single user can have multiple auth tokens. The auth tokens should be per user per device. -* It should be generated by API call ideally, via server to server call. The auth token should then be given to CometChat for login. -* An Auth Token can only be deleted via dashboard or using REST API. +## Users -### Authentication +A user is anyone who uses CometChat. Each user is uniquely identified using a UID (Unique User Identifier). -To allow a user to use CometChat, the user must log in to CometChat. +- The UID is typically the primary ID of the user from your database +- UID can be alphanumeric with underscore and hyphen only — spaces, punctuation, and other special characters are not allowed -**CometChat does not handle user management.** You must handle user registration and login at your end. Once the user is logged into your app/site, you can log in the user to CometChat **programmatically**. So the user does not ever directly login to CometChat. +## Auth Tokens -**CometChat does not handle friends management.** If you want to associate friends with your users, you must handle friends management in your app. Once two users are friends (i.e. they have accepted each other as friends), then you can associate them as friends in CometChat. +Auth Tokens are secure, per-user credentials for production use: -### Typical Workflow +- A single user can have multiple auth tokens (one per device) +- Generate tokens server-side via the [REST API](https://api-explorer.cometchat.com/reference/create-authtoken) +- Tokens can only be deleted via the Dashboard or REST API -| Your App | Your Server | CometChat | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| User registers in your app | You store the user information in your database (e.g. ID, name, email, phone, location etc. in `users` table) | You add the user to CometChat (only ID & name) using the Rest API | -| User logs in to your app | You verify the credentials, login the user and retrieve the user ID | You log in the user to CometChat using the same user ID programmatically | -| User sends a friend request | You display the request to the potential friend | No action required | -| User accepts a friend request | You display the users as friends | You add both the users as friends using the Rest API | +## Authentication Flow -### User Roles +CometChat does not handle user management or friends management. You handle registration and login in your app, then log users into CometChat programmatically. -A role is a category for a group of similar users. For example, you may want to group your premium users using the role "Premium". You then use this to filter users or enable/disable features by writing conditional code. +| Your App | Your Server | CometChat | +| --- | --- | --- | +| User registers | Store user info in your database | Create user via REST API (UID & name) | +| User logs in | Verify credentials, retrieve user ID | Log in user programmatically with UID | +| User sends friend request | Display request to potential friend | No action required | +| User accepts friend request | Display users as friends | Add both users as friends via REST API | -### User List +## User Roles -* The User List can be used to build the **Contacts** or **Who's Online** view in your app. -* The list of users can be different based on the logged-in user. +A role is a category for grouping similar users. For example, group premium users with the role "Premium" to filter users or enable/disable features conditionally. -### Groups +## Groups -A group can be used for multiple users to communicate with each other on a particular topic/interest. +A group enables multiple users to communicate on a particular topic or interest. Each group is uniquely identified using a GUID (Group Unique Identifier). -### GUID +- The GUID is typically the primary ID of the group from your database +- GUID can be alphanumeric with underscore and hyphen only -* Each group is uniquely identified using GUID. -* The GUID is typically the primary ID of the group from your database. If you do not store group information in your database, you can generate a random string for use as GUID. +## Group Types - +| Type | Visibility | Participation | +| --- | --- | --- | +| Public | All users | Any user can join | +| Password | All users | Users with valid password can join | +| Private | Members only | Users must be invited (auto-joined) | -GUID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed. +## Member Scopes - +Once a user joins a group, they become a member with one of three scopes: -### Types +| Scope | Default | Privileges | +| --- | --- | --- | +| Admin | Group creator | Full control: manage members, change scopes, kick/ban anyone, update/delete group | +| Moderator | — | Moderate: change participant scopes, kick/ban participants, update group | +| Participant | All other members | Basic: send & receive messages and calls | -CometChat supports three different types of groups: +## Message Categories -| Type | Visibility | Participation | -| -------- | ---------------------------- | ------------------------------------------------- | -| Public | All users | Any user can choose to join | -| Password | All users | Any user with a valid password can choose to join | -| Private | Only users part of the group | Invited users will be auto-joined | +Every message belongs to one of these categories: -### Members +| Category | Types | Description | +| --- | --- | --- | +| `message` | `text`, `image`, `video`, `audio`, `file` | Standard messages | +| `custom` | Developer-defined | Custom data (e.g., location, polls) | +| `action` | `groupMember`, `message` | System-generated (joins, edits, deletes) | +| `call` | `audio`, `video` | Call-related messages | -Once a participant joins a group, they become a member of the group. Members are part of the group indefinitely i.e. they will keep receiving messages, calls & notifications. To stop, the participant must either be kicked, banned or intentionally leave the group. +For more details, see the [Message Structure and Hierarchy](/sdk/javascript/message-structure-and-hierarchy) guide. -CometChat supports three different types of member scopes in a group: +## Glossary -| Member | Default | Privileges | -| ----------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Admin | Group creator is assigned Admin scope | - Change scope of Group Members to admin, moderator or participant. - Can add members to a group. - Kick & Ban Participants/Moderators/Admins - Send & Receive Messages & Calls - Update group - Delete group | -| Moderator | - | - Change scope of moderator or participant. - Update group - Kick & Ban Participants - Send & Receive Messages & Calls | -| Participant | Any other user is assigned Participant scope | - Send & Receive Messages & Calls | +| Term | Definition | Learn More | +| --- | --- | --- | +| UID | Unique User Identifier — alphanumeric string you assign to each user | [Users Overview](/sdk/javascript/users-overview) | +| GUID | Group Unique Identifier — alphanumeric string you assign to each group | [Groups Overview](/sdk/javascript/groups-overview) | +| Auth Key | Development-only credential for quick testing. Never use in production | [Authentication](/sdk/javascript/authentication-overview) | +| Auth Token | Secure, per-user token generated via REST API. Use in production | [Authentication](/sdk/javascript/authentication-overview#login-using-auth-token) | +| REST API Key | Server-side credential for REST API calls. Never expose in client code | [CometChat Dashboard](https://app.cometchat.com) | +| Receiver Type | Specifies if a message target is a `user` or `group` | [Send Message](/sdk/javascript/send-message) | +| Scope | Group member scope: `admin`, `moderator`, or `participant` | [Change Member Scope](/sdk/javascript/group-change-member-scope) | +| Listener | Callback handler for real-time events (messages, presence, calls, groups) | [All Real-Time Listeners](/sdk/javascript/all-real-time-listeners) | +| Conversation | A chat thread between two users or within a group | [Retrieve Conversations](/sdk/javascript/retrieve-conversations) | +| Metadata | Custom JSON data attached to users, groups, or messages | [Send Message](/sdk/javascript/send-message) | +| Tags | String labels for categorizing users, groups, conversations, or messages | [Message Filtering](/sdk/javascript/message-filtering) | +| RequestBuilder | Builder pattern class for constructing filtered/paginated queries | [Message Filtering](/sdk/javascript/message-filtering) | +| AppSettings | Configuration object for initializing the SDK (App ID, Region, presence) | [Setup SDK](/sdk/javascript/setup-sdk) | +| Transient Message | Ephemeral message not stored on server (typing indicators, live reactions) | [Transient Messages](/sdk/javascript/transient-messages) | +| Interactive Message | Message with actionable UI elements (forms, cards, buttons) | [Interactive Messages](/sdk/javascript/interactive-messages) | -### Messaging - -Any message in CometChat can belong to either one of the below categories - -| Category | Description | -| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| message | Any message belonging to the category `message` can belong to either one of the below types: 1. text 2. image 3. video 4. audio 5. file | -| custom | Custom messages are an option available for developers to send custom data across to users/groups. To send any additional data that does not fit in the default categories and types provided by CometChat, you can use the custom messages. | -| action | Action messages are system-generated messages. These can belong to either of the below types: 1. groupMember - when the action is performed on a group member 2. message - when the action is performed on a message | -| call | These are call-related messages. These can belong to either one of the two types: 1. audio 2. video | +--- -For more information, you can refer to the [Message structure and hierarchy guide](/sdk/javascript/message-structure-and-hierarchy). +## Next Steps + + + + Install and initialize the CometChat SDK + + + Log users in and manage auth tokens + + + Send your first text or media message + + + Create and manage group conversations + + diff --git a/sdk/javascript/leave-group.mdx b/sdk/javascript/leave-group.mdx index a9534b8aa..caf03152b 100644 --- a/sdk/javascript/leave-group.mdx +++ b/sdk/javascript/leave-group.mdx @@ -1,32 +1,33 @@ --- title: "Leave A Group" +sidebarTitle: "Leave Group" +description: "Learn how to leave a group and receive real-time events when members leave using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + - -## Leave a Group - -In order to stop receiving updates and messages for any particular joined group, you will have to leave the group using the `leaveGroup()` method. - - - ```javascript -var GUID = "GUID"; +// Leave a group +await CometChat.leaveGroup("GUID"); -CometChat.leaveGroup(GUID).then( -hasLeft => { - console.log("Group left successfully:", hasLeft); -}, error => { - console.log("Group leaving failed with exception:", error); -} -); +// Listen for member left events +CometChat.addGroupListener("listener", new CometChat.GroupListener({ + onGroupMemberLeft: (message, leavingUser, group) => { } +})); ``` + - +Leave a group to stop receiving updates and messages from that conversation. + +## Leave a Group +Use `leaveGroup()` to leave a group. + + ```typescript -var GUID: string = "GUID"; +const GUID: string = "GUID"; CometChat.leaveGroup(GUID).then( (hasLeft: boolean) => { @@ -39,6 +40,21 @@ CometChat.leaveGroup(GUID).then( + +```javascript +const GUID = "GUID"; + +CometChat.leaveGroup(GUID).then( +hasLeft => { + console.log("Group left successfully:", hasLeft); +}, error => { + console.log("Group leaving failed with exception:", error); +} +); +``` + + + | Parameter | Description | @@ -47,19 +63,19 @@ CometChat.leaveGroup(GUID).then( Once a group is left, the user will no longer receive any updates or messages pertaining to the group. -## Real-time Group Member Left Events +On success, the method resolves with a success message string confirming the operation. -*In other words, as a member of a group, how do I know if someone has left it?* +## Real-time Group Member Left Events -If a user leaves any group, The members of the group receive a real-time event in the `onGroupMemberLeft()` method of the `GroupListener` class. +Register a `GroupListener` to receive events when members leave. - -```javascript + +```typescript CometChat.addGroupListener( "UNIQUE_LISTENER_ID", new CometChat.GroupListener({ - onGroupMemberLeft: (message, leavingUser, group) => { + onGroupMemberLeft: (message: CometChat.Action, leavingUser: CometChat.User, group: CometChat.Group) => { console.log("User left", { message, leavingUser, group }); } }) @@ -68,12 +84,12 @@ CometChat.addGroupListener( - -```typescript + +```javascript CometChat.addGroupListener( "UNIQUE_LISTENER_ID", new CometChat.GroupListener({ - onGroupMemberLeft: (message: CometChat.Action, leavingUser: CometChat.User, group: CometChat.Group) => { + onGroupMemberLeft: (message, leavingUser, group) => { console.log("User left", { message, leavingUser, group }); } }) @@ -84,14 +100,36 @@ CometChat.addGroupListener( -## Missed Group Member Left Events + +Always remove group listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + +```javascript +CometChat.removeGroupListener("UNIQUE_LISTENER_ID"); +``` + -*In other words, as a member of a group, how do I know if someone has left it when my app is not running?* +## Missed Group Member Left Events -When you retrieve the list of previous messages if a member has left any group that the logged-in user is a member of, the list of messages will contain an `Action` message. An `Action` message is a sub-class of `BaseMessage` class. +When fetching message history, leave events appear as `Action` messages with: +- `action` — `"left"` +- `actionBy` — [`User`](/sdk/reference/entities#user) who left +- `actionFor` — [`Group`](/sdk/reference/entities#group) that was left -For the group member left event, in the `Action` object received, the following fields can help you get the relevant information- +--- -1. `action` - `left` -2. `actionBy` - User object containing the details of the user who left the group -3. `actionFor` - Group object containing the details of the group the user has left +## Next Steps + + + + Join public or password-protected groups + + + Permanently delete a group + + + Remove or ban members from a group + + + Fetch and filter the list of groups + + diff --git a/sdk/javascript/login-listener.mdx b/sdk/javascript/login-listener.mdx index 4c98ff4c4..47dbcaf45 100644 --- a/sdk/javascript/login-listener.mdx +++ b/sdk/javascript/login-listener.mdx @@ -1,8 +1,24 @@ --- title: "Login Listener" +description: "Listen for real-time login and logout events using the CometChat JavaScript SDK LoginListener class." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Add login listener +CometChat.addLoginListener("LISTENER_ID", new CometChat.LoginListener({ + loginSuccess: (user) => { }, + loginFailure: (error) => { }, + logoutSuccess: () => { }, + logoutFailure: (error) => { } +})); + +// Remove login listener +CometChat.removeLoginListener("LISTENER_ID"); +``` + The CometChat SDK provides you with real-time updates for the `login` and `logout` events. This can be achieved using the `LoginListener` class provided. LoginListener consists of 4 events that can be triggered. These are as follows: @@ -16,6 +32,30 @@ The CometChat SDK provides you with real-time updates for the `login` and `logou To add the `LoginListener`, you need to use the `addLoginListener()` method provided by the SDK which takes a unique identifier for the listener and of the the `LoginListener` class itself. + +```typescript + const listenerID: string = "UNIQUE_LISTENER_ID"; + CometChat.addLoginListener( + listenerID, + new CometChat.LoginListener({ + loginSuccess: (user: CometChat.User) => { + console.log("LoginListener :: loginSuccess", user); + }, + loginFailure: (error: CometChat.CometChatException) => { + console.log("LoginListener :: loginFailure", error); + }, + logoutSuccess: () => { + console.log("LoginListener :: logoutSuccess"); + }, + logoutFailure: (error: CometChat.CometChatException) => { + console.log("LoginListener :: logoutFailure", error); + } + }) + ); +``` + + + ```js let listenerID = "UNIQUE_LISTENER_ID"; @@ -40,49 +80,122 @@ To add the `LoginListener`, you need to use the `addLoginListener()` method prov + + +### React Example + +If you're using React, register the listener inside a `useEffect` hook and clean it up on unmount: + + ```typescript - var listenerID: string = "UNIQUE_LISTENER_ID"; - CometChat.addLoginListener( +import { useEffect } from "react"; +import { CometChat } from "@cometchat/chat-sdk-javascript"; + +function useLoginListener(): void { + useEffect(() => { + const listenerID: string = "LOGIN_LISTENER"; + CometChat.addLoginListener( listenerID, new CometChat.LoginListener({ - loginSuccess: (user: CometChat.User) => { - console.log("LoginListener :: loginSuccess", user); - }, - loginFailure: (error: CometChat.CometChatException) => { - console.log("LoginListener :: loginFailure", error); - }, - logoutSuccess: () => { - console.log("LoginListener :: logoutSuccess"); - }, - logoutFailure: (error: CometChat.CometChatException) => { - console.log("LoginListener :: logoutFailure", error); - } + loginSuccess: (user: CometChat.User) => { + console.log("User logged in:", user); + }, + loginFailure: (error: CometChat.CometChatException) => { + console.log("Login failed:", error); + }, + logoutSuccess: () => { + console.log("User logged out"); + }, + logoutFailure: (error: CometChat.CometChatException) => { + console.log("Logout failed:", error); + }, }) - ); -``` + ); + return () => { + CometChat.removeLoginListener(listenerID); + }; + }, []); +} +``` + +```javascript +import { useEffect } from "react"; +import { CometChat } from "@cometchat/chat-sdk-javascript"; + +function useLoginListener() { + useEffect(() => { + const listenerID = "LOGIN_LISTENER"; + CometChat.addLoginListener( + listenerID, + new CometChat.LoginListener({ + loginSuccess: (user) => { + console.log("User logged in:", user); + }, + loginFailure: (error) => { + console.log("Login failed:", error); + }, + logoutSuccess: () => { + console.log("User logged out"); + // Redirect to login page, clear app state, etc. + }, + logoutFailure: (error) => { + console.log("Logout failed:", error); + }, + }) + ); + return () => { + CometChat.removeLoginListener(listenerID); + }; + }, []); +} +``` + In order to stop receiving events related to login and logout you need to use the removeLoginListener() method provided by the SDK and pass the ID of the listener that needs to be removed. - -```js - var listenerID = "UNIQUE_LISTENER_ID"; + +```typescript + const listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.removeLoginListener(listenerID); ``` - -```typescript - var listenerID: string = "UNIQUE_LISTENER_ID"; + +```js + const listenerID = "UNIQUE_LISTENER_ID"; CometChat.removeLoginListener(listenerID); ``` + + +Always remove login listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + +--- + +## Next Steps + + + + Learn about login methods and auth tokens + + + Monitor the SDK connection state in real time + + + Complete reference for all SDK event listeners + + + Manually manage WebSocket connections + + diff --git a/sdk/javascript/managing-web-sockets-connections-manually.mdx b/sdk/javascript/managing-web-sockets-connections-manually.mdx index 90cf107b5..76b996f5e 100644 --- a/sdk/javascript/managing-web-sockets-connections-manually.mdx +++ b/sdk/javascript/managing-web-sockets-connections-manually.mdx @@ -1,8 +1,24 @@ --- title: "Managing Web Sockets Connections Manually" +description: "Learn how to manually manage WebSocket connections for real-time messaging using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Disable auto WebSocket connection during init +const appSettings = new CometChat.AppSettingsBuilder() + .setRegion("REGION") + .autoEstablishSocketConnection(false) + .build(); +await CometChat.init("APP_ID", appSettings); + +// Manually connect/disconnect +CometChat.connect(); +CometChat.disconnect(); +``` + ## Default SDK behaviour on login @@ -25,20 +41,20 @@ The CometChat SDK also allows you to modify the above default behaviour of the S 1. While calling the init() function on the app startup, you need to inform the SDK that you will be managing the web socket connect. You can do so by using the `autoEstablishSocketConnection()` method provided by the `AppSettingsBuilder` class. This method takes a boolean value as an input. If set to `true` , the SDK will manage the web-socket connection internally based on the default behaviour mentioned above. If set to `false` , the web socket connection can will not be managed by the SDK and you will have to handle it manually. You can refer to the below code snippet for the same: - -```js -let appID = "APP_ID"; -let region = "APP_REGION"; -let appSetting = new CometChat.AppSettingsBuilder() + +```typescript +let appID: string = "APP_ID"; +let region: string = "APP_REGION"; +let appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder() .subscribePresenceForAllUsers() .setRegion(region) .autoEstablishSocketConnection(false) .build(); CometChat.init(appID, appSetting).then( - () => { + (isInitialized: boolean) => { console.log("Initialization completed successfully"); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Initialization failed with error:", error); } ); @@ -46,20 +62,20 @@ CometChat.init(appID, appSetting).then( - -```typescript -let appID: string = "APP_ID"; -let region: string = "APP_REGION"; -let appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder() + +```js +let appID = "APP_ID"; +let region = "APP_REGION"; +let appSetting = new CometChat.AppSettingsBuilder() .subscribePresenceForAllUsers() .setRegion(region) .autoEstablishSocketConnection(false) .build(); CometChat.init(appID, appSetting).then( - (isInitialized: boolean) => { + () => { console.log("Initialization completed successfully"); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Initialization failed with error:", error); } ); @@ -98,3 +114,22 @@ CometChat.disconnect(); + +--- + +## Next Steps + + + + Monitor the SDK connection state in real time + + + Listen for login and logout events + + + Complete reference for all SDK event listeners + + + SDK installation and initialization guide + + diff --git a/sdk/javascript/mentions.mdx b/sdk/javascript/mentions.mdx index c3ce4742a..ef0292b09 100644 --- a/sdk/javascript/mentions.mdx +++ b/sdk/javascript/mentions.mdx @@ -1,8 +1,29 @@ --- title: "Mentions" +sidebarTitle: "Mentions" +description: "Send messages with user mentions, retrieve mentioned users, and filter messages by mention metadata using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + + +```javascript +// Send a message with a mention (use <@uid:UID> format) +const msg = new CometChat.TextMessage("receiverUID", "Hello <@uid:cometchat-uid-1>", CometChat.RECEIVER_TYPE.USER); +await CometChat.sendMessage(msg); + +// Get mentioned users from a message +const mentionedUsers = message.getMentionedUsers(); + +// Fetch messages with mention tag info +const request = new CometChat.MessagesRequestBuilder() + .setUID("UID").setLimit(30).mentionsWithTagInfo(true).build(); +const messages = await request.fetchPrevious(); +``` + + + Mentions in messages enable users to refer to specific individual within a conversation. This is done by using the `<@uid:UID>` format, where `UID` represents the user’s unique identification. @@ -127,7 +148,7 @@ To get a list of messages in a conversation where users are mentioned along with let UID = "UID"; let limit = 30; -var messagesRequest = new CometChat.MessagesRequestBuilder() +let messagesRequest = new CometChat.MessagesRequestBuilder() .setUID(UID) .setLimit(limit) .mentionsWithTagInfo(true) @@ -154,7 +175,7 @@ messagesRequest.fetchPrevious().then( let GUID = "GUID"; let limit = 30; -var messagesRequest = new CometChat.MessagesRequestBuilder() +let messagesRequest = new CometChat.MessagesRequestBuilder() .setGUID(GUID) .setLimit(limit) .mentionsWithTagInfo(true) @@ -236,17 +257,32 @@ messagesRequest.fetchPrevious().then( +Relevant fields to access on returned messages and their mentioned users: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| mentionedUsers | `getMentionedUsers()` | [`User[]`](/sdk/reference/entities#user) | Array of users mentioned in the message | +| tags (on each mentioned user) | `getTags()` | `string[]` | Tags associated with the mentioned user | + ## Mentions With Blocked Info To get a list of messages in a conversation where users are mentioned along with the blocked relationship of the mentioned users with the logged-in user. +Relevant fields to access on returned messages and their mentioned users: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| mentionedUsers | `getMentionedUsers()` | [`User[]`](/sdk/reference/entities#user) | Array of users mentioned in the message | +| blockedByMe (on each mentioned user) | `getBlockedByMe()` | `boolean` | Whether the logged-in user has blocked this mentioned user | +| hasBlockedMe (on each mentioned user) | `getHasBlockedMe()` | `boolean` | Whether this mentioned user has blocked the logged-in user | + ```javascript let UID = "UID"; let limit = 30; -var messagesRequest = new CometChat.MessagesRequestBuilder() +let messagesRequest = new CometChat.MessagesRequestBuilder() .setUID(UID) .setLimit(limit) .mentionsWithBlockedInfo(true) @@ -274,7 +310,7 @@ messagesRequest.fetchPrevious().then( let GUID = "GUID"; let limit = 30; -var messagesRequest = new CometChat.MessagesRequestBuilder() +let messagesRequest = new CometChat.MessagesRequestBuilder() .setGUID(GUID) .setLimit(limit) .mentionsWithBlockedInfo(true) @@ -366,3 +402,25 @@ To retrieve the list of users mentioned in the particular message, you can use t ```javascript message.getMentionedUsers() ``` + + +The getMentionedUsers() method returns an array of [`User`](/sdk/reference/entities#user) objects. + +--- + +## Next Steps + + + + Send text, media, and custom messages + + + Listen for incoming messages in real time + + + Add emoji reactions to messages + + + Organize conversations with message threads + + diff --git a/sdk/javascript/additional-message-filtering.mdx b/sdk/javascript/message-filtering.mdx similarity index 69% rename from sdk/javascript/additional-message-filtering.mdx rename to sdk/javascript/message-filtering.mdx index 6648ba35e..d372fd2e8 100644 --- a/sdk/javascript/additional-message-filtering.mdx +++ b/sdk/javascript/message-filtering.mdx @@ -1,37 +1,73 @@ --- -title: "Additional Message Filtering" +title: "Message Filtering" +sidebarTitle: "Message Filtering" +description: "Advanced filtering options for fetching messages using MessagesRequestBuilder in the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Filter by category and type +let mediaRequest = new CometChat.MessagesRequestBuilder() + .setUID("UID") + .setCategories(["message"]) + .setTypes(["image", "video", "audio", "file"]) + .setLimit(50) + .build(); -The `MessagesRequest` class as you must be familiar with helps you to fetch messages based on the various parameters provided to it. This document will help you understand better the various options that are available using the `MessagesRequest` class. +// Unread messages only +let unreadRequest = new CometChat.MessagesRequestBuilder() + .setUID("UID") + .setUnread(true) + .setLimit(50) + .build(); -The `MessagesRequest` class is designed using the `Builder design pattern`. In order to obtain an object of the `MessagesRequest` class, you will have to make use of the `MessagesRequestBuilder` class in the `MessagesRequest` class. +// Threaded messages +let threadRequest = new CometChat.MessagesRequestBuilder() + .setUID("UID") + .setParentMessageId(parentId) + .setLimit(50) + .build(); -The `MessagesRequestBuilder` class allows you to set various parameters to the `MessagesRequest` class based on which the messages are fetched. +// Fetch with pagination +messagesRequest.fetchPrevious().then(messages => { }); +messagesRequest.fetchNext().then(messages => { }); +``` -Steps to generate an object of the MessagesRequest class: +**Key methods:** `setUID()`, `setGUID()`, `setLimit()`, `setCategories()`, `setTypes()`, `setTags()`, `setUnread()`, `setParentMessageId()`, `setMessageId()`, `setTimestamp()`, `hideReplies()`, `hideDeletedMessages()` + -1. Create an object of the `MessagesRequestBuilder` class. -2. Set all the parameters you wish to set. -3. Call the `build()` method of the `MessagesRequestBuilder` class to get an object of the `MessagesRequest` class. +The `MessagesRequest` class fetches messages based on various parameters. It uses the Builder design pattern via `MessagesRequestBuilder`. -Once you have an object of the `MessagesRequest` class, you can call either the `fetchNext()` method or the `fetchPrevious()` method using the object. +To fetch messages: +1. Create a `MessagesRequestBuilder` object +2. Set your desired parameters +3. Call `build()` to get a `MessagesRequest` object +4. Call `fetchNext()` or `fetchPrevious()` to retrieve messages -1. fetchNext() - Calling this method will return the messages after the specified parameters. -2. fetchPrevious() - Calling this method will give you messages before the specified parameters. +| Method | Description | +| --- | --- | +| `fetchNext()` | Returns messages after the specified parameters | +| `fetchPrevious()` | Returns messages before the specified parameters | -Since messages are obtained in a paginated manner, a `maximum of 100` messages can be pulled in a single iteration. Calling the `fetchPrevious()`/`fetchNext()` method on the same `MessagesRequest` object will get you the next set of messages. +Messages are paginated with a maximum of 100 per request. Call `fetchPrevious()`/`fetchNext()` repeatedly on the same object to get subsequent pages. -Now that you are clear how to use the `MessagesRequest` class, below are the various options available: +Both methods return an array of [`BaseMessage`](/sdk/reference/messages#basemessage) objects. Each message may be a [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), [`CustomMessage`](/sdk/reference/messages#custommessage), [`Action`](/sdk/reference/messages#action), or [`Call`](/sdk/reference/messages#call). Use `instanceof` to check the type. ## Number of messages fetched -*In other words, how do I set the number of messages fetched in a single iteration* - -To achieve this, you can use the `setLimit()` method. This method takes an integer value as the input and informs the SDK to fetch the specified number of messages in one iteration. The maximum number of messages that can be fetched in one go is `100`. +Set the number of messages to fetch per request using `setLimit()`. Maximum is 100. + +```typescript +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder().setLimit(50).build(); +``` + + + ```js let messagesRequest = new CometChat.MessagesRequestBuilder() @@ -41,24 +77,23 @@ let messagesRequest = new CometChat.MessagesRequestBuilder() + + +## Messages for a user conversation + +Use `setUID()` to fetch messages between the logged-in user and a specific user. + + ```typescript +let UID = "UID"; let messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder().setLimit(50).build(); + new CometChat.MessagesRequestBuilder().setUID(UID).setLimit(50).build(); ``` - - -## Messages for a user conversation - -*In other words, how do I fetch messages between me and any user* - -This can be achieved using the `setUID()` method. This method takes the UID of the user with whom the conversation is to be fetched. When a valid UID is passed, the SDK will return all the messages that are a part of the conversation between the logged-in user and the UID that has been specified. - - - + ```javascript let UID = "UID"; let messagesRequest = new CometChat.MessagesRequestBuilder() @@ -69,25 +104,29 @@ let messagesRequest = new CometChat.MessagesRequestBuilder() - -```typescript -let UID = "UID"; -let messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder().setUID(UID).setLimit(50).build(); -``` + - +When messages are fetched successfully, the response includes an array of message objects. - + +The examples on this page use a small `setLimit()` value for brevity. In production, use a higher limit (up to 100) for efficient pagination. + ## Messages for a group conversation -*In other words, how do I fetch messages for any group conversation* - -You can achieve this using the `setGUID()` method. This method takes the GUID of a group for which the conversations are to be fetched. Passing a valid GUID to this method will return all the messages that are a part of the group conversation. Please note that the logged-in user must be a member of the group to fetch the messages for that group. +Use `setGUID()` to fetch messages from a group. The logged-in user must be a member of the group. - + +```typescript +let GUID: string = "GUID"; +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder().setGUID(GUID).setLimit(50).build(); +``` + + + + ```javascript let GUID = "GUID"; let messagesRequest = new CometChat.MessagesRequestBuilder() @@ -98,28 +137,17 @@ let messagesRequest = new CometChat.MessagesRequestBuilder() - -```typescript -let GUID: string = "GUID"; -let messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder().setGUID(GUID).setLimit(50).build(); -``` - - - - - -If none of the above two methods `setUID()` and `setGUID()` is used, all the messages for the logged-in user will be fetched. This means that messages from all the one-on-one and group conversations which the logged-in user is a part of will be returned.> All the parameters discussed below can be used along with the setUID() or setGUID() or without any of the two to fetch all the messages that the logged-in user is a part of. +When messages are fetched successfully, the response includes an array of message objects. + +If neither `setUID()` nor `setGUID()` is used, all messages for the logged-in user across all conversations will be fetched. All parameters below can be combined with `setUID()` or `setGUID()`. ## Messages before/after a message -*In other words, how do I fetch messages before or after a particular message* - -This can be achieved using the `setMessageId()` method. This method takes the message-id as input and provides messages only after/before the message-id based on if the fetchNext() or fetchPrevious() method is triggered. +Use `setMessageId()` to fetch messages before or after a specific message ID. Use `fetchNext()` to get messages after, or `fetchPrevious()` to get messages before. @@ -182,13 +210,11 @@ let GUID: string = "GUID", -This method can be used along with `setUID()` or `setGUID()` methods to fetch messages after/before any specific message-id for a particular user/group conversation. +This method can be combined with `setUID()` or `setGUID()` to fetch messages around a specific message in a conversation. ## Messages before/after a given time -*In other words, how do I fetch messages before or after a particular date or time* - -You can easily achieve this using the `setTimestamp()` method. This method takes the Unix timestamp as input and provides messages only after/before the timestamp based on if fetchNext() or fetchPrevious() method is triggered. +Use `setTimestamp()` with a Unix timestamp to fetch messages before or after a specific time. @@ -251,13 +277,11 @@ let GUID: string = "GUID", -This method can be used along with `setUID()` or `setGUID()` methods to fetch messages after/before any specific date or time for a particular user/group conversation. +This method can be combined with `setUID()` or `setGUID()` to fetch messages around a specific time in a conversation. ## Unread messages -*In other words, how do I fetch unread messages* - -This can easily be achieved using setting the unread flag to true. For this, you need to use the `setUnread()` method. This method takes a boolean value as input. If the value is set to true, the SDK will return just the unread messages. +Use `setUnread(true)` to fetch only unread messages. @@ -316,13 +340,11 @@ let GUID: string = "GUID", -This method along with `setGUID()` or `setUID()` can be used to fetch unread messages for a particular group or user conversation respectively. +Combine with `setGUID()` or `setUID()` to fetch unread messages for a specific conversation. ## Exclude messages from blocked users -*In other words, how do I fetch messages excluding the messages from the users I have blocked* - -This can be easily achieved using the `hideMessagesFromBlockedUsers()` method. This method accepts a boolean value which determines if the messages from users blocked by the logged-in user need to be a part if the fetched messages. If the value is set to true, the messages will be hidden and won't be a part of the messages fetched. The default value is false i.e if this method is not used, the messages from blocked users will be included in the fetched messages. +Use `hideMessagesFromBlockedUsers(true)` to exclude messages from users you've blocked. Default is `false`. @@ -381,13 +403,11 @@ let GUID: string = "GUID", -This method can be used to hide the messages by users blocked by logged in user in groups that both the members are a part of. +This also works in group conversations where both users are members. ## Updated and received messages -*In other words, how do I fetch messages that have been received or updated after a particular date or time* - -This method accepts a Unix timestamp value and will return all the messages that have been updated and the ones that have been sent/received after the specified time. The messages updated could mean the messages that have been marked as read/delivered or if the messages are edited or deleted. +Use `setUpdatedAfter()` with a Unix timestamp to fetch messages that were sent or updated after a specific time. Updated messages include those marked as read/delivered, edited, or deleted. @@ -450,13 +470,11 @@ let GUID: string = "GUID", -This can be useful in finding the messages that have been received or updated after a certain time. Can prove very useful if you are saving the messages locally and would like to know the messages that have been updated or received after the last message available in your local databases. +Useful for syncing messages with a local database — fetch only what's changed since your last sync. ## Updated messages only -*In other words, how do I fetch messages that have been updated after a particular date or time* - -This can be achieved easily by setting the updatesOnly parameter to true. To do so, you can use the updatesOnly() method. This method takes a boolean input and can be used with the `setUpdatedAfter()` method to get jus the updated messages and not the messages sent/received after the specified time. This method cannot be used independently and always needs to be used with the `setUpdatedAfter()` method. +Use `updatesOnly(true)` with `setUpdatedAfter()` to fetch only updated messages (not newly received ones). This method must be used together with `setUpdatedAfter()`. @@ -523,13 +541,11 @@ let GUID: string = "GUID", -## Messages for multiple categories - -*In other words, how do I fetch messages belonging to multiple categories* +When messages are fetched successfully, the response includes only messages that have been updated (edited, deleted, read/delivered status changed) after the specified timestamp. -We recommend before trying this, you refer to the [Message structure and hierarchy guide](/sdk/javascript/message-structure-and-hierarchy) to get familiar with the various categories of messages. +## Messages for multiple categories -For this, you will have to use the `setCategories()` method. This method accepts a list of categories. This tells the SDK to fetch messages only belonging to these categories. +Use `setCategories()` with an array of category names to filter by message category. See [Message structure and hierarchy](/sdk/javascript/message-structure-and-hierarchy) for available categories. @@ -592,15 +608,11 @@ let GUID: string = "GUID", -The above snippet will help you get only the messages belonging to the `message` and `custom` category. This can also be used to disable certain categories of messages like `call` and `action`. +The above snippet fetches only messages in the `message` and `custom` categories. Use this to exclude categories like `call` and `action`. ## Messages for multiple types -*In other words, how do I fetch messages belonging to multiple types* - -We recommend before trying this, you refer to the [Message structure and hierarchy guide](/sdk/javascript/message-structure-and-hierarchy) to get familiar with the various types of messages. - -This can be easily achieved using the `setTypes()` method. This method accepts a list of types. This tells the SDK to fetch messages only belonging to these types. +Use `setTypes()` with an array of type names to filter by message type. See [Message structure and hierarchy](/sdk/javascript/message-structure-and-hierarchy) for available types. @@ -671,13 +683,11 @@ let GUID: string = "GUID", -Using the above code snippet, you can fetch all the media messages. +The above snippet fetches all media messages (image, video, audio, file). ## Messages for a specific thread -*In other words, how do I fetch messages that are a part of a thread and not directly a user/group conversations* - -This can be done using the `setParentMessageId()` method. This method needs to be used when you have implemented threaded conversations in your app. This method will return the messages only belonging to the thread with the specified parent Id. +Use `setParentMessageId()` to fetch messages belonging to a specific thread. @@ -740,13 +750,11 @@ let GUID: string = "GUID", -The above code snippet returns the messages that belong to the thread with parent id 100. +The above code returns messages belonging to the thread with the specified parent message ID. ## Hide threaded messages in user/group conversations -*In other words, how do I exclude threaded messages from the normal user/group conversations* - -In order to do this, you can use the `hideReplies()` method. This method is also related to threaded conversations. This method takes boolean as input. This boolean when set to true will make sure that the messages that belong to threads are not fetched. If set to false, which is also the default value, the messages belong to the threads will also be fetched along with other messages. +Use `hideReplies(true)` to exclude threaded messages from the main conversation. Default is `false`. @@ -804,12 +812,9 @@ let GUID: string = "GUID", - ## Hide deleted messages in user/group conversations -*In other words, how do I exclude deleted messages a user/group conversations* - -In order to do this, you can use the `hideDeletedMessages()` method. This method takes boolean as input. This boolean when set to true will make sure that the deleted messages are not fetched. If set to false, which is also the default value, the deleted messages will also be fetched along with other messages. +Use `hideDeletedMessages(true)` to exclude deleted messages. Default is `false`. @@ -867,12 +872,9 @@ let GUID: string = "GUID", - ## Hide quoted messages in user/group conversations -*In other words, how do I exclude quoted messages in a user/group conversations* - -In order to do this, you can use the `hideQuotedMessages()` method. This method takes boolean as input. This boolean when set to true will make sure that the quoted messages are not fetched. If set to false, which is also the default value, the quoted messages will also be fetched along with other messages. +Use `hideQuotedMessages(true)` to exclude quoted messages. Default is `false`. @@ -930,12 +932,9 @@ let GUID: string = "GUID", - ## Messages by tags -*In other words, how do I fetch messages by tags* - -In order to do this, you can use the `setTags()` method. This method accepts a list of tags. This tells the SDK to fetch messages only belonging to these tags. +Use `setTags()` with an array of tag names to fetch only messages with those tags. @@ -997,12 +996,9 @@ let GUID: string = "GUID", - ## Messages with tags -*In other words, how do I fetch messages with the tags information* - -In order to do this, you can use the `withTags()` method. This method accepts boolean as input. When set to `true` , the SDK will fetch messages along with the tags. When set to `false` , the SDK will not fetch tags associated with messages. The default value for this parameter is `false` . +Use `withTags(true)` to include tag information in the response. Default is `false`. @@ -1060,12 +1056,15 @@ let GUID: string = "GUID", +When `withTags(true)` is set, each message's `tags` field will be populated. Access tags using `getTags()`. -## Messages with links +| Additional Field | Getter | Return Type | Description | +| --- | --- | --- | --- | +| tags | `getTags()` | `string[]` | Tags associated with the message | -In other words, as a logged-in user, how do I fetch messages that contains links? +## Messages with links -In order to do this, you can use the `hasLinks()` method. This method accepts boolean as input. When set to `true` , the SDK will fetch messages which have links in the text. The default value for this parameter is `false`. +Use `hasLinks(true)` to fetch only messages containing links. Default is `false`. @@ -1129,12 +1128,9 @@ let GUID: string = "GUID", - ## Messages with attachments -In other words, as a logged-in user, how do I fetch messages that contains attachments? - -In order to do this, you can use the `hasAttachments()` method. This method accepts boolean as input. When set to `true` , the SDK will fetch messages which have attachments (image, audio, video or file). The default value for this parameter is `false`. +Use `hasAttachments(true)` to fetch only messages with attachments (image, audio, video, or file). Default is `false`. @@ -1199,11 +1195,11 @@ let GUID: string = "GUID", -## Messages with reactions +The response contains media message objects with attachment details including file metadata and thumbnail URLs. -In other words, as a logged-in user, how do I fetch messages that contains reactions? +## Messages with reactions -In order to do this, you can use the `hasReactions()` method. This method accepts boolean as input. When set to `true` , the SDK will fetch messages which have reactions. The default value for this parameter is `false`. +Use `hasReactions(true)` to fetch only messages that have reactions. Default is `false`. @@ -1268,11 +1264,11 @@ let GUID: string = "GUID", -## Messages with mentions +The response contains message objects with reactions. Each message's `data` object includes a `reactions` array. -In other words, as a logged-in user, how do I fetch messages that contains mentions? +## Messages with mentions -In order to do this, you can use the `hasMentions()` method. This method accepts boolean as input. When set to `true` , the SDK will fetch messages which have mentions. The default value for this parameter is `false`. +Use `hasMentions(true)` to fetch only messages that contain mentions. Default is `false`. @@ -1337,11 +1333,11 @@ let GUID: string = "GUID", -## Messages with particular user mentions +The response contains text message objects with mentions. Each message has a `mentionedUsers` array, a `mentionedMe` boolean, and a `data.mentions` object. -In other words, as a logged-in user, how do I fetch messages that mentions specific users? +## Messages with particular user mentions -In order to do this, you can use the `setMentionedUIDs()` method. This method accepts an array of UIDs as input. When set, the SDK will fetch messages which have the mentions of the UIDs passed. +Use `setMentionedUIDs()` with an array of UIDs to fetch messages that mention specific users. @@ -1406,11 +1402,11 @@ let GUID: string = "GUID", -## Messages with specific attachment types +The response contains text message objects that mention the specified users. -In other words, as a logged-in user, how do I fetch messages that contain specific types of attachments? +## Messages with specific attachment types -In order to do this, you can use the `setAttachmentTypes()` method. This method accepts an array of `CometChat.AttachmentType` ENUM values as input. When provided, the SDK will fetch only those messages that include attachments of the specified types (such as image, audio, video, or file). +Use `setAttachmentTypes()` with an array of `CometChat.AttachmentType` values to fetch messages with specific attachment types. @@ -1474,3 +1470,23 @@ let GUID: string = "GUID", + +The response contains media message objects filtered to the specified attachment types. +--- + +## Next Steps + + + + Send text, media, and custom messages + + + Listen for incoming messages in real-time + + + Understand message categories, types, and hierarchy + + + Work with threaded conversations + + diff --git a/sdk/javascript/message-structure-and-hierarchy.mdx b/sdk/javascript/message-structure-and-hierarchy.mdx index 797cb91df..5046d4cbf 100644 --- a/sdk/javascript/message-structure-and-hierarchy.mdx +++ b/sdk/javascript/message-structure-and-hierarchy.mdx @@ -1,86 +1,187 @@ --- -title: "Message" -sidebarTitle: "Message Structure And Hierarchy" +title: "Message Structure and Hierarchy" +sidebarTitle: "Message Structure" +description: "Understand the message categories, types, and hierarchy in the CometChat JavaScript SDK including text, media, custom, action, interactive, and call messages." --- + +Message categories and types: +- **message** → `text`, `image`, `video`, `audio`, `file` +- **custom** → Developer-defined types (e.g., `location`, `poll`) +- **interactive** → `form`, `card`, `customInteractive` +- **action** → `groupMember` (joined/left/kicked/banned), `message` (edited/deleted) +- **call** → `audio`, `video` + -The below diagram helps you better understand the various message categories and types that a CometChat message can belong to. +Every message in CometChat belongs to a category and has a specific type. Understanding this hierarchy helps you handle different message types correctly in your application. + +## Message Hierarchy -As you can see in the above diagram, every message belongs to a particular category. A message can belong to either one of the 4 categories - -1. Message -2. Custom -3. Action -4. Call - -Each category can be further be classified into types. - -A message belonging to the category `message` can be classified into either 1 of the below types: - -1. text - A plain text message -2. image- An image message -3. video- A video message -4. audio- An audio message -5. file- A file message - -## Custom - -In the case of messages that belong to the `custom` category, there are no predefined types. Custom messages can be used by developers to send messages that do not fit in the default category and types provided by CometChat. For messages with the category `custom`, the developers can set their own type to uniquely identify the custom message. A very good example of a custom message would be the sharing of location co-ordinates. In this case, the developer can decide to use the custom message with type set to `location`. - -## Interactive - -An InteractiveMessage is a specialized object that encapsulates an interactive unit within a chat message, such as an embedded form that users can fill out directly within the chat interface. Messages belonging to the interactive category can further be classified into one of the below types: - -1. form- for interactive form -2. card- for interactive card -3. customInteractive- for custom interaction messages - - - -to know about Interactive messages please [click here](/sdk/javascript/interactive-messages) +## Categories Overview + +| Category | Types | Description | +| --- | --- | --- | +| `message` | `text`, `image`, `video`, `audio`, `file` | Standard user messages | +| `custom` | Developer-defined | Custom data (location, polls, etc.) | +| `interactive` | `form`, `card`, `customInteractive` | Messages with actionable UI elements | +| `action` | `groupMember`, `message` | System-generated events | +| `call` | `audio`, `video` | Call-related messages | + +## Checking Message Category and Type + +Use `getCategory()` and `getType()` to determine how to handle a received message: + + + +```typescript +const category: string = message.getCategory(); +const type: string = message.getType(); + +switch (category) { + case CometChat.CATEGORY_MESSAGE: + if (type === CometChat.MESSAGE_TYPE.TEXT) { + const textMsg = message as CometChat.TextMessage; + console.log("Text:", textMsg.getText()); + } else if (type === CometChat.MESSAGE_TYPE.IMAGE) { + const mediaMsg = message as CometChat.MediaMessage; + console.log("Image URL:", mediaMsg.getData().url); + } + break; + case CometChat.CATEGORY_CUSTOM: + const customMsg = message as CometChat.CustomMessage; + console.log("Custom type:", type, "data:", customMsg.getData()); + break; + case CometChat.CATEGORY_ACTION: + const actionMsg = message as CometChat.Action; + console.log("Action:", actionMsg.getAction()); + break; + case CometChat.CATEGORY_CALL: + const callMsg = message as CometChat.Call; + console.log("Call status:", callMsg.getStatus()); + break; +} +``` + + +```javascript +const category = message.getCategory(); +const type = message.getType(); + +switch (category) { + case CometChat.CATEGORY_MESSAGE: + if (type === CometChat.MESSAGE_TYPE.TEXT) { + console.log("Text:", message.getText()); + } else if (type === CometChat.MESSAGE_TYPE.IMAGE) { + console.log("Image URL:", message.getData().url); + } + break; + case CometChat.CATEGORY_CUSTOM: + console.log("Custom type:", type, "data:", message.getData()); + break; + case CometChat.CATEGORY_ACTION: + console.log("Action:", message.getAction()); + break; + case CometChat.CATEGORY_CALL: + console.log("Call status:", message.getStatus()); + break; +} +``` + + + +## Message Category + +Messages with category `message` are standard user-sent messages: + +| Type | Description | +| --- | --- | +| `text` | Plain text message | +| `image` | Image attachment | +| `video` | Video attachment | +| `audio` | Audio attachment | +| `file` | File attachment | + +## Custom Category + +Custom messages allow you to send data that doesn't fit the default categories. You define your own type to identify the message (e.g., `location`, `poll`, `sticker`). + +```javascript +// Example: Sending a location as a custom message +const customMessage = new CometChat.CustomMessage( + receiverID, + CometChat.RECEIVER_TYPE.USER, + "location", + { latitude: 37.7749, longitude: -122.4194 } +); +``` + +See [Send Message → Custom Messages](/sdk/javascript/send-message#custom-message) for details. + +## Interactive Category + +Interactive messages contain actionable UI elements that users can interact with directly in the chat: + +| Type | Description | +| --- | --- | +| `form` | Embedded form with input fields | +| `card` | Card with buttons and actions | +| `customInteractive` | Custom interactive elements | + +See [Interactive Messages](/sdk/javascript/interactive-messages) for implementation details. + +## Action Category + +Action messages are system-generated events. They have a `type` and an `action` property: + +**Type: `groupMember`** — Actions on group members: +- `joined` — Member joined the group +- `left` — Member left the group +- `kicked` — Member was kicked +- `banned` — Member was banned +- `unbanned` — Member was unbanned +- `added` — Member was added +- `scopeChanged` — Member's scope was changed + +**Type: `message`** — Actions on messages: +- `edited` — Message was edited +- `deleted` — Message was deleted + +## Call Category + +Call messages track call events with types `audio` or `video`. The `status` property indicates the call state: + +| Status | Description | +| --- | --- | +| `initiated` | Call started | +| `ongoing` | Call accepted and in progress | +| `canceled` | Caller canceled | +| `rejected` | Receiver rejected | +| `unanswered` | No answer | +| `busy` | Receiver on another call | +| `ended` | Call completed | + +See [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call) for implementation. - - -## Action - -Action messages are system-generated messages. Messages belonging to the `action` category can further be classified into one of the below types: - -1. groupMember - action performed on a group member. -2. message - action performed on a message. - -Action messages hold another property called `action` which actually determine the action that has been performed For the type `groupMember` the action can be either one of the below: - -1. joined - when a group member joins a group -2. left - when a group member leaves a group -3. kicked - when a group member is kicked from the group -4. banned - when a group member is banned from the group -5. unbanned - when a group member is unbanned from the group -6. added - when a user is added to the group -7. scopeChanged - When the scope of a group member is changed. - -For the type `message`, the action can be either one of the below: - -1. edited - when a message is edited. -2. deleted - when a message is deleted. - -## Call - -Messages with the category `call` are Calling related messages. These can belong to either one of the 2 types - -1. audio -2. video - -The call messages have a property called status that helps you figure out the status of the call. The status can be either one of the below values: +--- -1. initiated - when a is initiated to a user/group -2. ongoing - when the receiver of the call has accepted the call -3. canceled - when the call has been canceled by the initiator of the call -4. rejected - when the call has been rejected by the receiver of the call -5. unanswered - when the call was not answered by the receiver. -6. busy - when the receiver of the call was busy on another call. -7. ended - when the call was successfully completed and ended by either the initiator or receiver. +## Next Steps + + + + Send text, media, and custom messages + + + Listen for incoming messages in real time + + + Send messages with embedded forms and buttons + + + Advanced message filtering with RequestBuilder + + diff --git a/sdk/javascript/messaging-overview.mdx b/sdk/javascript/messaging-overview.mdx index 5a8902b43..4914e383e 100644 --- a/sdk/javascript/messaging-overview.mdx +++ b/sdk/javascript/messaging-overview.mdx @@ -1,12 +1,40 @@ --- title: "Messaging" sidebarTitle: "Overview" +description: "Overview of messaging capabilities in the CometChat JavaScript SDK including sending, receiving, editing, deleting messages, and advanced features." --- +{/* TL;DR for Agents and Quick Reference */} + +Choose your path: +- **Send Messages** → [Send Message](/sdk/javascript/send-message) - Text, media, custom +- **Receive Messages** → [Receive Message](/sdk/javascript/receive-message) - Real-time listeners +- **Edit/Delete** → [Edit](/sdk/javascript/edit-message) | [Delete](/sdk/javascript/delete-message) +- **Advanced** → [Threads](/sdk/javascript/threaded-messages) | [Reactions](/sdk/javascript/reactions) | [Mentions](/sdk/javascript/mentions) + Messaging is one of the core features of CometChat. We've thoughtfully created methods to help you send, receive and fetch message history. At the minimum, you must add code for [sending messages](/sdk/javascript/send-message) and [receiving messages](/sdk/javascript/receive-message). Once you've implemented that, you can proceed to more advanced features like [typing indicators](/sdk/javascript/typing-indicators) and [delivery & read receipts](/sdk/javascript/delivery-read-receipts). + +--- + +## Next Steps + + + + Send text, media, and custom messages + + + Listen for incoming messages in real time + + + Understand message categories and types + + + Show real-time typing status in conversations + + diff --git a/sdk/javascript/overview.mdx b/sdk/javascript/overview.mdx index 05fa4c3d2..2b3cf997a 100644 --- a/sdk/javascript/overview.mdx +++ b/sdk/javascript/overview.mdx @@ -1,554 +1,135 @@ --- -title: "Overview" +title: "JavaScript SDK" +sidebarTitle: "Overview" +description: "Add real-time chat, voice, and video to your JavaScript application with the CometChat SDK." --- +{/* TL;DR for Agents and Quick Reference */} + - -This guide demonstrates how to add chat to a JavaScript application using CometChat. Before you begin, we strongly recommend you read the [Key Concepts](/sdk/javascript/key-concepts) guide. - -#### I want to integrate with my app - -1. [Get your application keys](overview#get-your-application-keys) -2. [Add the CometChat dependency](overview#add-the-cometchat-dependency) -3. [Initialize CometChat](overview#initialize-cometchat) -4. [Register and Login your user](overview#register-and-login-your-user) -5. [Integrate our UI Kits](overview#integrate-our-ui-kits) -6. [Integrate our Chat Widget](overview#integrate-our-chat-widget) - -#### I want to explore a sample app (includes UI) - -Open the app folder in your favorite code editor and follow the steps mentioned in the `README.md` file. - -[React Sample App](https://github.com/cometchat-pro/javascript-react-chat-app) - -[Angular Sample App](https://github.com/cometchat-pro/javascript-angular-chat-app) - -[Vue Sample App](https://github.com/cometchat-pro/javascript-vue-chat-app) - -### Get your Application Keys - -[Signup for CometChat](https://app.cometchat.com) and then: - -1. Create a new app -2. Head over to the **API & Auth Keys** section and note the **Auth Key**, **App ID** & **Region** - -## Add the CometChat Dependency - -### NPM - - - -```js - npm install @cometchat/chat-sdk-javascript -``` - - - - - -Then, import the `CometChat` object wherever you want to use CometChat. - - - -```js - import { CometChat } from "@cometchat/chat-sdk-javascript"; -``` - - - - - -### HTML (via CDN) - -Include the CometChat JavaScript library in your HTML code - - - -```html - -``` - - - - - -### Server Side Rendering (SSR) Compatibility - -You can use CometChat with SSR frameworks such as [Next.js](https://nextjs.org/) or [NuxtJS](https://nuxtjs.org/) by importing it dynamically on the client side. - -#### Next.js - -You need to import the CometChat SDK dynamically in the `useEffect` React Hook or `componentDidMount()` lifecycle method. - - - -```javascript -import React from "react"; -import Chat from "./Chat"; - -export default function Home() { - let [libraryImported, setLibraryImported] = React.useState(false); - - React.useEffect(() => { - window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat; - setLibraryImported(true); - }); - - return libraryImported ? :

Loading....

; -} -``` - - - - -```javascript -import React from 'react'; -import Chat from './Chat'; - -export default class Home extends React.Component { - -constructor(props) { - super(props); - this.state = { - libraryImported: false - }; -} - -componentDidMount(){ - CometChat = require("@cometchat/chat-sdk-javascript").CometChat; - this.setState({libraryImported: true}); -} - -return( - this.state.libraryImported ? :

Loading....

-) - -} -``` - - - - -```javascript -import React, { Component } from "react"; - -import { COMETCHAT_CONSTANTS } from "./CONSTS"; - -export default class Chat extends Component { - constructor(props) { - super(props); - this.state = { - user: undefined, - }; - } - - componentDidMount() { - this.init(); - } - - init() { - CometChat.init( - COMETCHAT_CONSTANTS.APP_ID, - new CometChat.AppSettingsBuilder() - .setRegion(COMETCHAT_CONSTANTS.REGION) - .subscribePresenceForAllUsers() - .build() - ).then( - () => { - this.login(); - }, - (error) => { - console.log("Init failed with exception:", error); - } - ); - } - - login() { - let UID = "UID"; - CometChat.login(UID, COMETCHAT_CONSTANTS.AUTH_KEY).then( - (user) => { - this.setState({ user }); - }, - (error) => { - console.log("Login failed with exception:", error); - } - ); - } - - render() { - return this.state.user ? ( -
User logged in
- ) : ( -
User not logged in
- ); - } -} -``` - - - - -```javascript -export const COMETCHAT_CONSTANTS = { - APP_ID: "APP_ID", - REGION: "REGION", - AUTH_KEY: "AUTH_KEY", -}; -``` - - - - - -#### NuxtJS - -You need to import the CometChat SDK dynamically in the `mounted` lifecycle hook. - - - -```javascript - - - -``` - - - - -```javascript - - - +```bash +npm install @cometchat/chat-sdk-javascript ``` - - - ```javascript -module.exports = { - APP_ID: "APP_ID", - REGION: "REGION", - AUTH_KEY: "AUTH_KEY", -}; -``` - - - - - -#### Ionic/Cordova - -For Ionic and Cordova applications, you can use the JavaScript SDK directly. Import the CometChat SDK in your component or service: - - - -```typescript -import { Component, OnInit } from '@angular/core'; -import { CometChat } from '@cometchat/chat-sdk-javascript'; - -@Component({ - selector: 'app-root', - templateUrl: 'app.component.html', -}) -export class AppComponent implements OnInit { - - ngOnInit() { - this.initCometChat(); - } - - initCometChat() { - const appID = 'APP_ID'; - const region = 'APP_REGION'; - - const appSetting = new CometChat.AppSettingsBuilder() - .subscribePresenceForAllUsers() - .setRegion(region) - .autoEstablishSocketConnection(true) - .build(); - - CometChat.init(appID, appSetting).then( - () => { - console.log('CometChat initialized successfully'); - }, - (error) => { - console.log('CometChat initialization failed:', error); - } - ); - } -} -``` - - +import { CometChat } from "@cometchat/chat-sdk-javascript"; - - - - -The dedicated Ionic Cordova SDK has been deprecated. For new Ionic/Cordova applications, use the JavaScript SDK as shown above. Existing users of the Ionic SDK can refer to the [legacy documentation](/sdk/ionic-legacy/overview) for reference. - - - -## Initialize CometChat - -The `init()` method initializes the settings required for CometChat. The `init()` method takes the below parameters: - -1. appID - Your CometChat App ID -2. appSettings - An object of the AppSettings class can be created using the AppSettingsBuilder class. The region field is mandatory and can be set using the `setRegion()` method. - -The `AppSettings` class allows you to configure the following settings: - -* **Region**: The region where your app was created. -* [Presence Subscription](/sdk/javascript/user-presence): Represents the subscription type for user presence (real-time online/offline status) -* **autoEstablishSocketConnection(boolean value)**: This property takes a boolean value which when set to `true` informs the SDK to manage the web-socket connection internally. If set to `false`, it informs the SDK that the web-socket connection will be managed manually. The default value for this parameter is true. For more information on this, please check the [Managing Web-Socket connections manually](/sdk/javascript/managing-web-sockets-connections-manually) section. The default value for this property is **true.** -* **overrideAdminHost(adminHost: string)**: This method takes the admin URL as input and uses this admin URL instead of the default admin URL. This can be used in case of dedicated deployment of CometChat. -* **overrideClientHost(clientHost: string)**: This method takes the client URL as input and uses this client URL instead of the default client URL. This can be used in case of dedicated deployment of CometChat. -* **setStorageMode(storageMode)**: This method allows you to configure how CometChat stores data locally. The storageMode parameter can be set to `CometChat.StorageMode.SESSION` to use session storage, which persists data only for the current browser session, or other available storage modes for different persistence behaviors. - -You need to call `init()` before calling any other method from CometChat. We suggest you call the `init()` method on app startup, preferably in the `index.js` file. - - - -```js -let appID = "APP_ID"; -let region = "APP_REGION"; -let appSetting = new CometChat.AppSettingsBuilder() +// 1. Initialize (once at app startup) +const appSettings = new CometChat.AppSettingsBuilder() + .setRegion("APP_REGION") // e.g. "us", "eu", "in" .subscribePresenceForAllUsers() - .setRegion(region) .autoEstablishSocketConnection(true) - .setStorageMode(CometChat.StorageMode.SESSION) .build(); -CometChat.init(appID, appSetting).then( - () => { - console.log("Initialization completed successfully"); - }, - (error) => { - console.log("Initialization failed with error:", error); - } -); -``` - - - - -```typescript -let appID: string = "APP_ID", - region: string = "APP_REGION", - appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder() - .subscribePresenceForAllUsers() - .setRegion(region) - .autoEstablishSocketConnection(true) - .setStorageMode(CometChat.StorageMode.SESSION) - .build(); -CometChat.init(appID, appSetting).then( - (initialized: boolean) => { - console.log("Initialization completed successfully", initialized); - }, (error: CometChat.CometChatException) => { - console.log("Initialization failed with error:", error); - } -); -``` - - - - - -Make sure you replace the `APP_ID` with your CometChat **App ID** and `APP_REGION` with your **App Region** in the above code. - -## Register and Login your user - -Once initialization is successful, you will need to create a user. To create users on the fly, you can use the `createUser()` method. This method takes a `User` object and the `Auth Key` as input parameters and returns the created `User` object if the request is successful. - - -```js -let authKey = "AUTH_KEY"; -var UID = "user1"; -var name = "Kevin"; +await CometChat.init("APP_ID", appSettings); -var user = new CometChat.User(UID); - -user.setName(name); - -CometChat.createUser(user, authKey).then( - (user) => { - console.log("user created", user); - }, - (error) => { - console.log("error", error); - } -); -``` - - - - -```typescript -let authKey: string = "AUTH_KEY", - UID: string = "user1", - name: string = "Kevin"; - -var user = new CometChat.User(UID); - -user.setName(name); - -CometChat.createUser(user, authKey).then( - (user: CometChat.User) => { - console.log("user created", user); - }, - (error: CometChat.CometChatException) => { - console.log("error", error); - } -); -``` - - - - - -Make sure that `UID` and `name` are specified as these are mandatory fields to create a user. - -Once you have created the user successfully, you will need to log the user into CometChat using the `login()` method. - -We recommend you call the CometChat `login()` method once your user logs into your app. The `login()` method needs to be called only once. - - - -This straightforward authentication method is ideal for proof-of-concept (POC) development or during the early stages of application development. For production environments, however, we strongly recommend using an [Auth Token](/sdk/javascript/authentication-overview#login-using-auth-token) instead of an Auth Key to ensure enhanced security. - - - - - -```js -var UID = "cometchat-uid-1"; -var authKey = "AUTH_KEY"; - -CometChat.getLoggedinUser().then( - (user) => { - if (!user) { - CometChat.login(UID, authKey).then( - (user) => { - console.log("Login Successful:", { user }); - }, - (error) => { - console.log("Login failed with exception:", { error }); - } - ); - } - }, - (error) => { - console.log("Some Error Occured", { error }); - } -); -``` - - - - -```typescript -var UID: string = "cometchat-uid-1", - authKey: string = "AUTH_KEY"; - -CometChat.getLoggedinUser().then( - (user: CometChat.User) => { - if (!user) { - CometChat.login(UID, authKey).then( - (user: CometChat.User) => { - console.log("Login Successful:", { user }); - }, - (error: CometChat.CometChatException) => { - console.log("Login failed with exception:", { error }); - } - ); - } - }, - (error: CometChat.CometChatException) => { - console.log("Some Error Occured", { error }); - } -); +// 2. Login (check session first) +const existing = await CometChat.getLoggedinUser(); +if (!existing) { + await CometChat.login("cometchat-uid-1", "AUTH_KEY"); // dev only — use Auth Token in production +} ``` - - - - -Make sure you replace the `AUTH_KEY` with your CometChat **AuthKey** in the above code. - - -Sample Users - -We have set up 5 users for testing having UIDs: `cometchat-uid-1`, `cometchat-uid-2`, `cometchat-uid-3`, `cometchat-uid-4` and `cometchat-uid-5`. - - - -The `login()` method returns the `User` object on `Promise` resolved containing all the information of the logged-in user. - - - -UID can be alphanumeric with an underscore and hyphen. Spaces, punctuation and other special characters are not allowed. - - - -## Integrate our UI Kits - -* Please refer to the section to integrate [React UI Kit](/ui-kit/react/overview) into your website. -* Please refer to the section to integrate [Angular UI Kit](/ui-kit/angular/overview) into your website. -* Please refer to the section to integrate [Vue UI Kit](/ui-kit/vue/overview) into your website. - -## Integrate our Chat Widget - -* Please refer to the section to integrate [Chat Widget](/widget/html-bootstrap-jquery) into your Website. +**Credentials:** App ID, Region, Auth Key from [CometChat Dashboard](https://app.cometchat.com) +**Test UIDs:** `cometchat-uid-1` through `cometchat-uid-5` +**SSR:** SDK requires browser APIs — initialize client-side only (`useEffect` / `mounted`) + + +The CometChat JavaScript SDK lets you add real-time messaging, voice, and video calling to any JavaScript application — React, Angular, Vue, Next.js, Nuxt, or vanilla JS. + +## Requirements + +| Requirement | Minimum Version | +|-------------|-----------------| +| npm | 8.x | +| Node.js | 16 | + +Works in all modern browsers (Chrome, Firefox, Safari, Edge) and SSR frameworks (Next.js, Nuxt) with [client-side initialization](/sdk/javascript/setup-sdk#ssr-compatibility). + +## Getting Started + + + + [Sign up for CometChat](https://app.cometchat.com) and create an app. Note your App ID, Region, and Auth Key from the Dashboard. + + + Add the SDK to your project and initialize it with your credentials. See [Setup SDK](/sdk/javascript/setup-sdk). + + + Log in users with Auth Key (development) or Auth Token (production). See [Authentication](/sdk/javascript/authentication-overview). + + + Send your first message, make a call, or manage users and groups. + + + +## Features + + + + 1:1 and group chat, threads, reactions, typing indicators, read receipts, file sharing, and interactive messages. + + + Ringing flows, direct call sessions, standalone calling, recording, virtual backgrounds, and screen sharing. + + + Create, retrieve, and manage users. Track online/offline presence and block/unblock users. + + + Public, private, and password-protected groups with member management, roles, and ownership transfer. + + + +## Sample Apps + +Explore working examples with full source code: + + + + React sample app + + + Angular sample app + + + Vue sample app + + + +## UI Kits + +Skip the UI work — use pre-built, customizable components: + + + + React UI Kit + + + Angular UI Kit + + + Vue UI Kit + + + +For the fastest integration, embed the [Chat Widget](/widget/html/overview) with just a few lines of code. + +## Resources + + + + UIDs, GUIDs, auth tokens, and core SDK concepts + + + Message categories, types, and hierarchy + + + Latest SDK version and release notes + + + Migration guide for V3 users + + + Common issues and solutions + + diff --git a/sdk/javascript/presenter-mode.mdx b/sdk/javascript/presenter-mode.mdx index 42b2bdc2a..fbe24fac0 100644 --- a/sdk/javascript/presenter-mode.mdx +++ b/sdk/javascript/presenter-mode.mdx @@ -1,41 +1,38 @@ --- title: "Presenter Mode" +sidebarTitle: "Presenter Mode" +description: "Learn how to implement Presenter Mode for webinars, keynotes, and online classes using the CometChat JavaScript Calls SDK." --- + +```javascript +// Start a presentation session +const settings = new CometChatCalls.PresenterSettingsBuilder() + .setIsPresenter(true) + .enableDefaultLayout(true) + .setCallEventListener(callListener) + .build(); -## Overview - -The Presenter Mode feature allows developers to create a calling service experience in which: - -1. There are one or more users who are presenting their video, audio and/or screen (Maximum 5) -2. Viewers who are consumers of that presentation. (They cannot send their audio, video or screen streams out). -3. The total number of presenters and viewers can go up to 100. -4. Features such as mute/unmute audio, show/hide camera capture, recording, etc. will be enabled only for the Presenter in this mode. -5. Other call participants will not get these features. Hence they act like passive viewers in the call. - -Using this feature developers can create experiences such as: - -1. All hands calls -2. Keynote speeches -3. Webinars -4. Talk shows -5. Online classes -6. and many more... - -### About this guide +CometChatCalls.joinPresentation(callToken, settings, htmlElement); +``` -This guide demonstrates how to start a presentation into an React Native application. Before you begin, we strongly recommend you read the calling setup guide. +- **Presenter** (max 5): Can share video, audio, and screen +- **Viewer** (up to 100 total): Passive consumers, no outgoing streams + -Before starting a call session you have to generate a call token using the generateToken() method of the CometChatCalls SDK as mentioned [here](/sdk/javascript/direct-call#generate-call-token). +Presenter Mode enables broadcast-style calling — up to 5 presenters share content with passive viewers (up to 100 total participants). Use it for webinars, keynotes, all-hands meetings, online classes, or talk shows. -### Start Presentation Session +| Role | Capabilities | Max Count | +| ---- | ------------ | --------- | +| Presenter | Video, audio, screen sharing, mute controls, recording | 5 | +| Viewer | Watch and listen only (no outgoing streams) | Up to 100 total | -The most important class that will be used in the implementation is the `PresentationSettings` class. This class allows you to set the various parameters for the Presentation Mode. In order to set the various parameters of the `PresentationSettings` class, you need to use the `PresentationSettingsBuilder` class. Below are the various options available with the `PresentationSettings` class. +Before starting a presentation, generate a call token using `generateToken()` as described in [Call Session](/sdk/javascript/direct-call#generate-call-token). -You will need to set the User Type, There are 2 type of users in Presenter Mode, `Presenter` & `Participant` , You can set this `PresentationSettingsBuilder` by using the following method `setIsPresenter(true/false)` +## Start a Presentation Session -A basic example of how to start a Presentation: +Configure the presentation using `PresentationSettingsBuilder`. Set `setIsPresenter(true)` for presenters or `setIsPresenter(false)` for viewers. @@ -58,9 +55,15 @@ CometChatCalls.joinPresentation( -## **Listeners** +## Listeners + +Add listeners in two ways: +1. Use `.setCallEventListener()` in `PresentationSettingsBuilder` +2. Use `CometChatCalls.addCallEventListener(name, listener)` for multiple listeners -Listeners can be added in two ways the first one is to use `.setCallEventListener(listeners : OngoingCallListener)` method in `CallSettingsBuilder` or `PresenterSettingsBuilder` class. The second way is to use `CometChatCalls.addCallEventListener(name: string, callListener: OngoingCallListener)` by this you can add multiple listeners and remove the specific listener by their name `CometChatCalls.removeCallEventListener(name: string)` + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + @@ -85,9 +88,6 @@ useEffect(() => { onError: error => { console.log('Call Error: ', error); }, - onAudioModesUpdated: (audioModes) => { - console.log("audio modes:", audioModes); - }, onUserMuted: (event) => { console.log("user muted:", event); } @@ -100,48 +100,45 @@ useEffect(() => { -The `CometChatCallsEventsListener` listener provides you with the below callback methods: - -| Callback Method | Description | -| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -| onCallEnded() | This method is called when the call is successfully ended. The call details can be obtained from the `Call` object provided. | -| onCallEndButtonPressed() | This method is called when the user press end call button. | -| onUserJoined(user: RTCUser) | This method is called when any other user joins the call. The user details can be obtained from the `User` object provided. | -| onUserLeft(user: RTCUser) | This method is called when a user leaves the call. The details of the user can be obtained from the provided `User` object. | -| onUserListUpdated(users: Array\) | This method is triggered every time a participant joins or leaves the call providing the list of users active in the call | -| onAudioModesUpdated(devices: Array\) | This callback is triggered if any new audio output source is available or becomes unavailable. | -| onUserMuted(muteObj: RTCMutedUser) | This method is triggered when a user is muted in the ongoing call. | -| onRecordingStarted(user: RTCUser) | This method is triggered when a recording starts. | -| onRecordingStopped(user: RTCUser) | This method is triggered when a recording stops. | -| onError(e: CometChatException) | This method is called when there is some error in establishing the call. | +The `OngoingCallListener` provides the same callbacks as in [Call Session](/sdk/javascript/direct-call) and [Standalone Calling](/sdk/javascript/standalone-calling). For the full list of callbacks and their parameter shapes, see the [`OngoingCallListener`](/sdk/javascript/all-real-time-listeners#ongoing-call-listener-calls-sdk) reference. ## Settings -The `PresentationSettings` class is the most important class when it comes to the implementation of the Calling feature. This is the class that allows you to customize the overall calling experience. The properties for the call/conference can be set using the `PresentationSettingsBuilder` class. This will eventually give you and object of the `PresentationSettings` class which you can pass to the `joinPresentation()` method to start the call. - -The **mandatory** parameters that are required to be present for any call/conference to work are: - -1. Context - context of the activity/application -2. RelativeLayout - A RelativeLayout object in which the calling UI is loaded. +Configure the presentation experience using `PresentationSettingsBuilder`: + +| Method | Description | Default | +| ------ | ----------- | ------- | +| `setIsPresenter(isPresenter: boolean)` | If `true`, user joins as presenter. If `false`, user joins as viewer. | — | +| `enableDefaultLayout(defaultLayout: boolean)` | Show/hide the default button layout. If `false`, only the call view is displayed. | `true` | +| `showEndCallButton(showEndCallButton: boolean)` | Show/hide the end call button. | `true` | +| `showPauseVideoButton(showPauseVideoButton: boolean)` | Show/hide the pause video button. | `true` | +| `showMuteAudioButton(showMuteAudioButton: boolean)` | Show/hide the mute audio button. | `true` | +| `showSwitchCameraButton(showSwitchCameraButton: boolean)` | Show/hide the switch camera button. | `true` | +| `showAudioModeButton(showAudioModeButton: boolean)` | Show/hide the audio mode button. | `true` | +| `showRecordingButton(showRecordingButton: boolean)` | Show/hide the recording button. | `false` | +| `setIsAudioOnlyCall(audioOnly: boolean)` | If `true`, the call is audio-only. If `false`, audio-video. | `false` | +| `startWithAudioMuted(audioMuted: boolean)` | Start the call with the microphone muted. | `false` | +| `startWithVideoMuted(videoMuted: boolean)` | Start the call with the camera off. | `false` | +| `setDefaultAudioMode(audioMode: string)` | Start with a specific audio output. Values: `CometChatCalls.AUDIO_MODE.SPEAKER`, `EARPIECE`, `BLUETOOTH`, `HEADPHONES` | — | +| `setCallEventListener(listener)` | Set the event listener for call callbacks. | — | + +For custom UI, embed your own buttons and use the call control methods described in [Call Session Methods](/sdk/javascript/direct-call#methods). -The options available for customization of calls are: - -| Parameter | Description | -| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `setIsPresenter(isPresenter: boolean)` | If set to `true` user will join as the presenter. If set to `false` user will join as the viewer. | -| `enableDefaultLayout(defaultLayout: boolean)` | If set to `true` enables the default layout for handling the call operations. If set to `false` it hides the button layout and just displays the Call View. **Default value = true** | -| `showEndCallButton(showEndCallButton: boolean)` | If set to `true` it displays the EndCallButton in Button Layout. If set to `false` it hides the EndCallButton in Button Layout. **Default value = true** | -| `showPauseVideoButton(showPauseVideoButton: boolean)` | If set to `true` it displays the PauseVideoButton in Button Layout. If set to `false` it hides the PauseVideoButton in Button Layout. **Default value = true** | -| `showMuteAudioButton`(showMuteAudioButton: boolean)\`\` | If set to `true` it displays the MuteAudioButton in Button Layout. If set to `false` it hides the MuteAudioButton in Button Layout. **Default value = true** | -| `showSwitchCameraButton`(showSwitchCameraButton: boolean)\`\` | If set to `true` it displays the SwitchCameraButton in Button Layout. If set to `false` it hides the SwitchCameraButton in Button Layout. **Default value = true** | -| `showAudioModeButton`(showAudioModeButton: boolean)\`\` | If set to `true` it displays the AudioModeButton in Button Layout. If set to `false` it hides the AudioModeButton in Button Layout. **Default value = true** | -| `setIsAudioOnlyCall(audioOnly: boolean)` | If set to `true`, the call will be strictly an audio call. If set to `false`, the call will be an audio-video call.**Default value = false** | -| `startWithAudioMuted(audioMuted: boolean)` | This ensures the call is started with the audio muted if set to true. **Default value = false** | -| `startWithVideoMuted(videoMuted: boolean)` | This ensures the call is started with the video paused if set to true. **Default value = false** | -| `startWithVideoMuted(videoMuted: boolean)` | If set to true it displays the Recording in Button Layout. if set to false it hides the Recording in Button Layout. **Default value = false** | -| `setDefaultAudioMode(audioMode: string)` | This method can be used if you wish to start the call with a specific audio mode. The available options are 1. CometChatCalls.AUDIO\_MODE.SPEAKER = "SPEAKER" 2. CometChatCalls.AUDIO\_MODE.EARPIECE = "EARPIECE" 3. CometChatCalls.AUDIO\_MODE.BLUETOOTH = "BLUETOOTH" 4. CometChatCalls.AUDIO\_MODE.HEADPHONES = "HEADPHONES" | -| `setEventListener(new CometChatCallsEventsListener())` | The `CometChatCallsEventsListener` listener provides you callbacks | - -In case you wish to achieve a completely customised UI for the Calling experience, you can do so by embedding default android buttons to the screen as per your requirement and then use the below methods to achieve different functionalities for the embedded buttons. +--- -For the use case where you wish to align your own custom buttons and not use the default layout provided by CometChat you can embed the buttons in your layout and use the below methods to perform the corresponding operations: +## Next Steps + + + + Start standard call sessions without presenter mode + + + Record call and presentation sessions + + + Add virtual backgrounds to video calls + + + Customize the video layout and containers + + diff --git a/sdk/javascript/rate-limits.mdx b/sdk/javascript/rate-limits.mdx index 17581b144..c7689f4ef 100644 --- a/sdk/javascript/rate-limits.mdx +++ b/sdk/javascript/rate-limits.mdx @@ -1,34 +1,119 @@ --- title: "Rate Limits" +description: "Understand CometChat REST API rate limits, response headers, and how to handle rate-limited requests in your JavaScript application." --- + +- Core Operations (login, create/delete user, create/join group): `10,000` requests/min cumulative +- Standard Operations (all other): `20,000` requests/min cumulative +- Rate-limited responses return HTTP `429` with `Retry-After` and `X-Rate-Limit-Reset` headers +- Monitor usage via `X-Rate-Limit` and `X-Rate-Limit-Remaining` response headers + -### CometChat REST API Rate Limits +CometChat applies rate limits to ensure fair usage and platform stability. Understanding these limits helps you build applications that handle high traffic gracefully. - +## Rate Limit Tiers -The rate limits below are for general applications. Rate limits can be adjusted on a per need basis, depending on your use-case and plan. The rate limits are cumulative. For example: If the rate limit for core operations is 100 requests per minute, then you can either login a user, add user to a group, remove a user from a group, etc for total 100 requests per minute. +| Operation Type | Limit | Examples | +| --- | --- | --- | +| Core Operations | 10,000 requests/min | Login, create/delete user, create/join group | +| Standard Operations | 20,000 requests/min | All other operations | + +Rate limits are cumulative within each tier. For example, if you make 5,000 login requests and 5,000 create user requests in one minute, you've hit the 10,000 core operations limit. -1. **Core Operations:** Core operations are rate limited to `10,000` requests per minute. Core operations include user login, create/delete user, create/join group cumulatively. -2. **Standard Operations:** Standard operations are rate limited to `20,000` requests per minute. Standard operations include all other operations cumulatively. - -## What happens when rate limit is reached ? - -The request isn't processed and a response is sent containing a 429 response code. Along with the response code there will be couple of headers sent which specifies the time in seconds that you must wait before you can try request again. - -`Retry-After: 15` +## Response Headers + +CometChat includes rate limit information in response headers: + +| Header | Description | +| --- | --- | +| `X-Rate-Limit` | Your current rate limit | +| `X-Rate-Limit-Remaining` | Requests remaining in current window | +| `Retry-After` | Seconds to wait before retrying (on 429) | +| `X-Rate-Limit-Reset` | Unix timestamp when limit resets (on 429) | + +## Handling Rate Limits + +When you exceed the rate limit, CometChat returns HTTP `429 Too Many Requests`. Implement exponential backoff to handle this gracefully: + + + +```typescript +async function callWithRetry( + apiCall: () => Promise, + maxRetries: number = 3 +): Promise { + for (let attempt = 0; attempt < maxRetries; attempt++) { + try { + return await apiCall(); + } catch (error: any) { + if (error.code === "ERR_TOO_MANY_REQUESTS" && attempt < maxRetries - 1) { + const waitTime = Math.pow(2, attempt) * 1000; + console.log(`Rate limited. Retrying in ${waitTime / 1000}s...`); + await new Promise((resolve) => setTimeout(resolve, waitTime)); + } else { + throw error; + } + } + } + throw new Error("Max retries exceeded"); +} + +// Usage +const users: CometChat.User[] = await callWithRetry(() => + new CometChat.UsersRequestBuilder().setLimit(30).build().fetchNext() +); +``` + + +```javascript +async function callWithRetry(apiCall, maxRetries = 3) { + for (let attempt = 0; attempt < maxRetries; attempt++) { + try { + return await apiCall(); + } catch (error) { + if (error.code === "ERR_TOO_MANY_REQUESTS" && attempt < maxRetries - 1) { + const waitTime = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s + console.log(`Rate limited. Retrying in ${waitTime / 1000}s...`); + await new Promise((resolve) => setTimeout(resolve, waitTime)); + } else { + throw error; + } + } + } +} + +// Usage +const users = await callWithRetry(() => + new CometChat.UsersRequestBuilder().setLimit(30).build().fetchNext() +); +``` + + + +## Tips for Staying Within Limits + +- **Batch operations** — Space out bulk operations over time instead of firing all at once +- **Monitor headers** — Check `X-Rate-Limit-Remaining` to proactively slow down before hitting limits +- **Avoid frequent login/logout** — Core operations share a lower limit; minimize login cycles +- **Use pagination** — Fetch data in reasonable page sizes (30-50 items) rather than requesting everything at once -`X-Rate-Limit-Reset: 1625143246` - -## Is there any endpoint that returns rate limit of all resources ? - -No, we don't provide a rate-limit endpoint. + +Rate limits can be adjusted based on your use case and plan. Contact CometChat support if you need higher limits. + -However, we do provide the following response headers that you can use to confirm the app's current rate limit and monitor the number of requests remaining in the current minute: +--- -`X-Rate-Limit: 700` +## Next Steps -`X-Rate-Limit-Remaining: 699` + + + Install and configure the CometChat JavaScript SDK + + + Learn the core concepts behind CometChat + + diff --git a/sdk/javascript/reactions.mdx b/sdk/javascript/reactions.mdx index 8ac8f43fd..f79f09d73 100644 --- a/sdk/javascript/reactions.mdx +++ b/sdk/javascript/reactions.mdx @@ -1,31 +1,40 @@ --- title: "Reactions" +sidebarTitle: "Reactions" +description: "Add, remove, and fetch message reactions in real-time using the CometChat JavaScript SDK. Includes listener events and helper methods for updating UI." --- + +```javascript +// Add a reaction +await CometChat.addReaction(messageId, "😊"); -Enhance user engagement in your chat application with message reactions. Users can express their emotions using reactions to messages. This feature allows users to add or remove reactions, and to fetch all reactions on a message. You can also listen to reaction events in real-time. Let's see how to work with reactions in CometChat's SDK. +// Remove a reaction +await CometChat.removeReaction(messageId, "😊"); -## Add a Reaction +// Fetch reactions for a message +const request = new CometChat.ReactionRequestBuilder() + .setMessageId(messageId).setLimit(10).build(); +const reactions = await request.fetchNext(); -Users can add a reaction to a message by calling `addReaction` with the message ID and the reaction emoji. +// Listen for reaction events +CometChat.addMessageListener("LISTENER_ID", { + onMessageReactionAdded: (reaction) => {}, + onMessageReactionRemoved: (reaction) => {} +}); +``` + - - -```js -let messageId = "1"; -let emoji = "😊"; +Reactions let users respond to messages with emoji. You can add or remove reactions, fetch all reactions on a message, listen for reaction events in real time, and update your UI when reactions change. -CometChat.addReaction(messageId, emoji) -.then((res) => { - console.log('response', res); -}).catch(err => { - console.log('err', err); -}) -``` +Reactions work on text messages, media messages, and custom messages. - +## Add a Reaction +Call `addReaction()` with a message ID and an emoji string. + + ```typescript let messageId:string = "1"; @@ -38,37 +47,28 @@ CometChat.addReaction(messageId, emoji) console.log('err', err); }) ``` - - - - - -You can react on text message, media message and custom message - - - -## Remove a Reaction - -Removing a reaction from a message can be done using the `removeReaction` method. - - ```js let messageId = "1"; let emoji = "😊"; -CometChat.removeReaction(messageId, emoji) +CometChat.addReaction(messageId, emoji) .then((res) => { console.log('response', res); }).catch(err => { console.log('err', err); -}) +}) ``` - + + +## Remove a Reaction + +Call `removeReaction()` with the same message ID and emoji. + ```typescript let messageId:string = "1"; @@ -81,49 +81,84 @@ CometChat.removeReaction(messageId, emoji) console.log('err', err); }) ``` - - + +```js +let messageId = "1"; +let emoji = "😊"; -## Fetch Reactions for a Message +CometChat.removeReaction(messageId, emoji) +.then((res) => { + console.log('response', res); +}).catch(err => { + console.log('err', err); +}) +``` + + -To get all reactions for a specific message, first create a `ReactionRequest` using `ReactionRequestBuilder`. You can specify the number of reactions to fetch with setLimit with max limit 100. For this, you will require the ID of the message. This ID needs to be passed to the `setMessageId()` method of the builder class. The `setReaction()` will allow you to fetch details for specific reaction or emoji. +Both `addReaction()` and `removeReaction()` return a [`BaseMessage`](/sdk/reference/messages#basemessage) object with the updated reactions. -| Setting | Description | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `setMessageId(value)` | Specifies the unique identifier of the message for which you want to fetch reactions. This parameter is mandatory as it tells the SDK which message's reactions are being requested. | -| `setReaction(value)` | Filters the reactions fetched by the specified reaction type (e.g., "😊", "😂", "👍"). When set, this method will cause the ReactionRequest to only retrieve details of the provided reaction for the given message. | +## Read Reaction Data from a Message -*** +Any [`BaseMessage`](/sdk/reference/messages#basemessage) exposes reaction data through two methods: -## Fetch Next +### Get All Reactions -The `fetchNext()` method fetches the next set of reactions for the message. +Use `getReactions()` to retrieve the list of reactions on a message. Returns an empty array if no one has reacted. + +```typescript +message.getReactions() +``` + + ```js -let limit = 10; -let messageId = 1; +message.getReactions() +``` + + -let reactionRequest = new CometChat.ReactionRequestBuilder() -.setMessageId(messageId) -.setLimit(limit) -.build(); +### Check if the Logged-in User Has Reacted -reactionRequest.fetchNext().then( - messages => { - console.log("list fetched:", messages); - }, - error => {a - console.log('list fetching failed with error:', error); - }, - ); +Call `getReactedByMe()` on any [`ReactionCount`](/sdk/reference/auxiliary#reactioncount) object to check whether the logged-in user has reacted with that particular emoji. + + + +```typescript +let reactions = message.getReactions(); +reactions.forEach((reaction) => { +reaction.getReactedByMe(); //Return true is logged-in user reacted on that message, otherwise false +}) ``` + + +```js +let reactions = message.getReactions(); +reactions.forEach((reaction) => { +reaction.getReactedByMe(); //Return true is logged-in user reacted on that message, otherwise false +}) +``` + + +## Fetch Reactions for a Message + +To get the full list of who reacted with what on a specific message, use `ReactionRequestBuilder`. You can paginate through results with `fetchNext()` and `fetchPrevious()` (max 100 per request). + +| Builder Method | Description | +| --- | --- | +| `setMessageId(value)` | The message ID to fetch reactions for. Required. | +| `setReaction(value)` | Filter to a specific emoji (e.g., `"😊"`). When set, only reactions matching this emoji are returned. | +| `setLimit(value)` | Number of reactions to fetch per request. Max 100. | + +### Fetch Next + ```typescript let limit:number = 10; @@ -135,19 +170,20 @@ let reactionRequest = new CometChat.ReactionRequestBuilder() .build(); reactionRequest.fetchNext().then( - (messages: MessageReaction[]) => { - console.log("list fetched:", messages); + (reactions: CometChat.Reaction[]) => { + console.log("list fetched:", reactions); }, (error: CometChat.CometChatException) => { console.log('list fetching failed with error:', error); }, ); ``` - +The `fetchNext()` method returns an array of [`Reaction`](/sdk/reference/auxiliary#reaction) objects representing individual user reactions on the message. + Fetch Previous The `fetchPrevious()` method fetches the previous set of reactions for the message. @@ -161,18 +197,21 @@ let reactionRequest = new CometChat.ReactionRequestBuilder() .setLimit(limit) .build(); -reactionRequest.fetchPrevious().then( +reactionRequest.fetchNext().then( messages => { console.log("list fetched:", messages); }, - error => {a + error => { console.log('list fetching failed with error:', error); }, - ); + ); ``` - + + +### Fetch Previous + ```typescript let limit:number = 10; @@ -184,86 +223,103 @@ let reactionRequest = new CometChat.ReactionRequestBuilder() .build(); reactionRequest.fetchPrevious().then( - (messages: MessageReaction[]) => { - console.log("list fetched:", messages); + (reactions: CometChat.Reaction[]) => { + console.log("list fetched:", reactions); }, (error: CometChat.CometChatException) => { console.log('list fetching failed with error:', error); }, ); ``` - - - -## Real-time Reaction Events - -Keep the chat interactive with real-time updates for reactions. Register a listener for these events and make your UI responsive. - - ```js -let listenerID = "UNIQUE_LISTENER_ID"; +let limit = 10; +let messageId = 1; -CometChat.addMessageListener(listenerID, { - onMessageReactionAdded:(message) => { - console.log("Reaction added", message); +let reactionRequest = new CometChat.ReactionRequestBuilder() +.setMessageId(messageId) +.setLimit(limit) +.build(); + +reactionRequest.fetchPrevious().then( + messages => { + console.log("list fetched:", messages); }, - onMessageReactionRemoved:(message) => { - console.log("Reaction removed", message); - } - }) + error => { + console.log('list fetching failed with error:', error); + }, + ); ``` - + + +## Real-Time Reaction Events +Register a `MessageListener` to receive reaction events as they happen. This is how you keep your UI in sync when other users add or remove reactions. + + ```typescript let listenerID:string = "UNIQUE_LISTENER_ID"; -CometChat.addMessageListener(listenerID, { +CometChat.addMessageListener(listenerID, new CometChat.MessageListener({ onMessageReactionAdded:(message: Object) => { console.log("Reaction added", message); }, onMessageReactionRemoved:(message: Object) => { console.log("Reaction removed", message); } - }) + })) ``` - - - -## Removing a Reaction Listener - -To stop listening for reaction events, remove the listener as follows: - - ```js let listenerID = "UNIQUE_LISTENER_ID"; -CometChat.removeMessageListener(listenerID); +CometChat.addMessageListener(listenerID, new CometChat.MessageListener({ + onMessageReactionAdded:(message) => { + console.log("Reaction added", message); + }, + onMessageReactionRemoved:(message) => { + console.log("Reaction removed", message); + } + })) ``` - + + +Each reaction listener callback receives a [`ReactionEvent`](/sdk/reference/auxiliary#reactionevent) object. +### Remove the Listener + + ```typescript let listenerID:string = "UNIQUE_LISTENER_ID"; -CometChat.removeMessageReactionListener(listenerID); +CometChat.removeMessageListener(listenerID); ``` - + +```js +let listenerID = "UNIQUE_LISTENER_ID"; + +CometChat.removeMessageListener(listenerID); +``` + -## Get Reactions List + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + +## Update a Message with Reaction Info -To retrieve the list of reactions reacted on particular message, you can use the `message.getReactions()` method. This method will return an array containing the reactions, or an empty array if no one reacted on the message. +When you receive a real-time reaction event, you'll want to update the corresponding message object so your UI reflects the change. `updateMessageWithReactionInfo()` does this — it takes the [`BaseMessage`](/sdk/reference/messages#basemessage) instance, the [`MessageReaction`](/sdk/reference/auxiliary#messagereaction) event data, and the action type, then returns the updated message. @@ -282,6 +338,8 @@ message.getReactions() +The `getReactions()` method returns an array of [`ReactionCount`](/sdk/reference/auxiliary#reactioncount) objects, each containing the reaction emoji, the total count of users who reacted with it, and whether the logged-in user used that reaction. + ## Check if Logged-in User has Reacted on Message To check if the logged-in user has reacted on a particular message or not, You can use the `getReactedByMe()` method on any `ReactionCount` object instance. This method will return a boolean value, true if the logged-in user has reacted on that message, otherwise false. @@ -309,6 +367,8 @@ reaction.getReactedByMe(); //Return true is logged-in user reacted on that messa +The `getReactedByMe()` method on a [`ReactionCount`](/sdk/reference/auxiliary#reactioncount) object returns a `boolean` — `true` if the logged-in user has reacted with that specific emoji, `false` otherwise. + ## Update Message With Reaction Info When a user adds or removes a reaction, you will receive a real-time event. Once you receive the real time event you would want to update the message with the latest reaction information. To do so you can use the `updateMessageWithReactionInfo()` method. @@ -350,14 +410,52 @@ let messageReaction: CometChat.MessageReaction = ...; let action: CometChat.REACTION_ACTION = CometChat.REACTION_ACTION.REACTION_ADDED; let modifiedBaseMessage = CometChat.CometChatHelper.updateMessageWithReactionInfo( -baseMessage, -messageReaction, +message, +messageReaction, action ); ``` - + +```js +// The message to which the reaction is related +let message = ...; + +// The reaction event data received in real-time +let messageReaction = ...; + +// The recieved reaction event real-time action type. Can be CometChatConstants.REACTION_ADDED or CometChatConstants.REACTION_REMOVED +let action = CometChat.REACTION_ACTION.REACTION_ADDED; + +let modifiedBaseMessage = CometChat.CometChatHelper.updateMessageWithReactionInfo( +message, +messageReaction, +action +); +``` + -After calling this method, the message instance's reactions are updated. You can then use message.getReactions() to get the latest reactions and refresh your UI accordingly. +On success, this method returns a [`BaseMessage`](/sdk/reference/messages#basemessage) object + +After calling this method, use modifiedBaseMessage.getReactions() to get the latest reactions and refresh your UI. + +| Parameter | Type | Description | +|-----------|------|-------------| +| `message` | [`BaseMessage`](/sdk/reference/messages#basemessage) | The message object to update | +| `messageReaction` | [`MessageReaction`](/sdk/reference/auxiliary#messagereaction) | The reaction event received from the listener | +| `action` | `REACTION_ACTION` | `CometChat.REACTION_ACTION.REACTION_ADDED` or `CometChat.REACTION_ACTION.REACTION_REMOVED` | + +--- + +## Next Steps + + + + Send text, media, and custom messages to users and groups + + + Listen for incoming messages in real-time and fetch missed messages + + diff --git a/sdk/javascript/receive-message.mdx b/sdk/javascript/receive-message.mdx index a6f9a8925..33d4f5776 100644 --- a/sdk/javascript/receive-message.mdx +++ b/sdk/javascript/receive-message.mdx @@ -1,150 +1,110 @@ --- -title: "Receive A Message" +title: "Receive Messages" +sidebarTitle: "Receive Messages" +description: "Receive real-time messages, fetch missed and unread messages, retrieve message history, search messages, and get unread counts using the CometChat JavaScript SDK." --- + +| Field | Value | +| --- | --- | +| Key Classes | `CometChat.MessageListener`, `CometChat.MessagesRequestBuilder` | +| Key Methods | `addMessageListener()`, `fetchPrevious()`, `fetchNext()`, `getUnreadMessageCount()` | +| Listener Events | `onTextMessageReceived`, `onMediaMessageReceived`, `onCustomMessageReceived` | +| Prerequisites | SDK initialized, user logged in | + + Receiving messages with CometChat has two parts: -1. Adding a listener to receive [real-time messages](/sdk/javascript/receive-message#real-time-messages) when your app is running -2. Calling a method to retrieve [missed messages](/sdk/javascript/receive-message#missed-messages) when your app was not running +1. Adding a [real-time listener](#real-time-messages) to receive messages while your app is running +2. Fetching [missed](#missed-messages), [unread](#unread-messages), or [historical](#message-history) messages when your app starts up or the user scrolls back -## Real-Time Messages + +The TypeScript and JavaScript APIs are identical — the only difference is type annotations (e.g., `: string`, `: CometChat.BaseMessage[]`). The Real-Time Messages section shows both for reference. The remaining sections use TypeScript only to keep things concise — just drop the type annotations for plain JavaScript. + -*In other words, as a recipient, how do I receive messages when my app is running?* +## Real-Time Messages -To receive real-time incoming messages, you need to register the `MessageListener` wherever you wish to receive the incoming messages. You can use the `addMessageListener()` method to do so. +Register a `MessageListener` to receive incoming messages as they arrive. Each callback receives the specific message subclass — [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), or [`CustomMessage`](/sdk/reference/messages#custommessage). - -```javascript -let listenerID = "UNIQUE_LISTENER_ID"; + +```typescript +let listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.addMessageListener( listenerID, new CometChat.MessageListener({ - onTextMessageReceived: (textMessage) => { + onTextMessageReceived: (textMessage: CometChat.TextMessage) => { console.log("Text message received successfully", textMessage); }, - onMediaMessageReceived: (mediaMessage) => { + onMediaMessageReceived: (mediaMessage: CometChat.MediaMessage) => { console.log("Media message received successfully", mediaMessage); }, - onCustomMessageReceived: (customMessage) => { + onCustomMessageReceived: (customMessage: CometChat.CustomMessage) => { console.log("Custom message received successfully", customMessage); }, }) ); ``` - - -```typescript -let listenerID: string = "UNIQUE_LISTENER_ID"; + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; CometChat.addMessageListener( listenerID, new CometChat.MessageListener({ - onTextMessageReceived: (textMessage: CometChat.TextMessage) => { + onTextMessageReceived: (textMessage) => { console.log("Text message received successfully", textMessage); }, - onMediaMessageReceived: (mediaMessage: CometChat.MediaMessage) => { + onMediaMessageReceived: (mediaMessage) => { console.log("Media message received successfully", mediaMessage); }, - onCustomMessageReceived: (customMessage: CometChat.CustomMessage) => { + onCustomMessageReceived: (customMessage) => { console.log("Custom message received successfully", customMessage); }, }) ); ``` - - -| Parameter | Description | -| -------------- | --------------------------------------------- | -| **listenerId** | An ID that uniquely identifies that listener. | +| Parameter | Description | +| --- | --- | +| `listenerID` | An ID that uniquely identifies that listener. Use the same ID to remove it later. | -We recommend you remove the listener once you don't want to receive a message for particular listener. +Remove the listener when you no longer need it: - - ```javascript -let listenerID = "UNIQUE_LISTENER_ID"; - -CometChat.removeMessageListener(listenerID); -``` - - - - -```typescript -let listenerID: string = "UNIQUE_LISTENER_ID"; - -CometChat.removeMessageListener(listenerID); +CometChat.removeMessageListener("UNIQUE_LISTENER_ID"); ``` - - - - - -As a sender, you will not receive your own message in a real-time message event. However, if a user is logged-in using multiple devices, they will receive an event for their own message in other devices. - +Always remove listeners when they're no longer needed (e.g., on component unmount). Failing to do so can cause memory leaks and duplicate event handling. -## Missed Messages +Each listener callback receives the specific message subclass — [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), or [`CustomMessage`](/sdk/reference/messages#custommessage) — depending on the message type. -*In other words, as a recipient, how do I receive messages that I missed when my app was not running?* - -For most use cases, you will need to add functionality to load missed messages. If you're building an on-demand or live streaming app, you may choose to skip this and fetch message history instead. - -Using the same `MessagesRequest` class and the filters provided by the `MessagesRequestBuilder` class, you can fetch the message that were sent to the logged-in user but were not delivered to him as he was offline. For this, you will require the id of the last message received. You can either maintain it at your end or use the `getLastDeliveredMessageId()` method provided by the CometChat class. This id needs to be passed to the `setMessageId()` method of the builder class. - -Now using the `fetchNext()` method, you can fetch all the messages that were sent to the user when he/she was offline. - -Calling the `fetchNext()` method on the same object repeatedly allows you to fetch all the offline messages for the logged in user. +## Missed Messages -### Fetch Missed Messages of a particular one-on-one conversation +Fetch messages that arrived while your app was offline. Use `getLastDeliveredMessageId()` to find where you left off, then call `fetchNext()` to get everything after that point. Call `fetchNext()` repeatedly on the same request object to paginate. - -```javascript -let UID = "UID"; -let limit = 30; -let latestId = await CometChat.getLastDeliveredMessageId(); - -var messagesRequest = new CometChat.MessagesRequestBuilder() - .setUID(UID) - .setMessageId(latestId) - .setLimit(limit) - .build(); - -messagesRequest.fetchNext().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - - - + ```typescript -let UID: string = "UID", - limit: number = 30, - latestId: number = await CometChat.getLastDeliveredMessageId(), - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder() - .setUID(UID) - .setMessageId(latestId) - .setLimit(limit) - .build(); +let UID: string = "UID"; +let limit: number = 30; +let latestId: number = await CometChat.getLastDeliveredMessageId(); + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setUID(UID) + .setMessageId(latestId) + .setLimit(limit) + .build(); messagesRequest.fetchNext().then( (messages: CometChat.BaseMessage[]) => { @@ -155,49 +115,20 @@ messagesRequest.fetchNext().then( } ); ``` - - - -### Fetch Missed Messages of a particular group conversation - - - -```javascript -let GUID = "GUID"; -let limit = 30; -let latestId = await CometChat.getLastDeliveredMessageId(); - -var messagesRequest = new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setMessageId(latestId) - .setLimit(limit) - .build(); - -messagesRequest.fetchNext().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - - - + ```typescript -let GUID: string = "GUID", - limit: number = 30, - latestId: number = await CometChat.getLastDeliveredMessageId(), - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setMessageId(latestId) - .setLimit(limit) - .build(); +let GUID: string = "GUID"; +let limit: number = 30; +let latestId: number = await CometChat.getLastDeliveredMessageId(); + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setGUID(GUID) + .setMessageId(latestId) + .setLimit(limit) + .build(); messagesRequest.fetchNext().then( (messages: CometChat.BaseMessage[]) => { @@ -208,52 +139,27 @@ messagesRequest.fetchNext().then( } ); ``` - - -## Unread Messages - -*In other words, as a logged-in user, how do I fetch the messages I've not read?* +The `fetchNext()` method returns an array of [`BaseMessage`](/sdk/reference/messages#basemessage) objects (which may be [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), or other subclasses). -Using the `MessagesRequest` class described above, you can fetch the unread messages for the logged in user. In order to achieve this, you need to set the `unread` variable in the builder to true using the `setUnread()` method so that only the unread messages are fetched. +## Unread Messages -### Fetch Unread Messages of a particular one-on-one conversation +Fetch unread messages by adding `setUnread(true)` to the builder. Use `fetchPrevious()` to retrieve them. - -```javascript -let UID = "UID"; -let limit = 30; -let messagesRequest = new CometChat.MessagesRequestBuilder() - .setUID(UID) - .setUnread(true) - .setLimit(limit) - .build(); - -messagesRequest.fetchPrevious().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - - - + ```typescript -let UID: string = "UID", - limit: number = 30, - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder() - .setUID(UID) - .setUnread(true) - .setLimit(limit) - .build(); +let UID: string = "UID"; +let limit: number = 30; + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setUID(UID) + .setUnread(true) + .setLimit(limit) + .build(); messagesRequest.fetchPrevious().then( (messages: CometChat.BaseMessage[]) => { @@ -264,46 +170,19 @@ messagesRequest.fetchPrevious().then( } ); ``` - - - - - -### Fetch Unread Messages of a particular group conversation - - - -```javascript -let GUID = "GUID"; -let limit = 30; -let messagesRequest = new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setUnread(true) - .setLimit(limit) - .build(); - -messagesRequest.fetchPrevious().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - + ```typescript -let GUID: string = "GUID", - limit: number = 30, - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setUnread(true) - .setLimit(limit) - .build(); +let GUID: string = "GUID"; +let limit: number = 30; + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setGUID(GUID) + .setUnread(true) + .setLimit(limit) + .build(); messagesRequest.fetchPrevious().then( (messages: CometChat.BaseMessage[]) => { @@ -314,54 +193,28 @@ messagesRequest.fetchPrevious().then( } ); ``` - - -Base Message - -The list of messages received is in the form of objects of `BaseMessage` class. A BaseMessage can either be an object of the `TextMessage`, `MediaMessage`, `CustomMessage`, `Action` or `Call` class. You can use the `instanceOf` operator to check the type of object. - +Results are returned as [`BaseMessage`](/sdk/reference/messages#basemessage) objects, which may be instances of [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), [`CustomMessage`](/sdk/reference/messages#custommessage), `Action`, or `Call`. Use the `instanceof` operator to check the type. ## Message History -*In other words, as a logged-in user, how do I fetch the complete message history?* - -### Fetch Message History of a particular one-on-one conversation - -Using the `MessagesRequest` class and the filters for the `MessagesRequestBuilder` class as shown in the below code snippet, you can fetch the entire conversation between the logged in user and any particular user. For this use case, it is mandatory to set the UID parameter using the `setUID()` method of the builder. This UID is the unique id of the user for which the conversation needs to be fetched. +Fetch the full conversation history using `fetchPrevious()`. Call it repeatedly on the same request object to paginate — useful for implementing upward scrolling. - -```javascript -let UID = "UID"; -let limit = 30; -let messagesRequest = new CometChat.MessagesRequestBuilder() - .setUID(UID) - .setLimit(limit) - .build(); - -messagesRequest.fetchPrevious().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - - - + ```typescript -let UID: string = "UID", - limit: number = 30, - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder().setUID(UID).setLimit(limit).build(); +let UID: string = "UID"; +let limit: number = 30; + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setUID(UID) + .setLimit(limit) + .build(); messagesRequest.fetchPrevious().then( (messages: CometChat.BaseMessage[]) => { @@ -372,48 +225,18 @@ messagesRequest.fetchPrevious().then( } ); ``` - - - -Calling the `fetchPrevious()` method on the same object repeatedly allows you to fetch the entire conversation between the logged in user and the specified user. This can be implemented with upward scrolling to display the entire conversation. - -### Fetch Message History of a particular group conversation - -Using the `MessagesRequest` class and the filters for the `MessagesRequestBuilder` class as shown in the below code snippet, you can fetch the entire conversation for any group provided you have joined the group. For this use case, it is mandatory to set the GUID parameter using the `setGUID()` method of the builder. This GUID is the unique identifier of the Group for which the messages are to be fetched. - - - -```javascript -let GUID = "GUID"; -let limit = 30; -let messagesRequest = new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setLimit(limit) - .build(); - -messagesRequest.fetchPrevious().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - - - + ```typescript -let GUID: string = "GUID", - limit: number = 30, - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setLimit(limit) - .build(); +let GUID: string = "GUID"; +let limit: number = 30; + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setGUID(GUID) + .setLimit(limit) + .build(); messagesRequest.fetchPrevious().then( (messages: CometChat.BaseMessage[]) => { @@ -424,71 +247,30 @@ messagesRequest.fetchPrevious().then( } ); ``` - - Calling the `fetchPrevious()` method on the same object repeatedly allows you to fetch the entire conversation for the group. This can be implemented with upward scrolling to display the entire conversation. -## Search Messages +The `fetchPrevious()` method returns an array of [`BaseMessage`](/sdk/reference/messages#basemessage) objects (which may be [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), or other subclasses). -In other words, as a logged-in user, how do I search a message? - -In order to do this, you can use the `setSearchKeyword()` method. This method accepts string as input. When set, the SDK will fetch messages which match the `searchKeyword`. - - - -By default, the searchKey is searched only in message text. However, if you enable `Conversation & Advanced Search`, the searchKey will be searched in message text, file name, mentions & mime type of the file. - -The `Conversation & Advanced Search` is only available in `Advanced` & `Custom` [plans](https://www.cometchat.com/pricing). If you're already on one of these plans, please enable the `Conversation & Advanced Search` from [CometChat Dashboard](https://app.cometchat.com) (Open your app, navigate to Chats -> Settings -> General Configuration) - - - -| Feature | Basic Search | Advance Search | -| ---------------- | ------------ | -------------- | -| Text search | ✅ | ✅ | -| File name search | ❌ | ✅ | -| Mentions search | ❌ | ✅ | -| Mime type search | ❌ | ✅ | +## Search Messages -### Search Messages in a particular one-on-one conversation +Add `setSearchKeyword()` to the builder to filter messages by keyword. - -```javascript -let UID = "UID"; -let limit = 30; -let searchKeyword = "Hello"; -let messagesRequest = new CometChat.MessagesRequestBuilder() - .setUID(UID) - .setLimit(limit) - .setSearchKeyword(searchKeyword) - .build(); - -messagesRequest.fetchPrevious().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - - - + ```typescript -let UID: string = "UID", - limit: number = 30, - searchKeyword: string = "Hello", - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder() - .setUID(UID) - .setLimit(limit) - .setSearchKeyword(searchKeyword) - .build(); +let UID: string = "UID"; +let limit: number = 30; +let searchKeyword: string = "Hello"; + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setUID(UID) + .setLimit(limit) + .setSearchKeyword(searchKeyword) + .build(); messagesRequest.fetchPrevious().then( (messages: CometChat.BaseMessage[]) => { @@ -499,48 +281,20 @@ messagesRequest.fetchPrevious().then( } ); ``` - - - - - -### Search Messages in a particular group conversation - - - -```javascript -let GUID = "GUID"; -let limit = 30; -let searchKeyword = "Hello"; -let messagesRequest = new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setLimit(limit) - .setSearchKeyword(searchKeyword) - .build(); - -messagesRequest.fetchPrevious().then( - (messages) => { - console.log("Message list fetched:", messages); - }, - (error) => { - console.log("Message fetching failed with error:", error); - } -); -``` - - + ```typescript -let GUID: string = "GUID", - limit: number = 30, - searchKeyword: string = "Hello", - messagesRequest: CometChat.MessagesRequest = - new CometChat.MessagesRequestBuilder() - .setGUID(GUID) - .setLimit(limit) - .setSearchKeyword(searchKeyword) - .build(); +let GUID: string = "GUID"; +let limit: number = 30; +let searchKeyword: string = "Hello"; + +let messagesRequest: CometChat.MessagesRequest = + new CometChat.MessagesRequestBuilder() + .setGUID(GUID) + .setLimit(limit) + .setSearchKeyword(searchKeyword) + .build(); messagesRequest.fetchPrevious().then( (messages: CometChat.BaseMessage[]) => { @@ -551,76 +305,47 @@ messagesRequest.fetchPrevious().then( } ); ``` - - -## Unread Message Count - -*In other words, as a logged-in user, how do I find out the number of unread messages that I have?* - -### Fetch Unread Message Count of a particular one-on-one conversation - -*In other words, how do I find out the number of unread messages I have from a particular user?* - -In order to get the unread message count for a particular user, you can use the `getUnreadMessageCountForUser()`. - -This method has the below two variants: +### Search Capabilities - - -```javascript -CometChat.getUnreadMessageCountForUser(UID); -``` +By default, search only matches message text. With `Conversation & Advanced Search` enabled, it also matches file names, mentions, and MIME types. - +| Feature | Basic Search | Advanced Search | +| ---------------- | ------------ | --------------- | +| Text search | ✅ | ✅ | +| File name search | ❌ | ✅ | +| Mentions search | ❌ | ✅ | +| MIME type search | ❌ | ✅ | - -```typescript -let UID: string = "UID"; -CometChat.getUnreadMessageCountForUser(UID); -``` + +`Conversation & Advanced Search` is available on `Advanced` and `Custom` [plans](https://www.cometchat.com/pricing). Enable it from the [CometChat Dashboard](https://app.cometchat.com) under Chats → Settings → General Configuration. + - +## Unread Message Count - +CometChat provides several methods to get unread counts at different scopes. All return a `Promise` that resolves with an object mapping IDs to counts. -If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true: +Each method accepts an optional boolean parameter to exclude messages from blocked users. - - -```javascript -CometChat.getUnreadMessageCountForUser(UID, hideMessagesFromBlockedUsers); -``` +| Method | Scope | Returns | +| --- | --- | --- | +| `getUnreadMessageCountForUser(UID)` | Single user conversation | `{ [UID]: count }` | +| `getUnreadMessageCountForGroup(GUID)` | Single group conversation | `{ [GUID]: count }` | +| `getUnreadMessageCountForAllUsers()` | All user conversations | `{ [UID]: count, ... }` | +| `getUnreadMessageCountForAllGroups()` | All group conversations | `{ [GUID]: count, ... }` | +| `getUnreadMessageCount()` | Everything | `{ users: { ... }, groups: { ... } }` | - +### Single Conversation - ```typescript -let UID: string = "UID", - hideMessagesFromBlockedUsers: boolean = true; -CometChat.getUnreadMessageCountForUser(UID, hideMessagesFromBlockedUsers); -``` - - - - - - - -```javascript -let UID = "UID"; - +// One-on-one +let UID: string = "UID"; CometChat.getUnreadMessageCountForUser(UID).then( - (unreadMessageCountObject) => { - console.log("Unread message count fetched", unreadMessageCountObject); - }, - (error) => { - console.log("Error in getting unread message count", error); - } + (count: Object) => console.log("Unread count:", count), + (error: CometChat.CometChatException) => console.log("Error:", error) ); -``` @@ -642,6 +367,8 @@ CometChat.getUnreadMessageCountForUser(UID).then( +The `getUnreadMessageCountForUser()` method returns a count object where the key is the UID and the value is the unread message count (e.g., `{ "UID": 5 }`). + It will return an object which will contain the UID as the key and the unread message count as the value. ### Fetch Unread Message Count of a particular group conversation @@ -663,52 +390,14 @@ CometChat.getUnreadMessageCountForGroup(GUID); ```typescript let GUID: string = "GUID"; -CometChat.getUnreadMessageCountForGroup(GUID); -``` - - - - - -If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true: - - - -```javascript -CometChat.getUnreadMessageCountForGroup(GUID, hideMessagesFromBlockedUsers); -``` - - - - -```typescript -let GUID: string = "GUID", - hideMessagesFromBlockedUsers: boolean = true; -CometChat.getUnreadMessageCountForGroup(GUID, hideMessagesFromBlockedUsers); -``` - - - - - - - -```javascript -let GUID = "GUID"; - CometChat.getUnreadMessageCountForGroup(GUID).then( - (unreadMessageCountObject) => { - console.log("Unread message count fetched", unreadMessageCountObject); - }, - (error) => { - console.log("Error in getting unread message count", error); - } + (count: Object) => console.log("Unread count:", count), + (error: CometChat.CometChatException) => console.log("Error:", error) ); ``` - +### All Conversations - ```typescript let GUID: string = "GUID"; @@ -726,6 +415,8 @@ CometChat.getUnreadMessageCountForGroup(GUID).then( +The `getUnreadMessageCountForGroup()` method returns a count object where the key is the GUID and the value is the unread message count (e.g., `{ "GUID": 12 }`). + It will return an object which will contain the GUID as the key and the unread message count as the value. ### Fetch Unread Message Count of all one-on-one & group conversations @@ -777,14 +468,9 @@ CometChat.getUnreadMessageCount(hideMessagesFromBlockedUsers); ```javascript CometChat.getUnreadMessageCount().then( - (unreadMessageCountObject) => { - console.log("Unread message count fetched", unreadMessageCountObject); - }, - (error) => { - console.log("Error in getting unread message count", error); - } + (count: Object) => console.log("Unread count:", count), + (error: CometChat.CometChatException) => console.log("Error:", error) ); -``` @@ -804,6 +490,8 @@ CometChat.getUnreadMessageCount().then( +The `getUnreadMessageCount()` method returns a count object with two keys: `users` (a map of `{ UID: count }`) and `groups` (a map of `{ GUID: count }`), representing unread message counts across all conversations. + It returns an object having two keys: 1. users - The value for this key holds another object that holds the UID as key and their corresponding unread message count as value. @@ -854,105 +542,38 @@ CometChat.getUnreadMessageCountForAllUsers(hideMessagesFromBlockedUsers); ```javascript CometChat.getUnreadMessageCountForAllUsers().then( - (unreadMessageCountObject) => { - console.log("Unread message count fetched", unreadMessageCountObject); - }, - (error) => { - console.log("Error in getting unread message count", error); - } -); -``` - - - - -```typescript -CometChat.getUnreadMessageCountForAllUsers().then( - (unreadMessageCount: Object) => { - console.log("Unread message count fetched", unreadMessageCount); - }, - (error: CometChat.CometChatException) => { - console.log("Error in getting unread message count", error); - } + (count: Object) => console.log("Unread count:", count), + (error: CometChat.CometChatException) => console.log("Error:", error) ); -``` - - - - -It returns an object which will contain the UID as the key and the unread message count as the value. - -### Fetch Unread Message Count of all group conversations - -In order to fetch the unread message counts for just the groups, you can use the `getUnreadMessageCountForAllGroups()` method. This method just like others has two variants: - - - -```javascript -CometChat.getUnreadMessageCountForAllGroups(); -``` - - - - -```typescript -CometChat.getUnreadMessageCountForAllGroups(); -``` - - - - - -If you wish to ignore the messages from blocked users you can use the below syntax setting the boolean parameter to true: - - - -```javascript -CometChat.getUnreadMessageCountForAllGroups(hideMessagesFromBlockedUsers); -``` - - - - -```typescript -let hideMessagesFromBlockedUsers: boolean = true; -CometChat.getUnreadMessageCountForAllGroups(hideMessagesFromBlockedUsers); -``` - - - - - - - -```javascript +// All group conversations only CometChat.getUnreadMessageCountForAllGroups().then( - (unreadMessageCountObject) => { - console.log("Unread message count fetched", unreadMessageCountObject); - }, - (error) => { - console.log("Error in getting unread message count", error); - } + (count: Object) => console.log("Unread count:", count), + (error: CometChat.CometChatException) => console.log("Error:", error) ); ``` - +### Excluding Blocked Users + +Pass `true` as the last argument to any of the methods above: - ```typescript -CometChat.getUnreadMessageCountForAllGroups().then( - (unreadMessageCount: Object) => { - console.log("Unread message count fetched", unreadMessageCount); - }, - (error: CometChat.CometChatException) => { - console.log("Error in getting unread message count", error); - } -); +CometChat.getUnreadMessageCountForUser(UID, true); +CometChat.getUnreadMessageCountForGroup(GUID, true); +CometChat.getUnreadMessageCount(true); +CometChat.getUnreadMessageCountForAllUsers(true); +CometChat.getUnreadMessageCountForAllGroups(true); ``` - +--- - +## Next Steps -It returns an object which will contain the GUID as the key and the unread message count as the value. + + + Track when messages are delivered and read by recipients + + + Show real-time typing status in conversations + + diff --git a/sdk/javascript/recording.mdx b/sdk/javascript/recording.mdx index 214d56bcd..4ca7df53e 100644 --- a/sdk/javascript/recording.mdx +++ b/sdk/javascript/recording.mdx @@ -1,22 +1,38 @@ --- title: "Recording (Beta)" +sidebarTitle: "Recording" +description: "Implement call recording for voice and video calls using the CometChat JavaScript SDK, including start/stop controls, listeners, and accessing recordings from the Dashboard." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Start recording +CometChatCalls.startRecording(); + +// Stop recording +CometChatCalls.stopRecording(); -This section will guide you to implement call recording feature for the voice and video calls. +// Listen for recording events (in CallSettings) +const callListener = new CometChatCalls.OngoingCallListener({ + onRecordingStarted: (event) => console.log("Recording started", event.user), + onRecordingStopped: () => console.log("Recording stopped"), +}); +``` -## Implementation +**Recordings are available on the [CometChat Dashboard](https://app.cometchat.com) → Calls section.** + -Once you have decided to implement [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call) calling and followed the steps to implement them. Just few additional listeners and methods will help you quickly implement call recording in your app. +Record voice and video calls for playback, compliance, or archival purposes. Recording is built on top of the [Call Session](/sdk/javascript/direct-call) — you add recording listeners to your call settings and optionally control recording programmatically. -You need to make changes in the CometChat.startCall method and add the required listeners for recording. Please make sure your callSettings is configured accordingly for [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call). +## Setup -A basic example of how to make changes to implement recording for a direct call/ a default call: +Add `onRecordingStarted` and `onRecordingStopped` callbacks to your `OngoingCallListener` when building call settings. These fire for all participants when any user starts or stops recording. - -```js + +```typescript // Add listeners onRecordingStarted and onRecordingStopped to the startCall method const defaultLayout = true; const audioOnly = false; @@ -37,7 +53,30 @@ const callSettings = new CometChatCalls.CallSettingsBuilder() const htmlElement = document.getElementById("ELEMENT_ID"); CometChatCalls.startSession(callToken, callSettings, htmlElement); ``` + + + +```js +// Add listeners onRecordingStarted and onRecordingStopped to the startCall method +const defaultLayout = true; +const audioOnly = false; + +const callListener = new CometChatCalls.OngoingCallListener({ + onRecordingStarted: (event) => + console.log("Listener => onRecordingStarted", event.user), + onRecordingStopped: () => + console.log("Listener => onRecordingStopped"), +}); + +const callSettings = new CometChatCalls.CallSettingsBuilder() + .enableDefaultLayout(defaultLayout) + .setIsAudioOnlyCall(audioOnly) + .setCallListener(callListener) + .build(); +const htmlElement = document.getElementById("ELEMENT_ID"); +CometChatCalls.startSession(callToken, callSettings, htmlElement); +``` @@ -49,8 +88,8 @@ const audioOnly = false; const callListener = new CometChatCalls.OngoingCallListener({ onRecordingStarted: (event) => console.log("Listener => onRecordingStarted", event.user), - onRecordingStopped: (event) => - console.log("Listener => onRecordingStopped", event.user), + onRecordingStopped: () => + console.log("Listener => onRecordingStopped"), }); const callSettings = new CometChatCalls.CallSettingsBuilder() @@ -67,33 +106,41 @@ CometChatCalls.startSession(callToken, callSettings, htmlElement); -## Settings for call recording +The `onRecordingStarted` callback receives an event object — see the [`OngoingCallListener`](/sdk/javascript/all-real-time-listeners#ongoing-call-listener-calls-sdk) reference for the full shape. + +The `onRecordingStopped` callback receives no arguments. -The `CallSettings`class allows you to customise the overall calling experience. The properties for the call/conference can be set using the `CallSettingsBuilder` class. This will eventually give you and object of the `CallSettings` class which you can pass to the `startSession()` method to start the call. + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + -The options available for recording of calls are: +## Settings for call recording + +## CallSettings Options -| Setting | Description | -| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `showRecordingButton(showRecordingButton: boolean)` | If set to `true` it displays the Recording button in the button Layout. if set to `false` it hides the Recording button in the button Layout. **Default value = false** | +| Setting | Description | +| ------- | ----------- | +| `showRecordingButton(showRecordingButton: boolean)` | If set to `true` it displays the Recording button in the button Layout. if set to `false` it hides the Recording button in the button Layout. **Default value = false** | | `startRecordingOnCallStart(startRecordingOnCallStart: boolean)` | If set to `true` call recording will start as soon as the call is started. if set to `false` call recording will not start as soon as the call is started. **Default value = false** | -For the use case where you wish to align your own custom buttons and not use the default layout provided by CometChat, you can embed the buttons in your layout and use the below methods to perform the corresponding operations: +## Programmatic Control + +If you're building a custom UI without the default layout, use these methods to control recording during an active call. ### Start Recording You can use the startRecording() method to start call recording. - -```javascript + +```typescript CometChatCalls.startRecording(); ``` - -```typescript + +```javascript CometChatCalls.startRecording(); ``` @@ -106,15 +153,15 @@ CometChatCalls.startRecording(); You can use the stopRecording() method to stop call recording. - -```javascript + +```typescript CometChatCalls.stopRecording(); ``` - -```typescript + +```javascript CometChatCalls.stopRecording(); ``` @@ -122,9 +169,9 @@ CometChatCalls.stopRecording(); -## Downloading Recording +## Downloading Recordings -Currently, the call recordings are available on the [CometChat Dashboard](https://app.cometchat.com/signup) under the Calls Section. Recordings can be accessed after clicking on the three dots menu icon to expand the menu and then select "View Recordings". You can refer to the below screenshot. You can refer to the below screenshot. +Call recordings are available on the [CometChat Dashboard](https://app.cometchat.com) under the Calls section. Click the three-dot menu and select "View Recordings". @@ -137,3 +184,16 @@ Currently, the call recordings are available on the [CometChat Dashboard](https: + +--- + +## Next Steps + + + + Implement ringing call flows with accept/reject functionality + + + Retrieve and display call history for users and groups + + diff --git a/sdk/javascript/resources-overview.mdx b/sdk/javascript/resources-overview.mdx index ea0d211bf..d2610212a 100644 --- a/sdk/javascript/resources-overview.mdx +++ b/sdk/javascript/resources-overview.mdx @@ -1,12 +1,32 @@ --- title: "Resources" sidebarTitle: "Overview" +description: "Access CometChat JavaScript SDK resources including real-time listeners reference, migration guides, and rate limits." --- +{/* TL;DR for Agents and Quick Reference */} + +- [All Real-Time Listeners](/sdk/javascript/all-real-time-listeners) — Complete listener reference +- [Upgrading from v3](/sdk/javascript/upgrading-from-v3) — Migration guide +- [Rate Limits](/sdk/javascript/rate-limits) — API rate limit details + We have a number of resources that will help you while integrating CometChat in your app. You can begin with the [all real-time listeners](/sdk/javascript/all-real-time-listeners) guide. If you're upgrading from v2, we recommend reading our [Upgrading from v3](/sdk/javascript/upgrading-from-v3) guide. + +--- + +## Next Steps + + + + Complete reference for all CometChat event listeners + + + Step-by-step migration guide from SDK v3 to v4 + + \ No newline at end of file diff --git a/sdk/javascript/retrieve-conversations.mdx b/sdk/javascript/retrieve-conversations.mdx index a58ef59d1..fedfba16c 100644 --- a/sdk/javascript/retrieve-conversations.mdx +++ b/sdk/javascript/retrieve-conversations.mdx @@ -1,10 +1,30 @@ --- title: "Retrieve Conversations" +sidebarTitle: "Retrieve Conversations" +description: "Fetch, filter, tag, and search conversations using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Fetch conversations list +const request = new CometChat.ConversationsRequestBuilder() + .setLimit(30).build(); +const conversations = await request.fetchNext(); + +// Get a specific conversation +const conversation = await CometChat.getConversation("UID", "user"); + +// Tag a conversation +await CometChat.tagConversation("UID", "user", ["archived"]); -Conversations provide the last messages for every one-on-one and group conversation the logged-in user is a part of. This makes it easy for you to build a **Recent Chat** list. +// Convert message to conversation +const conversation = await CometChat.CometChatHelper.getConversationFromMessage(message); +``` + + +Conversations provide the last message for every one-on-one and group conversation the logged-in user is part of. Each [`Conversation`](/sdk/reference/entities#conversation) object includes the other participant (user or group), the last message, unread counts, and optional tags. Use this to build a Recent Chats list. ## Retrieve List of Conversations @@ -12,23 +32,15 @@ Conversations provide the last messages for every one-on-one and group conversat To fetch the list of conversations, you can use the `ConversationsRequest` class. To use this class i.e. to create an object of the `ConversationsRequest` class, you need to use the `ConversationsRequestBuilder` class. The `ConversationsRequestBuilder` class allows you to set the parameters based on which the conversations are to be fetched. -The `ConversationsRequestBuilder` class allows you to set the below parameters: +Fetching using this builder will return [`Conversation`](/sdk/reference/entities#conversation) objects. + +The `ConversationsRequestBuilder` to fetch conversations with various filters. ### Set Limit -This method sets the limit i.e. the number of conversations that should be fetched in a single iteration. +Set the number of conversations to fetch per request. - -```javascript -let limit = 30; -let conversationRequest = new CometChat.ConversationsRequestBuilder() - .setLimit(limit) - .build(); -``` - - - ```typescript let limit: number = 30, @@ -39,30 +51,23 @@ let limit: number = 30, - - -### Set Conversation Type - -This method can be used to fetch user or group conversations specifically. The `conversationType` variable can hold one of the below two values: - -* user - Only fetches user conversation. -* group - Only fetches group conversations. - -If none is set, the list of conversations will include both user and group conversations. - - - + ```javascript let limit = 30; -let conversationType = "group"; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setConversationType(conversationType) .build(); ``` + + +### Set Conversation Type + +Filter by conversation type: `user` for one-on-one or `group` for group conversations. If not set, both types are returned. + + ```typescript let limit: number = 30, @@ -77,22 +82,48 @@ let limit: number = 30, + +The default value for `setLimit` is 30 and the max value is 50. + + +When conversations are fetched successfully, the response will include an array of `Conversation` objects filtered by the specified type. + +Relevant fields to access on returned conversations: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| conversationType | `getConversationType()` | `string` | Type of conversation (`"user"` or `"group"`) | + ### With User and Group Tags This method can be used to fetch the user/group tags in the `Conversation` Object. By default the value is `false`. - + ```javascript let limit = 30; +let conversationType = "group"; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .withUserAndGroupTags(true) + .setConversationType(conversationType) .build(); ``` + + + +Default limit is 30, maximum is 50. + + +When conversations are fetched successfully, the response includes an array of [`Conversation`](/sdk/reference/entities#conversation) objects filtered by the specified type. + +### With User and Group Tags + +Use `withUserAndGroupTags(true)` to include user/group tags in the response. Default is `false`. + + ```typescript let limit: number = 30, @@ -106,23 +137,39 @@ let limit: number = 30, +When conversations are fetched successfully, the response will include `tags` arrays on the `conversationWith` objects (user or group). + +Relevant fields to access on returned conversations: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| conversationWith tags | `getConversationWith().getTags()` | `string[]` | Tags associated with the user or group in the conversation | + ### Set User Tags This method fetches user conversations that have the specified tags. -```js +```javascript let limit = 30; -let userTags = ["tag1"]; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setUserTags(userTags) - .build(); + .withUserAndGroupTags(true) + .build(); ``` + + +When conversations are fetched successfully, the response includes `tags` arrays on the `conversationWith` objects. + +### Set User Tags + +Fetch user conversations where the user has specific tags. + + ```typescript let limit: number = 30, @@ -137,6 +184,14 @@ let limit: number = 30, +When conversations are fetched successfully, the response will include only user conversations where the user has the specified tags. + +Relevant fields to access on returned conversations: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| conversationWith tags | `getConversationWith().getTags()` | `string[]` | Tags associated with the user in the conversation | + ### Set Group Tags This method fetches group conversations that have the specified tags. @@ -145,15 +200,24 @@ This method fetches group conversations that have the specified tags. ```js let limit = 30; -let groupTags = ["tag1"]; +let userTags = ["tag1"]; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setGroupTags(groupTags) - .build(); + .setUserTags(userTags) + .build(); ``` + + +When conversations are fetched successfully, the response includes only user conversations where the user has the specified tags. + +### Set Group Tags + +Fetch group conversations where the group has specific tags. + + ```typescript let limit: number = 30, @@ -168,22 +232,40 @@ let limit: number = 30, +When conversations are fetched successfully, the response will include only group conversations where the group has the specified tags. + +Relevant fields to access on returned conversations: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| conversationWith tags | `getConversationWith().getTags()` | `string[]` | Tags associated with the group in the conversation | + ### With Tags This method makes sure that the tags associated with the conversations are returned along with the other details of the conversations. The default value for this parameter is `false` - + ```javascript let limit = 30; +let groupTags = ["tag1"]; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .withTags(true) + .setGroupTags(groupTags) .build(); ``` + + +When conversations are fetched successfully, the response includes only group conversations where the group has the specified tags. + +### With Tags + +Use `withTags(true)` to include conversation tags in the response. Default is `false`. + + ```typescript let limit: number = 30, @@ -197,23 +279,34 @@ conversationRequest: CometChat.ConversationsRequest = new CometChat.Conversation +Relevant fields to access on returned conversations: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the conversation | + ### Set Tags This method helps you fetch the conversations based on the specified tags. - + ```javascript let limit = 30; -let tags = ["archivedChat"]; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setTags(tags) + .withTags(true) .build(); ``` + +### Set Tags + +Fetch conversations that have specific tags. + + ```typescript let limit: number = 30, @@ -228,22 +321,35 @@ let limit: number = 30, +Relevant fields to access on returned conversations: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the conversation | + ### Include Blocked Users This method helps you fetch the conversations of users whom the logged-in user has blocked. -```js +```javascript let limit = 30; +let tags = ["archivedChat"]; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setIncludeBlockedUsers(true) + .setTags(tags) .build(); ``` + +### Include Blocked Users + +Use `setIncludeBlockedUsers(true)` to include conversations with users you've blocked. + + ```typescript let limit: number = 30, @@ -255,24 +361,26 @@ let limit: number = 30, - - -### With Blocked Info - -This method can be used to fetch the blocked information of the blocked user in the `ConversationWith` object. - - ```js let limit = 30; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setWithBlockedInfo(true) + .setIncludeBlockedUsers(true) .build(); ``` + + +When conversations are fetched successfully, the response includes conversations with blocked users. To also get blocked info details (`blockedByMe`, `blockedByMeAt`, `blockedAt`), set `withBlockedInfo` to `true`. + +### With Blocked Info + +Use `setWithBlockedInfo(true)` to include blocked user information in the response. + + ```typescript let limit: number = 30, @@ -284,11 +392,31 @@ let limit: number = 30, + +```js +let limit = 30; +let conversationRequest = new CometChat.ConversationsRequestBuilder() + .setLimit(limit) + .setWithBlockedInfo(true) + .build(); +``` + + + +Relevant fields to access on returned conversations: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| blockedByMe | `getConversationWith().getBlockedByMe()` | `boolean` | Whether the logged-in user has blocked this user | +| hasBlockedMe | `getConversationWith().getHasBlockedMe()` | `boolean` | Whether this user has blocked the logged-in user | +| blockedByMeAt | `getConversationWith().blockedByMeAt` | `number` | Timestamp when the logged-in user blocked this user | +| blockedAt | `getConversationWith().blockedAt` | `number` | Timestamp when this user was blocked | + ### Search Conversations -This method helps you search a conversation based on User or Group name. +Use `setSearchKeyword()` to search conversations by user or group name. @@ -297,17 +425,6 @@ This feature is only available with `Conversation & Advanced Search`. The `Conve - -```js -let limit = 30; -let conversationRequest = new CometChat.ConversationsRequestBuilder() - .setLimit(limit) - .setSearchKeyword("Hiking") - .build(); -``` - - - ```typescript let limit: number = 30, @@ -319,11 +436,24 @@ let limit: number = 30, + +```js +let limit = 30; +let conversationRequest = new CometChat.ConversationsRequestBuilder() + .setLimit(limit) + .setSearchKeyword("Hiking") + .build(); +``` + + + +When conversations are fetched successfully, the response includes conversations where the user or group name matches the search keyword. + ### Unread Conversations -This method helps you fetch unread conversations. +Use `setUnread(true)` to fetch only conversations with unread messages. @@ -332,17 +462,6 @@ This feature is only available with `Conversation & Advanced Search`. The `Conve - -```js -let limit = 30; -let conversationRequest = new CometChat.ConversationsRequestBuilder() - .setLimit(limit) - .setUnread(true) - .build(); -``` - - - ```typescript let limit: number = 30, @@ -354,24 +473,26 @@ let limit: number = 30, - - -### Hide Agentic Conversations - -This method allows you to exclude agent conversations from the conversation list. When set to `true`, conversations with AI agents will be filtered out. - - ```js let limit = 30; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setHideAgentic(true) + .setUnread(true) .build(); ``` + + +When conversations are fetched successfully, the response includes only conversations with unread messages (`unreadMessageCount` > 0). + +### Hide Agentic Conversations + +Use `setHideAgentic(true)` to exclude AI agent conversations from the list. + + ```typescript let limit: number = 30, @@ -383,24 +504,23 @@ let limit: number = 30, - - -### Only Agentic Conversations - -This method allows you to fetch only agent conversations. When set to `true`, only conversations with AI agents will be returned in the list. - - ```js let limit = 30; let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) - .setOnlyAgentic(true) + .setHideAgentic(true) .build(); ``` + +### Only Agentic Conversations + +Use `setOnlyAgentic(true)` to fetch only AI agent conversations. + + ```typescript let limit: number = 30, @@ -420,32 +540,38 @@ The `setHideAgentic()` and `setOnlyAgentic()` methods are mutually exclusive. Yo +When conversations are fetched successfully, the response will include only conversations with AI agents. Agent users have `role: "@agentic"` and include agent-specific metadata. Finally, once all the parameters are set to the builder class, you need to call the `build()` method to get the object of the `ConversationsRequest` class. -Once you have the object of the `ConversationsRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of `Conversation` objects containing X number of users depending on the limit set. +Once you have the object of the `ConversationsRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of [`Conversation`](/sdk/reference/entities#conversation) objects containing X number of users depending on the limit set. A Maximum of only 50 Conversations can be fetched at once. - + ```javascript let limit = 30; -let conversationsRequest = new CometChat.ConversationsRequestBuilder() +let conversationRequest = new CometChat.ConversationsRequestBuilder() .setLimit(limit) + .setOnlyAgentic(true) .build(); - -conversationsRequest.fetchNext().then( - (conversationList) => { - console.log("Conversations list received:", conversationList); - }, - (error) => { - console.log("Conversations list fetching failed with error:", error); - } -); ``` + + + +`setHideAgentic()` and `setOnlyAgentic()` are mutually exclusive — use only one per request. + + +When conversations are fetched successfully, the response includes only AI agent conversations. Agent users have `role: "@agentic"`. + +### Fetch Conversations + +After configuring the builder, call `build()` to create the request, then `fetchNext()` to retrieve conversations. Maximum 50 per request. Call `fetchNext()` repeatedly on the same object to paginate. + + ```typescript let limit: number = 30, @@ -465,50 +591,40 @@ conversationsRequest.fetchNext().then( - - -The `Conversation` Object consists of the following fields: - -| Field | Information | -| ------------------ | ----------------------------------------------------------------- | -| conversationId | ID of the conversation. | -| conversationType | Type of conversation. (user/group) | -| lastMessage | Last message the conversation. | -| conversationWith | User or Group object containing the details of the user or group. | -| unreadMessageCount | Unread message count for the conversation. | - -## Tag Conversation - -*In other words, as a logged-in user, how do I tag a conversation?* - -To tag a specific conversation, you can use the `tagConversation()` method. The `tagConversation()` method accepts three parameters. - -1. `conversationWith`: UID/GUID of the user/group whose conversation you want to fetch. - -2. `conversationType`: The `conversationType` variable can hold one of the below two values: - - 1. user - Only fetches user conversation. - 2. group - Only fetches group conversations. - -3. `tags`: The `tags` variable will be a list of tags you want to add to a conversation. - - - + ```javascript -let tags = ["archivedChat"]; +let limit = 30; +let conversationsRequest = new CometChat.ConversationsRequestBuilder() + .setLimit(limit) + .build(); -CometChat.tagConversation("conversationWith", "conversationType", tags).then( - (conversation) => { - console.log("conversation", conversation); +conversationsRequest.fetchNext().then( + (conversationList) => { + console.log("Conversations list received:", conversationList); }, (error) => { - console.log("error while fetching a conversation", error); + console.log("Conversations list fetching failed with error:", error); } ); ``` + + +The `fetchNext()` method returns an array of [`Conversation`](/sdk/reference/entities#conversation) objects. + +## Tag Conversation + +Use `tagConversation()` to add tags to a conversation. + +| Parameter | Description | +| --- | --- | +| `conversationWith` | UID or GUID of the user/group | +| `conversationType` | `user` or `group` | +| `tags` | Array of tags to add | + + ```typescript let conversationWith: string = "UID", @@ -535,6 +651,16 @@ The tags for conversations are one-way. This means that if user A tags a convers +When the conversation is tagged successfully, the response will return a single `Conversation` object (not an array) with the `tags` field included. + +The `tagConversation()` method returns a [`Conversation`](/sdk/reference/entities#conversation) object with the `tags` field populated. + +Relevant fields to access on returned conversation: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags applied to the conversation | + ## Retrieve Single Conversation *In other words, as a logged-in user, how do I retrieve a specific conversation?* @@ -549,9 +675,14 @@ To fetch a specific conversation, you can use the `getConversation` method. The 2. group - Only fetches group conversations. - + ```javascript -CometChat.getConversation("conversationWith", "conversationType").then( +let tags = ["archivedChat"]; + +let conversationWith = "UID"; +let conversationType = "user"; + +CometChat.tagConversation(conversationWith, conversationType, tags).then( (conversation) => { console.log("conversation", conversation); }, @@ -563,6 +694,24 @@ CometChat.getConversation("conversationWith", "conversationType").then( + + + +Conversation tags are one-way. If user A tags a conversation with user B, that tag only applies for user A. + + +When the conversation is tagged successfully, the response returns a [`Conversation`](/sdk/reference/entities#conversation) object with the `tags` field. + +## Retrieve Single Conversation + +Use `getConversation()` to fetch a specific conversation. + +| Parameter | Description | +| --- | --- | +| `conversationWith` | UID or GUID of the user/group | +| `conversationType` | `user` or `group` | + + ```typescript let conversationWith: string = "UID", @@ -582,24 +731,41 @@ CometChat.getConversation(conversationWith, conversationType).then( +When the conversation is fetched successfully, the response will return a single `Conversation` object (not an array). + +The `getConversation()` method returns a single [`Conversation`](/sdk/reference/entities#conversation) object. + ## Convert Messages to Conversations As per our [receive messages](/sdk/javascript/receive-message) guide, for real-time messages, you will always receive `Message` objects and not `Conversation` objects. Thus, you will need a mechanism to convert the Message object to the `Conversation` object. You can use the `getConversationFromMessage(BaseMessage message)` of the `CometChatHelper` class. - + ```javascript -CometChat.CometChatHelper.getConversationFromMessage(message).then( +let conversationWith = "UID"; +let conversationType = "user"; + +CometChat.getConversation(conversationWith, conversationType).then( (conversation) => { - console.log("Conversation Object", conversation); - }, (error) => { - console.log("Error while converting message object", error); + console.log("conversation", conversation); + }, + (error) => { + console.log("error while fetching a conversation", error); } ); ``` + + +When the conversation is fetched successfully, the response returns a single [`Conversation`](/sdk/reference/entities#conversation) object. + +## Convert Messages to Conversations + +Use `CometChatHelper.getConversationFromMessage()` to convert a received message into a [`Conversation`](/sdk/reference/entities#conversation) object. Useful for updating your Recent Chats list when receiving real-time messages. + + ```typescript let message: CometChat.TextMessage | CometChat.MediaMessage | CometChat.CustomMessage; @@ -615,10 +781,36 @@ CometChat.CometChatHelper.getConversationFromMessage(message).then( + +```javascript +CometChat.CometChatHelper.getConversationFromMessage(message).then( + (conversation) => { + console.log("Conversation Object", conversation); + }, (error) => { + console.log("Error while converting message object", error); + } +); +``` + + + +When converting a message to a conversation, `unreadMessageCount` and `tags` won't be available. Manage unread counts in your client-side code. + -While converting the `Message` object to the `Conversation` object, the `unreadMessageCount` & `tags` will not be available in the `Conversation` object. The unread message count needs to be managed in your client-side code. +The `getConversationFromMessage()` method returns a [`Conversation`](/sdk/reference/entities#conversation) object. - +--- + +## Next Steps + + + + Remove conversations from the logged-in user's list + + + Show real-time typing status in conversations + + diff --git a/sdk/javascript/retrieve-group-members.mdx b/sdk/javascript/retrieve-group-members.mdx index 3e21b909d..db20762c9 100644 --- a/sdk/javascript/retrieve-group-members.mdx +++ b/sdk/javascript/retrieve-group-members.mdx @@ -1,33 +1,39 @@ --- title: "Retrieve Group Members" +sidebarTitle: "Retrieve Members" +description: "Fetch and filter group members by scope, status, and search keyword using the CometChat JavaScript SDK with pagination support." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Fetch group members +const request = new CometChat.GroupMembersRequestBuilder("GUID") + .setLimit(30).build(); +const members = await request.fetchNext(); + +// Filter by scope +const request = new CometChat.GroupMembersRequestBuilder("GUID") + .setLimit(30).setScopes(["admin", "moderator"]).build(); + +// Search members +const request = new CometChat.GroupMembersRequestBuilder("GUID") + .setLimit(30).setSearchKeyword("john").build(); +``` + ## Retrieve the List of Group Members -In order to fetch the list of groups members for a group, you can use the `GroupMembersRequest` class. To use this class i.e to create an object of the GroupMembersRequest class, you need to use the `GroupMembersRequestBuilder` class. The `GroupMembersRequestBuilder` class allows you to set the parameters based on which the groups are to be fetched. +Use `GroupMembersRequestBuilder` to fetch members of a [Group](/sdk/reference/entities#group). The GUID must be specified in the constructor. -The `GroupMembersRequestBuilder` class allows you to set the below parameters: - -The GUID of the group for which the members are to be fetched must be specified in the constructor of the `GroupMembersRequestBuilder` class. +Fetching using this builder will return [`GroupMember`](/sdk/reference/entities#groupmember) objects. `GroupMember` extends [`User`](/sdk/reference/entities#user) and adds group-specific fields. ### Set Limit -This method sets the limit i.e. the number of members that should be fetched in a single iteration. +Sets the number of members to fetch per request. - -```javascript -let GUID = "GUID"; -let limit = 30; -let groupMembersRequest = new CometChat.GroupMembersRequestBuilder(GUID) - .setLimit(limit) - .build(); -``` - - - ```typescript let GUID: string = "GUID"; @@ -39,26 +45,24 @@ let groupMembersRequest: CometChat.GroupMembersRequest = new CometChat.GroupMemb - - -### Set Search Keyword - -This method allows you to set the search string based on which the group members are to be fetched. - - - + ```javascript let GUID = "GUID"; let limit = 30; -let searchKeyword = "super"; let groupMembersRequest = new CometChat.GroupMembersRequestBuilder(GUID) .setLimit(limit) - .setSearchKeyword(searchKeyword) - .build(); + .build(); ``` + + +### Set Search Keyword + +Filters members by a search string. + + ```typescript let GUID: string = "GUID"; @@ -72,26 +76,26 @@ let groupMembersRequest: CometChat.GroupMembersRequest = new CometChat.GroupMemb - - -### Set Scopes - -This method allows you to fetch group members based on multiple scopes. - - - + ```javascript let GUID = "GUID"; let limit = 30; -let scopes = ["admin", "moderator"]; +let searchKeyword = "super"; let groupMembersRequest = new CometChat.GroupMembersRequestBuilder(GUID) .setLimit(limit) - .setScopes(scopes) + .setSearchKeyword(searchKeyword) .build(); ``` + + +### Set Scopes + +Filters members by one or more scopes (`admin`, `moderator`, `participant`). + + ```typescript let GUID: string = "GUID"; @@ -107,6 +111,12 @@ let groupMembersRequest: CometChat.GroupMembersRequest = new CometChat.GroupMemb +Relevant fields to access on returned members: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| scope | `getScope()` | `string` | Scope of the member in the group (`"admin"`, `"moderator"`, or `"participant"`) | + ### Set Status The status based on which the group members are to be fetched. The status parameter can contain one of the below two values: @@ -117,18 +127,33 @@ The status based on which the group members are to be fetched. The status parame If this parameter is not set, will return all the group members regardless of their status. - + ```javascript let GUID = "GUID"; let limit = 30; +let scopes = ["admin", "moderator"]; let groupMembersRequest = new CometChat.GroupMembersRequestBuilder(GUID) .setLimit(limit) - .setStatus(CometChat.USER_STATUS.ONLINE) + .setScopes(scopes) .build(); ``` + + +### Set Status + +Filters members by online status: + +| Value | Description | +|-------|-------------| +| `CometChat.USER_STATUS.ONLINE` | Only online members | +| `CometChat.USER_STATUS.OFFLINE` | Only offline members | + +If not set, returns all members regardless of status. + + ```typescript let GUID: string = "GUID"; @@ -143,30 +168,34 @@ let groupMembersRequest: CometChat.GroupMembersRequest = new CometChat.GroupMemb +Relevant fields to access on returned members: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| status | `getStatus()` | `string` | Online status of the member (`"online"` or `"offline"`) | + Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the `GroupMembersRequest` class. Once you have the object of the `GroupMembersRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of `GroupMember` objects containing n number of members where n is the limit set in the builder class. - + ```javascript let GUID = "GUID"; let limit = 30; -let groupMemberRequest = new CometChat.GroupMembersRequestBuilder(GUID) +let groupMembersRequest = new CometChat.GroupMembersRequestBuilder(GUID) .setLimit(limit) + .setStatus(CometChat.USER_STATUS.ONLINE) .build(); - -groupMemberRequest.fetchNext().then( -groupMembers => { - console.log("Group Member list fetched successfully:", groupMembers); -}, error => { - console.log("Group Member list fetching failed with exception:", error); -} -); ``` + + +Once configured, call `build()` to create the request, then `fetchNext()` to retrieve members. + + ```typescript let GUID: string = "GUID"; @@ -186,4 +215,38 @@ groupMembersRequest.fetchNext().then( + +```javascript +let GUID = "GUID"; +let limit = 30; +let groupMemberRequest = new CometChat.GroupMembersRequestBuilder(GUID) + .setLimit(limit) + .build(); + +groupMemberRequest.fetchNext().then( +groupMembers => { + console.log("Group Member list fetched successfully:", groupMembers); +}, error => { + console.log("Group Member list fetching failed with exception:", error); +} +); +``` + + + + +The `fetchNext()` method returns an array of [`GroupMember`](/sdk/reference/entities#groupmember) objects. `GroupMember` extends [`User`](/sdk/reference/entities#user) and adds group-specific fields. + +--- + +## Next Steps + + + + Add users to a group programmatically + + + Remove or ban members from a group + + diff --git a/sdk/javascript/retrieve-groups.mdx b/sdk/javascript/retrieve-groups.mdx index 92a074c0d..81a27bff5 100644 --- a/sdk/javascript/retrieve-groups.mdx +++ b/sdk/javascript/retrieve-groups.mdx @@ -1,8 +1,31 @@ --- title: "Retrieve Groups" +sidebarTitle: "Retrieve Groups" +description: "Fetch, filter, and search groups using the CometChat JavaScript SDK. Includes pagination, tag-based filtering, joined-only groups, and online member counts." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Fetch groups list +const request = new CometChat.GroupsRequestBuilder() + .setLimit(30).build(); +const groups = await request.fetchNext(); + +// Get specific group details +const group = await CometChat.getGroup("GUID"); + +// Fetch only joined groups +const request = new CometChat.GroupsRequestBuilder() + .setLimit(30).joinedOnly(true).build(); + +// Get online member count +const count = await CometChat.getOnlineGroupMemberCount(["GUID"]); +``` + + +Fetch the list of [`Group`](/sdk/reference/entities#group) objects the logged-in user can see, get details for a specific group, or check online member counts. ## Retrieve List of Groups @@ -10,15 +33,17 @@ title: "Retrieve Groups" In order to fetch the list of groups, you can use the `GroupsRequest` class. To use this class i.e to create an object of the `GroupsRequest` class, you need to use the `GroupsRequestBuilder` class. The `GroupsRequestBuilder` class allows you to set the parameters based on which the groups are to be fetched. -The `GroupsRequestBuilder` class allows you to set the below parameters: +Fetching using this builder will return [`Group`](/sdk/reference/entities#group) objects + +Use `GroupsRequestBuilder` to fetch groups with filtering, searching, and pagination. ### Set Limit -This method sets the limit i.e. the number of groups that should be fetched in a single iteration. +Sets the number of groups to fetch per request. - -```javascript + +```typescript let limit = 30; let groupsRequest = new CometChat.GroupsRequestBuilder() .setLimit(limit) @@ -27,8 +52,8 @@ let groupsRequest = new CometChat.GroupsRequestBuilder() - -```typescript + +```javascript let limit = 30; let groupsRequest = new CometChat.GroupsRequestBuilder() .setLimit(limit) @@ -41,21 +66,9 @@ let groupsRequest = new CometChat.GroupsRequestBuilder() ### Set Search Keyword -This method allows you to set the search string based on which the groups are to be fetched. +Filters groups by a search string. - -```javascript -let limit = 30; -let searchKeyword = "group"; -let groupsRequest = new CometChat.GroupsRequestBuilder() - .setLimit(limit) - .setSearchKeyword(searchKeyword) - .build(); -``` - - - ```typescript let limit: number = 30; @@ -68,24 +81,25 @@ let groupsRequest: CometChat.GroupsRequest = new CometChat.GroupsRequestBuilder( - - -### Joined Only - -This method when used, will ask the SDK to only return the groups that the user has joined or is a part of. - - - + ```javascript let limit = 30; +let searchKeyword = "group"; let groupsRequest = new CometChat.GroupsRequestBuilder() .setLimit(limit) - .joinedOnly(true) + .setSearchKeyword(searchKeyword) .build(); ``` + + +### Joined Only + +When `true`, returns only groups the logged-in user has joined. + + ```typescript let limit: number = 30; @@ -97,25 +111,24 @@ let groupsRequest: CometChat.GroupsRequest = new CometChat.GroupsRequestBuilder( - - -### Set Tags - -This method accepts a list of tags based on which the list of groups is to be fetched. The list fetched will only contain the groups that have been tagged with the specified tags. - - - + ```javascript let limit = 30; -let tags = ["tag1", "tag2"]; let groupsRequest = new CometChat.GroupsRequestBuilder() .setLimit(limit) - .setTags(tags) + .joinedOnly(true) .build(); ``` + + +### Set Tags + +Filters groups by specified tags. + + ```typescript let limit: number = 30; @@ -128,24 +141,25 @@ let groupsRequest: CometChat.GroupsRequest = new CometChat.GroupsRequestBuilder( - - -### With Tags - -This property when set to true will fetch tags data along with the list of groups. - - - + ```javascript let limit = 30; +let tags = ["tag1", "tag2"]; let groupsRequest = new CometChat.GroupsRequestBuilder() .setLimit(limit) - .withTags(true) - .build(); + .setTags(tags) + .build(); ``` + + +### With Tags + +When `true`, includes tag data in the returned group objects. + + ```typescript let limit: number = 30; @@ -159,6 +173,12 @@ let groupsRequest: CometChat.GroupsRequest = new CometChat.GroupsRequestBuilder( +Relevant fields to access on returned groups: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the group | + Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the `GroupsRequest` class. Once you have the object of the `GroupsRequest` class, you need to call the `fetchNext()` method. Calling this method will return a list of `Group` objects containing n number of groups where n is the limit set in the builder class. @@ -166,24 +186,26 @@ Once you have the object of the `GroupsRequest` class, you need to call the `fet The list of groups fetched will only have the public and password type groups. The private groups will only be available if the user is a member of the group. - + ```javascript let limit = 30; let groupsRequest = new CometChat.GroupsRequestBuilder() .setLimit(limit) - .build(); - -groupsRequest.fetchNext().then( -groupList => { - console.log("Groups list fetched successfully", groupList); -}, error => { - console.log("Groups list fetching failed with error", error); -} -); + .withTags(true) + .build(); ``` + + +After configuring the builder, call `build()` to get the `GroupsRequest` object, then call `fetchNext()` to retrieve groups. + + +The list only includes public and password-protected groups. Private groups appear only if the user is a member. + + + ```typescript let limit: number = 30; @@ -202,32 +224,36 @@ groupsRequest.fetchNext().then( - - -## Retrieve Particular Group Details - -*In other words, as a logged-in user, how do I retrieve information for a specific group?* - -To get the information of a group, you can use the `getGroup()` method. - - - + ```javascript -var GUID = "GUID"; -CometChat.getGroup(GUID).then( -group => { - console.log("Group details fetched successfully:", group); +let limit = 30; +let groupsRequest = new CometChat.GroupsRequestBuilder() + .setLimit(limit) + .build(); + +groupsRequest.fetchNext().then( +groupList => { + console.log("Groups list fetched successfully", groupList); }, error => { - console.log("Group details fetching failed with exception:", error); + console.log("Groups list fetching failed with error", error); } -); +); ``` + + +The `fetchNext()` method returns an array of [`Group`](/sdk/reference/entities#group) objects. + +## Retrieve Particular Group Details + +Use `getGroup()` to fetch a specific group's details by GUID. + + ```typescript -var GUID: string = "GUID"; +const GUID: string = "GUID"; CometChat.getGroup(GUID).then( (group: CometChat.Group) => { console.log("Group details fetched successfully:", group); @@ -239,33 +265,33 @@ CometChat.getGroup(GUID).then( - - -| Parameter | Description | -| --------- | ------------------------------------------------------------ | -| `GUID` | The GUID of the group for whom the details are to be fetched | - -It returns `Group` object containing the details of the group. - -## Get online group member count - -To get the total count of online users in particular groups, you can use the `getOnlineGroupMemberCount()` method. - - - + ```javascript -let guids = ["cometchat-guid-1"]; -CometChat.getOnlineGroupMemberCount(guids).then( -groupMemberCount => { - console.log("Total online user for specified groups:", groupMemberCount); +const GUID = "GUID"; +CometChat.getGroup(GUID).then( +group => { + console.log("Group details fetched successfully:", group); }, error => { - console.log("Online group member count fetching failed with error:", error); + console.log("Group details fetching failed with exception:", error); } -); +); ``` + + +| Parameter | Description | +| --------- | ------------------------------ | +| `GUID` | The GUID of the group to fetch | + +The method returns a [`Group`](/sdk/reference/entities#group) object. + +## Get Online Group Member Count + +Use `getOnlineGroupMemberCount()` to get the number of online members in specified groups. + + ```typescript let guids: String[] = ["cometchat-guid-1"]; @@ -280,6 +306,35 @@ CometChat.getOnlineGroupMemberCount(guids).then( + +```javascript +let guids = ["cometchat-guid-1"]; +CometChat.getOnlineGroupMemberCount(guids).then( +groupMemberCount => { + console.log("Total online user for specified groups:", groupMemberCount); +}, error => { + console.log("Online group member count fetching failed with error:", error); +} +); +``` + + + -This method returns a JSON Object with the GUID as the key and the online member count for that group as the value. +Returns an object with GUIDs as keys and online member counts as values. + +`getOnlineGroupMemberCount()` resolves with a `{ guid: count }` object where each key is a group GUID and its value is the number of currently online members in that group. + +--- + +## Next Steps + + + + Create public, private, or password-protected groups + + + Fetch and filter members of a specific group + + diff --git a/sdk/javascript/retrieve-users.mdx b/sdk/javascript/retrieve-users.mdx index 943df6404..a9763aa8d 100644 --- a/sdk/javascript/retrieve-users.mdx +++ b/sdk/javascript/retrieve-users.mdx @@ -1,26 +1,34 @@ --- title: "Retrieve Users" +sidebarTitle: "Retrieve Users" +description: "Fetch, filter, search, and sort users using the CometChat JavaScript SDK. Includes pagination, role-based filtering, tag support, and online user counts." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Fetch users list +const request = new CometChat.UsersRequestBuilder() + .setLimit(30).build(); +const users = await request.fetchNext(); -## Retrieve Logged In User Details +// Get specific user details +const user = await CometChat.getUser("UID"); -You can get the details of the logged-in user using the `getLoggedInUser()` method. This method can also be used to check if the user is logged in or not. If the method returns `Promise` with reject callback, it indicates that the user is not logged in and you need to log the user into CometChat SDK. +// Get logged-in user +const me = await CometChat.getLoggedinUser(); - - -```javascript -CometChat.getLoggedinUser().then( -user => { - console.log("user details:", { user }); -}, error => { - console.log("error getting details:", { error }); -} -); +// Get online user count +const count = await CometChat.getOnlineUserCount(); ``` + - +## Retrieve Logged In User Details + +Use `getLoggedInUser()` to get the current user's details. This method also verifies if a user is logged in — a rejected promise indicates no user is logged in. + + ```typescript @@ -35,30 +43,36 @@ CometChat.getLoggedinUser().then( + +```javascript +CometChat.getLoggedinUser().then( +user => { + console.log("user details:", { user }); +}, error => { + console.log("error getting details:", { error }); +} +); +``` + + + -This method will return a `User` object containing all the information related to the logged-in user. +This method returns a [`User`](/sdk/reference/entities#user) object with the logged-in user's information ## Retrieve List of Users In order to fetch the list of users, you can use the `UsersRequest` class. To use this class i.e to create an object of the `UsersRequest` class, you need to use the `UsersRequestBuilder` class. The `UsersRequestBuilder` class allows you to set the parameters based on which the users are to be fetched. +Fetching using this builder will return [`User`](/sdk/reference/entities#user) objects + The `UsersRequestBuilder` class allows you to set the below parameters: ### Set Limit -This method sets the limit i.e. the number of users that should be fetched in a single iteration. +Sets the number of users to fetch per request. - -```javascript -let limit = 30; -let usersRequest = new CometChat.UsersRequestBuilder() - .setLimit(limit) - .build(); -``` - - ```typescript @@ -70,25 +84,24 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() - - -### Set Search Keyword - -This method allows you to set the search string based on which the users are to be fetched. - - - + ```javascript let limit = 30; -let searchKeyword = "super"; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .setSearchKeyword(searchKeyword) .build(); ``` + + +### Set Search Keyword + +Filters users by a search string. + + + ```typescript let limit: number = 30; @@ -101,27 +114,26 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() - - -### Search In - -This method allows you to define in which user property should the searchKeyword be searched. This method only works in combination with `setSearchKeyword()`. By default the keyword is searched in both UID & Name. - - -```js +```javascript let limit = 30; let searchKeyword = "super"; -let searchIn = ["uid", "name"]; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) .setSearchKeyword(searchKeyword) - .searchIn(searchIn) .build(); ``` + + +### Search In + +Specifies which user properties to search. Works with `setSearchKeyword()`. By default, searches both UID and name. + + + ```typescript let limit: number = 30; @@ -136,28 +148,32 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() + +```js +let limit = 30; +let searchKeyword = "super"; +let searchIn = ["uid", "name"]; +let usersRequest = new CometChat.UsersRequestBuilder() + .setLimit(limit) + .setSearchKeyword(searchKeyword) + .searchIn(searchIn) + .build(); +``` + + + ### Set Status -The status based on which the users are to be fetched. The status parameter can contain one of the below two values: +Filters users by online status: -* CometChat.USER\_STATUS.ONLINE - will return the list of only online users. -* CometChat.USER\_STATUS.OFFLINE - will return the list of only offline users. +- `CometChat.USER_STATUS.ONLINE` — Only online users +- `CometChat.USER_STATUS.OFFLINE` — Only offline users -If this parameter is not set, will return all the available users. +If not set, returns all users. - -```javascript -let limit = 30; -let usersRequest = new CometChat.UsersRequestBuilder() - .setLimit(limit) - .setStatus(CometChat.USER_STATUS.ONLINE) - .build() -``` - - ```typescript @@ -172,22 +188,35 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() +Relevant fields to access on returned users: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| status | `getStatus()` | `string` | Online status of the user (`"online"` or `"offline"`) | + ### Hide Blocked Users This method is used to determine if the blocked users should be returned as a part of the user list. If set to true, the user list will not contain the users blocked by the logged in user. - + ```javascript let limit = 30; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .hideBlockedUsers(true) - .build(); + .setStatus(CometChat.USER_STATUS.ONLINE) + .build() ``` + + +### Hide Blocked Users + +When `true`, excludes users blocked by the logged-in user from the results. + + ```typescript let limit: number = 30; @@ -199,25 +228,24 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() - - -### Set Roles - -This method allows you to fetch the users based on multiple roles. - - - + ```javascript let limit = 30; -let roles = ["default", "dev"]; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .setRoles(roles) + .hideBlockedUsers(true) .build(); ``` + + +### Set Roles + +Filters users by specified roles. + + ```typescript let limit: number = 30; @@ -232,22 +260,36 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() +Relevant fields to access on returned users: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| role | `getRole()` | `string` | Role assigned to the user | + ### Friends Only This property when set to true will return only the friends of the logged-in user. - + ```javascript let limit = 30; +let roles = ["default", "dev"]; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .friendsOnly(true) + .setRoles(roles) .build(); ``` + + +### Friends Only + +When `true`, returns only friends of the logged-in user. + + ```typescript let limit: number = 30; @@ -259,25 +301,24 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() - - -### Set Tags - -This method accepts a list of tags based on which the list of users is to be fetched. The list fetched will only contain the users that have been tagged with the specified tags. - - - + ```javascript let limit = 30; -let tags = ["tag1", "tag2"]; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .setTags(tags) + .friendsOnly(true) .build(); ``` + + +### Set Tags + +Filters users by specified tags. + + ```typescript let limit: number = 30; @@ -292,22 +333,36 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() +Relevant fields to access on returned users: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the user | + ### With Tags This property when set to true will fetch tags data along with the list of users. - + ```javascript let limit = 30; +let tags = ["tag1", "tag2"]; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .withTags(true) + .setTags(tags) .build(); ``` + + +### With Tags + +When `true`, includes tag data in the returned user objects. + + ```typescript let limit: number = 30; @@ -321,23 +376,35 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() +Relevant fields to access on returned users: + +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the user | + ### Set UIDs This method accepts a list of UIDs based on which the list of users is fetched. A maximum of `25` users can be fetched. - + ```javascript let limit = 30; -let UIDs = ["cometchat-uid-1", "cometchat-uid-2"]; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .setUIDs(UIDs) + .withTags(true) .build(); ``` + + +### Set UIDs + +Fetches specific users by their UIDs. Maximum 25 users per request. + + ```typescript let limit: number = 30; @@ -350,26 +417,25 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() - - -### Sort By - -This method allows you to sort the User List by a specific property of User. By default the User List is sorted by `status => name => UID` . If `name` is pass to the `sortBy()` method the user list will be sorted by `name => UID`. - - -```js +```javascript let limit = 30; let UIDs = ["cometchat-uid-1", "cometchat-uid-2"]; -let sortBy = "name"; let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .sortBy(sortBy) + .setUIDs(UIDs) .build(); ``` + + +### Sort By + +Sorts the user list by a specific property. Default sort order: `status → name → UID`. Pass `"name"` to sort by `name → UID`. + + ```typescript let limit: number = 30; @@ -382,18 +448,31 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() + +```js +let limit = 30; +let UIDs = ["cometchat-uid-1", "cometchat-uid-2"]; +let sortBy = "name"; +let usersRequest = new CometChat.UsersRequestBuilder() + .setLimit(limit) + .sortBy(sortBy) + .build(); +``` + + + ### Sort By Order -This method allows you to sort the User List in a specific order. By default the user list is sorted in ascending order. +Sets the sort order. Default is ascending (`"asc"`). Use `"desc"` for descending. - -```js -let limit = 30; -let sortByOrder = "desc"; -let usersReques = new CometChat.UsersRequestBuilder() + +```typescript +let limit: number = 30; +let sortOrder: string = "desc"; +let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) .sortByOrder(sortOrder) .build(); @@ -401,13 +480,13 @@ let usersReques = new CometChat.UsersRequestBuilder() - -```typescript -let limit: number = 30; -let sortOrder: string = "desc"; -let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() + +```js +let limit = 30; +let sortOrder = "desc"; +let usersRequest = new CometChat.UsersRequestBuilder() .setLimit(limit) - .sortOrder(sortOrder) + .sortByOrder(sortOrder) .build(); ``` @@ -415,29 +494,9 @@ let usersRequest: CometChat.UsersRequest = new CometChat.UsersRequestBuilder() -Finally, once all the parameters are set to the builder class, you need to call the build() method to get the object of the UsersRequest class. - -Once you have the object of the UsersRequest class, you need to call the fetchNext() method. Calling this method will return a list of User objects containing n number of users where n is the limit set in the builder class. +After configuring the builder, call `build()` to get the `UsersRequest` object, then call `fetchNext()` to retrieve users. - -```javascript -var limit = 30; -var usersRequest = new CometChat.UsersRequestBuilder() -.setLimit(limit) -.build(); - -usersRequest.fetchNext().then( -userList => { - console.log("User list received:", userList); -}, error => { - console.log("User list fetching failed with error:", error); -} -); -``` - - - ```typescript let limit: number = 30; @@ -456,27 +515,33 @@ usersRequest.fetchNext().then( - - -## Retrieve Particular User Details - -To get the information of a user, you can use the `getUser()` method. - - - + ```javascript -let UID = "UID"; -CometChat.getUser(UID).then( -user => { - console.log("User details fetched for user:", user); +const limit = 30; +const usersRequest = new CometChat.UsersRequestBuilder() +.setLimit(limit) +.build(); + +usersRequest.fetchNext().then( +userList => { + console.log("User list received:", userList); }, error => { - console.log("User details fetching failed with error:", error); + console.log("User list fetching failed with error:", error); } ); ``` + + +The `fetchNext()` method returns an array of [`User`](/sdk/reference/entities#user) objects. + +## Retrieve Particular User Details + +Use `getUser()` to fetch a specific user's details by UID. + + ```typescript let UID: string = "UID"; @@ -491,34 +556,37 @@ CometChat.getUser(UID).then( + +```javascript +let UID = "UID"; +CometChat.getUser(UID).then( +user => { + console.log("User details fetched for user:", user); +}, error => { + console.log("User details fetching failed with error:", error); +} +); +``` + + + -The `getUser()` method takes the following parameters: +| Parameter | Description | +| --------- | ----------- | +| UID | The UID of the user to fetch | | Parameter | Description | | --------- | ---------------------------------------------------------- | | UID | The UID of the user for whom the details are to be fetched | -It returns the `User` object containing the details of the user. +It returns the [`User`](/sdk/reference/entities#user) object containing the details of the user. -## Get online user count +## Get Online User Count -To get the total count of online users for your app, you can use the `getOnlineUserCount()` method. +Use `getOnlineUserCount()` to get the total number of online users in your app. - -```javascript -CometChat.getOnlineUserCount().then( -userCount => { - console.log("Total online user count:", userCount); -}, error => { - console.log("Online user count fetching failed with error:", error); -} -); -``` - - - ```typescript CometChat.getOnlineUserCount().then( @@ -532,6 +600,34 @@ CometChat.getOnlineUserCount().then( + +```javascript +CometChat.getOnlineUserCount().then( +userCount => { + console.log("Total online user count:", userCount); +}, error => { + console.log("Online user count fetching failed with error:", error); +} +); +``` + + + -This method returns the total online user count for your app. +Returns the total online user count as a number. + +`getOnlineUserCount()` resolves with a `number` representing the total count of currently online users in your app. + +--- + +## Next Steps + + + + Track and subscribe to user online/offline status + + + Block and unblock users from your application + + diff --git a/sdk/javascript/send-message.mdx b/sdk/javascript/send-message.mdx index ae9f8e125..2d5cffe86 100644 --- a/sdk/javascript/send-message.mdx +++ b/sdk/javascript/send-message.mdx @@ -1,81 +1,34 @@ --- -title: "Send A Message" +title: "Send Messages" +sidebarTitle: "Send Messages" +description: "Send text, media, and custom messages to users and groups using the CometChat JavaScript SDK." --- + +| Field | Value | +| --- | --- | +| Key Classes | [`TextMessage`](/sdk/reference/messages#textmessage), [`MediaMessage`](/sdk/reference/messages#mediamessage), [`CustomMessage`](/sdk/reference/messages#custommessage) | +| Key Methods | `sendMessage()`, `sendMediaMessage()`, `sendCustomMessage()` | +| Receiver Types | `CometChat.RECEIVER_TYPE.USER`, `CometChat.RECEIVER_TYPE.GROUP` | +| Message Types | `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `FILE`, `CUSTOM` | +| Prerequisites | SDK initialized, user logged in | -Using CometChat, you can send three types of messages: + -1. [Text Message](/sdk/javascript/send-message#text-message) is the most common and standard message type. -2. [Media Message](/sdk/javascript/send-message#media-message) for sending photos, videos and files. -3. [Custom Message](/sdk/javascript/send-message#custom-message), for sending completely custom data using JSON structures. -4. [Interactive Messages](/sdk/javascript/interactive-messages), for sending end-user interactive messages of type form, card and custom Interactive +CometChat supports three types of messages: -You can also send metadata along with a text, media or custom message. Think, for example, if you'd want to share the user's location with every message, you can use the metadata field +| Type | Method | Use Case | +| --- | --- | --- | +| [Text](#text-message) | `sendMessage()` | Plain text messages | +| [Media](#media-message) | `sendMediaMessage()` | Images, videos, audio, files | +| [Custom](#custom-message) | `sendCustomMessage()` | Location, polls, or any JSON data | -## Text Message - -*In other words, as a sender, how do I send a text message?* - -To send a text message to a single user or group, you need to use the `sendMessage()` method and pass a `TextMessage` object to it. - -### Add Metadata - -To send custom data along with a text message, you can use the `setMetadata` method and pass a `JSON Object` to it. - - - -```javascript -let metadata = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", -}; - -textMessage.setMetadata(metadata); -``` - - - - -```typescript -let metadata: Object = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", -}; - -textMessage.setMetadata(metadata); -``` - - - - +You can also send [Interactive Messages](/sdk/javascript/interactive-messages) for forms, cards, and custom UI elements. -### Add Tags - -To add a tag to a message you can use the `setTags()` method of the TextMessage Class. The `setTags()` method accepts a list of tags. - - - -```javascript -let tags = ["starredMessage"]; - -textMessage.setTags(tags); -``` - - - - -```typescript -let tags: Array = ["starredMessage"]; - -textMessage.setTags(tags); -``` - - - - +## Text Message -Once the text message object is ready, you need to use the `sendMessage()` method to send the text message to the recipient. +Send a text message using `CometChat.sendMessage()` with a [`TextMessage`](/sdk/reference/messages#textmessage) object. @@ -98,9 +51,7 @@ CometChat.sendMessage(textMessage).then( } ); ``` - - ```javascript let receiverID = "GUID"; @@ -121,9 +72,7 @@ CometChat.sendMessage(textMessage).then( } ); ``` - - ```typescript let receiverID: string = "UID", @@ -144,9 +93,7 @@ CometChat.sendMessage(textMessage).then( } ); ``` - - ```typescript let receiverID: string = "GUID", @@ -167,14 +114,35 @@ CometChat.sendMessage(textMessage).then( } ); ``` - + +```javascript +try { + const receiverID = "UID"; + const messageText = "Hello world!"; + const receiverType = CometChat.RECEIVER_TYPE.USER; + const textMessage = new CometChat.TextMessage( + receiverID, + messageText, + receiverType + ); + const message = await CometChat.sendMessage(textMessage); + console.log("Message sent successfully:", message); +} catch (error) { + console.log("Message sending failed with error:", error); +} +``` + -### Set Quoted Message Id +The [`TextMessage`](/sdk/reference/messages#textmessage) class constructor takes the following parameters: -To set a quoted message ID for a message, use the `setQuotedMessageId()` method of the TextMessage class. This method accepts the ID of the message to be quoted. +| Parameter | Description | Required | +| --- | --- | --- | +| `receiverID` | UID of the user or GUID of the group receiving the message | Yes | +| `messageText` | The text message content | Yes | +| `receiverType` | `CometChat.RECEIVER_TYPE.USER` or `CometChat.RECEIVER_TYPE.GROUP` | Yes | @@ -298,7 +266,8 @@ The `TextMessage` class constructor takes the following parameters: | **messageText** | The text message | Required | | **receiverType** | The type of the receiver - `CometChat.RECEIVER_TYPE.USER` or `CometChat.RECEIVER_TYPE.GROUP` | Required | -When a text message is sent successfully, the response will include a `TextMessage` object which includes all information related to the sent message. + +On success, `sendMessage()` method returns a [`TextMessage`](/sdk/reference/messages#textmessage) | [`MediaMessage`](/sdk/reference/messages#mediamessage) | [`CustomMessage`](/sdk/reference/messages#custommessage) | [`BaseMessage`](/sdk/reference/messages#basemessage) object depending on the input message type. ## Media Message @@ -308,121 +277,96 @@ To send a media message to any user or group, you need to use the `sendMediaMess ### Add Metadata -To send custom data along with a media message, you can use the `setMetadata` method and pass a `JSON Object` to it. +Attach custom JSON data to the message: - -```javascript -let metadata = { + +```typescript +let metadata: Object = { latitude: "50.6192171633316", longitude: "-72.68182268750002", }; -mediaMessage.setMetadata(metadata); +textMessage.setMetadata(metadata); ``` - - - -```typescript -let metadata: Object = { + +```javascript +let metadata = { latitude: "50.6192171633316", longitude: "-72.68182268750002", }; -mediaMessage.setMetadata(metadata); +textMessage.setMetadata(metadata); ``` - - -### Add Caption(Text along with Media Message) +### Add Tags -To send a caption with a media message, you can use the `setCaption` method and pass text to it. +Tag messages for easy filtering later: - -```javascript -let caption = "Random Caption"; - -mediaMessage.setCaption(caption); -``` - - - ```typescript -let caption: string = "Random Caption"; +let tags: Array = ["starredMessage"]; -mediaMessage.setCaption(caption); +textMessage.setTags(tags); ``` - - - - -### Add Tags - -To add a tag to a message you can use the `setTags()` method of the MediaMessage Class. The `setTags()` method accepts a list of tags. - - - + ```javascript let tags = ["starredMessage"]; -mediaMessage.setTags(tags); +textMessage.setTags(tags); ``` - + + +### Quote a Message +Reply to a specific message by setting its ID: + + ```typescript -let tags: Array = ["starredMessage"]; - -mediaMessage.setTags(tags); +textMessage.setQuotedMessageId(10); +``` + + +```javascript +textMessage.setQuotedMessageId(10); ``` - - -There are 2 ways you can send Media Messages using the CometChat SDK: +## Media Message -1. **By providing the File:** You can directly share the file object while creating an object of the MediaMessage class. When the media message is sent using the `sendMediaMessage()` method, this file is then uploaded to CometChat servers and the URL of the file is sent in the success response of the `sendMediaMessage()` function. +Send images, videos, audio, or files using `CometChat.sendMediaMessage()`. -Getting file Object: +There are two ways to send media messages: +1. **Upload a file** — Pass a file object and CometChat uploads it automatically +2. **Send a URL** — Provide a URL to media hosted on your server or cloud storage - - -```html - - - - - - -``` +### Upload a File - +Get the file from an input element and pass it to [`MediaMessage`](/sdk/reference/messages#mediamessage): - +```html + +``` ```javascript let receiverID = "UID"; -let messageType = CometChat.MESSAGE_TYPE.FILE; +let messageType = CometChat.MESSAGE_TYPE.IMAGE; let receiverType = CometChat.RECEIVER_TYPE.USER; +let file = document.getElementById("img_file").files[0]; + let mediaMessage = new CometChat.MediaMessage( receiverID, - "INPUT FILE OBJECT", + file, messageType, receiverType ); @@ -436,17 +380,17 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - - ```javascript let receiverID = "GUID"; -let messageType = CometChat.MESSAGE_TYPE.FILE; +let messageType = CometChat.MESSAGE_TYPE.IMAGE; let receiverType = CometChat.RECEIVER_TYPE.GROUP; +let file = document.getElementById("img_file").files[0]; + let mediaMessage = new CometChat.MediaMessage( receiverID, - `INPUT FILE OBJECT`, + file, messageType, receiverType ); @@ -460,20 +404,20 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - - ```typescript let receiverID: string = "UID", - messageType: string = CometChat.MESSAGE_TYPE.FILE, + messageType: string = CometChat.MESSAGE_TYPE.IMAGE, receiverType: string = CometChat.RECEIVER_TYPE.USER, - mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( - receiverID, - "INPUT FILE OBJECT", - messageType, - receiverType - ); + file: File = (document.getElementById("img_file") as HTMLInputElement).files![0]; + +let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( + receiverID, + file, + messageType, + receiverType +); CometChat.sendMediaMessage(mediaMessage).then( (message: CometChat.MediaMessage) => { @@ -484,20 +428,20 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - - ```typescript let receiverID: string = "GUID", - messageType: string = CometChat.MESSAGE_TYPE.FILE, + messageType: string = CometChat.MESSAGE_TYPE.IMAGE, receiverType: string = CometChat.RECEIVER_TYPE.GROUP, - mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( - receiverID, - "INPUT FILE OBJECT", - messageType, - receiverType - ); + file: File = (document.getElementById("img_file") as HTMLInputElement).files![0]; + +let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( + receiverID, + file, + messageType, + receiverType +); CometChat.sendMediaMessage(mediaMessage).then( (message: CometChat.MediaMessage) => { @@ -508,72 +452,36 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - - - - - -### Set Quoted Message Id - -To set a quoted message ID for a message, use the `setQuotedMessageId()` method of the MediaMessage class. This method accepts the ID of the message to be quoted. - - - -```javascript -mediaMessage.setQuotedMessageId(10); -``` - - - - -```typescript -mediaMessage.setQuotedMessageId(10); -``` - - -There are 2 ways you can send Media Messages using the CometChat SDK: - -1. **By providing the File:** You can directly share the file object while creating an object of the MediaMessage class. When the media message is sent using the `sendMediaMessage()` method, this file is then uploaded to CometChat servers and the URL of the file is sent in the success response of the `sendMediaMessage()` function. - -Getting file Object: - - - -```html - - - - - - -``` - - +### Send a URL - +Send media hosted on your server or cloud storage using the [`Attachment`](/sdk/reference/auxiliary#attachment) class: ```javascript let receiverID = "UID"; -let messageType = CometChat.MESSAGE_TYPE.FILE; +let messageType = CometChat.MESSAGE_TYPE.IMAGE; let receiverType = CometChat.RECEIVER_TYPE.USER; let mediaMessage = new CometChat.MediaMessage( receiverID, - "INPUT FILE OBJECT", + "", messageType, receiverType ); +let file = { + name: "mario", + extension: "png", + mimeType: "image/png", + url: "https://pngimg.com/uploads/mario/mario_PNG125.png", +}; + +let attachment = new CometChat.Attachment(file); +mediaMessage.setAttachment(attachment); + CometChat.sendMediaMessage(mediaMessage).then( (message) => { console.log("Media message sent successfully", message); @@ -583,21 +491,29 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - - ```javascript let receiverID = "GUID"; -let messageType = CometChat.MESSAGE_TYPE.FILE; +let messageType = CometChat.MESSAGE_TYPE.IMAGE; let receiverType = CometChat.RECEIVER_TYPE.GROUP; let mediaMessage = new CometChat.MediaMessage( receiverID, - `INPUT FILE OBJECT`, + "", messageType, receiverType ); +let file = { + name: "mario", + extension: "png", + mimeType: "image/png", + url: "https://pngimg.com/uploads/mario/mario_PNG125.png", +}; + +let attachment = new CometChat.Attachment(file); +mediaMessage.setAttachment(attachment); + CometChat.sendMediaMessage(mediaMessage).then( (message) => { console.log("Media message sent successfully", message); @@ -607,30 +523,182 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - - ```typescript let receiverID: string = "UID", - messageType: string = CometChat.MESSAGE_TYPE.FILE, + messageType: string = CometChat.MESSAGE_TYPE.IMAGE, receiverType: string = CometChat.RECEIVER_TYPE.USER, mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( receiverID, - "INPUT FILE OBJECT", + "", messageType, receiverType ); -CometChat.sendMediaMessage(mediaMessage).then( - (message: CometChat.MediaMessage) => { - console.log("Media message sent successfully", message); - }, - (error: CometChat.CometChatException) => { - console.log("Media message sending failed with error", error); - } -); -``` +let file: Object = { + name: "mario", + extension: "png", + mimeType: "image/png", + url: "https://pngimg.com/uploads/mario/mario_PNG125.png", +}; + +let attachment: CometChat.Attachment = new CometChat.Attachment(file); +mediaMessage.setAttachment(attachment); + +CometChat.sendMediaMessage(mediaMessage).then( + (message: CometChat.MediaMessage) => { + console.log("Media message sent successfully", message); + }, + (error: CometChat.CometChatException) => { + console.log("Media message sending failed with error", error); + } +); +``` + + +```typescript +let receiverID: string = "GUID", + messageType: string = CometChat.MESSAGE_TYPE.IMAGE, + receiverType: string = CometChat.RECEIVER_TYPE.GROUP, + mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( + receiverID, + "", + messageType, + receiverType + ); + +let file: Object = { + name: "mario", + extension: "png", + mimeType: "image/png", + url: "https://pngimg.com/uploads/mario/mario_PNG125.png", +}; + +let attachment: CometChat.Attachment = new CometChat.Attachment(file); +mediaMessage.setAttachment(attachment); + +CometChat.sendMediaMessage(mediaMessage).then( + (message: CometChat.MediaMessage) => { + console.log("Media message sent successfully", message); + }, + (error: CometChat.CometChatException) => { + console.log("Media message sending failed with error", error); + } +); +``` + + + +The [`MediaMessage`](/sdk/reference/messages#mediamessage) class constructor takes the following parameters: + +| Parameter | Description | Required | +| --- | --- | --- | +| `receiverID` | UID of the user or GUID of the group | Yes | +| `file` | File object to upload, or empty string if using URL | Yes | +| `messageType` | `CometChat.MESSAGE_TYPE.IMAGE`, `VIDEO`, `AUDIO`, or `FILE` | Yes | +| `receiverType` | `CometChat.RECEIVER_TYPE.USER` or `GROUP` | Yes | + +On success, `sendMediaMessage()` returns a [MediaMessage](/sdk/reference/messages#mediamessage) object. + +### Add Caption + +Add text along with the media: + + + +```typescript +mediaMessage.setCaption("Check out this photo!"); +``` + + +```javascript +mediaMessage.setCaption("Check out this photo!"); +``` + + + +### Add Metadata and Tags + +Same as text messages: + +```javascript +mediaMessage.setMetadata({ location: "Paris" }); +mediaMessage.setTags(["vacation"]); +mediaMessage.setQuotedMessageId(10); +``` + +## Multiple Attachments + +Send multiple files in a single media message. + +### Upload Multiple Files + + + +```javascript +let receiverID = "UID"; +let messageType = CometChat.MESSAGE_TYPE.FILE; +let receiverType = CometChat.RECEIVER_TYPE.USER; +let files = document.getElementById("img_file").files; // FileList + +CometChat.sendMediaMessage(mediaMessage).then( + (message) => { + console.log("Media message sent successfully", message); + }, + (error) => { + console.log("Media message sending failed with error", error); + } +); +``` + + + + +```javascript +let receiverID = "GUID"; +let messageType = CometChat.MESSAGE_TYPE.FILE; +let receiverType = CometChat.RECEIVER_TYPE.GROUP; +let mediaMessage = new CometChat.MediaMessage( + receiverID, + `INPUT FILE OBJECT`, + messageType, + receiverType +); + +CometChat.sendMediaMessage(mediaMessage).then( + (message) => { + console.log("Media message sent successfully", message); + }, + (error) => { + console.log("Media message sending failed with error", error); + } +); +``` + + + + +```typescript +let receiverID: string = "UID", + messageType: string = CometChat.MESSAGE_TYPE.FILE, + receiverType: string = CometChat.RECEIVER_TYPE.USER, + mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( + receiverID, + "INPUT FILE OBJECT", + messageType, + receiverType + ); + +CometChat.sendMediaMessage(mediaMessage).then( + (message: CometChat.MediaMessage) => { + console.log("Media message sent successfully", message); + }, + (error: CometChat.CometChatException) => { + console.log("Media message sending failed with error", error); + } +); +``` @@ -814,7 +882,8 @@ CometChat.sendMediaMessage(mediaMessage).then( -When a media message is sent successfully, the response will include a `MediaMessage` object which includes all information related to the sent message. + +The `sendMediaMessage()` method returns a [`MediaMessage`](/sdk/reference/messages#mediamessage) object. ## Multiple Attachments in a Media Message @@ -831,11 +900,11 @@ Getting files: @@ -867,39 +936,39 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - + +```javascript +let receiverID = "GUID"; +let messageType = CometChat.MESSAGE_TYPE.FILE; +let receiverType = CometChat.RECEIVER_TYPE.GROUP; +let files = document.getElementById("img_file").files; - -```typescript -let receiverID: string = "UID", - messageType: string = CometChat.MESSAGE_TYPE.FILE, - receiverType: string = CometChat.RECEIVER_TYPE.USER, - mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( - receiverID, - files, - messageType, - receiverType - ); +let mediaMessage = new CometChat.MediaMessage( + receiverID, + files, + messageType, + receiverType +); CometChat.sendMediaMessage(mediaMessage).then( - (message: CometChat.MediaMessage) => { + (message) => { console.log("Media message sent successfully", message); }, - (error: CometChat.CometChatException) => { + (error) => { console.log("Media message sending failed with error", error); } ); ``` - + +```typescript +let receiverID: string = "UID", + messageType: string = CometChat.MESSAGE_TYPE.FILE, + receiverType: string = CometChat.RECEIVER_TYPE.USER, + files: FileList = (document.getElementById("img_file") as HTMLInputElement).files!; - -```javascript -let receiverID = "GUID"; -let messageType = CometChat.MESSAGE_TYPE.FILE; -let receiverType = CometChat.RECEIVER_TYPE.GROUP; -let mediaMessage = new CometChat.MediaMessage( +let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( receiverID, files, messageType, @@ -907,28 +976,28 @@ let mediaMessage = new CometChat.MediaMessage( ); CometChat.sendMediaMessage(mediaMessage).then( - (message) => { + (message: CometChat.MediaMessage) => { console.log("Media message sent successfully", message); }, - (error) => { + (error: CometChat.CometChatException) => { console.log("Media message sending failed with error", error); } ); ``` - - ```typescript let receiverID: string = "GUID", messageType: string = CometChat.MESSAGE_TYPE.FILE, receiverType: string = CometChat.RECEIVER_TYPE.GROUP, - mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( - receiverID, - files, - messageType, - receiverType - ); + files: FileList = (document.getElementById("img_file") as HTMLInputElement).files!; + +let mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( + receiverID, + files, + messageType, + receiverType +); CometChat.sendMediaMessage(mediaMessage).then( (message: CometChat.MediaMessage) => { @@ -939,26 +1008,15 @@ CometChat.sendMediaMessage(mediaMessage).then( } ); ``` - - -The `MediaMessage` class constructor takes the following parameters: - -| Parameter | Description | -| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **receiverId** | The `UID` or `GUID` of the recipient. | -| **files** | An array of files. | -| **messageType** | The type of the message that needs to be sent which in this case can be:
1. `CometChat.MESSAGE_TYPE.IMAGE`
2. `CometChat.MESSAGE_TYPE.VIDEO`
3. `CometChat.MESSAGE_TYPE.AUDIO`
4. `CometChat.MESSAGE_TYPE.FILE` | -| **receiverType** | The type of the receiver to whom the message is to be sent.
`1. CometChat.RECEIVER_TYPE.USER`
`2. CometChat.RECEIVER_TYPE.GROUP` | - -2. **By providing the URL of the multiple files:** The second way to send multiple attachments in a single media message using the CometChat SDK is to provide the SDK with the URL of multiple files that are hosted on your servers or any cloud storage. To achieve this you will have to make use of the Attachment class. For more information, you can refer to the below code snippet: +### Send Multiple URLs ```javascript -let receiverID = "cometchat-uid-2"; +let receiverID = "UID"; let messageType = CometChat.MESSAGE_TYPE.IMAGE; let receiverType = CometChat.RECEIVER_TYPE.USER; let mediaMessage = new CometChat.MediaMessage( @@ -989,20 +1047,60 @@ attachments.push(new CometChat.Attachment(attachment2)); mediaMessage.setAttachments(attachments); CometChat.sendMediaMessage(mediaMessage).then( - (mediaMessage) => { - console.log("message", mediaMessage); + (message) => { + console.log("Media message sent successfully", message); }, (error) => { - console.log("error in sending message", error); + console.log("Media message sending failed with error", error); } ); ``` - + +```javascript +let receiverID = "GUID"; +let messageType = CometChat.MESSAGE_TYPE.IMAGE; +let receiverType = CometChat.RECEIVER_TYPE.GROUP; +let mediaMessage = new CometChat.MediaMessage( + receiverID, + "", + messageType, + receiverType +); + +let attachment1 = { + name: "mario", + extension: "png", + mimeType: "image/png", + url: "https://pngimg.com/uploads/mario/mario_PNG125.png", +}; + +let attachment2 = { + name: "jaguar", + extension: "png", + mimeType: "image/png", + url: "https://pngimg.com/uploads/jaguar/jaguar_PNG20759.png", +}; + +let attachments = []; +attachments.push(new CometChat.Attachment(attachment1)); +attachments.push(new CometChat.Attachment(attachment2)); + +mediaMessage.setAttachments(attachments); +CometChat.sendMediaMessage(mediaMessage).then( + (message) => { + console.log("Media message sent successfully", message); + }, + (error) => { + console.log("Media message sending failed with error", error); + } +); +``` + ```typescript -let receiverID: string = "cometchat-uid-2", +let receiverID: string = "UID", messageType: string = CometChat.MESSAGE_TYPE.IMAGE, receiverType: string = CometChat.RECEIVER_TYPE.USER, mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( @@ -1033,64 +1131,18 @@ attachments.push(new CometChat.Attachment(attachment2)); mediaMessage.setAttachments(attachments); CometChat.sendMediaMessage(mediaMessage).then( - (mediaMessage: CometChat.MediaMessage) => { - console.log("message", mediaMessage); + (message: CometChat.MediaMessage) => { + console.log("Media message sent successfully", message); }, (error: CometChat.CometChatException) => { - console.log("error in sending message", error); - } -); -``` - - - - -```javascript -let receiverID = "cometchat-guid-1"; -let messageType = CometChat.MESSAGE_TYPE.IMAGE; -let receiverType = CometChat.RECEIVER_TYPE.GROUP; -let mediaMessage = new CometChat.MediaMessage( - receiverID, - "", - messageType, - receiverType -); - -let attachment1 = { - name: "mario", - extension: "png", - mimeType: "image/png", - url: "https://pngimg.com/uploads/mario/mario_PNG125.png", -}; - -let attachment2 = { - name: "jaguar", - extension: "png", - mimeType: "image/png", - url: "https://pngimg.com/uploads/jaguar/jaguar_PNG20759.png", -}; - -let attachments = []; -attachments.push(new CometChat.Attachment(attachment1)); -attachments.push(new CometChat.Attachment(attachment2)); - -mediaMessage.setAttachments(attachments); - -CometChat.sendMediaMessage(mediaMessage).then( - (mediaMessage) => { - console.log("message", mediaMessage); - }, - (error) => { - console.log("error in sending message", error); + console.log("Media message sending failed with error", error); } ); ``` - - ```typescript -let receiverID: string = "cometchat-guid-1", +let receiverID: string = "GUID", messageType: string = CometChat.MESSAGE_TYPE.IMAGE, receiverType: string = CometChat.RECEIVER_TYPE.GROUP, mediaMessage: CometChat.MediaMessage = new CometChat.MediaMessage( @@ -1107,7 +1159,7 @@ let attachment1: Object = { url: "https://pngimg.com/uploads/mario/mario_PNG125.png", }; -let attachment1: Object = { +let attachment2: Object = { name: "jaguar", extension: "png", mimeType: "image/png", @@ -1121,97 +1173,20 @@ attachments.push(new CometChat.Attachment(attachment2)); mediaMessage.setAttachments(attachments); CometChat.sendMediaMessage(mediaMessage).then( - (mediaMessage: CometChat.MediaMessage) => { - console.log("message", mediaMessage); + (message: CometChat.MediaMessage) => { + console.log("Media message sent successfully", message); }, (error: CometChat.CometChatException) => { - console.log("error in sending message", error); + console.log("Media message sending failed with error", error); } ); ``` - - -When a media message is sent successfully, the response will include a `MediaMessage` object which includes all information related to the sent message. - -You can use the `setMetadata()`, `setCaption()` & `setTags()` methods to add metadata, caption and tags respectively in exactly the same way as it is done while sending a single file or attachment in a Media Message. - ## Custom Message -*In other words, as a sender, how do I send a custom message like location coordinates?* - -CometChat allows you to send custom messages which are neither text nor media messages. - -In order to send a custom message, you need to use the `sendCustomMessage()` method. - -The `sendCustomMessage()` method takes an object of the `CustomMessage` which can be obtained using the below constructor. - - - -```js -let customMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData -); -``` - - - - -```typescript -let customMessage: CometChat.CustomMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData -); -``` - - - - - -The above constructor, helps you create a custom message with the message type set to whatever is passed to the constructor and the category set to `custom`. - -The parameters involved are: - -1. `receiverId` - The unique ID of the user or group to which the message is to be sent. -2. `receiverType` - Type of the receiver i.e user or group -3. `customType` - custom message type that you need to set -4. `customData` - The data to be passed as the message in the form of a JSON Object. - -You can also use the subType field of the `CustomMessage` class to set a specific type for the custom message. This can be achieved using the `setSubtype()` method. - -### Add Tags - -To add a tag to a message you can use the `setTags()` method of the CustomMessage Class. The `setTags()` method accepts a list of tags. - - - -```javascript -let tags = ["starredMessage"]; - -customMessage.setTags(tags); -``` - - - - -```typescript -let tags: Array = ["starredMessage"]; - -customMessage.setTags(tags); -``` - - - - - -Once the object of `CustomMessage` class is ready you can send the custom message using the `sendCustomMessage()` method. +Send structured data that doesn't fit text or media categories — like location coordinates, polls, or game moves. @@ -1223,34 +1198,7 @@ let customData = { }; let customType = "location"; let receiverType = CometChat.RECEIVER_TYPE.USER; -let customMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData -); -CometChat.sendCustomMessage(customMessage).then( - (message) => { - console.log("custom message sent successfully", message); - }, - (error) => { - console.log("custom message sending failed with error", error); - } -); -``` - - - - -```javascript -let receiverID = "GUID"; -let customData = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", -}; -let customType = "location"; -let receiverType = CometChat.RECEIVER_TYPE.GROUP; let customMessage = new CometChat.CustomMessage( receiverID, receiverType, @@ -1260,126 +1208,14 @@ let customMessage = new CometChat.CustomMessage( CometChat.sendCustomMessage(customMessage).then( (message) => { - console.log("custom message sent successfully", message); + console.log("Custom message sent successfully", message); }, (error) => { - console.log("custom message sending failed with error", error); - } -); -``` - - - - -```typescript -let receiverID: string = "UID", - customData: Object = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", - }, - customType: string = "location", - receiverType: string = CometChat.RECEIVER_TYPE.USER, - customMessage: CometChat.CustomMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData - ); - -CometChat.sendCustomMessage(customMessage).then( - (message: CometChat.CustomMessage) => { - console.log("custom message sent successfully", message); - }, - (error: CometChat.CometChatException) => { - console.log("custom message sending failed with error", error); + console.log("Custom message sending failed with error", error); } ); ``` - - - - -```typescript -let receiverID: string = "GUID", - customData: Object = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", - }, - customType: string = "location", - receiverType: string = CometChat.RECEIVER_TYPE.GROUP, - customMessage: CometChat.CustomMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData - ); - -CometChat.sendCustomMessage(customMessage).then( - (message: CometChat.CustomMessage) => { - console.log("custom message sent successfully", message); - }, - (error: CometChat.CometChatException) => { - console.log("custom message sending failed with error", error); - } -); -``` - - - - -### Set Quoted Message Id - -To set a quoted message ID for a message, use the `setQuotedMessageId()` method of the CustomMessage class. This method accepts the ID of the message to be quoted. - - - -```javascript -customMessage.setQuotedMessageId(10); -``` - - - - -```typescript -customMessage.setQuotedMessageId(10); -``` - - - - - -Once the object of `CustomMessage` class is ready you can send the custom message using the `sendCustomMessage()` method. - - - -```javascript -let receiverID = "UID"; -let customData = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", -}; -let customType = "location"; -let receiverType = CometChat.RECEIVER_TYPE.USER; -let customMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData -); - -CometChat.sendCustomMessage(customMessage).then( - (message) => { - console.log("custom message sent successfully", message); - }, - (error) => { - console.log("custom message sending failed with error", error); - } -); -``` - - - ```javascript let receiverID = "GUID"; @@ -1389,6 +1225,7 @@ let customData = { }; let customType = "location"; let receiverType = CometChat.RECEIVER_TYPE.GROUP; + let customMessage = new CometChat.CustomMessage( receiverID, receiverType, @@ -1398,16 +1235,14 @@ let customMessage = new CometChat.CustomMessage( CometChat.sendCustomMessage(customMessage).then( (message) => { - console.log("custom message sent successfully", message); + console.log("Custom message sent successfully", message); }, (error) => { - console.log("custom message sending failed with error", error); + console.log("Custom message sending failed with error", error); } ); ``` - - ```typescript let receiverID: string = "UID", @@ -1426,16 +1261,14 @@ let receiverID: string = "UID", CometChat.sendCustomMessage(customMessage).then( (message: CometChat.CustomMessage) => { - console.log("custom message sent successfully", message); + console.log("Custom message sent successfully", message); }, (error: CometChat.CometChatException) => { - console.log("custom message sending failed with error", error); + console.log("Custom message sending failed with error", error); } ); ``` - - ```typescript let receiverID: string = "GUID", @@ -1454,179 +1287,61 @@ let receiverID: string = "GUID", CometChat.sendCustomMessage(customMessage).then( (message: CometChat.CustomMessage) => { - console.log("custom message sent successfully", message); + console.log("Custom message sent successfully", message); }, (error: CometChat.CometChatException) => { - console.log("custom message sending failed with error", error); + console.log("Custom message sending failed with error", error); } ); ``` - - -The above sample explains how custom messages can be used to share the location with a user. The same can be achieved for groups. +The [`CustomMessage`](/sdk/reference/messages#custommessage) class constructor takes the following parameters: -On success, you will receive an object of the `CustomMessage` class. +| Parameter | Description | Required | +| --- | --- | --- | +| `receiverID` | UID of the user or GUID of the group | Yes | +| `receiverType` | `CometChat.RECEIVER_TYPE.USER` or `GROUP` | Yes | +| `customType` | Your custom type string (e.g., `"location"`, `"poll"`) | Yes | +| `customData` | JSON object with your custom data | Yes | -### Update Conversation +On success, `sendCustomMessage()` returns a [CustomMessage](/sdk/reference/messages#custommessage) object. -*How can I decide whether the custom message should update the last message of a conversation?* - -By default, a custom message will update the last message of a conversation. If you wish to not update the last message of the conversation when a custom message is sent, please use shouldUpdateConversation(value: boolean) method of the Custom Message. +### Add Tags - - ```javascript -let receiverID = "UID"; -let customData = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", -}; -let customType = "location"; -let receiverType = CometChat.RECEIVER_TYPE.USER; -let customMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData -); - -customMessage.shouldUpdateConversation(false); -CometChat.sendCustomMessage(customMessage).then( - (message) => { - console.log("custom message sent successfully", message); - }, - (error) => { - console.log("custom message sending failed with error", error); - } -); +customMessage.setTags(["starredMessage"]); ``` - +### Quote a Message - ```javascript -let receiverID = "GUID"; -let customData = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", -}; -let customType = "location"; -let receiverType = CometChat.RECEIVER_TYPE.GROUP; -let customMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData -); - -customMessage.shouldUpdateConversation(false); -CometChat.sendCustomMessage(customMessage).then( - (message) => { - console.log("custom message sent successfully", message); - }, - (error) => { - console.log("custom message sending failed with error", error); - } -); -``` - - - - -```typescript -let receiverID: string = "UID", - customData: Object = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", - }, - customType: string = "location", - receiverType: string = CometChat.RECEIVER_TYPE.USER, - customMessage: CometChat.CustomMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData - ); - -customMessage.shouldUpdateConversation(false); -CometChat.sendCustomMessage(customMessage).then( - (message: CometChat.CustomMessage) => { - console.log("custom message sent successfully", message); - }, - (error: CometChat.CometChatException) => { - console.log("custom message sending failed with error", error); - } -); +customMessage.setQuotedMessageId(10); ``` - +### Control Conversation Update - -```typescript -let receiverID: string = "GUID", - customData: Object = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", - }, - customType: string = "location", - receiverType: string = CometChat.RECEIVER_TYPE.GROUP, - customMessage: CometChat.CustomMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData - ); +By default, custom messages update the conversation's last message. To prevent this: +```javascript customMessage.shouldUpdateConversation(false); -CometChat.sendCustomMessage(customMessage).then( - (message: CometChat.CustomMessage) => { - console.log("custom message sent successfully", message); - }, - (error: CometChat.CometChatException) => { - console.log("custom message sending failed with error", error); - } -); ``` - +{/* ### Control Push Notifications - +By default, custom messages don't trigger push notifications. To enable them: -### Custom Notification Body +```javascript +customMessage.shouldSendNotification(true); +``` */} -*How can i customise the notification body of custom message?* +### Custom Notification Text -To add a custom notification body for `Push, Email & SMS` notification of a custom message you can use the `setConversationText(text: string)` method of Custom Message class. +Set custom text for push, email, and SMS notifications: - - ```javascript -let receiverID = "UID"; -let customData = { - latitude: "50.6192171633316", - longitude: "-72.68182268750002", -}; -let customType = "location"; -let receiverType = CometChat.RECEIVER_TYPE.USER; -let customMessage = new CometChat.CustomMessage( - receiverID, - receiverType, - customType, - customData -); - -customMessage.setConversationText("Custom notification body"); -CometChat.sendCustomMessage(customMessage).then( - (message) => { - console.log("custom message sent successfully", message); - }, - (error) => { - console.log("custom message sending failed with error", error); - } -); +customMessage.setConversationText("Shared a location"); ``` @@ -1720,8 +1435,28 @@ CometChat.sendCustomMessage(customMessage).then( - -It is also possible to send interactive messages from CometChat, to know more [click here](/sdk/javascript/interactive-messages) +The `sendCustomMessage()` method returns a [`CustomMessage`](/sdk/reference/messages#custommessage) object. + +You can also send interactive messages with forms, cards, and buttons. See [Interactive Messages](/sdk/javascript/interactive-messages) for details. + +--- + +## Next Steps + + + + Listen for incoming messages in real-time + + + Edit previously sent messages + + + Delete sent messages + + + Send forms, cards, and custom UI elements + + diff --git a/sdk/javascript/session-timeout.mdx b/sdk/javascript/session-timeout.mdx index 23470881f..70bd8403d 100644 --- a/sdk/javascript/session-timeout.mdx +++ b/sdk/javascript/session-timeout.mdx @@ -1,34 +1,81 @@ --- -title: "Session Timeout Flow" +title: "Session Timeout" +sidebarTitle: "Session Timeout" +description: "Handle idle session timeouts in CometChat calls, including automatic termination, user prompts, and the onSessionTimeout event." --- + +```javascript +// Set custom timeout (in seconds) +const callSettings = new CometChatCalls.CallSettingsBuilder() + .setIdleTimeoutPeriod(300) // 5 minutes + .setCallListener(new CometChatCalls.OngoingCallListener({ + onSessionTimeout: () => { + console.log("Session timed out"); + CometChatCalls.endSession(); + } + })) + .build(); +``` -Available since v4.1.0 +- Default idle timeout: 180 seconds (3 minutes) alone in a session +- Warning dialog appears 60 seconds before auto-termination +- Listen for `onSessionTimeout` to handle auto-termination +- Customize with `setIdleTimeoutPeriod(seconds)` in CallSettings (v4.1.0+) + -## Overview +*Available since v4.1.0* -CometChat Calls SDK provides a mechanism to handle session timeouts for idle participants. By default, if a participant is alone in a call session for 180 seconds (3 minutes), the following sequence is triggered: +The Calls SDK automatically terminates call sessions when a participant is alone for too long, preventing abandoned calls from consuming resources. You can customize the timeout duration and handle the termination event. -1. After 120 seconds of being alone in the session, the participant will see a dialog box +## How It Works -2. This dialog provides options to either: +When a participant is alone in a session: - * Stay in the call - * Leave immediately +1. A warning dialog appears 60 seconds before the timeout, with "Stay" or "Leave" options +2. If no action is taken, the call auto-terminates and the `onSessionTimeout` event fires -3. If no action is taken within the next 60 seconds, the call will automatically end +The default timeout is 180 seconds (3 minutes). -This feature helps manage inactive call sessions and prevents unnecessary resource usage. The idle timeout period ensures that participants don't accidentally remain in abandoned call sessions. +## Configuration -### Session Timeout Flow +Set a custom timeout period using `setIdleTimeoutPeriod()` in `CallSettingsBuilder`. The warning dialog will always appear 60 seconds before the configured timeout. - - - +```javascript +const callSettings = new CometChatCalls.CallSettingsBuilder() + .setIdleTimeoutPeriod(300) // 5 minutes + .enableDefaultLayout(true) + .setCallListener(callListener) + .build(); +``` - +## Handling the Timeout Event -The `onSessionTimeout` event is triggered when the call automatically terminates due to session timeout, as illustrated in the diagram above. +Listen for `onSessionTimeout` in your `OngoingCallListener` to clean up when the call auto-terminates: - +```javascript +const callListener = new CometChatCalls.OngoingCallListener({ + onSessionTimeout: () => { + console.log("Session timed out due to inactivity"); + CometChatCalls.endSession(); + // Close the calling screen + }, + // ... other listeners +}); +``` + +See [Call Session — Call Listeners](/sdk/javascript/direct-call#call-listeners) for the full list of events. + +--- + +## Next Steps + + + + Implement ringing call flows with accept/reject functionality + + + Implement calling without the Chat SDK + + diff --git a/sdk/javascript/setup-sdk.mdx b/sdk/javascript/setup-sdk.mdx index e9bdce872..d0021b41a 100644 --- a/sdk/javascript/setup-sdk.mdx +++ b/sdk/javascript/setup-sdk.mdx @@ -1,96 +1,114 @@ --- title: "Setup" -sidebarTitle: "Overview" +sidebarTitle: "Setup" +description: "Install, configure, and initialize the CometChat JavaScript SDK in your application." --- +{/* TL;DR for Agents and Quick Reference */} + +```bash +npm install @cometchat/chat-sdk-javascript +``` - -Migrating app version from v3 to v4 ? +```typescript +import { CometChat } from "@cometchat/chat-sdk-javascript"; -Skip the create new app step. Your existing v3 app can be migrated to v4. +const appSettings: CometChat.AppSettings = new CometChat.AppSettingsBuilder() + .setRegion("APP_REGION") + .subscribePresenceForAllUsers() + .autoEstablishSocketConnection(true) + .build(); -Follow steps mentioned in **Add the CometChat dependency** section below to upgrade to latest version of v4 +await CometChat.init("APP_ID", appSettings); +await CometChat.login("UID", "AUTH_KEY"); // dev only +``` - +**Prerequisites:** npm 8+, Node.js 16+, credentials from [CometChat Dashboard](https://app.cometchat.com) +**SSR:** SDK requires browser APIs — initialize client-side only (useEffect / mounted) + -## Get your Application Keys +## Prerequisites -[Signup for CometChat](https://app.cometchat.com) and then: +| Requirement | Version | +|-------------|---------| +| npm | 8.x or above | +| Node.js | 16 or above | -1. Create a new app -2. Head over to the **API & Auth Keys** section and note the **Auth Key**, **App ID** & **Region** +Get your credentials from the [CometChat Dashboard](https://app.cometchat.com): +- App ID +- Region +- Auth Key (for development) -## Add the CometChat Dependency + +**Auth Key** is for development/testing only. In production, generate **Auth Tokens** on your server using the REST API. Never expose Auth Keys in production client code. + -### NPM +## Installation - - -```js +### Package Manager + +```bash npm install @cometchat/chat-sdk-javascript ``` - - - - -Then, import the `CometChat` object wherever you want to use CometChat. +Then import wherever needed: - - -```js +```javascript import { CometChat } from "@cometchat/chat-sdk-javascript"; ``` - - - +### CDN -### HTML (via CDN) - -Include the CometChat JavaScript library in your HTML code. - - - -``` +```html ``` - +When using the CDN, `CometChat` is available as a global variable. - +## Initialization -## Initialize CometChat +The `init()` method initializes the SDK and must be called before any other CometChat method. Call it once at app startup, typically in your entry file (`index.js`, `main.js`, or `App.js`). -The `init()` method initialises the settings required for CometChat. The `init()` method takes the below parameters: -1. appID - You CometChat App ID -2. appSettings - An object of the AppSettings class can be created using the AppSettingsBuilder class. The region field is mandatory and can be set using the `setRegion()` method. + + +```typescript +let appID: string = "APP_ID"; +let region: string = "APP_REGION"; -The `AppSettings` class allows you to configure two settings: +let appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .autoEstablishSocketConnection(true) + .build(); -* **Region**: The region where you app was created. -* [Presence Subscription](/sdk/javascript/user-presence)**:** Represents the subscription type for user presence (real-time online/offline status) -* **autoEstablishSocketConnection(boolean value)**: This property takes a boolean value which when set to `true` informs the SDK to manage the web-socket connection internally. If set to `false` , it informs the SDK that the web-socket connection will be managed manually. The default value for this parameter is true. For more information on this, please check the [Managing Web-Socket connections manually](/sdk/javascript/managing-web-sockets-connections-manually) section. The default value for this property is **true.** -* **overrideAdminHost(adminHost: string)**: This method takes the admin URL as input and uses this admin URL instead of the default admin URL. This can be used in case of dedicated deployment of CometChat. -* **overrideClientHost(clientHost: string)**: This method takes the client URL as input and uses this client URL instead of the default client URL. This can be used in case of dedicated deployment of CometChat. +CometChat.init(appID, appSetting).then( + (initialized: boolean) => { + console.log("Initialization completed successfully", initialized); + }, + (error: CometChat.CometChatException) => { + console.log("Initialization failed with error:", error); + } +); +``` -You need to call `init()` before calling any other method from CometChat. We suggest you call the `init()` method on app startup, preferably in the `index.js` file. + - -```js +```javascript let appID = "APP_ID"; let region = "APP_REGION"; + let appSetting = new CometChat.AppSettingsBuilder() .subscribePresenceForAllUsers() .setRegion(region) .autoEstablishSocketConnection(true) .build(); + CometChat.init(appID, appSetting).then( () => { console.log("Initialization completed successfully"); @@ -103,32 +121,184 @@ CometChat.init(appID, appSetting).then( - + +```javascript +let appID = "APP_ID"; +let region = "APP_REGION"; + +let appSetting = new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .autoEstablishSocketConnection(true) + .build(); + +try { + await CometChat.init(appID, appSetting); + console.log("Initialization completed successfully"); +} catch (error) { + console.log("Initialization failed with error:", error); +} +``` + + + + + +Replace `APP_ID` and `APP_REGION` with your credentials from the [Dashboard](https://app.cometchat.com). + + +`CometChat.init()` must be called before any other SDK method. Calling `login()`, `sendMessage()`, or registering listeners before `init()` will fail. + + +### Parameters + +| Parameter | Type | Description | +|-----------|------|-------------| +| appID | string | Your CometChat App ID | +| appSetting | AppSettings | Configuration object built with AppSettingsBuilder | + +### AppSettings Options + +| Method | Description | Default | +|--------|-------------|---------| +| `setRegion(region)` | Region where your app was created (`us`, `eu`, `in`, `in-private`) | Required | +| `subscribePresenceForAllUsers()` | Subscribe to presence events for all users | — | +| `subscribePresenceForRoles(roles)` | Subscribe to presence for specific roles | — | +| `subscribePresenceForFriends()` | Subscribe to presence for friends only | — | +| `autoEstablishSocketConnection(bool)` | Let SDK manage WebSocket connections | `true` | +| `overrideAdminHost(adminHost)` | Custom admin URL (dedicated deployment) | — | +| `overrideClientHost(clientHost)` | Custom client URL (dedicated deployment) | — | +| `setStorageMode(storageMode)` | Local storage mode (`CometChat.StorageMode.SESSION` for session storage) | — | + +### Presence Subscription + +Choose how to subscribe to user presence (online/offline status): + +```javascript +// All users +new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .build(); + +// Specific roles +new CometChat.AppSettingsBuilder() + .subscribePresenceForRoles(["admin", "moderator"]) + .setRegion(region) + .build(); + +// Friends only +new CometChat.AppSettingsBuilder() + .subscribePresenceForFriends() + .setRegion(region) + .build(); +``` + +See [User Presence](/sdk/javascript/user-presence) for more details. + +### WebSocket Connection + +By default, the SDK manages WebSocket connections automatically. To manage them manually: + +```javascript +let appSetting = new CometChat.AppSettingsBuilder() + .setRegion(region) + .autoEstablishSocketConnection(false) + .build(); +``` + +See [Managing WebSocket Connections](/sdk/javascript/managing-web-sockets-connections-manually) for manual control. + +### Session Storage + +Use session storage instead of local storage (data clears when browser closes): + +```javascript +let appSetting = new CometChat.AppSettingsBuilder() + .setRegion(region) + .setStorageMode(CometChat.StorageMode.SESSION) + .build(); +``` + +## SSR Compatibility + +The CometChat SDK requires browser APIs (`window`, `WebSocket`) and cannot run on the server. For SSR frameworks, initialize the SDK only on the client side. + + + +Import the SDK dynamically in `useEffect`: + +```javascript +import React from "react"; + +export default function Home() { + let [ready, setReady] = React.useState(false); + + React.useEffect(() => { + window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat; + setReady(true); + }, []); + + return ready ? :

Loading...

; +} +``` + + + + +Import the SDK in the `mounted` lifecycle hook: + +```javascript +export default { + data() { + return { ready: false }; + }, + mounted() { + window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat; + this.ready = true; + } +}; +``` + + + + +Use the JavaScript SDK directly. Import and initialize in your root component: + ```typescript -let appID: string = "APP_ID", - region: string = "APP_REGION", - appSetting: CometChat.AppSettings = new CometChat.AppSettingsBuilder() +import { CometChat } from "@cometchat/chat-sdk-javascript"; + +ngOnInit() { + const appSetting = new CometChat.AppSettingsBuilder() .subscribePresenceForAllUsers() - .setRegion(region) + .setRegion("APP_REGION") .autoEstablishSocketConnection(true) .build(); -CometChat.init(appID, appSetting).then( - (initialized: boolean) => { - console.log("Initialization completed successfully", initialized); - }, - (error: CometChat.CometChatException) => { - console.log("Initialization failed with error:", error); - } -); + + CometChat.init("APP_ID", appSetting).then( + () => console.log("CometChat initialized successfully"), + (error) => console.log("CometChat initialization failed:", error) + ); +} ``` + +The dedicated Ionic Cordova SDK has been deprecated. For new Ionic/Cordova applications, use the JavaScript SDK as shown above. + + -Make sure you replace the `APP_ID` with your CometChat **App ID** and `APP_REGION` with your **App Region** in the above code. +--- + +## Next Steps -| Parameter | Description | -| ---------- | ----------------------------------- | -| appID | CometChat App ID | -| appSetting | An object of the AppSettings class. | + + + Log in users with Auth Key or Auth Token + + + Send your first message + + diff --git a/sdk/javascript/ssr-compatibility.mdx b/sdk/javascript/ssr-compatibility.mdx new file mode 100644 index 000000000..a4b362c12 --- /dev/null +++ b/sdk/javascript/ssr-compatibility.mdx @@ -0,0 +1,279 @@ +--- +title: "SSR Compatibility" +description: "Set up the CometChat JavaScript SDK with Next.js, NuxtJS, Ionic, and other server-side rendering frameworks." +--- + +The CometChat SDK requires browser APIs (`window`, `WebSocket`) and cannot run on the server. For SSR frameworks, initialize the SDK only on the client side. + +## Next.js + +Import the SDK dynamically in `useEffect` (functional components) or `componentDidMount` (class components). + + + +```javascript +import React from "react"; +import Chat from "./Chat"; + +export default function Home() { + let [libraryImported, setLibraryImported] = React.useState(false); + + React.useEffect(() => { + window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat; + setLibraryImported(true); + }, []); + + return libraryImported ? :

Loading....

; +} +``` + + + + +```javascript +import React from 'react'; +import Chat from './Chat'; + +export default class Home extends React.Component { + constructor(props) { + super(props); + this.state = { + libraryImported: false + }; + } + + componentDidMount() { + window.CometChat = require("@cometchat/chat-sdk-javascript").CometChat; + this.setState({ libraryImported: true }); + } + + render() { + return this.state.libraryImported ? :

Loading....

; + } +} +``` + + + + +```javascript +import React, { Component } from "react"; +import { COMETCHAT_CONSTANTS } from "./CONSTS"; + +export default class Chat extends Component { + constructor(props) { + super(props); + this.state = { + user: undefined, + }; + } + + componentDidMount() { + this.init(); + } + + init() { + CometChat.init( + COMETCHAT_CONSTANTS.APP_ID, + new CometChat.AppSettingsBuilder() + .setRegion(COMETCHAT_CONSTANTS.REGION) + .subscribePresenceForAllUsers() + .build() + ).then( + () => { + this.login(); + }, + (error) => { + console.log("Init failed with exception:", error); + } + ); + } + + login() { + let UID = "UID"; + CometChat.login(UID, COMETCHAT_CONSTANTS.AUTH_KEY).then( + (user) => { + this.setState({ user }); + }, + (error) => { + console.log("Login failed with exception:", error); + } + ); + } + + render() { + return this.state.user ? ( +
User logged in
+ ) : ( +
User not logged in
+ ); + } +} +``` + + + + +```javascript +export const COMETCHAT_CONSTANTS = { + APP_ID: "APP_ID", + REGION: "REGION", + AUTH_KEY: "AUTH_KEY", +}; +``` + + + + + +## NuxtJS + +Import the SDK dynamically in the `mounted` lifecycle hook. + + + +```javascript + + + +``` + + + + +```javascript + + + +``` + + + + +```javascript +module.exports = { + APP_ID: "APP_ID", + REGION: "REGION", + AUTH_KEY: "AUTH_KEY", +}; +``` + + + + + +## Ionic/Cordova + +For Ionic and Cordova applications, use the JavaScript SDK directly. Import and initialize in your root component: + +```typescript +import { Component, OnInit } from '@angular/core'; +import { CometChat } from '@cometchat/chat-sdk-javascript'; + +@Component({ + selector: 'app-root', + templateUrl: 'app.component.html', +}) +export class AppComponent implements OnInit { + + ngOnInit() { + this.initCometChat(); + } + + initCometChat() { + const appID = 'APP_ID'; + const region = 'APP_REGION'; + + const appSetting = new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() + .setRegion(region) + .autoEstablishSocketConnection(true) + .build(); + + CometChat.init(appID, appSetting).then( + () => { + console.log('CometChat initialized successfully'); + }, + (error) => { + console.log('CometChat initialization failed:', error); + } + ); + } +} +``` + + +The dedicated Ionic Cordova SDK has been deprecated. For new Ionic/Cordova applications, use the JavaScript SDK as shown above. Existing users can refer to the [legacy documentation](/sdk/ionic-legacy/overview). + + +--- + +## Next Steps + + + + Log in users with Auth Key or Auth Token + + + Send your first message + + diff --git a/sdk/javascript/standalone-calling.mdx b/sdk/javascript/standalone-calling.mdx index 09df82d0e..b7d438368 100644 --- a/sdk/javascript/standalone-calling.mdx +++ b/sdk/javascript/standalone-calling.mdx @@ -1,10 +1,31 @@ --- title: "Standalone Calling" +sidebarTitle: "Standalone Calling" +description: "Implement video and audio calling using only the CometChat Calls SDK without the Chat SDK. Covers authentication, token generation, session management, and call controls." --- -## Overview + -This section demonstrates how to implement calling functionality using only the CometChat Calls SDK, without requiring the Chat SDK. This is ideal for applications that need video/audio calling capabilities without the full chat infrastructure. +```javascript +// Generate call token (requires user auth token from REST API) +const callToken = await CometChatCalls.generateToken(sessionId, userAuthToken); + +// Start call session +const callSettings = new CometChatCalls.CallSettingsBuilder() + .enableDefaultLayout(true) + .setIsAudioOnlyCall(false) + .setCallListener(callListener) + .build(); +CometChatCalls.startSession(callToken.token, callSettings, htmlElement); + +// End session +CometChatCalls.endSession(); +``` + + +Standalone Calling lets you add voice and video calls using only the CometChat Calls SDK — no Chat SDK required. This is ideal when you already have your own messaging system and just need calling, or when you want the smallest possible SDK footprint. + +The key difference from the regular [Call Session](/sdk/javascript/direct-call) flow is authentication: instead of using `CometChat.getLoggedinUser()`, you obtain auth tokens directly from the CometChat REST API. Before you begin, ensure you have completed the [Calls SDK setup](/sdk/javascript/calling-setup). @@ -38,33 +59,33 @@ You can generate the token just before starting the call, or generate and store Use the `generateToken()` method to create a call token: - -```javascript -const sessionId = "UNIQUE_SESSION_ID"; // Generate a unique session ID -const userAuthToken = "USER_AUTH_TOKEN"; // Obtained from REST API + +```typescript +const sessionId: string = "UNIQUE_SESSION_ID"; // Generate a unique session ID +const userAuthToken: string = "USER_AUTH_TOKEN"; // Obtained from REST API CometChatCalls.generateToken(sessionId, userAuthToken).then( - (callToken) => { + (callToken: any) => { console.log("Call token generated:", callToken.token); // Use callToken to start the session }, - (error) => { + (error: any) => { console.log("Token generation failed:", error); } ); ``` - -```typescript -const sessionId: string = "UNIQUE_SESSION_ID"; // Generate a unique session ID -const userAuthToken: string = "USER_AUTH_TOKEN"; // Obtained from REST API + +```javascript +const sessionId = "UNIQUE_SESSION_ID"; // Generate a unique session ID +const userAuthToken = "USER_AUTH_TOKEN"; // Obtained from REST API CometChatCalls.generateToken(sessionId, userAuthToken).then( - (callToken: any) => { + (callToken) => { console.log("Call token generated:", callToken.token); // Use callToken to start the session }, - (error: any) => { + (error) => { console.log("Token generation failed:", error); } ); @@ -77,6 +98,8 @@ CometChatCalls.generateToken(sessionId, userAuthToken).then( | `sessionId` | A unique session ID for the call. Generate this yourself or use a shared ID for participants to join the same call. | | `userAuthToken` | The user auth token obtained from the CometChat REST API. | +The `Promise` resolves with an object containing a `token` property (string) that you pass to `startSession()`. + ## Start Call Session Use the `startSession()` method to join a call session. This method requires: @@ -85,16 +108,16 @@ Use the `startSession()` method to join a call session. This method requires: 3. An HTML element where the call UI will be rendered - -```javascript + +```typescript const callListener = new CometChatCalls.OngoingCallListener({ - onUserJoined: (user) => { + onUserJoined: (user: any) => { console.log("User joined:", user); }, - onUserLeft: (user) => { + onUserLeft: (user: any) => { console.log("User left:", user); }, - onUserListUpdated: (userList) => { + onUserListUpdated: (userList: any[]) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -107,13 +130,13 @@ const callListener = new CometChatCalls.OngoingCallListener({ CometChatCalls.endSession(); // Close calling screen }, - onError: (error) => { + onError: (error: any) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList) => { + onMediaDeviceListUpdated: (deviceList: any[]) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event) => { + onUserMuted: (event: any) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -122,7 +145,7 @@ const callListener = new CometChatCalls.OngoingCallListener({ onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event) => { + onCallSwitchedToVideo: (event: any) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -136,20 +159,69 @@ const callSettings = new CometChatCalls.CallSettingsBuilder() .setCallListener(callListener) .build(); -const htmlElement = document.getElementById("call-container"); +const htmlElement = document.getElementById("call-container") as HTMLElement; CometChatCalls.startSession(callToken, callSettings, htmlElement); ``` - -```typescript + + +| Parameter | Description | +| -------------- | -------------------------------------------------------- | +| `callToken` | The token received from `generateToken()` onSuccess | +| `callSettings` | Object of `CallSettings` class configured via `CallSettingsBuilder` | +| `htmlElement` | DOM element where the call UI will be rendered | + +`startSession()` renders the call UI inside the provided HTML element and joins the user into the active call session. + +### Call Settings + +Configure the call experience using the following `CallSettingsBuilder` methods: + +| Method | Description | +| ------ | ----------- | +| `enableDefaultLayout(boolean)` | Enables or disables the default call UI layout with built-in controls. `true` shows the default layout. `false` hides the button layout. Default: `true` | +| `setIsAudioOnlyCall(boolean)` | Sets whether the call is audio-only or audio-video. `true` for audio-only, `false` for audio-video. Default: `false` | +| `setCallListener(OngoingCallListener)` | Sets the listener to receive call events. See [Call Listeners](#call-listeners). | +| `setMode(string)` | Sets the call UI layout mode. Available: `CometChat.CALL_MODE.DEFAULT`, `CometChat.CALL_MODE.SPOTLIGHT`. Default: `DEFAULT` | +| `startWithAudioMuted(boolean)` | Starts the call with the microphone muted. Default: `false` | +| `startWithVideoMuted(boolean)` | Starts the call with the camera turned off. Default: `false` | +| `showEndCallButton(boolean)` | Shows or hides the end call button in the default layout. Default: `true` | +| `showMuteAudioButton(boolean)` | Shows or hides the mute audio button. Default: `true` | +| `showPauseVideoButton(boolean)` | Shows or hides the pause video button. Default: `true` | +| `showScreenShareButton(boolean)` | Shows or hides the screen share button. Default: `true` | +| `showModeButton(boolean)` | Shows or hides the mode toggle button (switch between DEFAULT and SPOTLIGHT). Default: `true` | +| `showSwitchToVideoCallButton(boolean)` | Shows or hides the button to upgrade an audio call to video. Default: `true` | +| `setMainVideoContainerSetting(MainVideoContainerSetting)` | Customizes the main video container. See [Video View Customization](/sdk/javascript/video-view-customisation). | +| `setIdleTimeoutPeriod(number)` | Sets idle timeout in seconds. Warning appears 60 seconds before auto-termination. Default: `180` seconds. *v4.1.0+* | + +## Call Listeners + +The `OngoingCallListener` provides real-time callbacks for call session events, including participant changes, call state updates, and error conditions. + + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + +You can register listeners in two ways: + +1. **Via CallSettingsBuilder:** Use `.setCallListener(listener)` when building call settings +2. **Via addCallEventListener:** Use `CometChatCalls.addCallEventListener(listenerId, listener)` to add multiple listeners + +Each listener requires a unique `listenerId` string. This ID is used to: +- **Prevent duplicate registrations** — Re-registering with the same ID replaces the existing listener +- **Enable targeted removal** — Remove specific listeners without affecting others + + + +```javascript const callListener = new CometChatCalls.OngoingCallListener({ - onUserJoined: (user: any) => { + onUserJoined: (user) => { console.log("User joined:", user); }, - onUserLeft: (user: any) => { + onUserLeft: (user) => { console.log("User left:", user); }, - onUserListUpdated: (userList: any[]) => { + onUserListUpdated: (userList) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -162,13 +234,13 @@ const callListener = new CometChatCalls.OngoingCallListener({ CometChatCalls.endSession(); // Close calling screen }, - onError: (error: any) => { + onError: (error) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList: any[]) => { + onMediaDeviceListUpdated: (deviceList) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event: any) => { + onUserMuted: (event) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -177,7 +249,7 @@ const callListener = new CometChatCalls.OngoingCallListener({ onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event: any) => { + onCallSwitchedToVideo: (event) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -191,7 +263,7 @@ const callSettings = new CometChatCalls.CallSettingsBuilder() .setCallListener(callListener) .build(); -const htmlElement = document.getElementById("call-container") as HTMLElement; +const htmlElement = document.getElementById("call-container"); CometChatCalls.startSession(callToken, callSettings, htmlElement); ``` @@ -224,6 +296,29 @@ Configure the call experience using the following `CallSettingsBuilder` methods: | `setMainVideoContainerSetting(MainVideoContainerSetting)` | Customizes the main video container. See [Video View Customization](/sdk/javascript/video-view-customisation). | | `setIdleTimeoutPeriod(number)` | Sets idle timeout in seconds. Warning appears 60 seconds before auto-termination. Default: `180` seconds. *v4.1.0+* | +## End Call Session + +To end the call session and release all media resources (camera, microphone, network connections), call `CometChatCalls.endSession()` in the `onCallEndButtonPressed()` callback. + + + +```typescript +onCallEndButtonPressed: () => { + CometChatCalls.endSession(); + // Close the calling screen +} +``` + + +```javascript +onCallEndButtonPressed: () => { + CometChatCalls.endSession(); + // Close the calling screen +} +``` + + + ## Call Listeners The `OngoingCallListener` provides real-time callbacks for call session events, including participant changes, call state updates, and error conditions. @@ -237,19 +332,23 @@ Each listener requires a unique `listenerId` string. This ID is used to: - **Prevent duplicate registrations** — Re-registering with the same ID replaces the existing listener - **Enable targeted removal** — Remove specific listeners without affecting others + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + + - -```javascript -const listenerId = "UNIQUE_LISTENER_ID"; + +```typescript +const listenerId: string = "UNIQUE_LISTENER_ID"; CometChatCalls.addCallEventListener(listenerId, { - onUserJoined: (user) => { + onUserJoined: (user: any) => { console.log("User joined:", user); }, - onUserLeft: (user) => { + onUserLeft: (user: any) => { console.log("User left:", user); }, - onUserListUpdated: (userList) => { + onUserListUpdated: (userList: any[]) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -262,13 +361,13 @@ CometChatCalls.addCallEventListener(listenerId, { CometChatCalls.endSession(); // Close calling screen }, - onError: (error) => { + onError: (error: any) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList) => { + onMediaDeviceListUpdated: (deviceList: any[]) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event) => { + onUserMuted: (event: any) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -277,7 +376,7 @@ CometChatCalls.addCallEventListener(listenerId, { onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event) => { + onCallSwitchedToVideo: (event: any) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -289,18 +388,18 @@ CometChatCalls.addCallEventListener(listenerId, { CometChatCalls.removeCallEventListener(listenerId); ``` - -```typescript -const listenerId: string = "UNIQUE_LISTENER_ID"; + +```javascript +const listenerId = "UNIQUE_LISTENER_ID"; CometChatCalls.addCallEventListener(listenerId, { - onUserJoined: (user: any) => { + onUserJoined: (user) => { console.log("User joined:", user); }, - onUserLeft: (user: any) => { + onUserLeft: (user) => { console.log("User left:", user); }, - onUserListUpdated: (userList: any[]) => { + onUserListUpdated: (userList) => { console.log("User list updated:", userList); }, onCallEnded: () => { @@ -313,13 +412,13 @@ CometChatCalls.addCallEventListener(listenerId, { CometChatCalls.endSession(); // Close calling screen }, - onError: (error: any) => { + onError: (error) => { console.log("Call error:", error); }, - onMediaDeviceListUpdated: (deviceList: any[]) => { + onMediaDeviceListUpdated: (deviceList) => { console.log("Device list updated:", deviceList); }, - onUserMuted: (event: any) => { + onUserMuted: (event) => { console.log("User muted:", event); }, onScreenShareStarted: () => { @@ -328,7 +427,7 @@ CometChatCalls.addCallEventListener(listenerId, { onScreenShareStopped: () => { console.log("Screen sharing stopped"); }, - onCallSwitchedToVideo: (event: any) => { + onCallSwitchedToVideo: (event) => { console.log("Call switched to video:", event); }, onSessionTimeout: () => { @@ -344,45 +443,9 @@ CometChatCalls.removeCallEventListener(listenerId); ### Events -| Event | Description | -| ----- | ----------- | -| `onCallEnded()` | Invoked when the call session terminates for a 1:1 call. Both participants receive this callback. Only fires for calls with exactly 2 participants. | -| `onSessionTimeout()` | Invoked when the call is auto-terminated due to inactivity (default: 180 seconds). Warning appears 60 seconds before. *v4.1.0+* | -| `onCallEndButtonPressed()` | Invoked when the local user clicks the end call button. Call `CometChatCalls.endSession()` to leave the session. | -| `onUserJoined(user)` | Invoked when a remote participant joins. The `user` contains UID, name, and avatar. | -| `onUserLeft(user)` | Invoked when a remote participant leaves the call session. | -| `onUserListUpdated(userList)` | Invoked whenever the participant list changes (join or leave events). | -| `onMediaDeviceListUpdated(deviceList)` | Invoked when available audio/video devices change (e.g., new microphone connected). | -| `onUserMuted(event)` | Invoked when a participant's mute state changes. Contains `muted` and `mutedBy` properties. | -| `onScreenShareStarted()` | Invoked when the local user starts sharing their screen. | -| `onScreenShareStopped()` | Invoked when the local user stops sharing their screen. | -| `onCallSwitchedToVideo(event)` | Invoked when an audio call is upgraded to a video call. Contains `sessionId`, `initiator`, and `responder`. | -| `onError(error)` | Invoked when an error occurs during the call session. | +For the full list of callbacks, their descriptions, and parameter shapes, see the [`OngoingCallListener`](/sdk/javascript/all-real-time-listeners#ongoing-call-listener-calls-sdk) reference. -## End Call Session - -To end the call session and release all media resources (camera, microphone, network connections), call `CometChatCalls.endSession()` in the `onCallEndButtonPressed()` callback. - - - -```javascript -onCallEndButtonPressed: () => { - CometChatCalls.endSession(); - // Close the calling screen -} -``` - - -```typescript -onCallEndButtonPressed: () => { - CometChatCalls.endSession(); - // Close the calling screen -} -``` - - - -## Methods +## In-Call Methods These methods are available for performing custom actions during an active call session. Use them to build custom UI controls or implement specific behaviors based on your use case. @@ -395,13 +458,13 @@ These methods can only be called when a call session is active. Toggles between the front and rear camera during a video call. Only supported on mobile browsers. - -```javascript + +```typescript CometChatCalls.switchCamera(); ``` - -```typescript + +```javascript CometChatCalls.switchCamera(); ``` @@ -419,13 +482,13 @@ Controls the local audio stream transmission. When muted, other participants can - `false` — Unmutes the microphone, resumes audio transmission - -```javascript + +```typescript CometChatCalls.muteAudio(true); ``` - -```typescript + +```javascript CometChatCalls.muteAudio(true); ``` @@ -439,13 +502,13 @@ Controls the local video stream transmission. When paused, other participants se - `false` — Resumes the camera, continues video transmission - -```javascript + +```typescript CometChatCalls.pauseVideo(true); ``` - -```typescript + +```javascript CometChatCalls.pauseVideo(true); ``` @@ -456,13 +519,13 @@ CometChatCalls.pauseVideo(true); Starts sharing your screen or a specific application window with other participants. - -```javascript + +```typescript CometChatCalls.startScreenShare(); ``` - -```typescript + +```javascript CometChatCalls.startScreenShare(); ``` @@ -473,13 +536,13 @@ CometChatCalls.startScreenShare(); Stops the current screen sharing session. - -```javascript + +```typescript CometChatCalls.stopScreenShare(); ``` - -```typescript + +```javascript CometChatCalls.stopScreenShare(); ``` @@ -494,13 +557,13 @@ Changes the call UI layout mode dynamically during the call. - `CometChat.CALL_MODE.SPOTLIGHT` — Focus on the active speaker - -```javascript + +```typescript CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ``` - -```typescript + +```javascript CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ``` @@ -508,17 +571,17 @@ CometChatCalls.setMode(CometChat.CALL_MODE.SPOTLIGHT); ### Get Audio Input Devices -Returns a list of available audio input devices (microphones). +Returns a list of available audio input devices (microphones). Each item is a [`MediaDeviceInfo`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) object with `deviceId`, `label`, and `kind` properties. - -```javascript + +```typescript const audioInputDevices = CometChatCalls.getAudioInputDevices(); console.log("Available microphones:", audioInputDevices); ``` - -```typescript + +```javascript const audioInputDevices = CometChatCalls.getAudioInputDevices(); console.log("Available microphones:", audioInputDevices); ``` @@ -527,17 +590,17 @@ console.log("Available microphones:", audioInputDevices); ### Get Audio Output Devices -Returns a list of available audio output devices (speakers/headphones). +Returns a list of available audio output devices (speakers/headphones). Each item is a [`MediaDeviceInfo`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) object. - -```javascript + +```typescript const audioOutputDevices = CometChatCalls.getAudioOutputDevices(); console.log("Available speakers:", audioOutputDevices); ``` - -```typescript + +```javascript const audioOutputDevices = CometChatCalls.getAudioOutputDevices(); console.log("Available speakers:", audioOutputDevices); ``` @@ -546,17 +609,17 @@ console.log("Available speakers:", audioOutputDevices); ### Get Video Input Devices -Returns a list of available video input devices (cameras). +Returns a list of available video input devices (cameras). Each item is a [`MediaDeviceInfo`](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) object. - -```javascript + +```typescript const videoInputDevices = CometChatCalls.getVideoInputDevices(); console.log("Available cameras:", videoInputDevices); ``` - -```typescript + +```javascript const videoInputDevices = CometChatCalls.getVideoInputDevices(); console.log("Available cameras:", videoInputDevices); ``` @@ -568,13 +631,13 @@ console.log("Available cameras:", videoInputDevices); Sets the active audio input device (microphone) by device ID. - -```javascript + +```typescript CometChatCalls.setAudioInputDevice(deviceId); ``` - -```typescript + +```javascript CometChatCalls.setAudioInputDevice(deviceId); ``` @@ -585,13 +648,13 @@ CometChatCalls.setAudioInputDevice(deviceId); Sets the active audio output device (speaker/headphones) by device ID. - -```javascript + +```typescript CometChatCalls.setAudioOutputDevice(deviceId); ``` - -```typescript + +```javascript CometChatCalls.setAudioOutputDevice(deviceId); ``` @@ -602,13 +665,13 @@ CometChatCalls.setAudioOutputDevice(deviceId); Sets the active video input device (camera) by device ID. - -```javascript + +```typescript CometChatCalls.setVideoInputDevice(deviceId); ``` - -```typescript + +```javascript CometChatCalls.setVideoInputDevice(deviceId); ``` @@ -619,13 +682,13 @@ CometChatCalls.setVideoInputDevice(deviceId); Upgrades an ongoing audio call to a video call. This enables the camera and starts transmitting video to other participants. The remote participant receives the `onCallSwitchedToVideo()` callback. - -```javascript + +```typescript CometChatCalls.switchToVideoCall(); ``` - -```typescript + +```javascript CometChatCalls.switchToVideoCall(); ``` @@ -636,14 +699,27 @@ CometChatCalls.switchToVideoCall(); Terminates the current call session and releases all media resources (camera, microphone, network connections). After calling this method, the call view should be closed. - -```javascript + +```typescript CometChatCalls.endSession(); ``` - -```typescript + +```javascript CometChatCalls.endSession(); ``` + +--- + +## Next Steps + + + + Implement ringing call flows using the Chat SDK + + + Add call recording to your voice and video calls + + diff --git a/sdk/javascript/threaded-messages.mdx b/sdk/javascript/threaded-messages.mdx index e2d29a55a..a203f7c1e 100644 --- a/sdk/javascript/threaded-messages.mdx +++ b/sdk/javascript/threaded-messages.mdx @@ -1,42 +1,36 @@ --- title: "Threaded Messages" +sidebarTitle: "Threaded Messages" +description: "Send, receive, and fetch threaded messages using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Send message in a thread +const msg = new CometChat.TextMessage("UID", "Reply", CometChat.RECEIVER_TYPE.USER); +msg.setParentMessageId(100); +await CometChat.sendMessage(msg); + +// Fetch thread messages +const request = new CometChat.MessagesRequestBuilder() + .setParentMessageId(100).setLimit(30).build(); +const messages = await request.fetchPrevious(); + +// Exclude thread replies from main conversation +const request = new CometChat.MessagesRequestBuilder() + .setUID("UID").setLimit(30).hideReplies(true).build(); +``` + -Messages that are started from a particular message are called Threaded messages or simply threads. Each Thread is attached to a message which is the Parent message for that thread. +Threaded messages (or threads) are messages started from a particular parent message. Each thread is attached to a parent message. ## Send Message in a Thread -As mentioned in the [Send a Message](/sdk/javascript/send-message) section. You can either send a message to a User or a Group based on the `receiverType` and the UID/GUID specified for the message. A message can belong to either of the below types: - -1. Text Message -2. Media Message -3. Custom Message. - -Any of the above messages can be sent in a thread. As mentioned, a thread is identified based on the Parent message. So while sending a message the `parentMessageId` must be set for the message to indicate that the message to be sent needs to be a part of the thread with the specified `parentMessageId`. - -This can be achieved using the `setParentMessageId()` method provided by the object of the `TextMessage`, `MediaMessage` and `CustomMessage` class. The id specified in the `setParentMessageId()` method maps the message sent to the particular thread. - -**Example to Send a Text Message in a thread in a user conversation.** +Any message type (Text, Media, or Custom) can be sent in a thread. Set the `parentMessageId` using `setParentMessageId()` to indicate which thread the message belongs to. - -```javascript -let textMessage = new CometChat.TextMessage(UID, "Hello", CometChat.RECEIVER_TYPE.USER); -textMessage.setParentMessageId(100); - -CometChat.sendMessage(textMessage).then( - message => { - console.log('Message sent successfully', message); - }, err => { - console.log('err', err); - } -) -``` - - - ```typescript let receiverId = "UID", @@ -57,52 +51,35 @@ CometChat.sendMessage(textMessage).then( - - -The above snippet shows how a message with the text "Hello" can be sent in the thread with `parentMessageId` 100. - -Similarly, using the `setParentMessageId()` method, Media and Custom Messages can be sent in threads too. - -### Receiving Real-Time Messages - -The procedure to receive real-time messages is exactly the same as mentioned in the [Receive Messages](/sdk/javascript/receive-message). This can be achieved using the `MessageListener` class provided by the SDK. - -To add a MessageListener, you can use the `addMessageListener()` method of the SDK. The only thing that needs to be checked is if the received message belongs to the active thread. This can be done using the `parentMessageId` field of the message object. - - - + ```javascript -var listenerID = "UNIQUE_LISTENER_ID"; -var activeThreadId = 100; +let textMessage = new CometChat.TextMessage(UID, "Hello", CometChat.RECEIVER_TYPE.USER); +textMessage.setParentMessageId(100); -CometChat.addMessageListener( -listenerID, -new CometChat.MessageListener({ - onTextMessageReceived: textMessage => { - if(textMessage.getParentMessageId() == activeThreadId) { - console.log("Text message received for active thread.", textMessage); - } - }, - onMediaMessageReceived: mediaMessage => { - if(mediaMessage.getParentMessageId() == activeThreadId) { - console.log("Media message received for active thread.", mediaMessage); - } - }, - onCustomMessageReceived: customMessage => { - if(customMessage.getParentMessageId() == activeThreadId) { - console.log("Custom message received for active thread.", customMessage); - } +CometChat.sendMessage(textMessage).then( + message => { + console.log('Message sent successfully', message); + }, err => { + console.log('err', err); } -}) -); +) ``` + + +The above snippet sends "Hello" in the thread with `parentMessageId` 100. Media and Custom messages can also be sent in threads using `setParentMessageId()`. + +### Receiving Real-Time Messages + +Use `MessageListener` to receive real-time thread messages. Check if the received message belongs to the active thread using `getParentMessageId()`. + + ```typescript -var listenerID: string = "UNIQUE_LISTENER_ID", - activeThreadId: number = 100; +const listenerID: string = "UNIQUE_LISTENER_ID"; +const activeThreadId: number = 100; CometChat.addMessageListener( listenerID, @@ -128,35 +105,42 @@ CometChat.addMessageListener( - - -### Fetch all the messages for any particular thread. - -You can fetch all the messages belonging to a particular thread by using the `MessagesRequest` class. In order to get an object of the `MessagesRequest` class, you need to use the `MessagesRequestBuilder` class. and use the `setParentMessageId()` method of the `MessagesRequestBuilder` to inform the SDK that you only need the messages belonging to the thread with the specified parentMessageId. - -Once you have the object of the `MessagesRequest` class, you need to call the `fetchPrevious()` method to get the latest messages in the thread. In one integration, a maximum of 100 messages can be fetched. If you wish to fetch the next set of messages, you need to call the `fetchPrevious()` method again on the same object. - - - + ```javascript -let limit = 30; -let parentMessageId = 1; -let messagesRequest = new CometChat.MessagesRequestBuilder() - .setLimit(limit) - .setParentMessageId(parentMessageId) - .build(); - -messagesRequest.fetchPrevious().then( - messages => { - console.log("Messages for thread fetched successfully", messages); - }, error => { - console.log("Message fetching failed with error:", error); +const listenerID = "UNIQUE_LISTENER_ID"; +const activeThreadId = 100; + +CometChat.addMessageListener( +listenerID, +new CometChat.MessageListener({ + onTextMessageReceived: textMessage => { + if(textMessage.getParentMessageId() == activeThreadId) { + console.log("Text message received for active thread.", textMessage); + } + }, + onMediaMessageReceived: mediaMessage => { + if(mediaMessage.getParentMessageId() == activeThreadId) { + console.log("Media message received for active thread.", mediaMessage); + } + }, + onCustomMessageReceived: customMessage => { + if(customMessage.getParentMessageId() == activeThreadId) { + console.log("Custom message received for active thread.", customMessage); + } } -); +}) +); ``` + + +### Fetch all the messages for any particular thread. + +Use `MessagesRequestBuilder` with `setParentMessageId()` to fetch messages belonging to a specific thread. Call `fetchPrevious()` to get messages (max 100 per request). + + ```typescript let limit: number = 30, @@ -177,11 +161,33 @@ messagesRequest.fetchPrevious().then( + +```javascript +let limit = 30; +let parentMessageId = 1; +let messagesRequest = new CometChat.MessagesRequestBuilder() + .setLimit(limit) + .setParentMessageId(parentMessageId) + .build(); + +messagesRequest.fetchPrevious().then( + messages => { + console.log("Messages for thread fetched successfully", messages); + }, error => { + console.log("Message fetching failed with error:", error); + } +); +``` + + + +The `fetchPrevious()` method returns an array of [`BaseMessage`](/sdk/reference/messages#basemessage) objects representing thread replies. + ## Avoid Threaded Messages in User/Group Conversations -While fetching messages for normal user/group conversations using the `MessagesRequest`, the threaded messages by default will be a part of the list of messages received. In order to exclude the threaded messages from the list of user/group messages, you need to use the `hideReplies()` method of the `MessagesRequestBuilder` class. This method takes a boolean argument which when set to true excludes the messages belonging to threads from the list of messages. +Use `hideReplies(true)` to exclude threaded messages when fetching messages for a conversation. @@ -270,4 +276,17 @@ messagesRequest.fetchPrevious().then( -The above snippet will return messages between the logged in user and `cometchat-uid-1` excluding all the threaded messages belonging to the same conversation. +The response is an array of [`BaseMessage`](/sdk/reference/messages#basemessage) objects, excluding any messages that are replies within a thread. Only top-level messages in the conversation are returned. + +--- + +## Next Steps + + + + Send text, media, and custom messages to users and groups + + + Listen for incoming messages in real-time and fetch missed messages + + diff --git a/sdk/javascript/transfer-group-ownership.mdx b/sdk/javascript/transfer-group-ownership.mdx index 1de52a892..bb50b7896 100644 --- a/sdk/javascript/transfer-group-ownership.mdx +++ b/sdk/javascript/transfer-group-ownership.mdx @@ -1,44 +1,68 @@ --- title: "Transfer Group Ownership" +sidebarTitle: "Transfer Ownership" +description: "Transfer ownership of a CometChat group to another member using the JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Transfer group ownership +await CometChat.transferGroupOwnership("GUID", "NEW_OWNER_UID"); +``` -*In other words, as a logged-in user, how do I transfer the ownership of any group if I am the owner of the group?* +**Note:** Only the current group owner can transfer ownership. The owner must transfer ownership before leaving the group. + -In order to transfer the ownership of any group, the first condition is that you must be the owner of the group. In case you are the owner of the group, you can use the `transferGroupOwnership()` method provided by the `CometChat` class. +Only the owner of a [Group](/sdk/reference/entities#group) can transfer ownership. Since owners cannot leave their group, you must transfer ownership first if you want to leave. -This will be helpful as the owner is not allowed to leave the group. In case, you as the owner would like to leave the group, you will have to use this method and transfer your ownership first to any other member of the group and only then you will be allowed to leave the group. +Use `transferGroupOwnership()` to transfer ownership to another member. - -```javascript -let GUID = "GUID"; -let UID = "UID"; + +```typescript +let GUID: string = "GUID"; +let UID: string = "UID"; CometChat.transferGroupOwnership(GUID, UID).then( - () => { + (ownershipTransferred: string) => { console.log("Successfully transferred ownership of the group."); }, error => { console.log("Could not transfer ownership of the group: ", error); } -) +); ``` - -```typescript -let GUID: string = "GUID"; -let UID: string = "UID"; + +```javascript +let GUID = "GUID"; +let UID = "UID"; CometChat.transferGroupOwnership(GUID, UID).then( - (ownershipTransferred: string) => { + () => { console.log("Successfully transferred ownership of the group."); }, error => { console.log("Could not transfer ownership of the group: ", error); } -); +) ``` + +On success, the method resolves with a success message string confirming the operation. + +--- + +## Next Steps + + + + Leave a group after transferring ownership + + + Promote or demote group members + + diff --git a/sdk/javascript/transient-messages.mdx b/sdk/javascript/transient-messages.mdx index 9f44b2267..f6ed8783f 100644 --- a/sdk/javascript/transient-messages.mdx +++ b/sdk/javascript/transient-messages.mdx @@ -1,8 +1,23 @@ --- title: "Transient Messages" +sidebarTitle: "Transient Messages" +description: "Send and receive ephemeral real-time messages that are not stored on the server using the CometChat JavaScript SDK. Ideal for live reactions and temporary indicators." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Send transient message to user +const msg = new CometChat.TransientMessage("UID", CometChat.RECEIVER_TYPE.USER, { LIVE_REACTION: "heart" }); +CometChat.sendTransientMessage(msg); + +// Listen for transient messages +CometChat.addMessageListener("LISTENER_ID", new CometChat.MessageListener({ + onTransientMessageReceived: (msg) => console.log("Transient:", msg) +})); +``` + Transient messages are messages that are sent in real-time only and are not saved or tracked anywhere. The receiver of the message will only receive the message if he is online and these messages cannot be retrieved later. @@ -61,32 +76,20 @@ CometChat.sendTransientMessage(transientMessage); +`sendTransientMessage()` returns `void` — the message is sent as a fire-and-forget operation with no response. + ## Real-time Transient Messages -*In other words, as a recipient, how do I know when someone sends a transient message?* + +Always remove listeners when they're no longer needed (e.g., on component unmount or page navigation). Failing to remove listeners can cause memory leaks and duplicate event handling. + You will receive the transient message in the `onTransientMessageReceived()` method of the registered `MessageListener` class. - -```javascript -let listenerId = "UNIQUE_LITENER_ID"; - -CometChat.addMessageListener( -listenerId, -new CometChat.MessageListener({ - onTransientMessageReceived: transientMessage => { - console.log('transient message received', transientMessage); - }, -}) -); -``` - - - ```typescript -let listenerId: string = "UNIQUE_LITENER_ID"; +let listenerId: string = "UNIQUE_LISTENER_ID"; CometChat.addMessageListener( listenerId, @@ -100,13 +103,35 @@ CometChat.addMessageListener( + +```javascript +let listenerId = "UNIQUE_LISTENER_ID"; + +CometChat.addMessageListener( +listenerId, +new CometChat.MessageListener({ + onTransientMessageReceived: transientMessage => { + console.log('transient message received', transientMessage); + }, +}) +); +``` + + + -The `TransientMessage` class consists of the below parameters: +The received object is a [`TransientMessage`](/sdk/reference/auxiliary#transientmessage). + +--- + +## Next Steps -| Parameter | Information | -| ---------------- | -------------------------------------------------------------------------------------------------------- | -| **sender** | An object of the User class holding all the information. related to the sender of the transient message. | -| **receiverId** | Unique Id of the receiver. This can be the Id of the group or the user the transient message is sent to. | -| **receiverType** | The type of the receiver - `CometChat.RECEIVER_TYPE.USER` or `CometChat.RECEIVER_TYPE.GROUP` | -| **data** | A JSONObject to provide data. | + + + Show real-time typing status in conversations + + + Send text, media, and custom messages + + diff --git a/sdk/javascript/troubleshooting.mdx b/sdk/javascript/troubleshooting.mdx new file mode 100644 index 000000000..03a532438 --- /dev/null +++ b/sdk/javascript/troubleshooting.mdx @@ -0,0 +1,186 @@ +--- +title: "Troubleshooting" +sidebarTitle: "Troubleshooting" +description: "Common failure modes and fixes for the CometChat JavaScript SDK." +--- + +Find solutions to common issues when building with the CometChat JavaScript SDK. + + + +| Issue | Fix | +|-------|-----| +| `init()` fails | Verify App ID and Region from [Dashboard](https://app.cometchat.com) | +| Login fails with "UID not found" | Create user via Dashboard or REST API first | +| SDK methods fail | Ensure `init()` completes before calling other methods | +| No real-time events | Check WebSocket connection, verify listeners registered | +| SSR errors | Use dynamic imports or `useEffect` for client-side only | + + + +--- + +## Initialization & Authentication + +| Symptom | Cause | Fix | +|---------|-------|-----| +| `init()` fails with "App ID not found" | Invalid App ID or Region | Verify credentials in [Dashboard](https://app.cometchat.com) → API & Auth Keys | +| `init()` fails silently | Missing credentials | Double-check App ID and Region are strings, not undefined | +| "CometChat not initialized" | `init()` not awaited | Ensure `init()` resolves before calling other methods | +| Login fails with "UID not found" | User doesn't exist | Create user via [Dashboard](https://app.cometchat.com) or [REST API](https://api-explorer.cometchat.com/reference/creates-user) | +| Login fails with "Auth Key is not valid" | Wrong Auth Key | Verify Auth Key in Dashboard. Don't confuse with REST API Key | +| `getLoggedinUser()` returns null | Session cleared or `init()` not called | Call `init()` on every app load before checking session | +| Auth Token expired | Token lifetime exceeded | Generate new token via [REST API](https://api-explorer.cometchat.com/reference/create-authtoken) | +| User appears offline after login | Presence not configured | Use `subscribePresenceForAllUsers()` in `AppSettingsBuilder` | + +--- + +## Messaging + +| Symptom | Cause | Fix | +|---------|-------|-----| +| `sendMessage()` fails | Not logged in or invalid receiver | Ensure `login()` completes. Verify receiver UID/GUID exists | +| Messages sent but not received | Listener not registered | Register `addMessageListener()` with `onTextMessageReceived` | +| Duplicate messages | Multiple listeners | Use unique listener IDs. Remove old listeners first | +| Wrong conversation | Wrong receiver type | Use `RECEIVER_TYPE.USER` for 1:1, `RECEIVER_TYPE.GROUP` for groups | +| Media upload fails | File too large or unsupported | Check limits. Supported: PNG, JPG, GIF, MP4, MP3, WAV | +| Metadata not appearing | Set after send | Call `setMetadata()` before the send method | +| Pagination not working | New request object | Reuse the same `MessagesRequest` for `fetchPrevious()`/`fetchNext()` | +| Thread replies in main chat | Missing filter | Add `.hideReplies(true)` to `MessagesRequestBuilder` | +| Deleted messages showing | Missing filter | Add `.hideDeletedMessages(true)` | + +--- + +## Groups + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Cannot join group | Invalid GUID | Verify GUID. Create group first if needed | +| Cannot send to group | Not a member | Join group first with `joinGroup()` | +| Cannot kick/ban members | Insufficient scope | Only admins and moderators can kick/ban | +| Can't join private group | Requires invite | Private groups require admin to add you | +| Owner can't leave | Ownership not transferred | Call `transferGroupOwnership()` first | +| Password join fails | Wrong password | Pass correct password as second parameter | +| `fetchNext()` returns same results | New request object | Reuse the same `GroupsRequest` instance | +| Scope filter returns nothing | Invalid strings | Use `"admin"`, `"moderator"`, `"participant"` | +| Status filter not working | Wrong constant | Use `CometChat.USER_STATUS.ONLINE`/`OFFLINE` | +| Cannot demote admin | Not owner | Only group owner can demote admins | +| Kicked user can still see group | Kick vs ban | Use `banGroupMember()` to prevent rejoining | + +--- + +## Calling + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Calls SDK not found | Not installed | Run `npm install @cometchat/calls-sdk-javascript` | +| No audio/video | Permissions denied | Check browser permissions for camera/microphone | +| Call not connecting | Session ID mismatch | Verify both participants use same session ID | +| One-way audio | Firewall blocking WebRTC | Check network config. Corporate networks may block WebRTC | +| Incoming call not showing | Listener not registered | Register `addCallListener()` at app root level | +| Black screen after joining | Element not visible | Ensure HTML element has proper dimensions | +| CSS changes not applying | Specificity issue | Try adding `!important` | +| Styles only work in one mode | Mode-specific classes | Test in `DEFAULT`, `TILE`, and `SPOTLIGHT` modes | + +--- + +## WebSocket & Connection + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Real-time events not received | WebSocket disconnected | Check `getConnectionStatus()`. Reconnect if needed | +| WebSocket fails | Firewall blocking | Check network config. Corporate firewalls may block WebSocket | +| Connection drops frequently | Network instability | Use `addConnectionListener()` to monitor and reconnect | +| Stuck in "connecting" | Network or config issue | Verify network, `appId`, and `region` | +| No events after login | Auto-connect disabled | Call `CometChat.connect()` manually if `autoEstablishSocketConnection(false)` | +| `connect()` doesn't work | Not logged in | Ensure user is logged in first | + +--- + +## Listeners + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Events not firing | Registered before init | Register after `init()` and `login()` complete | +| Duplicate events | Multiple listeners | Remove old listeners before adding new ones | +| Missing events after navigation | Listeners removed | Re-register when new component mounts | +| Receipt events not triggering | Receipts not sent | Call `markAsDelivered()`/`markAsRead()` explicitly | + +--- + +## Typing, Receipts & Reactions + +| Symptom | Cause | Fix | +|---------|-------|-----| +| Typing indicator stuck | `endTyping()` not called | Call on send, blur, or after 3-5s timeout | +| Double-tick not showing | `markAsDelivered()` not called | Call on message fetch and real-time receive | +| Group receipts missing | Feature not enabled | Enable "Enhanced Messaging Status" in Dashboard | +| Reaction not appearing | UI not synced | Call `updateMessageWithReactionInfo()` on events | +| Duplicate reactions | No check before adding | Use `getReactedByMe()` first | + +--- + +## AI Features + +| Symptom | Cause | Fix | +|---------|-------|-----| +| AI features not appearing | Not enabled | Enable in [Dashboard](https://app.cometchat.com) → AI Features | +| AI Agents not responding | Not configured | Configure Agent in Dashboard. Agents only respond to text | +| `onAIAssistantEventReceived` not firing | Listener not registered | Register `AIAssistantListener` after login | +| Moderation always PENDING | Rules not configured | Configure rules in Dashboard → Moderation → Rules | +| Agentic messages not arriving | Wrong listener | Use `MessageListener` with `onAIAssistantMessageReceived` | + +--- + +## SSR / Framework-Specific + +| Symptom | Cause | Fix | +|---------|-------|-----| +| "window is not defined" | SDK accessed during SSR | Use dynamic imports or `useEffect` | +| Next.js SSR error | Server render | Use `await import('@cometchat/chat-sdk-javascript')` | +| Nuxt "document is not defined" | Server render | Import in `mounted()` lifecycle hook | +| React Native errors | Wrong SDK | Use `@cometchat/chat-sdk-react-native` | + +--- + +## Upgrading from V3 + +| Symptom | Cause | Fix | +|---------|-------|-----| +| "Module not found" | Old import paths | Replace `@cometchat-pro/chat` with `@cometchat/chat-sdk-javascript` | +| Calls SDK not working | Wrong package | Use `@cometchat/calls-sdk-javascript` | +| Both versions installed | Package conflict | Remove v3 package completely | + +--- + +## Error Codes + +| Code | Description | Resolution | +|------|-------------|------------| +| `ERR_UID_NOT_FOUND` | User doesn't exist | Create user via Dashboard or REST API | +| `ERR_AUTH_KEY_NOT_FOUND` | Invalid Auth Key | Verify in Dashboard | +| `ERR_APP_NOT_FOUND` | Invalid App ID or Region | Check Dashboard | +| `ERR_NOT_LOGGED_IN` | No active session | Call `login()` first | +| `ERR_GUID_NOT_FOUND` | Group doesn't exist | Create group or verify GUID | +| `ERR_NOT_A_MEMBER` | Not a group member | Join group first | +| `ERR_BLOCKED` | User is blocked | Unblock via Dashboard or SDK | +| `ERR_RATE_LIMIT_EXCEEDED` | Too many requests | See [Rate Limits](/articles/rate-limits) | + +--- + +## Next Steps + + + + Installation and initialization guide + + + Recommended patterns and practices + + + AI Agents, Moderation, and Copilot + + + Open a support ticket + + diff --git a/sdk/javascript/typing-indicators.mdx b/sdk/javascript/typing-indicators.mdx index 0174f5727..10ad79786 100644 --- a/sdk/javascript/typing-indicators.mdx +++ b/sdk/javascript/typing-indicators.mdx @@ -1,16 +1,33 @@ --- title: "Typing Indicators" +sidebarTitle: "Typing Indicators" +description: "Send and receive real-time typing indicators using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Start typing indicator +const typing = new CometChat.TypingIndicator("UID", CometChat.RECEIVER_TYPE.USER); +CometChat.startTyping(typing); + +// Stop typing indicator +CometChat.endTyping(typing); + +// Listen for typing events +CometChat.addMessageListener("LISTENER_ID", new CometChat.MessageListener({ + onTypingStarted: (indicator) => console.log("Typing started:", indicator), + onTypingEnded: (indicator) => console.log("Typing ended:", indicator) +})); +``` + ## Send a Typing Indicator -*In other words, as a sender, how do I let the recipient(s) know that I'm typing?* - ### Start Typing -You can use the `startTyping()` method to inform the receiver that the logged in user has started typing. The receiver will receive this information in the `onTypingStarted()` method of the `MessageListener` class. In order to send the typing indicator, you need to use the `TypingIndicator` class. +Use `startTyping()` with a [`TypingIndicator`](/sdk/reference/auxiliary#typingindicator) object to notify the receiver that you're typing. @@ -59,9 +76,11 @@ CometChat.startTyping(typingNotification); +`startTyping()` returns `void` — the typing indicator is sent as a fire-and-forget operation. + ### Stop Typing -You can use the `endTyping()` method to inform the receiver that the logged in user has stopped typing. The receiver will receive this information in the `onTypingEnded()` method of the `MessageListener` class. In order to send the typing indicator, you need to use the `TypingIndicator` class. +Use `endTyping()` to notify the receiver that you've stopped typing. @@ -110,42 +129,20 @@ CometChat.endTyping(typingNotification); - -Custom Data - -You can use the `metadata` field of the `TypingIndicator` class to pass additional data along with the typing indicators. The metadata field is a JSONObject and can be set using the `setMetadata()` method of the `TypingIndicator` class. This data will be received at the receiver end and can be obtained using the `getMetadata()` method. +`endTyping()` returns `void` — the typing indicator is sent as a fire-and-forget operation. + +Use `setMetadata()` on `TypingIndicator` to pass additional custom data. Retrieve it with `getMetadata()` on the receiver side. ## Real-time Typing Indicators -*In other words, as a recipient, how do I know when someone is typing?* - -You will receive the typing indicators in the `onTypingStarted()` and the `onTypingEnded()` method of the registered `MessageListener` class. +Use `onTypingStarted` and `onTypingEnded` in `MessageListener` to receive typing events. - -```javascript -let listenerId = "UNIQUE_LITENER_ID"; - -CometChat.addMessageListener( -listenerId, -new CometChat.MessageListener({ - onTypingStarted: typingIndicator => { - console.log("Typing started :", typingIndicator); - }, - onTypingEnded: typingIndicator => { - console.log("Typing ended :", typingIndicator); - } -}) -); -``` - - - ```typescript -let listenerId: string = "UNIQUE_LITENER_ID"; +let listenerId: string = "UNIQUE_LISTENER_ID"; CometChat.addMessageListener( listenerId, @@ -162,13 +159,38 @@ CometChat.addMessageListener( + +```javascript +let listenerId = "UNIQUE_LISTENER_ID"; + +CometChat.addMessageListener( +listenerId, +new CometChat.MessageListener({ + onTypingStarted: typingIndicator => { + console.log("Typing started :", typingIndicator); + }, + onTypingEnded: typingIndicator => { + console.log("Typing ended :", typingIndicator); + } +}) +); +``` + + + -The `TypingIndicator` class consists of the below parameters: +The received object is a [`TypingIndicator`](/sdk/reference/auxiliary#typingindicator). + +--- + +## Next Steps -| Parameter | Information | -| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **sender** | An object of the `User` class holding all the information. related to the sender of the typing indicator. | -| **receiverId** | Unique Id of the receiver. This can be the Id of the group or the user the typing indicator is sent to. | -| **receiverType** | This parameter indicates if the typing indicator is to be sent to a user or a group. The possible values are: 1. `CometChat.RECEIVER_TYPE.USER` 2. `CometChat.RECEIVER_TYPE.GROUP` | -| **metadata** | A JSONObject to provider additional data. | + + + Track when messages are delivered and read + + + Send ephemeral real-time messages like live reactions + + diff --git a/sdk/javascript/update-group.mdx b/sdk/javascript/update-group.mdx index 113b79f8b..d29abcc9d 100644 --- a/sdk/javascript/update-group.mdx +++ b/sdk/javascript/update-group.mdx @@ -1,41 +1,31 @@ --- title: "Update A Group" +sidebarTitle: "Update Group" +description: "Update group details such as name, type, icon, and description using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Update group details +const group = new CometChat.Group("GUID", "New Name", CometChat.GROUP_TYPE.PUBLIC); +const updated = await CometChat.updateGroup(group); +``` + ## Update Group -*In other words, as a group owner, how can I update the group details?* - -You can update the existing details of the group using the `updateGroup()` method. +Use `updateGroup()` to modify group details. Pass a `Group` object with the updated values. - -```javascript -var GUID = "GUID"; -var groupName = "Hello Group"; -var groupType = CometChat.GROUP_TYPE.PUBLIC; -var group = new CometChat.Group(GUID, groupName, groupType); - -CometChat.updateGroup(group).then( -group => { - console.log("Groups details updated successfully:", group); -}, error => { - console.log("Group details update failed with exception:", error); -} -); -``` - - - ```typescript -var GUID: string = "GUID"; -var groupName: string = "Hello Group!"; -var groupType: string = CometChat.GROUP_TYPE.PUBLIC; +const GUID: string = "GUID"; +const groupName: string = "Hello Group!"; +const groupType: string = CometChat.GROUP_TYPE.PUBLIC; -var group: CometChat.Group = new CometChat.Group(GUID, groupName, groupType); +const group: CometChat.Group = new CometChat.Group(GUID, groupName, groupType); CometChat.updateGroup(group).then( (group: CometChat.Group) => { @@ -48,18 +38,49 @@ CometChat.updateGroup(group).then( + +```javascript +const GUID = "GUID"; +const groupName = "Hello Group"; +const groupType = CometChat.GROUP_TYPE.PUBLIC; +const group = new CometChat.Group(GUID, groupName, groupType); + +CometChat.updateGroup(group).then( +group => { + console.log("Groups details updated successfully:", group); +}, error => { + console.log("Group details update failed with exception:", error); +} +); +``` + + + -This method takes an instance of the `Group` class as a parameter which should contain the data that you wish to update. +| Parameter | Description | +| --------- | ----------- | +| `group` | An instance of `Group` class with updated values | -| Parameter | Description | -| --------- | ---------------------------- | -| `group` | an instance of class `Group` | +On success, returns a [`Group`](/sdk/reference/entities#group) object with the updated details. -After a successful update of the group, you will receive an instance of `Group` class containing update information of the group. +The method returns a [`Group`](/sdk/reference/entities#group) object. There is no real-time event listener available to receive updated group details when the `updateGroup()` method is called. To get the latest group information, you need to fetch the group details again using the appropriate method. For more information on the `Group` class, please check [here](/sdk/javascript/create-group#create-a-group). + +--- + +## Next Steps + + + + Permanently delete a group + + + Fetch and filter groups with pagination + + diff --git a/sdk/javascript/upgrading-from-v3.mdx b/sdk/javascript/upgrading-from-v3.mdx index 00cf6868a..51d7e1b01 100644 --- a/sdk/javascript/upgrading-from-v3.mdx +++ b/sdk/javascript/upgrading-from-v3.mdx @@ -1,9 +1,17 @@ --- title: "Upgrading From V3" +description: "Migrate your CometChat JavaScript SDK integration from v3 to v4 with updated dependencies and import statements." --- +{/* TL;DR for Agents and Quick Reference */} + - +Key changes from v3 to v4: +- Chat SDK: `npm i @cometchat/chat-sdk-javascript` +- Calls SDK: `npm i @cometchat/calls-sdk-javascript` +- Import: `import { CometChat } from '@cometchat/chat-sdk-javascript'` +- Import Calls: `import { CometChatCalls } from '@cometchat/calls-sdk-javascript'` + ## Upgrading From v3 Upgrading from v3.x to v4 is fairly simple. Below are the major changes that are released as a part of CometChat v4: @@ -63,3 +71,16 @@ import {CometChatCalls} from '@cometchat/calls-sdk-javascript'; + +--- + +## Next Steps + + + + Install and configure the CometChat JavaScript SDK + + + Learn the core concepts behind CometChat v4 + + diff --git a/sdk/javascript/user-management.mdx b/sdk/javascript/user-management.mdx index 76ac2b585..5433652a4 100644 --- a/sdk/javascript/user-management.mdx +++ b/sdk/javascript/user-management.mdx @@ -1,183 +1,194 @@ --- title: "User Management" +sidebarTitle: "User Management" +description: "Create, update, and manage CometChat users programmatically using the JavaScript SDK. Includes user creation, profile updates, and the User class reference." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Create a user +const user = new CometChat.User("user1"); +user.setName("Kevin"); +await CometChat.createUser(user, "AUTH_KEY"); -When a user logs into your app, you need to programmatically login the user into CometChat. But before you log in the user to CometChat, you need to create the user. +// Update a user +user.setName("Kevin Fernandez"); +await CometChat.updateUser(user, "AUTH_KEY"); -Summing up- +// Update logged-in user (no auth key needed) +await CometChat.updateCurrentUserDetails(user); +``` -**When a user registers in your app** +**Note:** User creation/deletion should ideally happen on your backend via the [REST API](https://api-explorer.cometchat.com). + -1. You add the user details in your database -2. You create a user in CometChat +Users must exist in CometChat before they can log in. Typically: -**When a user logs into your app** +1. User registers in your app → Create user in CometChat +2. User logs into your app → [Log user into CometChat](/sdk/javascript/authentication-overview) -1. You log in the user to your app -2. You [log in the user in CometChat](/sdk/javascript/authentication-overview) (programmatically) +## Creating a User -## Creating a user +User creation should ideally happen on your backend via the [REST API](https://api-explorer.cometchat.com/reference/creates-user). -Ideally, user creation should take place at your backend. You can refer our Rest API to learn more about [creating a user](https://api-explorer.cometchat.com/reference/creates-user) and use the appropriate code sample based on your backend language. + +**Security:** Never expose your `Auth Key` in client-side production code. User creation and updates using `Auth Key` should ideally happen on your backend server. Use client-side creation only for prototyping or development. + -However, if you wish to create users on the fly, you can use the `createUser()` method. This method takes a `User` object and the `Auth Key` as input parameters and returns the created `User` object if the request is successful. +For client-side creation (development only), use `createUser()`: - -```js -let authKey = "AUTH_KEY"; -var uid = "user1"; -var name = "Kevin"; - -var user = new CometChat.User(uid); - -user.setName(name); - -CometChat.createUser(user, authKey).then( - user => { - console.log("user created", user); - }, error => { - console.log("error", error); - } -) -``` - - - ```typescript let authKey: string = "AUTH_KEY"; -var uid: string = "user1"; -var name: string = "Kevin"; +let uid: string = "user1"; +let name: string = "Kevin"; -var user: CometChat.User = new CometChat.User(uid); +let user: CometChat.User = new CometChat.User(uid); user.setName(name); CometChat.createUser(user, authKey).then( (user: CometChat.User) => { - console.log("user created", user); + console.log("user created", user); }, (error: CometChat.CometChatException) => { - console.log("error", error); + console.log("error", error); } ); ``` - - - - - - -UID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed. - - - -## Updating a user - -Updating a user similar to creating a user should ideally be achieved at your backend using the Restful APIs. For more information, you can check the [update a user](https://api-explorer.cometchat.com/reference/update-user) section. However, this can be achieved on the fly as well as using the `updateUser()` method. This method takes a `User` object and the `Auth Key` as inputs and returns the updated `User` object on the successful execution of the request. - - -```js +```javascript let authKey = "AUTH_KEY"; let uid = "user1"; -let name = "Kevin Fernandez"; +let name = "Kevin"; -var user = new CometChat.User(uid); +let user = new CometChat.User(uid); user.setName(name); -CometChat.updateUser(user, authKey).then( +CometChat.createUser(user, authKey).then( user => { - console.log("user updated", user); + console.log("user created", user); }, error => { - console.log("error", error); + console.log("error", error); } -) +) ``` - + + +The method returns a [`User`](/sdk/reference/entities#user) object. + + + +UID can be alphanumeric with underscore and hyphen. Spaces, punctuation and other special characters are not allowed. + + +## Updating a User + +Like creation, user updates should ideally happen on your backend via the [REST API](https://api-explorer.cometchat.com/reference/update-user). + +For client-side updates (development only), use `updateUser()`: + + ```typescript let authKey: string = "AUTH_KEY"; -var uid: string = "user1"; -var name: string = "Kevin Fernandez"; +let uid: string = "user1"; +let name: string = "Kevin Fernandez"; -var user: CometChat.User = new CometChat.User(uid); +let user: CometChat.User = new CometChat.User(uid); user.setName(name); CometChat.updateUser(user, authKey).then( (user: CometChat.User) => { - console.log("user updated", user); + console.log("user updated", user); }, (error: CometChat.CometChatException) => { - console.log("error", error); + console.log("error", error); } -) +) ``` - - - - -Please make sure the `User` object provided to the `updateUser()` method has the `UID` of the user to be updated set. - -## Updating logged-in user - -Updating a logged-in user is similar to updating a user. The only difference being this method does not require an AuthKey. This method takes a `User` object as input and returns the updated `User` object on the successful execution of the request. - - -```js +```javascript +let authKey = "AUTH_KEY"; let uid = "user1"; let name = "Kevin Fernandez"; -var user = new CometChat.User(uid); +let user = new CometChat.User(uid); user.setName(name); -CometChat.updateCurrentUserDetails(user).then( +CometChat.updateUser(user, authKey).then( user => { - console.log("user updated", user); + console.log("user updated", user); }, error => { - console.log("error", error); + console.log("error", error); } ) ``` - + + +Ensure the [`User`](/sdk/reference/entities#user) object has the correct `UID` set. +The method returns a [`User`](/sdk/reference/entities#user) object. + +## Updating Logged-in User + +Use `updateCurrentUserDetails()` to update the current user without an Auth Key. Note: You cannot update the user's role with this method. + + ```typescript -var uid: string = "user1"; -var name: string = "Kevin Fernandez"; +let uid: string = "user1"; +let name: string = "Kevin Fernandez"; -var user: CometChat.User = new CometChat.User(uid); +let user: CometChat.User = new CometChat.User(uid); user.setName(name); CometChat.updateCurrentUserDetails(user).then( (user: CometChat.User) => { - console.log("user updated", user); + console.log("user updated", user); }, (error: CometChat.CometChatException) => { - console.log("error", error); + console.log("error", error); } ); ``` - + +```javascript +let uid = "user1"; +let name = "Kevin Fernandez"; + +let user = new CometChat.User(uid); + +user.setName(name); +CometChat.updateCurrentUserDetails(user).then( + user => { + console.log("user updated", user); + }, error => { + console.log("error", error); + } +) +``` + -By using the `updateCurrentUserDetails()` method one can only update the logged-in user irrespective of the UID passed. Also, it is not possible to update the role of a logged-in user. +## Deleting a User + +The method returns a [`User`](/sdk/reference/entities#user) object. ## Deleting a user -Deleting a user can only be achieved via the Restful APIs. For more information please check the [delete a user](https://api-explorer.cometchat.com/reference/delete-user) section. +User deletion is only available via the [REST API](https://api-explorer.cometchat.com/reference/delete-user). ## User Class @@ -195,3 +206,20 @@ Deleting a user can only be achieved via the Restful APIs. For more information | hasBlockedMe | No | A boolean that determines if the user has blocked the logged in user | | blockedByMe | No | A boolean that determines if the logged in user has blocked the user | | tags | Yes | A list of tags to identify specific users | + +## Next Steps + + + + Fetch and filter user lists with pagination. + + + Monitor real-time online/offline status. + + + Block and unblock users. + + + Log users into CometChat. + + diff --git a/sdk/javascript/user-presence.mdx b/sdk/javascript/user-presence.mdx index 503bc0d6f..6ccc2c11f 100644 --- a/sdk/javascript/user-presence.mdx +++ b/sdk/javascript/user-presence.mdx @@ -1,50 +1,50 @@ --- title: "User Presence" -sidebarTitle: "Overview" +sidebarTitle: "User Presence" +description: "Track real-time user online/offline status and configure presence subscriptions using the CometChat JavaScript SDK." --- +{/* TL;DR for Agents and Quick Reference */} + +```javascript +// Subscribe to presence during init +const appSettings = new CometChat.AppSettingsBuilder() + .subscribePresenceForAllUsers() // or .subscribePresenceForRoles([]) / .subscribePresenceForFriends() + .setRegion("REGION").build(); -User Presence helps us understand if a user is available to chat or not. +// Listen for presence changes +CometChat.addUserListener("LISTENER_ID", new CometChat.UserListener({ + onUserOnline: (user) => console.log("Online:", user), + onUserOffline: (user) => console.log("Offline:", user) +})); -## Real-time Presence +// Remove listener +CometChat.removeUserListener("LISTENER_ID"); +``` + -*In other words, as a logged-in user, how do I know if a user is online or offline?* +Track whether users are online or offline in real-time. -Based on the settings provided in the AppSettings class while initialising the SDK using the `init()` method, the logged-in user will receive the presence for the other users in the app. +## Real-time Presence -In the `AppSettings` class, you can set the type of Presence you wish to receive for that particular session of the app. +Configure presence subscription in `AppSettings` during SDK initialization. The `AppSettingsBuilder` provides three subscription options: -For presence subscription, the AppSettingsBuilder provides 3 methods : +| Method | Description | +| ------ | ----------- | +| `subscribePresenceForAllUsers()` | Receive presence updates for all users | +| `subscribePresenceForRoles(roles)` | Receive presence updates only for users with specified roles | +| `subscribePresenceForFriends()` | Receive presence updates only for friends | -* `subscribePresenceForAllUsers()` - this will inform the logged-in user when any user in the app comes online or goes offline -* `subscribePresenceForRoles(Array roles)` - This will inform the logged-in user, only when the users with the specified roles come online or go offline. -* `subscribePresenceForFriends()` - This will inform the logged-in user, only when either of his friends come online or go offline. +If none of these methods are called, no presence events will be delivered. -If none of the above methods are used, no presence will be sent to the logged-in user. + +You must configure presence subscription in `AppSettings` during `CometChat.init()` before any presence events will be delivered. See [Setup SDK](/sdk/javascript/setup-sdk) for details. + -You need to register the `UserListener` using the `addUserListener()` method where ever you wish to receive these events in. +Register a `UserListener` to receive presence events: - -``` -let listenerID = "UNIQUE_LISTENER_ID"; - -CometChat.addUserListener( -listenerID, -new CometChat.UserListener({ - onUserOnline: onlineUser => { - console.log("On User Online:", { onlineUser }); - }, - onUserOffline: offlineUser => { - console.log("On User Offline:", { offlineUser }); - } -}) -); -``` - - - ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; @@ -52,58 +52,96 @@ let listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.addUserListener( listenerID, new CometChat.UserListener({ - onUserOnline: (onlineUser: CometChat.User) => { - console.log("On User Online:", { onlineUser }); - }, - onUserOffline: (offlineUser: CometChat.User) => { - console.log("On User Offline:", { offlineUser }); - } + onUserOnline: (onlineUser: CometChat.User) => { + console.log("On User Online:", { onlineUser }); + }, + onUserOffline: (offlineUser: CometChat.User) => { + console.log("On User Offline:", { offlineUser }); + } }) ); ``` - + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; +CometChat.addUserListener( + listenerID, + new CometChat.UserListener({ + onUserOnline: onlineUser => { + console.log("On User Online:", { onlineUser }); + }, + onUserOffline: offlineUser => { + console.log("On User Offline:", { offlineUser }); + } + }) +); +``` + -| Parameter | Description | -| ------------ | --------------------------------------------- | -| `listenerID` | An ID that uniquely identifies that listener. | +| Parameter | Description | +| --------- | ----------- | +| `listenerID` | Unique identifier for the listener | -You will receive an object of the `User` class in the listener methods. +Each callback receives a [`User`](/sdk/reference/entities#user) object with presence information. -We recommend you remove the listener once the activity or view is not in use. -We suggest adding this method when not in use. +Relevant fields to access on returned users: - - -``` -let listenerID = "UNIQUE_LISTENER_ID"; -CometChat.removeUserListener(listenerID); -``` +| Field | Getter | Return Type | Description | +|-------|--------|-------------|-------------| +| status | `getStatus()` | `string` | Online status of the user (`"online"` or `"offline"`) | +| lastActiveAt | `getLastActiveAt()` | `number` | Timestamp when the user was last active | - +Remove the listener when no longer needed: + ```typescript let listenerID: string = "UNIQUE_LISTENER_ID"; CometChat.removeUserListener(listenerID); ``` - - + +```javascript +let listenerID = "UNIQUE_LISTENER_ID"; +CometChat.removeUserListener(listenerID); +``` + -## User List Presence + +Always remove your `UserListener` when the component or view unmounts to prevent memory leaks and duplicate event handling. -*In other words, as a logged-in user, when I retrieve the user list, how do I know if a user is online/offline?* - -When you fetch the list of users, in the [User](/sdk/javascript/user-management#user-class) object, you will receive 2 fields - -1. `status` - This will hold either of the two values : +```javascript +CometChat.removeUserListener("LISTENER_ID"); +``` + -* online - This indicates that the user is currently online and available to chat. -* offline - This indicates that the user is currently offline and is not available to chat. +## User List Presence -2. `lastActiveAt` - in case the user is offline, this field holds the timestamp of the time when the user was last online. This can be used to display the Last seen of the user if need be. +When fetching users via `UsersRequest`, each [`User`](/sdk/reference/entities#user) object includes presence fields: + +| Field | Description | +| ----- | ----------- | +| `status` | `"online"` or `"offline"` | +| `lastActiveAt` | Timestamp of last activity (useful for "Last seen" display) | + +## Next Steps + + + + Fetch user lists with filtering and pagination. + + + Create and update users programmatically. + + + Monitor SDK connection to CometChat servers. + + + Overview of all available real-time listeners. + + diff --git a/sdk/javascript/users-overview.mdx b/sdk/javascript/users-overview.mdx index 2193624f4..a63e5b9f2 100644 --- a/sdk/javascript/users-overview.mdx +++ b/sdk/javascript/users-overview.mdx @@ -1,10 +1,37 @@ --- title: "Users" sidebarTitle: "Overview" +description: "Overview of CometChat user functionality including user management, retrieval, and presence tracking in the JavaScript SDK." --- + +- [User Management](/sdk/javascript/user-management) — Create and update users +- [Retrieve Users](/sdk/javascript/retrieve-users) — Fetch and filter user lists +- [User Presence](/sdk/javascript/user-presence) — Track online/offline status +- [Block Users](/sdk/javascript/block-users) — Block and unblock users + -The primary aim for our Users functionality is to allow you to quickly retrieve and add users to CometChat. +Every person who uses your app needs a corresponding user in CometChat. Once a user exists, you can manage their profile, fetch user lists for your UI, track who's online, and control communication with blocking. -You can begin with [user management](/sdk/javascript/user-management) to sync your users to CometChat. Once that is done, you can [retrieve users](/sdk/javascript/retrieve-users) and display them in your app. +- [User Management](/sdk/javascript/user-management) — Create users when they sign up, update profiles, and delete accounts +- [Retrieve Users](/sdk/javascript/retrieve-users) — Fetch and filter user lists with pagination, search, and role-based filtering +- [User Presence](/sdk/javascript/user-presence) — Monitor real-time online/offline status and subscribe to presence changes +- [Block Users](/sdk/javascript/block-users) — Block and unblock users to prevent all communication + +## Next Steps + + + + Create, update, and delete users in CometChat. + + + Fetch user lists with filtering, sorting, and pagination. + + + Monitor real-time online/offline status of users. + + + Block and unblock users to control communication. + + diff --git a/sdk/javascript/video-view-customisation.mdx b/sdk/javascript/video-view-customisation.mdx index 5e3880224..7d5c7179d 100644 --- a/sdk/javascript/video-view-customisation.mdx +++ b/sdk/javascript/video-view-customisation.mdx @@ -1,82 +1,77 @@ --- title: "Video View Customisation" +sidebarTitle: "Video View Customisation" description: "Customize the main video container in CometChat calls — aspect ratio, full screen button, name label, and network label positioning." --- - -**Quick Reference** + + - **Class:** `CometChat.MainVideoContainerSetting` - **Apply via:** `CallSettingsBuilder.setMainVideoContainerSetting(videoSettings)` - **Customizable elements:** Aspect ratio, full screen button, name label, network label - **Position constants:** `POSITION_TOP_LEFT`, `POSITION_TOP_RIGHT`, `POSITION_BOTTOM_LEFT`, `POSITION_BOTTOM_RIGHT` - **Requires:** [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call) setup - + -This section will guide you to customise the main video container. +Customize the main video container in your call UI — aspect ratio, button positions, and label visibility. Create a `MainVideoContainerSetting` instance, configure it, and pass it to `CallSettingsBuilder.setMainVideoContainerSetting()`. -## Implementation +Before you begin, make sure you've set up [Ringing](/sdk/javascript/default-call) or [Call Session](/sdk/javascript/direct-call). -Once you have decided to implement [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call) calling and followed the steps to implement them. Just few additional methods will help you quickly customize the main video container. +## MainVideoContainerSetting -Please make sure your callSettings is configured accordingly for [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call). +| Method | Description | Default | +| ------ | ----------- | ------- | +| `setMainVideoAspectRatio(aspectRatio)` | Aspect ratio of the main video. Values: `ASPECT_RATIO_CONTAIN`, `ASPECT_RATIO_COVER` | `ASPECT_RATIO_CONTAIN` | +| `setFullScreenButtonParams(position, visibility)` | Position and visibility of the full screen button. | Bottom-right, visible | +| `setNameLabelParams(position, visibility, backgroundColor)` | Position, visibility, and background color of the participant name label. | Bottom-left, visible, `rgba(27, 27, 27, 0.4)` | +| `setNetworkLabelParams(position, visibility)` | Position and visibility of the network quality label. | Bottom-right, visible | -## Main Video Container Setting +### Position Constants -The `MainVideoContainerSetting` Class is the required in case you want to customise the main video view. You need to pass the Object of the `MainVideoContainerSetting` Class in the `setMainVideoContainerSetting()` method of the `CallSettingsBuilder`. +All position parameters accept one of these values from `CometChat.CallSettings`: -| Setting | Description | -| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `setMainVideoAspectRatio(aspectRatio: string)` | This method is used to set the aspect ratio of main video. The default value is **contain.**

Possible Values:
**1. CometChat.CallSettings. ASPECT\_RATIO\_CONTAIN\*\*\*\***
**2. CometChat.CallSettings. ASPECT\_RATIO\_COVER** | -| `setFullScreenButtonParams(position: string, visibility: boolean)` | This method is used to set the position & visibility parameter of the full screen button. By default the full screen button is visible in the **bottom-right** position.

Possible Values for **POSITION:**
1. **CometChat.CallSettings. POSITION\_TOP\_LEFT**
2. **CometChat.CallSettings. POSITION\_TOP\_RIGHT**
3. **CometChat.CallSettings. POSITION\_BOTTOM\_LEFT**
4. **CometChat.CallSettings. POSITION\_BOTTOM\_RIGHT**

Possible Values for **VISIBILITY:**
1. **true**
2. **false** | -| `setNameLabelParams(position: string, visibility: boolean, backgroundColor: string)` | This method is used to set the position, visibility & background color of the name label. By default the name label is visible in the **bottom-left** position with a background-color \*\*rgba(27, 27, 27, 0.4)\*\*

Possible Values for **POSITION:**
1. **CometChat.CallSettings. POSITION\_TOP\_LEFT**
2. **CometChat.CallSettings. POSITION\_TOP\_RIGHT**
3. **CometChat.CallSettings. POSITION\_BOTTOM\_LEFT**
4. **CometChat.CallSettings. POSITION\_BOTTOM\_RIGHT**

Possible Values for **VISIBILITY:**
1. **true**
2. **false** | -| `setNetworkLabelParams(position: string, visibility: boolean)` | This method is used to set the position, visibility of the network label. By default the network label is visible in the **bottom-right** position.

Possible Values for **POSITION:**
1. **CometChat.CallSettings. POSITION\_TOP\_LEFT**
2. **CometChat.CallSettings. POSITION\_TOP\_RIGHT**
3. **CometChat.CallSettings. POSITION\_BOTTOM\_LEFT**
4. **CometChat.CallSettings. POSITION\_BOTTOM\_RIGHT**

Possible Values for **VISIBILITY:**
1. **true**
2. **false** | +- `POSITION_TOP_LEFT` +- `POSITION_TOP_RIGHT` +- `POSITION_BOTTOM_LEFT` +- `POSITION_BOTTOM_RIGHT` -Example: +### Example - -```javascript -let videoSettings = new CometChat.MainVideoContainerSetting(); + +```typescript +let videoSettings: CometChat.MainVideoContainerSetting = new CometChat.MainVideoContainerSetting(); videoSettings.setMainVideoAspectRatio(CometChat.CallSettings.ASPECT_RATIO_CONTAIN); videoSettings.setFullScreenButtonParams(CometChat.CallSettings.POSITION_BOTTOM_RIGHT, true); videoSettings.setNameLabelParams(CometChat.CallSettings.POSITION_BOTTOM_LEFT, true, "rgba(27, 27, 27, 0.4)"); videoSettings.setNetworkLabelParams(CometChat.CallSettings.POSITION_BOTTOM_RIGHT, true); + +// Pass to CallSettingsBuilder +const callSettings = new CometChatCalls.CallSettingsBuilder() + .setMainVideoContainerSetting(videoSettings) + // ... other settings + .build(); ``` - -```typescript -let videoSettings: CometChat.MainVideoContainerSetting = new CometChat.MainVideoContainerSetting(); + +```javascript +let videoSettings = new CometChat.MainVideoContainerSetting(); videoSettings.setMainVideoAspectRatio(CometChat.CallSettings.ASPECT_RATIO_CONTAIN); videoSettings.setFullScreenButtonParams(CometChat.CallSettings.POSITION_BOTTOM_RIGHT, true); videoSettings.setNameLabelParams(CometChat.CallSettings.POSITION_BOTTOM_LEFT, true, "rgba(27, 27, 27, 0.4)"); videoSettings.setNetworkLabelParams(CometChat.CallSettings.POSITION_BOTTOM_RIGHT, true); + +// Pass to CallSettingsBuilder +const callSettings = new CometChatCalls.CallSettingsBuilder() + .setMainVideoContainerSetting(videoSettings) + // ... other settings + .build(); ``` - - - -| Practice | Details | -| --- | --- | -| Aspect ratio choice | Use `ASPECT_RATIO_CONTAIN` to show the full video without cropping; use `ASPECT_RATIO_COVER` for a full-bleed look that may crop edges | -| Label positioning | Avoid placing the name label and network label in the same corner to prevent overlap | -| Full screen button | Keep the full screen button visible for better UX; only hide it if your app provides its own full screen toggle | - - - - -| Symptom | Cause | Fix | -| --- | --- | --- | -| Video settings not applied | `setMainVideoContainerSetting()` not called on `CallSettingsBuilder` | Pass the `MainVideoContainerSetting` object to `CallSettingsBuilder.setMainVideoContainerSetting()` before calling `startCall()` | -| Labels overlapping | Multiple labels positioned in the same corner | Assign different position constants to each label | -| Full screen button missing | Visibility set to `false` | Set the second parameter of `setFullScreenButtonParams()` to `true` | - - - - ## Next Steps diff --git a/sdk/javascript/virtual-background.mdx b/sdk/javascript/virtual-background.mdx index 0879041c1..808ebb534 100644 --- a/sdk/javascript/virtual-background.mdx +++ b/sdk/javascript/virtual-background.mdx @@ -1,59 +1,54 @@ --- title: "Virtual Background" +sidebarTitle: "Virtual Background" description: "Implement virtual background features in CometChat video calls — background blur, custom images, and enforced backgrounds using the JavaScript SDK." --- - -**Quick Reference** + + - **Settings class:** `CometChat.VirtualBackground` - **Apply via:** `CallSettingsBuilder.setVirtualBackground(virtualBackground)` - **Toggle UI:** `CallSettingsBuilder.showVirtualBackgroundSetting(true|false)` - **Runtime control:** `CometChat.CallController.getInstance()` → `setBackgroundBlur()`, `setBackgroundImage()`, `openVirtualBackground()` - **Requires:** [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call) setup - - -This section will guide you to implement virtual background feature in video calls. - -## Implementation - -Once you have decided to implement [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call) calling and followed the steps to implement them. Just few additional methods will help you quickly implement virtual background. + -Please make sure your callSettings is configured accordingly for [Default Calling](/sdk/javascript/default-call) or [Direct Calling](/sdk/javascript/direct-call). +Virtual backgrounds let users blur their background or replace it with a custom image during video calls. You can configure defaults at build time via `CallSettingsBuilder`, and control them programmatically at runtime via `CallController`. -## Settings +Before you begin, make sure you've set up [Ringing](/sdk/javascript/default-call) or [Call Session](/sdk/javascript/direct-call). -The `CallSettings`class allows you to customise the overall calling experience. The properties for the call/conference can be set using the `CallSettingsBuilder` class. This will eventually give you and object of the `CallSettings` class which you can pass to the `startCall()` method to start the call. +## CallSettings Options -The **mandatory** parameters that are required to be present for any call/conference to work are: +Configure virtual background behavior when building your call settings: -1. sessionId - The unique session Id for the call/conference session. +| Setting | Description | +| ------- | ----------- | +| `showVirtualBackgroundSetting(showVBSettings: boolean)` | This method shows/hides the virtual background settings in the menu bar. **Default value = true** | +| `setVirtualBackground(virtualBackground: CometChat.VirtualBackground)` | This method will set the virtual background setting. This methods takes an Object of Virtual Background Class. | -The options available for virtual background are: +See [VirtualBackground Class](#virtualbackground-class) below for the full configuration options you can pass to `setVirtualBackground()`. -| Setting | Description | -| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -| `showVirtualBackgroundSetting(showVBSettings: boolean)` | This method shows/hides the virtual background settings in the menu bar. **Default value = true** | -| `setVirtualBackground(virtualBackground: CometChat.VirtualBackground)` | This method will set the virtual background setting. This methods takes an Object of Virtual Background Class. | +## Runtime Control -For the use case where you wish to align your own custom buttons and not use the default layout provided by CometChat, you can embed the buttons in your layout and use the below methods to perform the corresponding operations: +For custom UI without the default layout, use `CallController` to control virtual background during an active call. ### Open Virtual Background Setting You can use the `openVirtualBackground()` method to open the virtual background settings pop-up. - -```javascript -let callController = CometChat.CallController.getInstance(); -callController.openVirtualBackground(); -``` - ```typescript let callController: CometChat.CallController = CometChat.CallController.getInstance(); callController.openVirtualBackground(); ``` + +```javascript +let callController = CometChat.CallController.getInstance(); +callController.openVirtualBackground(); +``` + ### Set Background Blur @@ -61,13 +56,6 @@ callController.openVirtualBackground(); You can use the `setBackgroundBlur()` method to apply background blur on the video stream. This method accepts a number which decides the level of blur to be applied. - -```javascript -let callController = CometChat.CallController.getInstance(); -let blurLevel = 1; -callController.setBackgroundBlur(blurLevel); -``` - ```typescript let callController: CometChat.CallController = CometChat.CallController.getInstance(); @@ -75,6 +63,13 @@ let blurLevel: number = 1; callController.setBackgroundBlur(blurLevel); ``` + +```javascript +let callController = CometChat.CallController.getInstance(); +let blurLevel = 1; +callController.setBackgroundBlur(blurLevel); +``` + ### Set Background Image @@ -82,13 +77,6 @@ callController.setBackgroundBlur(blurLevel); You can use the `setBackgroundImage()`method to set the background image. This method takes either a URL or file Object & sets that image as the background. - -```javascript -let callController = CometChat.CallController.getInstance(); -let imageURL = "URL_OF_BACKGROUND_IMAGE"; -callController.setBackgroundImage(imageURL); -``` - ```typescript let callController: CometChat.CallController = CometChat.CallController.getInstance(); @@ -96,11 +84,18 @@ let imageURL: string = "URL_OF_BACKGROUND_IMAGE"; callController.setBackgroundImage(imageURL); ``` + +```javascript +let callController = CometChat.CallController.getInstance(); +let imageURL = "URL_OF_BACKGROUND_IMAGE"; +callController.setBackgroundImage(imageURL); +``` + -## Virtual Background Settings +## VirtualBackground Class -The `VirtualBackground` Class is the required in case you want to change how the end user can use virtual background features in a video call. You need to pass the Object of the `VirtualBackground` Class in the `setVirtualBackground()` method of the `CallSettingsBuilder`. +The `VirtualBackground` class controls how users interact with virtual background features. Pass a `VirtualBackground` instance to `setVirtualBackground()` in `CallSettingsBuilder`. | Setting | Description | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | @@ -111,30 +106,6 @@ The `VirtualBackground` Class is the required in case you want to change how the | `enforceBackgroundBlur(enforceBackgroundBlur: number)` | This method starts the call with background blurred. To blur the background you need to pass an integer value between 1-99 which decides the blur level. **Default = 0** | | `enforceBackgroundImage(enforceBackgroundImage: string)` | This methods starts the call with the provided background image. | - - - -| Practice | Details | -| --- | --- | -| Blur level range | Use values between 1-99 for `enforceBackgroundBlur()`. Higher values produce stronger blur. A value of 0 disables blur | -| Image hosting | Host background images on a CDN for fast loading. Large images may cause lag when applied | -| Enforce vs allow | Use `enforceBackgroundBlur()` or `enforceBackgroundImage()` when you want a mandatory background (e.g., for privacy). Use `allowBackgroundBlur()` and `allowUserImages()` to let users choose | -| Custom buttons | Use `CallController` methods (`setBackgroundBlur`, `setBackgroundImage`, `openVirtualBackground`) when building a custom UI instead of the default CometChat menu | - - - - -| Symptom | Cause | Fix | -| --- | --- | --- | -| Virtual background option not visible | `showVirtualBackgroundSetting(false)` was set | Set `showVirtualBackgroundSetting(true)` in `CallSettingsBuilder` | -| Background blur not applied on call start | `enforceBackgroundBlur()` not set or set to 0 | Pass a value between 1-99 to `enforceBackgroundBlur()` | -| Custom images not appearing | `setImages()` not called or empty array passed | Pass a non-empty array of valid image URLs to `setImages()` | -| `CallController.getInstance()` returns null | Called before the call has started | Only use `CallController` methods after `startCall()` has been invoked | -| User can't upload their own images | `allowUserImages(false)` was set | Set `allowUserImages(true)` in the `VirtualBackground` configuration | - - - - ## Next Steps diff --git a/sdk/reference/auxiliary.mdx b/sdk/reference/auxiliary.mdx new file mode 100644 index 000000000..ea1107012 --- /dev/null +++ b/sdk/reference/auxiliary.mdx @@ -0,0 +1,135 @@ +--- +title: "Auxiliary" +description: "Class reference for auxiliary objects returned by CometChat SDK methods. Covers MessageReceipt, Reaction, ReactionCount, ReactionEvent, TypingIndicator, TransientMessage, Attachment, and CometChatException." +--- + +This page documents the auxiliary classes used across all CometChat SDKs. These objects are returned by listener callbacks and specific SDK methods. + +All properties are accessed via getter methods. + +--- + +## MessageReceipt + +`MessageReceipt` represents a delivery or read receipt for a message. It is received via the `onMessagesDelivered` and `onMessagesRead` listener callbacks. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| messageId | `getMessageId()` | `string` | ID of the message this receipt is for | +| sender | `getSender()` | `User` | The user who triggered the receipt | +| receiver | `getReceiver()` | `string` | UID or GUID of the receiver | +| receiverType | `getReceiverType()` | `string` | Receiver type (`"user"` or `"group"`) | +| receiptType | `getReceiptType()` | `string` | Type of receipt (`"read"`, `"delivery"`, `"readByAll"`, or `"deliveredToAll"`) | +| timestamp | `getTimestamp()` | `string` | Timestamp of the receipt | +| readAt | `getReadAt()` | `number` | Timestamp when the message was read (epoch seconds) | +| deliveredAt | `getDeliveredAt()` | `number` | Timestamp when the message was delivered (epoch seconds) | + +--- + +## Reaction + +`Reaction` represents an individual user's reaction on a message. It is returned by `fetchNext()` and `fetchPrevious()` on a `ReactionsRequest` object, and is also available within a `ReactionEvent`. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| id | `getReactionId()` | `string` | Unique identifier for this reaction | +| messageId | `getMessageId()` | `string` | ID of the message this reaction belongs to | +| reaction | `getReaction()` | `string` | The reaction emoji (e.g., `"😀"`, `"👍"`) | +| uid | `getUid()` | `string` | UID of the user who reacted | +| reactedAt | `getReactedAt()` | `number` | Timestamp when the reaction was added (epoch seconds) | +| reactedBy | `getReactedBy()` | `User` | The user who added this reaction | + +--- + +## ReactionCount + +`ReactionCount` represents the count of a specific reaction on a message. It is available via `getReactions()` on a `BaseMessage` object. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| reaction | `getReaction()` | `string` | The reaction emoji (e.g., `"😀"`, `"👍"`) | +| count | `getCount()` | `number` | Number of users who reacted with this reaction | +| reactedByMe | `getReactedByMe()` | `boolean` | Whether the logged-in user reacted with this reaction | + +--- + +## ReactionEvent + +`ReactionEvent` represents a real-time reaction event. It is received via the `onMessageReactionAdded` and `onMessageReactionRemoved` listener callbacks. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| reaction | `getReaction()` | `Reaction` | The reaction details object | +| receiverId | `getReceiverId()` | `string` | UID or GUID of the receiver | +| receiverType | `getReceiverType()` | `string` | Receiver type (`"user"` or `"group"`) | +| conversationId | `getConversationId()` | `string` | ID of the conversation | +| parentMessageId | `getParentMessageId()` | `string` | ID of the parent message (if the reacted message is in a thread) | + +--- + +## TypingIndicator + +`TypingIndicator` represents a typing event. It is received via the `onTypingStarted` and `onTypingEnded` listener callbacks. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| receiverId | `getReceiverId()` | `string` | UID or GUID of the receiver | +| receiverType | `getReceiverType()` | `string` | Receiver type (`"user"` or `"group"`) | +| sender | `getSender()` | `User` | The user who is typing | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the typing indicator | + +--- + +## TransientMessage + +`TransientMessage` represents a transient (non-persistent) message. It is received via the `onTransientMessageReceived` listener callback. Transient messages are not stored on the server. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| receiverId | `getReceiverId()` | `string` | UID or GUID of the receiver | +| receiverType | `getReceiverType()` | `string` | Receiver type (`"user"` or `"group"`) | +| sender | `getSender()` | `User` | The user who sent the transient message | +| data | `getData()` | `any` | Custom data payload of the transient message | + +--- + +## Attachment + +`Attachment` represents a file attachment on a `MediaMessage`. It is available via `getAttachment()` or `getAttachments()` on a `MediaMessage` object. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| name | `getName()` | `string` | Name of the file | +| extension | `getExtension()` | `string` | File extension (e.g., `"png"`, `"pdf"`) | +| mimeType | `getMimeType()` | `string` | MIME type of the file (e.g., `"image/png"`) | +| size | `getSize()` | `number` | Size of the file in bytes | +| url | `getUrl()` | `string` | URL to download the file | + +--- + +## CometChatException + +`CometChatException` represents an error from the Chat SDK. It is received in rejection callbacks of promise-based SDK methods (e.g., `sendMessage`, `login`, `getGroup`). + +### Properties + +| Property | Type | Description | +|----------|------|-------------| +| `code` | `string` \| `number` | Error code identifying the type of error | +| `name` | `string` | Name/category of the error | +| `message` | `string` | Human-readable error description | +| `details` | `string` | Additional error details | diff --git a/sdk/reference/calls.mdx b/sdk/reference/calls.mdx new file mode 100644 index 000000000..04ea85a3f --- /dev/null +++ b/sdk/reference/calls.mdx @@ -0,0 +1,142 @@ +--- +title: "Calls" +description: "Class reference for objects returned by the CometChat Calls SDK. Covers CallLog, CallUser, CallGroup, Participant, Recording, OngoingCallListener, CometChatCallsException, and MediaDeviceInfo." +--- + +This page documents the classes used in the CometChat Calls SDK. These objects are returned by call log queries and call session methods. + +All properties on proper classes are accessed via getter methods. Listener event objects are plain objects accessed via dot notation. + +--- + +## CallLog + +`CallLog` represents a call history entry. It is returned by `CallLogRequestBuilder.fetchNext()` and `CallLogRequestBuilder.fetchPrevious()`. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| sessionId | `getSessionID()` | `string` | Unique session ID of the call | +| totalAudioMinutes | `getTotalAudioMinutes()` | `number` | Total audio minutes in the call | +| totalVideoMinutes | `getTotalVideoMinutes()` | `number` | Total video minutes in the call | +| totalDuration | `getTotalDuration()` | `string` | Total duration of the call as a formatted string | +| totalDurationInMinutes | `getTotalDurationInMinutes()` | `number` | Total duration in minutes | +| hasRecording | `getHasRecording()` | `boolean` | Whether the call has a recording | +| initiatedAt | `getInitiatedAt()` | `number` | Timestamp when the call was initiated | +| endedAt | `getEndedAt()` | `number` | Timestamp when the call ended | +| callCategory | `getCallCategory()` | `string` | Category of the call (`"call"` or `"meet"`) | +| type | `getType()` | `string` | Type of the call (`"audio"` or `"video"`) | +| status | `getStatus()` | `string` | Status of the call (`"ongoing"`, `"ended"`, `"cancelled"`, etc.) | +| receiverType | `getReceiverType()` | `string` | Receiver type (`"user"` or `"group"`) | +| totalParticipants | `getTotalParticipants()` | `number` | Total number of participants | +| mid | `getMid()` | `string` | Message ID associated with the call | +| initiator | `getInitiator()` | [`CallUser`](#calluser) | The user who initiated the call | +| receiver | `getReceiver()` | [`CallUser`](#calluser) \| [`CallGroup`](#callgroup) | The user or group that received the call | +| participants | `getParticipants()` | [`Participant[]`](#participant) | Array of call participants | +| recordings | `getRecordings()` | [`Recording[]`](#recording) | Array of call recordings | + +--- + +## CallUser + +`CallUser` represents a user within the Calls SDK context (used in `CallLog` as initiator/receiver). + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| uid | `getUid()` | `string` | Unique user ID | +| name | `getName()` | `string` | Display name of the user | +| avatar | `getAvatar()` | `string` | URL of the user's avatar | + +--- + +## CallGroup + +`CallGroup` represents a group within the Calls SDK context (used in `CallLog` as receiver for group calls). + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| guid | `getGuid()` | `string` | Unique group ID | +| name | `getName()` | `string` | Display name of the group | +| icon | `getIcon()` | `string` | URL of the group icon | + +--- + +## Participant + +`Participant` represents a user who participated in a call. It is available via `getParticipants()` on a [`CallLog`](#calllog) object. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| uid | `getUid()` | `string` | Unique user ID | +| name | `getName()` | `string` | Display name of the participant | +| avatar | `getAvatar()` | `string` | URL of the participant's avatar | +| totalAudioMinutes | `getTotalAudioMinutes()` | `number` | Audio minutes for this participant | +| totalVideoMinutes | `getTotalVideoMinutes()` | `number` | Video minutes for this participant | +| totalDurationInMinutes | `getTotalDurationInMinutes()` | `number` | Total duration in minutes for this participant | +| deviceID | `getDeviceID()` | `string` | Device ID of the participant | +| hasJoined | `getHasJoined()` | `boolean` | Whether the participant joined the call | +| joinedAt | `getJoinedAt()` | `number` | Timestamp when the participant joined | +| leftAt | `getLeftAt()` | `number` | Timestamp when the participant left | +| mid | `getMid()` | `string` | Media ID of the participant | +| state | `getState()` | `string` | State of the participant | + +--- + +## Recording + +`Recording` represents a call recording. It is available via `getRecordings()` on a [`CallLog`](#calllog) object. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| rid | `getRid()` | `string` | Unique recording ID | +| recordingUrl | `getRecordingURL()` | `string` | URL to download the recording | +| startTime | `getStartTime()` | `number` | Timestamp when the recording started | +| endTime | `getEndTime()` | `number` | Timestamp when the recording ended | +| duration | `getDuration()` | `number` | Duration of the recording in seconds | + +--- + +## OngoingCallListener + +For the full `OngoingCallListener` documentation including all callbacks and parameter shapes, see the [All Real-Time Listeners](/sdk/javascript/all-real-time-listeners#ongoing-call-listener-calls-sdk) page. + +--- + +## CometChatCallsException + +`CometChatCallsException` represents an error from the Calls SDK. It is received in the `onError` callback of `OngoingCallListener` and in rejection callbacks of Calls SDK promise-based methods. + +### Properties + +| Property | Type | Description | +|----------|------|-------------| +| `code` | `string` \| `number` | Error code identifying the type of error | +| `name` | `string` | Name/category of the error | +| `message` | `string` | Human-readable error description | +| `details` | `string` | Additional error details | + +--- + +## MediaDeviceInfo + +`MediaDeviceInfo` represents an audio or video device available on the user's system. It is returned by `getAudioInputDevices()`, `getAudioOutputDevices()`, and `getVideoInputDevices()` methods, and also received in the `onMediaDeviceListUpdated` callback. + +These objects follow the browser's [MediaDeviceInfo](https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo) interface shape. + +### Properties + +| Property | Type | Description | +|----------|------|-------------| +| `deviceId` | `string` | Unique device identifier | +| `kind` | `string` | Device type (`"videoinput"`, `"audioinput"`, or `"audiooutput"`) | +| `label` | `string` | Human-readable device name | +| `groupId` | `string` | Group identifier for related devices (e.g., a headset's mic and speaker share a group) | diff --git a/sdk/reference/entities.mdx b/sdk/reference/entities.mdx new file mode 100644 index 000000000..2d5588aa8 --- /dev/null +++ b/sdk/reference/entities.mdx @@ -0,0 +1,109 @@ +--- +title: "Entities" +sidebarTitle: "Entities" +description: "Class reference for entity objects returned by CometChat SDK methods. Covers User, Group, Conversation, and GroupMember." +--- + +This page documents the entity classes used across all CometChat SDKs. All entity objects share the same structure regardless of platform. + +All properties are accessed via getter methods. + +--- + +## User + +`User` represents a CometChat user. It is returned by methods like `CometChat.login()`, `CometChat.getUser()`, and user list requests. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| uid | `getUid()` | `string` | Unique user ID | +| name | `getName()` | `string` | Display name of the user | +| avatar | `getAvatar()` | `string` | URL of the user's avatar image | +| link | `getLink()` | `string` | URL link associated with the user | +| role | `getRole()` | `string` | Role assigned to the user | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the user | +| status | `getStatus()` | `string` | Online status of the user (`"online"` or `"offline"`) | +| statusMessage | `getStatusMessage()` | `string` | Custom status message set by the user | +| lastActiveAt | `getLastActiveAt()` | `number` | Timestamp when the user was last active (epoch seconds) | +| tags | `getTags()` | `string[]` | Tags associated with the user | +| deactivatedAt | `getDeactivatedAt()` | `number` | Timestamp when the user was deactivated (epoch seconds) | + +### Conditional Properties + +These properties may or may not be populated depending on the method or request configuration used. + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| hasBlockedMe | `getHasBlockedMe()` | `boolean` | Whether this user has blocked the logged-in user | +| blockedByMe | `getBlockedByMe()` | `boolean` | Whether the logged-in user has blocked this user | +| authToken | `getAuthToken()` | `string` | Auth token of the user (only available after login) | + +--- + +## Group + +`Group` represents a CometChat group. It is returned by methods like `CometChat.createGroup()`, `CometChat.getGroup()`, and group list requests. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| guid | `getGuid()` | `string` | Unique group ID | +| name | `getName()` | `string` | Display name of the group | +| type | `getType()` | `string` | Group type (`"public"`, `"private"`, or `"password"`) | +| icon | `getIcon()` | `string` | URL of the group icon | +| description | `getDescription()` | `string` | Description of the group | +| owner | `getOwner()` | `string` | UID of the group owner | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the group | +| createdAt | `getCreatedAt()` | `number` | Timestamp when the group was created (epoch seconds) | +| updatedAt | `getUpdatedAt()` | `number` | Timestamp when the group was last updated (epoch seconds) | +| hasJoined | `getHasJoined()` | `boolean` | Whether the logged-in user has joined this group | +| scope | `getScope()` | `string` | Scope of the logged-in user in the group (`"admin"`, `"moderator"`, or `"participant"`) | +| joinedAt | `getJoinedAt()` | `string` | Timestamp when the logged-in user joined the group | +| membersCount | `getMembersCount()` | `number` | Total number of members in the group | +| tags | `getTags()` | `string[]` | Tags associated with the group | + +### Conditional Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| password | `getPassword()` | `string` | Group password (only for password-protected groups, only available during creation) | +| isBanned | `isBannedFromGroup()` | `boolean` | Whether the logged-in user is banned from the group | + +--- + +## Conversation + +`Conversation` represents a chat conversation. It is returned by `CometChat.getConversation()` and conversation list requests. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| conversationId | `getConversationId()` | `string` | Unique conversation ID | +| conversationType | `getConversationType()` | `string` | Type of conversation (`"user"` or `"group"`) | +| lastMessage | `getLastMessage()` | `BaseMessage` | The last message in the conversation | +| conversationWith | `getConversationWith()` | `User` \| `Group` | The user or group this conversation is with | +| unreadMessageCount | `getUnreadMessageCount()` | `number` | Number of unread messages in the conversation | +| unreadMentionsCount | `getUnreadMentionsCount()` | `number` | Number of unread mentions in the conversation | +| lastReadMessageId | `getLastReadMessageId()` | `string` | ID of the last message read by the logged-in user | +| latestMessageId | `getLatestMessageId()` | `string` | ID of the latest message in the conversation | +| tags | `getTags()` | `string[]` | Tags associated with the conversation | + +--- + +## GroupMember + +`GroupMember` extends [User](#user) and represents a member of a CometChat group. It is returned by group member list requests. + +It inherits all properties from `User` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| scope | `getScope()` | `string` | Scope of the member in the group (`"admin"`, `"moderator"`, or `"participant"`) | +| joinedAt | `getJoinedAt()` | `number` | Timestamp when the member joined the group (epoch seconds) | +| guid | `getGuid()` | `string` | GUID of the group this member belongs to | diff --git a/sdk/reference/messages.mdx b/sdk/reference/messages.mdx new file mode 100644 index 000000000..d2331149e --- /dev/null +++ b/sdk/reference/messages.mdx @@ -0,0 +1,323 @@ +--- +title: "Messages" +sidebarTitle: "Messages" +description: "Class reference for message objects returned by CometChat SDK methods. Covers BaseMessage and its subclasses like TextMessage." +--- + +This page documents the message classes used across all CometChat SDKs. All message objects share the same structure regardless of platform. + +All properties are accessed via getter methods. + +## Class Hierarchy + +``` +BaseMessage +├── TextMessage +├── MediaMessage +├── CustomMessage +├── InteractiveMessage +└── Action +``` + +--- + +## BaseMessage + +`BaseMessage` is the base class for all message types. Every message object — whether it's a text message, media message, or custom message — extends this class. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| id | `getId()` | `number` | Unique message ID | +| conversationId | `getConversationId()` | `string` | ID of the conversation this message belongs to | +| parentMessageId | `getParentMessageId()` | `number` | ID of the parent message (for threaded messages) | +| muid | `getMuid()` | `string` | Client-generated unique message ID | +| sender | `getSender()` | `User` | Sender of the message | +| receiver | `getReceiver()` | `User` \| `Group` | Receiver of the message | +| receiverId | `getReceiverId()` | `string` | UID/GUID of the receiver | +| type | `getType()` | `string` | Message type (e.g., `"text"`, `"image"`, `"file"`, `"custom"`) | +| receiverType | `getReceiverType()` | `string` | Receiver type (`"user"` or `"group"`) | +| category | `getCategory()` | `MessageCategory` | Message category (e.g., `"message"`, `"action"`, `"call"`, `"custom"`) | +| sentAt | `getSentAt()` | `number` | Timestamp when the message was sent (epoch seconds) | +| deliveredAt | `getDeliveredAt()` | `number` | Timestamp when the message was delivered | +| readAt | `getReadAt()` | `number` | Timestamp when the message was read | +| deliveredToMeAt | `getDeliveredToMeAt()` | `number` | Timestamp when the message was delivered to the logged-in user | +| readByMeAt | `getReadByMeAt()` | `number` | Timestamp when the message was read by the logged-in user | +| editedAt | `getEditedAt()` | `number` | Timestamp when the message was edited | +| editedBy | `getEditedBy()` | `string` | UID of the user who edited the message | +| deletedAt | `getDeletedAt()` | `number` | Timestamp when the message was deleted | +| deletedBy | `getDeletedBy()` | `string` | UID of the user who deleted the message | +| replyCount | `getReplyCount()` | `number` | Number of replies to this message | +| unreadRepliesCount | `getUnreadRepliesCount()` | `number` | Number of unread replies | +| data | `getData()` | `Object` | Raw data payload of the message | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the message | +| rawMessage | `getRawMessage()` | `Object` | Raw JSON of the message as received from the server | + +### Conditional Properties + +These properties may or may not be populated depending on the method or request configuration used to fetch the message. + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| reactions | `getReactions()` | `ReactionCount[]` | Array of reaction counts on the message | +| mentionedUsers | `getMentionedUsers()` | `User[]` | Array of users mentioned in the message | +| hasMentionedMe | `hasMentionedMe()` | `boolean` | Whether the logged-in user was mentioned in the message | +| quotedMessageId | `getQuotedMessageId()` | `number` | ID of the quoted message (if this is a reply) | +| quotedMessage | `getQuotedMessage()` | `BaseMessage` | The quoted message object (if this is a reply) | + +--- + +## TextMessage + +`TextMessage` extends [BaseMessage](#basemessage) and represents a text-based chat message. + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| text | `getText()` | `string` | The text content of the message | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the message (includes extension data like data masking, link preview, etc.) | +| data | `getData()` | `Object` | Raw data payload including `text`, `resource`, `metadata`, `moderation`, and `entities` | +| moderationStatus | `getModerationStatus()` | `ModerationStatus` | Moderation status of the message. Returns `"unmoderated"` if not moderated. | + +### Conditional Properties + +These properties may or may not be populated depending on the method or request configuration used to fetch the message. + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the message | + +--- + +## MediaMessage + +`MediaMessage` extends [BaseMessage](#basemessage) and represents a message with media attachments such as images, videos, audio files, or documents. + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| caption | `getCaption()` | `string` | Caption text for the media message | +| attachment | `getAttachment()` | `Attachment` | The primary attachment of the media message | +| attachments | `getAttachments()` | `Attachment[]` | All attachments of the media message | +| url | `getURL()` | `string` | URL of the media file | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the message | +| data | `getData()` | `Object` | Raw data payload of the message | +| moderationStatus | `getModerationStatus()` | `ModerationStatus` | Moderation status of the message. Returns `"unmoderated"` if not moderated. | + +### Conditional Properties + +These properties may or may not be populated depending on the method or request configuration used to fetch the message. + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the message | + +--- + +## CustomMessage + +`CustomMessage` extends [BaseMessage](#basemessage) and represents a developer-defined message with a custom data payload. + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| customData | `getCustomData()` | `Object` | The custom data payload set by the developer | +| subType | `getSubType()` | `string` | Sub type of the custom message | +| conversationText | `getConversationText()` | `string` | Preview text displayed in the conversation list | +| updateConversation | `willUpdateConversation()` | `boolean` | Whether this message updates the conversation's last message | +| sendNotification | `willSendNotification()` | `boolean` | Whether a push notification is sent for this message | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the message | +| data | `getData()` | `Object` | Raw data payload of the message | + +### Conditional Properties + +These properties may or may not be populated depending on the method or request configuration used to fetch the message. + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the message | + +--- + +## InteractiveMessage + +`InteractiveMessage` extends [BaseMessage](#basemessage) and represents a message with interactive UI elements such as forms, cards, or buttons. + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| interactiveData | `getInteractiveData()` | `Object` | The interactive element data (form fields, buttons, etc.) | +| interactionGoal | `getInteractionGoal()` | `InteractionGoal` | The goal that defines when the interaction is considered complete | +| interactions | `getInteractions()` | `Interaction[]` | Array of interactions that have occurred on this message | +| allowSenderInteraction | `getIsSenderInteractionAllowed()` | `boolean` | Whether the sender is allowed to interact with the message | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the message | +| data | `getData()` | `Object` | Raw data payload of the message | + +### Conditional Properties + +These properties may or may not be populated depending on the method or request configuration used to fetch the message. + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| tags | `getTags()` | `string[]` | Tags associated with the message | + +--- + +## Action + +`Action` extends [BaseMessage](#basemessage) and represents a system-generated action message such as a member joining, leaving, or being banned from a group. + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| action | `getAction()` | `string` | The action being performed (e.g., `"joined"`, `"left"`, `"kicked"`, `"banned"`) | +| message | `getMessage()` | `string` | The default human-readable action message | +| actionBy | `getActionBy()` | `User` \| `Group` \| `BaseMessage` | The entity that performed the action | +| actionOn | `getActionOn()` | `User` \| `Group` \| `BaseMessage` | The entity on which the action was performed | +| actionFor | `getActionFor()` | `User` \| `Group` \| `BaseMessage` | The entity for whom the action was performed | +| oldScope | `getOldScope()` | `string` | Previous scope of the member (for scope change actions) | +| newScope | `getNewScope()` | `string` | New scope of the member (for scope change actions) | +| rawData | `getRawData()` | `Object` | Raw JSON data of the action message | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the action message | + +--- + +## Call + +`Call` extends [BaseMessage](#basemessage) and represents a voice or video call message. + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| sessionId | `getSessionId()` | `string` | Unique session ID of the call | +| callInitiator | `getCallInitiator()` | [`User`](/sdk/reference/entities#user) | The user who initiated the call | +| callReceiver | `getCallReceiver()` | [`User`](/sdk/reference/entities#user) \| [`Group`](/sdk/reference/entities#group) | The user or group receiving the call | +| action | `getAction()` | `string` | The call action (e.g., `"initiated"`, `"ongoing"`, `"ended"`, `"cancelled"`, `"rejected"`) | +| initiatedAt | `getInitiatedAt()` | `number` | Timestamp when the call was initiated | +| joinedAt | `getJoinedAt()` | `number` | Timestamp when the call was joined | +| rawData | `getRawData()` | `Object` | Raw JSON data of the call message | +| metadata | `getMetadata()` | `Object` | Custom metadata attached to the call message | + +--- + +## AIAssistantMessage + +`AIAssistantMessage` extends [BaseMessage](#basemessage) and represents the full assistant reply persisted after an AI Agent run completes. It is received via the `onAIAssistantMessageReceived` callback of the [MessageListener](/sdk/javascript/all-real-time-listeners#message-listener). + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| assistantMessageData | `getAssistantMessageData()` | `AIAssistantMessageData` | The assistant message data containing runId, threadId, and text | + +### AIAssistantMessageData + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| runId | `getRunId()` | `string` | The run ID of the agent execution | +| threadId | `getThreadId()` | `string` | The thread ID of the conversation | +| text | `getText()` | `string` | The full text of the assistant's reply | + +--- + +## AIToolResultMessage + +`AIToolResultMessage` extends [BaseMessage](#basemessage) and represents the output of a tool call made during an AI Agent run. It is received via the `onAIToolResultReceived` callback of the [MessageListener](/sdk/javascript/all-real-time-listeners#message-listener). + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| toolResultMessageData | `getToolResultMessageData()` | `AIToolResultMessageData` | The tool result data containing runId, threadId, text, and toolCallId | + +### AIToolResultMessageData + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| runId | `getRunId()` | `string` | The run ID of the agent execution | +| threadId | `getThreadId()` | `string` | The thread ID of the conversation | +| text | `getText()` | `string` | The text output of the tool | +| toolCallId | `getToolCallId()` | `string` | The ID of the tool call this result belongs to | + +--- + +## AIToolArgumentMessage + +`AIToolArgumentMessage` extends [BaseMessage](#basemessage) and represents the arguments passed to a tool during an AI Agent run. It is received via the `onAIToolArgumentsReceived` callback of the [MessageListener](/sdk/javascript/all-real-time-listeners#message-listener). + +It inherits all properties from `BaseMessage` and adds the following. + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| toolArgumentMessageData | `getToolArgumentMessageData()` | `AIToolArgumentMessageData` | The tool argument data containing runId, threadId, and toolCalls | + +### AIToolArgumentMessageData + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| runId | `getRunId()` | `string` | The run ID of the agent execution | +| threadId | `getThreadId()` | `string` | The thread ID of the conversation | +| toolCalls | `getToolCalls()` | `AIToolCall[]` | Array of tool calls with their arguments | + +### AIToolCall + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| id | `getId()` | `string` | Unique tool call ID | +| type | `getType()` | `string` | Type of the tool call | +| displayName | `getDisplayName()` | `string` | Display name of the tool | +| executionText | `getExecutionText()` | `string` | Execution text for the tool | +| function | `getFunction()` | `AIToolCallFunction` | The function details (name and arguments) | + +### AIToolCallFunction + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| name | `getName()` | `string` | Name of the function being called | +| arguments | `getArguments()` | `string` | JSON string of the arguments passed to the function | + +--- + +## AIAssistantBaseEvent + +`AIAssistantBaseEvent` is the base class for all real-time streaming events from an AI Agent run. It is received via the `onAIAssistantEventReceived` callback of the [AIAssistantListener](/sdk/javascript/all-real-time-listeners#ai-assistant-listener). + +The `type` field identifies the specific event (e.g., `"run_started"`, `"tool_call_started"`, `"text_message_content"`, `"run_finished"`). + +### Properties + +| Property | Getter | Return Type | Description | +|----------|--------|-------------|-------------| +| type | `getType()` | `string` | The event type identifier | +| conversationId | `getConversationId()` | `string` | The conversation ID associated with the event | +| messageId | `getMessageId()` | `string` | The message ID associated with the event | +| parentMessageId | `getParentMessageId()` | `string` | The parent message ID (if in a thread) | +| data | `getData()` | `object` | Additional event-specific data | +| data.timestamp | `getTimestamp()` | `number` | Timestamp of the event | +| data.runId | `getRunId()` | `string` | The run ID of the agent execution | +| data.threadId | `getThreadId()` | `string` | The thread ID of the conversation |