Web SDK Development Guide V2

Overview

JMessage Web SDK provides an IM system development framework for Web applications. It blocks the complex details of the IM system and provides a relatively simple API interface to facilitate third-party applications to quickly integrate IM functionality. SDK supports mainstream browsers such as IE10 and above, Edge, Chrome, Safari, Firefox and UC.

Release Notes

The JMessage Web SDK V2 repackages and optimizes the SDK communication protocol.

  • Provide more convenient API calls: Using Promise-style APIs simplifies the way the interface is called, allowing developers to integrate SDKs more easily and conveniently.
  • More reliable message retry solution: The new SDK optimizes the message retry solution. When a weak network condition occurs, the SDK will automatically retry 5 times and ensure that each API call is idempotent. Developers do not need to worry about repeated transmissions due to message retry.
  • Support instances of multiple chats on a single page: The new SDK modifies the instantiation mode so that developers do not need to initialize JMessage when the page is initialized. When the chat function is needed, it can be initialized again, and a page can initialize multiple channels to implement multi-account login.

Since the V2 API has completely transformed the API, in order to provide a better user experience, the V2 API is not backward compatible, and developers need to re-access the SDK according to the JMessage Web SDK documentation.

Authentication

Developers need to pass in auth_payload when performing initialization. The data structure is generated by the developer server and passed back to the browser for developers to authorize JMessage initialization that the browser runs. Developers need to ensure that all who could call and obtain this data are legitimate users.

The data structure of auth_payload is as follows:

  1. {
  2.     "appkey": "7e42e869baa2fbca8ccb823c",
  3.     "random_str": "022cd9fd995849b58b3ef0e943421ed9",
  4.     "signature": "E422A978DE37196588531CD0C42010B5",
  5.     "timestamp": "1467967210887"
  6. }

Parameter Description

  • appkey : An IM application appkey registered by the developer on Jiguang platform
  • 3random_str: a random string of 20-36 lengths, used as a signature plus salt
  • timestamp : current timestamp, used to prevent replay attacks. Accurate to millisecond.
  • signature : expire after 10 minutes (only for initialization operations, the operation after the initialization has nothing to do with the signature)

The generation algorithm of signature is as follows:

  1. signature = md5(appkey={appkey}&timestamp={timestamp}&random_str={random_str}&key={secret})

Secret is the IM application masterSecret registered by the developer on the Jiguang platform. Example of signature generation:

  1. signature = md5("appkey=25b693b31d2c2ad5f072ef0c&timestamp=1507791639926&random_str=022cd9fd995849b&key=bc2efab258f2019727a4f36l")
  • The signature of the production environment needs to be generated on the developer’s server, otherwise there is a risk of masterSecret exposure.

Quick Start

Visit the Jiguang official website to get the latest Web SDK. Then introduce the following in the page:

  1. <script src='./jmessage-sdk-web.<version>.min.js'></script>

With the introduction of this JS, you can use the global object JMessage on the Window and create a JMessage example:

  1. var JIM = new JMessage();

If you want to turn on Debug mode, you can pass in parameters when instantiating a JMessage:

  1. var JIM = new JMessage({debug:true});

API

The API uses the Promise style. All API requests without special notes are asynchronous and support the following four callbacks.

  • Request succeeded callback - onSuccess()
  • Request failed callback - onFail()
  • Request timeout callback - onTimeout()
  • Request reply callback - onAck()
  1. JIM.sendSingleMsg({
  2.     'target_username' : 'xiezefan',
  3.     'content' : 'Hi, JiGuang '
  4. }).onSuccess(function(data) {
  5.     // do something
  6. }).onFail(function(data) {
  7.     // do something
  8. }).onTimeout(function(data) {
  9.     if (data.response_timeout) {
  10.         // do something when response timeout
  11.     } else {
  12.         // do something when request timeout
  13.     }
  14. }).onAck(function(data) {
  15.     // do something
  16. });

Initialization

JMessage#init()

Roaming Parameter

Add roaming parameters Since 2.2.0. You can set whether to enable message logging roaming when initializing. After the message roaming is enabled, sdk automatically synchronizes the history of the current user when the user logs in between multiple devices.

Request Parameter

KEY REQUIRE DESCRIPTION
appkey TRUE IM applications appkey registered by developers on the Jiguang platforms
random_str TRUE Random string
timestamp TRUE Original timestamp
signature TRUE Signature
flag FALSE Whether to enable message logging roaming, default 0 as no, 1 as yes

Request Example

  1.   JIM.init({
  2.                "appkey" : "<appkey>",
  3.            "random_str" : "<random_str>",
  4.             "signature" : "<signature>",
  5.             "timestamp" : "<timestamp>",
  6.             "flag" : 0
  7.         }).onSuccess(function(data) {
  8.            //data.code 返回码
  9.            //data.message 描述
  10.           }).onFail(function(data) {
  11.             // 同上
  12.         });

Disconnection Monitoring

JMessage#onDisconnect(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Disconnected processing function

Request Example

  1.   JIM.onDisconnect(function(){
  2.   });

Multi-end Simultaneously Online

The SDK supports multi-end simultaneously online from 2.4.0. For details, see Multi-end Online Instructions.

Registration and Logon Related

Registration

Registration supports other fields Since 2.4.0

JMessage#register()

Request Parameter

KEY REQUIRE DESCRIPTION
username TRUE Username
password TRUE Password
is_md5 FALSE Whether the password is an MD5 password, and the default is No
nickname FALSE Nickname
birthday FALSE Birthday
signature FALSE Signature
gender FALSE Gender, 0-Unknown, 1-Male, 2-Female
region FALSE Area
address FALSE Address
extras FALSE Custom json format fields
media_id FALSE Avatar id

Request Example

  1.   JIM.register({
  2.         'username' : '<register name>',
  3.         'password' : '<register password>',
  4.           'is_md5' : '<is_md5>',
  5.           'extras' : {'key1':'val1','key2':'val2'},
  6.          'address' : '深圳'
  7.         }).onSuccess(function(data) {
  8.             //data.code 返回码
  9.             //data.message 描述
  10.           }).onFail(function(data) {
  11.             // 同上
  12.         });

Connection Status

JMessage#isConnect()

Request Parameter\

N/A

Request Example

  1. JIM.isConnect();// 无回调函数，调用则成功

Initialization State

JMessage#isInit()

Request Parameter

N/A

Request Example

  1. JIM.isInit();// 无回调函数，调用则成功

Login Status

JMessage#isLogin()

Request Parameter

N/A

Request Example

  1. JIM.isLogin();// 无回调函数，调用则成功

Log in

Support online_list Since 2.6.0

JMessage#login()

Request Parameter

KEY REQUIRE DESCRIPTION
username TRUE Username
password TRUE Password
is_md5 FALSE Whether the password is an MD5 password, and the default is No

Request Example

  1. JIM.login({
  2.     'username' : '<login username>',
  3.     'password' : '<login password>'
  4. }).onSuccess(function(data) {
  5.      //data.code 返回码
  6.      //data.message 描述
  7.      //data.online_list[] 在线设备列表
  8.      //data.online_list[].platform  Android,ios,pc,web
  9.      //data.online_list[].mtime 最近一次登录时间
  10.      //data.online_list[].isOnline 是否在线 true or false
  11.      //data.online_list[].isLogin 是否登录 true or false
  12.      //data.online_list[].flag 该设备是否被当前登录设备踢出 true or false
  13. }.onFail(function(data){
  14.   //同上
  15. });

Log out

JMessage#loginOut()

Request Parameter

N/A

Request Example

  1. JIM.loginOut();//无回调函数，调用则成功

User Management

Get User Information

Support extras fields Since 2.4.0

JMessage#getUserInfo()

Request Parameter:

KEY REQUIRE DESCRIPTION
username TRUE Username
appkey FALSE Appkey of target app is required when queried across applications.

Request Example

  1.   JIM.getUserInfo({
  2.             'username' : '<search username>',
  3.               'appkey' : '<search appkey>'
  4.         }).onSuccess(function(data) {
  5.             //data.code 返回码
  6.             //data.message 描述
  7.             //data.user_info.username
  8.             //data.user_info.appkey
  9.             //data.user_info.nickname
  10.             //data.user_info.avatar 头像
  11.             //data.user_info.birthday 生日，默认空
  12.             //data.user_info.gender 性别 0 - 未知， 1 - 男 ，2 - 女
  13.             //data.user_info.signature 用户签名
  14.             //data.user_info.region 用户所属地区
  15.             //data.user_info.address 用户地址
  16.             //data.user_info.mtime 用户信息最后修改时间
  17.             //data.extras 自定义json字段
  18.           }).onFail(function(data) {
  19.             //data.code 返回码
  20.             //data.message 描述
  21.         });

Update Personal Information

Support extras fields since 2.4.0

JMessage#updateSelfInfo()

Request Parameter

KEY REQUIRE DESCRIPTION
nickname FALSE Nickname
birthday FALSE Birthday
signature FALSE Signature
gender FALSE Gender, 0-Unknown, 1-Male, 2-Female
region FALSE Area
address FALSE Address
extras FALSE Custom json format fields

Request Example

  1.    JIM.updateSelfInfo({
  2.                  'nickname' : '<your_nickname>',
  3.                  'birthday' : '<your_address>',
  4.                 'signature' : '<your_address>',
  5.                    'gender' : '<your_address>',
  6.                    'region' : '<your_address>',
  7.                   'address' : '<your_address>'
  8.                    'extras' : {'key1':'val1','key2':'val2'}
  9.                }).onSuccess(function(data) {
  10.                    //data.code 返回码
  11.                    //data.message 描述
  12.                }).onFail(function(data) {
  13.                    //同上
  14.                });

Update Personal Avatar

JMessage#updateSelfAvatar()

Request Parameter

KEY REQUIRE DESCRIPTION
avatar TRUE DataForm object of avatar images

Request Example

  1.    JIM.updateSelfAvatar({
  2.                 'avatar' : '<formData with image>'
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    //同上
  8.                });

Update Personal Password

JMessage#updateSelfPwd()

Request Parameter

KEY REQUIRE DESCRIPTION
old_pwd TRUE Old password
new_pwd TRUE New password
is_md5 FALSE Whether the password passed MD5

Request Example

  1.    JIM.updateSelfPwd({
  2.                  'old_pwd' : '<oldPwd>',
  3.                  'new_pwd' : '<newPwd>',
  4.                   'is_md5' : '<idMd5>'
  5.                }).onSuccess(function(data) {
  6.                    //data.code 返回码
  7.                    //data.message 描述
  8.                }).onFail(function(data) {
  9.                   //同上
  10.                });

Message Management

Get a list of sessions

Support session extras fields Since 2.4.0

JMessage#getConversation()

Request Parameter

N/A

Request Example

  1.    JIM.getConversation().onSuccess(function(data) {
  2.                    //data.code 返回码
  3.                    //data.message 描述
  4.                    //data.conversations[] 会话列表，属性如下示例
  5.                    //data.conversations[0].extras 附加字段
  6.                    //data.conversations[0].unread_msg_count 消息未读数
  7.                    //data.conversations[0].name  会话名称
  8.                    //data.conversations[0].appkey  appkey(单聊)
  9.                    //data.conversations[0].username  用户名(单聊)
  10.                    //data.conversations[0].nickname  用户昵称(单聊)
  11.                    //data.conversations[0].avatar  头像 media_id 
  12.                    //data.conversations[0].mtime 会话最后的消息时间戳
  13.                    //data.conversations[0].gid 群 id(群聊)
  14.                    //data.conversations[0].type  会话类型(3 代表单聊会话类型，4 代表群聊会话类型)
  15.                }).onFail(function(data) {
  16.                    //data.code 返回码
  17.                    //data.message 描述
  18.                });

Update Session Information

Since 2.4.0

JMessage#updateConversation()

Request Parameter

KEY REQUIRE DESCRIPTION
gid FALSE Group id. Valid for group chat sessions.
username FALSE Username. Valid for single chat sessions.
appkey FALSE User appkey. Valid for single chat sessions.
extras TRUE Json object. Old data will be covered

Request Example

  1.    // 群会话,调用则成功，无回调函数
  2.    JIM.updateConversation({
  3.                             'gid' : 'gid',
  4.                             'extras' : {'key':'val','key2':'val2'}
  5.                            });
  7.    // 单聊会话, 调用则成功，无回调函数
  8.    JIM.updateConversation({
  9.                             'appkey' : 'appkey',
  10.                             'username' : 'username',
  11.                             'extras' : {'key':'val','key2':'val2'}
  12.                            });

Get Number of Unread Sessions

Since 2.4.0

JMessage#getUnreadMsgCnt()

Request Parameter

KEY REQUIRE DESCRIPTION
gid FALSE Group id. Valid for group chat sessions.
username FALSE Username. Valid for single chat sessions.
appkey FALSE User appkey. Valid for single chat sessions.

Request Example

  1.    // 单聊，未读数，调用则成功，无回调函数
  2.    var count = JIM.getUnreadMsgCnt({
  3.                             'username' : '<username>'
  4.                            });
  5.    // 群聊，未读数，调用则成功，无回调函数
  6.    var count = JIM.getUnreadMsgCnt({
  7.                             'gid' : '<gid>'
  8.                            });

Reset the Number of Unread Sessions

Since 2.4.0

JMessage#resetUnreadCount()

Request Parameter

KEY REQUIRE DESCRIPTION
gid FALSE Group id. Valid for group chat sessions.
username FALSE Username. Valid for single chat sessions.
appkey FALSE User appkey. Valid for single chat sessions.

Request Example

  1.    // 重置单聊会话，调用则成功，无回调函数
  2.    JIM.resetUnreadCount({
  3.                             'username' : '<username>'
  4.                            });
  5.    // 重置群聊会话，调用则成功，无回调函数
  6.    JIM.resetUnreadCount({
  7.                             'gid' : '<gid>'
  8.                            });

List of Message Unread User

Since 2.4.0

JMessage#msgUnreadList()

Request Parameter

KEY REQUIRE DESCRIPTION
msg_id TRUE Message id

Request Example

  1.    // 消息发送设置了需要回执的时候,可以查看消息的已读未读用户列表
  2.    // 消息接收方收到需要回执的消息的时候,阅读后需要通过消息已读回执接口通知后台消息已读
  3.    JIM.msgUnreadList({
  4.                         'msg_id' : '<msg_id>'
  5.                      }).onSuccess(function(data) {
  6.                         //data.code 返回码
  7.                         //data.message 描述
  8.                         // 未读用户列表
  9.                         //data.msg_unread_list.unread_list[].appkey
  10.                         //data.msg_unread_list.unread_list[].username
  11.                         //data.msg_unread_list.read_list[].nickname
  12.                         // 已读用户列表
  13.                         //data.msg_unread_list.read_list[].appkey
  14.                         //data.msg_unread_list.read_list[].username
  15.                         //data.msg_unread_list.read_list[].nickname
  16.                     }).onFail(function(data) {
  17.                         //data.code 返回码
  18.                         //data.message 描述
  19.                      });

Read Receipt of Single Chat Messages

Since 2.4.0

JMessage#addSingleReceiptReport()

Request Parameter

KEY REQUIRE DESCRIPTION
username TRUE Username
msg_ids TRUE Id list and array type of messages that have been read
appkey FALSE Default to appkey of this application

Request Example

  1.    // 接收方收到需要消息回执的消息，阅读后进行消息回执操作
  2.    JIM.addSingleReceiptReport({
  3.                       'username' : '<用户 name>',
  4.                       'msg_ids' : '<[msg_ids]>'
  5.                      }).onSuccess(function(data,msg_ids){
  6.                        // data.code 返回码
  7.                        // data.appkey 目标 appkey
  8.                        // data.username 目标 username
  9.                        // msg_ids 消息数组
  10.                      }).onFail(function(data.msg_ids){
  12.                      })

Read Receipt of Group Chat Messages

Since 2.4.0

JMessage#addGroupReceiptReport()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group ID
msg_ids TRUE Id list and array type of messages that have been read

Request Example

  1.    // 接收方收到需要消息回执的消息，阅读后进行消息回执操作
  2.    JIM.addGroupReceiptReport({
  3.                       'gid' : '<gid>',
  4.                       'msg_id' : '<[msg_ids]>'
  5.                      }).onSuccess(function(data,msg_ids){
  6.                        // data.code 返回码
  7.                        // gid 目标 群
  8.                        // msg_ids 消息数组
  9.                      }).onFail(function(data.msg_ids){
  11.                      });

Get Resource Access Path

JMessage#getResource ()

Request Parameter

KEY REQUIRE DESCRIPTION
media_id TRUE Media_id：resource id

Request Example

  1.    JIM.getResource({
  2.                  'media_id' : '<media_id >',
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                    //data.url 资源临时访问路径
  7.                }).onFail(function(data) {
  8.                    //data.code 返回码
  9.                    //data.message 描述
  10.                });

Retract Messages

JMessage#msgRetract ()

Request Parameter

KEY REQUIRE DESCRIPTION
msg_id TRUE Message id

Request Example

  1.    JIM.msgRetract({
  2.                  'msg_id' : '<msg_id >',
  3.                }).onSuccess(function(data , msg) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    //data.code 返回码
  8.                    //data.message 描述
  9.                });

Send Single Chat Texts

JMessage#sendSingleMsg()

Request Parameter

KEY REQUIRE DESCRIPTION
target_username TRUE Username of message receiver
content Either content or msg_body Message text
msg_body Either content or msg_body Message’s msg_body, used to implement message forwarding
target_nickname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
appkey FALSE Appkey of target app is required when queried across applications.
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
custom_notification FALSE See the table below for notification bar parameters.
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar

Request Example

  1.    // 发送消息
  2.    JIM.sendSingleMsg({
  3.                  'target_username' : '<targetName>',
  4.              'target_nickname' : '<targetNickname>',
  5.                  'content' : '<textContent>',
  6.                  'appkey' : '<targetAppkey>',
  7.                  'extras' : 'json object'
  8.                }).onSuccess(function(data , msg<可选>) {
  9.                   //data.code 返回码
  10.                   //data.message 描述
  11.                   //data.msg_id 发送成功后的消息 id
  12.                   //data.ctime_ms 消息生成时间,毫秒
  13.                   //data.appkey 用户所属 appkey
  14.                   //data.target_username 用户名
  15.                   //msg.content 发送成功消息体,见下面消息体详情
  16.                }).onFail(function(data) {
  17.                   //data.code 返回码
  18.                   //data.message 描述
  19.                });
  1.    // 转发消息
  2.    JIM.sendSingleMsg({
  3.                  'target_username' : '<targetName>',
  4.              'target_nickname' : '<targetNickname>',
  5.                  'msg_body' : {
  6.                               'text' : '',
  7.                             'extras' : 'json object'
  8.                               }, // 可以直接从已有消息体里面获取msg_body
  9.                  'appkey' : '<targetAppkey>',
  10.                }).onSuccess(function(data , msg<可选>) {
  11.                   //data.code 返回码
  12.                   //data.message 描述
  13.                   //data.msg_id 发送成功后的消息 id
  14.                   //data.ctime_ms 消息生成时间,毫秒
  15.                   //data.appkey 用户所属 appkey
  16.                   //data.target_username 用户名
  17.                   //msg.content 发送成功消息体,见下面消息体详情
  18.                }).onFail(function(data) {
  19.                   //data.code 返回码
  20.                   //data.message 描述
  21.                });

Message Body

Details of message body:

Send Single Chat Pictures

JMessage#sendSinglePic()

Request Parameter:

KEY REQUIRE DESCRIPTION
target_username TRUE Username of message receiver
image Either image or msg_body DataForm object of images
msg_body Either image or msg_body Message’s msg_body, used to implement message forwarding
target_nickname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
appkey FALSE Appkey of target app is required when queried across applications.
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
custom_notification FALSE See the table below for notification bar parameters.
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar

Request Example

  1.  // 发送消息
  2.  JIM.sendSinglePic({
  3.                  'target_username' : '<targetName>',
  4.              'target_nickname' : '<targetNickname>',
  5.                  'image' : '<formData with image>',
  6.                  'appkey' : '<targetAppkey>',
  7.                  'extras' : 'json object'
  8.                }).onSuccess(function(data , msg<可选>) {
  9.                   //data.code 返回码
  10.                   //data.message 描述
  11.                   //data.msg_id 发送成功后的消息id
  12.                   //data.ctime_ms 消息生成时间,毫秒
  13.                   //data.appkey 用户所属 appkey
  14.                   //data.target_username 用户名
  15.                   //msg.content 发送成功消息体
  16.                }).onFail(function(data) {
  17.                   //同发送单聊文本
  18.                });
  1.   // 转发消息
  2.   JIM.sendSinglePic({
  3.                  'target_username' : '<targetName>',
  4.              'target_nickname' : '<targetNickname>',
  5.                  'msg_body' : {
  6.                              'media_id':'',
  7.                           'media_crc32':'',
  8.                                 'width':'',
  9.                                'height':'',
  10.                                'format':'',
  11.                                 'fsize':'',
  12.                               'extras' : 'json object'
  13.                                 }, // 可以直接从已有消息体里面获取msg_body
  14.                  'appkey' : '<targetAppkey>',
  15.                }).onSuccess(function(data , msg<可选>) {
  16.                   //data.code 返回码
  17.                   //data.message 描述
  18.                   //data.msg_id 发送成功后的消息id
  19.                   //data.ctime_ms 消息生成时间,毫秒
  20.                   //data.appkey 用户所属 appkey
  21.                   //data.target_username 用户名
  22.                   //msg.content 发送成功消息体
  23.                }).onFail(function(data) {
  24.                   //同发送单聊文本
  25.                });

Send Single Chat Files

JMessage#sendSingleFile()

Request Parameter

KEY REQUIRE DESCRIPTION
target_username TRUE Username of message receiver
file Either file or msg_body DataForm object of images
msg_body Either file or msg_body Message’s msg_body, used to implement message forwarding
target_nickname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
appkey FALSE Appkey of target app is required when queried across applications.
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
custom_notification FALSE See the table below for notification bar parameters.
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar

Request Example

  1.   // 发送消息
  2.   JIM.sendSingleFile({
  3.                  'target_username' : '<targetName>',
  4.          'target_nickname' : '<targetNickname>',
  5.                  'file' : '<formData with file>',
  6.                  'appkey' : '<targetAppkey>',
  7.                  'extras' : 'json object'
  8.                }).onSuccess(function(data , msg) {
  9.                   //data.code 返回码
  10.                   //data.message 描述
  11.                   //data.msg_id 发送成功后的消息id
  12.                   //data.ctime_ms 消息生成时间,毫秒
  13.                   //data.appkey 用户所属 appkey
  14.                   //data.target_username 用户名
  15.                   //msg.content 发送成功消息体
  16.                }).onFail(function(data) {
  17.                    //同发送单聊文本
  18.                });
  1.   // 转发消息
  2.   JIM.sendSingleFile({
  3.                  'target_username' : '<targetName>',
  4.              'target_nickname' : '<targetNickname>',
  5.                  'msg_body' : {
  6.                              'media_id':'',
  7.                           'media_crc32':'',
  8.                                  'hash':'',
  9.                                 'fname':'',
  10.                                 'fsize':'',
  11.                               'extras' : 'json object'
  12.                                 }, // 可以直接从已有消息体里面获取msg_body
  13.                  'appkey' : '<targetAppkey>',
  14.                }).onSuccess(function(data , msg<可选>) {
  15.                   //data.code 返回码
  16.                   //data.message 描述
  17.                   //data.msg_id 发送成功后的消息id
  18.                   //data.ctime_ms 消息生成时间,毫秒
  19.                   //data.appkey 用户所属 appkey
  20.                   //data.target_username 用户名
  21.                   //msg.content 发送成功消息体
  22.                }).onFail(function(data) {
  23.                   //同发送单聊文本
  24.                });

