号码隐私保护服务端API文档

接口概述

API调用说明

本文档中,所有调用网易云通信服务端接口的请求都需要按此规则校验。

API checksum校验

以下参数需要放在Http Request Header中

参数 参数说明
AppKey 开发者平台分配的appkey
Nonce 随机数(最大长度128个字符)
CurTime 当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的秒数(String)
CheckSum SHA1(AppSecret + Nonce + CurTime),三个参数拼接的字符串,进行SHA1哈希计算,转化成16进制字符(String,小写)

CheckSum有效期:出于安全性考虑,每个checkSum的有效期为5分钟(用CurTime计算),建议每次请求都生成新的checkSum,同时请确认发起请求的服务器是与标准时间同步的,比如有NTP服务。

CheckSum检验失败时会返回414错误码,具体参看code状态表。

重要提示: 本文档中提供的所有接口均面向开发者服务器端调用,用于计算CheckSum的AppSecret开发者应妥善保管,可在应用的服务器端存储和使用,但不应存储或传递到客户端,也不应在网页等前端代码中嵌入。

计算CheckSum的java代码举例如下 ( 其他语言示例见下方接口示例) :

import java.security.MessageDigest;

public class CheckSumBuilder {
    // 计算并获取CheckSum
    public static String getCheckSum(String appSecret, String nonce, String curTime) {
        return encode("sha1", appSecret + nonce + curTime);
    }

    // 计算并获取md5值
    public static String getMD5(String requestBody) {
        return encode("md5", requestBody);
    }

    private static String encode(String algorithm, String value) {
        if (value == null) {
            return null;
        }
        try {
            MessageDigest messageDigest
                    = MessageDigest.getInstance(algorithm);
            messageDigest.update(value.getBytes());
            return getFormattedText(messageDigest.digest());
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
    private static String getFormattedText(byte[] bytes) {
        int len = bytes.length;
        StringBuilder buf = new StringBuilder(len * 2);
        for (int j = 0; j < len; j++) {
            buf.append(HEX_DIGITS[(bytes[j] >> 4) & 0x0f]);
            buf.append(HEX_DIGITS[bytes[j] & 0x0f]);
        }
        return buf.toString();
    }
    private static final char[] HEX_DIGITS = { '0', '1', '2', '3', '4', '5',
            '6', '7', '8', '9', 'a', 'b', 'c', 'd', 'e', 'f' };
}

接口说明

  1. IM服务端所有接口都只支持POST请求;
  2. 所有接口请求Content-Type类型为:application/x-www-form-urlencoded;charset=utf-8;
  3. 所有接口返回类型为JSON,同时进行UTF-8编码。

接口示例

网易云通信服务端接口是简单的http接口,适配各种语言。 当然我们也提供了一些简单的示例供开发者参考。网易云通信服务器接口示例


号码隐私保护(AXB模式)

AXB模式绑定

请求说明

POST https://api.netease.im/smallphone/axb/bind HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

接口描述

AXB模式绑定,给用户 A、用户 B绑定一个小号 X。

参数说明

参数类型必须说明
phoneAString用户A号码。格式遵循国际电信联盟定义的E.164标准 手机号前加86,如:8613511112222 固话前加86加区号(首位0不写),如:北京固话 861082325588
phoneBString用户B号码。格式遵循国际电信联盟定义的E.164标准 手机号前加86,如:8613511112222 固话前加86加区号(首位0不写),如:北京固话 861082325588
phoneXString小号号码。格式遵循国际电信联盟定义的E.164标准
areaCodeInteger小号区号。需要选择的小号所属区号,例如:北京(10),目前最多为3位
expirationInteger绑定有效期设置长度。单位为分钟,这里的值为正数,最大值为:525600(即1年)
recordFlagInteger是否对通话进行录音,0:否,1:是,默认为0
userDataString透传参数。最大长度为150字符

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "Content-Type: application/x-www-form-urlencoded" -d 'phoneA=8613511112222&phoneB=8613533334444&phoneX=8613512345678&expiration=60' 'https://api.netease.im/smallphone/axb/bind'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "bindId": "02201808081112188538032951", // 绑定关系ID
    "phoneX": "8613912345678" // 小号号码
}

主要返回码

200、403、414、416、431、500、601、602、603


AXB模式解绑

请求说明

POST https://api.netease.im/smallphone/axb/unbind HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

接口描述

AXB模式解绑,解除用户 A、用户 B和小号 X的绑定。

参数说明

参数类型必须说明
bindIdString绑定关系ID

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "Content-Type: application/x-www-form-urlencoded" -d 'bindId=04201609051011220123456789' 'https://api.netease.im/smallphone/axb/unbind'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200 
}

