# @chatlychat/sdk-js 中文文档

规范地址：https://npmcn.com/package/%40chatlychat/sdk-js/

版本：0\.26\.2
npm 元数据更新时间：2026-11-05T20:04:42.234Z
中文译文更新时间：2026-11-09T11:50:10.272Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40chatlychat/sdk-js
原文对照：https://npmcn.com/package/%40chatlychat/sdk-js/?lang=original
项目主页：https://github.com/chatlychat/chatly-sdk-js#readme
源码仓库：https://github.com/chatlychat/chatly-sdk-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：266 kB，56 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：0 个
- 首次发布：2026-10-12T16:54:48.031Z
- 最新版本发布：2026-11-05T20:04:41.866Z
- 近 30 天下载量：4606（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 31 个）

## 中文简介

Chartly的浏览器SDK——识别访客,射击CDP事件,控制部件,无头地运行对话,并打入窗口. 聊天时.

## 安装

```sh
npm install @chatlychat/sdk-js
```

也可以使用：`pnpm add @chatlychat/sdk-js`、`yarn add @chatlychat/sdk-js`、`bun add @chatlychat/sdk-js`

## README

# @chatlychat/sdk-js (英语)

Chatly 平台的浏览器 SDK: 控制页面中的部件, 识别 访问者、射击CDP活动以及——无头无尾——列表对话、发送 留言和订阅答复,但根本不显示我们的UI.

