AI Agents - CometChat Docs

AI Integration Quick Reference

Feature	Description
AI Agents	Intelligent automated conversations with real-time streaming
AI Moderation	Automatic content moderation with `PENDING` → `APPROVED` / `DISAPPROVED` flow

// 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", new CometChat.MessageListener({
  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 Event flow: Run Start → Tool Call(s) → Text Message Stream → Run Finished

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.

Agents only respond to text messages.

Agent Run Lifecycle and Message Flow

When a user sends a text message to an Agent:

The platform starts a run and streams real-time events via AIAssistantListener
After the run completes, persisted Agentic Messages arrive via MessageListener

Real-time Events

Events are received via the onAIAssistantEventReceived method of the AIAssistantListener class as 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 — there can be multiple tool call cycles in a single run. Text Message events are always emitted and carry the assistant’s reply incrementally.

Event Object Properties

Every event is an AIAssistantBaseEvent with these common properties:

Getter	Return Type	Description
`getType()`	`string`	Event type (e.g., `run_started`, `text_message_content`)
`getConversationId()`	`string`	The conversation this event belongs to
`getMessageId()`	`string`	The message ID associated with the event
`getParentMessageId()`	`string`	Parent message ID (for threaded messages)
`getRunId()`	`string`	The run ID for this agent execution
`getThreadId()`	`string`	The thread ID for this agent execution
`getTimestamp()`	`number`	Timestamp of the event
`getData()`	`object`	Full event data payload

Some events carry additional data:

Event	Extra Getter	Description
Text Message Content	`getDelta()`	The streaming text chunk for progressive rendering
Tool Call Arguments	`getToolCallId()`, `getDelta()`	Tool call ID and argument chunk
Tool Call Result	`getToolCallId()`, `getContent()`, `getRole()`	Tool call ID, result content, and role

TypeScript
JavaScript

        const listnerId: string = "unique_listener_id";

        // Adding the AIAssistantListener
        CometChat.addAIAssistantListener(listnerId, {
            onAIAssistantEventReceived: (message: CometChat.AIAssistantBaseEvent) => {
                console.log("AIAssistant event received successfully", message);
            }
        });

        // Removing the AIAssistantListener
        CometChat.removeAIAssistantListener(listnerId);

        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);

Always remove AI Assistant listeners when the component unmounts to prevent memory leaks.

CometChat.removeAIAssistantListener("unique_listener_id");

Event descriptions

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.
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

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

Each message type extends BaseMessage and has a typed data accessor:

Message Type	Data Getter	Data Properties
`AIAssistantMessage`	`getAssistantMessageData()`	`getRunId()`, `getThreadId()`, `getText()`
`AIToolResultMessage`	`getToolResultMessageData()`	`getRunId()`, `getThreadId()`, `getText()`, `getToolCallId()`
`AIToolArgumentMessage`	`getToolArgumentMessageData()`	`getRunId()`, `getThreadId()`, `getToolCalls()`

The getToolCalls() method on AIToolArgumentMessage returns an array of AIToolCall objects, each with:

Getter	Return Type	Description
`getId()`	`string`	Unique tool call ID
`getType()`	`string`	Tool call type
`getFunction()`	`AIToolCallFunction`	Function object with `getName()` and `getArguments()`
`getDisplayName()`	`string`	Display name of the tool
`getExecutionText()`	`string`	Execution description text

TypeScript
JavaScript

const listnerId: string = "unique_listener_id";

// Adding the MessageListener
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);
    },
});

// Removing the MessageListener
CometChat.removeMessageListener(listnerId);

const listnerId = "unique_listener_id";

// Adding the MessageListener
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);
    },
});

// Removing the MessageListener
CometChat.removeMessageListener(listnerId);

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

AI Agents Overview

Explore the full AI Agents platform documentation

AI Moderation

Automatically moderate messages using AI

Send Messages

Send text messages that trigger AI Agent responses

​Agent Run Lifecycle and Message Flow

​Real-time Events

​Event Object Properties

​Event descriptions

​Agentic Messages

​Next Steps

AI Agents Overview

AI Moderation

Send Messages

Agent Run Lifecycle and Message Flow

Real-time Events

Event Object Properties

Event descriptions

Agentic Messages

Next Steps