Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -4152,7 +4152,6 @@
"sdk/android/v5/typing-indicators",
"sdk/android/v5/delivery-read-receipts",
"sdk/android/v5/transient-messages",
"sdk/android/v5/interactive-messages",
"sdk/android/v5/mentions",
"sdk/android/v5/reactions"
]
Expand Down Expand Up @@ -8348,6 +8347,10 @@
"source": "/fundamentals/limits",
"destination": "/rest-api/rate-limits"
},
{
"source": "/sdk/android/v5/interactive-messages",
"destination": "/sdk/android/v5/send-message"
},
{
"source": "/sdk/javascript/interactive-messages",
"destination": "/sdk/javascript/send-message"
Expand Down
116 changes: 116 additions & 0 deletions images/message-structure-hierarchy-card.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 4 additions & 4 deletions sdk/android/ai-agents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@

## Agent Run Lifecycle and Message Flow

This section explains how a users 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.

Check warning on line 34 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L34

Did you really mean 'agentic'?
- 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`**.

Check warning on line 37 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L37

Did you really mean 'Agentic'?

### Real-time Events
Events are received via the **`onAIAssistantEventReceived`** method of the **`AIAssistantListener`** class as [`AIAssistantBaseEvent`](/sdk/reference/messages#aiassistantbaseevent) objects in this general order:
Expand All @@ -54,7 +54,7 @@
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 assistants reply incrementally.
- `Text Message` events are always emitted and carry the assistant's reply incrementally.

<Tabs>
<Tab title="Java">
Expand Down Expand Up @@ -87,17 +87,17 @@
</Tabs>

#### Event descriptions
- Run Start: A new run has begun for the users 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: Tools output is available.
- Tool Call Result: Tool's output is available.
- 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.

### Agentic Messages

Check warning on line 100 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L100

Did you really mean 'Agentic'?

These events are received via the **`MessageListener`** after the run completes.
- `AIAssistantMessage`: The full assistant reply.
Expand Down Expand Up @@ -153,7 +153,7 @@
</Tabs>


## Agentic Message Payload Structures

Check warning on line 156 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L156

Did you really mean 'Agentic'?

<Accordion title="AIAssistantMessage Object">

Expand All @@ -172,7 +172,7 @@
| `sentAt` | long | Unix timestamp when sent |
| `deliveredAt` | long | Unix timestamp when delivered |
| `readAt` | long | Unix timestamp when read |
| `metadata` | JSONObject | Custom message metadata |

Check warning on line 175 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L175

Did you really mean 'JSONObject'?
| `readByMeAt` | long | When logged-in user read message |
| `deliveredToMeAt` | long | When delivered to logged-in user |
| `deletedAt` | long | Unix timestamp when deleted (0 if not deleted) |
Expand Down Expand Up @@ -203,24 +203,24 @@
"uid": "user_456",
"name": "Jane Smith"
},
"receiverUid": "user_456",

Check warning on line 206 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L206

Did you really mean 'receiverUid'?
"type": "assistant",
"receiverType": "user",

Check warning on line 208 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L208

Did you really mean 'receiverType'?
"category": "agentic",

Check warning on line 209 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L209

Did you really mean 'agentic'?
"sentAt": 1699900000,

Check warning on line 210 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L210

Did you really mean 'sentAt'?
"deliveredAt": 1699900001,

Check warning on line 211 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L211

Did you really mean 'deliveredAt'?
"readAt": 1699900002,

Check warning on line 212 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L212

Did you really mean 'readAt'?
"metadata": {"priority": "high"},
"readByMeAt": 1699900002,
"deliveredToMeAt": 1699900001,
"deletedAt": 0,

Check warning on line 216 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L216

Did you really mean 'deletedAt'?
"editedAt": 0,

Check warning on line 217 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L217

Did you really mean 'editedAt'?
"deletedBy": null,

Check warning on line 218 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L218

Did you really mean 'deletedBy'?
"editedBy": null,

Check warning on line 219 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L219

Did you really mean 'editedBy'?
"updatedAt": 1699900000,

Check warning on line 220 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L220

Did you really mean 'updatedAt'?
"conversationId": "user_123_user_456",

Check warning on line 221 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L221

Did you really mean 'conversationId'?
"runId": 98765,

Check warning on line 222 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L222

Did you really mean 'runId'?
"threadId": "thread_abc",

Check warning on line 223 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L223

Did you really mean 'threadId'?

Check warning on line 223 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L223

Did you really mean 'thread_abc'?
"text": "Here's the answer...",
"tags": ["ai-response"]
}
Expand Down Expand Up @@ -324,7 +324,7 @@
| `sentAt` | long | Unix timestamp when sent |
| `deliveredAt` | long | Unix timestamp when delivered |
| `readAt` | long | Unix timestamp when read |
| `metadata` | JSONObject | Custom message metadata |

Check warning on line 327 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L327

Did you really mean 'JSONObject'?
| `readByMeAt` | long | When logged-in user read message |
| `deliveredToMeAt` | long | When delivered to logged-in user |
| `deletedAt` | long | Unix timestamp when deleted (0 if not deleted) |
Expand Down Expand Up @@ -390,7 +390,7 @@
|-----------|------|-------------|
| `id` | String | Unique identifier for the tool call |
| `name` | String | Name of the tool being called |
| `arguments` | JSONObject | Arguments passed to the tool |

Check warning on line 393 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L393

Did you really mean 'JSONObject'?

**Sample AIToolCall Object:**

Expand Down Expand Up @@ -419,7 +419,7 @@
| `avatar` | String | URL to user's profile picture |
| `link` | String | URL to user's profile page |
| `role` | String | User role for access control |
| `metadata` | JSONObject | Custom data set by developer |

Check warning on line 422 in sdk/android/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/ai-agents.mdx#L422

Did you really mean 'JSONObject'?
| `status` | String | User online status. Values: `"online"`, `"offline"` |
| `statusMessage` | String | Custom status message |
| `lastActiveAt` | long | Unix timestamp of last activity |
Expand Down
139 changes: 133 additions & 6 deletions sdk/android/v5/ai-agents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@

## Agent Run Lifecycle and Message Flow

This section explains how a users 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.

Check warning on line 14 in sdk/android/v5/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/v5/ai-agents.mdx#L14

Did you really mean 'agentic'?
- 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`**.

Check warning on line 17 in sdk/android/v5/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/v5/ai-agents.mdx#L17

Did you really mean 'Agentic'?

### Real-time Events
Events are received via the **`onAIAssistantEventReceived`** method of the **`AIAssistantListener`** class in this general order:
Expand All @@ -25,16 +25,21 @@
- Tool Call Arguments
- Tool Call End
- Tool Call Result
3. One or more assistant reply streams:
3. Zero or more card streams (repeats for each card the agent produces):
- Card Start
- Card
- 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 (`Card Start` → `Card` → `Card End`) appear only when the agent produces a card, and repeat for each card.
- `Text Message` events are always emitted and carry the assistant's reply incrementally.

<Tabs>
<Tab title="Java">
Expand Down Expand Up @@ -67,17 +72,82 @@
</Tabs>

#### Event descriptions
- Run Start: A new run has begun for the users 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 began producing a card; carries a `cardId` and an `executionText` loading label.
- Card: The full card payload for the given `cardId` is available to render.
- Card End: The card stream for the given `cardId` is complete.
- 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 Events

When an agent produces a card, it is delivered through three streaming events on `onAIAssistantEventReceived`. Each event is a subclass of `AIAssistantBaseEvent` — check the concrete type to handle it.

| Event | Getter | Description |
| ----- | ------ | ----------- |
| `AIAssistantCardStartedEvent` | `getCardId()` | Identifier for the card being generated. |
| | `getExecutionText()` | Loading label shown while the card is built. |
| | `getStreamMessageId()` | Identifier of the streaming message that owns this card. |
| `AIAssistantCardReceivedEvent` | `getCardId()` | Identifier matching the corresponding start event. |
| | `getCard()` | The complete card payload (`JSONObject`) to render. |
| `AIAssistantCardEndedEvent` | `getCardId()` | Signals the card stream for this `cardId` is complete. |

<Tabs>
<Tab title="Java">
```java

CometChat.addAIAssistantListener(LISTENERS_TAG, new CometChat.AIAssistantListener() {
@Override
public void onAIAssistantEventReceived(AIAssistantBaseEvent event) {
if (event instanceof AIAssistantCardStartedEvent) {
AIAssistantCardStartedEvent started = (AIAssistantCardStartedEvent) event;
String cardId = started.getCardId();
String label = started.getExecutionText(); // e.g. "Building card…"
} else if (event instanceof AIAssistantCardReceivedEvent) {
AIAssistantCardReceivedEvent received = (AIAssistantCardReceivedEvent) event;
String cardId = received.getCardId();
JSONObject card = received.getCard(); // full card payload
} else if (event instanceof AIAssistantCardEndedEvent) {
AIAssistantCardEndedEvent ended = (AIAssistantCardEndedEvent) event;
// card stream for ended.getCardId() is complete
}
}
});

```
</Tab>
<Tab title="Kotlin">
```kotlin

CometChat.addAIAssistantListener(LISTENERS_TAG, object : CometChat.AIAssistantListener() {
override fun onAIAssistantEventReceived(event: AIAssistantBaseEvent) {
when (event) {
is AIAssistantCardStartedEvent -> {
val cardId = event.cardId
val label = event.executionText // e.g. "Building card…"
}
is AIAssistantCardReceivedEvent -> {
val cardId = event.cardId
val card = event.card // full card payload (JSONObject)
}
is AIAssistantCardEndedEvent -> {
// card stream for event.cardId is complete
}
}
}
})

```
</Tab>
</Tabs>

### Agentic Messages

Check warning on line 150 in sdk/android/v5/ai-agents.mdx

View check run for this annotation

Mintlify / Mintlify Validation (cometchat-22654f5b) - vale-spellcheck

sdk/android/v5/ai-agents.mdx#L150

Did you really mean 'Agentic'?

These events are received via the **`MessageListener`** after the run completes.
- `AIAssistantMessage`: The full assistant reply.
Expand Down Expand Up @@ -128,6 +198,63 @@
}
})

