# @getdial/chat-sdk-adapter 中文文档

规范地址：https://npmcn.com/package/%40getdial/chat-sdk-adapter/

版本：0\.2\.0
npm 元数据更新时间：2026-07-13T13:11:42.050Z
中文译文更新时间：2026-11-16T06:01:15.229Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40getdial/chat-sdk-adapter
原文对照：https://npmcn.com/package/%40getdial/chat-sdk-adapter/?lang=original
项目主页：https://getdial.ai/
源码仓库：https://github.com/GetDial-AI/chat-sdk-adapter

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

- 包体积（解压后）：75.8 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- peer 依赖：chat ^4\.20\.0
- 首次发布：2026-07-05T10:07:52.234Z
- 最新版本发布：2026-07-13T13:11:41.827Z
- 近 30 天下载量：74241（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

把一个拨号接入一个Chat SDK bot——同一个处理器会回答短消息,MMS,iMessage,以及输入的声音.

## 安装

```sh
npm install @getdial/chat-sdk-adapter
```

也可以使用：`pnpm add @getdial/chat-sdk-adapter`、`yarn add @getdial/chat-sdk-adapter`、`bun add @getdial/chat-sdk-adapter`

## README

# @ getdial/ chat- sdk- 适应器

把真正的电话号码输入你的Chat SDK机器人 一样 `onNewMention` 回答Slack,Teams,或Discord的处理器现在也回答短信,MMS,iMessage,以及进站语音电话——通过拨号通过电话发送回信.

```bash
npm install @getdial/chat-sdk-adapter chat
```

```typescript
import { Chat } from "chat";
import { createDialAdapter } from "@getdial/chat-sdk-adapter";

const chat = new Chat({
  adapter: createDialAdapter(),  // reads DIAL_* env vars; overridable — see Options
  onNewMention: async ({ message, reply }) => {
    await reply(`heard you: ${message.text}`);
  },
});

// Bind to whatever HTTP framework you use:
app.post("/webhook/dial", (req) => chat.webhooks.dial(req));
```

获取拨号API 密钥和电话号码 ID [https://getdial.ai (英语)](https://getdial.ai/)。指该数字的 Webhook 订阅在上方端点.

## 适配器携带的

| 方向 | 频道 | 文本 | 媒体 |
| --- | --- | :-: | --- |
| 入境 | 简讯 | ✅ | —— 说 |
| 入境 | 管理事务 | ✅ | qq (图像/ 视频/ 音频/ 文件) |
| 入境 | iMessage 图像 | ✅ | ✅ |
| 入境 | 语音呼叫 | (作为记录) | —— 说 |
| 出境 | 短消息/短消息/短消息/短消息 | ✅ | QQ( 通过附件 URL) |

## 配置

`createDialAdapter(config?)` 读取字段时的环境。 明确的价值观总是赢得.

| 外地 | 新闻 var | 需求 | 这是什么 |
| --- | --- | :-: | --- |
| `apiKey` | `DIAL_API_KEY` | ✅ | 拨号 API 密钥( O)`sk_live_…`从仪表板上铸造. |
| `fromNumberId` | `DIAL_FROM_NUMBER_ID` | ✅ | 拨打机器人应该发送的电话号码的号码 **从**。 。 。 . |
| `webhookSecret` | `DIAL_WEBHOOK_SECRET` | 专业 | 在创建 Webhook 订阅时签名秘密拨号 。 设定后,将对照 `X-Dial-Signature`; 当未设置时, 校验会被跳过( 仅保留). |
| `apiBaseUrl` | `DIAL_API_URL` |  | 覆盖 Dial API 主机 。 默认为 `https://api.getdial.ai`。 。 。 . |
| `botName` | `BOT_USERNAME` |  | 显示用于机器人的 Chat SDK 名称 。 默认为 `"bot"`。 。 。 . |
| `logger` | —— 说 |  | 聊天SDK `Logger` 举个例子 默认为 `ConsoleLogger("info").child("dial")`。 。 。 . |

## Webhook活动

在您交接的端点标出拨号 Webhook 订阅 `chat.webhooks.dial`。四个事件类型被识别(信封形状镜像 Dial 自己的发射器):

| 活动 | 回应 |
| --- | --- |
| `message.received` | 转发给机器人作为聊天信息. 媒体项目成为 Chat SDK 附件( 图像 / 视频 / 音频 / 文件, 按键关闭) `contentType`) (中文(简体) ). |
| `call.ended` (输入) | 吞了 - 200 OK,没有转发。 波茨只将语音视为后来的录音 `call.transcribed`一个"呼叫结束"的占位符 将保持查特SDK每端锁 并饿死真正的记录片事件。 非常短的电话,从没有记录 所以绝对不会浮出水面. |
| `call.ended` (境外) | 投出——200 OK,没有转发. 适配器表面仅限入地. |
| `call.transcribed` | 通过 `@getdial/sdk.getCall()`。只有在 `direction === "inbound"`。 。 。 . |
| `webhook.ping` | `200 OK`未转发——这是Dial的仪表板"试送"按钮. |

