AI Assistant Chat - CometChat Docs

AI Integration Quick Reference

{
  "component": "CometChatAIAssistantChat",
  "package": "@cometchat/chat-uikit-react",
  "import": "import { CometChatAIAssistantChat } from \"@cometchat/chat-uikit-react\";",
  "description": "AI agent chat interface with streaming responses, suggested messages, tool calling, and conversation history.",
  "cssRootClass": ".cometchat-ai-assistant-chat",
  "primaryOutput": {
    "prop": "onSendButtonClick",
    "type": "(message: CometChat.BaseMessage) => void"
  },
  "props": {
    "data": {
      "user": {
        "type": "CometChat.User",
        "default": "REQUIRED",
        "note": "The AI assistant user entity"
      },
      "streamingSpeed": {
        "type": "number",
        "default": 30,
        "note": "Milliseconds between text chunks during streaming"
      },
      "aiAssistantTools": {
        "type": "CometChatAIAssistantTools",
        "default": "undefined",
        "note": "Tool handlers for AI function calls"
      },
      "loadLastAgentConversation": {
        "type": "boolean",
        "default": false
      },
      "suggestedMessages": {
        "type": "string[]",
        "default": "[] (falls back to user metadata)"
      },
      "parentMessageId": {
        "type": "number",
        "default": "undefined",
        "note": "Load a specific conversation thread"
      }
    },
    "callbacks": {
      "onSendButtonClick": "(message: CometChat.BaseMessage) => void",
      "onBackButtonClicked": "() => void",
      "onCloseButtonClicked": "() => void",
      "onError": "((error: CometChat.CometChatException) => void) | null"
    },
    "visibility": {
      "hideSuggestedMessages": { "type": "boolean", "default": false },
      "hideChatHistory": { "type": "boolean", "default": false },
      "hideNewChat": { "type": "boolean", "default": false },
      "showBackButton": { "type": "boolean", "default": false },
      "showCloseButton": { "type": "boolean", "default": false }
    },
    "viewSlots": {
      "emptyChatImageView": "ReactNode",
      "emptyChatGreetingView": "ReactNode",
      "emptyChatIntroMessageView": "ReactNode",
      "emptyView": "ReactNode",
      "loadingView": "ReactNode",
      "errorView": "ReactNode",
      "headerItemView": "ReactNode",
      "headerTitleView": "ReactNode",
      "headerSubtitleView": "ReactNode",
      "headerLeadingView": "ReactNode",
      "headerTrailingView": "ReactNode",
      "headerAuxiliaryButtonView": "ReactNode"
    }
  },
  "events": [
    {
      "name": "ui:compose/text",
      "payload": "{ text }",
      "description": "Suggestion pill clicked (sets text in composer)"
    }
  ],
  "sdkListeners": [],
  "types": {
    "CometChatAIAssistantTools": "Class — maps tool function names to handler functions via constructor(actions: Record<string, (args: Record<string, unknown>) => void>)"
  }
}

Overview

CometChatAIAssistantChat is an AI agent chat interface. It renders a full chat experience with streaming responses, suggested message pills, tool calling support, and a conversation history sidebar. Pass a CometChat.User representing the AI assistant and the component handles the rest — message threading, streaming display, and composer integration.

1:1 and group conversations. AI Agents work in both one-on-one and group conversations. In a 1:1 chat, the end user talks directly with the agent user. In a group, the agent participates as a member — its messages (including cards) are delivered and attributed like any other member’s message. If the group contains only one user and one agent, the agent responds automatically. In groups with more than two members, the agent only responds when @mentioned.

Live Preview — interact with the default AI assistant chat.Open in Storybook ↗

The component handles:

Streaming AI responses with configurable speed
Suggested message pills (from props or user metadata)
Tool calling via aiAssistantTools
Conversation history sidebar
New chat creation
Custom header views

Usage

Flat API

import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIChat({ aiUser }: { aiUser: CometChat.User }) {
  return (
    <CometChatAIAssistantChat
      user={aiUser}
      onSendButtonClick={(message) => {
        console.log("Message sent:", message);
      }}
    />
  );
}

With Tool Calling

import {
  CometChatAIAssistantChat,
  CometChatAIAssistantTools,
} from "@cometchat/chat-uikit-react";

