Bitzsoft.Integrations.OutboundCall.Tencent 1.0.4

Bitzsoft.Integrations.OutboundCall.Tencent

腾讯云 CCC 外呼实现 — 手写 TC3-HMAC-SHA256 签名 + HttpClient，实现 IOutboundCallService 统一接口，支持境内外分离与白名单控制。

功能特性

• 实现 IOutboundCallService 统一接口：创建 / 暂停 / 恢复 / 停止活动 + 活动列表 / 详情查询 + 话单查询（DescribeTelCdr）
• 手写 TC3-HMAC-SHA256 签名：纯静态 TencentCccSigner，仅依赖 SHA256 与 HMACSHA256，不依赖 TencentCloudSDK.Common，确定可重放便于单元测试
• 境内外自动分离：基于 CreateCampaignRequest.Region 自动选择 Callers / OverseaCallers、SdkAppId / OverseaSdkAppId、CnIvrId / EnIvrId
• 白名单 / 黑名单过滤：创建活动前自动过滤号码（复用 CallListFilter），过滤后无可用号码直接返回失败
• 腾讯活动状态映射：将腾讯预测式外呼任务状态码映射为统一 CampaignStatus（待启动 / 运行中 / 已暂停 / 已完成 / 已终止）
• 错误码透传：TencentCccException 携带腾讯云 ErrorCode 与 RequestId，经 OutboundCallException 上抛便于溯源

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.OutboundCall.Tencent

PackageReference

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

配置

appsettings.json

{
  "OutboundCall": {
    "AccessKeyId": "your-secret-id",
    "AccessKeySecret": "your-secret-key",
    "Region": "ap-guangzhou",
    "SdkAppId": "1400818883",
    "OverseaSdkAppId": "1400818885",
    "CnIvrId": 21232,
    "EnIvrId": 21408,
    "Callers": [ "008602160662606" ],
    "OverseaCallers": [ "0085230087235" ],
    "Whitelist": [ "5678" ],
    "RequireWhitelistInNonProduction": true
  }
}

注册服务

委托配置

using Bitzsoft.Integrations.OutboundCall;
// 命名空间 Microsoft.Extensions.DependencyInjection（扩展方法所在）

builder.Services.AddTencentOutboundCall(options =>
{
    options.AccessKeyId = "your-secret-id";
    options.AccessKeySecret = "your-secret-key";
    options.Region = "ap-guangzhou";
    options.SdkAppId = "1400818883";
    options.OverseaSdkAppId = "1400818885";
    options.CnIvrId = 21232;
    options.EnIvrId = 21408;
    options.Callers = new() { "008602160662606" };
    options.OverseaCallers = new() { "0085230087235" };
});

从 IConfiguration 绑定

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

说明：AddTencentOutboundCall 接收 Action<OutboundCallOptions> 配置委托，内部 services.Configure(configure) 绑定到 OutboundCallOptions，并将 TencentOutboundCallService 注册为 IOutboundCallService 单例。

使用示例

号码清洗 + 分类后境内外分呼

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

public class ReminderController
{
    private readonly IOutboundCallService _outbound;

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

    public async Task SendAsync(string[] rawPhones)
    {
        // 1. 号码清洗 + 分类
        var (mainland, oversea) = PhoneNumberClassifier.Classify(rawPhones);

        // 2. 境内外呼（使用 Callers + SdkAppId + CnIvrId）
        await _outbound.CreateCampaignAsync(new CreateCampaignRequest
        {
            Name = "催办-境内",
            Region = PhoneRegion.Mainland,
            Callees = mainland.ToList(),
            MaxAttempts = 2
        });

        // 3. 境外外呼（使用 OverseaCallers + OverseaSdkAppId + EnIvrId）
        await _outbound.CreateCampaignAsync(new CreateCampaignRequest
        {
            Name = "催办-境外",
            Region = PhoneRegion.Overseas,
            Callees = oversea.ToList()
        });
    }
}

活动生命周期管理 + 话单查询

// 创建活动（腾讯 CreateAutoCalloutTask 创建即运行）
var resp = await _outbound.CreateCampaignAsync(new CreateCampaignRequest
{
    Name = "夜间催办",
    Region = PhoneRegion.Mainland,
    Callees = mainland,
    NotBefore = DateTimeOffset.UtcNow.AddHours(1),
    NotAfter = DateTimeOffset.UtcNow.AddHours(4),
    MaxAttempts = 3
});

// 暂停 / 恢复 / 停止（腾讯 PausePredictiveDialingCampaign / Resume / Abort）
await _outbound.PauseCampaignAsync(resp.CampaignId);
await _outbound.ResumeCampaignAsync(resp.CampaignId);
await _outbound.StopCampaignAsync(resp.CampaignId);

// 查询活动列表
var campaigns = await _outbound.ListCampaignsAsync(pageIndex: 1, pageSize: 20);

// 查询话单（腾讯 DescribeTelCdr）
var records = await _outbound.QueryCallRecordsAsync(new QueryCallRecordsRequest
{
    StartTime = DateTimeOffset.UtcNow.AddDays(-1),
    PageSize = 100
});

请求审计

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

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

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

安全说明

• SecretId / SecretKey：腾讯云密钥必须通过环境变量或 Secret Manager 注入，禁止硬编码；AccessKeySecret 仅用于 TC3 签名计算，不会出现在 URL
• TC3 签名：每次请求实时派生签名密钥（date → service → terminator），Authorization 头携带时间戳防止重放，与腾讯云 API 3.0 一致
• 白名单防护：开发 / 测试环境务必配置 Whitelist，避免误呼叫真实客户号码
• RequestId 溯源：腾讯云错误响应携带 RequestId，会通过 TencentCccException.RequestId → OutboundCallException.RequestId 透传，便于对接腾讯云工单

依赖

相关包

• Bitzsoft.Integrations.OutboundCall -- 外呼抽象层
• Bitzsoft.Integrations.OutboundCall.Aliyun -- 阿里云 CCC 实现
• Bitzsoft.Integrations.OutboundCall.Huawei -- 华为云 CEC 实现
• Bitzsoft.Integrations.OutboundCall.Volcengine -- 火山引擎智能外呼实现
• Bitzsoft.Integrations.OutboundCall.Yuntongxun -- 容联云通讯实现
• Bitzsoft.Integrations.OutboundCall.Twilio -- Twilio 实现（per-call 编排）
• Bitzsoft.Integrations.OutboundCall.All -- 聚合包（全部供应商）