其他的都会得到回答 `200 OK` 并且被忽略,所以未来的"拨号"事件类型不会在升级前就破坏集成.

### 签字核查

何时 `webhookSecret` 每个请求必须携带:

```
X-Dial-Signature: t=<unix_seconds>,v1=<hex-hmac-sha256(secret, `${t}.${rawBody}`)>
```

驳回案件(全部) `401`:

| 判决 | 何时 |
| --- | --- |
| `missing` | 没有 `X-Dial-Signature` 问讯头. |
| `malformed` | 标题缺少 `t=` 或者说 `v1=`,或 `t=` 不是一个数字. |
| `stale` | `abs(now - t)` 超过5分钟。 重放保护. |
| `mismatch` | 重算的 HMAC 不等于 `v1`,或长度不同。 常时相较. |

结构无效的 JSON 或无信封 `type`返回 `400`。 。 。 .

## 线索

这条线是 **电话号码对数** -你的电话号码和同伴的:

```
dial:{yourDialNumber}:{peerNumber}
```

每一个不同的对 是一个不同的线。 Chat SDK的每行读状态(conversation history,上下文)是被范围化的每行,所以同时进行的对话不会互相泄露.

## 设计说明

-   **`@getdial/sdk` 在引擎盖下.** 出站发送和收发记录通过官方节点SDK;没有手卷HTTP.
-   **节点的 `crypto` 签字.** `createHmac` + 键 `timingSafeEqual`,与精确原始的"拨号"服务器标志相匹配.
-   **软件包为只使用无害环境管理,TypeScript-first.** 需要节点18+.
-   **适配器中没有商业逻辑.** 这是一个运输shim——你的机器人逻辑完全生活在Chat SDK处理器中.

## 链接

-   拨号 : [(原始内容存档于2017-09-21) (英语). getdial.ai](https://getdial.ai/) • 妇女 [文档](https://docs.getdial.ai/)
-   聊天 SDK : [聊天- sdk.dev](https://chat-sdk.dev/)

## 常见问题

### @getdial/chat-sdk-adapter 是什么？

把一个拨号接入一个Chat SDK bot——同一个处理器会回答短消息,MMS,iMessage,以及输入的声音\.

### 如何安装 @getdial/chat-sdk-adapter？

在项目目录运行 npm install @getdial/chat-sdk-adapter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：chat（^4\.20\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @getdial/chat-sdk-adapter 支持 TypeScript 吗？

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

### @getdial/chat-sdk-adapter 支持 ESM 还是 CommonJS？

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

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

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

### @getdial/chat-sdk-adapter 可以商用吗？

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

### @getdial/chat-sdk-adapter 的下载量有多少？

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

### @getdial/chat-sdk-adapter 还在维护吗？

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

