2023/12/15 10:26:48

API 参考

信息

本文内容由启智科技提供。

概述

本节介绍 RESTful API 的公共参数信息以及相关约定。

通讯协议

通讯方式：HTTP 协议通信
请求方式：POST/GET
请求实体：JSON
通讯字符集采用 UTF-8 编码

签名方式

开启签名验证后，进行接口调用时，HTTP 请求中需添加签名信息。

签名方式如下：

调用接口发送 GET/POST 请求时签名值的计算方式如下，其中 serverKey 为请求的公共参数，param1、param2、param3 为每个请求的查询参数，参数顺序根据字符长度升序排列：
Java
```
DigestUtils.md5Hex(serverKey:param1=value1&param2=value2&param3=value3);
```
接收事件推送的 POST（数据存放于 Body 中）请求时签名值的计算方式如下，其中 serverKey 为请求的公共参数，JSONStr 与存放于 Body 中的字符串相同：
Java
```
DigestUtils.md5Hex(serverKey:JSONStr);
```

公共参数

请求 Header 中包含以下参数：

参数名称	参数名	类型	是否必须	说明
用户密匙	`serverKey`	String	必须	用户密匙信息
签名	`sign`	String	必须	签名信息

其他约定

API 接口，可支持 GET/POST 请求，POST 请求时，可支持以 POST 实体 JSON 的方式，进行参数传递。
事件推送时，以 POST 实体 JSON 的方式，进行参数传递，返回值为 JSON 字符串，code 值为"0" 时，表示接受成功，其他为接受失败，msg 为接受失败的错误信息。返回示例如下：
JSON
```
{
    "code":"0",
    "msg":"success"
}
```

接口详情

添加会议

添加会议，仅用于其他用户以呼入的方式加入会议。

接口地址

/api/meet/add

请求参数

参数名称	参数名	类型	是否必须	说明
房间号	`room_id`	String	必须	声网房间号，即声网呼叫生成的房间号信息，用于接入 SIP 端呼叫。
会议号	`meet_num`	String	必须	会议号，用于呼入方输入，确认加入的会议室
呼入号码	`did_num`	String	必须	DID 号码，SIP 端所需的呼入号码

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	code	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	msg	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/add?room_id=346300810108500&meet_num=1234&did_num=xxxxxxxxxxxxx

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

获取 DID 号码在线并发数

查看用于呼入的 DID 号码的在线呼叫信息。

接口地址

/api/meet/online_for_did

请求参数

参数名称	参数名	类型	是否必须	说明
呼入号码	`did_num`	String	y	DID 号码，SIP 端所需的呼叫的被叫号码

返回参数

