> 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-web-sdk.md).

# Convai Web SDK

查找 Convai Web SDK 的设置指南、功能操作方法和 API 参考，它通过语音和文本将网页应用连接到 Convai 角色。

Convai Web SDK 在 npm 上以 `@convai/web-sdk`的名称发布，可将网页连接到 Convai 角色，实现实时语音和文本对话，并可选启用摄像头、屏幕共享、口型同步、动作和情绪。它同时提供 React 绑定、无框架客户端，以及适用于这两种方式的预构建聊天组件。这些页面介绍 <code class="expression">space.vars.web\_sdk\_version</code>.

{% embed url="<https://youtu.be/fK8R0SzuvNI>" %}
使用 Convai Web SDK、three.js 和 React 构建基于浏览器的对话式虚拟形象。
{% endembed %}

### 从这里开始

快速入门指南将带你在 React 中创建第一个对话。两个入门页面分别介绍各自方案的安装和聊天组件；请选择与你的应用相符的页面。

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Web SDK 快速入门</strong><br>从 React 连接到一个角色、发送消息并读取其回复。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/quickstart.md">Web SDK 快速入门</a></td></tr><tr><td><strong>React 入门</strong><br>安装软件包、添加聊天组件，并启用摄像头和屏幕共享。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react.md">开始使用 React</a></td></tr><tr><td><strong>原生 TypeScript 入门</strong><br>创建一个无框架客户端，并挂载原生聊天组件。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/vanilla-typescript.md">开始使用原生 TypeScript</a></td></tr></tbody></table>

### 构建使用场景

每个使用场景都会逐步整合多项功能，构建一个完整应用。

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>构建网站助手</strong><br>在每个页面添加一个角色，让它了解访客当前所在位置，并能导航、突出显示内容和填写表单。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/use-cases/website-assistant.md">构建网站助手</a></td></tr></tbody></table>

### 添加功能

每个功能页面都会介绍一项功能的配置和客户端调用方式，同时涵盖 React 和原生代码。

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>使用混合形状驱动面部动画</strong><br>流式传输口型同步帧，并将其应用于 3D 角色的变形目标。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/lipsync-and-blendshape.md">使用 blendshape 驱动面部动画</a></td></tr><tr><td><strong>处理角色动作</strong><br>接收语义动作，或运行客户端工具并返回其结果。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/actions.md">处理角色动作</a></td></tr><tr><td><strong>使用角色情绪</strong><br>读取角色的情绪并设置其心境状态。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/emotions.md">使用角色情绪</a></td></tr><tr><td><strong>在运行时更新角色上下文</strong><br>在会话期间发送场景状态、模板键和文件。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/dynamic-context.md">在运行时更新角色上下文</a></td></tr><tr><td><strong>使用长期记忆</strong><br>让角色在不同会话中记住每个人，并管理这些记忆。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/long-term-memory.md">使用长期记忆</a></td></tr><tr><td><strong>使用身份验证令牌连接</strong><br>将 API 密钥保存在服务器上，并使用令牌连接浏览器。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/auth-tokens.md">使用认证令牌连接</a></td></tr><tr><td><strong>处理错误和断开连接</strong><br>区分故障、断开连接原因和确认消息，并重新连接。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/error-handling.md">处理错误和断开连接</a></td></tr><tr><td><strong>选择传输方式</strong><br>选择 SSE、WebRTC 或 WebSocket，也可以将 SSE 聊天与实时语音模式结合使用。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/choose-a-transport.md">选择一种传输方式</a></td></tr><tr><td><strong>通过 SSE 传输方式聊天</strong><br>通过 HTTP 流式传输文本和可选语音，无需 WebRTC 或麦克风。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/sse-transport.md">通过 SSE 传输聊天</a></td></tr><tr><td><strong>使用 WebSocket 传输方式</strong><br>通过 WebSocket 而非 WebRTC 连接。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/websocket-transport-layer.md">使用 WebSocket 传输层</a></td></tr><tr><td><strong>连接到自托管部署</strong><br>将 SDK 指向你自己的主机，而不是 api.convai.com。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/self-hosted-deployments.md">连接到自托管部署</a></td></tr><tr><td><strong>将角色语音静音</strong><br>让听众听不到角色的声音，同时角色仍继续说话。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/mute-the-characters-voice.md">将角色的声音静音</a></td></tr><tr><td><strong>在一个房间中托管多个角色</strong><br>连接角色列表、切换应答角色，并实时更改成员（测试版）。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/multi-character-rooms.md">在一个房间中托管多个角色</a></td></tr><tr><td><strong>连接到角色版本</strong><br>使用草稿、最新发布版本或标签，并管理版本（测试版）。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/character-versioning.md">连接到角色版本</a></td></tr><tr><td><strong>连接到已发布的文本聊天</strong><br>通过发布授权运行无需凭据的纯文本聊天。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/published-text-chat.md">连接到已发布的文本聊天</a></td></tr><tr><td><strong>呈现链接和链接预览</strong><br>显示角色发送的链接，并可选择显示网站卡片。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/link-previews.md">渲染链接和链接预览</a></td></tr></tbody></table>

### 查阅 API

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>ConvaiClient 参考</strong><br>客户端上的所有属性、方法和控制接口。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/vanilla-typescript/convaiclient-core-api.md">ConvaiClient 参考</a></td></tr><tr><td><strong>配置与类型参考</strong><br>所有连接选项、包入口点和共享类型。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/vanilla-typescript/best-practices-and-type-definitions.md">配置和类型参考</a></td></tr><tr><td><strong>Web SDK 事件参考</strong><br>客户端发出的所有事件及其负载。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/event-reference.md">Web SDK 事件参考</a></td></tr><tr><td><strong>读取原始传输消息</strong><br>通过 rawMessage 检查每种传输上的所有传入帧。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/raw-messages.md">读取原始传输消息</a></td></tr><tr><td><strong>useConvaiClient 钩子参考</strong><br>React 钩子返回的内容，以及哪些字段会触发重新渲染。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/react/useconvaiclient-hook.md">useConvaiClient Hook 参考</a></td></tr></tbody></table>

该 SDK 并非旧版的 `convai-web-sdk` 包；该包的文档位于 [Convai Web SDK（旧版）](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk-1.md)]。两者的 API 不同，因此为其中一个编写的代码无法在另一个中运行。


---

# 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-web-sdk.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.
