Bitzsoft.Integrations.TencentCcc 1.0.0-alpha.5

Bitzsoft.Integrations.TencentCcc

腾讯云呼叫中心集成客户端 — TCLOUD SDK 封装、多租户配置、调用日志拦截。

功能特性

• TCLOUD SDK 封装 — 基于 TencentCloudSDK.Common 封装 70+ 个 API 端点，覆盖自动外呼、预测式外呼、座席管理、话机管理、通话会话、号码管理、公司资质、SDK 鉴权、实时指标等模块
• 多租户支持 — 通过 ITencentCccOptionsProvider 按租户动态解析配置（SecretId/SecretKey/Region），默认实现从静态配置读取，宿主层可替换为数据库解析
• 调用日志拦截 — 可选 ITencentCccCallLogger 拦截器，统一记录每次 API 调用的请求/响应/耗时/异常，便于排查与审计
• 异常统一包装 — 腾讯云 SDK 内部异常自动包装为 TencentCccException，宿主层无需直接引用 TencentCloudSDK.Common
• 工厂模式创建客户端 — ITencentCccClientFactory 按租户动态创建客户端实例，客户端无状态，可安全频繁创建
• SDK 鉴权集成 — 内置管理端 URL 生成、SDK Login Token 创建、UserSig 签名等鉴权方法

安装

dotnet add package Bitzsoft.Integrations.TencentCcc

<PackageReference Include="Bitzsoft.Integrations.TencentCcc" Version="*" />

配置

{
  "TencentCcc": {
    "SecretId": "YOUR_SECRET_ID",
    "SecretKey": "YOUR_SECRET_KEY",
    "Region": "ap-guangzhou",
    "SdkAppId": "1400000000",
    "CnIvrId": "100",
    "EnIvrId": "200",
    "Callers": "020-12345678,020-87654321",
    "Callees": "",
    "OverseaSdkAppId": null,
    "OverseaCnIvrId": null,
    "OverseaEnIvrId": null,
    "OverseaCallers": null,
    "OverseaCallees": null
  }
}

注册服务

单租户（静态配置）

using Bitzsoft.Integrations.TencentCcc;
using Bitzsoft.Integrations.TencentCcc.DependencyInjection;

// 方式一：使用默认配置（从 appsettings.json 读取）
services.AddTNTTencentCcc();

// 方式二：代码配置
services.AddTNTTencentCcc(options =>
{
    options.SecretId = "YOUR_SECRET_ID";
    options.SecretKey = "YOUR_SECRET_KEY";
    options.Region = "ap-guangzhou";
    options.SdkAppId = "1400000000";
    options.CnIvrId = "100";
    options.Callers = "020-12345678";
});

多租户（动态配置）

using Bitzsoft.Integrations.TencentCcc;
using Bitzsoft.Integrations.TencentCcc.DependencyInjection;
using Bitzsoft.Integrations.TencentCcc.Interfaces;

// 注册核心服务
services.AddTNTTencentCcc();

// 替换默认配置解析器为数据库实现
services.Replace(new ServiceDescriptor(
    typeof(ITencentCccOptionsProvider),
    typeof(DatabaseTencentCccOptionsProvider),
    ServiceLifetime.Transient));

注意：AddTNTTencentCcc 注册 ITencentCccOptionsProvider（默认从静态配置读取）和 ITencentCccClientFactory（Transient 生命周期）。腾讯云 CCC SDK 使用内置 HTTP 管道，不经过 IHttpClientFactory。

可选：注册调用日志拦截器

using Bitzsoft.Integrations.TencentCcc.Interfaces;

// 注册日志拦截器（可选）
services.AddTransient<ITencentCccCallLogger, MyCallLogger>();

使用示例

创建自动外呼任务

using Bitzsoft.Integrations.TencentCcc.Interfaces;
using Bitzsoft.Integrations.TencentCcc.Models.Dtos;

public class OutboundCallService
{
    private readonly ITencentCccClientFactory _clientFactory;

    public OutboundCallService(ITencentCccClientFactory clientFactory)
    {
        _clientFactory = clientFactory;
    }

