Getting started
Update time: 2024/03/07 09:06:31
This document outlines CommsEase Instant Messaging (IM), offering guidance on integration, making API calls, and understanding response status codes.
Understanding Instant Messaging
IM is a cloud-based platform developed with over two decades of technical expertise and industry experience. It provides a comprehensive suite of fundamental instant messaging capabilities. IM allows for seamless integration of instant messaging and real-time network functionalities into your applications. CommsEase offers a range of products and technical solutions, including Messaging components, SDKs for platforms, and platform APIs. You can incorporate instant messaging features into your applications, creating custom messaging scenarios to suit your unique needs.
IM SDK allows you to build basic features such as private messaging, chatting, message notification, and in-game communication. You can also use IM SDK to create large-scale social applications like Discord, WeChat, and Bullet SMS.
For more information about the IM service, see:
Install NIM SDK
Server-side services work together with NIM SDK. You app server can interact with the CommsEase server for data exchanges. NIM SDK integrated into your app can implement capabilities by interacting with Messaging server.
The data interaction between the app server and the Messaging server can be grouped into two types according to the data flow as shown in the following table.
Interaction |
Reference |
---|---|
App server sends requests to the Messaging server | API calling method |
Messaging server sends requests to App server |
Most server APIs can implement the same capabilities as SDK APIs. Some functions can only be implemented using server APIs, such as Sign up IM accounts and Create a chat room.
Work with Server APIs
Your app server can interact with CommsEase server by performing following steps. For information about how the Messaging server communicates with the app server,seeThird-party callbacks, Data sync和 Moderator.
To make a server API call, follow the steps below for registering a Messaging account(user/create.action
).
Prerequisites
- You have created a project for your app in the CommsEase console and activated required services with App Key and App Secret. For more information, see Create a project and Obtain App key .
- Get prepared with testing or debugging tools, such as cURL and Postman.
Step 1: Get the endpoint (URL)
CommsEase Messaging server provides different endpoint URLs for API calls. Go to the API reference and get the endpoint URL for the specified API.
The endpoint of Registering a CommsEase IM account(user/create.action
):
https://api.netease.im/nimserver/user/create.action
The request URL consists of the following parts:
-
https
: the communication protocol of the request. -
api.netease.im/nimserver
: base URL of CommsEase RESTful APIs -
user/create.action
: specified API.The domain name in the previous request URL (
api.netease.im
) belongs to the data center in China. If most of your app users are distributed out of Mainland China, set the domain name to the overseas data center (api-sg.netease.im
), and the endpoint URL ishttps://api-sg.netease.im/nimserver
. For more information, see Access Overseas Data Centers.
Step 2: Generate CheckSum
To ensure the security of API calls, the CommsEase Messaging server will authenticate each API request. When you call an API, your request must include CheckSum information.
CheckSum is calculated by concatenating App Secret obtained in Prerequisites, Nonce, and CurTime into a string and hashing the string by SHA1. For more information, see CheckSum Calculation example.
Step 3: Configure common request parameters
Before calling Messaging server APIs, you must configure the common request parameters of APIs, such as App Key, Nonce, CurTime, and CheckSum. Common request parameters are required in the request header.
Parameter |
Description |
---|---|
App Key | Obtained in the CommsEase console. For more information, see Obtain App key |
Nonce | A random number. The number must be 1 to 128 characters in length. |
CurTime | The number of seconds from January 1, 1970 at 00:00:00 to the present (Five minutes before or after sending a request). The data type is String. |
CheckSum | See Step 2: Generate CheckSum中的 CheckSum |
Step 4: Configure business parameters
After configuring the common request parameters, you must also configure the API-related business parameters to clarify the operation.
For more information about business parameters, see [Request Parameters](https://doc.commsease.com/en/messaging/docs/DQ3Nzk1MTY?platformId=60353#Request Parameters).
All request parameters, regardless of their original data type, must be converted to strings. Otherwise an error will be reported.
Step 5: Initiate a request from the app server
Send a request
After completing the previous configurations, your app server can initiate a request to the CommsEase Messaging server using the request URL.
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.netease.im/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.netease.im/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);//See the example code for calculating CheckSum in Java
// Set the request 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");
// Set the request parameters
List<NameValuePair> nvps = new ArrayList<NameValuePair>();
nvps.add(new BasicNameValuePair("accid", "hello, world"));
httpPost.setEntity(new UrlEncodedFormEntity(nvps, "utf-8"));
// Run the request.
HttpResponse response = httpClient.execute(httpPost);
// Print out the execution result.
System.out.println(EntityUtils.toString(response.getEntity(), "utf-8"));
}
}
Response
After receiving your request, CommsEase Messaging server will return a response.
Example response:
json"Content-Type": "application/json; charset=utf-8"
{
"code":200,
"info":{"token":"*","accid":"*","name":"*"}
}
Status codes
If you make an API call, CommsEase Messaging server returns a response with a status code, such as "code": 200
for a successful call.
If an API call fails, you can troubleshoot issues by checking status codes. For more information, see Status codes。
Status codes are generic. The same status codes returned by different interfaces may have slightly different meanings. Therefore, DO NOT develop business logic based on status codes. Relying solely on status codes for business development can introduce certain risks.
FAQ
Why does the API call fail when boolean parameters are used?
All request parameters, regardless of their original data type, must be converted to strings. Otherwise an error will be reported.
For example, for the all-mute API (nimserver/user/mute.action
), the request parameter mute
is of boolean type. You must use "mute":"true" instead of "mute":true for API calling, otherwise an error message will be returned: "mute not boolean".