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:

{
    "appkey": "7e42e869baa2fbca8ccb823c",
    "random_str": "022cd9fd995849b58b3ef0e943421ed9",
    "signature": "E422A978DE37196588531CD0C42010B5",
    "timestamp": "1467967210887"
}

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:

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:

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:

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

var JIM = new JMessage();

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

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

JIM.sendSingleMsg({
    'target_username' : 'xiezefan',
    'content' : 'Hi, JiGuang '
}).onSuccess(function(data) {
    // do something
}).onFail(function(data) {
    // do something
}).onTimeout(function(data) {
    if (data.response_timeout) {
        // do something when response timeout
    } else {
        // do something when request timeout
    }
}).onAck(function(data) {
    // do something
});

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

Request Example

  JIM.init({
               "appkey" : "<appkey>",
           "random_str" : "<random_str>",
            "signature" : "<signature>",
            "timestamp" : "<timestamp>",
            "flag" : 0
        }).onSuccess(function(data) {
           //data.code 返回码
           //data.message 描述
          }).onFail(function(data) {
            // 同上
        });

Disconnection Monitoring

JMessage#onDisconnect(fn)

Request Parameter

Request Example

  JIM.onDisconnect(function(){
  });

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

Request Example

  JIM.register({
        'username' : '<register name>',
        'password' : '<register password>',
          'is_md5' : '<is_md5>',
          'extras' : {'key1':'val1','key2':'val2'},
         'address' : '深圳'
        }).onSuccess(function(data) {
            //data.code 返回码
            //data.message 描述
          }).onFail(function(data) {
            // 同上
        });

Connection Status

JMessage#isConnect()

Request Parameter\

N/A

Request Example

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

Initialization State

JMessage#isInit()

Request Parameter

N/A

Request Example

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

Login Status

JMessage#isLogin()

Request Parameter

N/A

Request Example

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

Log in

Support online_list Since 2.6.0

JMessage#login()

Request Parameter

Request Example

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

Log out

JMessage#loginOut()

Request Parameter

N/A

Request Example

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

User Management

Get User Information

Support extras fields Since 2.4.0

JMessage#getUserInfo()

Request Parameter:

Request Example

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

Update Personal Information

Support extras fields since 2.4.0

JMessage#updateSelfInfo()

Request Parameter

Request Example

   JIM.updateSelfInfo({
                 'nickname' : '<your_nickname>',
                 'birthday' : '<your_address>',
                'signature' : '<your_address>',
                   'gender' : '<your_address>',
                   'region' : '<your_address>',
                  'address' : '<your_address>'
                   'extras' : {'key1':'val1','key2':'val2'}
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   //同上
               });

Update Personal Avatar

JMessage#updateSelfAvatar()

Request Parameter

Request Example

   JIM.updateSelfAvatar({
                'avatar' : '<formData with image>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   //同上
               });

Update Personal Password

JMessage#updateSelfPwd()

Request Parameter

Request Example

   JIM.updateSelfPwd({
                 'old_pwd' : '<oldPwd>',
                 'new_pwd' : '<newPwd>',
                  'is_md5' : '<idMd5>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                  //同上
               });

Message Management

Get a list of sessions

Support session extras fields Since 2.4.0

JMessage#getConversation()

Request Parameter

N/A

Request Example

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

Update Session Information

Since 2.4.0

JMessage#updateConversation()

Request Parameter

Request Example

   // 群会话,调用则成功，无回调函数
   JIM.updateConversation({
                            'gid' : 'gid',
                            'extras' : {'key':'val','key2':'val2'}
                           });

   // 单聊会话, 调用则成功，无回调函数
   JIM.updateConversation({
                            'appkey' : 'appkey',
                            'username' : 'username',
                            'extras' : {'key':'val','key2':'val2'}
                           });

Get Number of Unread Sessions

Since 2.4.0

JMessage#getUnreadMsgCnt()

Request Parameter

Request Example

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

Reset the Number of Unread Sessions

Since 2.4.0

JMessage#resetUnreadCount()

Request Parameter

Request Example

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

List of Message Unread User

Since 2.4.0