function AIChat({ aiUser }: { aiUser: CometChat.User }) {
  const tools = new CometChatAIAssistantTools({
    getWeather: (args) => {
      console.log("Getting weather for:", args.location);
    },
    searchDocs: (args) => {
      console.log("Searching docs for:", args.query);
    },
  });

  return (
    <CometChatAIAssistantChat
      user={aiUser}
      aiAssistantTools={tools}
      suggestedMessages={["What's the weather?", "Search documentation"]}
    />
  );
}

With Custom Header

import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIChat({ aiUser }: { aiUser: CometChat.User }) {
  return (
    <CometChatAIAssistantChat
      user={aiUser}
      showBackButton
      onBackButtonClicked={() => navigateBack()}
      headerTitleView={<span>My AI Assistant</span>}
      headerSubtitleView={<span>Always online</span>}
    />
  );
}

Full Layout Example

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function App() {
  const [aiUser, setAiUser] = useState<CometChat.User | null>(null);

  useEffect(() => {
    CometChat.getUser("ai-assistant-uid").then(setAiUser);
  }, []);

  if (!aiUser) return <div>Loading...</div>;

  return (
    <div style={{ height: "100vh" }}>
      <CometChatAIAssistantChat
        user={aiUser}
        loadLastAgentConversation
        suggestedMessages={[
          "How do I get started?",
          "What features are available?",
          "Help me with integration",
        ]}
        onSendButtonClick={(message) => {
          console.log("User sent:", message);
        }}
        onError={(error) => {
          console.error("AI Chat error:", error);
        }}
      />
    </div>
  );
}

Actions and Events

Callback Props

Prop	Signature	Fires when
`onSendButtonClick`	`(message: CometChat.BaseMessage) => void`	User sends a message
`onBackButtonClicked`	`() => void`	Back button is clicked
`onCloseButtonClicked`	`() => void`	Close button is clicked
`onError`	`((error: CometChat.CometChatException) => void) \| null`	SDK error occurs

Events Emitted

UI events this component publishes:

Event	Payload	Fires when
`ui:compose/text`	`{ text }`	Suggestion pill clicked (sets text in composer)

Events Received

None.

SDK Listeners (Automatic)

None directly — the component uses CometChatMessageList internally which handles SDK listeners for message updates. The AI streaming is handled via CometChat.addAIAssistantListener.

Customization

View Props

Use view props to replace sections of the default UI while keeping the component’s behavior intact:

<CometChatAIAssistantChat
  user={aiUser}
  emptyChatImageView={<MyBotAvatar />}
  emptyChatGreetingView={<h2>Hello! I'm your assistant.</h2>}
  emptyChatIntroMessageView={<p>Ask me anything about our product.</p>}
  headerItemView={<MyCustomHeader />}
  loadingView={<AILoadingSkeleton />}
  errorView={<AIErrorState />}
/>

Slot	Signature	Replaces
`emptyChatImageView`	`ReactNode`	AI avatar/icon in empty state
`emptyChatGreetingView`	`ReactNode`	Greeting message in empty state
`emptyChatIntroMessageView`	`ReactNode`	Intro message in empty state
`emptyView`	`ReactNode`	Entire empty state (replaces default greeting)
`loadingView`	`ReactNode`	Loading shimmer
`errorView`	`ReactNode`	Error state
`headerItemView`	`ReactNode`	Entire header (replaces default)
`headerTitleView`	`ReactNode`	Header title
`headerSubtitleView`	`ReactNode`	Header subtitle
`headerLeadingView`	`ReactNode`	Header avatar area
`headerTrailingView`	`ReactNode`	Header trailing section
`headerAuxiliaryButtonView`	`ReactNode`	Header auxiliary buttons (New Chat + History)

emptyChatImageView

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIAssistantCustomImage() {
  const [agent, setAgent] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("assistant_uid").then((u) => setAgent(u));
  }, []);

  if (!agent) return null;

  return (
    <CometChatAIAssistantChat
      user={agent}
      emptyChatImageView={<img src={"ICON_URL"} height={60} width={60} alt="" />}
    />
  );
}

emptyChatGreetingView

