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.

Architecture.png

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

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  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'
HttpClient in Java
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".

Was this page helpful?
Yes
No
  • Understanding Instant Messaging
  • Install NIM SDK
  • Work with Server APIs
  • Prerequisites
  • Step 1: Get the endpoint (URL)
  • Step 2: Generate CheckSum
  • Step 3: Configure common request parameters
  • Step 4: Configure business parameters
  • Step 5: Initiate a request from the app server
  • Send a request
  • Response
  • Status codes
  • FAQ
  • Why does the API call fail when boolean parameters are used?