1. 场景介绍

本节针对典型场景说明及场景涉 API 的使用方法,供第三方平台在研发系统时参考。



1.1 AXB模式

X 表示米糠小号, A、 B 为平台两类用户, A 和 B 用户之间不知道对方真实号码的存在,他们所拨打的被叫号码都是 X。 AXB 场景下 X 号码允许被多组号码进行绑定, 同一个 X 号码不能被相同的 A 或者 B 号码同时绑定。

AXB 模式涉及的接口:

  • 应用接口:

    1. 获取可用小号:获取应用下面可以使用的小号,使用该列表中的小号可以进行绑定A、B号码,AXB模式的可用小号的获取规则为绑定数量组数最少的优先获取,相同绑定组数则绑定总数量少的优先

    2. AXB绑定:通过X号码绑定A、B号码

    3. AXB解绑:对绑定的关系进行解绑,可根据设定时间自动解绑

    4. AXB自动绑定:传入AB号码,自动绑定并返回X号码

  • 通话记录推送接口:

    A、B通过X通话完成后,主动推送到第三方提供接收通话记录接口。包括主叫、被叫、通话时长、通话状态等信息。

  • 录音播放及下载接口

    在绑定号码时启用了录音功能,则可以调用录音下载接口下载录音



1.2 AX模式

X 表示米糠小号, A 为用户。 A 用户对外呈现的号码用 X 替代,所有与 A 用户建立的通讯都是通过 X 号码建立。 AX 场景下 X 号码只能被 A 号码独享,即不同 A 号码对应不同的 X 号码。

AX模式涉及的接口:

  • 应用接口:

    1. 获取可用小号:获取应用下面可用小号进行绑定A用户。

    2. AX绑定:通过X号码绑定A号码。

    3. AX解绑:根据设定时间自动解绑或业务流程触发解绑。

    4. AX自动绑定:传入A号码,自动绑定并返回X号码

  • 呼叫通知接口:

    1. 呼出流程(A 呼 X),真实被叫号码 B 由应用在点击呼叫时提交给小号平台。请参考AX呼出接口。

    2. 呼入流程(B 呼 X),真实被叫 A 由小号平台自动根据 AX 绑定关系获取到。

  • 通话记录推送接口:

    A、B通过X通话完成后,主动推送到第三方提供接收通话记录接口。包括主叫、被叫、通话时长、通话状态等信息。

  • 录音播放及下载接口

    在绑定号码时启用了录音功能,则可以调用录音下载接口下载录音



2. 接口介绍



2.1 服务基地址

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

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

http使用21588端口



2.2 接入认证

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

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

说明:

AppKey 和 AppSecret,为小号业务分配给商户的接入账号和密码,请到http://www.mixcom.cn注册米糠小号(企业)。



2.3 加密规则

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

  2. 排除数组中键为sign和值为空的数据,即sign的值和空数据不参与加密

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

  4. 遍历参数数组,将值拼接成一串字符串 str1

  5. 对秘钥进行sha1加密, 生成一串字符串str2

  6. 将两串字符串进行拼接, 即 str1 str2生成str3

  7. 对str3进行sha1加密, 即是sign的值

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



3. 应用管理接口



3.1 获取AXB可用小号

接口功能:获取可以被绑定的axb号码,返回3个号码

返回的号码的排序规则: 当前绑定数量最少 > 总绑定数量最少 > id降序

请求方向:第三方应用平台 →小号平台(服务端)

请求方法:POST

请求URI:http://{BaseUrl}/virtual/getAxbNumber

请求消息体:

参数名 类型 最大长度 是否可选 解 释
region_code String 4 可选 获取指定区号的号码
time String 32 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": [
        {
            "number": "8617130700001",
            "region_code": "0771",
            "bindcount": "0"
        },
        {
            "number": "8617130700002",
            "region_code": "0771",
            "bindcount": "1"
        },
        {
            "number": "8617130700003",
            "region_code": "0771",
            "bindcount": "3"
        }
    ]
}

// number 代表虚拟小号
// region_code代表区号
// bindcount 代表该虚拟号绑定的号码组数量

错误码说明

错误码 描述
E300101 无可用号



3.2 AXB绑定

接口功能:AXB号码绑定接口

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/axbBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 必选 虚拟小号, 长度为11位的手机号码
aparty String 15 必选 A号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
bparty String 15 必选 B号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
maxduration Int 11 可选 最大通话时长,单位为分钟,到达指定的通话时长会挂断通话,0代表不限制通话时长,最大值为1440
lastminvoice String 32 可选 通话最后一分钟的提示音,传提示音的名称
recording String 1 可选 可选值 0或1, 1代表录音,0代表不录音, 默认为不录音
recordhinttone String 32 可选 录音前播放的提示音
callerhinttone String 32 可选 A拨通X通话前等待音
calleehinttone String 32 可选 B拨通X通话前等待音
enddate String 10 可选 绑定关系解除的时间,格式为unix时间戳
dicrection Int 2 可选 可选值0, 1, 2,默认为0, 0表示可以双向呼叫,1表示只允许A拨打B, 2表示只允许B拨打A
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "绑定成功",
    "data": {}
}

错误码说明:

错误码 描述
E300201 虚拟小号格式错误,只能是11位手机号码
E300202 A号码格式错误,固话请加区号(区号去掉前面的0)
E300203 号码格式错误,固话请加区号(区号去掉前面的0)
E300204 允许的最大通话时长为1440分钟
E300205 AXB绑定, A号码不能和B号码相同
E300206 AXB绑定, A号码不能和虚拟号相同
E300207 AXB绑定, B号码不能和虚拟号相同
E300208 保留
E300209 enddate的时间请大于现在
E300210 未在您的号码库中查询到该虚拟小号
E300211 该号码状态为暂停中, 无法使用
E300212 AX模式号码请勿使用AXB绑定接口
E300213 该号码绑定数量已达200组上限
E300214 A号码或B号码与X号码的绑定关系已存在
E300215 检测到为重复请求,已过滤
E300216 号码绑定成功, 但是绑定关系写入失败
E300217 该组绑定关系已存在, 请更换a号码或者b号码
E300218 未知错误



3.3 AXB解绑

接口功能:AXB号码解绑接口

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/unAxbBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 必选 虚拟小号, 长度为11位的手机号码
aparty String 15 必选 A号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
bparty String 15 必选 B号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "解绑成功",
    "data": {}
}

错误码说明:

错误码 描述
E300301 虚拟小号格式错误,只能是11位手机号码
E300302 A号码格式错误,固话请加区号(区号去掉前面的0)
E300303 B号码格式错误,固话请加区号(区号去掉前面的0)
E300304 未在您的号码库中查询到该虚拟小号
E300305 AX模式号码请勿使用AXB解绑接口
E300306 AXB绑定, A号码不能和B号码相同
E300307 号码解绑成功, 但数据处理失败
E300308 AXB绑定关系不存在,已执行删除操作,无需解绑
E300309 未知错误, AXB解绑号码失败



3.4 AXB自动绑定

接口功能:AXB号码自动绑定接口,需要传入a号码和b号码,会自动从号码库中选取虚拟小号并进行绑定

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/axbAutoBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
aparty String 15 必选 A号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
bparty String 15 必选 B号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
region_code String 4 可选 获取指定区域的虚拟小号
defregioncode String 4 可选 默认的区号,当在指定区号的地区没有虚拟小号时,获取该地区的虚拟小号
maxduration Int 11 可选 最大通话时长,单位为分钟,到达指定的通话时长会挂断通话,0代表不限制通话时长,最大值为1440
lastminvoice String 32 可选 通话最后一分钟的提示音,传提示音的名称
recording String 1 可选 可选值 0或1, 1代表录音,0代表不录音, 默认为不录音
recordhinttone String 32 可选 录音前播放的提示音
callerhinttone String 32 可选 A拨通X通话前等待音
calleehinttone String 32 可选 B拨通X通话前等待音
enddate String 10 可选 绑定关系解除的时间,格式为unix时间戳
direction Int 2 可选 可选值0, 1, 2,默认为0, 0表示可以双向呼叫,1表示只允许A拨打B, 2表示只允许B拨打A
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "绑定成功",
    "data": {
        "number": "8617699993333",
        "bindid": ""
    }
}

// number: 表示分配的虚拟小号
// bindid: 表示绑定的id

错误码说明:

错误码 描述
E300501 A号码格式错误,固话请加区号(区号去掉前面的0)
E300502 B号码格式错误,固话请加区号(区号去掉前面的0)
E300503 允许的最大通话时长为1440分钟
E300504 AXB绑定, A号码不能和B号码相同
E300505 保留
E300506 enddate的时间请大于现在
E300507 未获取到可用的号码
E300508 检测到为重复请求,已过滤
E300509 号码绑定成功, 但是绑定关系写入失败
E300510 该组绑定关系已存在, 请更换a号码或者b号码
E300511 未知错误



3.5 获取AX可用小号

接口功能:获取没有绑定的ax号码

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/getAxNumber

请求消息体:

参数名 类型 最大长度 是否可选 解 释
region_code String 4 可选 获取指定区号的号码
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": [
        {
            "number": "8617190320000",
            "region_code": "0755"
        }
    ]
}

// Number:代表虚拟小号
// Region_code:代表区号

错误码说明:

错误码 描述
E300601 无可用号码



3.6 AX绑定

接口功能:AX号码绑定接口

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/axBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 必选 虚拟小号, 长度为11位的手机号码
aparty String 15 必选 A号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
display_call String 1 可选 是否显示虚拟号, 默认显示虚拟号,可选值0或者1,1代表显示真实号码,0代表显示虚拟号。开启显示真实号码可能会存在无法接通的问题,透传号码的方式也是被禁止的。如非必要,请勿开启。
recording String 1 可选 可选值 0或1, 1代表录音,0代表不录音
recordhinttone String 32 可选 录音前播放的提示音
callerhinttone String 32 可选 A拨通X通话前等待音
calleehinttone String 32 可选 B拨通X通话前等待音
enddate String 10 可选 绑定关系解除的时间,格式为unix时间戳
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": "此处为绑定关系的id"
}

// number 代表虚拟小号

错误码说明:

错误码 描述
E300701 虚拟小号格式错误,只能是11位手机号码
E300702 A号码格式错误,固话请加区号(区号去掉前面的0)
E300703 AX绑定, A号码不能和虚拟号相同
E300704 保留
E300705 enddate的时间请大于现在
E300706 未在您的号码库中查询到该虚拟小号
E300707 该号码状态为暂停中, 无法使用
E300708 AXB模式号码请勿使用AX绑定接口
E300709 该绑定关系已存在, 无需绑定
E300710 检测到为重复请求,已过滤
E300711 号码绑定成功, 但数据处理失败
E300712 该虚拟号已存在其他绑定关系,请解绑后再重新绑定
E300713 未知错误, AX绑定号码失败



3.7 AX解绑

接口功能:AX号码解绑接口

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/unAxBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 必选 虚拟小号, 长度为11位的手机号码
aparty String 15 必选 A号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
bparty String 15 可选 只有在调用AxBindMore进行绑定的绑定关系解绑时才需要传B号码
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "解绑成功",
    "data": {}
}

错误码说明:

错误码 描述
E300801 虚拟小号格式错误,只能是11位手机号码
E300802 A号码格式错误,固话请加区号(区号去掉前面的0)
E300803 B号码格式错误,固话请加区号(区号去掉前面的0)
E300804 未在您的号码库中查询到该虚拟小号
E300805 AXB模式号码请勿使用AX解绑接口
E300806 该组绑定关系不存在,无法解绑
E300807 该X号码绑定了多组号码,请带上AB号码参数进行解绑
E300808 绑定关系不存在, 无需解绑
E300809 号码解绑成功, 但数据处理失败
E300810 AX绑定关系不存在, 已进行删除操作, 无需解绑
E300811 未知错误, AX解绑号码失败



3.8 AX设置临时被叫

接口功能:ax号码绑定呼出,用于呼出前绑定b号码

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/axDialNumber

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 必选 虚拟小号, 长度为11位的手机号码
aparty String 15 必选 A号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
bparty String 15 必选 B号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
duration Int 11 可选 临时被叫的有效期,默认为60秒,最大值86400
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "更新AX绑定成功",
    "data": {}
}

错误码说明:

错误码 描述
E301001 虚拟小号格式错误,只能是11位手机号码
E301002 A号码格式错误,固话请加区号(区号去掉前面的0)
E301003 B号码格式错误,固话请加区号(区号去掉前面的0)
E301004 AX绑定呼出, B号码不能和虚拟号相同
E301005 AX绑定呼出, B号码不能和A号码相同
E301006 未在您的号码库中查询到该虚拟小号
E301007 该号码状态为暂停中, 无法使用
E301008 该号码不是AX模式, 请将该号码变更为AX模式后再调用此接口
E301009 该请先进行ax绑定再使用ax绑定呼出功能
E301010 保留
E301011 更新AX绑定失败
E301012 未知错误,更新AX绑定失败



