Bitzsoft.Integrations.OutboundCall.Volcengine 1.0.1

Bitzsoft.Integrations.OutboundCall.Volcengine

火山引擎智能外呼实现 — 基于 AI 外呼机器人 REST API（AccessKeyID + SecretKey，签名 V4 / HMAC-SHA256），实现 IOutboundCallService 统一接口。

功能特性

• 实现 IOutboundCallService 统一接口：创建 / 暂停 / 恢复 / 停止外呼任务 + 任务列表 / 详情查询 + 通话记录查询
• 创建即启动：火山引擎 CreateTask 创建任务后自动启动，无需额外调用 StartCampaign（接口兼容返回成功）
• 号码追加：AppendNumbers 向已有任务动态追加被叫号码
• 火山引擎签名 V4 鉴权：HMAC-SHA256 计算签名，Authorization 头携带 Credential（AccessKeyId）与 Signature，配合 X-Date / X-AK 头
• 境内外主叫分离：基于 CreateCampaignRequest.Region 选择 Callers / OverseaCallers
• 白名单 / 黑名单过滤：创建任务前自动过滤号码（复用 CallListFilter），过滤后无可用号码直接返回失败
• 任务状态映射：将火山引擎状态（pending / running / paused / completed / stopped / failed 等）映射为统一 CampaignStatus

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.OutboundCall.Volcengine

PackageReference

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

配置

appsettings.json

{
  "OutboundCall": {
    "AccessKeyId": "AKxxxxxxxxxxxxxxxx",
    "AccessKeySecret": "SKxxxxxxxxxxxxxxxx",
    "Endpoint": "https://visual.volcengineapi.com",
    "Callers": [ "01012345678" ],
    "OverseaCallers": [],
    "Whitelist": [ "5678" ],
    "RequireWhitelistInNonProduction": true
  }
}

注册服务

委托配置

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

builder.Services.AddVolcengineOutboundCall(options =>
{
    options.AccessKeyId = "AKxxxxxxxxxxxxxxxx";
    options.AccessKeySecret = "SKxxxxxxxxxxxxxxxx";
    options.Callers = new() { "01012345678" };
});

从 IConfiguration 绑定

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

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

使用示例

创建任务 + 追加号码 + 控制

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

public class VolcCallService
{
    private readonly IOutboundCallService _outbound;

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

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

        // 1. 创建任务（火山引擎创建即启动，返回 task_id）
        var resp = await _outbound.CreateCampaignAsync(new CreateCampaignRequest
        {
            Name = "智能外呼",
            Region = PhoneRegion.Mainland,
            Callees = mainland.ToList(),
            MaxAttempts = 2,
            NotBefore = DateTimeOffset.UtcNow,
            NotAfter = DateTimeOffset.UtcNow.AddHours(2)
        });

        // 2. 追加号码（AppendNumbers）
        await _outbound.ImportContactsAsync(new ImportContactsRequest
        {
            CampaignId = resp.CampaignId,
            Contacts = new() { "0086139xxxxxxxx" }
        });

        // 3. 暂停 / 恢复 / 停止
        await _outbound.PauseCampaignAsync(resp.CampaignId);
        await _outbound.ResumeCampaignAsync(resp.CampaignId);
        await _outbound.StopCampaignAsync(resp.CampaignId);
    }
}

查询任务与话单

// 查询任务列表
var tasks = await _outbound.ListCampaignsAsync(pageIndex: 1, pageSize: 20);

// 查询单个任务详情
var detail = await _outbound.GetCampaignAsync(taskId);

// 查询任务的通话记录（含录音 URL）
var records = await _outbound.QueryCallRecordsAsync(new QueryCallRecordsRequest
{
    CampaignId = taskId,
    PageSize = 100
});

请求审计

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

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

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

安全说明

• AccessKeyID / SecretKey：火山引擎密钥必须通过环境变量或 Secret Manager 注入，禁止硬编码；SecretKey 仅参与 HMAC-SHA256 签名，不出现在请求中
• 签名机制：每次请求实时计算签名，附加 X-Date（Unix 秒时间戳）、X-AK（AccessKeyId）与 Authorization 头，请求经 HTTPS 发送
• 端点配置：默认端点 https://visual.volcengineapi.com，如使用其他区域或专属端点可通过 Endpoint 覆盖
• 白名单防护：开发 / 测试环境务必配置 Whitelist，避免误呼叫真实客户

依赖

相关包

• Bitzsoft.Integrations.OutboundCall -- 外呼抽象层
• Bitzsoft.Integrations.OutboundCall.Tencent -- 腾讯云 CCC 实现
• Bitzsoft.Integrations.OutboundCall.Aliyun -- 阿里云 CCC 实现
• Bitzsoft.Integrations.OutboundCall.Huawei -- 华为云 CEC 实现
• Bitzsoft.Integrations.OutboundCall.Yuntongxun -- 容联云通讯实现
• Bitzsoft.Integrations.OutboundCall.All -- 聚合包（全部供应商）