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 SDK v2.2.0 新增漫游参数,初始化时,可设置是否启用消息记录漫游。 打开消息漫游之后,用户多个设备之间登录时,sdk 会自动同步当前登录用户的历史消息。

请求参数:

KEY REQUIRE DESCRIPTION
appkey TRUE 开发者在极光平台注册的IM应用 appkey
random_str TRUE 随机字符串
timestamp TRUE 当初时间戳
signature TRUE 签名
flag FALSE 是否启用消息记录漫游,默认 0 否,1 是

请求示例

  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)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 断线处理函数

请求示例

  JIM.onDisconnect(function(){
  });

注册登录相关

注册

JMessage#register()

请求参数:

KEY REQUIRE DESCRIPTION
username TRUE 用户名
password TRUE 密码
is_md5 FALSE 密码是否是 MD5 密码,默认否
nickname FALSE 昵称
birthday FALSE 生日
signature FALSE 签名
gender FALSE 性别,0 未知, 1 男,2 女
region FALSE 地区
address FALSE 地址
extras FALSE 自定义 json 格式字段
media_id FALSE 头像 id

请求示例

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

请求参数:

KEY REQUIRE DESCRIPTION
username TRUE 用户名
password TRUE 密码
is_md5 FALSE 密码是否是 MD5 密码,默认否

请求示例

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

登出

JMessage#loginOut()

请求参数:

请求示例

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

用户管理

获取用户信息

JMessage#getUserInfo()

请求参数:

KEY REQUIRE DESCRIPTION
username TRUE 用户名
appkey FALSE 跨应用查询时必填,目标应用的 appkey

请求示例

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

更新个人信息

JMessage#updateSelfInfo()

请求参数:

KEY REQUIRE DESCRIPTION
nickname FALSE 昵称
birthday FALSE 生日
signature FALSE 签名
gender FALSE 性别,0 未知, 1 男,2 女
region FALSE 地区
address FALSE 地址
extras FALSE 自定义 json 格式字段

请求示例

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

请求参数:

KEY REQUIRE DESCRIPTION
avatar TRUE 头像头像图片的 DataForm 对象

请求示例

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

更新个人密码

JMessage#updateSelfPwd()

请求参数:

KEY REQUIRE DESCRIPTION
old_pwd TRUE 旧的密码
new_pwd TRUE 新的密码
is_md5 FALSE 密码是否经过 MD5

请求示例

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

消息管理

获取会话列表

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

更新会话信息

JMessage#updateConversation()

请求参数:

KEY REQUIRE DESCRIPTION
gid FALSE 群 id,群聊有效
username FALSE 用户username,单聊有效
appkey FALSE 用户appkey,单聊有效
extras TRUE json object, 老的数据会被覆盖

请求示例

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

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

获取会话未读数

JMessage#getUnreadMsgCnt()

请求参数:

KEY REQUIRE DESCRIPTION
gid FALSE 群 id,群聊会话有效
username FALSE 用户username,单聊会话有效
appkey FALSE 用户appkey,单聊会话有效

请求示例

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

重置会话未读数

JMessage#resetUnreadCount()

请求参数:

KEY REQUIRE DESCRIPTION
gid FALSE 群 id,群聊会话有效
username FALSE 用户username,单聊会话有效
appkey FALSE 用户appkey,单聊会话有效

请求示例

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

消息未读用户列表

JMessage#msgUnreadList()

请求参数:

KEY REQUIRE DESCRIPTION
msg_id TRUE 消息 id

请求示例

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

单聊消息已读回执

JMessage#addSingleReceiptReport()

请求参数:

KEY REQUIRE DESCRIPTION
username TRUE 用户 name
msg_ids TRUE 已经阅读过的消息的 id 列表,数组类型
appkey FALSE 默认本应用 appkey

请求示例

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

                     })

群聊消息已读回执

JMessage#addGroupReceiptReport()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群 ID
msg_ids TRUE 已经阅读过的消息的 id 列表,数组类型

请求示例

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

请求参数:

KEY REQUIRE DESCRIPTION
media_id TRUE media_id 资源 id

请求示例

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

消息撤回

JMessage#msgRetract ()

请求参数:

KEY REQUIRE DESCRIPTION
msg_id TRUE 消息id

请求示例

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

发送单聊文本

JMessage#sendSingleMsg()

请求参数:

