> 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/vanilla-typescript.md).

# 原生 TypeScript

## 安装与快速开始（原生 TypeScript）

## 安装

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

从原生入口导入：

```ts
import { ConvaiClient } from '@convai/web-sdk/vanilla';
```

***

## 快速入门

原生 API 仅暴露一个类， `ConvaiClient`，它负责处理连接、音频、视频和消息。

### 基础示例

```ts
import { ConvaiClient } from '@convai/web-sdk/vanilla';

async function main() {
  const client = new ConvaiClient();

  client.on('stateChange', (state) => {
    console.log('智能体状态：', state.agentState);
  });

  client.on('message', (message) => {
    console.log('消息：', message.content);
  });

  await client.connect({
    apiKey: '你的-api-key',
    characterId: 'your-character-id',
    endUserId: 'user-uuid', // 可选：启用记忆和分析
  });

  client.sendUserTextMessage('你好！');
}

main().catch(console.error);
```

***

### 可选的视频支持

```ts
await client.connect({
  apiKey: '你的-api-key',
  characterId: 'your-character-id',
  enableVideo: true,
  startWithVideoOn: false
});
```

***

### 关于 endUserId

* 提供它以启用 **记忆**, **会话连续性**，以及 **分析**.
* 如果你想要无状态会话，请省略。

***

#### 使用原生 Widget（可选）

如果你想在原生 TypeScript/JavaScript 中使用现成的 UI，可以使用这个 widget 辅助工具：

```ts
import {
  ConvaiClient,
  createConvaiWidget,
} from "@convai/web-sdk/vanilla";

const client = new ConvaiClient({
  apiKey: "your-api-key",
  characterId: "your-character-id",
});

const widget = createConvaiWidget(document.body, {
  convaiClient: client,
  showVideo: true,
  showScreenShare: true,
});

// 之后，在清理时：
widget.destroy();
```

原生 widget 的行为与 React widget 类似：

* 在用户首次交互时自动连接
* 管理音频采集和播放
* 如果已启用，可显示视频和屏幕共享控件


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/web-plugins/convai-web-sdk/vanilla-typescript.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.