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:

• benefits
• Features
• APIs and limits

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.

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.

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 is https://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.

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).

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。

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