```
</Tab>
</Tabs>

### AIAssistantMessage Elements

Once a run completes, the assistant's reply is persisted as an `AIAssistantMessage`. Its content is exposed as an ordered list of blocks via `getElements()`, letting you render text and cards in the exact order the agent produced them. When `getElements()` is `null` or empty, fall back to the plain `getText()` body.

| Method | Returns | Description |
| ------ | ------- | ----------- |
| `getElements()` | `List<AIAssistantElement>` | Ordered content blocks. `null`/empty for plain-text replies. |
| `getText()` | `String` | Plain-text body (fallback when there are no elements). |

Each `AIAssistantElement` exposes:

| Method | Returns | Description |
| ------ | ------- | ----------- |
| `getType()` | `String` | Block type — `"text"` or `"card"`. |
| `getData()` | `Object` | The block body (text string, or card payload). |

<Tabs>
<Tab title="Java">
```java

List<AIAssistantElement> elements = message.getElements();
if (elements == null || elements.isEmpty()) {
renderText(message.getText());
} else {
for (AIAssistantElement element : elements) {
switch (element.getType()) {
case "text":
renderText(String.valueOf(element.getData()));
break;
case "card":
renderCard(element.getData());
break;
}
}
}

```
</Tab>
<Tab title="Kotlin">
```kotlin

val elements = message.elements
if (elements.isNullOrEmpty()) {
renderText(message.text.orEmpty())
} else {
for (element in elements) {
when (element.type) {
"text" -> renderText(element.data?.toString().orEmpty())
"card" -> renderCard(element.data)
}
}
}

```
</Tab>
</Tabs>
Loading