3.9 AX自动绑定

接口功能:AX号码的自动绑定接口,需要传入a号码,会自动从号码库中选取虚拟小号并进行绑定

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/axAutoBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
aparty String 15 必选 A号码,可以是手机号码,也可以是固定电话,固定电话需要加区号,区号前面无需加0
region_code String 4 可选 规定虚拟小号的所属区域
display_call String 1 可选 是否显示虚拟号, 默认显示虚拟号,可选值0 或者1,1代表显示真实号码,0代表显示虚拟号。开启显示真实号码可能会存在无法接通的问题,透传号码的方式也是被禁止的。如非必要,请勿开启。
recording String 1 可选 可选值 0或1, 1代表录音,0代表不录音
recordhinttone String 32 可选 录音前播放的提示音
callerhinttone String 32 可选 A拨通X通话前等待音
calleehinttone String 32 可选 B拨通X通话前等待音
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": {
        "number": "86171903200xx",
        "bindid": "",
        "region_code": "0755"
    }
}

// number:代表虚拟小号
// bindid:表示绑定的id
// region_code:代表区号

错误码说明:

错误码 描述
E301101 A号码格式错误,固话请加区号(区号去掉前面的0)
E301102 enddate的时间请大于现在
E301103 未获取到可用的号码
E301104 检测到为重复请求,已过滤
E301105 号码绑定成功, 但数据处理失败
E301106 该虚拟号已存在其他绑定关系,请解绑后再重新绑定
E301107 未知错误, AX绑定号码失败



3.10 AXE号码绑定

接口功能:绑定axe模式的号码

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:请设置成POST

请求URI:http://{BaseUrl}/virtual/axeAutoBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 可选 指定虚拟号码用于axe绑定, 如果没有则会根据区号自动获取号码
aparty String 13 必选 A方号码,为隐私保护的受益方
region_code String 4 可选 根据区号获取指定区域的虚拟小号
display_call String 1 可选 是否显示虚拟号, 默认显示虚拟号,可选值0 或者1,1代表显示真实号码,0代表显示虚拟号。开启显示真实号码可能会存在无法接通的问题,透传号码的方式也是被禁止的。如非必要,请勿开启。
recording String 1 可选 可选值 0或1, 1代表录音,0代表不录音
recordhinttone String 32 可选 录音前播放的提示音
callbacktone String 64 可选 A拨打x号码时,如果不存在回呼记录,则播放该提示音。当存在callbacknum时,此参数无效
callbacknum String 13 可选 A拨打x号码时,如果不存在回呼记录,则转到指定的号码
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": {
        "number": "86171903200xx",
        "bindid": "",
        "region_code": "0755",
        "extendnum": "0001"
    }
}

// number:代表虚拟小号
// bindid:表示绑定的id
// region_code:代表区号

错误码说明:

错误码 描述
E302001 虚拟小号格式错误
E302002 A号码格式错误,固话请加区号
E302003 enddate的时间请大于现在
E302004 检测到为重复请求,已过滤
E302005 未获取到可用的号码
E302006 该绑定关系已存在, 无需绑定
E302007 号码绑定成功, 但数据处理失败
E302008 未知错误, AXE绑定号码失败



3.11 AXE号码解绑

接口功能:解除axe模式的绑定

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:请设置成POST

请求URI:http://{BaseUrl}/virtual/unAxeBind

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 可选 指定虚拟号码用于axe绑定, 如果没有则会根据区号自动获取号码
aparty String 13 必选 A方号码,为隐私保护的受益方
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

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

错误码说明:

错误码 描述
E302101 虚拟小号格式错误
E302102 A号码格式错误,固话请加区号
E302103 检测到为重复请求,已过滤
E302104 未在您的号码库中查询到该虚拟小号
E302105 非AXE模式号码请勿使用AXE解绑接口
E302106 绑定关系不存在, 无需解绑
E302107 号码解绑成功, 但数据处理失败
E302108 AXE绑定关系不存在, 已进行删除操作, 无需解绑
E302109 未知错误, AXE解绑号码失败



