> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-chat-widget-to-a-character.md).

# 向角色添加聊天小部件

将 Convai 聊天小部件添加到 Convai Embody 角色中，这样用户就可以通过该角色已建立的连接输入并与它对话。

在 Convai Embody 角色旁添加 Convai Web SDK 聊天组件，让用户可以通过文字和语音与角色交谈。在 React 应用中渲染角色后，请参阅本页。完成后，通过组件发送的消息会收到语音回复，角色的口型会与语音同步。

### 前提条件

* 使用以下组件渲染的角色： `ConvaiCharacter` 或 `CharacterModel`。请参阅 [将 3D 角色添加到 React 应用](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-3d-character-to-a-react-app.md).

### 从角色中获取客户端

角色持有连接。 `onReady` 会在角色的身体加载完成且连接已建立后将角色传递给你，而 `character.client` 就是该连接对应的 `ConvaiClient`。请将它存储在画布外部的状态中，因为该组件属于 DOM，无法在 3D 场景中渲染。

### 渲染聊天组件

将角色自己的客户端传递给 `ConvaiWidget`。聊天组件会订阅该客户端，因此聊天和角色共用同一个连接。 `ConvaiClient` 来自 `@convai/embody/react`; `ConvaiWidget` 而聊天 UI 包则提供该组件，因此请将其（0.3.0 或更高版本）与 Convai Embody 一起安装：

```bash
npm install @convai/web-widget
```

{% code title="src/App.tsx" %}

```tsx
import { useState } from 'react'
import { ConvaiCharacter, type ConvaiClient } from '@convai/embody/react'
import { ConvaiWidget } from '@convai/web-widget/react'

export default function App({ token }: { token: string }) {
  const [client, setClient] = useState<ConvaiClient | null>(null)

  return (
    <>
      <ConvaiCharacter
        token={token}
        characterId="YOUR_CHARACTER_ID"
        onReady={(character) => setClient(character.client)}
      />
      {client && <ConvaiWidget convaiClient={client} />}
    </>
  )
}
```

{% endcode %}

{% hint style="warning" %}
不要使用 `useConvaiClient`来创建聊天组件的客户端。该 Hook 会创建另一个 `ConvaiClient`，从而建立第二个连接：聊天组件会与一个会话交互，而角色的口型同步使用另一个会话，因此角色不会发声。
{% endhint %}

### 验证聊天组件

在聊天组件中输入一条消息并发送。

{% hint style="success" %}
回复会显示在聊天组件中，角色会说出回复，且角色的嘴部会随音频同步动作。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/afcae56dd5bee11232aa7e5af42d7608c0a2f044" %}
[React API 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/react-api-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/eb896fafee38ed6296228fce9cc8190b93be03b8" %}
[ConvaiWidget 组件参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/convaiwidget.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-embody/add-a-chat-widget-to-a-character.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