JMessage#msgUnreadList()

Request Parameter

Request Example

   // 消息发送设置了需要回执的时候,可以查看消息的已读未读用户列表
   // 消息接收方收到需要回执的消息的时候,阅读后需要通过消息已读回执接口通知后台消息已读
   JIM.msgUnreadList({
                        'msg_id' : '<msg_id>'
                     }).onSuccess(function(data) {
                        //data.code 返回码
                        //data.message 描述
                        // 未读用户列表
                        //data.msg_unread_list.unread_list[].appkey
                        //data.msg_unread_list.unread_list[].username
                        //data.msg_unread_list.read_list[].nickname
                        // 已读用户列表
                        //data.msg_unread_list.read_list[].appkey
                        //data.msg_unread_list.read_list[].username
                        //data.msg_unread_list.read_list[].nickname
                    }).onFail(function(data) {
                        //data.code 返回码
                        //data.message 描述
                     });

Read Receipt of Single Chat Messages

Since 2.4.0

JMessage#addSingleReceiptReport()

Request Parameter

Request Example

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

                     })

Read Receipt of Group Chat Messages

Since 2.4.0

JMessage#addGroupReceiptReport()

Request Parameter

Request Example

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

                     });

Get Resource Access Path

JMessage#getResource ()

Request Parameter

