Web SDK 开发指南 V2

概述

极光 IM Web SDK 为 Web 应用提供一个 IM 系统开发框架, 屏蔽掉 IM 系统的复杂的细节, 对外提供较为简洁的 API 接口, 方便第三方应用快速集成 IM 功能。

版本说明

JMessage Web SDK V2 版本对 SDK 通讯协议进行重新封装与优化:

• 提供更方便的 API 调用方式: 使用 Promise 风格的 API，简化了接口调用方式，开发者可以更简单方便的集成 SDK。
• 更可靠的消息重试方案: 新的 SDK 优化了消息重试技术方案，当弱网络环境下，出现消息发送失败，SDK 会自动重试 5 次，并保证每次 API 调用都是幂等的，开发者无需担心因为消息重试导致重复发送的情况。
• 支持单页面多聊天实例: 新的 SDK 修改了实例化方式，开发者可以不需要在页面初始化的时候就初始化 JMessage。在需要聊天功能的时候再进行初始化即可，并且一个页面可以初始化多个通道，实现多账号登录。
  因为 V2 API 全面改造了 API，为了提供更好的用户体验，V2 API 不向下兼容，开发者需要根据 JMessage Web SDK 文档重新接入 SDK。

鉴权

开发者在执行初始化的时候，需要传入 auth_payload。 该数据结构由开发者服务端生成并传回浏览器，用于开发者授权此浏览器运行的 JMessage 初始化。开发者需确保能调用获取到此数据的皆为合法用户。

auth_payload的数据结构如下:

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

参数说明:

• appkey : 开发者在极光平台注册的 IM 应用 appkey
• random_str : 20-36 长度的随机字符串, 作为签名加 salt 使用
• timestamp : 当前时间戳，用于防止重放攻击，精确到毫秒
• signature : 签名，10 分钟后失效（只针对初始化操作，初始化成功则之后的操作跟签名无关）
  签名生成算法如下:

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

其中 secret 为开发者在极光平台注册的 IM 应用 masterSecret。签名生成示例:

signature = md5("appkey=25b693b31d2c2ad5f072ef0c&timestamp=1507791639926&random_str=022cd9fd995849b&key=bc2efab258f2019727a4f36l")

*生产环境签名的生成需要在开发者服务端生成，不然存在 masterSecret 暴露的风险

快速开始

访问极光官网获取最新的 Web SDK。 然后在页面中引入：

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

引入该 JS 后，就可以使用 Window 上的全局对象 JMessage。你可以通过以下方式创建 JMessage 示例:

var JIM = new JMessage();

如果你想开启 Debug 模式，则可以在实例化 JMessage 的时候传入参数：

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

API

API 使用 Promise 风格，无特殊说明所有的 API 请求都是异步的，并支持以下 4 种回调处理。

• 请求成功回调 onSuccess()
• 请求失败回调 onFail()
• 请求超时回调 onTimeout()
• 请求应答回调 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
});

初始化

JMessage#init()

漫游参数

Since 2.2.0 新增漫游参数，初始化时，可设置是否启用消息记录漫游。打开消息漫游之后，用户多个设备之间登录时，sdk 会自动同步当前登录用户的历史消息。

请求参数:

请求示例

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

断线监听

JMessage#onDisconnect(fn)

请求参数:

请求示例

  JIM.onDisconnect(function(){
  });

多端同时在线

SDK从2.4.0版本开始支持多端同时在线，具体规则见多端在线说明

注册登录相关

注册

Since 2.4.0 注册支持其他字段

JMessage#register()

请求参数:

请求示例

  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) {
            // 同上
        });

连接状态

JMessage#isConnect()

请求参数:

无

请求示例

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

初始化状态

JMessage#isInit()

请求参数:

无

请求示例

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

登录状态

JMessage#isLogin()

请求参数:

无

请求示例

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

登录

JMessage#login()

请求参数:

请求示例

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

登出

JMessage#loginOut()

请求参数:

无

请求示例

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

用户管理

获取用户信息

Since 2.4.0 支持 extras 字段

JMessage#getUserInfo()

请求参数:

请求示例

  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 描述
        });

更新个人信息

Since 2.4.0 支持 extras 字段

JMessage#updateSelfInfo()

请求参数:

请求示例

   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) {
                   //同上
               });

更新个人头像

JMessage#updateSelfAvatar()

请求参数:

请求示例

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

更新个人密码

JMessage#updateSelfPwd()

请求参数:

请求示例

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

消息管理

获取会话列表

Since 2.4.0 支持会话 extras 字段

JMessage#getConversation()

请求参数：

无

请求示例

   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 描述
               });

更新会话信息

Since 2.4.0

JMessage#updateConversation()

请求参数：

请求示例

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

获取会话未读数

Since 2.4.0

JMessage#getUnreadMsgCnt()

请求参数：

请求示例

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

重置会话未读数

Since 2.4.0

JMessage#resetUnreadCount()

请求参数：

请求示例

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

消息未读用户列表

Since 2.4.0

JMessage#msgUnreadList()

请求参数：

请求示例

   // 消息发送设置了需要回执的时候,可以查看消息的已读未读用户列表
   // 消息接收方收到需要回执的消息的时候,阅读后需要通过消息已读回执接口通知后台消息已读
   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 描述
                     });

