跳转到主要内容
电话线路对设备网关来说就是一路 SIP,和接 SIP 会议终端走的是同一套能力:来电在频道里是一名普通成员, 可以和 SAI Agent 对话,也可以进 SMeeting 会议。不需要专门的电话硬件—— 运营商的 SIP Trunk 或客户已有的 IP-PBX 都能直接对接。
按被叫号码分流、电话按键转发、平台拒绝时立即拒接来电,需要设备网关 1.3.5 及以上。

工作原理

关键在 agent_join 回调:网关只把被叫号码(no)和主叫(name)交给平台,进哪个频道、要不要接,由你的业务后端决定。

三种接法

会议电话入会(来电后输入会议号)需要 IVR 收号,由客户 PBX 完成后再转给网关;网关本身没有语音导航。AI 电话不需要收号,拨通即对话。

网关配置

配置在设备网关的 options.xml,改完重启网关生效。

监听与公网地址

SIP 端口和 RTP 端口段要在防火墙放通,见网络与端口要求。 UseRtpAddress 为 true 时,网关把语音回发到对端实际发来 RTP 的地址,对端在 NAT 后面也能听到声音。

来电进哪个应用

前缀匹配的是被叫号码。接运营商号码时,直接用号码本身(或号段)做前缀。

注册到运营商或 PBX(可选)

来电 IP 白名单(接公网线路时必开)

SIP 端口暴露在公网后会持续收到扫描呼叫。网关自带自动黑名单(同一 IP 30 秒内超过 5 次即封禁), 扫描不会进入入会流程;接运营商线路时对端 IP 是固定的,再打开白名单,只接受线路侧的来电:
支持单个 IP、IP 范围和 CIDR,仅 IPv4。

业务后端:每通电话一个频道

在 AI 电话应用上设置回调,订阅 agent_join。收到回调时:
  1. 判断是不是电话:type 为 2(SIP),no 是被叫号码
  2. 为这通电话生成一个唯一频道名,例如 phone- 加随机串
  3. 用回调里的 uid 调获取加入频道token,拿到设备的 sid
  4. 异步拉起 Agent 加入同一频道,不要等 Agent 入会再返回
  5. 回调返回 {"code": 0, "data": "<sid>"};返回非 0 即拒接,网关回 603
agent_join 是同步回调,平台等待约 5 秒,超时视为失败。拉起 Agent、加载模型这类耗时操作放到回调返回之后。
字段说明和返回格式见回调事件接入指南。 Agent 只听话机的声音:部署了 MCU 时,平台会为 SIP 设备在频道里发布合成流(uid __mcu__),其中包含 Agent 自己的声音。 Agent 订阅全部音频时要按发送者过滤,只把设备 uid(agent_join 回调里的 uid)的音频送进语音识别, 否则 Agent 会听到自己说话、被自己打断。

电话按键

网关收到按键后,以设备身份向频道发一条自定义消息: Python SDK 里用 on_custom_msg 接收,例如交给 pipecat 管线处理:

挂断

  • 来电方挂机:设备离开频道,Agent 收到成员离开事件后结束会话
  • 业务侧挂断(例如 AI 说完告别语):调踢人接口把设备 uid 踢出频道,平台通知网关给线路发 BYE

常见问题

接 SIP 会议终端的配置见 SIP / H.323 终端;AI 侧接入见接入 pipecat。