主要返回码

200、403、414、416、431、500


AXB模式绑定延期

请求说明

POST https://api.netease.im/smallphone/axb/delay HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

接口描述

AXB模式绑定延期,延长绑定关系有效期。

参数说明

参数类型必须说明
bindIdString绑定关系ID
deltaInteger绑定有效期延长长度。单位为分钟,这里的值为正数,最大值为:525600(即1年)

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "Content-Type: application/x-www-form-urlencoded" -d 'bindId=04201609051011220123456789&delta=60' 'https://api.netease.im/smallphone/axb/delay'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200 
}

主要返回码

200、403、414、416、431、500


AXB模式绑定查询

请求说明

POST https://api.netease.im/smallphone/axb/query HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

接口描述

AXB模式绑定查询,获取正在使用的绑定信息。

参数说明

参数类型必须说明
phoneXString小号X号码。格式遵循国际电信联盟定义的E.164标准
bindIdString绑定关系ID
opTypeInteger查询类型。0:根据小号号码查询,1:根据绑定ID查询

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Nonce: 4tgggergigwow323t23t" -H "Content-Type: application/x-www-form-urlencoded" -d 'phoneX=8613912345678&opType=0' 'https://api.netease.im/smallphone/axb/query'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200 
  "bindInfos": [
          {
              "bindId": "02201808081112188538032950", // 绑定关系ID
              "phoneA": "8613512345678", // 用户A号码
              "phoneB": "8613712345678", // 用户B号码
              "phoneX": "8613912345678", // 小号X号码
              "expireTime": 1521082125500, // 失效时间
              "recordFlag": 1, // 录音标志
              "userData": "", // 透传参数
              "createTime": 1506652312445, // 创建时间
              "updateTime": 1521082125400 // 更新时间
          },
          {
              "bindId": "02201808081112188538032951",
              "phoneA": "8613612345678",
              "phoneB": "8613812345678",
              "phoneX": "8613912345678",
              "expireTime": 1521082125600,
              "recordFlag": 1,
              "userData": "",
              "createTime": 1506652312545,
              "updateTime": 1521082125500
          }
      ]
}

主要返回码

200、403、414、416、431、500


code状态表

code 详细描述
200 操作成功
403 非法操作或没有权限
404 对象不存在
414 参数错误
416 频率控制
417 重复操作
419 数量超过上限
431 HTTP重复请求
500 服务器内部错误
514 服务不可用
号码隐私保护相关错误码
601 绑定数量超限
602 号码间已绑定
603 无可分配小号
运营商相关错误码
2** 运营商相关错误码

号码隐私保护事件抄送

AXB模式通话结束话单抄送

假设第三方开发者的消息接收地址为:http://yunxinservice.com.cn/receiveMsg.action.以下的抄送地址均假设为此接口,不再赘述。

"eventType"="32"

HTTP示例

POST  /receiveMsg.action   HTTP/1.1
Host:  yunxinservice.com.cn
Content-Type:  application/json
CurTime: 1440570500855    //当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String)
MD5: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx //根据请求中的request body计算出来的MD5值
CheckSum: 001511b8435e0b28044ca50a78e8f983026c5e01

{"callId":"22019122718533304786364931","callDuration":"0","finishTime":"20191227185347","userData":"abc","callNo":"8618667016326","phoneX":"8618413277972","eventType":"32","bindId":"02201912271851578829810300","finishType":"1","finishState":"3","startTime":"20191227185347","peerNo":"8618072928687","callTime":"20191227185333"}

cURL示例

