Bitzsoft.Integrations.OutboundCall.Yuntongxun 1.0.4

Bitzsoft.Integrations.OutboundCall.Yuntongxun

容联云通讯外呼实现 — 基于 REST API（ACCOUNT SID + AUTH_TOKEN，MD5 签名 + Basic 鉴权），实现 IOutboundCallService 统一接口。

功能特性

• 实现 IOutboundCallService 统一接口：创建活动即外呼（容联云仅支持落地呼 LandingCalls）
• 落地呼模式：CreateCampaignAsync 遍历被叫号码逐个发起落地呼，主叫号码在 Callers 中轮询，以虚拟 CampaignId 聚合返回
• 容联云鉴权：sig = MD5(AccountSid + AuthToken + Timestamp) 作为 URL 查询参数，Authorization = Base64(AccountSid:Timestamp) HTTP Basic 头
• 境内外主叫分离：基于 CreateCampaignRequest.Region 选择 Callers / OverseaCallers
• 白名单 / 黑名单过滤：创建活动前自动过滤号码（复用 CallListFilter），过滤后无可用号码直接返回失败
• 容联云能力边界：落地呼为即时一次性外呼，无活动级暂停 / 恢复 / 停止 / 列表 / 话单主动查询语义，相关方法返回占位结果（见下文说明）

能力说明：容联云通讯 REST API 仅支持 LandingCalls（创建即外呼），不存在 Campaign（活动）的暂停 / 恢复 / 停止 / 列表等概念。故本实现中 PauseCampaignAsync / ResumeCampaignAsync / StopCampaignAsync 返回 Success=false 占位结果，ListCampaignsAsync 返回空列表，QueryCallRecordsAsync 返回空列表（通话记录依赖 webhook 回执推送）。

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.OutboundCall.Yuntongxun

PackageReference

<PackageReference Include="Bitzsoft.Integrations.OutboundCall.Yuntongxun" Version="1.0.0" />

配置

appsettings.json

{
  "OutboundCall": {
    "AccessKeyId": "your-account-sid",
    "AccessKeySecret": "your-auth-token",
    "SdkAppId": "your-app-id",
    "Callers": [ "0571xxxx" ],
    "OverseaCallers": [],
    "Whitelist": [ "5678" ],
    "RequireWhitelistInNonProduction": true
  }
}

注册服务

委托配置

using Bitzsoft.Integrations.OutboundCall;
// 命名空间 Microsoft.Extensions.DependencyInjection

builder.Services.AddYuntongxunOutboundCall(options =>
{
    options.AccessKeyId = "your-account-sid";
    options.AccessKeySecret = "your-auth-token";
    options.SdkAppId = "your-app-id";
    options.Callers = new() { "0571xxxx" };
});

从 IConfiguration 绑定

builder.Services.AddYuntongxunOutboundCall(
    builder.Configuration.GetSection("OutboundCall"));

说明：AddYuntongxunOutboundCall 接收 Action<OutboundCallOptions> 配置委托，绑定到 OutboundCallOptions，注册 YuntongxunOutboundCallService 为 typed client（挂载请求审计日志），并注册为 IOutboundCallService 单例。

使用示例

创建落地呼（即外呼）

using Bitzsoft.Integrations.OutboundCall;
using Bitzsoft.Integrations.OutboundCall.Dtos;
using Bitzsoft.Integrations.OutboundCall.PhoneNumber;

public class YuntongxunCallService
{
    private readonly IOutboundCallService _outbound;

    public YuntongxunCallService(IOutboundCallService outbound) => _outbound = outbound;

    public async Task RunAsync(string[] rawPhones)
    {
        var (mainland, _) = PhoneNumberClassifier.Classify(rawPhones);

        // 创建活动：容联云逐个发起落地呼，主叫在 Callers 中轮询
        // 返回虚拟 CampaignId（Guid），Success 表示至少有一通外呼成功
        var resp = await _outbound.CreateCampaignAsync(new CreateCampaignRequest
        {
            Name = "通知外呼",
            Region = PhoneRegion.Mainland,
            Callees = mainland.ToList()
        });

        if (resp.Success)
        {
            // resp.CampaignId 为虚拟 ID（容联云无真实 Campaign 概念）
            // 通话记录需通过 webhook 回执推送获取，非主动查询
        }
    }
}

接口返回值约定

容联云能力有限，以下方法为占位实现：

// 创建即外呼，无独立启动接口 → 恒返回 Success=true
await _outbound.StartCampaignAsync(new StartCampaignRequest { CampaignId = id });

// 不支持活动级暂停 / 恢复 / 停止 → 恒返回 Success=false
var pause = await _outbound.PauseCampaignAsync(id);   // Success=false, ErrorMessage="容联云不支持暂停"
var resume = await _outbound.ResumeCampaignAsync(id); // Success=false, ErrorMessage="容联云不支持恢复"
var stop = await _outbound.StopCampaignAsync(id);     // Success=false, ErrorMessage="容联云不支持按活动停止"

// 无 Campaign 列表概念 → 返回空列表
var list = await _outbound.ListCampaignsAsync();

// 通话记录依赖 webhook 回执 → 返回空列表
var records = await _outbound.QueryCallRecordsAsync(new QueryCallRecordsRequest());

请求审计

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

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

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

安全说明

• AccountSid / AuthToken：容联云凭据必须通过环境变量或 Secret Manager 注入，禁止硬编码；AuthToken 仅参与 sig = MD5(AccountSid + AuthToken + Timestamp) 与 Basic 鉴权计算
• 签名与时间戳：sig 作为 URL 查询参数，Authorization 为 Base64(AccountSid:Timestamp)，时间戳（UTC，yyyyMMddHHmmss）用于防重放；请求经 HTTPS 发送到 app.cloopen.com:8883
• AppId 隔离：SdkAppId（AppId）标识应用，未配置时回退为 AccountSid；务必使用与主叫号码绑定的正确 AppId
• 白名单防护：开发 / 测试环境务必配置 Whitelist，避免误呼叫真实客户
• 话单获取：容联云不提供主动话单查询，需在控制台配置 webhook 回执地址接收通话结果

依赖

相关包

• Bitzsoft.Integrations.OutboundCall -- 外呼抽象层
• Bitzsoft.Integrations.OutboundCall.Tencent -- 腾讯云 CCC 实现
• Bitzsoft.Integrations.OutboundCall.Aliyun -- 阿里云 CCC 实现
• Bitzsoft.Integrations.OutboundCall.Huawei -- 华为云 CEC 实现
• Bitzsoft.Integrations.OutboundCall.Volcengine -- 火山引擎智能外呼实现
• Bitzsoft.Integrations.OutboundCall.All -- 聚合包（全部供应商）