参数名	类型	是否必须	说明
`code`	String	必须	错误码，`000000` 为成功，其他为失败，例：`000001`
`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息
`data`	JSONArray	必须	在线呼叫信息
`data.room_id`	String	必须	在线呼叫的房间号
`data.caller`	String	必须	在线呼叫的主叫号码

请求示例

HTTP
http://ip:port/api/meet/online_for_did?did_num=xxxxxxxxxxxxx

返回示例

JSON
{
    "msg":"success",
    "code":"000000",
    "data":[
        {
            "room_id":"346300810108500",
            "caller":"16620137426"
        },
        {
            "room_id":"346300810108500",
            "caller":"18860233225"
        }
    ]
}

释放会议

释放会议信息，禁止其他用户呼入 DID 加入会议。

接口地址

/api/meet/delete

请求参数

参数名称	参数名	类型	是否必须	说明
呼入号码	`did_num`	String	必须	DID 号码，SIP 端所需的呼叫的被叫号码
房间号	`room_id`	String	必须	房间号
会议号	`meet_num`	String	必须	会议号

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/delete?room_id=346300810108500&meet_num=1234&did_num=xxxxxxxxxxxxx

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

禁言/解除禁言某个用户

禁言/解除禁言指定房间的指定用户。禁言即禁止相应用户发言。

接口地址

/api/meet/userMute

请求参数

参数名称	参数名	类型	是否必须	说明
被叫号码	`did_num`	String	必须	被叫号码
房间号	`room_id`	String	必须	房间号
主叫	`caller`	String	必须	主叫号码
是否禁言	`mute`	String	必须	`ON` 表示开启禁言，`OFF` 表示解除禁言

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/userMute?room_id=346300810108500&caller=16620137426&did_num=xxxxxxxxxxxxx&mute=ON

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

禁言/解除禁言全部用户

禁言/解除禁言指定房间内所有用户。禁言即禁止相应用户发言。

接口地址

/api/meet/userMuteAll

请求参数

参数名称	参数名	类型	是否必须	说明
房间号	`room_id`	String	必须	房间号
是否禁言	`mute`	String	必须	禁言：ON：开启禁言，OFF，解除禁言

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/userMuteAll?room_id=346300810108500&mute=ON

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

禁听/解除禁听某个用户

禁听/解除禁听指定房间内的指定用户。禁听，即禁止用户听到会议信息。

接口地址

/api/meet/userForbidListen

请求参数

参数名称	参数名	类型	是否必须	说明
主叫号码	`caller`	String	必须	主叫号码
被叫号码	`did_num`	String	必须	DID 号码，被叫号码
房间号	`room_id`	String	必须	房间号
是否禁听	`mute`	String	必须	禁言：ON：开启禁听，OFF，解除禁听

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/userForbidListen?room_id=346300810108500&caller=16620137426&did_num=xxxxxxxxxxxxx&mute=ON

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

禁听/解除禁听全部用户

禁听/解除禁听指定房间内的所有用户。

接口地址

/api/meet/userForbidListenAll

请求参数

参数名称	参数名	类型	是否必须	说明
房间号	`room_id`	String	必须	房间号
是否禁言	`mute`	String	必须	禁听：ON：开启禁听，OFF，解除禁听

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/userForbidListenAll?room_id=346300810108500mute=ON

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

用户申请发言未通过

用户按键申请发言时，管理员拒绝该用户的申请，调用该接口提示用户发言申请失败。

接口地址

/api/meet/applyNo

请求参数

参数名称	参数名	类型	是否必须	说明
主叫号码	`caller`	String	必须	房间号
被叫号码	`did_num`	String	必须	DID 号码，被叫号码
房间号	`room_id`	String	必须	房间号

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/applyNo?room_id=346300810108500&caller=16620137426&did_num=xxxxxxxxxxxxx

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

外呼手机号加入会议

调用该接口，直接外呼指定的手机号。该功能需要本系统技术方对接相关线路，请联系业务进行相关线路对接。对接时请说明是否对接自己的线路或者业务推荐相关线路。

接口地址

/api/meet/callAndJoin

请求参数

参数名称	参数名	类型	是否必须	说明
主叫号码	`caller`	String	必须	房间号
被叫号码	`phone`	String	必须	被叫号码
房间号	`room_id`	String	必须	房间号
声网的 uid 信息	`uid`	String	必须	加入房间的 uid 信息，用于 Token 验证，仅 Token 验证的方式可用

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/callAndJoin? caller= xxxxxxxxxxxxx&phone= 938616620137426& room_id=4244445308293274

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

外呼 SIP 用户

本接口为外呼 SIP 服务器用户接口，调用该接口可直接外呼指定的 SIP 账号。外呼时，caller（即送到 SIP 服务器的主叫信息）和 phone（即送到 SIP 服务器的被叫信息）可根据 SIP 服务器方需求自定义。

接口地址

/api/meet/callSIP

请求参数

参数名称	参数名	类型	是否必须	说明
主叫号码	`caller`	String	必须	房间号
被叫号码	`phone`	String	必须	被叫号码
房间号	`room_id`	String	必须	房间号
声网的 uid 信息	`uid`	String	必须	加入房间的 uid 信息，用于 Token 验证，仅 Token 验证的方式可用
SIPServer 地址	`gw`	String	必须	加入房间的 uid 信息，仅 Token 验证的方式可用

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/callSIP?room_id=346300810108500&&caller=xxxxxxxxxxxxx&phone=902020&gw=SIPServer:port

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

会议在线呼叫列表

本接口查看指定房间号内的在线呼叫信息。

接口地址

/api/meet/onlineForRoomid

请求参数

参数名称	参数名	类型	是否必须	说明
房间号	`room_id`	String	必须	房间号

返回参数

参数名	类型	是否必须	说明
`code`	String	必须	错误码，`000000` 为成功，其他为失败，例：`000001`
`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息
`data`	JSONArray	必须	在线呼叫信息
`data.uuid`	String	必须	在线呼叫的 uuid 信息
`data.uid`	String	必须	加入房间的 uid 信息
`data.caller`	String	必须	主叫
`data.creatAt`	String	必须	开始时间
`data.callSteps`	String	必须	呼叫阶段： `calling`：呼叫中 `connect`：接通中（振铃状态算接通中）
`data.callee`	String	必须	被叫
`data.mute`	String	必须	是否禁言: `off`: 未禁言 `on`: 已禁言
`data.forbidListen`	String	必须	是否禁听: `off`: 或空，未禁听 `on`: 已禁听
`data.updateTime`	String	必须	更新时间
`data.direction`	String	必须	呼叫方向: `in`: 呼入 `out`: 呼出

