> 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 角色。

npm 上发布的 Convai Web SDK，名为 `@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="/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="/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="/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="/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>使用 blendshapes 驱动面部动画</strong><br>流式传输唇形同步帧，并将其应用到 3D 角色的变形目标。</td><td><a href="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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="/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（旧版）](/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.
