三方会议接口(呼叫第三方 / 三方通话 / 多方会议 / 成员管理)

适用于:坐席通话中请求第三方支援——先与第三方私下沟通再决定三方通话或转接;或直接把双方拉进多方会议并继续邀请更多成员。 配套:配合 websocket-call-state 订阅坐席分机可实时观察各阶段通话状态。

所有 callctrl 接口均为 GET http://{cti_host}:12121/bridge/callctrl,HTTP 状态码恒为 200,业务码写在响应体。

1. 两条业务路径

路径 A:先谈后合(CALL_THIRD 系列)路径 B:快速会议(CONFERENCE 系列)
过程坐席通话中呼叫第三方,客户听等待音乐;坐席先与第三方通话,再选择升级三方/转接/放弃一步把当前通话双方+第三方拉进会议
适用需要先与第三方确认情况(显转、求助)明确要开多方通话,后续可继续加人
接口CALL_THIRD → (GET_THIRD_STATE) → CALL_THIRD_CONFERENCE / CALL_THIRD_TRANSFER / CALL_THIRD_RESUMECONFERENCE_CREATE → CONFERENCE_JOIN → KICK_OUT_OF_CONFERENCE / 成员查询
成员上限三方多方(受会议资源限制)

2. 路径 A:通话中呼叫第三方

2.1 发起:CALL_THIRD

坐席(801)与客户通话中,呼叫第三方(802 或外部号码)。CTI 先给客户播放等待音乐,再让坐席与第三方通话:

GET http://{cti_host}:12121/bridge/callctrl?callee=801&target=802&opt=CALL_THIRD
参数必填说明
caller 或 callee二选一坐席的分机号:坐席是当前通话的被叫侧传 callee(来电场景通常如此);坐席是主叫侧传 caller(点击呼叫外呼场景)
target是第三方号码(分机号或手机/固话)
backid否true 时成功返回关联呼叫记录的 callid,否则返回 200
opt是固定 CALL_THIRD

业务码:200 成功 / 400 参数错误 / 404 找不到该坐席的相关通话 / 500 系统错误。

2.2 查第三方状态:CALL_THIRD_GET_THIRD_STATE

第三方振铃或接听后,想知道其当前状态(用于界面提示):

GET http://{cti_host}:12121/bridge/callctrl?callee=801&opt=CALL_THIRD_GET_THIRD_STATE
业务码含义
100瞃时状态,可忽略
180第三方振铃中
200第三方已接听(PSTN 线路不一定精确,需结合坐席听筒判断)
404找不到相关通话,或已经转话/建三方
603第三方忙/拒绝接听

2.3 后续三选一

目标接口说明
建立三方通话opt=CALL_THIRD_CONFERENCE坐席+客户+第三方三方通话;成功后坐席可挂机变为普通会议
显转(转给第三方)opt=CALL_THIRD_TRANSFER客户与第三方通话,坐席退出
放弃,恢复原通话opt=CALL_THIRD_RESUME挂断第三方,坐席与客户恢复通话(第三方无论振铃或已接听都可调用)

三个接口参数相同:坐席分机号(caller 或 callee,与 2.1 中一致的取法),无 target。

GET http://{cti_host}:12121/bridge/callctrl?callee=801&opt=CALL_THIRD_CONFERENCE

业务码:

接口业务码
CALL_THIRD_CONFERENCE200 成功 / 400 参数错 / 404 无相关通话(之前未调 CALL_THIRD)/ 487 有终端已挂机,无法建立三方 / 500 系统错误
CALL_THIRD_TRANSFER200 成功(坐席可挂机)/ 400 / 404 / 500
CALL_THIRD_RESUME200 成功 / 400 / 404 / 500

2.4 路径 A 时序

坐席801 ──通话中── 客户
   │ CALL_THIRD(target=802)
   ├──▶ 客户听等待音乐;坐席与第三方802通话(GET_THIRD_STATE: 180→200)
   │        ├── CALL_THIRD_CONFERENCE ─▶ 三方通话
   │        ├── CALL_THIRD_TRANSFER   ─▶ 客户↔802,坐席退出
   │        └── CALL_THIRD_RESUME     ─▶ 挂断802,坐席↔客户恢复

3. 路径 B:快速会议

3.1 创建会议:CONFERENCE_CREATE

坐席与客户通话中,一步创建三方会议(当前通话双方 + target),会议号 = 创建坐席的分机号:

GET http://{cti_host}:12121/bridge/callctrl?caller=135xxxxxxxx&callee=801&target=802&opt=CONFERENCE_CREATE
参数必填说明
caller是当前通话的主叫号码
callee是当前通话的被叫号码
target是被邀请加入会议的号码(分机/手机/固话)
opt是固定 CONFERENCE_CREATE

业务码:200 成功(可继续邀请)/ 400 参数错误 / 404 找不到相关通话 / 483 重复创建(该坐席已有会议)/ 486 被邀请电话忙 / 503 系统资源不足。

3.2 继续邀请成员:CONFERENCE_JOIN

GET http://{cti_host}:12121/bridge/callctrl?conferenceid=801&target=159XXXXXXXX&opt=CONFERENCE_JOIN
参数必填说明
conferenceid是会议编号,一般用创建会议的坐席分机号
target是被邀请加入的号码
opt是固定 CONFERENCE_JOIN

业务码:200 成功 / 404 会议不存在 / 480 会议正在创建,稍后再试 / 486 被邀请电话忙 / 503 资源不足。

3.3 踢出与会人:KICK_OUT_OF_CONFERENCE

GET http://{cti_host}:12121/bridge/callctrl?extnum=801&target=808&opt=KICK_OUT_OF_CONFERENCE
参数必填说明
extnum是创建会议的分机号
target是要踢出的成员号码
opt是固定 KICK_OUT_OF_CONFERENCE

业务码:200 成功 / 400 参数错误 / 404 找不到相关资源 / 500 系统错误。

4. 会议成员查询(GET /bridge/conference)

查询某分机所在的会议及全部成员(三方通话/会议均可查):

GET http://{cti_host}:12121/bridge/conference?extnum=801
参数必填说明
extnum是会议中的任一分机号(优先按会议号匹配,即创建者分机)

前置条件:软参 conference.http.json.statas.offon 需为开启状态(现场配置;stauts 拼写即如此)。未开启或无会议时返回 {}。

响应示例

{
  "conferenceId": "806",
  "stauts": 1,
  "talkTime": 4,
  "timeStamp": "2022-05-24 16:19:33",
  "participants": [
    { "telnum": "15875566080", "timeStamp": "2022-05-24 16:19:34", "talkTime": 3, "stauts": 1, "owner": false },
    { "telnum": "806",         "timeStamp": "2022-05-24 16:19:34", "talkTime": 3, "stauts": 1, "owner": true },
    { "telnum": "802",         "timeStamp": "2022-05-24 16:19:35", "talkTime": 2, "stauts": 1, "owner": false }
  ]
}
字段说明
conferenceId会议编号
stauts1 通话中 / 0 释放(拼写即如此)
talkTime会议时长(秒,查询时实时计算)
timeStamp会议状态变更时间
participants.telnum成员号码
participants.timeStamp / talkTime该成员加入时间 / 通话时长(秒)
participants.stauts成员状态:1 通话中 / 0 释放
participants.owner是否会议创建者(会议号本人)

监管/会控页面可 1-2 秒轮询本接口刷新成员列表(连续多次 {} 表示会议已结束,可停止轮询)。

5. curl 示例(完整三方流程)

CTI=http://192.168.1.80:12121

# 1. 坐席801(来电被叫侧)通话中呼叫第三方 802
curl "$CTI/bridge/callctrl?callee=801&target=802&opt=CALL_THIRD"

# 2. 观察第三方状态(180 振铃 → 200 接听)
curl "$CTI/bridge/callctrl?callee=801&opt=CALL_THIRD_GET_THIRD_STATE"

# 3a. 建立三方通话
curl "$CTI/bridge/callctrl?callee=801&opt=CALL_THIRD_CONFERENCE"

# 3b. 或显转给第三方(二选一)
# curl "$CTI/bridge/callctrl?callee=801&opt=CALL_THIRD_TRANSFER"

# 4. 快速会议路径:一步建会并继续加人
curl "$CTI/bridge/callctrl?caller=13512340001&callee=801&target=802&opt=CONFERENCE_CREATE"
curl "$CTI/bridge/callctrl?conferenceid=801&target=15912340002&opt=CONFERENCE_JOIN"

# 5. 查会议成员 / 踢人
curl "$CTI/bridge/conference?extnum=801"
curl "$CTI/bridge/callctrl?extnum=801&target=802&opt=KICK_OUT_OF_CONFERENCE"

6. 常见问题排查

现象原因与处理
CALL_THIRD 返回 404坐席不在通话中,或 caller/callee 传错侧(来电场景坐席是被叫,传 callee)
三方建立返回 487第三方或客户已挂机,无法再建立三方
CONFERENCE_CREATE 返回 483该坐席名下已有会议(先踢散旧会议或用 CONFERENCE_JOIN 续邀)
/bridge/conference 一直返回 {}软参 conference.http.json.stutas.offon 未开启;或确实无会议;或 extnum 不在任一会议中
会议成员查不到刚加入的人成员加入有 1-2 秒延迟,轮询即可见
三方通话与会议怎么选需要先与第三方单独沟通选路径 A;确定多方多人选路径 B