专线电话接入指引(暂停售卖)

说明

专线电话服务可提供基于运营商网络的回拨电话和多人电话会议功能,支持国内手机号码和固定电话。

返回接口格式

{ "code":200, "msg":"this is for errmsg!", "obj":"for return object" }

  1. code: 错误码字段,具体见错误码定义;
  2. msg:错误信息描述字段,返回人阅读友好的错误信息 ;
  3. obj: 返回请求结果数据,json格式内容。

接口限制

  1. 单通专线电话时长有限制;
  2. 专线会议参与方的数量有限制,默认3--8人(含主叫方);
  3. 专线电话是收费功能,需联系客户顾问开通才能使用;
  4. 如需使用回调通知需联系客户顾问开通和配置。

发起单人专线电话

请求说明

POST https://api.netease.im/call/ecp/startcall.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

发起专线电话呼叫请求,请求成功之后会依次呼叫主叫方和被叫方的号码,两边接听电话之后即可建立通话。主叫和被叫的号码仅支持国内手机号码和固定电话号码。

参数说明

参数类型必须说明
callerAccString发起本次请求的用户的accid
callerString主叫方电话号码(不带+86这类国家码,下同)
calleeString被叫方电话号码
maxDurint本通电话最大可持续时长,单位秒,超过该时长时通话会自动切断。
recordString本通电话是否需要录音,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
}

主要的返回码

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的设置请参考接口概述

接口描述

发起专线会议呼叫请求,会先接通主叫方的电话,主叫接通之后依次接通各个被叫,所有人都会在同一个频道中通话。

参数说明

参数类型必须说明
callerAccString发起本次请求的用户的accid
callerString主叫方电话号码(不带+86这类国家码,下同)
calleeString所有被叫方电话号码,必须是json格式的字符串,如["13588888888","13699999999"]
maxDurint本通电话最大可持续时长,单位秒,超过该时长时通话会被自动切断, 会议时长计算规则是所有单路时长之和
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,查询单通电话的通话信息,如时长,接入时间,主被叫号码等。

参数说明

参数类型必须说明
sessionString本次通话的id号
typeint通话类型,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
}

专线电话查询结果中的字段释义:

专线会议查询结果示例:

"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
}

专线会议查询结果中的字段释义:

主要的返回码

200、404、414、500

具体请参考code状态表


通话结束回调

说明

专线电话通话结束回调是指在双人通话或会议通话最后一个人退出通话过程之后,由云信服务端主动向应用提供的接口中POST该通会话的详情(其内容与1.7.3接口中取到的响应相同),第三方可借助该接口实时了解通话结束状态。

通知接口要求

需要开发者提供一个http接口的回调地址,支持POST方法,并保证该接口公网可访问并具有较快的响应时间。

回调请求格式

包头Header

ContentType=application/json,    
AppKey=fk416670c8e8a72774819f184vah2577, 
CurTime=1442046775227,     
MD5=ebc80f130991d3a92c494832c4de0b31, 
CheckSum=2640bb6074d0cddb370d8f6dac9aa9a981f98126
  1. AppKey:接入应用的appkey;
  2. CurTime:发送通知请求时的时间戳,单位毫秒;
  3. MD5:通知内容文本的md5,开发者可借此判断通知是否被篡改;
  4. 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"
    }
  ]
}

双人呼叫回调中的字段释义:

状态码说明
CALL_REJECTED呼叫被拒绝, 正常
NO_ANSWER呼叫未应答, 正常
NONE如果一方主动挂断,另一方为平台挂断则为NONE, 正常
NORMAL_CLEARING双方都由运营商挂断, 正常
NORMAL_TEMPORARY_FAILUREFAILURE:呼叫线路超时
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\"]"
}

多人会议回调中的字段释义:

通话信息实时通知的内容与主动查询接口获取的内容保持一致

回调响应

回调接口在收到来自云信的回调通知之后只需要返回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的设置请参考接口概述

接口描述

如果指定的通话还在进行,可以通过服务器端强制挂断

参数说明

参数类型必须说明
sessionString本次通话的id号
typeint通话类型,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释义: