本文是《从零搭建 AI + 人工呼叫中心》的补充篇。主篇做的是"呼入":客户打进来,AI 接听。本篇反过来做"外呼":系统按名单拨出去,客户接通后由 AI 进行回访,需要时转人工。
用到的代码在配套代码包里:
dialer.py(外呼任务)、bot/scenes.py(外呼话术)、拨号计划里的 8100 分机。下载地址:https://www.liaoxinghui.com/upload/ai-callcenter-demo.zip
目录
- 1. 整体流程
- 2. 关键设计:接通后再交给 AI
- 3. 三种路由模式与推流方向
- 4. 外呼 AI 分机与话术
- 5. dialer.py 逐段讲解
- 6. 用软电话模拟客户,跑通一次
- 7. 接入真实线路
- 8. 外呼特有的问题
- 9. 并发怎么定
- 10. 合规提醒
- 11. 常见问题
1. 整体流程
dialer.py FCC FreeSWITCH AI 机器人 客户
│ POST /calls │ │ │ │
├────────────────────►│ originate … &park()│ │ │
│ ├───────────────────►│ ─────────── 呼叫 ─────────────────────────►│
│◄── call.ringing ────┤◄───── 180/183 ─────┤ │ │
│ │ │◄──────────── 接听 ─────────────────────────┤
│◄── call.answered ───┤ │ park │ │
│ POST transfer 8100 │ │ │ │
├────────────────────►│ uuid_transfer ────►│ 8100:taering_stream start ─────────────►│ │
│ │ │ start 帧 metadata.scene=outbound
│ │◄──────────── GET /calls/{call_id}(查被叫号码 → 客户资料)──────┤
│ │ │◄════════ AI 开场白、对话 ══════════════════╪═══►│
│ │ │ │ [转人工] │
│ │◄──── POST /calls/{uuid}/transfer 7000 ───────┤ │
│◄── queue.* ─────────┤ │ 7000:stop 推流 → 排队 → 坐席接听 │
│◄── call.hangup ─────┤ │ │
│ 记录结果,补拨下一个 │ │ │和呼入相比,多出来的部分是:谁来发起呼叫、什么时候交给 AI、怎么控制并发、结果记在哪里。这些都由 dialer.py 负责。
2. 关键设计:接通后再交给 AI
FCC 发起外呼时,实际执行的命令是:
originate {origination_uuid=<uuid>,fcc_call_id=<call_id>,origination_caller_id_number=<caller>}<endpoint> &park()也就是说,客户接听以后,这条通道会停在 park,什么都不做。dialer 收到 call.answered 后,再用 FCC 把它转到外呼 AI 分机 8100。
为什么不在 originate 时直接进 AI?
ringing不是接通。运营商在振铃阶段会通过 183 早期媒体播放彩铃,或者"您拨打的电话已关机/空号"之类的提示音。如果这时就开始推流,AI 会对着提示音说话,还会浪费 ASR 和推流授权。- 把并发占用压到最小。推流授权、ASR 连接、大模型并发都只在真正接通后才占用。外呼接通率往往不高,这一点对成本影响很大。
- 业务后端掌握时机。接通后可以先做判断(比如这个号码今天是否已经接通过一次),再决定交给 AI、交给人工,还是直接挂断。
另一种写法是:不转 8100,而是在 call.answered 时直接调用推流模块的 HTTP 接口,在这条通道上启动推流(见系列 1 的 6.4 节)。两种方式的对比:
| 转到 8100(本文采用) | 直接调用推流 HTTP 接口 | |
|---|---|---|
| 依赖 | 只需要 FCC | 需要开启推流模块的 HTTP 接口 |
| 传 metadata | ✅ 拨号计划里可以带 | ❌ HTTP 启动不支持 metadata,只能传 external_id |
| 通道保持 | 8100 里的 park |
原来 originate 的 park |
| 推流失败兜底 | 拨号计划里可以直接转人工 | 业务后端自己处理 |
3. 三种路由模式与推流方向
FCC 外呼有三种路由模式,生成的 endpoint 不同,推流时的方向也不同:
route_mode |
endpoint | FCC 持有的通道 | 推流方向 |
|---|---|---|---|
user |
user/<callee>@<domain> |
直接打给已注册分机的通道 | 常规:采集读、注入写 |
direct_gateway |
sofia/gateway/<gateway>/<callee> |
直接打给运营商的通道 | 常规:采集读、注入写 |
dialplan |
loopback/<callee>/<context> |
loopback 的 A 腿 | 模块自动反转:采集写、注入读 |
3.1 user:测试用
呼叫一个已经注册的分机,用来在没有运营商线路时调试整个流程(第 6 章)。
3.2 direct_gateway:生产首选
直接通过指定网关呼出,不经过拨号计划,没有额外的 loopback 通道。编码协商发生在 FreeSWITCH 和运营商之间,推流方向是常规的。
3.3 dialplan:需要拨号计划做路由时
loopback/<callee>/<context> 会创建两条通道:
FCC 持有 ──► loopback A 腿 ◄═══ 内部 ═══► loopback B 腿 ──► 拨号计划 ──► 网关 ──► 客户
(park,后来转 8100) (bridge 到运营商)客户的声音是从 B 腿经过 loopback 内部"写"进 A 腿的。所以在 A 腿上:
- 客户的声音出现在写方向;
- 要让客户听到 AI,要注入到读方向。
推流模块通过通道变量 loopback_leg=A 自动识别并反转方向,你不需要做任何设置。开启 log_debug 后,日志里会看到 capture_dir=write inject_dir=read。
使用 dialplan 模式时还要注意:
- FreeSWITCH 1.10.12 的 loopback 内部使用
L16/8000。FCC 已经设置了media_mix_inbound_outbound_codecs=true,让拨号计划后续呼出时使用网关自己的编码偏好,但推流时的采样率可能是 8000,以 start 帧为准; - FCC 禁用了 loopback 的自动退出(bow-out),所以转接、排队之后,FCC 持有的 UUID 仍然有效,能一直跟踪到客户挂机;
- 部分终端或网关会拒绝 loopback 的媒体协商。能用
direct_gateway的话就优先用它。
4. 外呼 AI 分机与话术
4.1 拨号计划
<extension name="tutorial_outbound_ai">
<condition field="destination_number" expression="^8100$">
<action application="answer"/>
<action application="taering_stream" data="start - mono 16k {"scene":"outbound","call_id":"${fcc_call_id}"}"/>
<action application="execute_extension" data="tutorial_stream_failed XML default"/>
<action application="park"/>
<action application="hangup"/>
</condition>
</extension>answer:通道已经接通,这一步不会有副作用,保留它是为了这个分机单独测试时也能用;${fcc_call_id}:FCC 外呼时写进通道的变量。放进 metadata 后,机器人就知道这是哪一通外呼;scene=outbound:告诉机器人使用外呼话术。
4.2 机器人按场景选话术(bot/scenes.py)
async def prepare(metadata: dict) -> tuple[str, str]:
if metadata.get("scene") != "outbound":
return config.GREETING, config.SYSTEM_PROMPT # 呼入:主篇的客服话术
call = await fcc.get_call(metadata["call_id"]) # 用 call_id 向 FCC 查被叫号码
customer = _find_customer(call["callee"]) # 再从 data/customers.csv 找客户资料
prompt = OUTBOUND_PROMPT.format(name=…, plan=…, months=…)
greeting = OUTBOUND_GREETING.format(name=…)
return greeting, promptbot/server.py 在会话开始时调用它,用返回的开场白和提示词替换默认值。真实业务里,_find_customer 应该换成查询你的 CRM。
外呼话术的系统提示词(节选):
你是宽带公司的回访专员"小安",正在给老客户打电话,做一次简短的满意度回访并推荐提速。
客户资料:姓名 {name},当前套餐 {plan},在网 {months} 个月。
2. 流程:确认对方身份 → 询问最近网络使用是否满意 → 如果满意,推荐升级 → 礼貌结束。
3. 客户表示不方便、没兴趣或要求不要再打来时,立即道歉并结束,不要纠缠。
4. 客户有投诉、要办理业务或要求人工时,告知马上转接,并在回复末尾加上标记 [转人工]。
5. 通话结束时礼貌道别,并在回复末尾加上标记 [挂机]。和呼入相比,外呼话术要特别写清楚两件事:怎样确认对方身份,以及客户拒绝时立刻结束。
5. dialer.py 逐段讲解
5.1 任务与幂等键
def load_tasks(self) -> None:
with (HERE / "data" / "outbound_tasks.csv").open(encoding="utf-8") as f:
for i, row in enumerate(csv.DictReader(f)):
row["request_id"] = f"dial-{self.batch}-{i}" # 批次 + 序号
self.pending.put_nowait(row)request_id 代表"这一批次里对这个客户的这一次拨打"。网络超时重试时复用它,FCC 保证只拨一次(原理见系列 2 第 5 章)。
5.2 先连事件流,再拨号
async with connect(config.FCC_WS_URL, …) as ws:
await ws.send(json.dumps({"type": "client.hello", …}))
await ws.recv()
await self.refill() # 握手完成后才开始拨号
async for raw in ws: …顺序很重要:如果先拨号再连 WebSocket,被叫号码很快接通或挂断时,call.answered / call.hangup 可能在连接建立之前就发出了,dialer 会漏掉。
5.3 补量:只在挂机时
async def refill(self) -> None:
async with self.lock:
while len(self.active) < self.args.concurrency and not self.pending.empty():
task = await self.pending.get()
res = await fcc.originate(task["request_id"], task["phone"], …)
if res.get("code") == "OK":
self.active[res["data"]["call_id"]] = {**task, "phase": "dialing"}
elif res.get("code") == "RATE_LIMITED":
await self.pending.put(task) # 放回去,稍后用同一个 request_id 重试
await asyncio.sleep(1)
break
else:
self.save(task, "originate_failed", res.get("code", ""))active以call_id为键,保存当前在途的通话;- 加锁是因为多个通话可能同时挂机、同时触发补量,没有锁就会超发;
- 遇到
RATE_LIMITED(FCC 并发或 CPS 达到上限),把任务放回队列,稍后用同一个request_id重试。
5.4 事件处理
async def on_event(self, ev):
call_id = ev["data"].get("call_id")
task = self.active.get(call_id)
if not task:
return # 不是本 dialer 发起的通话,忽略
if ev["type"] == "call.answered":
task["phase"] = "ai"
await fcc.transfer(call_id, config.OUTBOUND_AI_EXTENSION)
elif ev["type"] == "queue.bridged":
task["phase"] = "human"
elif ev["type"] == "call.hangup":
self.active.pop(call_id, None)
result = {"no_answer": "no_answer"}.get(ev["data"].get("status"), task["phase"])
self.save(task, result, ev["data"].get("hangup_cause", ""))
await self.refill()- FCC 会把所有通话的事件推给每个客户端,所以先用
active过滤出自己发起的通话; call.hangup是唯一的补量触发点。queue.abandoned、queue.timeout之后一定还会有call.hangup,如果在这些事件上也补量,就会拨多;- 结果分四类:
no_answer(没接通)、dialing(接通但没进 AI,通常是 transfer 失败)、ai(AI 处理完结束)、human(转过人工)。
5.5 断线后的对账
async def reconcile(self) -> None:
for call_id in list(self.active):
call = await fcc.get_call(call_id)
if call["status"] in ("hangup", "no_answer"):
await self.on_event({"type": "call.hangup", "data": call})收到 resume.failed 时,逐个查询在途通话,把断线期间已经结束的补处理掉。完整的对账策略见系列 2 第 7 章。
这个 dialer 是教学版:任务和结果用 CSV 文件,序号只保存在内存里,进程重启后会从头开始拨。生产环境要把任务、在途通话、结果和事件序号都放进数据库。
6. 用软电话模拟客户,跑通一次
没有运营商线路时,可以用主篇里的软电话 1001 当"客户",用 route_mode=user 呼叫它。
① 更新配置
下载最新的配套代码包,重新执行一次 ./conf/apply-conf.sh,让拨号计划里多出 8100 分机。
② 准备名单
data/outbound_tasks.csv:
phone,name
1001,张先生data/customers.csv(客户资料,机器人会用到):
phone,name,plan,months
1001,张先生,100M,26
13800138000,李女士,300M,14③ 启动
# 终端 1:AI 机器人(已经在跑就不用重启)
python -m bot.server
# 终端 2:外呼
python dialer.py --route user --concurrency 11001 振铃,接听后会听到:"您好,请问是张先生吗?我是宽带公司的回访专员小安……"
dialer 的输出(示例):
loaded 1 tasks
FCC originate 1001 -> 200 OK
FCC transfer call_3c1e… -> 200 OK
RESULT 1001 ai NORMAL_CLEARING
all tasks finished, results in data/outbound_results.csv机器人的输出:
outbound scene: call_id=call_3c1e… phone=1001 customer=张先生
[3c1e…] call start rate=16000 metadata={'scene': 'outbound', 'call_id': 'call_3c1e…'}
[3c1e…] USER: 是我,什么事?
[3c1e…] BOT: 张先生您好,想问一下您最近家里宽带用着还满意吗?
…在对话里说"我要办业务,转人工",就会和主篇一样转进队列(记得先让坐席 1002 签入)。
7. 接入真实线路
有了运营商 SIP 中继后(配置方法见系列 6):
python dialer.py --route direct_gateway --gateway gw_main --caller 02180000000--gateway:conf/sip_profiles/external/下网关的名字;--caller:主叫号码,必须是运营商分配给你、允许外显的号码,否则通常会被运营商拒绝(常见挂机原因是CALL_REJECTED或INVALID_NUMBER_FORMAT);- 被叫号码的格式(是否加 0、是否加区号)取决于运营商要求。
真实线路上,采样率通常是 8000(PCMA)。可以用 .env 把 ASR_MODEL 换成 paraformer-realtime-8k-v2 对比识别效果。
8. 外呼特有的问题
8.1 谁先说话
呼入时,客户打进来,AI 先说话很自然。外呼时,很多人接起电话会先说"喂",如果 AI 同时开口,两边会撞在一起。
可选的策略:
- 立即开场(配套代码的做法):接通后马上播开场白。客户说"喂"时会触发打断,AI 停下来听完再回答。实现简单,但开头偶尔会显得急;
- 等一下再开场:接通后等 300~800 毫秒,如果客户先说话就先听,没说话再开场。可以在
CallSession.run()里,在播放开场白之前加一个短暂等待,并检查 ASR 是否已经收到中间结果。
8.2 接通的不是本人
- 家人代接、号码已换人:话术里先确认身份,对方否认时礼貌结束;
- 语音信箱、秘书台、运营商的"来电提醒":这些服务会"接听"电话(返回 200 OK),FCC 会正常发出
call.answered。可以在提示词里让大模型识别这类录音特征(比如"请在提示音后留言"),然后直接输出[挂机];也可以在业务侧加一条规则:开场后若干秒内没有识别到任何有效回应,就挂断并标记为"疑似非人工接听"。
8.3 振铃时长与无人接听
FreeSWITCH 默认的 originate 超时是 60 秒。外呼一般不需要等这么久,超时可以在网关或拨号计划里通过 originate_timeout / call_timeout 控制,或者由 dialer 在 call.ringing 后自己计时,超时调用 hangup。
8.4 转人工时没有坐席
外呼转人工最怕客户被晾在排队音乐里。建议:
- 队列设置
max-wait-time-with-no-agent,没有坐席在线时让客户尽快出队; - 出队后在拨号计划里播放"稍后由专人回电",然后挂机,业务侧生成回电任务;
- 外呼并发要和坐席数量匹配(下一章)。
9. 并发怎么定
外呼并发 = 同时在途的通话数,受以下几项共同限制,取最小值:
| 限制 | 在哪里配置 |
|---|---|
| 推流授权并发 | mod_taering_stream 授权(试用版 1 路;商业版不限并发,联系 taering@vip.qq.com) |
| FCC | max_concurrent_calls、max_cps |
| 运营商线路 | 线路并发数、每秒呼叫数(CPS) |
| AI 服务 | ASR / TTS 并发配额、大模型 RPM |
| 坐席 | 见下面的公式 |
| 机器 | 压测结果 |
注意,推流授权只在接通后才占用,没接通的通话不占。所以在接通率较低的名单上,外呼并发可以设得比推流授权数大,但要保证"同时接通的通话数"不超过推流授权。保守做法是先让两者相等,再根据实际接通率逐步调高。
和坐席数量的关系,粗略估算:
需要的坐席数 ≈ 外呼并发 × 接通率 × 转人工率 × (人工平均通话时长 ÷ 平均外呼周期)比如:外呼并发 20、接通率 30%、转人工率 20%、人工通话 3 分钟、一次外呼周期(振铃 + AI 对话)平均 1.5 分钟,约需 20 × 0.3 × 0.2 × 2 = 2.4 个坐席,至少安排 3 个。这只是估算,实际要用排队事件(queue.joined 到 queue.bridged 的等待时长、queue.abandoned 的比例)来校准。
10. 合规提醒
AI 外呼涉及的监管要求比呼入多,各地规定也在变化。上线前请向法务和运营商确认,至少包括:
- 外呼号码实名、用途与报备一致;
- 遵守有关营销电话的规定:拨打时段、频次,客户明确拒绝后不再拨打;
- 是否需要在开场时说明正在与 AI 通话;
- 录音、转写数据的告知、存储和使用范围;
- 名单来源合法,客户已同意接收此类电话。
技术上可以配合的做法:dialer 在拨号前检查"拒绝名单"和"今日已拨打";在提示词里要求客户拒绝时立即结束;把每通电话的转写和结果完整留档。
11. 常见问题
Q:客户接了,但 AI 不说话?
- 看 dialer 有没有输出
FCC transfer … 200。没有的话,说明没收到call.answered:确认 WebSocket 握手成功,以及通话真的接通了(不是 183 早期媒体); - 看机器人有没有
call start。没有的话,用fs_cli查看日志,确认 8100 已经加载(执行过reloadxml),以及taering_stream_result不是-ERR。
Q:dialplan 模式下 AI 能说话,但听不到客户?
loopback 腿的方向问题。确认推流模块是 0.55 或更新的版本(taering_stream version 里有 capture_route=loopback-aware),并开启 log_debug 查看 capture_dir。
Q:一个客户被打了两次?
检查 request_id:是不是每次请求都重新生成了随机值?是不是在 queue.* 事件上也触发了补量?
Q:开场白被吞掉了前半句?
一般是 AI 开口时,运营商的媒体通道还没完全建立。可以在开场白前加 300~500 毫秒等待(见 8.1)。
Q:机器人日志里客户资料是空的?
data/customers.csv 里的号码要和 FCC 记录的被叫号码(callee)完全一致,包括前缀。
相关链接
- 主篇:https://www.liaoxinghui.com/archives/freeswitch-ai-callcenter-from-scratch
- mod_fcc:https://github.com/taering365/mod_fcc
- freeswitch_stream_mod:https://github.com/taering365/freeswitch_stream_mod
- 配套代码: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