一键呼叫接口文档



1. 接口介绍

1.1 服务基地址

一键呼叫业务提供的 API 请求服务地址称之为服务基地址(下文中使用变量{BaseUrl}表示), 一键呼叫平台的{BaseUrl}固定为: api-voicecall.mixcom.cn

实际提供的接口服务请求地址为"http://{BaseUrl}:21588/+[接口服务名]"。

http使用21588端口

1.2 接入认证

业务提供的 API 均采用加密认证方式。

此种认证方式下,将根据私有的 AppSecret 生成加密码进行鉴权。鉴权通过后,语音平台处理该请求消息。

说明:

AppKey 和 AppSecret,为一键呼叫业务分配给商户的接入账号和密码。

请到http://www.mixcom.cn注册账户及企业认证。创建应用。

1.3 加密规则

  1. 获取所有的需要传递的参数,作为一个数组

  2. 将加密数组中所有的 key 转换成小写

  3. 排除参数列表中的 sign 和值为空的数据,即 sign 的值和空数据不参与加密

  4. 对参数数组进行排序,按照 key 的名称升序排列

  5. 遍历参数数组,将值进行拼接

  6. 在拼接后的字符串后面再连接私有的秘钥,拼接后的字符串表示为$string

  7. 采用 sha1 进行加密,规则 sha1($string . sha1($secret)), $string 代表拼接后的字符串,$secret 代表私有秘钥

  8. 将生成的 sign 转换为小写



2. 接口



2.1 点击呼叫

接口功能: A 手机(营销人员)<---平台--->B 手机(客户)

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://{BaseUrl}/voice/dial

请求消息体:

参数名 类型 最大长度 是否可选 解 释
callerNbr String 20 必选 主叫号码
calleeNbr String 20 必选 被叫号码
maxduration Int 可选 最大通话时长,单位(分钟), 如果接口没有设置, 则使用号码设置的最大通话时长,默认值为0, 表示不限制
Uuid String 200 可选 自定义的唯一 id, 允许是数字, 字母和下划线, 中划线, + = /, 支持base64
time String 10 必选 Unix 时间戳,用来限制接口连接的有效期,有效期为 10 分钟
appkey String 32 必选 应用的 appkey
sign String 32 必选 生成的加密校验码

参数说明:

参数名不区分大小写

响应消息:

{
  "success": true,
  "code": 200,
  "msg": "",
}



2.2 通话记录接口

接口功能: 返回当前应用的通话记录列表

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://{BaseUrl}/cdr/lists

请求消息体:

参数名 类型 最大长度 是否可选 解 释
timestart Int 11 可选 查询的开始时间, 格式如下: 1591242125
timeend Int 11 可选 查询的结束时间, 格式如下: 1591242199
page Int 11 可选 当前页数
pagenum Int 11 可选 每页查询的数量,最大为100

参数说明:

参数名不区分大小写

响应消息:

{
    "success": true,
    "msg": "",
    "code": 200,
    "data": {
        "count": 205,
        "pagecount": 21,
        "page": 1,
        "list": [
            {
                "callIdentifier": "CAE-20200527202311-12015692",
                "bindNum": "+8697171483**",
                "caller": "+8697171483**",
                "callee": "+86130809211**",
                "Duration": "0",
                "callerStartTime": "2020-05-27 20:23:11",
                "callerAlertingTime": "2020-05-27 20:23:23",
                "callerAnswerTime": "",
                "ulFailReason": "520",
                "calleeStartTime": "",
                "calleeAlertingTime": "",
                "calleeAnswerTime": "",
                "callEndTime": "2020-05-27 20:23:23",
                "isRecord": "0",
                "recordUrl": "http://v-record.mixcom.cn/record/download?icid=CAE-20200527202311-12015692&appkey=691aa6a934e6962b589ca7c22ebe****&sign=2c534e8518e084836be4c657d8f298062d81****"
            },
            {
                "callIdentifier": "CAE-20200527202152-12005561",
                "bindNum": "+8697175363**",
                "caller": "+8697175363**",
                "callee": "+86130809211**",
                "Duration": "0",
                "callerStartTime": "2020-05-27 20:21:52",
                "callerAlertingTime": "2020-05-27 20:22:17",
                "callerAnswerTime": "",
                "ulFailReason": "520",
                "calleeStartTime": "",
                "calleeAlertingTime": "",
                "calleeAnswerTime": "",
                "callEndTime": "2020-05-27 20:22:17",
                "isRecord": "0",
                "recordUrl": "http://v-record.mixcom.cn/record/download?icid=CAE-20200527202152-12005561&appkey=691aa6a934e6962b589ca7c22ebe****&sign=fd9452bfa981f9505a03cd706a94f3ac7aec****"
            }
        ]
    }
}

// success 为true表示成功, false表示失败
// data为具体返回的数据
// data中count为数据的总的数量
// data中pagecount为分页的总的数量
// data中page为当前所在的页数
// data中list为具体数据, 数据格式客参照通话记录推送的格式说明