单聊消息已读回执

Since 2.4.0

JMessage#addSingleReceiptReport()

请求参数：

请求示例

   // 接收方收到需要消息回执的消息，阅读后进行消息回执操作
   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){
                     })

群聊消息已读回执

Since 2.4.0

JMessage#addGroupReceiptReport()

请求参数：

请求示例

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

获取资源访问路径

JMessage#getResource ()

请求参数：

请求示例

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

消息撤回

JMessage#msgRetract ()

请求参数：

请求示例

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

发送单聊文本

JMessage#sendSingleMsg()

请求参数：

custom_notification：

请求示例

   // 发送消息
   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 描述
               });

消息体

消息体详情:

发送单聊图片

JMessage#sendSinglePic()

请求参数：

custom_notification：

请求示例

 // 发送消息
 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) {
                  //同发送单聊文本
               });

发送单聊文件

JMessage#sendSingleFile()

请求参数：

custom_notification：

请求示例

  // 发送消息
  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) {
                  //同发送单聊文本
               });

发送单聊位置

JMessage#sendSingleLocation()

请求参数：

custom_notification：

请求示例

  // 发送消息
  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) {
                   //同发送单聊文本
               });

发送单聊自定义消息

JMessage#sendSingleCustom()

请求参数：

custom_notification：

请求示例

   // 发送消息
   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) {
                  //同发送单聊文本
               });

发送群聊文本

JMessage#sendGroupMsg()

请求参数：

custom_notification：

请求示例

   // 发送消息
   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) {
                  //同发送单聊文本
               });

发送群聊图片

JMessage#sendGroupPic()

请求参数：

custom_notification：

请求示例

   // 发送消息
   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) {
                  //同发送单聊文本
               });

发送群聊文件

JMessage#sendGroupFile()

请求参数：

custom_notification：

请求示例

   // 发送消息
   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) {
                   //同发送单聊文本
               });

发送群聊位置

JMessage#sendGroupLocation()

请求参数：

custom_notification：

请求示例

   // 发送消息
   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) {
                   //同发送单聊文本
               });

发送群聊自定义消息

JMessage#sendGroupCustom()

请求参数：

custom_notification：

请求示例

   // 发送消息
   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) {
                   //同发送单聊文本
               });

单聊消息透传

Since 2.4.0

JMessage#transSingleMsg()

请求参数：

请求示例

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

群聊消息透传

Since 2.4.0

JMessage#transGroupMsg()

请求参数：

请求示例

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

群组管理

创建群组

Since 2.4.0 支持群头像

Since 2.5.0 支持公开群

JMessage#createGroup()

请求参数：

请求示例

   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 描述
               });

退出群组

JMessage#exitGroup()

请求参数：

请求示例

   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 描述
               });

增加群组成员

JMessage#addGroupMembers()

请求参数：

请求示例

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

删除群组成员

JMessage#delGroupMembers()

请求参数：

请求示例

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

获取群组列表

JMessage#getGroups()

Since 2.5.0 支持 flag 标记

请求参数：

无

请求示例

   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 描述
               });

获取群信息

JMessage#getGroupInfo()

Since 2.5.0 支持公开群

请求参数：

请求示例

   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_info.avatar 群头像
                  //data.group_info.group_type 公开群:2,私有群:0或者1
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

更新群信息

Since 2.4.0 支持群头像

JMessage#updateGroupInfo()

请求参数：

请求示例

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

获取群成员

JMessage#getGroupMembers()

请求参数：

请求示例

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：群主
                  //data.member_list[0].keep_silence 是否被禁言true|false
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

主动加群（公开群）

JMessage#joinGroup()

Since 2.5.0

请求参数：

请求示例

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

群主审批入群请求

JMessage#addGroupMemberResp()

Since 2.5.0

请求参数：

请求示例

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 描述
               });

添加群用户禁言

JMessage#addGroupMemSilence()

Since 2.5.0

请求参数：

请求示例

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 描述
               });

取消群用户禁言

JMessage#delGroupMemSilence()

Since 2.5.0

请求参数：

请求示例

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 描述
               });

聊天室

Since 2.5.0 加入聊天室相关功能

获取appkey下聊天室分页列表

JMessage#getAppkeyChatrooms()

请求参数：

请求示例

   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[].ctime 聊天室创建时间
                   //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 描述
               });

获取已加入的聊天室

JMessage#getSelfChatrooms()

请求参数：

无

请求示例

   JIM.getSelfChatrooms().onSuccess(function(data) {
                   //data.code 返回码
                   //data.message 描述
                   //data.chat_rooms[].id 聊天室 id
                   //data.chat_rooms[].name 聊天室名字
                   //data.chat_rooms[].ctime 聊天室创建时间
                   //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 描述
               });

获取聊天室详情

JMessage#getChatroomInfo()

请求参数：

请求示例

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

进入聊天室

JMessage#enterChatroom ()

请求参数：

请求示例

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

退出聊天室

JMessage#exitChatroom ()

请求参数：

请求示例

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

聊天室发送文本消息

JMessage#sendChatroomMsg()

请求参数：

请求示例

   // 发送文本消息
   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 描述
               });

消息体

消息体详情:

聊天室发送图片消息

JMessage#sendChatroomPic()

请求参数：