Send Single Chat Locations

JMessage#sendSingleLocation()

Request Parameter

KEY REQUIRE DESCRIPTION
target_username TRUE Username of message receiver
latitude Either latitude or msg_body Latitude
longitude Either longitude or msg_body Longitude
scale Either scale or msg_body Map zoom level
label Either label or msg_body Address
msg_body Either position related parameter or msg_body Message’s msg_body, used to implement message forwarding
target_nickname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
appkey FALSE Appkey of target app is required when queried across applications.
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
custom_notification FALSE See the table below for notification bar parameters.
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar

Request Example

  1.   // 发送消息
  2.   JIM.sendSingleLocation({
  3.                  'target_username' : '<targetName>',
  4.          'target_nickname' : '<targetNickname>',
  5.          'latitude' : '<latitude>',
  6.                  'longitude' : '<longitude>',
  7.                  'scale' : '<scale>',
  8.                  'label' : '<address label>'
  9.                  'appkey' : '<targetAppkey>',
  10.                  'extras' : 'json object'
  11.                }).onSuccess(function(data , msg) {
  12.                   //data.code 返回码
  13.                   //data.message 描述
  14.                   //data.msg_id 发送成功后的消息id
  15.                   //data.ctime_ms 消息生成时间,毫秒
  16.                   //data.appkey 用户所属 appkey
  17.                   //data.target_username 用户名
  18.                   //msg.content 发送成功消息体
  19.                }).onFail(function(data) {
  20.                    //同发送单聊文本
  21.                });
  1.   // 转发消息
  2.   JIM.sendSingleLocation({
  3.                  'target_username' : '<targetName>',
  4.          'target_nickname' : '<targetNickname>',
  5.                 'msg_body' : {
  6.                                'latitude' : '<latitude>',
  7.                               'longitude' : '<longitude>',
  8.                                   'scale' : '<scale>',
  9.                                   'label' : '<address label>',
  10.                                  'extras' : 'json object'
  11.                               } // 可以直接从已有消息体里面获取msg_body
  12.                  'appkey' : '<targetAppkey>',
  13.                }).onSuccess(function(data , msg) {
  14.                   //data.code 返回码
  15.                   //data.message 描述
  16.                   //data.msg_id 发送成功后的消息id
  17.                   //data.ctime_ms 消息生成时间,毫秒
  18.                   //data.appkey 用户所属 appkey
  19.                   //data.target_username 用户名
  20.                   //msg.content 发送成功消息体
  21.                }).onFail(function(data) {
  22.                    //同发送单聊文本
  23.                });

Send Custom Message of Single Chats

JMessage#sendSingleCustom()

Request Parameter

KEY REQUIRE DESCRIPTION
target_username TRUE Username of message receiver
custom TRUE Custom json object message
msg_body Either custom or msg_body Message’s msg_body, used to implement message forwarding
target_nickname FALSE Recipient’s display name
appkey FALSE Appkey of target app is required when queried across applications.
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
custom_notification FALSE See the table below for notification bar parameters.
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar

Request Example

  1.    // 发送消息
  2.    JIM.sendSingleCustom({
  3.                  'target_username' : '<targetName>',
  4.          'target_nickname' : '<targetNickname>',
  5.                  'custome' : '<json object>'
  6.                  'appkey' : '<targetAppkey>'
  7.                }).onSuccess(function(data , msg) {
  8.                   //data.code 返回码
  9.                   //data.message 描述
  10.                   //data.msg_id 发送成功后的消息id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                   //data.appkey 用户所属 appkey
  13.                   //data.target_username 用户名
  14.                   //msg.content 发送成功消息体
  15.                }).onFail(function(data) {
  16.                   //同发送单聊文本
  17.                });
  1.   // 转发消息
  2.   JIM.sendSingleCustom({
  3.                  'target_username' : '<targetName>',
  4.          'target_nickname' : '<targetNickname>',
  5.                  'msg_body' : '<json object>', // 可以直接从已有消息体里面获取msg_body
  6.                  'appkey' : '<targetAppkey>'
  7.                }).onSuccess(function(data , msg) {
  8.                   //data.code 返回码
  9.                   //data.message 描述
  10.                   //data.msg_id 发送成功后的消息id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                   //data.appkey 用户所属 appkey
  13.                   //data.target_username 用户名
  14.                   //msg.content 发送成功消息体
  15.                }).onFail(function(data) {
  16.                   //同发送单聊文本
  17.                });

Send Group Chat Texts

JMessage#sendGroupMsg()

Request Parameter

KEY REQUIRE DESCRIPTION
target_gid TRUE Group id
content Either content or msg_body Message text
msg_body Either content or msg_body Message’s msg_body, used to implement message forwarding
target_gname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
at_list FALSE @user list: [{‘username’: ‘name1’, ‘appkey’: ‘ Required for cross-application, default is not filled in to indicate this application’}], @ALL direct empty array: []
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
custom_notification FALSE See the table below for notification bar parameters.
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar
at_prefix FALSE Notification content prefix of @ target

Request Example

  1.    // 发送消息
  2.    JIM.sendGroupMsg({
  3.                  'target_gid' : '<targetGid>',
  4.          'target_gname' : '<targetGName>',
  5.                  'content' : '<textContent>',
  6.                  'extras' : '<json object>',
  7.                  'at_list' : [] //at all
  8.                }).onSuccess(function(data , msg) {
  9.                   //data.code 返回码
  10.                   //data.message 描述
  11.                   //data.msg_id 发送成功后的消息id
  12.                   //data.ctime_ms 消息生成时间,毫秒
  13.                   //data.target_gid 群 id
  14.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  15.                   //msg.content 发送成功消息体
  16.                }).onFail(function(data) {
  17.                   //同发送单聊文本
  18.                });
  1.    // 转发消息
  2.    JIM.sendGroupMsg({
  3.                  'target_gid' : '<targetGid>',
  4.          'target_gname' : '<targetGName>',
  5.                  'msg_body' : {
  6.                               'text' : '',
  7.                             'extras' : ''
  8.                                }, // 可以直接从已有消息体里面获取msg_body
  9.                  'at_list' : [] //at all
  10.                }).onSuccess(function(data , msg) {
  11.                   //data.code 返回码
  12.                   //data.message 描述
  13.                   //data.msg_id 发送成功后的消息id
  14.                   //data.ctime_ms 消息生成时间,毫秒
  15.                   //data.target_gid 群 id
  16.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  17.                   //msg.content 发送成功消息体
  18.                }).onFail(function(data) {
  19.                   //同发送单聊文本
  20.                });

Send Group Chat Pictures

JMessage#sendGroupPic()

Request Parameter

KEY REQUIRE DESCRIPTION
target_gid TRUE Group id
image Either image or msg_body DataForm object of images
msg_body Either image or msg_body Message’s msg_body, used to implement message forwarding
target_gname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar
at_prefix FALSE Notification content prefix of @ target

Request Example

  1.    // 发送消息
  2.    JIM.sendGroupPic({
  3.                  'target_gid' : '<targetGid>',
  4.          'target_gname' : '<targetGName>',
  5.                  'image' : '<formData with image>',
  6.                  'extras' : 'json object'
  7.                }).onSuccess(function(data , msg) {
  8.                   //data.code 返回码
  9.                   //data.message 描述
  10.                   //data.msg_id 发送成功后的消息id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                   //data.target_gid 群 id
  13.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  14.                   //msg.content 发送成功消息体
  15.                }).onFail(function(data) {
  16.                   //同发送单聊文本
  17.                });
  1.   // 转发消息
  2.   JIM.sendGroupPic({
  3.                  'target_gid' : '<targetGid>',
  4.            'target_gname' : '<targetGName>',
  5.                   'msg_body' : {
  6.                              'media_id':'',
  7.                           'media_crc32':'',
  8.                                 'width':'',
  9.                                'height':'',
  10.                                'format':'',
  11.                                 'fsize':'',
  12.                               'extras' : 'json object'
  13.                                 }, // 可以直接从已有消息体里面获取msg_body
  14.                }).onSuccess(function(data , msg) {
  15.                   //data.code 返回码
  16.                   //data.message 描述
  17.                   //data.msg_id 发送成功后的消息id
  18.                   //data.ctime_ms 消息生成时间,毫秒
  19.                   //data.target_gid 群 id
  20.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  21.                   //msg.content 发送成功消息体
  22.                }).onFail(function(data) {
  23.                   //同发送单聊文本
  24.                });

Send Group Chat Files

JMessage#sendGroupFile()

Request Parameter

KEY REQUIRE DESCRIPTION
target_gid TRUE Group id
file Either file or msg_body The DataForm object of the file
msg_body Either file or msg_body Message’s msg_body, used to implement message forwarding
target_gname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar
at_prefix FALSE Notification content prefix of @ target

Request Example

  1.    // 发送消息
  2.    JIM.sendGroupFile({
  3.                  'target_gid' : '<targetGid>',
  4.          'target_gname' : '<targetGName>',
  5.                  'file' : '<formData with file>',
  6.                  'extras' : 'json object'
  7.                }).onSuccess(function(data , msg) {
  8.                   //data.code 返回码
  9.                   //data.message 描述
  10.                   //data.msg_id 发送成功后的消息id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                   //data.target_gid 群 id
  13.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  14.                   //msg.content 发送成功消息体
  15.                }).onFail(function(data) {
  16.                    //同发送单聊文本
  17.                });
  1.    // 转发消息
  2.    JIM.sendGroupFile({
  3.                  'target_gid' : '<targetGid>',
  4.          'target_gname' : '<targetGName>',
  5.                  'msg_body' : {
  6.                              'media_id':'',
  7.                           'media_crc32':'',
  8.                                  'hash':'',
  9.                                 'fname':'',
  10.                                 'fsize':'',
  11.                                 'extras' : 'json object'
  12.                                 } // 可以直接从已有消息体里面获取msg_body
  13.                }).onSuccess(function(data , msg) {
  14.                   //data.code 返回码
  15.                   //data.message 描述
  16.                   //data.msg_id 发送成功后的消息id
  17.                   //data.ctime_ms 消息生成时间,毫秒
  18.                   //data.target_gid 群 id
  19.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  20.                   //msg.content 发送成功消息体
  21.                }).onFail(function(data) {
  22.                    //同发送单聊文本
  23.                });

Send Group Chat Locations

JMessage#sendGroupLocation()

Request Parameter

KEY REQUIRE DESCRIPTION
target_gid TRUE Group id
latitude Either latitude or msg_body Latitude
longitude Either longitude or msg_body Longitude
scale Either scale or msg_body Map zoom level
label Either label or msg_body Address
msg_body Either msg_body or position related parameter Message’s msg_body, used to implement message forwarding
target_gname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable custom message notification bar. Default to FALSE.
title FALSE Heading of notification bar
alert FALSE Content of notification bar
at_prefix FALSE Notification content prefix of @ target

Request Example

  1.    // 发送消息
  2.    JIM.sendGroupLocation({
  3.                  'target_gid' : '<targetGid>',
  4.          'target_gname' : '<targetGName>',
  5.          'latitude' : '<latitude>',
  6.                  'longitude' : '<longitude>',
  7.                  'scale' : '<scale>',
  8.                  'label' : '<address label>',
  9.                  'extras' : 'json object'
  10.                }).onSuccess(function(data , msg) {
  11.                   //data.code 返回码
  12.                   //data.message 描述
  13.                   //data.msg_id 发送成功后的消息id
  14.                   //data.ctime_ms 消息生成时间,毫秒
  15.                   //data.target_gid 群 id
  16.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  17.                   //msg.content 发送成功消息体
  18.                }).onFail(function(data) {
  19.                    //同发送单聊文本
  20.                });
  1.    // 转发消息
  2.    JIM.sendGroupLocation({
  3.                  'target_gid' : '<targetGid>',
  4.                'target_gname' : '<targetGName>',
  5.            'msg_body' : {
  6.                               'latitude' : '<latitude>',
  7.                              'longitude' : '<longitude>',
  8.                                  'scale' : '<scale>',
  9.                                  'label' : '<address label>',
  10.                                  'extras' : 'json object'
  11.                               } // 可以直接从已有消息体里面获取msg_body
  12.                }).onSuccess(function(data , msg) {
  13.                   //data.code 返回码
  14.                   //data.message 描述
  15.                   //data.msg_id 发送成功后的消息id
  16.                   //data.ctime_ms 消息生成时间,毫秒
  17.                   //data.target_gid 群 id
  18.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  19.                   //msg.content 发送成功消息体
  20.                }).onFail(function(data) {
  21.                    //同发送单聊文本
  22.                });

Send Group Custom Messages

JMessage#sendGroupCustom()

Request Parameter

KEY REQUIRE DESCRIPTION
target_gid TRUE Group id
custom TRUE Custom json object message
msg_body Either custom or msg_body Message’s msg_body, used to implement message forwarding
target_gname FALSE Recipient’s display name
no_offline FALSE Control flag of offline messages, false as default value, means to save offline messages; true means not to save offline message
no_notification FALSE Message flag displayed on status bar, false as default value, means that status bar displays messages; true, means that status bar does not display messages
need_receipt FALSE Whether to need a read receipt. Need as true, not need as false

custom_notification：

KEY REQUIRE DESCRIPTION
enabled TRUE Whether to enable notification bar of custom message. Default to FALSE
title FALSE Heading of notification bar
alert FALSE Content of notification bar
at_prefix FALSE Notification content prefix of @ target

Request Example

  1.    // 发送消息
  2.    JIM.sendGroupCustom({
  3.                   'target_gid' : '<targetGid>',
  4.         'target_gname' : '<targetGName>',
  5.               'custom' : '<json object>'
  6.                }).onSuccess(function(data , msg) {
  7.                   //data.code 返回码
  8.                   //data.message 描述
  9.                   //data.msg_id 发送成功后的消息id
  10.                   //data.ctime_ms 消息生成时间,毫秒
  11.                   //data.target_gid 群 id
  12.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  13.                   //msg.content 发送成功消息体
  14.                }).onFail(function(data) {
  15.                    //同发送单聊文本
  16.                });
  1.    // 转发消息
  2.    JIM.sendGroupCustom({
  3.                   'target_gid' : '<targetGid>',
  4.         'target_gname' : '<targetGName>',
  5.             'msg_body' : '<json object>'// 可以直接从已有消息体里面获取msg_body
  6.                }).onSuccess(function(data , msg) {
  7.                   //data.code 返回码
  8.                   //data.message 描述
  9.                   //data.msg_id 发送成功后的消息id
  10.                   //data.ctime_ms 消息生成时间,毫秒
  11.                   //data.target_gid 群 id
  12.                   //data.unread_count 消息需要已读回执的时候,默认未读数
  13.                   //msg.content 发送成功消息体
  14.                }).onFail(function(data) {
  15.                    //同发送单聊文本
  16.                });

Transparent Transmission of Single Chat Messages

Since 2.4.0

JMessage#transSingleMsg()

Request Parameter

KEY REQUIRE DESCRIPTION
target_username TRUE Target user
cmd TRUE String type of transparent information
target_appkey FALSE Appkey of target user

Request Example

  1.    JIM.transSingleMsg({
  2.                  'target_username' : '<username>',
  3.                              'cmd' : '<cmd>'
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                     //data.code 返回码
  9.                     //data.message 描述
  10.                });

Transparent Transmission of Group Chat Messages

Since 2.4.0

JMessage#transGroupMsg()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Target group id
cmd TRUE String type of transparent transmission information

Request Example

  1.    JIM.transGroupMsg({
  2.                  'gid' : '<gid>',
  3.                  'cmd' : '<cmd>'
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                     //data.code 返回码
  9.                     //data.message 描述
  10.                });

Transparent Transmission of Multi-end Online Messages

Since 2.6.0

JMessage#transPlatMsg()

Request Parameter

KEY REQUIRE DESCRIPTION
platform TRUE Target platform of multi-end online: [all,android,ios,pc]
cmd TRUE String type of transparent transmission information

Request Example

  1.    JIM.transPlatMsg({
  2.                  'platform' : 'android',
  3.                  'cmd' : '<cmd>'
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                     //data.code 返回码
  9.                     //data.message 描述
  10.                });

Group Management

Create a Group

Support group avatar since 2.4.0 Support public groups since 2.5.0

JMessage#createGroup()

Request Parameter

KEY REQUIRE DESCRIPTION
group_name TRUE Group name
group_description FALSE Group description
avatar FALSE DataForm object of group portrait image
is_limit FALSE Whether it is a public group. The default is false

Request Example

  1.    JIM.createGroup({
  2.                  'group_name' : '<groupName>',
  3.           'group_description' : '<groupDescription>'
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                   //data.gid 群组id
  8.                   //data.group_name 群名
  9.                   //data.group_descriptin 群描述
  10.                }).onFail(function(data) {
  11.                     //data.code 返回码
  12.                     //data.message 描述
  13.                });

Leave the Group

JMessage#exitGroup()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1.    JIM.exitGroup({
  2.                   'gid' : '<exit gid>'
  3.                }).onSuccess(function(data) {
  4.                     //data.code 返回码
  5.                     //data.message 描述
  6.                     //data.gid 群组id
  7.                     //data.group_name 群名
  8.                }).onFail(function(data) {
  9.                     //data.code 返回码
  10.                     //data.message 描述
  11.                });

Add Group Members

JMessage#addGroupMembers()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
member_usernames TRUE Add user name list, example: [{‘username’:’name1’, ‘appkey’: ‘Required for cross-application, default is not filled in to indicate this application ‘},…]

Request Example

  1.    JIM.addGroupMembers({
  2.                   'gid' : '<gid>',
  3.           'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                   //同上
  9.                });

Delete Group Members

JMessage#delGroupMembers()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
member_usernames TRUE Add user name list, example: [{‘username’:’name1’, ‘appkey’: ‘Required for cross-application, default is not filled in to indicate this application ‘},…]

Request Example

  1.    JIM.delGroupMembers({
  2.                   'gid' : '<gid>',
  3.           'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                   // 同上
  9.                });

Get a List of Groups

JMessage#getGroups()

Support flag Since 2.5.0

Request Parameter

N/A

Request Example

  1.    JIM.getGroups().onSuccess(function(data) {
  2.                   //data.code 返回码
  3.                   //data.message 描述
  4.                   //data.group_list[] 群组列表，如下示例
  5.                   //data.group_list[0].gid 群id
  6.                   //data.group_list[0].name 群名
  7.                   //data.group_list[0].desc 群描述
  8.                   //data.group_list[0].appkey 群所属appkey
  9.                   //data.group_list[0].ctime 群创建时间
  10.                   //data.group_list[0].mtime 最近一次群信息修改时间
  11.                   //data.group_list[0].avatar 群头像
  12.                   //data.group_list[0].group_type 公开群:2,私有群:0或者1
  13.                }).onFail(function(data) {
  14.                   //data.code 返回码
  15.                   //data.message 描述
  16.                });

Get Group Information

JMessage#getGroupInfo()

Support public groups since 2.5.0

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1.    JIM.getGroupInfo({
  2.                   'gid' : '<gid>'
  3.                }).onSuccess(function(data) {
  4.                   //data.code 返回码
  5.                   //data.message 描述
  6.                   //data.group_info.gid 群id
  7.                   //data.group_info.name 群名
  8.                   //data.group_info.desc 群描述
  9.                   //data.group_info.appkey 群所属appkey
  10.                   //data.group_info.ctime 群创建时间
  11.                   //data.group_info.mtime 最近一次群信息修改时间
  12.                   //data.group_list[0].avatar 群头像
  13.                   //data.group_list[0].group_type 公开群:2,私有群:0或者1
  14.                }).onFail(function(data) {
  15.                    //data.code 返回码
  16.                    //data.message 描述
  17.                });

Update Group Information

Support group avatar since 2.4.0

JMessage#updateGroupInfo()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
group_name FALSE Group name. Required at least one attribute, and cannot be empty.
group_description FALSE Group description. Required at least one attribute, and cannot be empty.
avatar FALSE The DataForm object of the group avatar image. Required at least one attribute, and cannot be empty.

Request Example

  1.    JIM.updateGroupInfo({
  2.                   'gid' : '<gid>',
  3.                   'group_name' : '<new group name>',
  4.                   'group_description' : '<new group description>' 
  5.                }).onSuccess(function(data) {
  6.                    //data.code 返回码
  7.                    //data.message 描述
  8.                }).onFail(function(data) {
  9.                    // 同上
  10.                });

Get Group Members

JMessage#getGroupMembers()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1. JIM.getGroupMembers({
  2.                   'gid' : '<gid>'
  3.                }).onSuccess(function(data) {
  4.                   //data.code 返回码
  5.                   //data.message 描述
  6.                   //data.member_list[] 成员列表，如下示例
  7.                   //data.member_list[0].username 用户名
  8.                   //data.member_list[0].appkey 用户所属 appkey
  9.                   //data.member_list[0].nickname 用户昵称
  10.                   //data.member_list[0].avatar 用户头像 id
  11.                   //data.member_list[0].flag  0：普通成员 1：群主 2：管理员
  12.                   //data.member_list[0].keep_silence 是否被禁言true|false
  13.                }).onFail(function(data) {
  14.                    //data.code 返回码
  15.                    //data.message 描述
  16.                });

Join Group Actively(Public Groups)

Since 2.5.0

JMessage#joinGroup()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
reason FALSE Reason for application

Request Example

  1. JIM.joinGroup({
  2.                   'gid' : '<gid>',
  3.                   'reason' : '<reason>'
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                    //data.code 返回码
  9.                    //data.message 描述
  10.                });

Group Owner Approves Request for Admission

Since 2.5.0

JMessage#addGroupMemberResp()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
event_id TRUE The id of group admission event
from_username TRUE Username of the inviter
target_username TRUE Username of the invitee
result TRUE Approval result, 0: Agree 1: Decline
reason FALSE Reason for rejection
from_appkey FALSE Inviter’s appkey, defaults to appkey of this application
target_appkey FALSE Invitee’s appkey, defaults to appkey of this application