    public async Task CreateCalloutTaskAsync(string tenantId, CancellationToken ct)
    {
        // 按租户创建客户端
        var client = await _clientFactory.CreateAsync(tenantId, ct);

        // 构建外呼任务请求
        var request = new CreateAutoCalloutTaskRequest
        {
            SdkAppId = 1400000000,
            Name = "客户回访任务",
            Description = "2024年Q4客户满意度回访",
            NotBefore = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
            Callers = new[] { "020-12345678" },
            Callees = new[] { "13800138001", "13800138002", "13800138003" },
            IvrId = 100,
            Tries = 3
        };

        var response = await client.CreateAutoCalloutTask(request);
        Console.WriteLine($"外呼任务已创建，TaskId: {response?.TaskId}");
    }
}

查询通话记录

using Bitzsoft.Integrations.TencentCcc.Interfaces;
using Bitzsoft.Integrations.TencentCcc.Models.Dtos;

public class CallRecordService
{
    private readonly ITencentCccClientFactory _clientFactory;

    public CallRecordService(ITencentCccClientFactory clientFactory)
    {
        _clientFactory = clientFactory;
    }

    public async Task QueryCallRecordsAsync(string tenantId, CancellationToken ct)
    {
        var client = await _clientFactory.CreateAsync(tenantId, ct);

        var request = new DescribeTelCdrRequest
        {
            SdkAppId = 1400000000,
            PageSize = 50,
            PageNumber = 0,
            StartTimeStamp = DateTimeOffset.UtcNow.AddDays(-7).ToUnixTimeSeconds(),
            EndTimeStamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds()
        };

        var response = await client.DescribeTelCdr(request);
        Console.WriteLine($"查询到 {response?.TotalCount ?? 0} 条通话记录");
    }
}

座席管理与实时指标

using Bitzsoft.Integrations.TencentCcc.Interfaces;
using Bitzsoft.Integrations.TencentCcc.Models.Dtos;

public class StaffManagementService
{
    private readonly ITencentCccClientFactory _clientFactory;

    public StaffManagementService(ITencentCccClientFactory clientFactory)
    {
        _clientFactory = clientFactory;
    }

    public async Task ManageStaffAsync(string tenantId, CancellationToken ct)
    {
        var client = await _clientFactory.CreateAsync(tenantId, ct);

        // 创建座席
        var createResult = await client.CreateStaff(new CreateStaffRequest
        {
            SdkAppId = 1400000000,
            // 填入座席信息
        });

        // 绑定技能组
        await client.BindStaffSkillGroupList(new BindStaffSkillGroupListRequest
        {
            SdkAppId = 1400000000,
            // 填入绑定参数
        });

        // 查询座席实时状态
        var metrics = await client.DescribeStaffStatusMetrics(
            new DescribeStaffStatusMetricsRequest
            {
                SdkAppId = 1400000000
            });
    }
}

多租户配置解析器实现

using Bitzsoft.Integrations.TencentCcc;
using Bitzsoft.Integrations.TencentCcc.Interfaces;

public class DatabaseTencentCccOptionsProvider : ITencentCccOptionsProvider
{
    private readonly ITenantConfigRepository _repository;

    public DatabaseTencentCccOptionsProvider(ITenantConfigRepository repository)
    {
        _repository = repository;
    }

    public async Task<TencentCccOptions> GetOptionsAsync(
        string? tenantId = null, CancellationToken ct = default)
    {
        var config = await _repository.GetByTenantIdAsync(tenantId!, ct);

        return new TencentCccOptions
        {
            SecretId = config.SecretId,
            SecretKey = config.SecretKey,
            Region = config.Region ?? "ap-guangzhou",
            SdkAppId = config.SdkAppId,
            CnIvrId = config.CnIvrId,
            EnIvrId = config.EnIvrId,
            Callers = config.Callers,
            Callees = config.Callees
        };
    }
}

API 一览

相关包

• Bitzsoft.Integrations.EkuaiBao — 合思易快报费控系统集成客户端
• Bitzsoft.Integrations.Sms — 短信服务集成客户端
• Bitzsoft.Integrations.All — 全部集成包聚合引用