diff --git a/calls/flutter/migration-guide-v5.mdx b/calls/flutter/migration-guide-v5.mdx index 79a0a0424..7168487fb 100644 --- a/calls/flutter/migration-guide-v5.mdx +++ b/calls/flutter/migration-guide-v5.mdx @@ -13,9 +13,7 @@ Calls SDK v5 is a **drop-in replacement** for v4. All v4 APIs are preserved as d ```yaml dependencies: - cometchat_calls_sdk: - hosted: https://dart.cloudsmith.io/cometchat/cometchat/ - version: ^5.0.0 + cometchat_calls_sdk: ^5.0.3 ``` diff --git a/sdk/flutter/ai-agents.mdx b/sdk/flutter/ai-agents.mdx index 087b6bceb..c3e238165 100644 --- a/sdk/flutter/ai-agents.mdx +++ b/sdk/flutter/ai-agents.mdx @@ -12,7 +12,7 @@ AI Agents enable intelligent, automated interactions within your application. Th ## 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. +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`**. @@ -26,16 +26,21 @@ Events are received via the **`onAIAssistantEventReceived`** method of the **`AI - Tool Call Arguments - Tool Call End - Tool Call Result -3. One or more assistant reply streams: +3. Zero or more card generation cycles (repeats for each card produced): + - Card Start + - Card (full payload) + - Card End +4. One or more assistant reply streams: - Text Message Start - Text Message Content (multiple times; token/char streaming) - Text Message End -4. Run Finished +5. 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. +- `Card` events appear only when the agent produces a card. The UI can show a loading state on `Card Start`, render the card on `Card` (payload), and finalize on `Card End`. +- `Text Message` events are always emitted and carry the assistant's reply incrementally. @@ -63,6 +68,18 @@ class AIAssistantEventHandler with AIAssistantListener { debugPrint( "Received AI Event: ${aiAssistantBaseEvent.type} for Run ID: ${aiAssistantBaseEvent.id}", ); + + // Handle card streaming events + if (aiAssistantBaseEvent is AIAssistantCardStartedEvent) { + debugPrint("Card generation started: ${aiAssistantBaseEvent.cardId}"); + debugPrint("Execution text: ${aiAssistantBaseEvent.executionText}"); + } else if (aiAssistantBaseEvent is AIAssistantCardReceivedEvent) { + debugPrint("Card received: ${aiAssistantBaseEvent.cardId}"); + final cardPayload = aiAssistantBaseEvent.getCard(); + // Pass cardPayload to CometChatCardView renderer + } else if (aiAssistantBaseEvent is AIAssistantCardEndedEvent) { + debugPrint("Card generation ended: ${aiAssistantBaseEvent.cardId}"); + } } } ``` @@ -70,16 +87,27 @@ class AIAssistantEventHandler with AIAssistantListener { #### Event descriptions -- Run Start: A new run has begun for the user’s message. +- Run Start: A new run has begun for the user's message. - Tool Call Start: The agent decided to invoke a tool. - Tool Call Arguments: Arguments being passed to the tool. - Tool Call End: Tool execution completed. -- Tool Call Result: Tool’s output is available. +- Tool Call Result: Tool's output is available. +- Card Start: The agent started generating a card. Contains `cardId` and `executionText` (a human-readable status like "Building your product card..."). +- Card: The full card payload is available. Use `getCard()` to retrieve the raw card JSON and pass it to the renderer. +- Card End: The card generation flow is finalized. - Text Message Start: The agent started composing a reply. - Text Message Content: Streaming content chunks for progressive rendering. - Text Message End: The agent reply is complete. - Run Finished: The run is finalized; persisted messages will follow. +#### Card Streaming Event Classes + +| Class | Properties | +| -- | -- | +| `AIAssistantCardStartedEvent` | `runId`, `threadId`, `streamMessageId`, `cardId`, `executionText` | +| `AIAssistantCardReceivedEvent` | `runId`, `threadId`, `streamMessageId`, `cardId`, `getCard()` → `Map?` | +| `AIAssistantCardEndedEvent` | `runId`, `threadId`, `streamMessageId`, `cardId` | + ### Agentic Messages These events are received via the **`MessageListener`** after the run completes. @@ -112,4 +140,113 @@ These events are received via the **`MessageListener`** after the run completes. } ``` - \ No newline at end of file + + + + +Starting from SDK version **5.0.5**, AI assistant message content is delivered via `getElements()`. If the agent response contains only a card (no accompanying text), `getText()` will return an empty string — always prefer `getElements()` as the primary data source for rendering. + + + +### AIAssistantMessage Elements + +A persisted `AIAssistantMessage` carries its content in two ways: + +1. **`getText()`** — The flat content string (unchanged, legacy/fallback path). +2. **`getElements()`** — An ordered array of `AIAssistantElement` objects representing discrete content blocks (text and cards) in the order the agent produced them. **This is the default render source** — when present, walk the list left-to-right and render each block in order. + +When `getElements()` returns `null` or is empty (older messages), fall back to `getText()`. + +#### AIAssistantElement + +Each element exposes two accessors: + +| Method | Return Type | Description | +| -- | -- | -- | +| `getType()` | `String?` | The element's type: `"text"`, `"card"`, `"graph"`, etc. | +| `getData()` | `dynamic` | The element's raw body data. Shape depends on type — `String` for text, `Map` (with keys `card` and `cardId`) for card, raw JSON value for others. | + + + + ```dart + void handleAIAssistantMessage(AIAssistantMessage message) { + final elements = message.getElements(); + + if (elements != null && elements.isNotEmpty) { + // Preferred path: walk elements in order + for (final element in elements) { + switch (element.getType()) { + case 'text': + final textContent = element.getData() as String; + debugPrint("Text block: $textContent"); + break; + case 'card': + final cardData = element.getData() as Map; + final cardPayload = cardData['card'] as Map; + final cardId = cardData['cardId'] as String; + debugPrint("Card block: $cardId"); + // Pass cardPayload to CometChatCardView renderer + break; + default: + debugPrint("Unknown element type: ${element.getType()}"); + break; + } + } + } else { + // Fallback: use getText() for older messages without elements + debugPrint("Message text: ${message.text}"); + } + } + ``` + + + +## Card Messages (Developer Cards) + +Developer card messages are rich, interactive messages (buttons, images, styled layouts) described as JSON and sent via the Platform API or Bubble Builder. The SDK only **receives** card messages — it does not send them. + +A `CardMessage` arrives with `category: "card"` and is delivered on the `onCardMessageReceived` callback of the `MessageListener`. + +### CardMessage Class + +| Method | Return Type | Description | +| -- | -- | -- | +| `getCard()` | `Map?` | The raw card schema payload. Pass directly to the card renderer. | +| `getText()` | `String?` | Preview text for push notifications and conversation list. | +| `getFallbackText()` | `String?` | Fallback text from inside the card (`card.fallbackText`). Used for accessibility or when the renderer fails. | +| `getTags()` | `List?` | Tags associated with this message. | + + + + ```dart + const listenerId = "unique_listener_id"; + + class CardMessageHandler with MessageListener { + // CometChat.addMessageListener(listenerId, this); + + @override + void onCardMessageReceived(CardMessage cardMessage) { + debugPrint("Card message received: ${cardMessage.id}"); + + // Get the raw card payload for the renderer + final cardPayload = cardMessage.getCard(); + debugPrint("Card payload: $cardPayload"); + + // Get fallback text for previews + final fallback = cardMessage.getFallbackText(); + debugPrint("Fallback: $fallback"); + + // Get preview text for conversation list + final previewText = cardMessage.getText(); + debugPrint("Preview text: $previewText"); + } + } + ``` + + + + + +Card messages are **receive-only**. They are created and sent exclusively via the Platform (REST) API and Dashboard Bubble Builder. The SDK exposes the card payload raw via `getCard()` — an external renderer library (e.g., CometChatCardView) is responsible for drawing the card UI. + + diff --git a/sdk/flutter/real-time-listeners.mdx b/sdk/flutter/real-time-listeners.mdx index 830e2bbf3..beb27a03b 100644 --- a/sdk/flutter/real-time-listeners.mdx +++ b/sdk/flutter/real-time-listeners.mdx @@ -152,6 +152,7 @@ The `MessageListener` class provides you with live events related to messages. B | `onMessageEdited(BaseMessage message)` | This method is triggered when a particular message has been edited in a user/group conversation. | | `onMessageDeleted(BaseMessage message)` | This event is triggered when a particular message is deleted in a user/group conversation. | | `onInteractiveMessageReceived(InteractiveMessage message)` | This event is triggered when an Interactive Message is received. | +| `onCardMessageReceived(CardMessage message)` | This event is triggered when a Card Message is received. | | `onInteractionGoalCompleted(InteractionReceipt receipt)` | This event is triggered when an interaction Goal is achieved. | | `onTransientMessageReceived(TransientMessage transientMessage)` | This event is triggered when a Transient Message is received. | | `onMessageReactionAdded(ReactionEvent reactionEvent)` | This event is triggered when a reaction is added to a message in a user/group conversation. | @@ -222,19 +223,24 @@ class Class_Name with MessageListener { } + @override + void onCardMessageReceived(CardMessage cardMessage) { + + } - @Override - public void onTransientMessageReceived(TransientMessage transientMessage) { + + @override + void onTransientMessageReceived(TransientMessage transientMessage) { } - @Override - public void onMessageReactionAdded(ReactionEvent reactionEvent) { + @override + void onMessageReactionAdded(ReactionEvent reactionEvent) { } - @Override - public void onMessageReactionRemoved(ReactionEvent reactionEvent) { + @override + void onMessageReactionRemoved(ReactionEvent reactionEvent) { } diff --git a/sdk/flutter/receive-messages.mdx b/sdk/flutter/receive-messages.mdx index 5af5f2d60..7434528c8 100644 --- a/sdk/flutter/receive-messages.mdx +++ b/sdk/flutter/receive-messages.mdx @@ -44,6 +44,11 @@ onInteractiveMessageReceived(InteractiveMessage message) { } +@override +void onCardMessageReceived(CardMessage cardMessage) { + debugPrint("Card message received successfully: $cardMessage"); +} + } ``` @@ -227,7 +232,7 @@ messageRequest.fetchPrevious(onSuccess: (List list) { 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 `is` operator to check the type of object. +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`, `CardMessage`, `Action` or `Call` class. You can use the `is` operator to check the type of object. diff --git a/sdk/flutter/setup.mdx b/sdk/flutter/setup.mdx index b07e589e5..4d23df6d5 100644 --- a/sdk/flutter/setup.mdx +++ b/sdk/flutter/setup.mdx @@ -22,16 +22,9 @@ Minimum Requirement ### Add the CometChat Dependency -### Cloudsmith - -Add the Cloudsmith hosted repository and dependency to your `pubspec.yaml`: - ```yaml dependencies: - cometchat_sdk: - hosted: - url: https://dart.cloudsmith.io/cometchat/cometchat/ - version: 5.0.0 + cometchat_sdk: ^5.0.5 ``` Then run: diff --git a/sdk/flutter/upgrading-from-v4-guide.mdx b/sdk/flutter/upgrading-from-v4-guide.mdx index 8f3cdc7f8..9271ee4d9 100644 --- a/sdk/flutter/upgrading-from-v4-guide.mdx +++ b/sdk/flutter/upgrading-from-v4-guide.mdx @@ -7,16 +7,13 @@ This guide helps you migrate your Flutter application from CometChat SDK v4 to v ## Installation -### Cloudsmith +### Add the CometChat Dependency -Add the Cloudsmith hosted repository and dependency to your `pubspec.yaml`: +Update your `pubspec.yaml` to the latest v5 SDK: ```yaml dependencies: - cometchat_sdk: - hosted: - url: https://dart.cloudsmith.io/cometchat/cometchat/ - version: 5.0.0 + cometchat_sdk: ^5.0.5 ``` Then run: