呼叫记录查询接口

适用于:OA/CRM 中展示通话历史(来电/去电/未接)、通话详情、关联录音。 配套:录音下载见 recording-download。

所有接口均为 GET http://{cti_host}:12121/bridge/callctrl,HTTP 状态码恒为 200,结果为 JSON 数组(或业务码文本)。

opt用途说明
CALL_LOG_QUERY通用记录查询全量字段,支持多条件过滤、翻页
EXTNUM_CALL_LOG_QUERY分机视角查询按"某分机的通话列表"组织,返回对端号码+方向,适合坐席个人通话页
EXTNUM_CALL_LOG_COUNT分机视角计数与上者同条件,返回总条数
CALL_LOG_GET_WITH_CALLID按 callid 精确查单条记录;点击呼叫 backid 返回的 UUID 亦可用此查询

1. CALL_LOG_QUERY(通用查询)

GET http://{cti_host}:12121/bridge/callctrl?first=0&maxResults=20&beginDate=2026-09-01&endDate=2026-09-13&telnum=801,13512340001&dirction=0&opt=CALL_LOG_QUERY
参数类型必填说明
firstint是行偏移(从 0 开始):第 N 页传 (N-1)*maxResults
maxResultsint是每页条数
beginDateString否起始时间 yyyy-MM-dd 或 yyyy-MM-ddTHH:mm:ss(日期与时间用 T 隔开)
endDateString否结束时间,格式同上
telnumString否相关号码(主叫或被叫匹配);多个号码用英文逗号分隔;不传查全部
dirctionint否0 全部(默认)/ 1 接听记录(呼入)/ 2 拨打记录(呼出)。参数名拼写即如此
stateString否STATE_RECEIVED 已接通 / STATE_FAILED 未接通;不传查全部
estimateString否按满意度评价过滤,多个逗号分隔(默认 1 非常满意 2 满意 3 不满意)
shortestTalkTimeint否最小通话时长(秒)
orderint否0 按时间逆序(默认)/ 1 正序
optString是固定 CALL_LOG_QUERY

响应示例

[
  {
    "id": 37,
    "caller": "13512340001",
    "callee": "816",
    "channel": "192.168.3.80",
    "beginTime": 1459160867375,
    "duration": 41,
    "state": "STATE_RECEIVED",
    "callType": "LOCAL_CALL",
    "estimate": "",
    "callid": "173a248c-8f85-4edb-b0c2-c11e1894a0d5@192.168.1.82",
    "record": "",
    "recordVoice": "",
    "cname": "",
    "servicetype": "",
    "manustate": "",
    "clickcallid": "",
    "fxonum": "",
    "business": "INCOMING",
    "clicktoken": ""
  }
]

主要字段说明

字段类型说明
idInteger记录编号(主键);录音下载可用 logId= 参数
caller / calleeString主叫 / 被叫号码
beginTimeLong开始时间(毫秒时间戳)
durationInteger通话时长(秒);STATE_FAILED 时为振铃时长
stateString见枚举 §4.1
callTypeString见枚举 §4.2
businessString见枚举 §4.3
callidString呼叫唯一标识,用于录音下载/精确查询
clickcallidString点击呼叫接口(backid=true)返回的 UUID
clicktokenString点击呼叫时传入的业务标记(用于与 OA/CRM 业务关联)
record / cname / servicetype / manustate / questionString坐席在弹屏助手录入的通话备注、客户名称、服务类型等
stttxtStringAI 通话摘要:开启 calllog.save.stttxt.offon 后,挂机由大模型按提示词模板对整通沟通生成(可为 JSON 结构,内容/格式由模板决定);详见 call-log-push
recordVoiceString录音文件在服务器上的路径(非下载 URL)
fxonumString来电落入的 FXO 端口/线路编号
ivrpoint / dtmfkeyStringIVR 转接节点 / 客户 IVR 按键
accessnumString客户呼入使用的接入号(E1 场景区分线路)
ringTime / ringDurationLong/int振铃开始时间(毫秒)/ 振铃时长(秒)
queueTime / queueDurationLong/int排队开始时间 / 排队时长(秒)
hungupsideString挂机方
estimateInteger客户评价(1/2/3)

total 分页总数:CALL_LOG_QUERY 的返回不带 total,需要总数时用相同条件改调 opt=CALL_LOG_COUNT(参数同上,响应体为数字)。

2. EXTNUM_CALL_LOG_QUERY(分机视角查询)

以"某分机的通话列表"组织:不区分主被叫,返回对端号码 telnum 和方向 drection,适合坐席个人通话历史页(demo 通话记录页即用此接口)。

GET http://{cti_host}:12121/bridge/callctrl?first=0&maxResults=10&beginDate=2026-09-13&endDate=2026-09-13&extnum=801&telnum=13512340001&opt=EXTNUM_CALL_LOG_QUERY
参数类型必填说明
firstint是行偏移(注意:与坐席监控接口 EXTNUM_MONITOR 的"页码"语义不同)
maxResultsint是每页条数
beginDateString是yyyy-MM-dd(自动补当天 00:00:00)或 yyyy-MM-ddTHH:mm:ss
endDateString是格式同上(补当天 23:59:59)
extnumString是分机号
telnumString否客户号码过滤
optString是固定 EXTNUM_CALL_LOG_QUERY

响应示例

