本文是《从零搭建 AI + 人工呼叫中心》的补充篇。主篇里,controller.py 只用了 FCC 的一小部分:收到来电、转到 AI。本篇讲清楚 FCC 的数据模型和可靠性语义,以及怎样在它上面写出一个不丢事件、不重复拨打、重启后能自动恢复的业务后端。
完整接口文档见 mod_fcc 仓库:https://github.com/taering365/mod_fcc。本文基于 FCC 1.2.1-open。
目录
- 1. FCC 的定位
- 2. 数据模型:call_id、uuid 和事件
- 3. 状态机与事件归属
- 4. HTTP 动作的真实含义
- 5. 幂等:怎样保证不重复拨打
- 6. WebSocket:握手、续传、背压
- 7. 对账:续传失败或 FCC 重启之后
- 8. 入呼接管与决策超时
- 9. 与 mod_callcenter 配合
- 10. 容量控制
- 11. 一个可靠的业务后端骨架
- 12. 安全与部署
- 13. 什么时候该换成 ESL
1. FCC 的定位
FCC 是运行在 FreeSWITCH 进程里的受约束的业务控制面:
业务后端 ──HTTP 命令──► FCC ──► FreeSWITCH 命令(originate / uuid_* / callcenter_config …)
业务后端 ◄──WS 事件─── FCC ◄── FreeSWITCH 事件(progress / answer / DTMF / hangup / callcenter::info)它做三件事:
- 把命令收窄:只开放白名单内的动作,并校验参数(不允许
{}、换行、单引号等能注入 FreeSWITCH 命令的字符); - 把状态归一化:把 FreeSWITCH 零散的通道事件整理成每通电话一个状态,以及有序的业务事件;
- 把标识稳定化:用
call_id贯穿一通电话的整个生命周期,包括转接和排队。
它不做的事:音频、录音、会议、ASR/TTS、坐席心跳、外呼任务调度、报表。这些都属于业务后端或其他模块。
2. 数据模型:call_id、uuid 和事件
2.1 两个标识
| 标识 | 格式 | 谁生成 | 用途 |
|---|---|---|---|
call_id |
call_<UUID> |
FCC | 业务主键。持久化它;跨重启不重复 |
uuid |
FreeSWITCH UUID | FreeSWITCH(外呼时由 FCC 指定) | 通道标识。推流模块、ESL 都用它 |
外呼时,FCC 生成 UUID 后通过 origination_uuid 指定给新通道,所以 call_id 就是 call_ 加上这个 UUID。所有 /calls/{call_id} 路径都同时接受这两种标识。
2.2 事件
每个业务事件长这样:
{"type":"call.answered","sequence":103,"timestamp_ms":1785744002500,
"data":{"request_id":"order-1","call_id":"call_…","uuid":"…","direction":"outbound",
"caller":"1000","callee":"1001","did":"","service":"","status":"answered",
"hangup_cause":"","detail":""}}sequence:全局单调递增,所有通话共用一个序号空间;data.status:事件发生后这通电话的状态快照;data.detail:事件附加信息,比如 DTMF 的按键、动作名、挂机原因。
2.3 三处保存
| 位置 | 保存什么 | 容量 | 跨重启 |
|---|---|---|---|
| 单通话事件表 | 该通话最近的事件 | 64 条 | ✗ |
| 全局事件环 | 所有通话的事件,用于 WS 续传 | 4096 条 | ✗ |
| 通话快照(内存) | 每通电话的当前状态 | 已结束的保留 call_history_ttl_sec(3600 秒),最多 call_history_max_records(10000)条 |
✗ |
| SQLite | 非空 request_id、call_id、uuid、规范化请求、终态 |
通话结束后保留 idempotency_ttl_sec(86400 秒) |
✓ |
FCC 的事件缓存不是持久消息队列。 业务状态必须落你自己的数据库。
3. 状态机与事件归属
3.1 状态
外呼: dialing ──► ringing ──► answered ──► hangup
│ │
└───────────┴──────────────────► no_answer
入呼: incoming ──► answered ──► hangup
└──► decision_timeoutringing不是接听。它对应 SIP 180/183,有可能只是运营商的彩铃或者"您拨打的用户已关机"的提示音。任何"接通后才做"的动作都要等answered。- 结束时只会有一个
call.hangup事件,用data.status区分:no_answer表示从来没接通(包括 originate 提交失败),hangup表示接通后结束。没有单独的call.no_answer事件。
3.2 事件归属
一通电话在 FreeSWITCH 里可能对应多个通道:loopback 有 A、B 两条腿,转进队列后还有坐席腿。FCC 只根据自己持有的那个 UUID 更新状态:事件的 Unique-ID 必须等于 FCC 记录的 UUID。
这保证了:
- loopback 另一条腿挂机时,不会被误判为客户挂机;
- 继承了
fcc_call_id变量的其他通道,不会产生重复的call.hangup。
例外:DTMF 事件经过传播后可能缺少 variable_fcc_call_id,这时 FCC 会按 UUID 找到自己持有的通话。
3.3 一通电话的完整事件序列
以主篇"AI 先接、再转人工"的流程为例:
call.incoming ← fcc_inbound 注册
action.accepted ← detail=transfer(controller 转到 8000)
call.answered ← 8000 执行 answer
action.accepted ← detail=transfer(AI 转到 7000)
queue.joined ← 进入 support@default
queue.agent_offered ← 选中坐席,坐席振铃
queue.bridged ← 坐席接听
queue.bridge_ended
queue.completed
call.hangup ← status=hangup,detail=NORMAL_CLEARING4. HTTP 动作的真实含义
POST /calls/{call_id}/{action} 返回 200 {"code":"OK","message":"submitted"},只表示 FreeSWITCH 接受了命令。比如:
transfer返回 200 时,目标 extension 可能还没开始执行;bridge返回 200 时,媒体可能还没接通;hangup返回 200 时,call.hangup事件还没到。
每个被识别的动作都会产生一个 action.accepted 或 action.failed 事件。以事件为准,以查询为辅。
动作和 FreeSWITCH 命令的对应关系:
| 动作 | 命令 | 备注 |
|---|---|---|
answer / pre_answer / park |
uuid_answer / uuid_pre_answer / uuid_park |
|
reject |
uuid_kill <cause> |
默认 CALL_REJECTED |
hangup |
uuid_kill |
|
hold / unhold |
uuid_hold / uuid_hold off |
对 FCC bridge 的通话会记住对端,处理保持音乐 |
clear |
uuid_break |
停止当前播放或应用,常用来打断 park 继续执行拨号计划 |
dtmf |
uuid_send_dtmf |
|
play_file |
uuid_broadcast <file> aleg |
|
transfer |
uuid_transfer … XML <context> |
|
bridge |
uuid_bridge |
other_uuid 必须是 FreeSWITCH UUID |
通话结束后,快照仍然可以查询,但所有实时动作都返回 409 COMMAND_FAILED。
5. 幂等:怎样保证不重复拨打
外呼最怕的事故是:网络超时后重试,结果同一个客户被打了两次。FCC 的 request_id 就是为此设计的。
5.1 机制
- 请求带非空
request_id时,FCC 在发起呼叫之前,先在 SQLite 里原子占位; - 同时对规范化后的
caller、callee、gateway、route_mode、route_context、user_domain计算请求指纹; - 再次收到同一个
request_id:- 指纹相同 → 不拨打,直接返回原来的
call_id/uuid和当前状态,message为idempotent replay; - 指纹不同 → 409
IDEMPOTENCY_CONFLICT;
- 指纹相同 → 不拨打,直接返回原来的
- 并发的相同请求只有一个会真正拨打;
- 记录跨模块重载和 FreeSWITCH 重启保留,通话结束后过
idempotency_ttl_sec才删除; - SQLite 不可用时返回 503
IDEMPOTENCY_UNAVAILABLE,不会在没有幂等保护的情况下拨打。
5.2 怎么生成 request_id
request_id 应该代表一次业务意图,而不是一次 HTTP 请求:
✅ campaign-20261120-客户ID-第1次尝试
✅ crm-callback-工单号
❌ 每次请求随机生成 UUID ← 重试时变了,就起不到幂等作用
❌ 只用客户号码 ← 第二天再打时会被当成重复(在 TTL 内)重试时复用同一个 request_id;需要真正再拨一次(比如第二次尝试)时,换一个新的。
5.3 重试策略
| 结果 | 处理 |
|---|---|
| 网络超时、连接断开 | 用同一个 request_id 重试,安全 |
| 200 | 记录 call_id |
409 IDEMPOTENCY_CONFLICT |
代码有 bug:同一个 key 用在了不同的请求上 |
409 ORIGINATE_FAILED |
提交失败,这次尝试结束(已产生 call.hangup,status=no_answer) |
429 RATE_LIMITED |
达到并发或 CPS 上限,退避后用同一个 request_id 重试 |
| 503 | FCC 的 SQLite 有问题,告警,暂停外呼 |
6. WebSocket:握手、续传、背压
6.1 握手
客户端 → Upgrade(带 Authorization: Bearer <token>)
客户端 → {"type":"client.hello","request_id":"h1","client_id":"worker-1","protocol_version":1,"last_sequence":<已处理的最大序号>}
FCC → {"type":"server.hello","code":"OK","data":{"current_sequence":…,"oldest_sequence":…,"resume_supported":true,"heartbeat_interval_ms":15000,…}}
FCC → 补发 last_sequence 之后、仍在环里的事件
FCC → 实时事件 …- 首帧不是 hello →
server.error/HELLO_REQUIRED,连接关闭; - 协议版本不对 →
server.hello/UNSUPPORTED_PROTOCOL,连接关闭; - 没完成握手的连接收不到任何事件。
6.2 续传
last_sequence=0:不补发,只接收之后的新事件;last_sequence=N:补发所有sequence > N并且仍在 4096 条环里的事件;- N 已经被挤出环:收到
{"type":"resume.failed","code":"SEQUENCE_EXPIRED"},需要对账(见第 7 章)。
server.hello 里的 oldest_sequence 和 current_sequence 可以让你预先判断能否续传。
持久化序号的时机:处理完一个事件、业务状态写入数据库之后,再保存它的 sequence。先保存再处理,崩溃时就会丢事件;处理完再保存,最坏情况是重复处理一次,所以业务处理本身也要幂等(按 sequence 去重)。
event.ack 可以发,但 FCC 当前会忽略它,不影响事件保留。
6.3 心跳与背压
- FCC 每 15 秒发一次 Ping,45 秒内收不到 Pong 就断开。大多数 WebSocket 库会自动回 Pong;
- 每个客户端最多积压 1000 条待发消息,超过就断开这个"慢消费者"。所以不要在事件循环里做慢操作(同步数据库写入、调用大模型),把事件放进内部队列,交给其他协程或线程处理。
6.4 用 WebSocket 发命令
除了 HTTP,也可以在同一条 WebSocket 上发命令:
{"type":"call.create","request_id":"c-1","callee":"1001","caller":"1000","route_mode":"user"}
{"type":"call.query","request_id":"q-1","call_id":"call_…"}
{"type":"call.transfer","request_id":"t-1","call_id":"call_…","destination":"7000","context":"default"}结果以 <type>.result 返回,response 字段里是对应 HTTP 接口的返回体。call.create 里的 request_id 同时也是幂等键。坐席和队列接口只有 HTTP 版本。
6.5 一条连接还是多条
FCC 会把所有事件推送给每一个完成握手的客户端。推荐:
- 每个业务后端进程维持一条 WebSocket;
- 后端内部按
call_id分发给各自的状态机; - 浏览器、坐席工作台等前端连接你自己的后端,不要直连 FCC。
多个后端进程同时连接时,每个进程都会收到全部事件,需要自己按业务归属过滤(比如外呼进程只处理自己发起的 call_id)。
7. 对账:续传失败或 FCC 重启之后
以下情况会导致事件缺失:
- 断线太久,
SEQUENCE_EXPIRED; - FCC 模块重载或 FreeSWITCH 重启,内存里的事件环清空,序号重新开始。
这时用 HTTP 查询逐个恢复:
1. 从自己的数据库取出所有"未结束"的 call_id
2. 逐个 GET /calls/{call_id}
├── 404 CALL_NOT_FOUND:内存快照已过期或 FCC 重启过 → 按"结果未知"处理,人工核查或标记失败
├── status = hangup / no_answer:补执行"通话结束"的业务逻辑
└── 其他:更新本地状态,继续等待事件
3. 对账完成后,再恢复外呼补量等会产生新呼叫的逻辑判断 FCC 是否重启过:server.hello 里的 current_sequence 小于你保存的序号,说明序号重新开始了。这时应该清空保存的序号(从 0 开始),并执行一次完整对账。
重启时哪些通话能恢复,要分情况看:
| 情况 | 带非空 request_id 的外呼 |
入呼、空 request_id 的外呼 |
|---|---|---|
只重载 FCC 模块(reload mod_fcc) |
从 SQLite 恢复到内存,包括还没结束的;之后的事件按 UUID 继续更新 | 不会恢复,后续事件不再推送,查询返回 404 |
| FreeSWITCH 整体重启 | 通话本身已经断开;恢复出来的记录如果重启前还没结束,可能停留在挂机前的状态 | 同左,且查询返回 404 |
所以:
- 外呼务必带
request_id,它不仅防重复,也让模块重载后还能继续跟踪; - FreeSWITCH 整体重启后,把"重启前还没结束"的通话统一标记为异常结束,不要等它们的
call.hangup; - 生产环境避免在业务高峰期重载 FCC 或重启 FreeSWITCH。
8. 入呼接管与决策超时
8.1 机制
<action application="fcc_inbound" data="service=customer_service"/>
<action application="park"/>
<!-- 超时兜底 -->
<action application="transfer" data="7000 XML default"/>fcc_inbound注册通道,设置fcc_call_id、fcc_direction=inbound、fcc_service、fcc_register_status,发布call.incoming;不应答、不接管路由;- 参数必须写成
service=xxx,否则 service 记为default; - 达到并发或 CPS 上限时,
fcc_register_status=rate_limited,并以USER_BUSY挂机; - 后端在
inbound_decision_timeout_ms(默认 5000)内做出决策; - 超时后发布
call.decision_timeout,然后:continue_dialplan(默认):执行uuid_break打断park,拨号计划继续往下执行兜底逻辑;hangup:直接挂断。
8.2 决策的写法
async def on_incoming(data):
call_id = data["call_id"]
caller, did, service = data["caller"], data["did"], data["service"]
if in_blacklist(caller):
return await fcc.action(call_id, "reject", {"cause": "CALL_REJECTED"})
if not in_business_hours():
return await fcc.transfer(call_id, "voicemail")
if is_vip(caller):
return await fcc.transfer(call_id, "7000") # VIP 直接转人工
return await fcc.transfer(call_id, "8000") # 其余交给 AI8.3 超时多长合适
- 决策逻辑要查数据库、调 CRM 时,留足时间,但不要让客户等在静默里太久:可以在
park之前先answer并播放一段提示音,或者用pre_answer加早期媒体; - 兜底逻辑要能独立工作:后端整体不可用时,客户应该被送到一个"最安全"的地方,比如人工队列或留言。
9. 与 mod_callcenter 配合
9.1 分工
| 负责方 | |
|---|---|
| 员工登录、心跳、超时自动下线 | 业务后端 |
| SIP 注册 | 软电话 / 浏览器(SIP over WSS) |
| 坐席创建、签入、签出、暂停、恢复 | 后端调用 FCC |
| 排队、选坐席、振铃、拒接惩罚、话后整理 | mod_callcenter |
| 队列事件 → 业务事件 | FCC |
9.2 坐席接口要点
- FCC 创建的是 callback 类型坐席,contact 由 FCC 内部生成:
[leg_timeout=20]user/<extension>@<domain>; - 初始状态
Logged Out,同时加入指定队列(tier); sign-in/resume会先检查 SIP 注册,未注册返回 409AGENT_NOT_REGISTERED;sign-out/pause只阻止新的分配,不会挂断正在进行的通话;- 生命周期动作是幂等的状态赋值,可以放心重试;
GET /callcenter/agents/{id}返回的registered和status互相独立。
坐席心跳的推荐做法:
坐席工作台每 15 秒向业务后端发心跳
业务后端:60 秒没收到心跳 → POST /callcenter/agents/{id}/sign-out
坐席重新上线 → 确认 registered=true → sign-in9.3 队列事件
FCC 订阅 callcenter::info,用 CC-Member-Session-UUID 把队列事件关联到原始 call_id:
| FCC 事件 | mod_callcenter 动作 | 用途 |
|---|---|---|
queue.joined |
member-queue-start / resume | 开始排队,计算排队时长的起点 |
queue.agent_offered |
agent-offering | 选中坐席,开始振铃 |
queue.bridged |
bridge-agent-start | 坐席接听;agent_uuid 是坐席腿的 UUID |
queue.bridge_ended |
bridge-agent-end | 人工通话结束 |
queue.abandoned |
member-queue-end(Cancel) | 排队中客户挂机 |
queue.timeout |
member-queue-end(TIMEOUT / NO_AGENT_TIMEOUT) | 排队超时 |
queue.completed |
member-queue-end(Terminated) | 正常结束 |
queue.bridged 里的 agent_uuid 很有用:系列 4 就是用它在坐席腿上开启质检推流。
队列终态之后一定还会有
call.hangup。统计排队结果看队列事件,驱动"通话结束"逻辑只看call.hangup,否则会重复处理。
10. 容量控制
| 配置 | 含义 | 超限表现 |
|---|---|---|
max_concurrent_calls |
已注册、尚未挂机完成的通话数(入呼 + 外呼) | 外呼 429 RATE_LIMITED;入呼 USER_BUSY 挂机 |
max_cps |
每个自然秒内新建的通话数(入呼外呼共用) | 同上 |
实际可用并发取以下几项的最小值:FCC 配置、线路并发、推流模块授权并发、AI 服务的并发配额、坐席数量(转人工比例 × 并发)、机器压测结果。
监控指标(GET /metrics,Prometheus 格式):fcc_active_calls、fcc_calls_created_total、fcc_calls_rejected_total、fcc_http_requests_total、fcc_errors_total。fcc_calls_rejected_total 持续增长,说明业务侧的并发控制和 FCC 配置不一致。
11. 一个可靠的业务后端骨架
把上面的规则合在一起,一个可靠的事件消费者应该长这样:
import asyncio, json
from websockets.asyncio.client import connect
class FccConsumer:
def __init__(self, db, handler):
self.db = db # 你的数据库:保存 last_sequence、活动 call_id、业务状态
self.handler = handler # 业务处理:async def handle(event),必须幂等
self.queue = asyncio.Queue(maxsize=10000)
async def run(self):
asyncio.create_task(self.worker())
while True:
try:
async with connect(WS_URL, additional_headers=AUTH, ping_interval=None) as ws:
saved = await self.db.get_last_sequence()
await ws.send(json.dumps({"type": "client.hello", "request_id": "h",
"client_id": "biz-1", "protocol_version": 1,
"last_sequence": saved}))
hello = json.loads(await ws.recv())
if hello["data"]["current_sequence"] < saved: # FCC 重启过
await self.db.set_last_sequence(0)
await self.reconcile()
async for raw in ws: # 只负责收,不做慢操作
ev = json.loads(raw)
if ev.get("type") == "resume.failed":
await self.reconcile()
elif "sequence" in ev:
await self.queue.put(ev)
except Exception:
await asyncio.sleep(2)
async def worker(self):
while True:
ev = await self.queue.get()
if await self.db.seen(ev["sequence"]): # 去重
continue
await self.handler(ev) # 先处理、落库
await self.db.set_last_sequence(ev["sequence"]) # 再保存序号
async def reconcile(self):
for call_id in await self.db.active_call_ids():
... # GET /calls/{call_id},按第 7 章处理要点回顾:
- 一条 WebSocket,收事件和处理事件分开;
- 先处理再保存序号,处理本身按
sequence去重; - 发现 FCC 重启或续传失败,先对账再继续;
- 外呼一律带稳定的
request_id; - 驱动"通话结束"的只有
call.hangup。
主篇的 controller.py 和系列 3 的 dialer.py 是这个骨架的简化版。
12. 安全与部署
- Token:所有接口(包括健康检查、指标、OPTIONS、WebSocket Upgrade)都要 Bearer Token。同一 IP 在
auth_failure_window_sec(60 秒)内失败auth_max_failures(5)次,锁定auth_lockout_sec(300 秒),期间返回 429AUTH_LOCKED; - 监听:默认只监听 127.0.0.1。模块只提供明文 HTTP/WS,跨机器访问必须加 TLS 反向代理、防火墙和来源限制。Nginx 配置示例见 mod_fcc 仓库的 README;
- 输入:不要把用户输入直接当作
callee(含/时会被当成完整 endpoint)、file、gateway、destination或队列名; - 请求:只支持定长请求体(
Content-Length),最大 1 MiB,5 秒内必须收完;不支持Transfer-Encoding: chunked(返回 501)。
13. 什么时候该换成 ESL
FCC 适合快速验证业务、搭建标准的呼叫中心流程。出现下面这些需求时,说明该直接使用 ESL(或者在 FCC 旁边加一个 ESL 程序)了:
- 需要 FCC 白名单以外的命令:录音(
uuid_record)、会议、设置任意通道变量、uuid_setvar等; - 需要订阅 FCC 没有转换的原始事件,比如推流模块的
taering_stream::*事件; - 需要按通道粒度精细控制媒体(比如三方通话、监听、强插);
- 单机并发很高,需要把控制面从 FreeSWITCH 进程里拆出去。
FCC 和 ESL 可以共存:用 FCC 做呼叫和坐席的主流程,用 ESL 补充 FCC 不覆盖的部分。
相关链接
- mod_fcc(含双语接口文档):https://github.com/taering365/mod_fcc
- 主篇:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- 配套代码:https://www.liaoxinghui.com/upload/ai-callcenter-demo.zip
系列文章
- 主篇:从零搭建 AI + 人工呼叫中心:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- 系列 1:mod_taering_stream 媒体协议详解:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-01-stream-protocol
- 系列 2:FCC 控制面深入:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-02-fcc
- 系列 3:AI 外呼:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-03-outbound
- 系列 4:实时质检与坐席辅助:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-04-qa-assist
- 系列 5:延迟优化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-05-latency
- 系列 6:接入运营商线路:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-06-carrier
- 系列 7:生产化:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-07-production
- 系列 8:排障手册:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-08-troubleshooting