KEY REQUIRE DESCRIPTION
target_username TRUE 接收消息者 username
content 与 msg_body 参数二选一 消息文本
msg_body 与 content 参数二选一 消息的 msg_body,用来实现消息转发功能
target_nickname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
appkey FALSE 跨应用查询时必填,目标应用的 appkey
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notification FALSE 通知栏参数,见下表
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认 FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容

请求示例

   // 发送消息
   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()

请求参数:

KEY REQUIRE DESCRIPTION
target_username TRUE 接收消息者 username
image 与 msg_body 参数二选一 图片的 DataForm 对象
msg_body 与 image 参数二选一 消息的 msg_body,用来实现消息转发功能
target_nickname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
appkey FALSE 跨应用查询时必填,目标应用的 appkey
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notification FALSE 通知栏参数,见下表
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认 FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容

请求示例

 // 发送消息
 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()

请求参数:

KEY REQUIRE DESCRIPTION
target_username TRUE 接收消息者 username
file 与 msg_body 参数二选一 文件的 DataForm 对象
msg_body 与 file 参数二选一 消息的 msg_body,用来实现消息转发
target_nickname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
appkey FALSE 跨应用查询时必填,目标应用的 appkey
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notification FALSE 通知栏参数,见下表
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认 FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容

请求示例

  // 发送消息
  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()

请求参数:

KEY REQUIRE DESCRIPTION
target_username TRUE 接收消息者 username
latitude 与 msg_body 二选一 维度
longitude 与 msg_body 二选一 精度
scale 与 msg_body 二选一 地图缩放级别
label 与 msg_body 二选一 地址
msg_body 与位置相关参数二选一 消息的 msg_body,用来实现消息转发功能
target_nickname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
appkey FALSE 跨应用查询时必填,目标应用的 appkey
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notification FALSE 通知栏参数,见下表
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认 FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容

请求示例

  // 发送消息
  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()

请求参数:

KEY REQUIRE DESCRIPTION
target_username TRUE 接收消息者 username
custom TRUE 自定义 json object 消息
msg_body 与 custom 二选一 消息的 msg_body,用来实现消息转发功能
target_nickname FALSE 接收者的展示名
appkey FALSE 跨应用查询时必填,目标应用的 appkey
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notification FALSE 通知栏参数,见下表
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认 FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容

请求示例

   // 发送消息
   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()

请求参数:

KEY REQUIRE DESCRIPTION
target_gid TRUE 群组 id
content 与 msg_body 参数二选一 消息文本
msg_body 与 content 参数二选一 消息的 msg_body,用来实现消息转发
target_gname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
at_list FALSE @用户列表:[{'username': 'name1', 'appkey': '跨应用必填,默认不填表示本应用'}],@ALL 直接空数组:[]
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notification FALSE 通知栏参数,见下表
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容
at_prefix FALSE 被@目标的通知内容前缀

请求示例

   // 发送消息
   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()

请求参数:

KEY REQUIRE DESCRIPTION
target_gid TRUE 群组 id
image 与 msg_body 参数二选一 图片的 DataForm 对象
msg_body 与 image 参数二选一 消息的 msg_body,用来实现消息转发
target_gname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容
at_prefix FALSE 被@目标的通知内容前缀

请求示例

   // 发送消息
   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()

请求参数:

KEY REQUIRE DESCRIPTION
target_gid TRUE 群组 id
file 与 msg_body 参数二选一 文件的 DataForm 对象
msg_body 与 file 参数二选一 消息的 msg_body,用来实现消息转发
target_gname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容
at_prefix FALSE 被@目标的通知内容前缀

请求示例

   // 发送消息
   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()

请求参数:

KEY REQUIRE DESCRIPTION
target_gid TRUE 群组 id
latitude 与 msg_body 二选一 维度
longitude 与 msg_body 二选一 精度
scale 与 msg_body 二选一 地图缩放级别
label 与 msg_body 二选一 地址
msg_body 与位置相关参数二选一 消息的 msg_body,用来实现消息转发
target_gname FALSE 接收者的展示名
extras FALSE 附加字段,字典类型
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容
at_prefix FALSE 被@目标的通知内容前缀

请求示例

   // 发送消息
   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()

请求参数:

KEY REQUIRE DESCRIPTION
target_gid TRUE 群组 id
custom TRUE 自定义 json object 消息
msg_body 与 custom 二选一 消息的 msg_body,用来实现消息转发
target_gname FALSE 接收者的展示名
no_offline FALSE 消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notification FALSE 状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receipt FALSE 是否需要已读回执,需要:true 不需要:false