2.3 详细账单接口

接口功能: 返回当前应用的计费的数据列表

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://{BaseUrl}/billing/lists

请求消息体:

参数名 类型 最大长度 是否可选 解 释
timestart Int 11 可选 查询的开始时间, 格式如下: 1591242125
timeend Int 11 可选 查询的结束时间, 格式如下: 1591242199
page Int 11 可选 当前页数
pagenum Int 11 可选 每页查询的数量,最大为100

参数说明:

参数名不区分大小写

响应消息:

{
    "success": true,
    "msg": "",
    "code": 200,
    "data": {
        "count": 205,
        "pagecount": 21,
        "page": 1,
        "list": [
            {
                "charge": "-0.1",
                "price": "0.1",
                "caller": "+86187108061**",
                "called": "+86185919882**",
                "number": "+8697171476**",
                "uniqueid": "CAE-20200527195518-12012464",
                "duration": "8",
                "minute": "1",
                "starttime": "2020-05-27 19:55:40"
            },
            {
                "charge": "-0.1",
                "price": "0.1",
                "caller": "+86183925567**",
                "called": "+86158092328**",
                "number": "+8697171496**",
                "uniqueid": "CAE-20200527195429-12021939",
                "duration": "24",
                "minute": "1",
                "starttime": "2020-05-27 19:55:00"
            }
        ]
    }
}

// success 为true表示成功, false表示失败
// data为具体返回的数据
// data中count为数据的总的数量
// data中pagecount为分页的总的数量
// data中page为当前所在的页数
// data中list为具体数据

// charge 表示实际扣费
// price 表示单价
// caller 表示主叫号码
// called 表示被叫号码
// number 表示中间号码
// uniqueid 表示唯一的id
// duration 表示通话时长
// minute 表示实际的计费时长
// starttime 表示通话开始的时间



2.4 日结报表数据

接口功能: 返回当前应用每日的报表数据

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://{BaseUrl}/report/day

请求消息体:

参数名 类型 最大长度 是否可选 解 释
daystart String 10 可选 查询的开始日期, 格式如下: 2020-06-01
dayend String 10 可选 查询的结束日期, 格式如下: 2020-07-01
page Int 11 可选 当前页数
pagenum Int 11 可选 每页查询的数量,最大为100

参数说明:

参数名不区分大小写

响应消息:

{
    "success": true,
    "msg": "",
    "code": 200,
    "data": {
        "count": 1,
        "pagecount": 1,
        "page": 1,
        "list": [
            {
                "day": "2020-06-09",
                "num": "12",
                "answercall": "0",
                "totalcall": "0",
                "money": "0"
            }
        ]
    }
}

// success 为true表示成功, false表示失败
// data为具体返回的数据
// data中count为数据的总的数量
// data中pagecount为分页的总的数量
// data中page为当前所在的页数
// data中list为具体数据

// day 表示日期
// num 表示总的通话分钟数
// answercall 总的接通次数
// totalcall 总的呼叫次数
// money 总的费用



2.5 月结报表数据

接口功能: 返回当前应用指定年份的报表数据

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://{BaseUrl}/report/month

请求消息体:

参数名 类型 最大长度 是否可选 解 释
year String 10 可选 格式如下: 2020

参数说明:

参数名不区分大小写

响应消息:

{
    "success": true,
    "msg": "",
    "code": 200,
    "data": {
        "list": [
            {
                "month": "2020-03",
                "num": "3000",
                "answercall": "2000",
                "totalcall": "4000",
                "money": "-300.0000"
            },
            {
                "month": "2020-04",
                "num": "3000",
                "answercall": "2000",
                "totalcall": "4000",
                "money": "-300.0000"
            },
            {
                "month": "2020-05",
                "num": "3000",
                "answercall": "2000",
                "totalcall": "4000",
                "money": "-300.0000"
            }
        ]
    }
}
// success 为true表示成功, false表示失败
// data为具体返回的数据
// data中list为具体数据

// month 表示月份
// num 表示该月总的通话分钟数
// answercall 该月总的接通次数
// totalcall 该余额总的呼叫次数
// money 该月总的费用



2.6 查询账户余额

接口功能: 返回当前应用对应的账户的余额

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://{BaseUrl}/balance/get

请求消息体:

无参数

响应消息:

{
    "success": true,
    "msg": "",
    "code": 200,
    "data": "-642.75"
}
// success 为true表示成功, false表示失败
// data为具体返回的金额



2.7 充值扣款记录接口

接口功能: 返回当前应用对应的账户的充值扣款记录

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://{BaseUrl}/recharge/lists

请求消息体:

参数名 类型 最大长度 是否可选 解 释
timestart Int 11 可选 查询的开始时间, 格式如下: 1591242125
timeend Int 11 可选 查询的结束时间, 格式如下: 1591242199
page Int 11 可选 当前页数
pagenum Int 11 可选 每页查询的数量,最大为100