TypeScript
CSS

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIAssistantCustomGreeting() {
  const [agent, setAgent] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("assistant_uid").then((u) => setAgent(u));
  }, []);

  if (!agent) return null;

  return (
    <CometChatAIAssistantChat
      user={agent}
      emptyChatGreetingView={
        <div className="cometchat-ai-assistant-chat__empty-chat-greeting">
          <span className="plan-name">Free Plan</span> .
          <span className="upgrade-button">Upgrade</span>
        </div>
      }
    />
  );
}

.cometchat-ai-assistant-chat__empty-chat-greeting {
  display: flex;
  padding: 8px 20px;
  justify-content: center;
  align-items: center;
  gap: 8px;
  border-radius: 6px;
  border: 1px solid #e8e8e8;
  background: #f5f5f5;
  width: fit-content;
  align-self: center;
}

.cometchat-ai-assistant-chat__empty-chat-greeting .upgrade-button {
  color: #6852d6;
}

emptyChatIntroMessageView

TypeScript
CSS

import { useState, useEffect } from "react";
import { CometChat } from "@cometchat/chat-sdk-javascript";
import { CometChatAIAssistantChat } from "@cometchat/chat-uikit-react";

function AIAssistantCustomIntro() {
  const [agent, setAgent] = useState<CometChat.User>();

  useEffect(() => {
    CometChat.getUser("assistant_uid").then((u) => setAgent(u));
  }, []);

  if (!agent) return null;

  return (
    <CometChatAIAssistantChat
      user={agent}
      emptyChatIntroMessageView={
        <div className="cometchat-ai-assistant-chat__empty-chat-intro">
          Hey, nice to see you What's new?
        </div>
      }
    />
  );
}

.cometchat-ai-assistant-chat__empty-chat-intro {
  display: flex;
  padding: 12px;
  justify-content: center;
  align-items: center;
  gap: 10px;
  border-radius: 12px;
  background: #f9f8fd;
  width: 172px;
  color: #141414;
  text-align: center;
  font-size: 16px;
  font-weight: 400;
  line-height: 140%;
  margin: 10px 0;
}

CSS Styling

Override design tokens on the component selector:

.cometchat-ai-assistant-chat {
  --cometchat-background-color-01: #1a1a2e;
  --cometchat-text-color-primary: #ffffff;
}

.cometchat-ai-assistant-chat__empty-state-greeting-message {
  font-size: 1.5rem;
  font-weight: 600;
}

Props

user is required. All other props are optional.

user

The AI assistant user entity. This is the CometChat user that represents the AI agent.


Type	`CometChat.User`
Default	REQUIRED

streamingSpeed

Milliseconds between text chunks during streaming display.


Type	`number`
Default	`30`

aiAssistantTools

Tool handlers for AI function calls. Maps tool names to handler functions.


Type	`CometChatAIAssistantTools`
Default	`undefined`

const tools = new CometChatAIAssistantTools({
  getWeather: (args) => fetchWeather(args.location as string),
  searchDocs: (args) => searchDocumentation(args.query as string),
});

<CometChatAIAssistantChat user={aiUser} aiAssistantTools={tools} />

loadLastAgentConversation

Auto-load the most recent conversation with the AI assistant on mount.


Type	`boolean`
Default	`false`

hideSuggestedMessages

Hide the suggestion pills in the empty chat state.


Type	`boolean`
Default	`false`

suggestedMessages

Custom suggestion texts displayed as pills in the empty state. Overrides suggestions from user metadata.


Type	`string[]`
Default	`[]` (falls back to user metadata `suggestedMessages`)

emptyChatImageView

Custom image/icon view for the empty chat state.


Type	`ReactNode`
Default	Built-in AI avatar

emptyChatGreetingView

Custom greeting message view for the empty chat state.


Type	`ReactNode`
Default	User’s `greetingMessage` metadata or display name

emptyChatIntroMessageView

Custom intro message view for the empty chat state.


Type	`ReactNode`
Default	User’s `introductoryMessage` metadata or “I am here to assist you!“

hideChatHistory

Hide the chat history sidebar button in the header.


Type	`boolean`
Default	`false`

hideNewChat

Hide the “New Chat” button in the header.


Type	`boolean`
Default	`false`

showBackButton

Show the back button in the header.


Type	`boolean`
Default	`false`

showCloseButton

Show the close button in the header.


Type	`boolean`
Default	`false`

onBackButtonClicked

Callback when the back button is clicked.


Type	`() => void`
Default	`undefined`

onCloseButtonClicked

Callback when the close button is clicked.