custom_notification:

KEY REQUIRE DESCRIPTION
enabled TRUE 是否启用自定义消息通知栏 默认FALSE
title FALSE 通知栏标题
alert FALSE 通知栏内容
at_prefix FALSE 被@目标的通知内容前缀

请求示例

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

单聊消息透传

JMessage#transSingleMsg()

请求参数:

KEY REQUIRE DESCRIPTION
target_username TRUE 目标用户
cmd TRUE 透传信息 string 类型
target_appkey FALSE 目标用户所属 appkey

请求示例

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

群聊消息透传

JMessage#transGroupMsg()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 目标群 id
cmd TRUE 透传信息 string 类型

请求示例

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

群组管理

创建群组

JMessage#createGroup()

请求参数:

KEY REQUIRE DESCRIPTION
group_name TRUE 群组名
group_description FALSE 群组描述
avatar FALSE 群头像图片的 DataForm 对象

请求示例

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

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组id

请求示例

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

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组id
member_usernames TRUE 增加用户名列表,示例:[{'username':'name1', 'appkey': '跨应用必填,默认不填表示本应用'},...]

请求示例

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

删除群组成员

JMessage#delGroupMembers()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组id
member_usernames TRUE 增加用户名列表,示例:[{'username':'name1', 'appkey': '跨应用必填,默认不填表示本应用'},...]

请求示例

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

获取群组列表

JMessage#getGroups()

请求参数:

请求示例

   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 群头像
               }).onFail(function(data) {
                  //data.code 返回码
                  //data.message 描述
               });

获取群信息

JMessage#getGroupInfo()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组 id

请求示例

   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 群头像
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

更新群信息

JMessage#updateGroupInfo()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群 id
group_name FALSE 群组名,最少一个属性必填,非空
group_description FALSE 群组描述,最少一个属性必填,非空
avatar FALSE 群头像图片的 DataForm 对象,最少一个属性必填

请求示例

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

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群id

请求示例


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:群主
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

免打扰管理

获取免打扰

JMessage#getNoDisturb()

请求参数:

请求示例

   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[] 免打扰群组列表,比如示例
                   //data.no_disturb.groups[0].gid 群组 id
                   //data.no_disturb.groups[0].name 群名字
                   //data.no_disturb.groups[0].appkey 群所属 appkey
                   //data.no_disturb.groups[0].desc 群描述
               }).onFail(function(data) {
                   //data.code 返回码
                   //data.message 描述
               });

添加用户免打扰

JMessage#addSingleNoDisturb()

请求参数:

KEY REQUIRE DESCRIPTION
target_name TRUE username
appkey FALSE 跨应用必填,默认不填表示本应用

请求示例

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

关闭用户免打扰

JMessage#delSingleNoDisturb()

请求参数:

KEY REQUIRE DESCRIPTION
target_name TRUE username
appkey FALSE 跨应用必填,默认不填表示本应用

请求示例

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

添加群组免打扰

JMessage#addGroupNoDisturb()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组id

请求示例

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

关闭群组免打扰

JMessage#delGroupNoDisturb()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组id

请求示例

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

群屏蔽列表

JMessage#groupShieldList()

请求参数:

请求示例

   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 最近一次群信息修改时间 
               }).onFail(function(data) {
                   // 同上
               });

添加群屏蔽

JMessage#addGroupShield()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组id

请求示例

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

关闭群屏蔽

JMessage#delGroupShield()

请求参数:

KEY REQUIRE DESCRIPTION
gid TRUE 群组id

请求示例

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

添加全局免打扰

JMessage#addGlobalNoDisturb()

请求参数:

请求示例

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

关闭全局免打扰

JMessage#delGlobalNoDisturb()

请求参数:

请求示例

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

黑名单管理

获取黑名单

JMessage#getBlacks()

请求参数:

请求示例

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

添加黑名单

JMessage#addSingleBlacks()

请求参数:

KEY REQUIRE DESCRIPTION
member_usernames TRUE 用户列表示例:[{'username': 'name1', 'appkey': '跨应用必填,默认不填表示本应用'}]

请求示例

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

删除黑名单

JMessage#delSingleBlacks()

请求参数:

KEY REQUIRE DESCRIPTION
member_usernames TRUE 用户列表示例:[{'username': 'name1', 'appkey': '跨应用必填,默认不填表示本应用'}]

请求示例

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

好友相关

好友列表

JMessage#getFriendList()

请求参数:

请求示例

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

添加好友

JMessage#addFriend()

请求参数:

KEY REQUIRE DESCRIPTION
target_name TRUE 目标 username
why TRUE 邀请说明
appkey FALSE 跨应用查询时必填,目标应用的 appkey

添加好友请求示例

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

同意好友请求

JMessage#acceptFriend()

请求参数:

KEY REQUIRE DESCRIPTION
target_name TRUE 目标 username
appkey FALSE 跨应用查询时必填,目标应用的 appkey

添加好友请求示例

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

拒绝好友请求

JMessage#declineFriend()

请求参数:

KEY REQUIRE DESCRIPTION
target_name TRUE 目标 username
why FALSE 拒绝理由
appkey FALSE 跨应用查询时必填,目标应用的 appkey

添加好友请求示例

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

删除好友

JMessage#delFriend()

请求参数:

KEY REQUIRE DESCRIPTION
target_name TRUE 目标 username
appkey FALSE 跨应用查询时必填,目标应用的 appkey

请求示例

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

更新好友备注

JMessage#updateFriendMemo()

请求参数:

KEY REQUIRE DESCRIPTION
target_name TRUE 目标 username
memo_name TRUE 名称备注
memo_others FALSE 其他备注
appkey FALSE 跨应用查询时必填,目标应用的 appkey

请求示例

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

聊天消息实时监听

JMessage#onMsgReceive(fn)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 消息接收处理函数

返回消息数组

KEY DESCRIPTION
ctime_ms 消息生成时间,毫秒
msg_type 消息类型 3-single, 4-group
from_appkey 消息来源 appkey 单聊有效
from_username 消息来源 username 单聊有效
from_gid 消息来源群id 群聊有效
msg_id 消息 ID
need_receipt 是否需要回执
custom_notification.enabled 是否启用自定义消息通知栏
custom_notification.title 通知栏标题
custom_notification.alert 通知栏内容
custom_notification.at_prefix 被@目标的通知内容前缀
content 消息体

使用示例

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

离线消息同步监听

JMessage#onSyncConversation(fn)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 消息接收处理函数

返回参数

KEY DESCRIPTION
messages [{'msg_type':'会话类型','from_appkey':'目标所属appkey','from_username':'目标username','from_gid':'目标群id','unread_msg_count':'消息未读数','receipt_msgs':[{'msg_id':'消息 id','unread_count':'未读数','mtime':'更新时时间,毫秒'},...],'msgs':[{参考聊天消息实时监听},...]},...]

使用示例

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

用户信息变更监听

JMessage#onUserInfUpdate(fn)

监听对象

监听对象包括好友、群组成员、会话列表中的单聊

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 处理函数

返回参数

KEY DESCRIPTION
appkey 变更方的appkey
username 变更方username
mtime 变更时间(秒)

使用示例

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

业务事件监听

JMessage#onEventNotification(fn)

请求参数(根据具体事件取值):

KEY REQUIRE DESCRIPTION
fn TRUE 事件接收处理函数

返回参数

KEY DESCRIPTION
event_id 事件 id
event_type 事件类型,开发者根据对应的事件类型取相关字段,见下面示例
gid 关系类型
from_username 事件发起者 username
from_appkey 事件发起者 appkey
to_usernames 事件当事人 [{"username":"","appkey":"","nickname":""},...]
ctime_ms 事件生成时间,精确到毫秒
extra 标识制字段
return_code 用于好友邀请应答事件
description 描述
msg_ids 消息 id 列表
from_gid 群 gid
to_groups 目标群组,格式 [{'gid':' ','name':' '},...]
new_owner 新群主,格式 {'appkey':' ','username':' '}
group_name 群名
type 0:单聊,1:群聊
group_name 群名

同时登录,被迫下线示例:event_type = 1

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

密码被修改,被迫下线示例:event_type = 2

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

好友邀请事件示例: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-来自被邀请方,即好友邀请的应答事件

});

好友应答事件示例: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 原因
});

删除好友事件示例: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
});

好友更新事件示例:event_type = 7

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

创建群组事件示例: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
});

退出群组事件示例:event_type = 9

