服务端集成新手必看
更新时间： 2025/08/25 15:56:39
本文为新手介绍如何快速了解网易云信即时通讯 IM（Instant Messaging）服务、IM 服务端集成原理，服务端 API 使用流程、以及状态码的查询路径。
集成概述
服务端集成与客户端集成相辅相成，前者实现您的应用服务端与网易云信 IM 服务端的数据交互，后者实现您的应用客户端与网易云信 IM 服务端的数据交互。
应用服务端和网易云信 IM 服务端的数据交互按数据流通方向可分为下表所示的两种类型。
服务端集成类型 |
相关文档 |
|---|---|
| 应用服务端 请求 网易云信 IM 服务端 | API 调用方式 |
| 网易云信 IM 服务端 请求 应用服务端 |
大部分服务端 API 能够实现和 SDK 接口相同的效果，但部分能力仅可通过服务端 API 实现，如 注册 IM 账号 和 创建聊天室。
准备工作
根据本文操作前，请确保您已经完成了以下设置：
- 已在网易云信控制台 创建应用，获取 App Key。
- 已准备好调用和调试服务端 API 的开发环境，如 cURL 和 Postman。
使用流程
本文以 注册 IM 账号 （user/create.action）这个 API 为例，详细介绍应用服务端请求网易云信 IM 服务端的流程。IM 服务端请求应用服务端的相关说明，请参考 第三方回调、消息抄送 和 安全通。
第一步：确认请求地址（URL）
网易云信 IM 服务端根据不同的请求地址（URL），区分不同的请求。因此，您需先到服务端 《API 参考》的相应 API 文档的 请求说明 中，获取请求地址。
以下为 注册 IM 账号 （user/create.action）的请求地址：
https://api.yunxinapi.com/nimserver/user/create.action
该请求地址可分为如下几个部分：
https：指定请求的通信协议。api.yunxinapi.com/nimserver：指定网易云信 IM 服务端的 服务地址。user/create.action：指定调用的 API。
第二步：生成 CheckSum
为保证 API 的安全调用，网易云信 IM 服务端会对每个 API 的访问请求进行身份验证。您在调用 API 时，都需要在请求中包含 CheckSum 信息。
CheckSum 可通过将本文 准备工作 获取的 App Secret 结合 Nonce 和 CurTime 这两个参数拼接成字符串后再进行 SHA1 哈希计算来生成，详情请参考 CheckSum 计算示例。
第三步：配置公共请求参数
调用网易云信 IM 服务端 API 前，需先配置 API 的公共请求参数，即每个 API 都需要使用的请求参数，包括 App Key、Nonce、CurTime 和 CheckSum。公共请求参数需放在请求头（Request Header）中。
参数 |
说明 |
|---|---|
| App Key | 通过网易云信控制台获取，请参考 获取 App key |
| Nonce | 随机数（最大长度 128 个字符） |
| CurTime | 当前 UTC 时间戳，从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在 （指发起请求瞬间的前后 5 分钟内）的秒数（类型为 String） |
| CheckSum | 即 步骤 2：生成 CheckSum 中的 CheckSum |
第四步：配置业务参数
配置完公共请求参数后，您需再配置 API 相关的业务参数，明确目标操作。
业务参数的具体介绍，请参考 请求参数。
请求参数无论为何类型，调用 API 实际传入时，都需要转为 String 格式，否则将报错。
第五步：应用服务端发起请求
发起请求
完成以上配置后，您的应用服务端可以通过请求地址，向网易云信 IM 服务端发起请求。
cURL curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw080*****" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan&name=zhangsan' 'https://api.yunxinapi.com/nimserver/user/create.action'
Javaimport org.apache.http.HttpResponse;
import org.apache.http.NameValuePair;
import org.apache.http.client.entity.UrlEncodedFormEntity;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.message.BasicNameValuePair;
import org.apache.http.util.EntityUtils;
import java.util.ArrayList;
import java.util.Date;
import java.util.List;
public class Test {
public static void main(String[] args) throws Exception{
DefaultHttpClient httpClient = new DefaultHttpClient();
String url = "https://api.yunxinapi.com/nimserver/user/create.action";
HttpPost httpPost = new HttpPost(url);
String appKey = "94kid09c9ig9k1loimjg01******";
String appSecret = "1234567*****";
String nonce = "12345";
String curTime = String.valueOf((new Date()).getTime() / 1000L);
String checkSum = CheckSumBuilder.getCheckSum(appSecret, nonce ,curTime);//参考 计算 CheckSum 的 java 代码
// 设置请求的 header
httpPost.addHeader("AppKey", appKey);
httpPost.addHeader("Nonce", nonce);
httpPost.addHeader("CurTime", curTime);
httpPost.addHeader("CheckSum", checkSum);
httpPost.addHeader("Content-Type", "application/x-www-form-urlencoded;charset=utf-8");
// 设置请求的参数
List<NameValuePair> nvps = new ArrayList<NameValuePair>();
nvps.add(new BasicNameValuePair("accid", "helloworld"));
httpPost.setEntity(new UrlEncodedFormEntity(nvps, "utf-8"));
// 执行请求
HttpResponse response = httpClient.execute(httpPost);
// 打印执行结果
System.out.println(EntityUtils.toString(response.getEntity(), "utf-8"));
}
}
响应请求
网易云信 IM 服务端接收到您的请求信息后，返回响应信息。
返回示例如下：
JSON"Content-Type": "application/json; charset=utf-8"
{
"code":200,
"info":{"token":"*****","accid":"*****","name":"*****"}
}
状态码
调用 API 发起请求后，网易云信 IM 服务端会通过状态码告知您 API 调用结果，如上文返回示例中表示调用成功的 "code":200。
如调用不成功，您可根据状态码进行问题排查。具体请参考 状态码。
状态码的含义均为开放式，不同接口返回的相同状态码，含义可能略有不同。因此 不建议 您针对状态码开发业务逻辑。如果对状态码存在依赖，可能存在风险。
常见问题
为什么按照 Boolean 格式传入参数，最终调用 API 失败？
网易云信 IM 服务端 API 在调用时，请求参数无论为何类型，实际传入时都需转为 String 格式，否则将报错。
以账号全局禁言接口（nimserver/user/mute.action）为例，虽然请求参数 mute 为 Boolean 类型，但在调用接口时，请不要传入"mute":true，而 应该 传入"mute":"true"，否则将返回错误提示：mute not boolean。
