信创电话助手记录上传对接开发文档

版本：V26.04.13 | 官网：https://agicall.com

前言
安装信创电话助手
Web服务器的URL地址设置方式
开发Web服务器接口时推荐模拟工具
信创电话助手提交记录的时机
Web服务器应答回复
通话记录和录音文件 JSON 数据格式字段描述
语音转文字 JSON 数据格式字段描述
Web服务器端 Java/Python 参考示例代码下载
设备实时事件上传开启配置

1 前言

文档概要信息

文档名	信创电话助手记录上传对接文档	起草人	agicall
文档版本	V25.03.07	起草日期	2025-03-07
技术支持	Email: 9421766@qq.com Tel: 13810450502 (微信同)	联系人	信电助
官网	https://agicallcom

编写目的

为了用户能更方便使用信创电话助手软件时对接通话记录，录音文件，录音转文字后上传到第三方 web服务器。

注意：本说明书对应的信创电话助手软件为 V25.02.20 以上版本，该版本以下的不支持上传对接开发。

2 安装信创电话助手

使用对接开发前，先从官网下载并安装信创电话助手，并接入 USB 信创录音盒设备。

注意：信创电话助手软件分为 Windows 版本和国产信创麒麟统信版本，两个版本的软件功能一致。

图：信创电话助手主界面

接线方式：

图：USB信创录音盒设备接线图

如果使用设备时支持离线录音转文字功能的，按官方说明，部署好离线 ASR 大模型。

协议说明：信创电话助手软件采用标准 HTTP 协议的 POST 请求发送记录到用户 Web 服务器，POST 数据采用 JSON 格式，不加密。

3 Web服务器的 URL地址设置方式

点击【文件】菜单。

图：USB信创录音盒设备接线图

在弹出的菜单里选择【录音上传配置】。

录音上传配置界面

在配置界面里，把【启用】打勾，然后在【服务器URL】输入用户已经开发好的 Web 服务器 URL 地址。

录音上传配置界面

注意：请确保这个服务器 URL 地址和当前软件在局域网内，或者有效的公网地址，能被使用信创助手软件的电脑正常链接访问。
示例：
- IPV4: http://192.168.0.9:8888/upload.aspx
- 域名: http://upload.agicall.com:8888/upload.aspx

4 开发 Web服务器接口时推荐模拟工具

对于模拟 HTTP POST 请求提交 JSON 数据，推荐使用 Postman，来模拟提交数据，把示例文件的 JSON 数据复制到 Postman 提交到服务器来测试服务器接口功能。

Postman测试功能

开发完成后，再把服务器的url地址保存到信创助手的上传服务器url地址。

配置上传服务器url地址

5 信创电话助手提交记录的时机

通话记录和录音文件上传

信创助手正常工作时，在来去电通话结束，会自动产生一个通话记录和录音文件（如果启用了自动录音或手动录音），然后检测到后台启用了录音上传功能，并配置了有效的服务器 URL，就会自动触发一个标准 HTTP 请求，POST 当前通话记录数据到指定服务器。

录音转文字上传

信创助手通话结束后如果产生了录音文件，就会自动提交录音文件给 ASR 大模型，大模型后台异步进行转文字，当大模型转文字完成会触发一个消息给信创助手软件，信创助手软件就会启动 HTTP 的 POST 请求来提交 JSON 格式的文字记录。

6 Web服务器应答回复

服务器接收数据后返回数据采用 JSON 固定格式：

{
    "err_id": 0,
    "err_desc": "ok"
}

7 通话记录和录音文件的 JSON 数据格式字段描述

判断方式：读取 JSON，判断 calllog/class 是 "calllog" 内容时表示呼叫记录 JSON 数据。

完整 JSON 结构示例