3.12 获取小号数量

接口功能:获取该应用下正常状态的小号的数量

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:请设置成POST

请求URI:http://{BaseUrl}/virtual/countNumber

请求消息体:

参数名 类型 最大长度 是否可选 解 释
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": {
        "count": 100
    }
}



3.13 获取小号列表

接口功能:查询应用下面所有的小号(包含已经暂停的号码)

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/queryAllNumber

请求消息体:

参数名 类型 最大长度 是否可选 解 释
page String 10 可选 按照每页100条进行分页,小号数量超过100条则需要分页获取,默认值为1
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": {
        "count": 100,
        "list": [
            {
                "number": "8617130700000",
                "mode": "axb",
                "region_code": "0771",
                "status": "running",
                "start_time": "2018-04-25 20:15:21",
                "bindcount": "2"
            }
        ],
        "page": 1
    }
}

// count:号码总数
// number:为虚拟小号
// mode:为模式,有两个值,ax和axb
// region_code:代表区号
// status:有两个值,running代表小号正常运行中,stop代表小号已暂停
// start_time: 小号开始时间
// end_time: 小号结束时间
// bindcount: 代表该虚拟号绑定的号码组数量
// page: 代表当前是第几页



3.14 查询号码绑定关系

接口功能:查询号码的绑定关系

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/queryBindRelation

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 可选 虚拟小号
aparty String 15 可选 A号码
bparty String 15 可选 B号码
timestart String 10 可选 查询的开始时间
timeend String 10 可选 查询的结束时间
page String 10 可选 分页,每页100条数据
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": {
        "count": 1,
        "list": [
            {
                "number": "8617100000000",
                "apart": "8617100000001",
                "bpart": "8617100000002",
                "bindtime": "2018-05-16 11:03:39",
                "subscriptionId": "5af19948-bbb7-4dc2-a9cb-50be3e1a0000",
                "recording": "0",
                "endDate": "",
                "display_call": "0"
            }
        ],
        "page": 1
    }
}

// number:虚拟小号
// apart: A号码
// bpart:B号码
// bindtime:绑定时间
// subscriptionId:绑定标志
// recording: 0代表不录音,1代表录音
// endDate:绑定结束时间
// display_call:0代表显示虚拟号,1代表显示真实号码

错误码说明

错误码 描述
E301401 虚拟小号格式错误,只能是86+11位手机号码
E301402 A号码请使用86开头,格式为86加上号码,固话请加区号
E301403 B号码请使用86开头,格式为86加上号码,固话请加区号



3.15 查询号码绑定关系日志

接口功能:查询号码的绑定关系日志

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/queryRelationLog

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 可选 虚拟小号
aparty String 15 可选 A号码
bparty String 15 可选 B号码
timestart String 10 可选 查询的开始时间
timeend String 10 可选 查询的结束时间
page String 10 可选 分页,每页100条数据
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": {
        "count": 1,
        "list": [
            {
                "number": "8617100000000",
                "apart": "8617100000001",
                "bpart": "8617100000002",
                "optime": "2018-05-16 11:03:39",
                "op": "bind",
                "subscriptionId": "5af19948-bbb7-4dc2-a9cb-50be3e1a0000",
                "recording": "0",
                "endDate": "",
                "'bindDirection'": "0"
            }
        ],
        "page": 1
    }
}

// Number: 虚拟小号
// Apart: A号码
// Bpart: B号码
// Op bind:绑定 unbind:解绑 changebind: 变更绑定
// optime: 操作时间
// subscriptionId: 绑定标志
// Recording: 0代表不录音,1代表录音
// endDate: 绑定结束时间
// bindDirection: 0代表双向绑定

错误码说明

错误码 描述
E301501 虚拟小号格式错误,只能是86+11位手机号码
E301502 A号码请使用86开头,格式为86加上号码,固话请加区号
E301503 B号码请使用86开头,格式为86加上号码,固话请加区号
E301504 开始时间请小于现在
E301505 开始时间请大于2015-01-01
E301506 结束时间请小于现在
E301507 结束时间请大于开始时间



3.16 查询号码的通话记录

接口功能:查询号码的通话记录

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/queryCallRecord

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 可选 虚拟小号
aparty String 15 可选 A号码
bparty String 15 可选 B号码
timestart String 10 可选 查询的开始时间
timeend String 10 可选 查询的结束时间
page String 10 可选 分页,每页100条数据
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