//群里所有人接收,包括退群者
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
    //data.media_id 群头像
    //data.group_name 群名
    //data.new_owner 如果是群主退出,这个表示新群主
});

添加群组成员事件示例: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
});

删除群组成员事件示例: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 如果是群主被删除,这个表示新群主
});

修改群信息事件示例: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
});

免打扰变更事件示例:event_type = 37

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

黑名单变更事件示例:event_type = 38

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

群屏蔽变更事件示例:event_type =39

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

用户信息变更事件示例:event_type = 40

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

消息被撤回事件示例: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 群聊有效
});

多端在线好友变更事件示例: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':''}
});

多端在线黑名单变更事件示例:event_type =101

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

多端在线免打扰变更事件示例: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 有效
});

多端在线群屏蔽变更事件示例:event_type =103

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

多端在线消息已读回执变更事件示例: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 表示其他端对消息列表里面的消息已经已读了
});

业务事件同步监听

JMessage#onSyncEvent(fn)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 事件接收处理函数

返回参数 同业务事件监听

使用示例

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

消息已读数变更事件实时监听

JMessage#onMsgReceiptChange(fn)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 事件接收处理函数

返回参数

KEY DESCRIPTION
gid 群 ID,群聊有效
appkey 所属 appkey,单聊有效
username 用户 name,单聊有效
type 会话类型 3:单聊 4:群聊
receipt_msgs 消息未读状态列表,如下:

消息未读状态参数

KEY DESCRIPTION
msg_id 消息 id
unread_count 消息未读数,跟之前的对比,取小的作为最新消息未读数

使用示例

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

消息已读数变更事件同步监听

JMessage#onSyncMsgReceipt(fn)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 事件接收处理函数

返回参数

同已读数变更事件实时监听

使用示例

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

会话未读数变更监听(多端在线)

JMessage#onMutiUnreadMsgUpdate(fn)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 事件接收处理函数

返回参数

KEY DESCRIPTION
type 3 单聊 ,4 群聊
gid 群 id ,type=4 有效
appkey 目标用户 appkey,type=3 有效
username 目标用户 username,type=3 有效

使用示例

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

消息透传监听

JMessage#onTransMsgRec(fn)

请求参数:

KEY REQUIRE DESCRIPTION
fn TRUE 监听处理函数

返回参数

KEY DESCRIPTION
type 3 单聊消息透传 ,4 群聊消息透传
gid 群 id ,type=4 有效
from_appkey 用户 appkey,type=3 有效
from_username 用户 username,type=3 有效
cmd 透传信息

使用示例

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

高级应用

发送跨应用消息

跨应用是指相同账号下不同 appkey 之间的用户进行操作,默认在没指定目标 appkey 的情况下目标 appkey 就是当前登录用户所使用的 appkey,如果需要跨应用操作则在接口参数上指定具体的目标 appkey。

以2.1发送单聊为例:

JMessage#sendSingleMsg()

请求参数:

KEY REQUIRE DESCRIPTION
target_username TRUE 接收消息者 username
target_nickname TRUE 接收消息者 nickname
content TRUE 消息文本
extras FALSE 附加字段,字典类型
appkey FALSE 跨应用查询时必填,目标应用的 appkey
其中 appkey 为目标 appkey,其他接口类似

发送图片或文件

SDK 支持单图片,单文件发送。发送文件和图片接口需要接收一个类型为 FormData 参数值,该参数值包含了用户需要发送的文件信息。

构造FormData示例:

var fd = new FormData();

fd.append(fileName, file);

完成构造 FormData 后 将其作为参数传入对用的接口,以发送单聊图片为例子:

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

其他发送文件,图片接口类似

发送和接收 Emoij 表情

Emoji 表情就是一种在 Unicode 位于\u1F601-\u1F64F区段的字符。 JMessage的消息内容都是使用utf8mb4编码,向下兼容 UTF8。 只要正确输入 Emoij 字符都可以使用 JMessage 文本消息 API 进行发送。如果用户需要转存聊天消息,请先确保数据库支持 utf8mb4 编码。 开发者可以使用第三方开源的 Web Emoij 解决方案,如coocy/emoji,iamcal/js-emoji来在网页上显示Emoij表情。

错误码定义

参考文档:IM Web SDK 错误码列表


Copyright 2011-2017, jiguang.cn, All Rights Reserved.
粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

Documentation built with MkDocs.