专线电话接入指引
说明
专线电话服务可提供基于运营商网络的回拨电话和多人电话会议功能,支持国内手机号码和固定电话。
返回接口格式
{
"code":200,
"msg":"this is for errmsg!",
"obj":"for return object"
}
- code: 错误码字段,具体见错误码定义;
- msg:错误信息描述字段,返回人阅读友好的错误信息 ;
- obj: 返回请求结果数据,json格式内容。
接口限制
- 单通专线电话时长有限制;
- 专线会议参与方的数量有限制,默认3--8人(含主叫方);
- 专线电话是收费功能,需联系客户顾问开通才能使用;
- 如需使用回调通知需联系客户顾问开通和配置。
发起单人专线电话
请求说明
POST https://api.netease.im/call/ecp/startcall.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求中Headers的设置请参考接口概述
接口描述
发起专线电话呼叫请求,请求成功之后会依次呼叫主叫方和被叫方的号码,两边接听电话之后即可建立通话。主叫和被叫的号码仅支持国内手机号码和固定电话号码。
参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
callerAcc | String | 是 | 发起本次请求的用户的accid |
caller | String | 是 | 主叫方电话号码(不带+86这类国家码,下同) |
callee | String | 是 | 被叫方电话号码 |
maxDur | int | 是 | 本通电话最大可持续时长,单位秒,超过该时长时通话会自动切断。 |
record | String | 否 | 本通电话是否需要录音,true或false,默认false,(appkey需要开启专线电话录音功能)。 |
curl请求示例
curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "charset: utf-8" -H "Content-Type: application/x-www-form-urlencoded" -d 'callerAcc=zhangsan&caller=13812341234&callee=13856785678&maxDur=60' 'https://api.netease.im/call/ecp/startcall.action'
返回说明
http 响应:json
"Content‐type":"application/json;charset=utf‐8"
{
"obj": {
"session": "61deedeb‐0396‐4ca5‐bc1a‐40bf322d46f6",
"calleeDisplay": "18088888888",
"callerDisplay": "13666666666"
},
"code": 200
}
- session: 本次通话的id号,后续可通过这个id号查询本次通话的时长等信息;
- calleeDisplay: 被叫方收到的专线回拨显号号码;
- callerDisplay: 主叫方收到的专线回拨显号号码;
主要的返回码
200、403、414、417、500
具体请参考code状态表
发起专线会议
请求说明
POST https://api.netease.im/call/ecp/startconf.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求中Headers的设置请参考接口概述
接口描述
发起专线会议呼叫请求,会先接通主叫方的电话,主叫接通之后依次接通各个被叫,所有人都会在同一个频道中通话。
参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
callerAcc | String | 是 | 发起本次请求的用户的accid |
caller | String | 是 | 主叫方电话号码(不带+86这类国家码,下同) |
callee | String | 是 | 所有被叫方电话号码,必须是json格式的字符串,如["13588888888","13699999999"] |
maxDur | int | 是 | 本通电话最大可持续时长,单位秒,超过该时长时通话会被自动切断, 会议时长计算规则是所有单路时长之和 |
curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "charset: utf-8" -H "Content-Type: application/x-www-form-urlencoded" -d 'callerAcc=zhangsan&caller=13812345678&callee=["13811111111","13822222222"]&maxDur=60' 'https://api.netease.im/call/ecp/startconf.action'
返回说明
http 响应:json
"Content‐type":"application/json;charset=utf‐8"
{
"obj": {
"session": "61deedeb‐0396‐4ca5‐bc1a‐40bf322d46f6",
"calleeDisplay": "40012345678",
"callerDisplay": "40012345678"
},
"code": 200
}
主要的返回码
200、403、414、417、500
具体请参考code状态表
查询专线电话或会议的详情
请求说明
POST https://api.netease.im/call/ecp/queryBySession.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求中Headers的设置请参考接口概述
接口描述
根据发起通话请求中返回的会话session,查询单通电话的通话信息,如时长,接入时间,主被叫号码等。
参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
session | String | 是 | 本次通话的id号 |
type | int | 是 | 通话类型,1:专线电话,2:专线会议 |
curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "charset: utf-8" -H "Content-Type: application/x-www-form-urlencoded" -d 'session=4af9ec50-6rd5-4cc7-b20d-68abc52fb294&type=1' 'https://api.netease.im/call/ecp/queryBySession.action'
返回说明
http 响应:json
专线电话查询结果示例:
"Content‐type":"application/json;charset=utf‐8"
{
"obj": {
"caller": "18088888888",
"initAccount": "zhangsan",
"session": "61deedeb‐0396‐4ca5‐bc1a‐40bf322d46f6",
"callee": "13600000000",
"status": "SUCCESS",
"recordUrl": "http://nos.netease.com/voip001/2015-06-08_7bfa6dcb-2ea7-408d-88c2-aa55dbce8f4a.mp3",
"durationSec": 0,
"starttime": "2015‐06‐0822:20:11",
"createtime": 1433773159894,
"legs": [
{
"endTime": "2016-05-16 20:59:05",
"endpoint": "15967166074",
"hangCause": "NORMAL_CLEARING"
},
{
"endTime": "2016-05-16 20:59:05",
"endpoint": "18605818212",
"hangCause": "ORIGINATOR_CANCEL"
}
],
},
"code": 200
}
专线电话查询结果中的字段释义:
- caller: 主叫方电话号码;
- initAccount: 发起呼叫请求的account;
- session: 本次通话的id号,后续可通过这个id号查询本次通话的时长等信息;
- callee: 被叫方电话号码;
- status: 通话状态,
INITED
表示发起通话,SUCCESS
表示通话结束; - recordUrl: 录音文件下载地址。录音文件因话单时长的计算方法,与录音时长间有1秒误差,通话内容录制是100%完整的;
- durationSec: 该次通话持续的时长,单位秒;
- starttime: 该次通话接通的时间点;
- createtime: 该次通话发起的时间点;
- legs: 双人通话中双方的接听状态和结束时间,多人会议不支持此字段;
- 其他错误码见code状态表。
专线会议查询结果示例:
"Content‐type":"application/json;charset=utf‐8"
{
"obj": {
"createtime": 1463403551392,
"starttime": "2016-05-16 20:59:11",
"status": "SUCCESS",
"session": "fcc603b4-e0b3-469a-956b-6650b7623c5c",
"durationSec": 0,
"initAccount": "zqt",
"members": "[\"15967166000\",\"18605818000\",\"18158128000\"]"
},
"code": 200
}
专线会议查询结果中的字段释义:
- createtime: 该次通话发起的时间点;
- starttime: 该次通话接通的时间点;
- status: 通话状态,
INITED
表示发起通话,SUCCESS
表示通话结束; - session: 本次通话的id号,后续可通过这个id号查询本次通话的时长等信息;
- durationSec: 该次通话持续的时长,单位秒;
- initAccount: 发起呼叫请求的account;
- members: 所有参与电话会议的电话号码
主要的返回码
200、404、414、500
具体请参考code状态表
通话结束回调
说明
专线电话通话结束回调是指在双人通话或会议通话最后一个人退出通话过程之后,由网易云信服务端主动向应用提供的接口中POST该通会话的详情(其内容与1.7.3接口中取到的响应相同),第三方可借助该接口实时了解通话结束状态。
通知接口要求
需要开发者提供一个http接口的回调地址,支持POST方法,并保证该接口公网可访问并具有较快的响应时间。
回调请求格式
包头Header
ContentType=application/json,
AppKey=fk416670c8e8a72774819f184vah2577,
CurTime=1442046775227,
MD5=ebc80f130991d3a92c494832c4de0b31,
CheckSum=2640bb6074d0cddb370d8f6dac9aa9a981f98126
- AppKey:接入应用的appkey;
- CurTime:发送通知请求时的时间戳,单位毫秒;
- MD5:通知内容文本的md5,开发者可借此判断通知是否被篡改;
- CheckSum: 通知校验码,第三方可以以此鉴定该通知是来自网易云信服务,校验规则如下:
CheckSum = sha1(AppSecret+MD5+CurTime)
。
请求body的内容,如
双人呼叫回调示例:
{
"caller": "18088888888",
"initAccount": "zhangsan",
"session": "61deedeb‐0396‐4ca5‐bc1a‐40bf322d46f6",
"callee": "13600000000",
"status": "SUCCESS",
"recordUrl": "http://nos.netease.com/voip001/2015-06-08_7bfa6dcb-2ea7-408d-88c2-aa55dbce8f4a.mp3",
"durationSec": 0,
"starttime": "2015‐06‐0822:20:11",
"createtime": 1433773159894,
"legs": [
{
"endTime": "2015‐06‐08 22:20:21",
"endpoint": "180888888888",
"hangCause": "NORMAL_CLEARING"
},
{
"endTime": "2015‐06‐08 22:20:21",
"endpoint": "13600000000",
"hangCause": "NORMAL_CLEARING"
}
]
}
双人呼叫回调中的字段释义:
- caller: 主叫方电话号码
- initAccount:发起呼叫的accid
- session:会话id
- callee: 被叫方电话号码
- status:状态,
INITED
表示发起通话;SUCCESS
表示通话结束 - recordUrl: 录音文件下载地址。录音文件因话单时长的计算方法,与录音时长间有1秒误差,通话内容录制是100%完整的。
- durationSec:通话时长,单位秒
- starttime:通话发起的时间
- createtime:请求创建时间,单位毫秒
- legs:双人通话中双方的接听状态和结束时间,多人会议不支持此字段。其中legs.endpoint: 参与方号码;legs.endTime:退出通话的时间戳;legs.hangCause:挂断状态码。挂断状态码详见如下:
状态码 | 说明 |
---|---|
CALL_REJECTED | 呼叫被拒绝, 正常 |
NO_ANSWER | 呼叫未应答, 正常 |
NONE | 如果一方主动挂断,另一方为平台挂断则为NONE, 正常 |
NORMAL_CLEARING | 双方都由运营商挂断, 正常 |
NORMAL_TEMPORARY_FAILURE | FAILURE:呼叫线路超时 |
NORMAL_UNSPECIFIED | 一般是线路不通, 可能盲区 |
NO_USER_RESPONSE | 呼叫未应答超时, 正常 |
RECOVERY_ON_TIMER_EXPIRE | 一般是媒体超时, 异常 |
UNALLOCATED_NUMBER | 一般是线路不通, 可能盲区 |
USER_BUSY | 用户占线繁忙, 正常 |
其他状态码 | 参考:https://wiki.freeswitch.org/wiki/Hangup_Causes |
备注:被叫直接挂断时,由于线路原因,可能出现CALL_REJECTED、NORMAL_CLEARING、ORIGINATOR_CANCEL等几种状态码。
多人会议回调示例:
{
"createtime": 1455856546421,
"starttime": "2016-02-19 12:35:46",
"status": "SUCCESS",
"session": "fff55eb2-9c9c-4a98-9d61-21b78bf1804b",
"durationSec": 140,
"initAccount": "600100",
"members": "[\"18812345678\",\"18812345679\",\"18812345668\",\"18812345671\",\"18812345672\"]"
}
多人会议回调中的字段释义:
- createtime:请求创建时间,单位毫秒
- starttime:通话发起的时间
- status:状态。INITED表示发起通话; SUCCESS表示通话结束;
- session:会话id
- durationSec:通话时长,单位秒
- initAccount:发起呼叫的accid
- members: 所有参与电话会议的电话号码
通话信息实时通知的内容与主动查询接口获取的内容保持一致
回调响应
回调接口在收到来自网易云信的回调通知之后只需要返回200响应码即可,为保证响应速度,建议开发者在回调接口中隔离内部业务逻辑,收到回调通知即返回200响应码。
其他注意
本接口注重通知的实时性(电话挂断即可收到通知),如回调接口不可用导致通知失败,该通知请求将不会再重发通知请求,开发者可使用queryBySession.action
接口来查询该通会话的详情。
主动挂断正在进行的通话
请求说明
POST https://api.netease.im/call/ecp/hangSession.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8
请求中Headers的设置请参考接口概述
接口描述
如果指定的通话还在进行,可以通过服务器端强制挂断
参数说明
参数 | 类型 | 必须 | 说明 |
---|---|---|---|
session | String | 是 | 本次通话的id号 |
type | int | 是 | 通话类型,1:专线电话,2:专线会议 |
curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "charset: utf-8" -H "Content-Type: application/x-www-form-urlencoded" -d 'session=2b4573cf-011a-4534-a929-956379c059d2&type=1' 'https://api.netease.im/call/ecp/hangSession.action'
返回说明
http 响应:json
专线电话挂断结果示例:
"Content‐type":"application/json;charset=utf‐8"
{
"msg": "session with sessionid '2b4573cf-011a-4534-a929-956379c059d2' already ended!",
"code": 403
}
专线电话挂断结果中的code释义:
- 200: 挂断成功;
- 403: 会话已经结束,不允许再次挂断;
- 404: 会话不存在;
- 414: 参数错误;
- 417: 同一个会话的挂断请求不能连续发起;
- 500: 超时或未知错误;