响应消息:

{
    "success": true,
    "code": 200,
    "msg": "",
    "data": {
        "count": 1,
        "list": [
            {
                "virtualNumber": "8617100000000",
                "calling": "8617100000001",
                "called": "8617100000002",
                "starttime": "2018-05-16 11:03:39",
                "ReleaseReason": "...",
                "callIdentifier": "...",
                "duration": "20"
            }
        ],
        "page": 1
    }
}

// virtualNumber: 虚拟小号
// Calling: 主叫号码
// Called: 被叫号码
// Starttime: 通话开始时间
// ReleaseReason: 结束原因
// callIdentifier: 通话唯一id
// Duration: 通话时长

错误码说明:

错误码 描述
E301601 虚拟小号格式错误,只能是86+11位手机号码
E301602 A号码请使用86开头,格式为86加上号码,固话请加区号
E301603 B号码请使用86开头,格式为86加上号码,固话请加区号
E301604 开始时间请小于现在
E301605 开始时间请大于2015-01-01
E301606 结束时间请小于现在
E301607 结束时间请大于开始时间



4. 录音管理接口



4.1 获取录音下载地址

接口功能:获取录音的下载地址

请求方向:第三方应用平台 →小号平台(服务端)。

请求方法:POST

请求URI:http://{BaseUrl}/virtual/getRecordUrl

请求消息体:

参数名 类型 最大长度 是否可选 解 释
number String 11 必选 虚拟小号
callidentifier String 32 必选 通话的唯一id
time String 10 必选 Unix时间戳,用来限制接口连接的有效期,有效期为10分钟
appkey String 32 必选 应用的appkey
sign String 32 必选 生成的加密校验码

错误码说明:

错误码 描述
E301701 虚拟小号格式错误,只能是11位手机号码
E301702 未在您的号码库中查询到该虚拟小号



4.2 推送录音下载地址

登录后台设置录音推送地址

推送格式:

{
    "eventType": "record",
    "statusInfo": {
        "recordurl": "http://record.mixcom.cn/xxxx",
        "callid": "ba171f34e6953fcd751edc77127748f4.3779798447.319858xxx",
        "bindid": "5333cea2-d8bf-f128-89fd-a2eca406xxxx"
    }
}

// eventType: 固定为record
// recordurl: 录音的下载地址
// callid: 通话的唯一id
// bindid: 绑定的id



5. 通话记录推送接口

接口功能:当用户发起呼叫或收到来电时, 小号业务会将呼叫事件推送到第三方应用。

请求方向:小号平台(服务端)→第三方应用平台。

请求方法:POST

请求URI:商户应用提供的用来接收通知的服务地址,示例:http://{AppServerAddr}{ AppServerAddr }是第三方应用接收呼叫通知的服务地址。



5.1 事件说明

应答事件(默认不推送)

格式:

{
    "eventType": "answer",
    "timestamp": "2018-12-05 02:35:15",
    "caller": "1719173xxxx",
    "called": "1852131xxxx",
    "subscriptionId": "c9f09eb2-22a9-46c4-86c7-fd1db5dexxxx"
}

// eventType answer:表示应答事件
// caller: 主叫号码应答中的主叫号码是虚拟小号
// called: 被叫号码
// subscriptionId: 绑定关系id
// timestamp: 事件的事件

话单事件

格式:

{
    "eventType": "fee",
    "bindNum": "1715677xxxx",
    "icid": "ba171f34e6953fcd751edc77127748f4.3753069029.2314xxxx",
    "subscriptionId": "16b22333-5056-4eff-a761-83d312e6xxxx",
    "callerNum": "1362543xxxx",
    "calleeNum": "1715677xxxx",
    "fwdDisplayNum": "1715677xxxx",
    "fwdDstNum": "1321071xxxx",
    "callInTime": "2018-12-06 15:10:29",
    "fwdStartTime": "2018-12-06 15:10:29",
    "fwdAlertingTime": "2018-12-06 15:10:32",
    "fwdAnswerTime": "",
    "callEndTime": "2018-12-06 15:10:52",
    "duration": 0,
    "reason": "8001",
    "recordFlag": 0
}

