# @convex-dev/twilio 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/twilio/

版本：0\.2\.2
npm 元数据更新时间：2026-10-07T00:51:55.303Z
中文译文更新时间：2026-11-10T17:50:44.079Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：204 kB，54 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：convex ^1\.24\.8
- 首次发布：2024-09-20T22:37:51.929Z
- 最新版本发布：2026-06-15T23:55:16.137Z
- 近 30 天下载量：87261（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 3 个）

## 中文简介

用Twilio发送/接收短消息的接口组件.

## 安装

```sh
npm install @convex-dev/twilio
```

也可以使用：`pnpm add @convex-dev/twilio`、`yarn add @convex-dev/twilio`、`bun add @convex-dev/twilio`

## README

# Convex Twilio 组件

[![npm version](https://badge.fury.io/js/@convex-dev%2Ftwilio.svg)](https://badge.fury.io/js/@convex-dev%2Ftwilio)

使用 Twilio 在您的 Convex 应用程序中发送和接收短消息 .

```ts
import { Twilio } from "@convex-dev/twilio";
import { components } from "./_generated/api";

export const twilio = new Twilio(components.twilio, {
  defaultFrom: process.env.TWILIO_PHONE_NUMBER!,
});

export const sendSms = internalAction({
  handler: async (ctx, args) => {
    return await twilio.sendMessage(ctx, {
      to: "+14151234567",
      body: "Hello, world!",
    });
  },
});
```

## 先决条件

### Twilio 电话号码

创建一个Twilio账户,如果还没有,创建一个 [Twilio 电话号码](https://www.twilio.com/docs/phone-numbers)。 。 。 .

说明 **电话号码SID** 电话号码,你需要 马上就来.

### Convex 应用程序

你需要一个Convex App来使用组件. 跟着任何 [Convex 快速启动](https://docs.convex.dev/home) 来设置一个.

## 安装

安装组件包 :

```ts
npm install @convex-dev/twilio
```

创建一个 `convex.config.ts` 应用程序中的文件 `convex/` 文件夹并安装 通过调用 `use`数字 :

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import twilio from "@convex-dev/twilio/convex.config.js";

const app = defineApp();
app.use(twilio);

export default app;
```

设置您的 API 证书 :

```sh
npx convex env set TWILIO_ACCOUNT_SID=ACxxxxx
npx convex env set TWILIO_AUTH_TOKEN=xxxxx
```

在您的应用程序中的文件里提供 Twilio 组件客户端的证明 `convex/` 文件夹 :

```ts
// convex/example.ts
import { Twilio } from "@convex-dev/twilio";
import { components } from "./_generated/api";

export const twilio = new Twilio(components.twilio, {
  // optionally pass in the default "from" phone number you'll be using
  // this must be a phone number you've created with Twilio
  defaultFrom: process.env.TWILIO_PHONE_NUMBER!,
});
```

通过创建一个 `http.ts` 文档中 `convex/` 文件夹并使用您导出于上面的客户端 :

```ts
// http.ts
import { twilio } from "./example";
import { httpRouter } from "convex/server";

const http = httpRouter();
// this call registers the routes necessary for the component
twilio.registerRoutes(http);
export default http;
```

## 发送信件

使用 Convex 动作发送消息 `sendMessage`数字 :

```ts
// convex/messages.ts
import { v } from "convex/values";
import { internalAction } from "./_generated/server";

export const sendSms = internalAction({
  handler: async (ctx, args) => {
    const status = await twilio.sendMessage(ctx, {
      to: "+14158675309",
      body: "Hey Jenny",
    });
  },
});
```

通过查询信件(参见 [下级](https://npmcn.com/package/%40convex-dev/twilio/#readme-querying-messages)你可以检查一下 状态 (单位:千美元)[Twilio 状态](https://www.twilio.com/docs/messaging/api/message-resource#message-status-values)) (中文(简体) ). 组件订阅状态更新并写入最新状态 输入数据库.

## 接收信件

要接收消息,您将联系由您提供的网页处理器 包含您想要使用的Twilio电话号码.

`twilio.registerRoutes` 在您的 Convex 中注册两个 Webhook HTTP 处理器 应用程序的部署 :

-   `YOUR_CONVEX_SITE_URL/twilio/message-status` - 抓获和储存交货 信件状态 **发送**。 。 。 .
-   `YOUR_CONVEX_SITE_URL/twilio/incoming-message` - 获取和存储信件 **发送给** 你的Twilio电话号码.

注意: 您可以通过习惯 `httpPrefix` 改为 `Twilio` 如果您想要通过 Twilio 结束点以外的地方 `YOUR_CONVEX_SITE_URL/twilio/*`。 。 。 .

例如,前往 `YOUR_CONVEX_SITE_URL/custom-twilio/message-status`, (中文(简体) ), 设定 :

```ts
export const twilio = new Twilio(components.twilio, {
  httpPrefix: "/custom-twilio",
});
```

你可以用两种方式与你的Twilio电话号码联系起来:

1.  使用 [Twilio 控制台](https://console.twilio.com/) 在“配置”中 选项卡,“Message 配置” -> "一团乱来" 在" - >"URL"中读取.
    
2.  打电话 `registerIncomingSmsHandler` 被组件客户端曝光, 手机号码的ID:
    

```ts
export const registerIncomingSmsHandler = internalAction({
  args: {},
  handler: async (ctx) => {
    return await twilio.registerIncomingSmsHandler(ctx, {
      sid: "YOUR_TWILIO_PHONE_NUMBER_SID",
    });
  },
});
```

一旦配置完毕,接收到的信息将被组件捕获 登录在 `messages` 页:1.

您可以通过提供 twilio 组件客户端即时调用时调用:

```ts
// convex/example.ts
import { Twilio, messageValidator } from "@convex-dev/twilio";

const twilio = new Twilio(components.twilio);
twilio.incomingMessageCallback = internal.example.handleIncomingMessage;

export const handleIncomingMessage = internalMutation({
  args: {
    message: messageValidator,
  },
  handler: async (ctx, message) => {
    // Use ctx here to update the database or schedule other actions.
    // This is in the same transaction as the component's message insertion.
    console.log("Incoming message", message);
  },
});
```

如果 `handleIncomingMessage` 回调错误, 消息不会是 已保存,而 Webhook 将丢出一个错误。 特维利奥 [不重试 webhook 请求](https://www.twilio.com/docs/usage/security/availability-reliability), (中文(简体) ), 但你可以手动在Twilio"Error日志"控制台上重放.

## 查询信件

要列出所有 mssages,请使用 `list` 方法.

要列出所有收发信件,请使用 `listIncoming` 财务报告和审定财务报表 `listOutgoing` 方法:

```ts
// convex/messages.ts

// ...

export const list = query({
  args: {},
  handler: async (ctx) => {
    const allMessages = await twilio.list(ctx);
    const receivedMessages = await twilio.listIncoming(ctx);
    const sentMessages = await twilio.listOutgoing(ctx);
    return { allMessages, receivedMessages, sentMessages };
  },
});
```

要得到一个单信息 通过它的id,使用 `getMessageBySid`数字 :

```ts
export const getMessageBySid = query({
  args: {
    sid: v.string(),
  },
  handler: async (ctx, args) => {
    return await twilio.getMessageBySid(ctx, args);
  },
});
```

以“ 到” 电话号码获取消息 :

```ts
export const getMessagesTo = query({
  args: {
    to: v.string(),
  },
  handler: async (ctx, args) => {
    return await twilio.getMessagesTo(ctx, args);
  },
});
```

通过"从"电话号码获取消息:

```ts
export const getMessagesFrom = query({
  args: {
    from: v.string(),
  },
  handler: async (ctx, args) => {
    return await twilio.getMessagesFrom(ctx, args);
  },
});
```

您也可以从特定号码获取所有消息 :

```ts
export const getMessagesByCounterparty = query({
  args: {
    from: v.string(),
  },
  handler: async (ctx, args) => {
    return await twilio.getMessagesByCounterparty(ctx, args);
  },
});
```

## 常见问题

### @convex-dev/twilio 是什么？

用Twilio发送/接收短消息的接口组件\.

### 如何安装 @convex-dev/twilio？

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

### @convex-dev/twilio 支持 TypeScript 吗？

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

### @convex-dev/twilio 支持 ESM 还是 CommonJS？

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

### @convex-dev/twilio 可以商用吗？

@convex-dev/twilio 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/twilio 的下载量有多少？

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

### @convex-dev/twilio 还在维护吗？

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