CommsEase IM accounts

1. App: developer app client;
2. AppServer: developer app server;
3. CommsEase webserver: CommsEase background web service;
4. CommsEase imserver: SDK connected IM service.

Note:

1. CommsEase IM account: it is also called "user account" in the following document, and the parameter names are "accid" or "account".
2. Token: password of CommsEase IM account. The IM accid can be specified by the developer app service when created. If not specified, CommsEase will automatically generate an IM token and return it to the developer. For client login, you should transmit the accid and token to the CommsEase server for authentication. The token is permanently valid unless it is changed artificially. Only the latest token is valid. The error code 302 will be returned when a non-updated token is used during login.
3. When the client is connected to the CommsEase server through the CommsEase SDK, you should ensure that the CommsEase IM account has been registered and that the client has got a valid token from its own server;
   

Creating a CommsEase IM account

1. Third-party accounts are imported to CommsEase platform. You should maintain the accid and token on your own application server after successful registration.

2. Pay attention to IM accid, name length and IM token management.

3. If the accid in the CommsEase application involves letters, please use lowercase letters only, and make sure that lowercase letters are used on the servers and all the clients.

Request URL

httpPOST https://api-sg.netease.im/nimserver/user/create.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
accid	String	Yes	User CommsEase account, with a maximum length of 32 characters, must be unique within one APP (only use letters, numbers, half-width underscore (_), @, half-width dot (.), and half-width (-), not case sensitive, all lowercase regardless of original input, and please make sure the accid is consistent with that in the result returned by this interface).
name	String	No	User CommsEase account profile name, with a maximum length of 64 characters,
props	String	No	Json attribute, optional field for developers, with a maximum length of 1024 characters. This parameter is no longer recommended for use.
icon	String	No	CommsEase IM account profile picture URL, optional field for developers, with a maximum length of 1024 characters.
token	String	No	CommsEase IM account could specify the token value for IM login in CommsEase YunXin, with a maximum length of 128 characters, and update, if not specified, token is automatically generated, and returned upon successful creation.
sign	String	No	User signature, with a maximum length of 256 characters
email	String	No	User email, with a maximum length of 64 characters,
birth	String	No	User birthday, with a maximum length of 16 characters,
mobile	String	No	User's mobile, with a maximum length of 32 characters, country code (for example, United States: +1-xxxxxxxxxx) or area code (for example, Hong Kong: +852-xxxxxxxx) is required for any mobile number registered outside of Mainland China
gender	int	No	User gender, 0-unknown, 1-male, 2-female, other figures would result in parameter error
ex	String	No	User name card extension fields, with a maximum length of 1024 characters, can be extended by the user, recommended to encapsulate it into JSON

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan&name=zhangsan' 'https://api-sg.netease.im/nimserver/user/create.action'

HttpClient request example(java) (For calling HttpClient of the following interfaces, see here)

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-sg.netease.im/nimserver/user/create.action";
        HttpPost httpPost = new HttpPost(url);

        String appKey = "94kid09c9ig9k1loimjg012345123456";
        String appSecret = "123456789012";
        String nonce = "12345";
        String curTime = String.valueOf((new Date()).getTime() / 1000L);
        String checkSum = CheckSumBuilder.getCheckSum(appSecret, nonce ,curTime);//Reference Java code for calculating CheckSum

        // Set the requested 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 requested parameter
        List<NameValuePair> nvps = new ArrayList<NameValuePair>();
        nvps.add(new BasicNameValuePair("accid", "helloworld"));
        httpPost.setEntity(new UrlEncodedFormEntity(nvps, "utf-8"));

        // Execute request
        HttpResponse response = httpClient.execute(httpPost);

        // Print the execution result
        System.out.println(EntityUtils.toString(response.getEntity(), "utf-8"));
    }
}

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "info":{"token":"xx","accid":"xx","name":"xx"} 
}

Valid status codes

200、403、414、416、417、431、500

See Status codes .

---

Updating CommsEase IM token

Updates CommsEase IM token. By using this interface, the accid can be updated to the specified IM token. After update, please make sure that the developer finishes local maintenance tasks. After update, you should make sure that the token carried by the client SDK for another login is kept updated.

Request URL

httpPOST https://api-sg.netease.im/nimserver/user/update.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
accid	String	Yes	User CommsEase account, with a maximum length of 32 characters, must be unique Unique with the APP
props	String	No	This parameter is no longer recommended for use.
token	String	No	Can specify the login token value for CommsEase IM account, with a maximum length of 128 characters

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan&token=123456' 'https://api-sg.netease.im/nimserver/user/update.action'

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200 
}

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

---

Reset CommsEase IM token

The token of CommsEase IM account will be randomly reset by CommsEase webserver, and the new token will be returned. After update, please make sure that the developer finishes local maintenance tasks.
2. The biggest difference between this interface and CommsEase token update interface is that the token of the former is specified by the CommsEase server, while the token of the latter is specified by the developer himself.

Request URL

httpPOST https://api-sg.netease.im/nimserver/user/refreshToken.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
accid	String	Yes	User CommsEase account, with a maximum length of 32 characters, must be unique Unique with the APP

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan' 'https://api-sg.netease.im/nimserver/user/refreshToken.action'

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200, 
  "info":{"token":"xxx","accid":"xx" } 
}

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

---

Ban CommsEase IM account

1. After the CommsEase IM account is banned, you cannot log in to this ID again. If the ID is logged in at the time of being banned, the current login will not be affected and you can still send and receive messages. This ban will take effect for next login. Therefore, we recommend to set needkick to true so that this account can be forced to log out.
2. For security purpose, accounts can only be banned after creation and cannot be deleted; after banning, accounts are still counted in the total number of accounts in the application.

Request URL

httpPOST https://api-sg.netease.im/nimserver/user/block.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
accid	String	Yes	User CommsEase account, with a maximum length of 32 characters, must be unique Unique with the APP
needkick	String	No	Whether to kick banned users, true or false, default is false
kickNotifyExt	String	No	Extension field for kick-out, requiring SDK v7.7.0 or higher

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan' 'https://api-sg.netease.im/nimserver/user/block.action'

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200
}

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .

---

Unbanning a CommsEase IM account

Unbans a CommsEase IM account

Request URL

httpPOST https://api-sg.netease.im/nimserver/user/unblock.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

For information about headers in the request, see Overview.

Parameters

Parameter	Type	Required	Description
accid	String	Yes	User CommsEase account, with a maximum length of 32 characters, must be unique Unique with the APP

curl request example

curlcurl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'accid=zhangsan' 'https://api-sg.netease.im/nimserver/user/unblock.action'

Response

The data returned in the HTTP response is in JSON format.

json"Content-Type": "application/json; charset=utf-8"
{
  "code":200
}

Valid status codes

200, 403, 414, 416, 431, 500

See Status codes .