IM 即时通讯
服务端
服务端集成新手指南
接口及业务限制
更新日志
平台服务
第三方回调
第三方回调概述
消息相关回调
用户信息相关回调
高级群相关回调
超大群相关回调
聊天室相关回调
音视频1.0相关回调
登录相关回调
圈组相关回调
消息抄送
消息抄送服务概述
开通消息抄送
IM会话相关抄送
IM 会话已读数据抄送
IM其他抄送
圈组相关抄送
音视频和白板相关抄送
安全通
安全通概述
开通 IM 安全通
最佳实践
聊天室重要消息投递
IM 平滑迁移方案
API 参考
API调用方式
状态码
云信 IM 账号管理
注册云信IM账号
刷新Token
封禁账号
账号全局禁言
设置移动端是否需要推送(桌面端在线时)
登录鉴权
消息功能
发送消息
消息撤回
发送广播消息
文件上传
删除单条消息
删除漫游消息
删除所有会话的消息
自定义系统通知
用户名片
用户关系管理
好友关系管理
黑名单/静音管理
群组功能
群组功能(高级群)
创建高级群
拉人入群
发送群消息
添加管理员
移除管理员
转让群主
禁言群组
禁言指定群成员
踢人出群
主动退群
修改群昵称
修改群组信息
设置群消息提醒开关
解散群组
获取群组详细信息
获取群组禁言列表
获取群消息已读未读详情
获取用户已加入的群组信息
获取用户已加入的群组的所有群成员信息
获取群组的在线成员列表
批量获取群组信息与成员列表
批量获取群组的在线成员数量
群组功能(超大群)
创建超大群
拉人入群
发送超大群消息
发送超大群自定义系统通知
撤回超大群消息
添加管理员
移除管理员
转让群主
禁言超大群
禁言指定超大群成员
踢人出群
主动退群
修改超大群昵称
修改超大群信息
设置超大群消息提醒开关
解散超大群
修改超大群人数级别
获取超大群信息
获取超大群成员信息
获取超大群禁言成员信息
获取已加入的超大群信息
查询超大群云端历史消息
聊天室
创建聊天室
获取聊天室地址
更新聊天室信息
修改聊天室开放/关闭状态
设置聊天室定时关闭
关闭聊天室进出通知
管理聊天室用户角色
获取聊天室成员列表
管理聊天室消息
发送聊天室全服广播消息
管理聊天室机器人
聊天室禁言
聊天室标签
管理聊天室队列
管理聊天室队列元素
查询聊天室信息
查询聊天室统计指标
圈组功能
获取圈组服务端连接地址
圈组服务器管理
圈组服务器成员管理
频道管理
频道分组管理
身份组相关
服务器身份组
身份组成员管理
频道身份组
频道用户定制权限
频道分组身份组
频道分组用户定制权限
身份组自定义权限
查询用户拥有的权限
圈组消息收发
圈组系统通知
搜索结果自定义排序
修改服务器自定义排序值
修改频道自定义排序值
在线状态订阅
历史消息记录
云端历史消息查询
IM 登录/登出记录查询
广播消息查询
文本翻译

API调用方式

更新时间: 2022/11/28 15:18:28

应用服务端调用 API 向云信 IM 服务端发起的请求需遵循固定的请求结构和请求方式。

请求概述

  • 通信协议:IM 服务端 API 是是简单的 HTTP/HTTPS 接口,适配各种语言。

  • 请求方式:应用服务端向 IM 服务端发起的所有请求都只支持 POST 方式。

  • 服务地址: 网易云信 IM 服务端 API 的接入地址为https://api.netease.im/nimserver

    上述接入地址的域名(api.netease.im)属于国内数据中心域名。如果您的应用主要服务于海外用户,建议将域名设置为海外数据中心域名(api-sg.netease.im),相应的海外接入地址为 https://api-sg.netease.im/nimserver。更多海外数据中心接入相关说明,请参见接入海外数据中心

  • 请求结构:IM 服务端 API 请求结构主要由下表所示三部分组成。

    组成部分
    说明
    URL 指向具体的业务请求,请参见各 API 文档
    注意: 如果您的应用主要服务于海外用户,建议将 URL 中的国内数据中心域名(api.netease.im)替换为海外数据中心域名(api-sg.netease.im
    Header 请求头,包含云信 App Key、CheckSum 等在内的公共请求参数,用于鉴权。应用服务端请求 IM 服务端的所有 API 调用均采用相同的 Header 公共请求参数配置
    Body 请求体,包含 API 对应的业务参数,具体参见各 API 文档的请求参数小节

请求头(Header)

调用 IM 服务端 API 的请求,都需要在 Header 中传入CheckSum进行鉴权。

Header参数

Header 参数为公共请求参数,应用服务端请求云信 IM 服务端,都需在Header 中配置如下参数。

参数
参数说明
AppKey 通过云信控制台获取,详见获取 App key
Nonce 随机数(最大长度 128 个字符)
CurTime 当前 UTC 时间戳,从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在(指发起请求瞬间的前后 5 分钟内)的秒数(类型为 String)
CheckSum SHA1(AppSecret + Nonce + CurTime),将该三个参数拼接的字符串进行 SHA1 哈希计算从而生成 16 进制字符(类型为 String,小写)
  • 出于安全性考虑,每个CheckSum有效期5 分钟(用CurTime计算),建议每次请求都生成新的CheckSum,同时请确认发起请求的服务器是与标准时间同步的,比如有NTP服务。
  • CheckSum检验失败时会返回 414 错误码,更多错误码信息请参见状态码

请妥善保管用于计算CheckSumAppSecret,可在应用服务器存储和使用,但不应存储或传递到客户端,也不应在网页等前端代码中嵌入。

CheckSum计算示例

计算CheckSum的示例代码如下 (其他语言示例请参见IM 服务端 API 示例 Demo):

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' };
}
Node.js
const { SHA1 } = require("crypto-js");

function randString(x) {
  let s = "";
  while (s.length < x && x > 0) {
    const v = Math.random() < 0.5 ? 32 : 0;
    s += String.fromCharCode(
      Math.round(Math.random() * (122 - v - (97 - v)) + (97 - v))
    );
  }
  return s;
}

const [Nonce, CurTime] = [randString(20), new Date().getTime().toString().slice(0, 10)]

function CheckSum(AppSecret, Nonce, CurTime) {
  return SHA1(AppSecret + Nonce + CurTime);
}

请求体(Body)

传入 Body 的具体业务参数请参见各 API 文档。以注册云信 IM 账号为例,对应的业务参数配置说明请参见注册云信IM账号。同时请求头的Content-Type类型均为application/x-www-form-urlencoded;charset=utf-8

返回结果

调用 IM 服务端 API 的返回类型均为 JSON,同时进行 UTF-8 编码。

如调用成功,则返回状态码200。表示调用异常的具体状态码及相应的排查指引请参见状态码

状态码的含义均为开放式,不同接口返回的相同状态码,含义可能略有不同。因此不建议您针对状态码开发业务逻辑。如果对状态码存在依赖,会有风险。

此文档是否对你有帮助?
有帮助
我要吐槽
  • 请求概述
  • 请求头(Header)
  • Header参数
  • CheckSum计算示例
  • 请求体(Body)
  • 返回结果