{
    "calllog": {
        "account": "5990012",
        "class": "calllog",
        "data": {
            "account": "5990012",
            "area": {
                "area_id": "010",
                "city": "北京",
                "code": "13810450502",
                "province": "北京"
            },
            "call_param": null,
            "callid": {
                "code": "13810450502",
                "dst_to": "013810450502",
                "type": "dtmf"
            },
            "connected_mode": "",
            "dialog_id": "1649095850785361432",
            "dialog_type": "out",
            "evt_name": null,
            "finished_reason": "phone_hangup",
            "func_id": 794,
            "operator": "phone",
            "recfile": {
                "duration": 7091,
                "file": "F:/.../090809_575_0001_805_out.mp3",
                "filename": "2025/03/05/090809_575_0001_805_out.mp3",
                "path": "F:/.../recfile/"
            },
            "step_name": null,
            "timestamp": {
                "connected": {
                    "datetime": "2025-03-05 09:08:10.621",
                    "duration": "6047",
                    "utc": "1741136890621",
                    "week": "3"
                },
                "connecting": { ... },
                "create": { ... },
                "dohangup": { ... },
                "finished": { ... },
                "ringing": { ... }
            }
        }
    },
    "encoding": "utf-8",
    "oid": { ... },
    "source": "agi_ub_dev",
    "time": { ... },
    "ver": "2.1.0",
    "md5": "...",
    "rec_data": {
        "data": "SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjM5LjEwMQ...base64数据...",
        "enable": true,
        "mode": "base64"
    }
}

8 语音转文字 JSON 数据格式字段描述

判断方式：读取 JSON，判断 calllog/class 是 "dialog" 内容时，再判断 calllog/data/evt_name 为 "recfile_asr" 就表示本次 JSON 是通话音频数据转换的文字信息。

JSON 结构示例

{
    "calllog": {
        "account": "5990012",
        "class": "dialog",
        "data": {
            "account": "5990012",
            "data": {
                "asr_file": "F:/.../091858_181_0001_805_out.mp3",
                "asr_result": {
                    "sentences": [
                        {
                            "begin_time": 0,
                            "channel_id": 0,
                            "end_time": 8610,
                            "pinyin": "ni-hao-huan-yin-shi-yong-xin-chuang-zhu-shou",
                            "step_name": "end",
                            "text": " 你好欢迎使用信创助手 "
                        },
                        {
                            "begin_time": 9990,
                            "channel_id": 0,
                            "end_time": 10739,
                            "pinyin": "",
                            "step_name": "end",
                            "text": ""
                        }
                    ]
                },
                "asr_user_data": { ... },
                "begin_asr": 1456457659,
                "begin_tick": 1456457655,
                "biz_duration": 5656,
                "channel_num": 1,
                "end_tick": 1456463315,
                "err_id": 0,
                "request_id": "1649095850787956692",
                "request_time": 1741137548926,
                "solve_time": 1741137554586,
                "task_id": "2691174167578935296"
            },
            "dialog_id": "1649095850787956692",
            "evt_name": "recfile_asr",
            "step_name": "end",
            "utc": "1741137536501"
        }
    },
    "encoding": "utf-8",
    "oid": { ... },
    "source": "agi_ub_dev",
    "time": { ... },
    "ver": "2.1.0",
    "md5": "..."
}

9 Web服务器端 Java/Python参考示例代码下载

方法一：

使用浏览器打开官网: https://agicall.com
在打开的页面中找到【java/python二次开发】项目。

java-python例子

选择【内网通话记录和录音文件备份 web服务器】下载示例参考代码。

方法二：

地址栏直接输入: https://agical.com/data/upload-web-service.zip
确认后就会自动下载。

10 设备实时事件上传开启配置

配置步骤：

如何打开安装目录，可以关注官方公众号，搜索【安装目录】关键字

微信扫一扫

使用文本编辑工具打开 agi_ub/config/agi_callog.json 文件。
找到 "remote" 字段内容。

实时事件推送开关

"dialog" 和 "account" 分别是 SDK 触发的实时事件类。
例如： "asr_stream" 表示通话中实时收到一句话文字内容，把对应的 false 改成 true 就表示启用触发后上传给服务器。
修改后保存文件，保存后会立即生效，不需要重启软件。