curl -X POST -H "Content-Type: application/json" -H "CurTime: 1440570500855" -H "MD5: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "CheckSum: 001511b8435e0b28044ca50a78e8f983026c5e01" -d '{"callId":"22019122718533304786364931","callDuration":"0","finishTime":"20191227185347","userData":"abc","callNo":"8618667016326","phoneX":"8618413277972","eventType":"32","bindId":"02201912271851578829810300","finishType":"1","finishState":"3","startTime":"20191227185347","peerNo":"8618072928687","callTime":"20191227185333"}' 'http://yunxinservice.com.cn/receiveMsg.action'

消息体中的JSON字段说明

参数类型说明
eventTypeString值为32,表示是通话话单抄送
bindIdString绑定关系ID
callIdString通话ID
callNoString主叫号码
peerNoString被叫号码
phoneXString小号号码
callTimeString通话发生时间
startTimeString通话开始时间
finishTimeString通话结束时间
callDurationString通话时长
finishTypeString结束发起方:0: 平台结束,1:主叫结束,2:被叫结束。
finishStateString结束状态(即挂断原因)
userDataString透传参数

AXB模式短信话单抄送

"eventType"="33"

HTTP示例

POST  /receiveMsg.action   HTTP/1.1
Host:  yunxinservice.com.cn
Content-Type:  application/json
CurTime: 1440570500855    //当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String)
MD5: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx //根据请求中的request body计算出来的MD5值
CheckSum: 001511b8435e0b28044ca50a78e8f983026c5e01

{"callId":"2009041383632679721227165500","callNo":"8618667016326","phoneX":"8618413277972","eventType":"33","smsResult":"1","bindId":"02201912271648385109656661","peerNo":"8618072928687","smsTime":"20191227165500"}

cURL示例

curl -X POST -H "Content-Type: application/json" -H "CurTime: 1440570500855" -H "MD5: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "CheckSum: 001511b8435e0b28044ca50a78e8f983026c5e01" -d '{"callId":"2009041383632679721227165500","callNo":"8618667016326","phoneX":"8618413277972","eventType":"33","smsResult":"1","bindId":"02201912271648385109656661","peerNo":"8618072928687","smsTime":"20191227165500"}' 'http://yunxinservice.com.cn/receiveMsg.action'

消息体中的JSON字段说明

参数类型说明
eventTypeString值为33,表示是短信话单抄送
bindIdString绑定关系ID
callIdString通话ID
callNoString主叫号码
peerNoString被叫号码
phoneXString小号号码
smsTimeString发送短信时间
smsResultString短信发送结果
userDataString透传参数

AXB模式通话录音地址抄送

"eventType"="34"

HTTP示例

POST  /receiveMsg.action   HTTP/1.1
Host:  yunxinservice.com.cn
Content-Type:  application/json
CurTime: 1440570500855    //当前UTC时间戳,从1970年1月1日0点0 分0 秒开始到现在的毫秒数(String)
MD5: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx //根据请求中的request body计算出来的MD5值
CheckSum: 001511b8435e0b28044ca50a78e8f983026c5e01

{"callId":"320191227161938014369095340","userData":"abc","eventType":"34","bindId":"03201912271618250873761918","url":"https://nim.nos.netease.com/smallphone/819f9b6c-ade5-43d2-8f2a-34d065caf7ae/audioInfo1577434848265","md5":"091b601db45c4daf095f33bf5eaecebc"}

cURL示例

curl -X POST -H "Content-Type: application/json" -H "CurTime: 1440570500855" -H "MD5: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "CheckSum: 001511b8435e0b28044ca50a78e8f983026c5e01" -d '{"callId":"320191227161938014369095340","userData":"abc","eventType":"34","bindId":"03201912271618250873761918","url":"https://nim.nos.netease.com/smallphone/819f9b6c-ade5-43d2-8f2a-34d065caf7ae/audioInfo1577434848265","md5":"091b601db45c4daf095f33bf5eaecebc"}' 'http://yunxinservice.com.cn/receiveMsg.action'

消息体中的JSON字段说明

参数类型说明
eventTypeString值为34,表示是录音地址抄送
bindIdString绑定关系ID
callIdString通话ID
userDataString透传参数
urlString录音url
md5String录音md5