Request Example

   JIM.getResource({
                 'media_id' : '<media_id >',
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
                   //data.url 资源临时访问路径
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Retract Messages

JMessage#msgRetract ()

Request Parameter

Request Example

   JIM.msgRetract({
                 'msg_id' : '<msg_id >',
               }).onSuccess(function(data , msg) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Send Single Chat Texts

JMessage#sendSingleMsg()

Request Parameter

custom_notification：

Request Example

   // 发送消息
   JIM.sendSingleMsg({
                 'target_username' : '<targetName>',
             'target_nickname' : '<targetNickname>',
                 'content' : '<textContent>',
                 'appkey' : '<targetAppkey>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体,见下面消息体详情
               }).onFail(function(data) {
                  //data.code 返回码
                  //data.message 描述
               });

   // 转发消息
   JIM.sendSingleMsg({
                 'target_username' : '<targetName>',
             'target_nickname' : '<targetNickname>',
                 'msg_body' : {
                              'text' : '',
                            'extras' : 'json object'
                              }, // 可以直接从已有消息体里面获取msg_body
                 'appkey' : '<targetAppkey>',
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体,见下面消息体详情
               }).onFail(function(data) {
                  //data.code 返回码
                  //data.message 描述
               });

Message Body

Details of message body:

Send Single Chat Pictures

JMessage#sendSinglePic()

Request Parameter:

custom_notification：

Request Example

 // 发送消息
 JIM.sendSinglePic({
                 'target_username' : '<targetName>',
             'target_nickname' : '<targetNickname>',
                 'image' : '<formData with image>',
                 'appkey' : '<targetAppkey>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

  // 转发消息
  JIM.sendSinglePic({
                 'target_username' : '<targetName>',
             'target_nickname' : '<targetNickname>',
                 'msg_body' : {
                             'media_id':'',
                          'media_crc32':'',
                                'width':'',
                               'height':'',
                               'format':'',
                                'fsize':'',
                              'extras' : 'json object'
                                }, // 可以直接从已有消息体里面获取msg_body
                 'appkey' : '<targetAppkey>',
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

Send Single Chat Files

JMessage#sendSingleFile()

Request Parameter

custom_notification：

Request Example

  // 发送消息
  JIM.sendSingleFile({
                 'target_username' : '<targetName>',
         'target_nickname' : '<targetNickname>',
                 'file' : '<formData with file>',
                 'appkey' : '<targetAppkey>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

  // 转发消息
  JIM.sendSingleFile({
                 'target_username' : '<targetName>',
             'target_nickname' : '<targetNickname>',
                 'msg_body' : {
                             'media_id':'',
                          'media_crc32':'',
                                 'hash':'',
                                'fname':'',
                                'fsize':'',
                              'extras' : 'json object'
                                }, // 可以直接从已有消息体里面获取msg_body
                 'appkey' : '<targetAppkey>',
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

Send Single Chat Locations

JMessage#sendSingleLocation()

Request Parameter

custom_notification：

Request Example

  // 发送消息
  JIM.sendSingleLocation({
                 'target_username' : '<targetName>',
         'target_nickname' : '<targetNickname>',
         'latitude' : '<latitude>',
                 'longitude' : '<longitude>',
                 'scale' : '<scale>',
                 'label' : '<address label>'
                 'appkey' : '<targetAppkey>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

  // 转发消息
  JIM.sendSingleLocation({
                 'target_username' : '<targetName>',
         'target_nickname' : '<targetNickname>',
                'msg_body' : {
                               'latitude' : '<latitude>',
                              'longitude' : '<longitude>',
                                  'scale' : '<scale>',
                                  'label' : '<address label>',
                                 'extras' : 'json object'
                              } // 可以直接从已有消息体里面获取msg_body
                 'appkey' : '<targetAppkey>',
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

Send Custom Message of Single Chats

JMessage#sendSingleCustom()

Request Parameter

custom_notification：

Request Example

   // 发送消息
   JIM.sendSingleCustom({
                 'target_username' : '<targetName>',
         'target_nickname' : '<targetNickname>',
                 'custome' : '<json object>'
                 'appkey' : '<targetAppkey>'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.appkey 用户所属 appkey
                  //data.target_username 用户名
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

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

Send Group Chat Texts

JMessage#sendGroupMsg()

Request Parameter

custom_notification：

Request Example

   // 发送消息
   JIM.sendGroupMsg({
                 'target_gid' : '<targetGid>',
         'target_gname' : '<targetGName>',
                 'content' : '<textContent>',
                 'extras' : '<json object>',
                 'at_list' : [] //at all
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

   // 转发消息
   JIM.sendGroupMsg({
                 'target_gid' : '<targetGid>',
         'target_gname' : '<targetGName>',
                 'msg_body' : {
                              'text' : '',
                            'extras' : ''
                               }, // 可以直接从已有消息体里面获取msg_body
                 'at_list' : [] //at all
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

Send Group Chat Pictures

JMessage#sendGroupPic()

Request Parameter

custom_notification：

Request Example

   // 发送消息
   JIM.sendGroupPic({
                 'target_gid' : '<targetGid>',
         'target_gname' : '<targetGName>',
                 'image' : '<formData with image>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

  // 转发消息
  JIM.sendGroupPic({
                 'target_gid' : '<targetGid>',
           'target_gname' : '<targetGName>',
                  'msg_body' : {
                             'media_id':'',
                          'media_crc32':'',
                                'width':'',
                               'height':'',
                               'format':'',
                                'fsize':'',
                              'extras' : 'json object'
                                }, // 可以直接从已有消息体里面获取msg_body
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                  //同发送单聊文本
               });

Send Group Chat Files

JMessage#sendGroupFile()

Request Parameter

custom_notification：

Request Example

   // 发送消息
   JIM.sendGroupFile({
                 'target_gid' : '<targetGid>',
         'target_gname' : '<targetGName>',
                 'file' : '<formData with file>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

   // 转发消息
   JIM.sendGroupFile({
                 'target_gid' : '<targetGid>',
         'target_gname' : '<targetGName>',
                 'msg_body' : {
                             'media_id':'',
                          'media_crc32':'',
                                 'hash':'',
                                'fname':'',
                                'fsize':'',
                                'extras' : 'json object'
                                } // 可以直接从已有消息体里面获取msg_body
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

Send Group Chat Locations

JMessage#sendGroupLocation()

Request Parameter

custom_notification：

Request Example

   // 发送消息
   JIM.sendGroupLocation({
                 'target_gid' : '<targetGid>',
         'target_gname' : '<targetGName>',
         'latitude' : '<latitude>',
                 'longitude' : '<longitude>',
                 'scale' : '<scale>',
                 'label' : '<address label>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

   // 转发消息
   JIM.sendGroupLocation({
                 'target_gid' : '<targetGid>',
               'target_gname' : '<targetGName>',
           'msg_body' : {
                              'latitude' : '<latitude>',
                             'longitude' : '<longitude>',
                                 'scale' : '<scale>',
                                 'label' : '<address label>',
                                 'extras' : 'json object'
                              } // 可以直接从已有消息体里面获取msg_body
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

Send Group Custom Messages

JMessage#sendGroupCustom()

Request Parameter

custom_notification：

Request Example

   // 发送消息
   JIM.sendGroupCustom({
                  'target_gid' : '<targetGid>',
        'target_gname' : '<targetGName>',
              'custom' : '<json object>'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.msg_id 发送成功后的消息id
                  //data.ctime_ms 消息生成时间,毫秒
                  //data.target_gid 群 id
                  //data.unread_count 消息需要已读回执的时候,默认未读数
                  //msg.content 发送成功消息体
               }).onFail(function(data) {
                   //同发送单聊文本
               });

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

Transparent Transmission of Single Chat Messages

Since 2.4.0

JMessage#transSingleMsg()

Request Parameter

Request Example

   JIM.transSingleMsg({
                 'target_username' : '<username>',
                             'cmd' : '<cmd>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                    //data.code 返回码
                    //data.message 描述
               });

Transparent Transmission of Group Chat Messages

Since 2.4.0

JMessage#transGroupMsg()

Request Parameter

Request Example

   JIM.transGroupMsg({
                 'gid' : '<gid>',
                 'cmd' : '<cmd>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                    //data.code 返回码
                    //data.message 描述
               });

Transparent Transmission of Multi-end Online Messages

Since 2.6.0

JMessage#transPlatMsg()

Request Parameter

Request Example

   JIM.transPlatMsg({
                 'platform' : 'android',
                 'cmd' : '<cmd>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                    //data.code 返回码
                    //data.message 描述
               });

Group Management

Create a Group

Support group avatar since 2.4.0 Support public groups since 2.5.0

JMessage#createGroup()

Request Parameter

Request Example

   JIM.createGroup({
                 'group_name' : '<groupName>',
          'group_description' : '<groupDescription>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
                  //data.gid 群组id
                  //data.group_name 群名
                  //data.group_descriptin 群描述
               }).onFail(function(data) {
                    //data.code 返回码
                    //data.message 描述
               });

Leave the Group

JMessage#exitGroup()

Request Parameter

Request Example

   JIM.exitGroup({
                  'gid' : '<exit gid>'
               }).onSuccess(function(data) {
                    //data.code 返回码
                    //data.message 描述
                    //data.gid 群组id
                    //data.group_name 群名
               }).onFail(function(data) {
                    //data.code 返回码
                    //data.message 描述
               });

Add Group Members

JMessage#addGroupMembers()

Request Parameter

Request Example

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

Delete Group Members

JMessage#delGroupMembers()

Request Parameter

Request Example

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

Get a List of Groups

JMessage#getGroups()

Support flag Since 2.5.0

Request Parameter

N/A

Request Example

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

Get Group Information

JMessage#getGroupInfo()

Support public groups since 2.5.0

Request Parameter

Request Example

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

Update Group Information

Support group avatar since 2.4.0

JMessage#updateGroupInfo()

Request Parameter

Request Example

   JIM.updateGroupInfo({
                  'gid' : '<gid>',
                  'group_name' : '<new group name>',
                  'group_description' : '<new group description>' 
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Get Group Members

JMessage#getGroupMembers()

Request Parameter

Request Example

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

Join Group Actively(Public Groups)

Since 2.5.0

JMessage#joinGroup()

Request Parameter

Request Example

JIM.joinGroup({
                  'gid' : '<gid>',
                  'reason' : '<reason>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Group Owner Approves Request for Admission

Since 2.5.0

JMessage#addGroupMemberResp()

Request Parameter

Request Example

JIM.addGroupMemberResp({
                  'gid' : '<gid>',
                  'event_id' : '<event_id>'
                  'target_appkey' : '<target_appkey>',
                  'target_username' : '<target_username>',
                  'result' : 2,
                  'from_appkey' : '<from_appkey>',
                  'from_username' : '<from_username>'
                  'resaon' : '<reason>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Add Banned Group Users

Since 2.5.0

JMessage#addGroupMemSilence()

Request Parameter

Request Example

JIM.addGroupMemSilence({
                  'gid' : '<gid>',
                  'target_appkey' : '<target_appkey>',
                  'target_username' : '<target_username>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Dismiss Banned Group Users

Since 2.5.0

JMessage#delGroupMemSilence()

Request Parameter

Request Example

JIM.delGroupMemSilence({
                  'gid' : '<gid>',
                  'target_appkey' : '<target_appkey>',
                  'target_username' : '<target_username>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Add Administrators

Since 2.6.0

JMessage#addGroupKeeper()

Request Parameter

Request Example

JIM.addGroupKeeper({
                  'gid' : '<gid>',
                   'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Remove Administrators

Since 2.6.0

JMessage#delGroupKeeper()

Request Parameter

Request Example

JIM.delGroupKeeper({
                  'gid' : '<gid>',
                   'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Transfer Owner Privileges

Since 2.6.0

JMessage#changeGroupAdmin()

Request Parameter

Request Example

JIM.changeGroupAdmin({
                  'gid' : '<gid>',
                   'target_username' : '<username>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Dissolve Groups

Since 2.6.0

JMessage#dissolveGroup()

Request Parameter

Request Example

JIM.dissolveGroup({
                  'gid' : '<gid>'
               }).onSuccess(function(data) {
                  //data.code 返回码
                  //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Get Public Groups

Since 2.6.0

JMessage#getAppkeyPublicGroups()

Request Parameter

Request Example

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

Chat room

Add chatroom related features since 2.5.0

Get Chatroom Pagination List under the appkey

JMessage#getAppkeyChatrooms()

Request Parameter

Request Example

   JIM.getAppkeyChatrooms({
                   'start' : 0
                 }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
                   //data.result.total 聊天室总数量
                   //data.result.start 本次查询 index 下标值
                   //data.result.count 本次查询返回列表大小
                   //data.result.rooms[].id 聊天室 id
                   //data.result.rooms[].name 聊天室名字
                   //data.result.rooms[].description 聊天室描述
                   //data.result.rooms[].appkey 聊天室所属 appkey
                   //data.result.rooms[].total_member_count 当前聊天室人数
                   //data.result.rooms[].max_member_count 聊天室最大容量
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Get Joined Chat Rooms

JMessage#getSelfChatrooms()

Request Parameter

N/A

Request Example

   JIM.getSelfChatrooms().onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
                   //data.chat_rooms[].id 聊天室 id
                   //data.chat_rooms[].name 聊天室名字
                   //data.chat_rooms[].description 聊天室描述
                   //data.chat_rooms[].appkey 聊天室所属 appkey
                   //data.chat_rooms[].total_member_count 当前聊天室人数
                   //data.chat_rooms[].max_member_count 聊天室最大容量
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Get Chat Room Details

JMessage#getChatroomInfo()

Request Parameter

Request Example

   JIM.getChatroomInfo({
                   'id' : '<id>'
                 }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
                   //data.info.id 聊天室 id
                   //data.info.name 聊天室名字
                   //data.info.description 聊天室描述
                   //data.info.appkey 聊天室所属 appkey
                   //data.info.total_member_count 当前聊天室人数
                   //data.info.max_member_count 聊天室最大容量
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Enter the Chat Room

JMessage#enterChatroom ()

Request Parameter

Request Example

   JIM.enterChatroom({
                   'id' : '<id>'
                 }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
                   //data.id 聊天室 id
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Leave the Chat Room

JMessage#exitChatroom ()

Request Parameter

Request Example

   JIM.exitChatroom({
                   'id' : '<id>'
                 }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
                   //data.id 聊天室 id
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Chat Room Sends Text Messages

JMessage#sendChatroomMsg()

Request Parameter

Request Example

   // 发送文本消息
   JIM.sendChatroomMsg({
                 'target_rid' : '<targetRid>',
                 'content' : '<textContent>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                  //data.code 返回码
                  //data.message 描述
               });

   // 转发文本消息
   JIM.sendChatroomMsg({
                 'target_rid' : '<targetRid>',
                 'msg_body' : {
                              'text' : '',
                            'extras' : 'json object'
                              }, // 可以直接从已有消息体里面获取msg_body
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                  //data.code 返回码
                  //data.message 描述
               });

Message Body

Details of message body

Chat Room Sends Picture Messages

JMessage#sendChatroomPic()

Request Parameter

Request Example

 // 发送消息
 JIM.sendChatroomPic({
            'target_rid' : '<targetRid>',
                 'image' : '<formData with image>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                  //同发送单聊文本
               });

  // 转发消息
  JIM.sendChatroomPic({
               'target_rid' : '<targetRid>',
                 'msg_body' : {
                             'media_id':'',
                          'media_crc32':'',
                                'width':'',
                               'height':'',
                               'format':'',
                                'fsize':'',
                              'extras' : 'json object'
                                } // 可以直接从已有消息体里面获取msg_body
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                  //同发送单聊文本
               });

Chat Room Sends File Messages

JMessage#sendChatroomFile()

Request Parameter

Request Example

  // 发送消息
  JIM.sendChatroomFile({
                 'target_rid' : '<targetRid>',
                 'file' : '<formData with file>',
                 'extras' : 'json object'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                   //同发送单聊文本
               });

  // 转发消息
  JIM.sendChatroomFile({
                 'target_rid' : '<targetRid>',
                 'msg_body' : {
                             'media_id':'',
                          'media_crc32':'',
                                 'hash':'',
                                'fname':'',
                                'fsize':'',
                              'extras' : 'json object'
                                } // 可以直接从已有消息体里面获取msg_body
               }).onSuccess(function(data , msg<可选>) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                  //同发送单聊文本
               });

Chat Room Sends Location Message

JMessage#sendChatroomLocation()

Request Parameter

Request Example

  // 发送消息
  JIM.sendChatroomLocation({
                'target_rid' : '<targetRid>',
                  'latitude' : '<latitude>',
                 'longitude' : '<longitude>',
                 'scale' : '<scale>',
                 'label' : '<address label>'
                 'extras' : 'json object'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                   //同发送单聊文本
               });

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

Chat Room Sends Custom Messages

JMessage#sendChatroomCustom()

Request Parameter

Request Example

   // 发送消息
   JIM.sendChatroomCustom({
              'target_rid' : '<targetRid>',
                 'custome' : '<json object>'
                 'appkey' : '<targetAppkey>'
               }).onSuccess(function(data , msg) {
                  //data.code 返回码
                  //data.message 描述
                  //data.room_id 目标聊天室 id
                  //data.msg_id 发送成功后的消息 id
                  //data.ctime_ms 消息生成时间,毫秒
               }).onFail(function(data) {
                  //同发送单聊文本
               });

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

Do-Not-Disturb Management

Get Do-Not-Disturb

JMessage#getNoDisturb()

Request Parameter

N/A

Request Example

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

Add User Do-Not-Disturb

JMessage#addSingleNoDisturb()

Request Parameter

Request Example

   JIM.addSingleNoDisturb({
          'target_name' : '<targetUserName>',
          'appkey' : '<targetAppkey>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Turn off User Do-Not-Disturb

JMessage#delSingleNoDisturb()

Request Parameter

Request Example

   JIM.delSingleNoDisturb({
          'target_name' : '<targetUserName>',
          'appkey' : '<targetAppkey>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Add Group Do-Not-Disturb

JMessage#addGroupNoDisturb()

Request Parameter

Request Example

   JIM.addGroupNoDisturb({
                     'gid' : '<targetGid>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Turn off Group Do-Not-Disturb

JMessage#delGroupNoDisturb()

Request Parameter

Request Example

   JIM.delGroupNoDisturb({
                     'gid' : '<targetGid>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

List of Group Blocking

JMessage#groupShieldList()

Request Parameter

N/A

Request Example

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

Add Group Blocking

JMessage#addGroupShield()

Request Parameter

Request Example

   JIM.addGroupShield({
                     'gid' : '<targetGid>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Close Group Blocking

JMessage#delGroupShield()

Request Parameter

Request Example

   JIM.delGroupShield({
                     'gid' : '<targetGid>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   //同上
               });

Add Global Do-Not-Disturb

JMessage#addGlobalNoDisturb()

Request Parameter

N/A

Request Example

   JIM.addGlobalNoDisturb().onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Turn off Global Do-Not-Disturb

JMessage#delGlobalNoDisturb()

Request Parameter

N/A

Request Example

   JIM.delGlobalNoDisturb().onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Blacklist Management

Get blacklist

JMessage#getBlacks()

Request Parameter

N/A

Request Example

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

Add Blacklists

JMessage#addSingleBlacks()

Request Parameter

Request Example

   JIM.addSingleBlacks({
          'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Remove Blacklists

JMessage#delSingleBlacks()

Request Parameter

Request Example\

   JIM.delSingleBlacks({
          'member_usernames' : [{'username':'name1'},{'username':'name2','appkey':'appkey2'}...]
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

Friends Related

Friends List

JMessage#getFriendList()

Request Parameter

N/A

Request Example

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

Add Friends

JMessage#addFriend()

Request Parameter

Request Example

   JIM.addFriend({
             'target_name' : '< username >' ,
                     'why' : '< why >',
                  'appkey' : '<appkey>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Agree Friends Request

Since 2.4.0

JMessage#acceptFriend()

Request Parameter

Request Example

   JIM.acceptFriend({
             'target_name' : '< username >' ,
                  'appkey' : '<appkey>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Reject Friends Request

Since 2.4.0

JMessage#declineFriend()

Request Parameter

Request Example

   JIM.declineFriend({
             'target_name' : '< username >' ,
                     'why' : '< why >',
                  'appkey' : '<appkey>'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Delete Friends

JMessage#delFriend()

Request Parameter

Request Example

   JIM.delFriend({
              'target_name' : '< username >' ,
              'appkey' : '< appkey >'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

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

   JIM.updateFriendMemo({
          'target_name' : '< username >' ,
            'memo_name' : '< memo_name >',
          'memo_others' : '< memo_others >',
               'appkey' : '< appkey >'
               }).onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
               }).onFail(function(data) {
                   // 同上
               });

Real-time Monitoring of Chat Messages

JMessage#onMsgReceive(fn)

Request Parameter

Array of returned messages

Example

JIM.onMsgReceive(function(data) {
   // data.messages[]
   // data.messages[].ctime_ms
   // data.messages[].msg_type 会话类型
   // data.messages[].msg_id
   // data.messages[].from_appey 单聊有效
   // data.messages[].from_username 单聊有效
   // data.messages[].from_gid 群聊有效
   // data.messages[].need_receipt
   // data.messages[].content
   // data.messages[].custom_notification.enabled
   // data.messages[].custom_notification.title
   // data.messages[].custom_notification.alert
   // data.messages[].custom_notification.at_prefix
});

Synchronization Monitoring of Offline Messages

JMessage#onSyncConversation(fn)

Request Parameter

Return Parameter

Example

JIM.onSyncConversation(function(data) {
   // data[]
   // data[].msg_type 会话类型
   // data[].from_appey 单聊有效
   // data[].from_username 单聊有效
   // data[].from_gid 群聊有效
   // data[].unread_msg_count 消息未读数
   // 消息已读回执状态，针对自己发的消息
   // data[].receipt_msgs[]
   // data[].receipt_msgs[].msg_id
   // data[].receipt_msgs[].unread_count
   // data[].receipt_msgs[].mtime
   // 消息列表
   // data[].msgs[]
   // data[].msgs[].msg_id
   // data[].msgs[].content
   // data[].msgs[].msg_type
   // data[].msgs[].ctime_ms
   // data[].msgs[].need_receipt
   // data[].msgs[].custom_notification.enabled
   // data[].msgs[].custom_notification.title
   // data[].msgs[].custom_notification.alert
   // data[].msgs[].custom_notification.at_prefix
});

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

Example

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

Business Event Monitoring

JMessage#onEventNotification(fn)

Request Parameter( Value based on the event)

Return Parameter\

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

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

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

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

Example of a friend inviting event: event_type = 5

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

});

Example of a friend responsing event: event_type = 5

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

Example of a friend deleting event: event_type = 6

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

Example of a friend updating event: event_type = 7

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

Example of a group creating event: event_type = 8

//群里所有人接收，即创建者接收该事件
JIM.onEventNotification(function(data) {
    //data.event_id 事件 id
    //data.event_type 事件类型
    //data.ctime_ms 事件生成时间
    //data.from_username 创建者 username
    //data.from_appkey 创建者 appkey
    //data.to_usernames 创建者
    //data.group_name 群名
    //data.media_id 群头像
    //data.gid 群 id
});

Example of a group exiting event: event_type = 9

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

Example of a group member adding event: event_type = 10

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

Example of a group member deleting event: event_type = 11

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

Example of a group information modifying event: event_type = 12

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

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

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

Example of a blacklist changing event: event_type = 38

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

Example of a group blocking change event: event_type =39

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

Example of a user information changing event: event_type = 40

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

Example of a message recalling event: event_type = 55

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

Example of a group applying event: event_type = 56

Since 2.5.0

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

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

Since 2.5.0

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

Example of approval rejected by administrator event: event_type = 58

Since 2.6.0

//群里所有管理员和群主
JIM.onEventNotification(function(data) {
    //data.event_id 事件 id
    //data.from_gid 群 id
    //data.group_name 群名
    //data.media_id 群头像
    //data.event_type 事件类型
    //data.ctime_ms 事件生成时间
    //data.from_appkey 群主所属 appkey
    //data.from_username 群主 username
    //data.to_usernames 被拒绝成员   
    //data.from_eventid 操作事件 id
});

Group user banned event: event_type = 65

Since 2.5.0

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

Group Administrator Change Event: event_type = 80

Since 2.6.0

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

Group owner handover event: event_type = 82

Since 2.6.0

//群所有用户接收该事件
JIM.onEventNotification(function(data) {
    //data.event_id 事件 id
    //data.from_gid 群 id
    //data.group_name 群名
    //data.media_id 群头像
    //data.event_type 事件类型
    //data.ctime_ms 事件生成时间
    //data.from_appkey 老群主 appkey
    //data.from_username 老群主 username
    //data.to_usernames 新群主   
});

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

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

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

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

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

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

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

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

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

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

Synchronization Monitoring of Business Event

JMessage#onSyncEvent(fn)

Request Parameter

Return Parameter (Same as business event monitoring)

Example

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

Real-time Monitoring of Message Reading Numbers Changing Event

Since 2.4.0

JMessage#onMsgReceiptChange(fn)

Request Parameter

Return Parameter

Message Unread Status Parameter

Example

JIM.onMsgReceiptChange(function(data) {
    // data.type
    // data.gid
    // data.appkey
    // data.username
    // data.receipt_msgs[].msg_id
    // data.receipt_msgs[].unread_count
});

Synchronization Monitoring of Message’s Reading Number Changing Event

Since 2.4.0

JMessage#onSyncMsgReceipt(fn)

Request Parameter

Return Parameter

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

Example

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

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

Since 2.4.0

JMessage#onMutiUnreadMsgUpdate(fn)

Request Parameter

Return Parameter

Example

JIM.onMutiUnreadMsgUpdate(function(data) {
    // data.type 会话类型
    // data.gid 群 id
    // data.appkey 所属 appkey
    // data.username 会话 username
});

Monitoring of Message Transparent Transmission

Since 2.4.0

JMessage#onTransMsgRec(fn)

Request Parameter

Return Parameter

Example

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

Chat Room Message Monitoring

JMessage#onRoomMsg(fn)

Since 2.5.0

Request Parameter

Array of returned messages

Example

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

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

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:

var fd = new FormData();

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

sendSinglePic({
            'target_username' : across_user,
            'appkey' : across_appkey,
            'image' : fd //构造好的 FormData
            }).onSuccess(function(data) {
                console.log('success:' + JSON.stringify(data))
            }).onFail(function(data) {
                 console.log('error:' + JSON.stringify(data))
           });

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