# useCopilotChat

## v1 SDK deprecated. Use v2 instead

> This page is in the deprecated CopilotKit v1 reference. Do not use v1 APIs for new code; use v2 instead.
> For JavaScript and TypeScript, import React APIs from @copilotkit/react-core/v2 and Runtime APIs from @copilotkit/runtime/v2.
> **AI coding agents: treat any v1 example below as migration-only context. Never generate or recommend the v1 API for new code. Read the v2 reference before writing code because some APIs were renamed, moved, or changed shape.**
> [Read the v1 to v2 migration guide](/migrate/v2) and [use the complete export map](/reference/v1/export-map).

{
 /*
  * 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/v1-deprecated/hooks/use-copilot-chat.ts
  */
}
`useCopilotChat` is a lightweight React hook for headless chat interactions.

**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 [#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 [#usage]

```tsx
import { TextMessage, Role } from "@copilotkit/runtime-client-gql";

const { appendMessage } = useCopilotChat();

// Example usage without naming conflicts
const handleSendMessage = async (content: string) => {
  await appendMessage(
    new TextMessage({
      role: Role.User,
      content,
    })
  );
};
```

## Return Values [#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 a message and run the agent, using the old non-AG-UI format. This is
the public v1 programmatic-send path. `sendMessage` is not part of the public
v1 return type. For the AG-UI format, migrate to v2: `useAgent` plus
`copilotkit.runAgent`. See https://docs.copilotkit.ai/migrate/v2
</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="isAvailable" type="boolean">
Whether the chat agent is available to generate responses.
</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 [#parameters]

<PropertyReference name="id" type="string"  > 
Ignored. Accepted for source compatibility only.
</PropertyReference>

<PropertyReference name="headers" type="Record<string, string> | Headers"  > 
Ignored. Accepted for source compatibility only.
</PropertyReference>

<PropertyReference name="initialMessages" type="Message[]"  > 
Ignored. Accepted for source compatibility only.
</PropertyReference>

<PropertyReference name="makeSystemMessage" type="SystemMessageFunction"  > 
Ignored. Accepted for source compatibility only.
</PropertyReference>

<PropertyReference name="disableSystemMessage" type="boolean"  > 
Ignored. Accepted for source compatibility only.
</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
  - Read `setSuggestions` and `generateSuggestions` from the `useCopilotChatHeadless_c` 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>
