useCopilotChat - Copilotkit

{ /*

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>