[
  {
    "callid": "173a248c-8f85-4edb-b0c2-c11e1894a0d5@192.168.1.82",
    "telnum": "13512340001",
    "drection": 1,
    "ringtime": "2026-09-13 10:00:00",
    "ringdration": 5,
    "talktime": "2026-09-13 10:00:05",
    "talkdration": 41,
    "state": "STATE_RECEIVED",
    "recordVoice": "/opt/data/records/2026-09-13/173a248c.wav",
    "total": 37
  }
]
字段类型说明
callidString呼叫唯一标识(录音下载用)
telnumString对端号码(该分机为主叫时取被叫,反之取主叫)
drectionint方向:extnum 是主叫 → 2 外呼;否则 1 呼入。拼写即如此
ringtime / ringdrationString / int振铃开始时间 / 振铃时长(秒),无振铃为空/0
talktime / talkdrationString / int接听开始时间 / 通话时长(秒),未接通为 0
stateStringSTATE_RECEIVED / STATE_FAILED
recordVoiceString录音文件路径(有录音时非空,可作为"有录音"标志)
totalint符合条件总条数(每条都带,取第一条即可)

配套计数接口:opt=EXTNUM_CALL_LOG_COUNT(参数相同,响应体为数字)。

3. CALL_LOG_GET_WITH_CALLID(按 callid 精确查询)

GET http://{cti_host}:12121/bridge/callctrl?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82&opt=CALL_LOG_GET_WITH_CALLID
参数必填说明
callid是呼叫唯一标识。来源:WebSocket 弹屏通知的 id、点击呼叫 backid=true 返回的 UUID。@ 等字符需 URL 编码(%40)
opt是固定 CALL_LOG_GET_WITH_CALLID

返回单条记录 JSON(字段同 §1),查无记录返回空。

4. 枚举值速查

4.1 state(通话状态)

值含义
STATE_RECEIVED已接通
STATE_RECEIVING通话中(实时查询时)
STATE_FAILED未接通(IVR 放音中挂断、振铃未接、坐席拒绝、外呼未呼通等)

4.2 callType(呼叫类型)

值含义
CENTREX_CALL内部通话
LOCAL_CALL本地通话
NATIONAL_CALL国内长途
OVERSEAS_CALL国际长途
UNKNOW_CALL未知

4.3 business(业务类型)

值含义典型场景
INCOMING呼入电话普通外线呼入(未进 IVR)
OUTGOING呼出电话分机主动外呼/点击拨号
BATCH_CALL批量外呼批量外呼任务产生
TRANSFER人工转接内部分机间转接(盲转/三方转接)
OUT_TRANSFER转外线转接到外部号码
OUT_OUT双呼回拨两条外线间回拨
IVR_INCOMINGIVR 打入进入 IVR 菜单的呼入
IVR_TRANSFERIVR 转接IVR 转内部分机
IVR_OUT_TRANSFERIVR 转外线IVR 转外部号码(110/120 等)
TRANSFER_TO_IVR人工转 IVR坐席把通话转回 IVR
VOICE_MAIL语音邮箱留言
CONFERENCE电话会议创建/加入会议、三方会议
QUEUE_TIMEOUT排队超时排队无人接听超时
QUEUE_HUNGUP排队挂机排队期间客户挂机
CENTREX_CALL内部呼叫集团内部分机互拨
FORCE_PICKUP强插强插/接管通话(监听、强插)
INCOMING_CALL_FLOOD_CTRL流控拒接并发流控丢弃的来电
AI_ROBOTAI 机器人机器人外呼/应答
AI_ROBOT_TRANSFER_IN机器人转接机器人转人工(会产生新记录)
BLACKLIST_REJECT黑名单拦截命中黑名单被拒接

5. curl 示例

# 查某号码近一天接通的记录(第一页,每页 20 条)
curl "http://192.168.1.80:12121/bridge/callctrl?first=0&maxResults=20&beginDate=2026-09-12&endDate=2026-09-13&telnum=13512340001&state=STATE_RECEIVED&opt=CALL_LOG_QUERY"

# 坐席个人今日通话页(分机视角,第二页)
curl "http://192.168.1.80:12121/bridge/callctrl?first=10&maxResults=10&beginDate=2026-09-13&endDate=2026-09-13&extnum=801&opt=EXTNUM_CALL_LOG_QUERY"

# 用 WebSocket 弹屏拿到的 callid 查单条(URL 编码 @ 为 %40)
curl "http://192.168.1.80:12121/bridge/callctrl?callid=173a248c-8f85-4edb-b0c2-c11e1894a0d5%40192.168.1.82&opt=CALL_LOG_GET_WITH_CALLID"

6. 常见问题排查

现象原因与处理
返回 []条件过窄或时间格式错误(T 分隔符、URL 编码);先放开条件验证
翻页数据重复/跳页注意两个查询的 first 语义:本页两个查询均为行偏移;坐席监控 EXTNUM_MONITOR 才是页码语义,勿混用
拿不到 totalCALL_LOG_QUERY 返回不含 total,用 CALL_LOG_COUNT;分机视角从返回第一条的 total 取
呼叫进行中查询,state 是 RECEIVING正常,记录在挂机后才落全(时长/录音)
记录里 recordVoice 为空未开启录音或该通话无录音;有录音时该字段为服务器文件路径,可直接判断非空
callid 查询 404/空callid 未 URL 编码(@→%40),或记录尚未落库(等挂机后 1-2 秒)