Request Example

  1. JIM.addGroupMemberResp({
  2.                   'gid' : '<gid>',
  3.                   'event_id' : '<event_id>'
  4.                   'target_appkey' : '<target_appkey>',
  5.                   'target_username' : '<target_username>',
  6.                   'result' : 2,
  7.                   'from_appkey' : '<from_appkey>',
  8.                   'from_username' : '<from_username>'
  9.                   'resaon' : '<reason>'
  10.                }).onSuccess(function(data) {
  11.                   //data.code 返回码
  12.                   //data.message 描述
  13.                }).onFail(function(data) {
  14.                    //data.code 返回码
  15.                    //data.message 描述
  16.                });

Add Banned Group Users

Since 2.5.0

JMessage#addGroupMemSilence()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
target_username TRUE Target username
target_appkey FALSE Target appkey

Request Example

  1. JIM.addGroupMemSilence({
  2.                   'gid' : '<gid>',
  3.                   'target_appkey' : '<target_appkey>',
  4.                   'target_username' : '<target_username>'
  5.                }).onSuccess(function(data) {
  6.                   //data.code 返回码
  7.                   //data.message 描述
  8.                }).onFail(function(data) {
  9.                    //data.code 返回码
  10.                    //data.message 描述
  11.                });

Dismiss Banned Group Users

Since 2.5.0

JMessage#delGroupMemSilence()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
target_username TRUE Target username
target_appkey FALSE Target appkey

Request Example

  1. JIM.delGroupMemSilence({
  2.                   'gid' : '<gid>',
  3.                   'target_appkey' : '<target_appkey>',
  4.                   'target_username' : '<target_username>'
  5.                }).onSuccess(function(data) {
  6.                   //data.code 返回码
  7.                   //data.message 描述
  8.                }).onFail(function(data) {
  9.                    //data.code 返回码
  10.                    //data.message 描述
  11.                });

Add Administrators

Since 2.6.0

JMessage#addGroupKeeper()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
member_usernames TRUE Add admin list, example: [{‘username’:’name1’, ‘appkey’: ‘ Required for cross-application, default is not filled in to indicate this application ‘},…]

Request Example

  1. JIM.addGroupKeeper({
  2.                   'gid' : '<gid>',
  3.                    'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                    //data.code 返回码
  9.                    //data.message 描述
  10.                });

Remove Administrators

Since 2.6.0

JMessage#delGroupKeeper()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
member_usernames TRUE Add admin list, example: [{‘username’:’name1’, ‘appkey’: ‘ Required for cross-application, default is not filled in to indicate this application ‘},…]

Request Example

  1. JIM.delGroupKeeper({
  2.                   'gid' : '<gid>',
  3.                    'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                    //data.code 返回码
  9.                    //data.message 描述
  10.                });

Transfer Owner Privileges

Since 2.6.0

JMessage#changeGroupAdmin()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id
target_username TRUE Target username
target_appkey FALSE Cross-application appkey, defaults to the appkey of this application

Request Example

  1. JIM.changeGroupAdmin({
  2.                   'gid' : '<gid>',
  3.                    'target_username' : '<username>'
  4.                }).onSuccess(function(data) {
  5.                   //data.code 返回码
  6.                   //data.message 描述
  7.                }).onFail(function(data) {
  8.                    //data.code 返回码
  9.                    //data.message 描述
  10.                });

Dissolve Groups

Since 2.6.0

JMessage#dissolveGroup()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1. JIM.dissolveGroup({
  2.                   'gid' : '<gid>'
  3.                }).onSuccess(function(data) {
  4.                   //data.code 返回码
  5.                   //data.message 描述
  6.                }).onFail(function(data) {
  7.                    //data.code 返回码
  8.                    //data.message 描述
  9.                });

Get Public Groups

Since 2.6.0

JMessage#getAppkeyPublicGroups()

Request Parameter

KEY REQUIRE DESCRIPTION
start TRUE Pagination subscript. Home page gets 0
appkey FALSE The appkey of chat room, defaults to this application

Request Example

  1. JIM.getAppkeyPublicGroups({
  2.                    'start' : 0
  3.                }).onSuccess(function(data) {
  4.                   //data.code 返回码
  5.                   //data.message 描述
  6.                   //data.result.total 群总数量
  7.                   //data.result.start 本次查询 index 下标值
  8.                   //data.result.groups[] 群列表
  9.                   //data.result.groups[0].gid 群id
  10.                   //data.result.groups[0].name 群名
  11.                   //data.result.groups[0].desc 群描述
  12.                   //data.result.groups[0].appkey 群所属appkey
  13.                   //data.result.groups[0].ctime 群创建时间
  14.                   //data.result.groups[0].mtime 最近一次群信息修改时间
  15.                   //data.result.groups[0].avatar 群头像
  16.                   //data.result.groups[0].group_type 公开群:2,私有群:0或者1
  17.                }).onFail(function(data) {
  18.                    //data.code 返回码
  19.                    //data.message 描述
  20.                });

Chat room

Add chatroom related features since 2.5.0

Get Chatroom Pagination List under the appkey

JMessage#getAppkeyChatrooms()

Request Parameter

KEY REQUIRE DESCRIPTION
start TRUE Pagination subscript. Home page gets 0
appkey FALSE The appkey of chat room, defaults to this application

Request Example

  1.    JIM.getAppkeyChatrooms({
  2.                    'start' : 0
  3.                  }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                    //data.result.total 聊天室总数量
  7.                    //data.result.start 本次查询 index 下标值
  8.                    //data.result.count 本次查询返回列表大小
  9.                    //data.result.rooms[].id 聊天室 id
  10.                    //data.result.rooms[].name 聊天室名字
  11.                    //data.result.rooms[].description 聊天室描述
  12.                    //data.result.rooms[].appkey 聊天室所属 appkey
  13.                    //data.result.rooms[].total_member_count 当前聊天室人数
  14.                    //data.result.rooms[].max_member_count 聊天室最大容量
  15.                }).onFail(function(data) {
  16.                    //data.code 返回码
  17.                    //data.message 描述
  18.                });

Get Joined Chat Rooms

JMessage#getSelfChatrooms()

Request Parameter

N/A

Request Example

  1.    JIM.getSelfChatrooms().onSuccess(function(data) {
  2.                    //data.code 返回码
  3.                    //data.message 描述
  4.                    //data.chat_rooms[].id 聊天室 id
  5.                    //data.chat_rooms[].name 聊天室名字
  6.                    //data.chat_rooms[].description 聊天室描述
  7.                    //data.chat_rooms[].appkey 聊天室所属 appkey
  8.                    //data.chat_rooms[].total_member_count 当前聊天室人数
  9.                    //data.chat_rooms[].max_member_count 聊天室最大容量
  10.                }).onFail(function(data) {
  11.                    //data.code 返回码
  12.                    //data.message 描述
  13.                });

Get Chat Room Details

JMessage#getChatroomInfo()

Request Parameter

KEY REQUIRE DESCRIPTION
id TRUE Chat room id

Request Example

  1.    JIM.getChatroomInfo({
  2.                    'id' : '<id>'
  3.                  }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                    //data.info.id 聊天室 id
  7.                    //data.info.name 聊天室名字
  8.                    //data.info.description 聊天室描述
  9.                    //data.info.appkey 聊天室所属 appkey
  10.                    //data.info.total_member_count 当前聊天室人数
  11.                    //data.info.max_member_count 聊天室最大容量
  12.                }).onFail(function(data) {
  13.                    //data.code 返回码
  14.                    //data.message 描述
  15.                });

Enter the Chat Room

JMessage#enterChatroom ()

Request Parameter

KEY REQUIRE DESCRIPTION
id TRUE Chat room id

Request Example

  1.    JIM.enterChatroom({
  2.                    'id' : '<id>'
  3.                  }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                    //data.id 聊天室 id
  7.                }).onFail(function(data) {
  8.                    //data.code 返回码
  9.                    //data.message 描述
  10.                });

Leave the Chat Room

JMessage#exitChatroom ()

Request Parameter

KEY REQUIRE DESCRIPTION
id TRUE Chat room id

Request Example

  1.    JIM.exitChatroom({
  2.                    'id' : '<id>'
  3.                  }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                    //data.id 聊天室 id
  7.                }).onFail(function(data) {
  8.                    //data.code 返回码
  9.                    //data.message 描述
  10.                });

Chat Room Sends Text Messages

JMessage#sendChatroomMsg()

Request Parameter

KEY REQUIRE DESCRIPTION
target_rid TRUE Target id
content Either content or msg_body Message text
msg_body Either content or msg_body Message’s msg_body, used to implement message forwarding
target_rname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type

Request Example

  1.    // 发送文本消息
  2.    JIM.sendChatroomMsg({
  3.                  'target_rid' : '<targetRid>',
  4.                  'content' : '<textContent>',
  5.                  'extras' : 'json object'
  6.                }).onSuccess(function(data , msg<可选>) {
  7.                   //data.code 返回码
  8.                   //data.message 描述
  9.                   //data.room_id 目标聊天室 id
  10.                   //data.msg_id 发送成功后的消息 id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                }).onFail(function(data) {
  13.                   //data.code 返回码
  14.                   //data.message 描述
  15.                });
  1.    // 转发文本消息
  2.    JIM.sendChatroomMsg({
  3.                  'target_rid' : '<targetRid>',
  4.                  'msg_body' : {
  5.                               'text' : '',
  6.                             'extras' : 'json object'
  7.                               }, // 可以直接从已有消息体里面获取msg_body
  8.                }).onSuccess(function(data , msg<可选>) {
  9.                   //data.code 返回码
  10.                   //data.message 描述
  11.                   //data.room_id 目标聊天室 id
  12.                   //data.msg_id 发送成功后的消息 id
  13.                   //data.ctime_ms 消息生成时间,毫秒
  14.                }).onFail(function(data) {
  15.                   //data.code 返回码
  16.                   //data.message 描述
  17.                });

Message Body

Details of message body

Chat Room Sends Picture Messages

JMessage#sendChatroomPic()

Request Parameter

KEY REQUIRE DESCRIPTION
target_rid TRUE Target id
image Either image or msg_body DataForm object of images
msg_body Either image or msg_body Message’s msg_body, used to implement message forwarding
target_rname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type

Request Example

  1.  // 发送消息
  2.  JIM.sendChatroomPic({
  3.             'target_rid' : '<targetRid>',
  4.                  'image' : '<formData with image>',
  5.                  'extras' : 'json object'
  6.                }).onSuccess(function(data , msg<可选>) {
  7.                   //data.code 返回码
  8.                   //data.message 描述
  9.                   //data.room_id 目标聊天室 id
  10.                   //data.msg_id 发送成功后的消息 id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                }).onFail(function(data) {
  13.                   //同发送单聊文本
  14.                });
  1.   // 转发消息
  2.   JIM.sendChatroomPic({
  3.                'target_rid' : '<targetRid>',
  4.                  'msg_body' : {
  5.                              'media_id':'',
  6.                           'media_crc32':'',
  7.                                 'width':'',
  8.                                'height':'',
  9.                                'format':'',
  10.                                 'fsize':'',
  11.                               'extras' : 'json object'
  12.                                 } // 可以直接从已有消息体里面获取msg_body
  13.                }).onSuccess(function(data , msg<可选>) {
  14.                   //data.code 返回码
  15.                   //data.message 描述
  16.                   //data.room_id 目标聊天室 id
  17.                   //data.msg_id 发送成功后的消息 id
  18.                   //data.ctime_ms 消息生成时间,毫秒
  19.                }).onFail(function(data) {
  20.                   //同发送单聊文本
  21.                });

Chat Room Sends File Messages

JMessage#sendChatroomFile()

Request Parameter