参数说明:

参数名不区分大小写

响应消息:

{
    "success": true,
    "msg": "",
    "code": 200,
    "data": {
        "count": 10,
        "pagecount": 1,
        "page": 1,
        "list": [
            {
                "dealtime": "2020-06-02 15:12:41",
                "type": "3",
                "money": "5.0000",
                "remark": "测试",
                "desc": "充值"
            },
            {
                "dealtime": "2020-06-02 15:02:10",
                "type": "2",
                "money": "-10.0000",
                "remark": "测试",
                "desc": "扣款"
            }
        ]
    }
}

// success 为true表示成功, false表示失败
// data为具体返回的数据
// data中count为数据的总的数量
// data中pagecount为分页的总的数量
// data中page为当前所在的页数
// data中list为具体数据

// dealtime 表示交易发生的时间
// type 表示类型, 2为扣款, 3为充值
// money 表示交易发生的金额
// remark 交易的备注
// desc type类型的文字说明



3. 通话记录推送

功能: A\B 通话完成后,推送通话记录数据。

请求方向:一键呼叫平台(服务端)→ 第三方应用平台

请求方法: POST

设置推送地址

  1. http://www.mixcom.cn,登录。如没有账号,请注册进行企业认证。后台会及时审核。

  2. 进入应用列表中,选择对应的应用,点击"回调地址",在"通话记录推送地址"输入要推送的地址,保存。

图片1

图片2

注:如没有应用,请先创建应用即可。

格式:

{
    "event": "fee",
    "callIdentifier": "CAE-20200302174758-12017889",
    "bindNum": "+86971714xxxx",
    "caller": "+86130372xxxx",
    "callee": "+861760709xxxx",
    "Duration": 10,
    "callerStartTime": "2020-03-02 17:48:07",
    "callerAlertingTime": "2020-03-02 17:48:12",
    "callerAnswerTime": "2020-03-02 17:48:15",
    "ulFailReason": 0,
    "calleeStartTime": "2020-03-02 17:47:58",
    "calleeAlertingTime": "2020-03-02 17:48:04",
    "calleeAnswerTime": "2020-03-02 17:48:07",
    "callEndTime": "2020-03-02 17:48:17",
    "isRecord": 0,
    "recordUrl": "",
    "uuid": "",
}

字段含义

Event fee 表示话单

Callidentifier 表示唯一的 id,用于关联录音文件。

Bindnum 表示业务的号码

Caller 表示主叫

Callee 表示被叫

Duration 表示通话时长

Callerstarttime 表示业务号码呼叫主叫的时间

Calleralertingtime 表示主叫振铃的时间

Calleranswertime 表示主叫应答的时间

Ulfailreason 通话失败的原因

Calleestarttime 呼叫被叫的时间

Calleealertingtime 被叫振铃的时间

Calleeanswertime 被叫应答的时间

Callendtime 通话挂断的时间

Isrecord 表示是否录音, 1 表示录音, 0 表示不录音

Recordurl 录音的下载地址, 如果开启了录音则有, 没有则为空

Uuid 用户自定义的 id

推送说明:

  1. 接收端返回的数据格式不是json, 不会进行重推

  2. 返回值是json, 且格式为{"code":200}, 则不会进程重推, 返回除code为200以外的json, 都会进行重推

  3. 404, 403 等状态码不会进行重推, 500 等状态码会进行重推

  4. 推送超时数据会进行重推, 推送超时的限制为2.5秒

  5. 重推间隔为 60 秒, 180 秒, 600 秒, 最多重推 3 次

  6. 如果已经开启了录音, 则可以根据话单中的 recordUrl 下载录音到本地, 也可以在线试听



4. 录音文件下载及播放

接口功能: 通话录音播放及下载接口。

请求方向: 第三方应用平台 → 一键呼叫平台(服务端)

请求方法: POST

请求 URI: http://v-record.mixcom.cn/record/download

请求消息体:

参数名 类型 最大长度 是否可选 解 释
icid String 64 必选 呼叫唯一标识,用于关联录音。
sign String 32 必选 生成的加密校验码
appkey String 32 必选 应用的 appkey

调用实例:

http://v-record.mixcom.cn/record/download?icid=CAE-20200304030813-12010906&appkey=4442323&sign=089b3c103f9c597dc2ea592912bd8f1969c862b4



5. 呼叫失败原因

说明:

状态码 说明
0 接通后主动挂机
507 启动录音失败
508 启动录音超时
509 放录音提示音失败
510 放录音提示音超时
512 录音 VCU 倒换释放呼叫
513 呼叫超时
514 振铃超时
515 远端用户主动 Cancel
516 本端用户主动 Cancel
517 平台响应超时
518 远端用户呼叫失败
519 本端用户呼叫失败(OXX)
520 本端用户呼叫失败(18X)
524 放音文件不存在
525 超过语音呼叫端口数限制