呼叫记录推送接口

适用于: 挂机话单落库后,由 CTI 批量 POST 推送到第三方服务器,实现 OA/CRM 话单同步、BI 入库。 配套: 话单字段含义见 call-log-query(推送 datas 即完整话单实体);录音按 recordVoice/callid 走 recording-download。 呼叫状态推送(振铃/接通实时事件流)不在本文档范围,见 websocket-call-state 与官方说明书"HTTP 来电弹屏推送"章节。

实现: HibernateService/src/com/mediapbx/hibernate/calllog/post/CallLogPostManager.java(对应官方说明书《HTTP呼叫记录推送接口》章节)。

1. 机制概述

• 定时器周期扫描 calllog 表,把增量话单(id >= lastCallLogId 且 posted != 1)按批 POST 到配置的 URL;
• 第三方接收成功(见 §4 响应约定)后服务端置 posted=1,失败则下一轮自动重推,不丢数据;
• 有数据时按忙时间隔轮询,空闲/失败时自动降频(见 §5);
• 系统启动完成后延迟 3 分钟才开始推送(等待各组件初始化)。

2. 开通与配置(软参)

在 OMS 配置管理"高级参数"(confview 软参)中配置,HibernateService/conf/service.properties 默认值:

要点:

• 软参修改热生效(开关/间隔变更会自动重启推送定时器);calllog.post.start.id 改为 0 会触发全量重推,对接初期可用它回灌历史数据,正式运行后改回 -1。
• 推送报文中的 client_ip 取自软参 internal.ip(服务器内网 IP),第三方可据此区分多台 CTI。
• AI 摘要联动: 开启 calllog.save.stttxt.offon 后,话单的 stttxt 字段是 CTI 在挂机后用大模型对整通沟通内容生成的摘要总结(不是原始转写文本)——内容与格式由提示词模板决定,可让模型输出 JSON 等结构化结果(通话摘要、沟通结果等)。摘要生成前话单暂不推送,生成后立即经直推通道推送——即第三方拿到的一定是摘要完成后的 stttxt。提示词模板与配置见 §3.1 的 stttxt 字段说明。

3. 推送报文(CTI → 第三方,HTTP POST JSON)

Content-Type 为 JSON,UTF-8 编码。按接收 URL 自动二选一:

3.1 标准格式(URL 不含 opencalllog&openkey)

{
    "client_ip": "192.168.3.86",
    "datas": [
        {
            "id": 1476510,
            "caller": "806",
            "callee": "1000",
            "beginTime": 1691059681306,
            "duration": 41,
            "state": "STATE_RECEIVED",
            "callType": "LOCAL_CALL",
            "callid": "105652437424950-326581766720130@192.168.3.9",
            "recordVoice": "/opt/data/records/2023-08-03/xxx.wav",
            "business": "INCOMING",
            "stttxt": "{\"summary\":\"客户咨询设备维修...\",\"result\":\"需返厂\",\"followup\":\"3天内回访\"}",
            "...": "其余字段与 CALL_LOG_QUERY 返回一致"
        }
    ]
}

datas 数组元素即完整话单实体,字段含义与枚举(state/callType/business 等)同 call-log-query §1/§4,不再重复。注意 beginTime/ivrAnwerTime 等为毫秒时间戳;recordVoice 非空表示有录音。

stttxt 字段(AI 通话摘要): 开启 calllog.save.stttxt.offon 后,由 CTI 在挂机后调用大模型对整通沟通内容生成摘要总结——不是逐句转写文本。输出内容与格式由提示词模板决定,按需生成纯文本或 JSON 结构(通话摘要、沟通结果、待办事项等)。模板配置:

3.2 兼容格式(URL 含 opencalllog&openkey,国信 PHP 对接历史格式)

推送精简字段数组,extnum/telnum 已按"哪一侧是内部分机"自动归位:

[
  {
    "callid": "105652437424950-326581766720130@192.168.3.9",
    "extnum": "806",
    "telnum": "13512340001",
    "business": "INCOMING",
    "forward": "",
    "state": "STATE_RECEIVED",
    "beginTime": "2023-08-03 14:48:01",
    "ivrAnwerDuration": 1,
    "queueDuration": 0,
    "ringDuration": 5,
    "duration": 41,
    "estimate": 0,
    "isrecord": 1,
    "hungupside": "extnum",
    "ivrvoicemail": "",
    "stttxt": ""
  }
]

4. 响应约定(第三方必读)

接收端处理完成后返回纯文本:

注意:一批数据是一起重推的——某条记录持续 400 会导致整批滞留。第三方解析失败时应返回 400 并人工介入,而非无限重试。

5. 推送节奏与可靠性

6. 接收端最小示例

// Spring Boot 示例:收到即落队列,快速返回
@PostMapping(value = "/telcrm/calllog")
@ResponseBody
public String receive(@RequestBody CallLogPushBody body) {
    try {
        queue.offer(body);          // 异步处理,不要在本请求内做慢操作
        return "200";
    } catch (Exception e) {
        return "400";
    }
}

接收端要求:HTTP 服务快速应答(超时按失败处理会反复重推);按 id(标准格式)或 callid(兼容格式)做幂等。

7. 挂机事件推送(辅助通道)

另一族轻量 GET 推送在挂机瞬间发出(挂机信息推送,HungupNotifyUtils 家族),与 §1 的批量话单推送互补——实时性更高但只有摘要字段:

通用参数:callid、caller、callee、business,拼在 URL query 上(同步 GET 直发,无重试)。callid 与话单一致,可联动查询完整记录。

8. 常见问题排查