CommsEase IM account

Update time: 2022/11/25 08:19:39

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

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

ParameterTypeRequiredDescription
accidStringYesUser 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).
nameStringNoUser CommsEase account profile name, with a maximum length of 64 characters,
propsStringNoJson attribute, optional field for developers, with a maximum length of 1024 characters. This parameter is no longer recommended for use.
iconStringNoCommsEase IM account profile picture URL, optional field for developers, with a maximum length of 1024 characters.
tokenStringNoCommsEase 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.
signStringNoUser signature, with a maximum length of 256 characters
emailStringNoUser email, with a maximum length of 64 characters,
birthStringNoUser birthday, with a maximum length of 16 characters,
mobileStringNoUser'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
genderintNoUser gender, 0-unknown, 1-male, 2-female, other figures would result in parameter error
exStringNoUser 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

ParameterTypeRequiredDescription
accidStringYesUser CommsEase account, with a maximum length of 32 characters, must be unique
Unique with the APP
propsStringNoThis parameter is no longer recommended for use.
tokenStringNoCan 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

ParameterTypeRequiredDescription
accidStringYesUser 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

ParameterTypeRequiredDescription
accidStringYesUser CommsEase account, with a maximum length of 32 characters, must be unique
Unique with the APP
needkickStringNoWhether to kick banned users, true or false, default is false
kickNotifyExtStringNoExtension 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

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

Was this page helpful?
Yes
No
  • CommsEase IM accounts
  • Creating a CommsEase IM account
  • Request URL
  • Parameters
  • curl request example
  • Response
  • Valid status codes
  • Updating CommsEase IM token
  • Request URL
  • Parameters
  • curl request example
  • Response
  • Valid status codes
  • Reset CommsEase IM token
  • Request URL
  • Parameters
  • curl request example
  • Response
  • Valid status codes
  • Ban CommsEase IM account
  • Request URL
  • Parameters
  • curl request example
  • Response
  • Valid status codes
  • Unbanning a CommsEase IM account
  • Request URL
  • Parameters
  • curl request example
  • Response
  • Valid status codes