Type	`() => void`
Default	`undefined`

onSendButtonClick

Callback when a message is sent to the AI assistant.


Type	`(message: CometChat.BaseMessage) => void`
Default	`undefined`

emptyView

Custom empty state view. Replaces the entire default greeting (image + greeting + intro + suggestions).


Type	`ReactNode`
Default	Built-in greeting with suggestions

loadingView

Custom loading view.


Type	`ReactNode`
Default	Built-in loading state

errorView

Custom error view.


Type	`ReactNode`
Default	Built-in error state

onError

Callback when an SDK error occurs.


Type	`((error: CometChat.CometChatException) => void) \| null`
Default	`null`

className

Additional CSS class name applied to the root element.


Type	`string`
Default	`undefined`

parentMessageId

Load a specific conversation thread by parent message ID.


Type	`number`
Default	`undefined`

headerItemView

Custom view that replaces the entire header.


Type	`ReactNode`
Default	Built-in `CometChatMessageHeader`

headerTitleView

Custom title view for the header.


Type	`ReactNode`
Default	AI user’s display name

headerSubtitleView

Custom subtitle view for the header.


Type	`ReactNode`
Default	Built-in subtitle

headerLeadingView

Custom leading view (avatar area) for the header.


Type	`ReactNode`
Default	AI user’s avatar

headerTrailingView

Custom trailing view for the header.


Type	`ReactNode`
Default	`undefined`

headerAuxiliaryButtonView

Custom auxiliary button view for the header. Replaces the default New Chat + History buttons.


Type	`ReactNode`
Default	Built-in New Chat + History buttons

CSS Selectors

Target	Selector
Root container	`.cometchat-ai-assistant-chat`
Header	`.cometchat-ai-assistant-chat__header`
Body	`.cometchat-ai-assistant-chat__body`
Empty state	`.cometchat-ai-assistant-chat__empty-state`
Empty state icon	`.cometchat-ai-assistant-chat__empty-state-icon`
Greeting message	`.cometchat-ai-assistant-chat__empty-state-greeting-message`
Intro message	`.cometchat-ai-assistant-chat__empty-state-intro-message`
Suggested messages	`.cometchat-ai-assistant-chat__empty-state-suggested-messages`

Next Steps

Message List

Display messages in a conversation

Message Composer

Compose and send messages

Theming

Customize colors, fonts, and spacing

​Overview

​Usage

​Flat API

​With Tool Calling

​With Custom Header

​Full Layout Example

​Actions and Events

​Callback Props

​Events Emitted

​Events Received

​SDK Listeners (Automatic)

​Customization

​View Props

​emptyChatImageView

​emptyChatGreetingView

​emptyChatIntroMessageView

​CSS Styling

​Props

​user

​streamingSpeed

​aiAssistantTools

​loadLastAgentConversation

​hideSuggestedMessages

​suggestedMessages

​emptyChatImageView

​emptyChatGreetingView

​emptyChatIntroMessageView

​hideChatHistory

​hideNewChat

​showBackButton

​showCloseButton

​onBackButtonClicked

​onCloseButtonClicked

​onSendButtonClick

​emptyView

​loadingView

​errorView

​onError

​className

​parentMessageId

​headerItemView

​headerTitleView

​headerSubtitleView

​headerLeadingView

​headerTrailingView

​headerAuxiliaryButtonView

​CSS Selectors

​Next Steps

Message List

Message Composer

Theming

Overview

Usage

Flat API

With Tool Calling

With Custom Header

Full Layout Example

Actions and Events

Callback Props

Events Emitted

Events Received

SDK Listeners (Automatic)

Customization

View Props

emptyChatImageView

emptyChatGreetingView

emptyChatIntroMessageView

CSS Styling

Props

user

streamingSpeed

aiAssistantTools

loadLastAgentConversation

hideSuggestedMessages

suggestedMessages

emptyChatImageView

emptyChatGreetingView

emptyChatIntroMessageView

hideChatHistory

hideNewChat

showBackButton

showCloseButton

onBackButtonClicked

onCloseButtonClicked

onSendButtonClick

emptyView

loadingView

errorView

onError

className

parentMessageId

headerItemView

headerTitleView

headerSubtitleView

headerLeadingView

headerTrailingView

headerAuxiliaryButtonView

CSS Selectors

Next Steps