请求示例

HTTP
http://ip:port/api/meet/onlineForRoomid?roomid=346300810108500

返回示例

JSON
{
    "msg":"success",
    "code":"000000",
    "data":[
        {
            "uid":"1813467991",
            "caller":"xxxxx",
            "creatAt":"2020-07-14 14:56:9839",
            "callSteps":"calling",
            "callee":"xxxxxx",
            "mute":"on",
            "forbidListen":"off",
            "updateTime":1594709799098,
            "direction":"in"
        },
        {
            "uid":"1813467990",
            "caller":"xxxx",
            "creatAt":"2020-07-14 15:01:48939",
            "callSteps":"connect",
            "callee":"xxxxxx",
            "mute":"on",
            "forbidListen":"off",
            "updateTime":1594710099489,
            "direction":"in"
        }
    ]
}

从会议中踢出用户

调用本接口，可从指定房间号中，根据主叫被叫踢出指定用户。

注：踢出用户时所需的主叫被叫信息，需为会议在线呼叫列表中的主叫被叫信息。

接口地址

/api/meet/killCall

请求参数

参数名称	参数名	类型	是否必须	说明
主叫号码	`caller`	String	必须	主叫号码
被叫号码	`callee`	String	必须	被叫号码
房间号	`roomid`	String	必须	房间号

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/killCall?roomid=346300810108500&caller=xxxxxxxxxxxxx&callee=xxxxx

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

结束会议

本接口为结束会议接口。调用该接口会挂断指定房间的所有在线呼叫信息，即结束会议。

接口地址

/api/meet/endTheMeet

请求参数

参数名称	参数名	类型	是否必须	说明
房间号	`roomid`	String	必须	房间号

返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	String	必须	`000000` 为成功，其他为失败，例：`000001`
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为调用失败信息

请求示例

HTTP
http://ip:port/api/meet/endTheMeet?roomid=346300810108500

返回示例

JSON
{
    "code":"000000",
    "msg":"success"
}

消息推送 (Webhook)

本接口为呼叫/会议相关的时间推送，由技术方配置好推送地址后，呼叫/会议相关的事件，将推送 JSON 至推送地址。

推送地址

提供推送地址，联系业务员，安排技术人员对接。

推送参数

参数名	类型	是否必须	说明
`event`	String	Y	推送事件信息： `enterMeet`，用户进入会议 `leaveMeet`，用户离开会议 `logMeet`，用户离开会议时，该用户的会议日志信息 `dtmf`，按键事件推送 `SIPConnect`，外呼被叫端接听事件 `SIPHangUp`，挂断事件，其中 hangUpReason 参数取值如下： `SIP_disconnected_res`：正常挂断，其他为异常呼叫 `SIP_calling_res`，呼叫失败 `SIP_user_busy`，用户忙-接口端 `SIP_user_busy_res`，用户忙-被叫 SIP 端 `SIP_no_response_res`，用户未响应 `SIP_rejected_res`，用户拒接
`data`	JSON	Y	推送信息
`caller`	String	Y	主叫号码
`callee`	String	Y	被叫号码
`enter_time`	String	Y	进入会议时间
`leave_time`	String	N	离开会议时间，`logMeet` 事件时该值不为空
`bille`	Int	N	呼叫时长，`logMeet` 事件时该值不为空
`uuid`	String	Y	声网 uid 信息
`roomid`	String	Y	声网房间号
`dtmf`	String	N	用户按键信息，`dtmf` 事件时不为空

约定返回参数

参数名称	参数名	类型	是否必须	说明
错误码	`code`	Int	必须	0，为接受成功，其他为接受失败
错误信息	`msg`	String	必须	错误信息，`success` 为成功，其他为接受失败

推送示例

会议日志推送

JSON
{
    "data":{
        "caller":"16620137426",
        "leave_time":"1588844180002",
        "callee":"xxxxxxxxxxxxx",
        "bille":9,
        "enter_time":"1588844170327",
        "uuid":"3735235538",
        "roomid":"346300810108500"
    },
    "event":"logMeet"
}

用户按键推送

JSON
{
    "data":{
        "caller":"16620137426",
        "dtmf":"1234#",
        "callee":"xxxxxxxxxxxxx",
        "enter_time":"1588844170327",
        "uuid":"3735235538",
        "roomid":"346300810108500"
    },
    "event":"dtmf"
}