KEY REQUIRE DESCRIPTION
target_rid TRUE Target id
file Either file or msg_body DataForm object of images
msg_body Either file or msg_body Message’s msg_body, used to implement message forwarding
target_rname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type

Request Example

  1.   // 发送消息
  2.   JIM.sendChatroomFile({
  3.                  'target_rid' : '<targetRid>',
  4.                  'file' : '<formData with file>',
  5.                  'extras' : 'json object'
  6.                }).onSuccess(function(data , msg) {
  7.                   //data.code 返回码
  8.                   //data.message 描述
  9.                   //data.room_id 目标聊天室 id
  10.                   //data.msg_id 发送成功后的消息 id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                }).onFail(function(data) {
  13.                    //同发送单聊文本
  14.                });
  1.   // 转发消息
  2.   JIM.sendChatroomFile({
  3.                  'target_rid' : '<targetRid>',
  4.                  'msg_body' : {
  5.                              'media_id':'',
  6.                           'media_crc32':'',
  7.                                  'hash':'',
  8.                                 'fname':'',
  9.                                 'fsize':'',
  10.                               'extras' : 'json object'
  11.                                 } // 可以直接从已有消息体里面获取msg_body
  12.                }).onSuccess(function(data , msg<可选>) {
  13.                   //data.code 返回码
  14.                   //data.message 描述
  15.                   //data.room_id 目标聊天室 id
  16.                   //data.msg_id 发送成功后的消息 id
  17.                   //data.ctime_ms 消息生成时间,毫秒
  18.                }).onFail(function(data) {
  19.                   //同发送单聊文本
  20.                });

Chat Room Sends Location Message

JMessage#sendChatroomLocation()

Request Parameter

KEY REQUIRE DESCRIPTION
target_rid TRUE Username of message receiver
latitude Either latitude or msg_body Latitude
longitude Either longitude or msg_body Longitude
scale Either scale or msg_body Map zoom level
label Either label or msg_body Address
msg_body Either position related parameter or msg_body Message’s msg_body, used to implement message forwarding
target_rname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type

Request Example

  1.   // 发送消息
  2.   JIM.sendChatroomLocation({
  3.                 'target_rid' : '<targetRid>',
  4.                   'latitude' : '<latitude>',
  5.                  'longitude' : '<longitude>',
  6.                  'scale' : '<scale>',
  7.                  'label' : '<address label>'
  8.                  'extras' : 'json object'
  9.                }).onSuccess(function(data , msg) {
  10.                   //data.code 返回码
  11.                   //data.message 描述
  12.                   //data.room_id 目标聊天室 id
  13.                   //data.msg_id 发送成功后的消息 id
  14.                   //data.ctime_ms 消息生成时间,毫秒
  15.                }).onFail(function(data) {
  16.                    //同发送单聊文本
  17.                });
  1.   // 转发消息
  2.   JIM.sendChatroomLocation({
  3.               'target_rid' : '<targetRid>',
  4.                 'msg_body' : {
  5.                                'latitude' : '<latitude>',
  6.                               'longitude' : '<longitude>',
  7.                                   'scale' : '<scale>',
  8.                                   'label' : '<address label>',
  9.                                  'extras' : 'json object'
  10.                               } // 可以直接从已有消息体里面获取msg_body
  11.                }).onSuccess(function(data , msg) {
  12.                   //data.code 返回码
  13.                   //data.message 描述
  14.                   //data.room_id 目标聊天室 id
  15.                   //data.msg_id 发送成功后的消息 id
  16.                   //data.ctime_ms 消息生成时间,毫秒
  17.                }).onFail(function(data) {
  18.                    //同发送单聊文本
  19.                });

Chat Room Sends Custom Messages

JMessage#sendChatroomCustom()

Request Parameter

KEY REQUIRE DESCRIPTION
target_rid TRUE Username of message receiver
custom TRUE Custom json object message
msg_body Either custom or msg_body Message’s msg_body, used to implement message forwarding
target_rname FALSE Recipient’s display name
extras FALSE Additional fields, dictionary type

Request Example

  1.    // 发送消息
  2.    JIM.sendChatroomCustom({
  3.               'target_rid' : '<targetRid>',
  4.                  'custome' : '<json object>'
  5.                  'appkey' : '<targetAppkey>'
  6.                }).onSuccess(function(data , msg) {
  7.                   //data.code 返回码
  8.                   //data.message 描述
  9.                   //data.room_id 目标聊天室 id
  10.                   //data.msg_id 发送成功后的消息 id
  11.                   //data.ctime_ms 消息生成时间,毫秒
  12.                }).onFail(function(data) {
  13.                   //同发送单聊文本
  14.                });
  1.   // 转发消息
  2.   JIM.sendChatroomCustom({
  3.            'target_rid' : '<targetRid>',
  4.            'msg_body' : '<json object>' // 可以直接从已有消息体里面获取msg_body
  5.                }).onSuccess(function(data , msg) {
  6.                  //data.code 返回码
  7.                   //data.message 描述
  8.                   //data.room_id 目标聊天室 id
  9.                   //data.msg_id 发送成功后的消息 id
  10.                   //data.ctime_ms 消息生成时间,毫秒
  11.                }).onFail(function(data) {
  12.                   //同发送单聊文本
  13.                });

Do-Not-Disturb Management

Get Do-Not-Disturb

JMessage#getNoDisturb()

Request Parameter

N/A

Request Example

  1.    JIM.getNoDisturb().onSuccess(function(data) {
  2.                    //data.code 返回码
  3.                    //data.message 描述
  4.                    //data.no_disturb.global 全局免打扰设置：0 关闭 1 打开
  5.                    //data.no_disturb.users[] 免打扰用户列表，比如示例
  6.                    //data.no_disturb.users[0].username 用户名
  7.                    //data.no_disturb.users[0].nickname 用户昵称
  8.                    //data.no_disturb.users[0].appkey 用户所属 appkey                 
  9.                    //data.no_disturb.groups[0].gid 群id
  10.                    //data.no_disturb.groups[0].name 群名
  11.                    //data.no_disturb.groups[0].desc 群描述
  12.                    //data.no_disturb.groups[0].appkey 群所属appkey
  13.                    //data.no_disturb.groups[0].ctime 群创建时间
  14.                    //data.no_disturb.groups[0].mtime 最近一次群信息修改时间
  15.                    //data.no_disturb.groups[0].avatar 群头像
  16.                    //data.no_disturb.groups[0].group_type 公开群:2,私有群:0或者1
  17.                }).onFail(function(data) {
  18.                    //data.code 返回码
  19.                    //data.message 描述
  20.                });

Add User Do-Not-Disturb

JMessage#addSingleNoDisturb()

Request Parameter

KEY REQUIRE DESCRIPTION
target_name TRUE Username
appkey FALSE Required for cross-application, default is not filled in to indicate this application

Request Example

  1.    JIM.addSingleNoDisturb({
  2.           'target_name' : '<targetUserName>',
  3.           'appkey' : '<targetAppkey>'
  4.                }).onSuccess(function(data) {
  5.                    //data.code 返回码
  6.                    //data.message 描述
  7.                }).onFail(function(data) {
  8.                    // 同上
  9.                });

Turn off User Do-Not-Disturb

JMessage#delSingleNoDisturb()

Request Parameter

KEY REQUIRE DESCRIPTION
target_name TRUE Username
appkey FALSE Required for cross-application, default is not filled in to indicate this application

Request Example

  1.    JIM.delSingleNoDisturb({
  2.           'target_name' : '<targetUserName>',
  3.           'appkey' : '<targetAppkey>'
  4.                }).onSuccess(function(data) {
  5.                    //data.code 返回码
  6.                    //data.message 描述
  7.                }).onFail(function(data) {
  8.                    // 同上
  9.                });

Add Group Do-Not-Disturb

JMessage#addGroupNoDisturb()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1.    JIM.addGroupNoDisturb({
  2.                      'gid' : '<targetGid>'
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    // 同上
  8.                });

Turn off Group Do-Not-Disturb

JMessage#delGroupNoDisturb()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1.    JIM.delGroupNoDisturb({
  2.                      'gid' : '<targetGid>'
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    // 同上
  8.                });

List of Group Blocking

JMessage#groupShieldList()

Request Parameter

N/A

Request Example

  1.    JIM.groupShieldList().onSuccess(function(data) {
  2.                   //data.code 返回码
  3.                   //data.message 描述
  4.                   //data.group_list[] 群组列表，如下示例
  5.                   //data.group_list[0].gid 群id
  6.                   //data.group_list[0].name 群名
  7.                   //data.group_list[0].desc 群描述
  8.                   //data.group_list[0].appkey 群所属appkey
  9.                   //data.group_list[0].ctime 群创建时间
  10.                   //data.group_list[0].mtime 最近一次群信息修改时间
  11.                   //data.group_list[0].avatar 群头像
  12.                   //data.group_list[0].group_type 公开群:2,私有群:0或者1 
  13.                }).onFail(function(data) {
  14.                    // 同上
  15.                });

Add Group Blocking

JMessage#addGroupShield()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1.    JIM.addGroupShield({
  2.                      'gid' : '<targetGid>'
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    // 同上
  8.                });

Close Group Blocking

JMessage#delGroupShield()

Request Parameter

KEY REQUIRE DESCRIPTION
gid TRUE Group id

Request Example

  1.    JIM.delGroupShield({
  2.                      'gid' : '<targetGid>'
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    //同上
  8.                });

Add Global Do-Not-Disturb

JMessage#addGlobalNoDisturb()

Request Parameter

N/A

Request Example

  1.    JIM.addGlobalNoDisturb().onSuccess(function(data) {
  2.                    //data.code 返回码
  3.                    //data.message 描述
  4.                }).onFail(function(data) {
  5.                    // 同上
  6.                });

Turn off Global Do-Not-Disturb

JMessage#delGlobalNoDisturb()

Request Parameter

N/A

Request Example

  1.    JIM.delGlobalNoDisturb().onSuccess(function(data) {
  2.                    //data.code 返回码
  3.                    //data.message 描述
  4.                }).onFail(function(data) {
  5.                    // 同上
  6.                });

Blacklist Management

Get blacklist

JMessage#getBlacks()

Request Parameter

N/A

Request Example

  1.    JIM.getBlacks().onSuccess(function(data) {
  2.                    //data.code 返回码
  3.                    //data.message 描述
  4.                    //data.black_list[] 黑名单列表，比如示例
  5.                    //data.black_list[0].username
  6.                    //data.black_list[0].appkey
  7.                    //data.black_list[0].nickname
  8.                    //data.black_list[0].avatar 头像
  9.                    //data.black_list[0].birthday 生日，默认空
  10.                    //data.black_list[0].gender 性别 0 未知， 1 男 ，2 女
  11.                    //data.black_list[0].signature 用户签名
  12.                    //data.black_list[0].region 用户所属地区
  13.                    //data.black_list[0].address 用户地址
  14.                    //data.black_list[0].mtime 用户信息最后修改时间
  15.                }).onFail(function(data) {
  16.                    //data.code 返回码
  17.                    //data.message 描述
  18.                });

Add Blacklists

JMessage#addSingleBlacks()

Request Parameter

KEY REQUIRE DESCRIPTION
member_usernames TRUE Example of user lists: [{‘username’: ‘name1’, ‘appkey’: ‘ Required for cross-application, default is not filled in to indicate this application ‘}]

Request Example

  1.    JIM.addSingleBlacks({
  2.           'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    //data.code 返回码
  8.                    //data.message 描述
  9.                });

Remove Blacklists

JMessage#delSingleBlacks()

Request Parameter

