@sadikkhan02/adapter-twilio
使用Twilio消息传递API的NotifyKit的全局SMS适配器。
这个包通过Twilio为NotifyKit提供企业短信传输。它实现了 SmsProvider 接口，支持字母数字发送者和消息服务sid，标准化E.164电话号码，并遵循 @sadikkhan02/test-utils 合同的测试。
安装
npm install @sadikkhan02/notifykit @sadikkhan02/adapter-twilio twilio
注意：
twilio被声明为外部对等依赖，以允许消费者控制SDK版本绑定和连接重用。
配置
环境变量
| 变量 | 要求 | 描述 |
|---|---|---|
TWILIO_ACCOUNT_SID | 是 | Twilio帐户SID (AC...） |
TWILIO_AUTH_TOKEN | 是 | Twilio授权令牌 |
TWILIO_FROM | 可选的* | E.164格式的默认发送人电话号码。 +15555550100） |
TWILIO_MESSAGING_SERVICE_SID | 可选的* | Twilio消息服务SID (MG...)进行自动发送人池 |
*要么 TWILIO_FROM 或者 TWILIO_MESSAGING_SERVICE_SID 必须配置（或在选项中提供）。
使用
import { createNotifier } from '@sadikkhan02/notifykit';
import { TwilioSmsProvider } from '@sadikkhan02/adapter-twilio';
const smsProvider = new TwilioSmsProvider({
accountSid: process.env.TWILIO_ACCOUNT_SID!,
authToken: process.env.TWILIO_AUTH_TOKEN!,
from: process.env.TWILIO_FROM, // e.g. +15555550100
// messagingServiceSid: process.env.TWILIO_MESSAGING_SERVICE_SID,
});
const notifier = createNotifier({
providers: {
sms: {
type: 'twilio',
adapter: smsProvider,
from: process.env.TWILIO_FROM,
},
},
});
// Register SMS template
notifier.registerTemplate(
'otp-verification',
'Your verification code is {{otp}}. Valid for 5 minutes. Do not share this code.',
);
// Enqueue SMS (returns immediately with jobId)
const { jobId } = await notifier.notify({
to: { phone: '+15555550199' }, // E.164 required
channels: ['sms'],
template: 'otp-verification',
data: { otp: '482910' },
});
// Start processing SMS queue
notifier.startWorker({ channels: ['sms'], concurrency: 5 });
错误分类和恢复
Twilio适配器将结构化的Twilio错误代码直接映射为标准化的 ProviderResult 对象:
| Twilio错误码 | 原因 | retryable | BullMQ行动 |
|---|---|---|---|
20429 | 超过速率限制/并发限制 | true | 以指数回退重试 |
30001 | 队列溢出 | true | 以指数回退重试 |
30008 | 未知载波故障/暂态网络 | true | 以指数回退重试 |
30010 | 无法联系到运营商/暂时不可用 | true | 以指数回退重试 |
20003 | 身份验证失败（无效的帐户SID /令牌） | false | 直接路由到DLQ（不重试） |
21211 | 无效的电话号码格式 | false | 直接路由到DLQ（不重试） |
21614 | 目标号码为座机/无法接收短信 | false | 直接路由到DLQ（不重试） |
21408 | 拒绝权限/未启用区域 | false | 直接路由到DLQ（不重试） |
监管通知和承运人成本
[!警告) 通过Twilio发送短信会产生每段运营商费用和转接费。 在美国，通过10位长代码（10DLC）发送的流量需要获得A2P批准的10DLC品牌和活动注册。未注册的流量受到严格的运营商过滤、节流或非交付费用的限制。
许可证
麻省理工学院