// eventType fee: 表示话单事件
// bindNum:  虚拟小号
// icid:  唯一的通话标志
// subscriptionId:  绑定关系id
// callerNum:  主叫号码
// calleeNum:  被叫号码
// fwdDisplayNum:  转接呼叫时的显示的号码
// fwdDstNum:  转接呼叫的被叫号码
// callInTime:  呼入开始的时间
// fwdStartTime:  呼叫转接开始时间
// fwdAlertingTime:  转接呼叫后振铃时间
// fwdAnswerTime:  转接呼叫后应答时间
// callEndTime:  挂断时间
// Duration:  通话时长



5.2 通话结束原因列表

错误码 错误原因
7001 呼叫频次管控
7002 应用呼叫频次管控
7003 主显号码呼叫频次管控
7004 被叫黑名单呼叫管控
7008 用户状态已冻结
8000 内部错误
8001 用户未接续成功
8002 接续用户时对端返回失败放音
8003 用户振铃超时
8004 用户振铃时挂机
8005 TTS转换失败
8006 放音文件不存在
8007 给用户放音失败
8008 给用户放音收号失败
8009 主叫用户主动挂机
8010 超过通话最大时长挂机
8011 其他错误
8012 无效的AX模式呼叫
8013 无效的AXB模式呼叫
8014 给用户录音失败
8015 AXB模式呼叫方向不允许
8016 X模式客户指示挂机
8017 业务无权限
8018 绑定关系不存在
8019 业务异常
8020 无效的分机号码
8022 被叫号码不存在
8101 被叫无应答
8102 被叫用户正忙
8103 被叫用户暂时无法接通
8104 被叫已关机
8105 被叫已停机
8201 主叫正常挂断(已接通)
8202 被叫正常挂断(已接通)
8203 主叫用户主动挂断(已振铃)
8204 主叫用户主动挂断(未振铃)



5.3 推送说明

接收端响应200后不会再进行推送, 404等状态不会进行重新推送, 500会进行重新推送, 重推次数为5次, 间隔时间为1分钟, 5分钟, 10分钟, 1小时, 1小时



6. 语音提示配置

提供提示音文件,文件需同时符合以下要求:

  • 编码格式是 g.711

  • 采样率是 8k

  • 比特率是 8bit

  • 小于 1M

AXB模式:

序号 场景描述 语音提示内容
1 无绑定关系提示音。 当系统根据小号未查询到绑定关系或者根据主叫号码未匹配到对应的绑定关系时,向用户播放该提示音。 您拨打的电话是空号。
2 当系统查找绑定关系失败(X 有绑定关系,但是查找异常,如数据库异常) 时,向用户播放该提示音。 您拨打的电话是空号。
3 录音场景下,转接时间较长,可以向用户播放该提示音。(播放提示音增加不能缩短接续被叫时间) 转接中,请稍等
4 无呼叫权限提示音,应用于单侧绑定的场景。 例如, A 单侧绑定 X 号码,只能 A 呼 X,不能 B 呼 X,当 B 呼 X 时,向 B 播放该提示音。 您拨打的电话是空号。

AX模式:

序号 场景描述 语音提示内容
1 无绑定关系提示音。 当系统根据小号未查询到绑定关系或者根据主叫号码未匹配到对应的绑定关系时,向用户播放该提示音。 您拨打的电话是空号。
2 查找绑定关系失败放音(X 有绑定关系,但是查找异常) 您拨打的电话是空号。
3 A 呼 X 的应用场景(外呼场景) IDP 事件,北向商户响应获取 B 号码失败放音 您拨打的电话是空号。



A 附录:返回码

错误码 描述
E100001
E100002 请使用post方法请求接口
E100003 time为必传的参数
E100004 接口访问连接的有效期为10分钟, 您传递过来的时间为...
E100005 appkey为必传的参数
E100006 appkey不能为空
E100007 appkey长度错误,应为32位字符串
E100008 appkey格式错误
E100009 该appkey不存在
E100010 该应用未上线
E100011 该应用已暂停
E100012 未检测到sign参数, sign参数为必传选项
E100013 加密校验失败, 请检查加密是否正确。 检测到的sign:xxx...
E100014 该号码数据存在异常
E100015 请求失败, 请重新操作
E100016 网络异常, 请重新操作
E100017 数据库故障, 连接异常
E100018 Redis连接故障