KEY REQUIRE DESCRIPTION
member_usernames TRUE Example of user lists: [{‘username’: ‘name1’, ‘appkey’: ‘ Required for cross-application, default is not filled in to indicate this application’}]

Request Example\

  1.    JIM.delSingleBlacks({
  2.           'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
  3.                }).onSuccess(function(data) {
  4.                    //data.code 返回码
  5.                    //data.message 描述
  6.                }).onFail(function(data) {
  7.                    //data.code 返回码
  8.                    //data.message 描述
  9.                });

Friends Related

Friends List

JMessage#getFriendList()

Request Parameter

N/A

Request Example

  1.    JIM.getFriendList().onSuccess(function(data) {
  2.                    //data.code 返回码
  3.                    //data.message 描述
  4.                    //data.friend_list[] 好友列表，示例如下
  5.                    //data.friend_list[0].username
  6.                    //data.friend_list[0].appkey
  7.                    //data.friend_list[0].nickname
  8.                    //data.friend_list[0].avatar 头像
  9.                    //data.friend_list[0].memo_nam 好友备注
  10.                    //data.friend_list[0].memo_others 其他备注
  11.                    //data.friend_list[0].birthday 生日，默认空
  12.                    //data.friend_list[0].gender 性别 0 未知， 1 男 ，2 女
  13.                    //data.friend_list[0].signature 用户签名
  14.                    //data.friend_list[0].region 用户所属地区
  15.                    //data.friend_list[0].address 用户地址
  16.                    //data.friend_list[0].mtime 用户信息最后修改时间
  17.                }).onFail(function(data) {
  18.                    //data.code 返回码
  19.                    //data.message 描述
  20.                });

Add Friends

JMessage#addFriend()

Request Parameter

KEY REQUIRE DESCRIPTION
target_name TRUE Target username
why TRUE Invitation instructions
appkey FALSE Appkey of target app is required when queried across applications

Request Example

  1.    JIM.addFriend({
  2.              'target_name' : '< username >' ,
  3.                      'why' : '< why >',
  4.                   'appkey' : '<appkey>'
  5.                }).onSuccess(function(data) {
  6.                    //data.code 返回码
  7.                    //data.message 描述
  8.                }).onFail(function(data) {
  9.                    // 同上
  10.                });

Agree Friends Request

Since 2.4.0

JMessage#acceptFriend()

Request Parameter

KEY REQUIRE DESCRIPTION
target_name TRUE Target username
appkey FALSE Appkey of target app is required when queried across applications

Request Example

  1.    JIM.acceptFriend({
  2.              'target_name' : '< username >' ,
  3.                   'appkey' : '<appkey>'
  4.                }).onSuccess(function(data) {
  5.                    //data.code 返回码
  6.                    //data.message 描述
  7.                }).onFail(function(data) {
  8.                    // 同上
  9.                });

Reject Friends Request

Since 2.4.0

JMessage#declineFriend()

Request Parameter

KEY REQUIRE DESCRIPTION
target_name TRUE Target username
why FALSE Reason for rejection
appkey FALSE Appkey of target app is required when queried across applications

Request Example

  1.    JIM.declineFriend({
  2.              'target_name' : '< username >' ,
  3.                      'why' : '< why >',
  4.                   'appkey' : '<appkey>'
  5.                }).onSuccess(function(data) {
  6.                    //data.code 返回码
  7.                    //data.message 描述
  8.                }).onFail(function(data) {
  9.                    // 同上
  10.                });

Delete Friends

JMessage#delFriend()

Request Parameter

KEY REQUIRE DESCRIPTION
target_name TRUE Target username
appkey FALSE Appkey of target app is required when queried across applications

Request Example

  1.    JIM.delFriend({
  2.               'target_name' : '< username >' ,
  3.               'appkey' : '< appkey >'
  4.                }).onSuccess(function(data) {
  5.                    //data.code 返回码
  6.                    //data.message 描述
  7.                }).onFail(function(data) {
  8.                    // 同上
  9.                });

Update Friend Notes

JMessage#updateFriendMemo()

Request Parameter

KEY REQUIRE DESCRIPTION
target_name TRUE Target username
memo_name TRUE Name note
memo_others FALSE Other notes
appkey FALSE Appkey of target app is required when queried across applications

Request Example

  1.    JIM.updateFriendMemo({
  2.           'target_name' : '< username >' ,
  3.             'memo_name' : '< memo_name >',
  4.           'memo_others' : '< memo_others >',
  5.                'appkey' : '< appkey >'
  6.                }).onSuccess(function(data) {
  7.                    //data.code 返回码
  8.                    //data.message 描述
  9.                }).onFail(function(data) {
  10.                    // 同上
  11.                });

Real-time Monitoring of Chat Messages

JMessage#onMsgReceive(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Message reception handler

Array of returned messages

KEY DESCRIPTION
ctime_ms Message generation time, milliseconds
msg_type Message type, 3-single, 4-group
from_appkey Source appkey, valid for single chat
from_username Source username, valid for single chat
from_gid Source group id, valid for group chat
msg_id Message ID
need_receipt Whether need a receipt
custom_notification.enabled Whether to enable notification bar of custom message
custom_notification.title Heading of notification bar
custom_notification.alert Content of notification bar
custom_notification.at_prefix Notification content prefix of @ target
content Message body

Example

  1. JIM.onMsgReceive(function(data) {
  2.    // data.messages[]
  3.    // data.messages[].ctime_ms
  4.    // data.messages[].msg_type 会话类型
  5.    // data.messages[].msg_id
  6.    // data.messages[].from_appey 单聊有效
  7.    // data.messages[].from_username 单聊有效
  8.    // data.messages[].from_gid 群聊有效
  9.    // data.messages[].need_receipt
  10.    // data.messages[].content
  11.    // data.messages[].custom_notification.enabled
  12.    // data.messages[].custom_notification.title
  13.    // data.messages[].custom_notification.alert
  14.    // data.messages[].custom_notification.at_prefix
  15. });

Synchronization Monitoring of Offline Messages

JMessage#onSyncConversation(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Message reception handler

Return Parameter

KEY DESCRIPTION
messages [{‘msg_type’:’session_type’,’from_appkey’:’ target appkey’,’from_username’:’target username’,’from_gid’:’target group id’,’unread_msg_count’:’nnumber of unread messages’, ‘receipt_msgs’:[{‘msg_id’:’message id’,’unread_count’:’unread number’,’mtime’:’update time, millisecond’},…],’msgs’:[{refer to real-time monitoring of chat message },…]},…]

Example

  1. JIM.onSyncConversation(function(data) {
  2.    // data[]
  3.    // data[].msg_type 会话类型
  4.    // data[].from_appey 单聊有效
  5.    // data[].from_username 单聊有效
  6.    // data[].from_gid 群聊有效
  7.    // data[].unread_msg_count 消息未读数
  8.    // 消息已读回执状态，针对自己发的消息
  9.    // data[].receipt_msgs[]
  10.    // data[].receipt_msgs[].msg_id
  11.    // data[].receipt_msgs[].unread_count
  12.    // data[].receipt_msgs[].mtime
  13.    // 消息列表
  14.    // data[].msgs[]
  15.    // data[].msgs[].msg_id
  16.    // data[].msgs[].content
  17.    // data[].msgs[].msg_type
  18.    // data[].msgs[].ctime_ms
  19.    // data[].msgs[].need_receipt
  20.    // data[].msgs[].custom_notification.enabled
  21.    // data[].msgs[].custom_notification.title
  22.    // data[].msgs[].custom_notification.alert
  23.    // data[].msgs[].custom_notification.at_prefix
  24. });

Monitoring of User Information Change

JMessage#onUserInfUpdate(fn)

Monitoring Object

Monitoring objects include friends, group members, single chats in the conversation list.

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Handler function

Return Parameter

KEY DESCRIPTION
appkey Changer’s appkey
username Changer’s username
mtime Change time (seconds)

Example

  1. JIM.onUserInfUpdate(function(data) {
  2.     console.log('user info update event: ' + JSON.stringify(data));
  3. });

Business Event Monitoring

JMessage#onEventNotification(fn)

Request Parameter( Value based on the event)

KEY REQUIRE DESCRIPTION
fn TRUE Event reception handler

Return Parameter\

KEY DESCRIPTION
event_id Event id
event_type The event type. The developer takes related field based on the corresponding event type, see the following example
gid Relationship type
from_username Username of the event initiator
from_appkey appkey of the event initiator
to_usernames Event party [{“username”:””,”appkey”:””,”nickname”:””},…]
ctime_ms Event generation time, accurate to milliseconds
extra Identification field
return_code Used for friend invitation response events
description Description
msg_ids Message id list
from_gid Group gid
to_groups Target group, format [{‘gid’:’ ‘,’name’:’ ‘},…]
new_owner New owner, format {‘appkey’:’ ‘,’username’:’ ‘}
group_name Group name
type 0: single chat, 1: group chat
group_name Group name

Example of simultaneous login or being banned and forced to offline event: event_type = 1

  1. //被踢者收到该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.extra =0同时登录，=1用户被禁用，=2用户被删除
  7. });

Example of password changed and forced to offline event: event_type = 2

  1. //当前在线者收到该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6. });

Example of a friend inviting event: event_type = 5

  1. //被邀请方收到该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 邀请方 username
  7.     //data.from_appkey 邀请方 appkey
  8.     //data.media_id 邀请方头像
  9.     //data.extra 1-来自邀请方的事件，2－来自被邀请方，即好友邀请的应答事件
  11. });

Example of a friend responsing event: event_type = 5

  1. //邀请方收到该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 被邀请方 username
  7.     //data.from_appkey 被邀请方 appkey
  8.     //data.extra 1-来自邀请方的事件，2－来自被邀请方，即好友邀请的应答事件
  9.     //data.return_code 0－添加好友成功，其他为添加好友被拒绝的返回码
  10.     //data.media_id 被邀请方头像
  11.     //data.description 原因
  12. });

Example of a friend deleting event: event_type = 6

  1. //被删除好友收到该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 删除请求方 username
  7.     //data.from_appkey 删除请求方 appkey
  8. });

Example of a friend updating event: event_type = 7

  1. //好友双方都会收到该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.description API 好友管理
  7. });

Example of a group creating event: event_type = 8

  1. //群里所有人接收，即创建者接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 创建者 username
  7.     //data.from_appkey 创建者 appkey
  8.     //data.to_usernames 创建者
  9.     //data.group_name 群名
  10.     //data.media_id 群头像
  11.     //data.gid 群 id
  12. });

Example of a group exiting event: event_type = 9

  1. //群里所有人接收，包括退群者
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.extra=69 表示群主解散群，所有成员退出
  7.     //data.from_username 退群者 username，extra=69 为空
  8.     //data.from_appkey 退群者 appkey，extra=69 为空
  9.     //data.to_usernames 退群者
  10.     //data.gid 群 id
  11.     //data.media_id 群头像
  12.     //data.group_name 群名
  13.     //data.new_owner 如果是群主退出，这个表示新群主
  14. });

Example of a group member adding event: event_type = 10

  1. //群里所有人接收，包括被添加的成员和原来的成员
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 添加者 username
  7.     //data.from_appkey 添加者 appkey
  8.     //data.to_usernames 被添加的成员
  9.     //data.media_id 群头像
  10.     //data.group_name 群名
  11.     //data.gid 群id
  12. });

Example of a group member deleting event: event_type = 11

  1. //群里所有人接收，包括被删除的成员和剩下的成员
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 删除者 username
  7.     //data.from_appkey 删除者 appkey
  8.     //data.to_usernames 被删除的成员
  9.     //data.media_id 群头像
  10.     //data.group_name 群名
  11.     //data.gid 群 id
  12.     //data.new_owner 如果是群主被删除，这个表示新群主
  13. });