> **两分之一,只有一块位于全球元件上.** 部件控制 方法(单位:千美元)`open`, (中文(简体) ), `close`, (中文(简体) ), `identify`, (中文(简体) ), `track`)也可用,无 软件包-装入部件片段并调用 `window.Chatly`。 。 。 . 无头之半 (:`listConversations`, (中文(简体) ), `listMessages`, (中文(简体) ), `send`, (中文(简体) ), `uploadFile`, (中文(简体) ), `subscribe`, (中文(简体) ), `rate`, (中文(简体) ), `emailTranscript`已经 **没有** 全球和 需要此软件包或直接调用已记录的 REST 端点.

```bash
npm install @chatlychat/sdk-js
# or
pnpm add @chatlychat/sdk-js
```

## 快开始

```ts
import { Chatly } from '@chatlychat/sdk-js';

// The constructor is PRIVATE. `init` is the only way in.
const chatly = Chatly.init({ publicId: 'ch_web_0192…' });

await chatly.identify({ externalId: 'user_42', name: 'Ada', userHash: '…' });
const { conversationId } = await chatly.startConversation('Hello');
await chatly.send(conversationId, 'and one more thing');
```

## `Chatly.init(options)`

| 选项 | 类型 | 默认 | 页:1 |
| --- | --- | --- | --- |
| `publicId` | `string` | —— 说 | (原始内容存档于2018-10-21). web 频道公众号 从Dashboard 频道. |
| `apiUrl` | `string?` | `https://api.chatlychat.com` | 另一个Chartly环境,或测试服务器在您自己的套房. |
| `realtimeUrl` | `string?` | 服务器报告 | 袜子。 IO 主机为 `subscribe()`。只为服务器无法知道的主机. |

## 方法

部件控制- 这些镜像 `window.Chatly` 并需要页面上的部件 :

-   `open()` 编号 : `close()`

访客身份和分析:

-   `identify(input)` → `{ contactId }`。通过 `userHash` 以获得身份 **已核实**没有它,来访者就无法核实,需要工具 被证明的身份会拒绝.
-   `track(name, properties?)`

无头对话表面——不需要部件 :

-   `startConversation(body, attachments?)` → `{ conversationId }`
-   `send(conversationId, body, attachments?)`
-   `listConversations(limit = 20)`
-   `unreadCount()` → `number`代理和机器人消息 这个访客没有 读取,横穿他们的线程——自定义发射机的徽章显示的数字. 这个 花费了请求,所以它是一个呼叫而不是财产.
-   `listMessages(conversationId, limit = 50)`
-   `subscribe(conversationId, handlers, options?)` → `Subscription`使用 当它能和落回投票时,推接接头,所以它继续工作 无法打开 WebSocket.
-   `uploadFile(file)` → `VisitorAttachment`,以传递给 `send` 或者说 `startConversation`
-   `rate(conversationId, score, comment?)`
-   `emailTranscript(conversationId, email)`

## 键入 `window.Chatly` (装载器片段的全局)

如果将部件嵌入两行加载器片段,然后从中驱动 您自己的类型脚本, 此软件包也是 **类型声明** 联 合 国 全球。 安装为 dev 依赖性 —— 您不需要运行时代码 并从中导入任何类型。 导入增强功能 `Window` 整个节目, 所以没有 `/// <reference>` 行与无 `tsconfig` `types` 添加条目:

```ts
import type { ChatlyGlobal, InitOptions } from '@chatlychat/sdk-js';

const options: InitOptions = { publicId: 'acme-web', theme: { primaryColor: '#4f46e5' } };
window.Chatly?.init(options);
```

从 `0.2.0`数字 : `ChatlyApi`, (中文(简体) ), `ChatlyGlobal`, (中文(简体) ), `InitOptions`, (中文(简体) ), `WidgetTheme`, (中文(简体) ), `WidgetBehavior`, (中文(简体) ), `WidgetCopy`, (中文(简体) ), `WidgetQuickLink`, (中文(简体) ), `WidgetQuip`, (中文(简体) ), `WidgetIdentity`, (中文(简体) ), `SessionSnapshot`, (中文(简体) ), `ChatlyEventName`, (中文(简体) ), `ChatlyEventHandler`, (中文(简体) ), `OpenRequest`, (中文(简体) ), `StartConversationRequest`, (中文(简体) ), `SetContextInput`, (中文(简体) ), `ReportActionInput`从 `0.4.0`数字 : `MountOptions`这些是部件的 因此,没有复制件送交 漂来漂去.

### 第二段,线性视图`mount`(中文(简体) )

`ChatlyApi` 声明 `mount(opts: MountOptions)` 财务报告和审定财务报表 `unmount(el)` - 一个秒 部件视图,在你的页面中,在发射器旁边。 这是在部件的 全球和 **没有** 编辑 `Chatly` 分类:视图由 部件捆绑,所以它需要页面上的捆绑.

```ts
import type { MountOptions } from '@chatlychat/sdk-js';

const view: MountOptions = { el: '#shop-assistant', publicId: 'ch_web_shop…' };
window.Chatly?.('mount', view);
// later, when your route unmounts
window.Chatly?.('unmount', '#shop-assistant');
```

`MountOptions` 实值 `InitOptions` 与 `mountTo` 改为 `el` 财务报告和审定财务报表 `publicId` 被选择。 与主部件共享的视图是什么 没有,为什么没有 `botSlug`: 见 [网络频道指南](https://chatlychat.com/guides/channel-web#an-inline-assistant-and-the-support-launcher)。 。 。 .

`Window.Chatly` 输入为完整的 API,因为 `window.Chatly.identify(...)` 作为类型错误对每个人都是没用的。 之间到底有什么 片段正在运行, 捆绑到达只是排队 **函数** 已安装的片段 。 从可以提早运行的代码,使用可调用 形式,即片段队列和捆绑重放的- `window.Chatly?.('identify', { externalId })` - 或等待着 `Chatly.on('ready', …)`。 。 。 .

## 已签名的页面上下文

`setContext` 实值 **没有** 在SDK上,它是在部件本身的全球。 见 页:1 [网络频道指南](https://chatlychat.com/guides/channel-web) 联 合 国 电话和 [身份核查](https://chatlychat.com/docs/identity-verification) 如何铸造签名 `contextToken`。 。 。 .

## 此 README 用于记录不存在的 API

为了记录在案,因为它可能已经复制:它描述了 `new Chatly({ channelPublicId, baseUrl, widgetSelector, locale })`附加时 `toggle()`, (中文(简体) ), `on()`, (中文(简体) ), `destroy()` 财务报告和审定财务报表 `send(body)`。 。 。 . **这些都不存在.** 这个 构造器是私有的, 选项名称是 `publicId` 编号 : `apiUrl` 编号 : `realtimeUrl`,以及 `send` 先找个人谈谈 已更正 2026-10-12 反对 `src/index.ts`。 。 。 .

* * *

## 关于此寄存器

这是一个 **镜像**。 。 。 . `@chatlychat/sdk-js` 由私人独身建筑 其余的 月台的迁移和合同检查现场直播 无法直接合并, 但补丁仍然是获得东西最快的方法 固定了,我们会把它 与归属.

您可以在这里做什么: 读取源代码, 运行测试, 打开一个问题, 或打开一个 PR 并且我们将把diff当作提案.

未镜像 : src/无头- message-parity.spec.ts, src/icon-names-parity.spec.ts - 仍然在此重现的类别 与单列波的原作相匹配,这仅仅是其中的一个有意义的主张. 他们 继续跑.

问题: [https://github.com/chatlychat/chatly-sdk-js/issues (中文(简体) )](https://github.com/chatlychat/chatly-sdk-js/issues) \* 文件: [https://chatlychat.com/docs (中文(简体) )](https://chatlychat.com/docs)

## 常见问题

### @chatlychat/sdk-js 是什么？

Chartly的浏览器SDK——识别访客,射击CDP事件,控制部件,无头地运行对话,并打入窗口\. 聊天时\.

### 如何安装 @chatlychat/sdk-js？

在项目目录运行 npm install @chatlychat/sdk-js，或使用 pnpm add / yarn add / bun add。

### @chatlychat/sdk-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @chatlychat/sdk-js 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @chatlychat/sdk-js 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chatlychat/sdk-js 可以商用吗？

@chatlychat/sdk-js 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @chatlychat/sdk-js 的下载量有多少？

根据 npm 官方下载统计，@chatlychat/sdk-js 在 2026/10/10 – 2026/11/08 这 30 天内被下载 4,606 次，日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @chatlychat/sdk-js 还在维护吗？

最新版本 0\.26\.2 发布于 2026/11/06（3 天前）；至今共发布 31 个版本，其中过去 12 个月发布了 31 个；首次发布于 2026/10/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。