447 lines
13 KiB
Markdown
447 lines
13 KiB
Markdown
SaaS Dispatcher 对接文档 v0.5
|
||
相关占位说明：
|
||
`/internal/v1/dispatcher/xxxxx` 路由按系统当前架构路由进行定义即可
|
||
`X-DISPATCHER-ID`/`X-DISPATCHER-SECRET-KEY` HEADER 头KEY 获取忽略大小写
|
||
Dispatcher 角色下称 D
|
||
触发顺序
|
||
1.1 MQ 发布消费规则
|
||
RabbitMQ 有发布入口 exchange → 发布时指定的 routing key → 预先绑定的 queue → D 消费四步；
|
||
```Plain Text
|
||
SaaS→D exchange: agent-call.dispatchers.v1
|
||
routing key: d.<dispatcher_id>.t.<tenant_id>.in
|
||
binding key: d.<dispatcher_id>.t.<tenant_id>.in
|
||
queue: agent-call.d.<dispatcher_id>.t.<tenant_id>.v1
|
||
consumer: 对应 Dispatcher
|
||
D→SaaS exchange: agent-call.saas.v1
|
||
routing key: d.<dispatcher_id>.t.<tenant_id>.out
|
||
queue: agent-call.saas.events.v1
|
||
consumer: SaaS
|
||
```
|
||
1.2 本轮任务队列与事件路由
|
||
硬边界：所有 exchange/queue/binding 均由 SaaS 创建、维护和退役；D 只消费 SaaS 创建的任务/控制队列，并向 SaaS 创建的结果 exchange 发布，不声明、绑定或删除队列。
|
||
```Plain Text
|
||
SaaS 创建并绑定：
|
||
exchange: agent-call.dispatchers.v1 (topic, durable)
|
||
task routing: d.<dispatcher_id>.task.<task_id>.in
|
||
task queue: agent-call.d.<dispatcher_id>.task.<task_id>.v1
|
||
control route: d.<dispatcher_id>.control.in
|
||
control queue: agent-call.d.<dispatcher_id>.control.v1
|
||
dead-letter: agent-call.dead-letter.v1
|
||
D -> SaaS exchange: agent-call.saas.v1 (topic, durable)
|
||
result route: d.<dispatcher_id>.out
|
||
SaaS result queue: agent-call.saas.d.<dispatcher_id>.v1
|
||
```
|
||
HTTP请求
|
||
SIP列表配置
|
||
```HTTP
|
||
GET /internal/v1/dispatcher/sip HTTP/1.1
|
||
Host: <SaaS 服务地址>
|
||
X-DISPATCHER-id: c046b893-8628-4589-ae50-619d049248a6
|
||
X-DISPATCHER-SECRET-KEY: <密钥>
|
||
```
|
||
响应：
|
||
```JSON
|
||
{
|
||
"resource": "sip_config", // 资源类型：SIP 配置
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6", // 这份配置所属的 Dispatcher
|
||
"trunks": [ // 该 Dispatcher 获批的线路列表
|
||
{
|
||
"trunk_id": "trunk-mock", // 线路的唯一标识
|
||
"provider_id": "provider-mock", // SIP 服务商标识
|
||
"codec": "PCMA", // 线路使用的语音编码
|
||
"dial_prefix": "", // 该线路拨号时添加的被叫前缀；空串表示不添加
|
||
"enabled": true, // 是否启用这条线路
|
||
"server_host": "sip.example.invalid", // SIP 服务端地址；此处是 Mock 地址
|
||
"server_port": 5060, // SIP 服务端端口
|
||
"transport": null, // 传输方式：udp、tcp、tls；null 表示尚未确认
|
||
"auth_mode": null, // 鉴权方式：ip、digest、none；null 表示尚未确认
|
||
"registration_required": null, // 是否需要 SIP 注册；null 表示尚未确认
|
||
"max_concurrent_calls": null, // 分配给该 Dispatcher 的线路并发上限；null 表示尚未确认
|
||
"caller_profiles": [ // 这条线路可用的主叫配置
|
||
{
|
||
"caller_profile_id": "caller-profile-mock", // 主叫配置标识，供任务引用
|
||
"caller_id": "BD00000000" // 实际主叫标识，保留原值及字母
|
||
}
|
||
],
|
||
"schedule": { // 这条线路允许外呼的每周时段
|
||
"time_zone": "Asia/Shanghai", // 判断时段使用的时区
|
||
"weekly_windows": { // 每天可配置多个时段；空数组表示当天不允许外呼
|
||
"monday": [{"start": "09:00", "end": "20:00"}], // 周一
|
||
"tuesday": [{"start": "09:00", "end": "20:00"}], // 周二
|
||
"wednesday": [{"start": "09:00", "end": "20:00"}], // 周三
|
||
"thursday": [{"start": "09:00", "end": "20:00"}], // 周四
|
||
"friday": [{"start": "09:00", "end": "20:00"}], // 周五
|
||
"saturday": [], // 周六不允许外呼
|
||
"sunday": [] // 周日不允许外呼
|
||
} }
|
||
} ]
|
||
}
|
||
```
|
||
AI 服务商全量读取
|
||
`GET /internal/v1/dispatcher/ai-providers`
|
||
```JSON
|
||
{
|
||
"resource": "ai_providers",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"providers": [
|
||
{
|
||
"provider_ref": "asr-provider-a",
|
||
"role": "asr",
|
||
"enabled": true,
|
||
"adapter": "volcengine_asr",
|
||
"endpoint": "https://asr.example.invalid",
|
||
"credential": "managed-asr-a"
|
||
},
|
||
{
|
||
"provider_ref": "llm-provider-a",
|
||
"role": "llm",
|
||
"enabled": true,
|
||
"adapter": "openai_compatible",
|
||
"endpoint": "https://llm.example.invalid/v1",
|
||
"credential": "managed-llm-a"
|
||
},
|
||
{
|
||
"provider_ref": "tts-provider-a",
|
||
"role": "tts",
|
||
"enabled": true,
|
||
"adapter": "volcengine_tts",
|
||
"endpoint": "https://tts.example.invalid",
|
||
"credential": "managed-tts-a"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
任务配置
|
||
```HTTP
|
||
GET /internal/v1/dispatcher/task/{task_id} HTTP/1.1
|
||
Host: <SaaS 服务地址>
|
||
X-DISPATCHER-id: c046b893-8628-4589-ae50-619d049248a6
|
||
X-DISPATCHER-SECRET-KEY: <密钥>
|
||
```
|
||
响应体：
|
||
仅 ASR 模式（Agent配置仅返回 ASR即可）
|
||
ASR + LLM + TTS 模式
|
||
```JSON
|
||
{
|
||
**"resource"**: **"task_config"**,
|
||
**"dispatcher_id"**: **"c046b893-8628-4589-ae50-619d049248a6"**,
|
||
**"tenant_id"**: **"tenant-id-mock"**,
|
||
**"task_id"**: **"task-mock"**,
|
||
**"task_revision"**: **2**,
|
||
**"status"**: **"running"**,
|
||
**"name"**: **"Mock task"**,
|
||
**"max_concurrent_calls"**: **2**,
|
||
**"ring_timeout_ms"**: **30000**,
|
||
**"max_call_duration_ms"**: **120000**,
|
||
**"route_policy_id"**: **"route-mock"**,
|
||
**"caller_profile_id"**: **"caller-profile-mock"**,
|
||
**"allowed_trunk_ids"**: [
|
||
**"trunk-mock"**
|
||
],
|
||
**"schedule"**: {
|
||
**"time_zone"**: **"Asia/Shanghai"**,
|
||
**"starts_at"**: **"2026-09-21T00:00:00+08:00"**,
|
||
**"ends_at"**: **null**,
|
||
**"weekly_windows"**: {
|
||
**"monday"**: [
|
||
{
|
||
**"start"**: **"09:00"**,
|
||
**"end"**: **"11:00"**
|
||
},
|
||
{
|
||
**"start"**: **"14:00"**,
|
||
**"end"**: **"18:00"**
|
||
}
|
||
],
|
||
**"tuesday"**: [
|
||
{
|
||
**"start"**: **"09:00"**,
|
||
**"end"**: **"18:00"**
|
||
}
|
||
],
|
||
**"wednesday"**: [
|
||
{
|
||
**"start"**: **"09:00"**,
|
||
**"end"**: **"18:00"**
|
||
}
|
||
],
|
||
**"thursday"**: [
|
||
{
|
||
**"start"**: **"09:00"**,
|
||
**"end"**: **"18:00"**
|
||
}
|
||
],
|
||
**"friday"**: [
|
||
{
|
||
**"start"**: **"09:00"**,
|
||
**"end"**: **"18:00"**
|
||
}
|
||
],
|
||
**"saturday"**: [
|
||
|
||
],
|
||
**"sunday"**: [
|
||
|
||
]
|
||
},
|
||
**"excluded_dates"**: [
|
||
**"2026-10-01"**,
|
||
**"2026-10-02"**
|
||
]
|
||
},
|
||
**"agent"**: {
|
||
**"immutable"**: **true**,
|
||
**"mode"**: **"full_ai"**,
|
||
**"llm"**: {
|
||
**"provider_ref"**: **"mock"**,
|
||
**"model"**: **"mock-chat-v1"**,
|
||
**"temperature"**: **0.2**,
|
||
**"max_tokens"**: **256**,
|
||
**"timeout_ms"**: **5000**
|
||
},
|
||
**"prompt"**: {
|
||
**"text"**: **"Mock prompt for an isolated test."**,
|
||
**"allowed_variables"**: [
|
||
|
||
],
|
||
**"max_bytes"**: **32768**
|
||
},
|
||
**"tts"**: {
|
||
**"provider_ref"**: **"mock"**,
|
||
**"model"**: **"mock-tts-v1"**,
|
||
**"voice"**: **"mock-neutral"**,
|
||
**"speed"**: **1**,
|
||
**"format"**: {
|
||
**"encoding"**: **"pcm_s16le"**,
|
||
**"sample_rate_hz"**: **16000**,
|
||
**"channels"**: **1**
|
||
},
|
||
**"timeout_ms"**: **5000**
|
||
},
|
||
**"asr"**: {
|
||
**"provider_ref"**: **"mock"**,
|
||
**"language"**: **"zh-CN"**,
|
||
**"input"**: {
|
||
**"encoding"**: **"pcm_s16le"**,
|
||
**"sample_rate_hz"**: **16000**,
|
||
**"channels"**: **1**,
|
||
**"sample_width_bytes"**: **2**
|
||
},
|
||
**"interim"**: **true**,
|
||
**"timeout_ms"**: **5000**
|
||
},
|
||
**"conversation"**: {
|
||
**"opening"**: **"开场白"**,
|
||
**"hangup_keywords"**: [
|
||
**"不用了"**,
|
||
**"请挂机"**
|
||
],
|
||
**"allow_interrupt"**: **true**,
|
||
**"silence_timeout_ms"**: **3000**,
|
||
**"max_duration_ms"**: **120000**,
|
||
**"max_turns"**: **20**,
|
||
**"sentence_max_chars"**: **80**,
|
||
**"max_pending_audio_chunks"**: **32**
|
||
}
|
||
}
|
||
}
|
||
```
|
||
任务列表
|
||
```HTTP
|
||
GET /internal/v1/dispatcher/tasks HTTP/1.1
|
||
Host: <SaaS 内网地址>
|
||
X-DISPATCHER-id: c046b893-8628-4589-ae50-619d049248a6
|
||
X-DISPATCHER-SECRET-KEY: <密钥>
|
||
```
|
||
增量请求
|
||
```HTTP
|
||
GET /internal/v1/dispatcher/tasks?after=1042 HTTP/1.1
|
||
Host: <SaaS 内网地址>
|
||
X-DISPATCHER-id: c046b893-8628-4589-ae50-619d049248a6
|
||
X-DISPATCHER-SECRET-KEY: <密钥>
|
||
```
|
||
响应:
|
||
```JSON
|
||
{
|
||
"schema_version": "task-discovery.v0.2-proposal",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"cursor": "1042",
|
||
"tasks": [
|
||
{
|
||
"task_id": "task-a",
|
||
"tenant_id": 1001,
|
||
"status": "running",
|
||
"task_revision": 1
|
||
},
|
||
{
|
||
"task_id": "task-old",
|
||
"tenant_id": 1001,
|
||
"status": "stopped",
|
||
"task_revision": 3
|
||
}
|
||
]
|
||
}
|
||
```
|
||
按租户 ID 获取配额信息
|
||
```HTTP
|
||
GET /internal/v1/dispatcher/tenant/{tenant-id}/quota HTTP/1.1
|
||
Host: <SaaS 内网地址>
|
||
X-DISPATCHER-id: c046b893-8628-4589-ae50-619d049248a6
|
||
X-DISPATCHER-SECRET-KEY: <密钥>
|
||
```
|
||
```JSON
|
||
{
|
||
"resource": "tenant_quota",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"tenant_id": "tenant-id-mock",
|
||
"quota_revision": 1,
|
||
"max_concurrent_calls": 3
|
||
}
|
||
```
|
||
控制事件
|
||
> 队列：agent\-call\.d\.\<dispatcher\_id\>\.control\.v1
|
||
>
|
||
>
|
||
SIP 线路变更
|
||
```JSON
|
||
{
|
||
"event_id": "7cd23165-c88e-4f36-8cf2-b5e9ac67ecdb",
|
||
"event_type": "sip.config",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"payload": {
|
||
"trunk_id": "trunk-mock",
|
||
"change_type": "disabled", // enabled/removed/created
|
||
"revision": 8
|
||
}
|
||
}
|
||
```
|
||
任务控制
|
||
```JSON
|
||
{
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"tenant_id": 1001,
|
||
"issued_at": "2026-09-21T00:00:00Z",
|
||
"event_id": "7cd23165-c88e-4f36-8cf2-b5e9ac67ecdb",
|
||
"event_type":: "task.control",
|
||
"payload": {
|
||
"task_id": "task-a",
|
||
"action": "pause", // resume , stop
|
||
"reason": "local-test",
|
||
"options": { // 附加控制参数
|
||
"active_call_policy": "drain", // 活跃通话策略,仅stop,pause事件生效 [drain|hangup]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
任务控制处理回执
|
||
> 队列 agent\-call\.saas\.v1
|
||
>
|
||
>
|
||
```JSON
|
||
{
|
||
"event_id": "7cd23165-c88e-4f36-8cf2-b5e9ac67ecdb",
|
||
"event_type":: "task.control",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"tenant_id": 1001,
|
||
"payload": {
|
||
"status": "applied"
|
||
}
|
||
}
|
||
```
|
||
|
||
外呼任务队列
|
||
> 队列：agent\-call\.d\.\<dispatcher\_id\>\.t\.\<tenant\_id\>\.v1
|
||
>
|
||
>
|
||
呼出
|
||
```JSON
|
||
{
|
||
"event_id": "7cd23165-c88e-4f36-8cf2-b5e9ac67ecdb",
|
||
"event_type":: "call.execute",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"tenant_id": 1001,
|
||
"issued_at": "2026-09-18T10:00:00+08:00"
|
||
"payload": {
|
||
"task_id": "task-a",
|
||
"callee": "15003164745"
|
||
}
|
||
}
|
||
```
|
||
回执
|
||
> 队列 agent\-call\.saas\.v1
|
||
>
|
||
>
|
||
开始调度执行
|
||
```JSON
|
||
{
|
||
"event_id": "7cd23165-c88e-4f36-8cf2-b5e9ac67ecdb",
|
||
"event_type":: "call.execute",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"tenant_id": 1001,
|
||
"issued_at": "2026-09-18T10:00:00+08:00"
|
||
"payload": {
|
||
"status": "dispatched",
|
||
}
|
||
}
|
||
```
|
||
完成结果上报
|
||
成功
|
||
```JSON
|
||
{
|
||
"event_id": "call-result-001",
|
||
"event_type": "call.execute.result",
|
||
"dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
|
||
"tenant_id": 1001,
|
||
"issued_at": "2026-09-18T10:10:15+08:00",
|
||
"payload": {
|
||
"task_id": "task-a",
|
||
"caller_profile_id": "caller-a",
|
||
"callee": "15003164745",
|
||
"trunk_id": "trunk-a",
|
||
"started_at": "2026-09-18T10:00:00+08:00",
|
||
"ended_at": "2026-09-18T10:10:00+08:00",
|
||
"duration_ms": 600000,
|
||
"outcome": "answered",
|
||
"reason_code": null,
|
||
"transcript": [
|
||
{
|
||
"turn_id": "turn-1",
|
||
"segment_id": "segment-1",
|
||
"role": "user",
|
||
"text": "示例转写内容",
|
||
"start_ms": 1000,
|
||
"end_ms": 2500
|
||
}
|
||
],
|
||
"opt_out": false,
|
||
"recording": {
|
||
"status": "uploaded",
|
||
"bucket": "example-bucket",
|
||
"object_key": "calls/tenant-a/call-a.wav",
|
||
"format": "wav",
|
||
"channels": 1,
|
||
"sample_rate_hz": 8000,
|
||
"duration_ms": 600000,
|
||
"size_bytes": 9600000,
|
||
"checksum_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
无应答
|
||
```JSON
|
||
{
|
||
// ...
|
||
"payload": {
|
||
//...
|
||
"outcome": "no_answer",
|
||
"reason_code": 480,
|
||
"reason_message": "SIP ring timeout Reason",
|
||
"transcript": [],
|
||
"opt_out": false,
|
||
"recording": {}
|
||
}
|
||
}
|
||
```
|
||
|