Example of a group information modifying event: event_type = 12

  1. //群里所有人接收该事件，包括修改者
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 修改者 username
  7.     //data.from_appkey 修改者 appkey
  8.     //data.to_usernames 修改者
  9.     //data.gid 群 id
  10. });

Example of a Do-Not-Disturb changing event: event_type = 37

  1. //变更方接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6. });

Example of a blacklist changing event: event_type = 38

  1. //变更方接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6. });

Example of a group blocking change event: event_type =39

  1. //变更方接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6. });

Example of a user information changing event: event_type = 40

  1. //变更方接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6. });

Example of a message recalling event: event_type = 55

  1. //变更方接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.from_username 消息发送方 username
  7.     //data.from_appkey 消息发送方 appkey
  8.     //data.msgid_list 被撤回的消息列表
  9.     //data.type 0 单聊 ，1 群聊
  10.     //data.to_usernames 撤回消息目标用户，单聊有效
  11.     //data.from_gid 群id 群聊有效
  12. });

Example of a group applying event: event_type = 56

Since 2.5.0

  1. //群主接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.from_gid 群 id
  5.     //data.group_name 群名
  6.     //data.media_id 群头像
  7.     //data.event_type 事件类型
  8.     //data.ctime_ms 事件生成时间
  9.     //data.by_self 是否主动申请入群，true 是，false 被动邀请
  10.     //data.from_appkey 邀请方或申请方 appkey
  11.     //data.from_username 邀请方或申请方 username
  12.     //data.target_appkey 被邀请方所属 appkey
  13.     //data.to_usernames 被邀请方数组，by_self=false 有效，当by_self=true的时候邀请的目标用户就是from_user
  14.     //data.description 申请理由，by_self=true 有效
  15. });

Example a application for group being rejected event: event_type = 57

Since 2.5.0

  1. //邀请方或者申请方接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.from_gid 群 id
  5.     //data.group_name 群名
  6.     //data.media_id 群头像
  7.     //data.event_type 事件类型
  8.     //data.ctime_ms 事件生成时间
  9.     //data.from_appkey 群主所属 appkey
  10.     //data.from_username 群主 username
  11.     //data.to_usernames 被邀请方或申请方   
  12.     //data.description 拒绝理由
  13. });

Example of approval rejected by administrator event: event_type = 58

Since 2.6.0

  1. //群里所有管理员和群主
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.from_gid 群 id
  5.     //data.group_name 群名
  6.     //data.media_id 群头像
  7.     //data.event_type 事件类型
  8.     //data.ctime_ms 事件生成时间
  9.     //data.from_appkey 群主所属 appkey
  10.     //data.from_username 群主 username
  11.     //data.to_usernames 被拒绝成员   
  12.     //data.from_eventid 操作事件 id
  13. });

Group user banned event: event_type = 65

Since 2.5.0

  1. //群所有用户接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.from_gid 群 id
  5.     //data.group_name 群名
  6.     //data.media_id 群头像
  7.     //data.event_type 事件类型
  8.     //data.ctime_ms 事件生成时间
  9.     //data.from_appkey 群主所属 appkey
  10.     //data.from_username 群主 username
  11.     //data.to_usernames 目标用户列表   
  12.     //data.extra 1:禁言 2:取消禁言
  13. });

Group Administrator Change Event: event_type = 80

Since 2.6.0

  1. //群所有用户接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.from_gid 群 id
  5.     //data.group_name 群名
  6.     //data.media_id 群头像
  7.     //data.event_type 事件类型
  8.     //data.ctime_ms 事件生成时间
  9.     //data.from_appkey 群主所属 appkey
  10.     //data.from_username 群主 username
  11.     //data.to_usernames 目标用户列表   
  12.     //data.extra =1 添加管理员 2=取消管理员
  13. });

Group owner handover event: event_type = 82

Since 2.6.0

  1. //群所有用户接收该事件
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.from_gid 群 id
  5.     //data.group_name 群名
  6.     //data.media_id 群头像
  7.     //data.event_type 事件类型
  8.     //data.ctime_ms 事件生成时间
  9.     //data.from_appkey 老群主 appkey
  10.     //data.from_username 老群主 username
  11.     //data.to_usernames 新群主   
  12. });

Example of a multi-end online friends changing event: event_type =100

  1. //自己触发
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.extra 5 添加好友 6 删除好友 7 修改好友备注
  7.     //data.to_usernames 目标用户
  8.     /data.media_id 目标头像
  9.     //data.description extra=7有效，格式{'memo_name':','memo_others':''}
  10. });

Example of a multi-end online blacklists changing event: event_type =101

  1. //自己触发
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.to_usernames 目标用户
  7.     //data.extra 1 添加黑名单 2 删除黑名单
  8. });

Example of a multi-end online Do-Not-Disturb changing event: event_type =102

  1. //自己触发
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.extra 31 添加单聊免打扰 32 删除单聊免打扰
  7.     //           33 添加群组免打扰 34 删除群组免打扰
  8.     //           35 添加全局免打扰 36 删除全局免打扰
  9.     //data.to_usernames 目标用户, extra = 31,32 有效
  10.     //data.to_groups 目标群组, extra = 33,34 有效
  11. });

Example of a multi-end online group blocking changing event: event_type =103

  1. //自己触发
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 事件生成时间
  6.     //data.extra 1 添加群屏蔽 2 删除群屏蔽
  7.     //data.to_groups 目标群组
  8. });

Example of a multi-end online message read receipt changing event: event_type = 201

  1. //自己触发
  2. JIM.onEventNotification(function(data) {
  3.     //data.event_id 事件 id
  4.     //data.event_type 事件类型
  5.     //data.ctime_ms 
  6.     //data.description.type 3:单聊 4:群聊
  7.     //data.description.gid 群 id, 群聊有效
  8.     //data.description.appkey 用户所属 appkey, 单聊有效
  9.     //data.description.username 用户 name
  10.     //data.msgids 表示其他端对消息列表里面的消息已经已读了
  11. });

Synchronization Monitoring of Business Event

JMessage#onSyncEvent(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Event reception handler

Return Parameter (Same as business event monitoring)

Example

  1. JIM.onSyncEvent(function(data) {
  2.     // data 为事件数组 [event1,event2,...]
  3. });

Real-time Monitoring of Message Reading Numbers Changing Event

Since 2.4.0

JMessage#onMsgReceiptChange(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Event reception handler

Return Parameter

KEY DESCRIPTION
gid Group ID, valid for group chat
appkey appkey belongs to, valid for single chat
username User name, valid for single chat
type Session type, 3: single chat, 4: group chat
receipt_msgs The list of unread messages is as follows

Message Unread Status Parameter

KEY DESCRIPTION
msg_id Message id
unread_count Unread number of messages. Compared with the previous one, take the smallest as the latest number of unread messages.

Example

  1. JIM.onMsgReceiptChange(function(data) {
  2.     // data.type
  3.     // data.gid
  4.     // data.appkey
  5.     // data.username
  6.     // data.receipt_msgs[].msg_id
  7.     // data.receipt_msgs[].unread_count
  8. });

Synchronization Monitoring of Message’s Reading Number Changing Event

Since 2.4.0

JMessage#onSyncMsgReceipt(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Event reception handler

Return Parameter

Same with the real-time monitoring of reading number changing event

Example

  1. JIM.onSyncMsgReceipt(function(data) {
  2.     // data 为已读数变更事件数组 [receiptChange1,...]
  3. });

Monitoring of Session’s Unreading Number Changing (Multi-end Online)

Since 2.4.0

JMessage#onMutiUnreadMsgUpdate(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Event reception handler

Return Parameter

KEY DESCRIPTION
type 3 single chat, 4 group chat
gid Group id , type=4 is valid
appkey Appkey of target user, type=3 is valid
username Username of target user,type=3 is valid

Example

  1. JIM.onMutiUnreadMsgUpdate(function(data) {
  2.     // data.type 会话类型
  3.     // data.gid 群 id
  4.     // data.appkey 所属 appkey
  5.     // data.username 会话 username
  6. });

Monitoring of Message Transparent Transmission

Since 2.4.0

JMessage#onTransMsgRec(fn)

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Monitoring handler function

Return Parameter

KEY DESCRIPTION
type 3: transparent transmission of single chat messages, 4: transparent transmission of group chat messages, 5: transparent transmission of messages on online devices
gid Group id , type=4 is valid
from_appkey Appkey of target user, type=3 is valid
from_username Username of target user, type=3 is valid
platform Target platforms: all android ios pc, type=5 is valid
cmd Transparent transmission of information

Example

  1. JIM.onTransMsgRec(function(data) {
  2.     // data.type 会话类型
  3.     // data.gid 群 id
  4.     // data.from_appkey 用户所属 appkey
  5.     // data.from_username 用户 username
  6.     // data.platform 目标平台
  7.     // data.cmd 透传信息
  8. });

Chat Room Message Monitoring

JMessage#onRoomMsg(fn)

Since 2.5.0

Request Parameter

KEY REQUIRE DESCRIPTION
fn TRUE Message reception handler

Array of returned messages

KEY DESCRIPTION
room_id Chat room id
msg_id Message ID
ctime_ms Message generation time, milliseconds
content Message body

Example

  1. JIM.onRoomMsg(function(data) {
  2.    // data.room_id 聊天室 id
  3.    // data.msg_id 消息 id
  4.    // data.ctime_ms 消息生成时间
  5.    // data.content
  6. });

Advanced Application

Send Cross-Application Messages

Cross-application refers to the operation between different appkeys under the same account. By default, if the target appkey is not specified, the target appkey is the appkey used by the current login user. If a cross-application operation is required, specify a specific target appkey on the interface parameter.

Take 2.1 sending a single chat as an example:

JMessage#sendSingleMsg()

Request Parameter

KEY REQUIRE DESCRIPTION
target_username TRUE Username of message receiver
target_nickname TRUE Nickname of message receiver
content TRUE Message text
extras FALSE Additional fields, dictionary type
appkey FALSE Appkey of target app is required when queried across applications.

Appkey is the target appkey and similar with other interfaces

Send and Receive Pictures or Files

The SDK supports sending of single picture and single file. The interface for file and picture sending needs to receive a value of FormData, which contains the file information that the user needs to send.

Sample of constructing FormData:

  1. var fd = new FormData();
  3. fd.append(fileName, file);

After the FormData is constructed, it is passed as a parameter to the corresponding interface. Take sending of a single chat image as an example

  1. sendSinglePic({
  2.             'target_username' : across_user,
  3.             'appkey' : across_appkey,
  4.             'image' : fd //构造好的 FormData
  5.             }).onSuccess(function(data) {
  6.                 console.log('success:' + JSON.stringify(data))
  7.             }).onFail(function(data) {
  8.                  console.log('error:' + JSON.stringify(data))
  9.            });

Other interfaces of files and pictures sending are similar.

The reception of pictures and files needs to be passed in media_id via the JMessage#getResource interface to obtain access path.

Send and Receive Emoij Expressions

Emoji expression is a character in the \u1F601-\u1F64F section of Unicode. The message content of JMessage is all encoded by utf8mb4, backward compatible with UTF8.

As long as the Emoij character is entered correctly, it can be sent using the JMessage Text API. If users need to dump chat messages, make sure that the database supports utf8mb4 encoding at first.

Developers can use Web Emoij solutions of third-party open source such as coocy/emoji,iamcal/js-emoji to display Emoij expressions on web pages.

Error Code Definition

Reference Document: Error Code List of IM Web SDK