---
title: "useCopilotChat"
---

{
 /*
  * ATTENTION! DO NOT MODIFY THIS FILE!
  * This page is auto-generated. If you want to make any changes to this page, changes must be made at:
  * packages/react-core/src/hooks/use-copilot-chat.ts
  */
}
`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.
 
<Callout title="Looking for fully headless UI?">
Get started with [useCopilotChatHeadless_c](https://docs.copilotkit.ai/reference/v1/hooks/useCopilotChatHeadless_c).
</Callout>
 
## 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
 
```tsx
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:
 
<PropertyReference name="visibleMessages" type="DeprecatedGqlMessage[]" deprecated>
Array of messages in old non-AG-UI format, use for compatibility only
</PropertyReference>
 
<PropertyReference name="appendMessage" type="(message: DeprecatedGqlMessage, options?) => Promise<void>" deprecated>
Append message using old format, use `sendMessage` instead
</PropertyReference>
 
<PropertyReference name="reloadMessages" type="(messageId: string) => Promise<void>">
Regenerate the response for a specific message by ID
</PropertyReference>
 
<PropertyReference name="stopGeneration" type="() => void">
Stop the current message generation process
</PropertyReference>
 
<PropertyReference name="reset" type="() => void">
Clear all messages and reset chat state completely
</PropertyReference>
 
<PropertyReference name="isLoading" type="boolean">
Whether the chat is currently generating a response
</PropertyReference>
 
<PropertyReference name="runChatCompletion" type="() => Promise<Message[]>">
Manually trigger chat completion for advanced usage
</PropertyReference>
 
<PropertyReference name="mcpServers" type="MCPServerConfig[]">
Array of Model Context Protocol server configurations
</PropertyReference>
 
<PropertyReference name="setMcpServers" type="(servers: MCPServerConfig[]) => void">
Update MCP server configurations for enhanced context
</PropertyReference>

## Parameters

<PropertyReference name="id" type="string"  > 
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.
</PropertyReference>

<PropertyReference name="headers" type="Record<string, string> | Headers"  > 
HTTP headers to be sent with the API request.
</PropertyReference>

<PropertyReference name="initialMessages" type="Message[]"  > 
Initial messages to populate the chat with.
</PropertyReference>

<PropertyReference name="makeSystemMessage" type="SystemMessageFunction"  > 
A function to generate the system message. Defaults to `defaultSystemMessage`.
</PropertyReference>

<PropertyReference name="disableSystemMessage" type="boolean"  > 
Disables inclusion of CopilotKit’s default system message. When true, no system message is sent (this also suppresses any custom message from <code>makeSystemMessage</code>).
</PropertyReference>

<PropertyReference name="suggestions" type="ChatSuggestions"  > 
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
</PropertyReference>

<PropertyReference name="onInProgress" type="(isLoading: boolean) => void"  > 

</PropertyReference>

<PropertyReference name="onSubmitMessage" type="(messageContent: string) => Promise<void> | void"  > 

</PropertyReference>

<PropertyReference name="onStopGeneration" type="OnStopGeneration"  > 

</PropertyReference>

<PropertyReference name="onReloadMessages" type="OnReloadMessages"  > 

</PropertyReference>

