Bitzsoft.Integrations.OutboundCall.Vonage 1.0.0

Bitzsoft.Integrations.OutboundCall.Vonage

Vonage（原 Nexmo）Voice API 外呼实现，手写 HttpClient + RS256 JWT 鉴权（Application 私钥签名）+ NCCO 呼叫控制，实现 IOutboundCallService 统一接口。

功能

• 实现 IOutboundCallService 统一接口（创建/启动/暂停/恢复/停止活动 + 活动列表/详情 + 话单查询）
• Vonage 为 per-call 模型（无原生 campaign）：campaign 元数据与联系人维护在本库内存中，StartCampaign 经共享 CampaignDialer 按 CPS 节流逐个发起外呼
• 支持暂停/恢复/停止（代次守卫，防止循环重叠与重复记账）
• 内联 NCCO 或 AnswerUrl 指定呼叫内容
• RS256 JWT 鉴权：用 Application 的 RSA 私钥（PEM）签 application_id claim，作 Bearer token；RSA.ImportFromPem 为主、BouncyCastle PemReader 兜底
• 白名单/黑名单过滤（复用 CallListFilter）
• 手写 HttpClient，不依赖 Vonage SDK（net5.0 兼容）

限制：campaign 状态存内存，进程重启后丢失；StartCampaign 可凭已导入联系人重跑，话单仍可从 Vonage 查询。

安装

dotnet add package Bitzsoft.Integrations.OutboundCall.Vonage

配置

{
  "VonageOutboundCall": {
    "ApplicationId": "your-application-id",
    "PrivateKeyPem": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
    "From": "12025550123",
    "Ncco": "[{\"action\":\"talk\",\"text\":\"您好\",\"language\":\"cmn-CN\"}]",
    "Cps": 1,
    "Domain": "api.nexmo.com"
  }
}

PrivateKeyPem 为 Vonage Application 的私钥（控制台创建 Application 时生成，PKCS#1/PKCS#8 PEM 均可）。生产环境建议从密文配置/密钥库读取，勿明文入库。

注册

services.AddVonageOutboundCall(options =>
{
    options.ApplicationId = "your-application-id";
    options.PrivateKeyPem = privateKeyPem; // PEM 文本
    options.From = "12025550123";
    options.Ncco = "[{\"action\":\"talk\",\"text\":\"您好\",\"language\":\"cmn-CN\"}]";
    options.Cps = 1;
});

第三方请求日志

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddVonageOutboundCall(options => { /* ... */ });

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("PrivateKeyPem"); // 额外脱敏字段
});
services.AddVonageOutboundCall(options => { /* ... */ });

使用

// 创建活动并导入联系人（campaign 状态存内存）
var resp = await outboundCall.CreateCampaignAsync(new CreateCampaignRequest
{
    Name = "通知外呼",
    Region = PhoneRegion.Overseas,
    Callees = new() { "12025550123", "12025550124" }
});

// 启动：后台按 CPS 节流逐个拨号
await outboundCall.StartCampaignAsync(new StartCampaignRequest { CampaignId = resp.CampaignId });

// 查询话单（从 Vonage 账号级 call 列表拉取）
var records = await outboundCall.QueryCallRecordsAsync(new QueryCallRecordsRequest { PageSize = 50 });

安全说明

• PrivateKeyPem：Vonage Application 的 RSA 私钥，用于签 RS256 JWT 作 Bearer token 鉴权。通过密文配置 / 密钥库注入，禁止明文入库；务必加入 RequestLogging 脱敏字段。
• campaign 状态存内存：进程重启后丢失；StartCampaign 可凭已导入联系人重跑。

依赖

相关包

• Bitzsoft.Integrations.OutboundCall — 外呼抽象层
• Bitzsoft.Integrations.OutboundCall.Twilio — Twilio 外呼实现
• Bitzsoft.Integrations.OutboundCall.Tencent — 腾讯云 CCC 实现
• Bitzsoft.Integrations.OutboundCall.All — 聚合包