useCopilotChat

useCopilotChat is a lightweight React hook for headless chat interactions. Perfect for controlling the prebuilt chat components programmatically.

Open Source Friendly - Works without requiring a free public license key.

Looking for fully headless UI?

Get started with useCopilotChatHeadless_c.

Use Cases

Programmatic Messaging: Send messages without displaying chat UI
Programmatic control: Control prebuilt component programmatically
Background Operations: Trigger AI interactions in the background
Fire-and-Forget: Send messages without needing to read responses

Usage

import { TextMessage, MessageRole } from "@copilotkit/runtime-client-gql";
 
const { appendMessage } = useCopilotChat();
 
// Example usage without naming conflicts
const handleSendMessage = async (content: string) => {
  await appendMessage(
    new TextMessage({
      role: MessageRole.User,
      content,
    })
  );
};

Return Values

The following properties are returned from the hook:

visibleMessagesDeprecatedGqlMessage[]deprecated

Array of messages in old non-AG-UI format, use for compatibility only

appendMessage(message: DeprecatedGqlMessage, options?) => Promise<void>deprecated

Append message using old format, use sendMessage instead

reloadMessages(messageId: string) => Promise<void>

Regenerate the response for a specific message by ID

stopGeneration() => void

Stop the current message generation process

reset() => void

Clear all messages and reset chat state completely

isLoadingboolean

Whether the chat is currently generating a response

runChatCompletion() => Promise<Message[]>

Manually trigger chat completion for advanced usage

mcpServersMCPServerConfig[]

Array of Model Context Protocol server configurations

setMcpServers(servers: MCPServerConfig[]) => void

Update MCP server configurations for enhanced context

Parameters

idstring

A unique identifier for the chat. If not provided, a random one will be generated. When provided, the useChat hook with the same id will have shared states across components.

headersRecord<string, string> | Headers

HTTP headers to be sent with the API request.

initialMessagesMessage[]

Initial messages to populate the chat with.

makeSystemMessageSystemMessageFunction

A function to generate the system message. Defaults to defaultSystemMessage.

disableSystemMessageboolean

Disables inclusion of CopilotKit’s default system message. When true, no system message is sent (this also suppresses any custom message from makeSystemMessage).

suggestionsChatSuggestions

Controls the behavior of suggestions in the chat interface.

auto (default) - Suggestions are generated automatically:

When the chat is first opened (empty state)
After each message exchange completes
Uses configuration from useCopilotChatSuggestions hooks

manual - Suggestions are controlled programmatically:

Use setSuggestions() to set custom suggestions
Use generateSuggestions() to trigger AI generation
Access via useCopilotChat hook

SuggestionItem[] - Static suggestions array:

Always shows the same suggestions
No AI generation involved

onInProgress(isLoading: boolean) => void

onSubmitMessage(messageContent: string) => Promise<void> | void

onStopGenerationOnStopGeneration

onReloadMessagesOnReloadMessages

useCopilotChat is a lightweight React hook for headless chat interactions. Perfect for controlling the prebuilt chat components programmatically.

Open Source Friendly - Works without requiring a free public license key.

Looking for fully headless UI?

Get started with useCopilotChatHeadless_c.

Use Cases

Programmatic Messaging: Send messages without displaying chat UI
Programmatic control: Control prebuilt component programmatically
Background Operations: Trigger AI interactions in the background
Fire-and-Forget: Send messages without needing to read responses

Usage

import { TextMessage, MessageRole } from "@copilotkit/runtime-client-gql";
 
const { appendMessage } = useCopilotChat();
 
// Example usage without naming conflicts
const handleSendMessage = async (content: string) => {
  await appendMessage(
    new TextMessage({
      role: MessageRole.User,
      content,
    })
  );
};

Return Values

The following properties are returned from the hook:

visibleMessagesDeprecatedGqlMessage[]deprecated

Array of messages in old non-AG-UI format, use for compatibility only

appendMessage(message: DeprecatedGqlMessage, options?) => Promise<void>deprecated

Append message using old format, use sendMessage instead

reloadMessages(messageId: string) => Promise<void>

Regenerate the response for a specific message by ID

stopGeneration() => void

Stop the current message generation process

reset() => void

Clear all messages and reset chat state completely

isLoadingboolean

Whether the chat is currently generating a response

runChatCompletion() => Promise<Message[]>

Manually trigger chat completion for advanced usage

mcpServersMCPServerConfig[]

Array of Model Context Protocol server configurations

setMcpServers(servers: MCPServerConfig[]) => void

Update MCP server configurations for enhanced context

Parameters

idstring

A unique identifier for the chat. If not provided, a random one will be generated. When provided, the useChat hook with the same id will have shared states across components.

headersRecord<string, string> | Headers

HTTP headers to be sent with the API request.

initialMessagesMessage[]

Initial messages to populate the chat with.

makeSystemMessageSystemMessageFunction

A function to generate the system message. Defaults to defaultSystemMessage.

disableSystemMessageboolean

Disables inclusion of CopilotKit’s default system message. When true, no system message is sent (this also suppresses any custom message from makeSystemMessage).

suggestionsChatSuggestions

Controls the behavior of suggestions in the chat interface.

auto (default) - Suggestions are generated automatically:

When the chat is first opened (empty state)
After each message exchange completes
Uses configuration from useCopilotChatSuggestions hooks

manual - Suggestions are controlled programmatically:

Use setSuggestions() to set custom suggestions
Use generateSuggestions() to trigger AI generation
Access via useCopilotChat hook

SuggestionItem[] - Static suggestions array:

Always shows the same suggestions
No AI generation involved

onInProgress(isLoading: boolean) => void

onSubmitMessage(messageContent: string) => Promise<void> | void

onStopGenerationOnStopGeneration

onReloadMessagesOnReloadMessages

useCopilotChat

Use Cases

Usage

Return Values

Parameters

On this page

useCopilotChat

Use Cases

Usage

Return Values

Parameters

On this page