呼叫接通

JSON
{
    "data":{
        "caller":"902020",
        "connectTime":"2020-01-01 00:00:00",
        "callee":"82902020",
        "roomid":"12345678"
    },
    "event":"SIPConnect"
}

呼叫挂断

JSON
{
    "data":{
        "caller":"902020",
        "hangUpReason":"SIP_disconnected_res",
        "connectTime":"2020-07-20 11:30:14",
        "callee":"82902020",
        "roomid":"12345678",
        "hangUpTime":"2020-07-20 11:31:08"
    },
    "event":"SIPHangUp"
}

异常呼叫

JSON
{
    "data":{
        "caller":"12345678",
        "hangUpReason":"SIP_user_busy",
        "callee":"82902020",
        "roomid":"12345678",
        "hangUpTime":"2020-01-01 00:00:00"
    },
    "event":"SIPHangUp"
}

确定返回示例

JSON
{
    "code":0,
    "msg":"success"
}

服务器配置相关

选购方案

服务器选购建议：

服务器区域：根据业务区域就近部署。
服务器类型：计算型。
网络安全组（防火墙）：入方向允许其他 IP 访问所有端口。
请根据您的业务规模（并发数）选购。

推荐的选购方案如下：

并发数	CPU	内存	硬盘	带宽	系统版本
30	1核	2G	40GB	10M	Linux Centos 6.9 64bit
50	2核	4G	60GB	20M	Linux Centos 6.9 64bit
100	4核	8G	120GB	50M	Linux Centos 6.9 64bit
300	8核	16G	320GB	100M	Linux Centos 6.9 64bit
500	16核	32G	500GB	200M	Linux Centos 6.9 64bit
1000	24核	48G	1024GB	400M	Linux Centos 6.9 64bit

注意事项

安装脚本以 Centos 64 位的版本为准，其他类型 Linux 系统可能会由于系统环境，以及相关命令不同，容易安装失败。
32 位系统，由于编译环境不用，所以安装脚本会执行失败。
Centos 其他型号 64 位系统，如：6.0，6.4，7.x 型号的，也可安装，但推荐 6.9 型号的，较为稳定。
可自定义设置云盘大小，由于需要存储数据信息，所以根据业务数据大小进行设定。
带宽，建议按流量计费，由于固定带宽较贵，且本系统为呼叫中心类型的系统，需处理呼叫语音包，带宽较小时，会出现带宽不足的情况，所以建议按流量计费。
网络安全组，本系统为呼叫中心系统，进行外呼时，需要用到 16384~32768，以及其他端口，需开放的端口较多，后续可在服务器内部设定防火墙信息，所以建议开放所有端口。
登录密码，若需要启智配合安装，则需要给予我们服务器的 SSH 的访问权限，也可以设定为密匙登录，按需配置。

概述​

通讯协议​

签名方式​

公共参数​

其他约定​

接口详情​

添加会议​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

获取 DID 号码在线并发数​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

释放会议​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

禁言/解除禁言某个用户​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

禁言/解除禁言全部用户​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

禁听/解除禁听某个用户​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

禁听/解除禁听全部用户​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

用户申请发言未通过​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

外呼手机号加入会议​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

外呼 SIP 用户​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

会议在线呼叫列表​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

从会议中踢出用户​

接口地址​

请求参数​

返回参数​

请求示例​

返回示例​

结束会议​

接口地址​

概述

通讯协议

签名方式

公共参数

其他约定

接口详情

添加会议

接口地址

请求参数

返回参数

请求示例

返回示例

获取 DID 号码在线并发数

接口地址

请求参数

返回参数

请求示例

返回示例

释放会议

接口地址

请求参数

返回参数

请求示例

返回示例

禁言/解除禁言某个用户

接口地址

请求参数

返回参数

请求示例

返回示例

禁言/解除禁言全部用户

接口地址

请求参数

返回参数

请求示例

返回示例

禁听/解除禁听某个用户

接口地址

请求参数

返回参数

请求示例

返回示例

禁听/解除禁听全部用户

接口地址

请求参数

返回参数

请求示例

返回示例

用户申请发言未通过

接口地址

请求参数

返回参数

请求示例

返回示例

外呼手机号加入会议

接口地址

请求参数

返回参数

请求示例

返回示例

外呼 SIP 用户

接口地址

请求参数

返回参数

请求示例

返回示例

会议在线呼叫列表

接口地址

请求参数

返回参数

请求示例

返回示例

从会议中踢出用户

接口地址

请求参数

返回参数

请求示例

返回示例

结束会议

接口地址