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的数据结构如下:

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

参数说明:

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

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

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

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

快速开始

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

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

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

  1. var JIM = new JMessage();

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

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

API

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

  • 请求成功回调 onSuccess()
  • 请求失败回调 onFail()
  • 请求超时回调 onTimeout()
  • 请求应答回调 onAck()
    比如你发送一条消息,你可以通过以下方式按需监听你感兴趣的事件回调:
  1. JIM.sendSingleMsg({
  2. 'target_username' : 'xiezefan',
  3. 'content' : 'Hi, JiGuang '
  4. }).onSuccess(function(data) {
  5. // do something
  6. }).onFail(function(data) {
  7. // do something
  8. }).onTimeout(function(data) {
  9. if (data.response_timeout) {
  10. // do something when response timeout
  11. } else {
  12. // do something when request timeout
  13. }
  14. }).onAck(function(data) {
  15. // do something
  16. });

初始化

JMessage#init()

漫游参数

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

请求参数:

KEYREQUIREDESCRIPTION
appkeyTRUE开发者在极光平台注册的IM应用 appkey
random_strTRUE随机字符串
timestampTRUE当初时间戳
signatureTRUE签名
flagFALSE是否启用消息记录漫游,默认 0 否,1 是

请求示例

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

断线监听

JMessage#onDisconnect(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE断线处理函数

请求示例

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

多端同时在线

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

注册登录相关

注册

Since 2.4.0 注册支持其他字段

JMessage#register()

请求参数:

KEYREQUIREDESCRIPTION
usernameTRUE用户名
passwordTRUE密码
is_md5FALSE密码是否是 MD5 密码,默认否
nicknameFALSE昵称
birthdayFALSE生日
signatureFALSE签名
genderFALSE性别,0 未知, 1 男,2 女
regionFALSE地区
addressFALSE地址
extrasFALSE自定义 json 格式字段
media_idFALSE头像 id

请求示例

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

连接状态

JMessage#isConnect()

请求参数:

请求示例

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

初始化状态

JMessage#isInit()

请求参数:

请求示例

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

登录状态

JMessage#isLogin()

请求参数:

请求示例

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

登录

JMessage#login()

请求参数:

KEYREQUIREDESCRIPTION
usernameTRUE用户名
passwordTRUE密码
is_md5FALSE密码是否是 MD5 密码,默认否

请求示例

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

登出

JMessage#loginOut()

请求参数:

请求示例

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

用户管理

获取用户信息

Since 2.4.0 支持 extras 字段

JMessage#getUserInfo()

请求参数:

KEYREQUIREDESCRIPTION
usernameTRUE用户名
appkeyFALSE跨应用查询时必填,目标应用的 appkey

请求示例

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

更新个人信息

Since 2.4.0 支持 extras 字段

JMessage#updateSelfInfo()

请求参数:

KEYREQUIREDESCRIPTION
nicknameFALSE昵称
birthdayFALSE生日
signatureFALSE签名
genderFALSE性别,0 未知, 1 男,2 女
regionFALSE地区
addressFALSE地址
extrasFALSE自定义 json 格式字段

请求示例

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

更新个人头像

JMessage#updateSelfAvatar()

请求参数:

KEYREQUIREDESCRIPTION
avatarTRUE头像头像图片的 DataForm 对象

请求示例

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

更新个人密码

JMessage#updateSelfPwd()

请求参数:

KEYREQUIREDESCRIPTION
old_pwdTRUE旧的密码
new_pwdTRUE新的密码
is_md5FALSE密码是否经过 MD5

请求示例

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

消息管理

获取会话列表

Since 2.4.0 支持会话 extras 字段

JMessage#getConversation()

请求参数:

请求示例

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

更新会话信息

Since 2.4.0

JMessage#updateConversation()

请求参数:

KEYREQUIREDESCRIPTION
gidFALSE群 id,群聊有效
usernameFALSE用户username,单聊有效
appkeyFALSE用户appkey,单聊有效
extrasTRUEjson object, 老的数据会被覆盖

请求示例

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

获取会话未读数

Since 2.4.0

JMessage#getUnreadMsgCnt()

请求参数:

KEYREQUIREDESCRIPTION
gidFALSE群 id,群聊会话有效
usernameFALSE用户username,单聊会话有效
appkeyFALSE用户appkey,单聊会话有效

请求示例

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

重置会话未读数

Since 2.4.0

JMessage#resetUnreadCount()

请求参数:

KEYREQUIREDESCRIPTION
gidFALSE群 id,群聊会话有效
usernameFALSE用户username,单聊会话有效
appkeyFALSE用户appkey,单聊会话有效

请求示例

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

消息未读用户列表

Since 2.4.0

JMessage#msgUnreadList()

请求参数:

KEYREQUIREDESCRIPTION
msg_idTRUE消息 id

请求示例

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

单聊消息已读回执

Since 2.4.0

JMessage#addSingleReceiptReport()

请求参数:

KEYREQUIREDESCRIPTION
usernameTRUE用户 name
msg_idsTRUE已经阅读过的消息的 id 列表,数组类型
appkeyFALSE默认本应用 appkey

请求示例

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

群聊消息已读回执

Since 2.4.0

JMessage#addGroupReceiptReport()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群 ID
msg_idsTRUE已经阅读过的消息的 id 列表,数组类型

请求示例

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

获取资源访问路径

JMessage#getResource ()

请求参数:

KEYREQUIREDESCRIPTION
media_idTRUEmedia_id 资源 id

请求示例

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

消息撤回

JMessage#msgRetract ()

请求参数:

KEYREQUIREDESCRIPTION
msg_idTRUE消息id

请求示例

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

发送单聊文本

JMessage#sendSingleMsg()

请求参数:

KEYREQUIREDESCRIPTION
target_usernameTRUE接收消息者 username
content与 msg_body 参数二选一消息文本
msg_body与 content 参数二选一消息的 msg_body,用来实现消息转发功能
target_nicknameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
appkeyFALSE跨应用查询时必填,目标应用的 appkey
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notificationFALSE通知栏参数,见下表
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认 FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容

请求示例

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

消息体

消息体详情:

发送单聊图片

JMessage#sendSinglePic()

请求参数:

KEYREQUIREDESCRIPTION
target_usernameTRUE接收消息者 username
image与 msg_body 参数二选一图片的 DataForm 对象
msg_body与 image 参数二选一消息的 msg_body,用来实现消息转发功能
target_nicknameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
appkeyFALSE跨应用查询时必填,目标应用的 appkey
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notificationFALSE通知栏参数,见下表
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认 FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容

请求示例

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

发送单聊文件

JMessage#sendSingleFile()

请求参数:

KEYREQUIREDESCRIPTION
target_usernameTRUE接收消息者 username
file与 msg_body 参数二选一文件的 DataForm 对象
msg_body与 file 参数二选一消息的 msg_body,用来实现消息转发
target_nicknameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
appkeyFALSE跨应用查询时必填,目标应用的 appkey
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notificationFALSE通知栏参数,见下表
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认 FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容

请求示例

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

发送单聊位置

JMessage#sendSingleLocation()

请求参数:

KEYREQUIREDESCRIPTION
target_usernameTRUE接收消息者 username
latitude与 msg_body 二选一纬度
longitude与 msg_body 二选一经度
scale与 msg_body 二选一地图缩放级别
label与 msg_body 二选一地址
msg_body与位置相关参数二选一消息的 msg_body,用来实现消息转发功能
target_nicknameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
appkeyFALSE跨应用查询时必填,目标应用的 appkey
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notificationFALSE通知栏参数,见下表
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认 FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容

请求示例

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

发送单聊自定义消息

JMessage#sendSingleCustom()

请求参数:

KEYREQUIREDESCRIPTION
target_usernameTRUE接收消息者 username
customTRUE自定义 json object 消息
msg_body与 custom 二选一消息的 msg_body,用来实现消息转发功能
target_nicknameFALSE接收者的展示名
appkeyFALSE跨应用查询时必填,目标应用的 appkey
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notificationFALSE通知栏参数,见下表
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认 FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容

请求示例

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

发送群聊文本

JMessage#sendGroupMsg()

请求参数:

KEYREQUIREDESCRIPTION
target_gidTRUE群组 id
content与 msg_body 参数二选一消息文本
msg_body与 content 参数二选一消息的 msg_body,用来实现消息转发
target_gnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
at_listFALSE@用户列表:[{'username': 'name1', 'appkey': '跨应用必填,默认不填表示本应用'}],@ALL 直接空数组:[]
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
custom_notificationFALSE通知栏参数,见下表
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容
at_prefixFALSE被@目标的通知内容前缀

请求示例

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

发送群聊图片

JMessage#sendGroupPic()

请求参数:

KEYREQUIREDESCRIPTION
target_gidTRUE群组 id
image与 msg_body 参数二选一图片的 DataForm 对象
msg_body与 image 参数二选一消息的 msg_body,用来实现消息转发
target_gnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容
at_prefixFALSE被@目标的通知内容前缀

请求示例

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

发送群聊文件

JMessage#sendGroupFile()

请求参数:

KEYREQUIREDESCRIPTION
target_gidTRUE群组 id
file与 msg_body 参数二选一文件的 DataForm 对象
msg_body与 file 参数二选一消息的 msg_body,用来实现消息转发
target_gnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容
at_prefixFALSE被@目标的通知内容前缀

请求示例

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

发送群聊位置

JMessage#sendGroupLocation()

请求参数:

KEYREQUIREDESCRIPTION
target_gidTRUE群组 id
latitude与 msg_body 二选一纬度
longitude与 msg_body 二选一经度
scale与 msg_body 二选一地图缩放级别
label与 msg_body 二选一地址
msg_body与位置相关参数二选一消息的 msg_body,用来实现消息转发
target_gnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容
at_prefixFALSE被@目标的通知内容前缀

请求示例

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

发送群聊自定义消息

JMessage#sendGroupCustom()

请求参数:

KEYREQUIREDESCRIPTION
target_gidTRUE群组 id
customTRUE自定义 json object 消息
msg_body与 custom 二选一消息的 msg_body,用来实现消息转发
target_gnameFALSE接收者的展示名
no_offlineFALSE消息离线控制标志,false,默认值,保存离线消息;true,不保存离线消息
no_notificationFALSE状态栏显示消息标志,false,默认值,状态栏显示消息;true,状态栏不显示消息
need_receiptFALSE是否需要已读回执,需要:true 不需要:false

custom_notification:

KEYREQUIREDESCRIPTION
enabledTRUE是否启用自定义消息通知栏 默认FALSE
titleFALSE通知栏标题
alertFALSE通知栏内容
at_prefixFALSE被@目标的通知内容前缀

请求示例

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

单聊消息透传

Since 2.4.0

JMessage#transSingleMsg()

请求参数:

KEYREQUIREDESCRIPTION
target_usernameTRUE目标用户
cmdTRUE透传信息 string 类型
target_appkeyFALSE目标用户所属 appkey

请求示例

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

群聊消息透传

Since 2.4.0

JMessage#transGroupMsg()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE目标群 id
cmdTRUE透传信息 string 类型

请求示例

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

群组管理

创建群组

Since 2.4.0 支持群头像

Since 2.5.0 支持公开群

JMessage#createGroup()

请求参数:

KEYREQUIREDESCRIPTION
group_nameTRUE群组名
group_descriptionFALSE群组描述
avatarFALSE群头像图片的 DataForm 对象
is_limitFALSE是否是公开群,默认 false

请求示例

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

退出群组

JMessage#exitGroup()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组id

请求示例

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

增加群组成员

JMessage#addGroupMembers()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组id
member_usernamesTRUE增加用户名列表,示例:[{'username':'name1', 'appkey': '跨应用必填,默认不填表示本应用'},…]

请求示例

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

删除群组成员

JMessage#delGroupMembers()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组id
member_usernamesTRUE增加用户名列表,示例:[{'username':'name1', 'appkey': '跨应用必填,默认不填表示本应用'},…]

请求示例

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

获取群组列表

JMessage#getGroups()

Since 2.5.0 支持 flag 标记

请求参数:

请求示例

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

获取群信息

JMessage#getGroupInfo()

Since 2.5.0 支持公开群

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组 id

请求示例

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

更新群信息

Since 2.4.0 支持群头像

JMessage#updateGroupInfo()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群 id
group_nameFALSE群组名,最少一个属性必填,非空
group_descriptionFALSE群组描述,最少一个属性必填,非空
avatarFALSE群头像图片的 DataForm 对象,最少一个属性必填

请求示例

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

获取群成员

JMessage#getGroupMembers()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群id

请求示例

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

主动加群(公开群)

JMessage#joinGroup()

Since 2.5.0

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群id
reasonFALSE申请理由

请求示例

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

群主审批入群请求

JMessage#addGroupMemberResp()

Since 2.5.0

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群id
event_idTRUE入群申请事件的 id
from_usernameTRUE邀请方 username
target_usernameTRUE被邀请方 username
resultTRUE审批结果,0:同意 1:拒绝
reasonFALSE拒绝原因
from_appkeyFALSE邀请方所属 appkey,默认本应用 appkey
target_appkeyFALSE被邀请方所属 appkey,默认本应用 appkey

请求示例

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

添加群用户禁言

JMessage#addGroupMemSilence()

Since 2.5.0

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群id
target_usernameTRUE目标 username
target_appkeyFALSE目标 appkey

请求示例

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

取消群用户禁言

JMessage#delGroupMemSilence()

Since 2.5.0

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群id
target_usernameTRUE目标 username
target_appkeyFALSE目标 appkey

请求示例

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

聊天室

Since 2.5.0 加入聊天室相关功能

获取appkey下聊天室分页列表

JMessage#getAppkeyChatrooms()

请求参数:

KEYREQUIREDESCRIPTION
startTRUE分页下标,首页获取为0
appkeyFALSE聊天室所属 appkey,默认本应用

请求示例

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

获取已加入的聊天室

JMessage#getSelfChatrooms()

请求参数:

请求示例

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

获取聊天室详情

JMessage#getChatroomInfo()

请求参数:

KEYREQUIREDESCRIPTION
idTRUE聊天室 id

请求示例

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

进入聊天室

JMessage#enterChatroom ()

请求参数:

KEYREQUIREDESCRIPTION
idTRUE聊天室id

请求示例

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

退出聊天室

JMessage#exitChatroom ()

请求参数:

KEYREQUIREDESCRIPTION
idTRUE聊天室id

请求示例

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

聊天室发送文本消息

JMessage#sendChatroomMsg()

请求参数:

KEYREQUIREDESCRIPTION
target_ridTRUE目标 id
content与 msg_body 参数二选一消息文本
msg_body与 content 参数二选一消息的 msg_body,用来实现消息转发功能
target_rnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型

请求示例

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

消息体

消息体详情:

聊天室发送图片消息

JMessage#sendChatroomPic()

请求参数:

KEYREQUIREDESCRIPTION
target_ridTRUE目标 id
image与 msg_body 参数二选一图片的 DataForm 对象
msg_body与 image 参数二选一消息的 msg_body,用来实现消息转发功能
target_rnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型

请求示例

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

聊天室发送文件消息

JMessage#sendChatroomFile()

请求参数:

KEYREQUIREDESCRIPTION
target_ridTRUE目标 id
file与 msg_body 参数二选一文件的 DataForm 对象
msg_body与 file 参数二选一消息的 msg_body,用来实现消息转发
target_rnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型

请求示例

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

聊天室发送位置消息

JMessage#sendChatroomLocation()

请求参数:

KEYREQUIREDESCRIPTION
target_ridTRUE接收消息者 username
latitude与 msg_body 二选一纬度
longitude与 msg_body 二选一经度
scale与 msg_body 二选一地图缩放级别
label与 msg_body 二选一地址
msg_body与位置相关参数二选一消息的 msg_body,用来实现消息转发功能
target_rnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型

请求示例

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

聊天室发送自定义消息

JMessage#sendChatroomCustom()

请求参数:

KEYREQUIREDESCRIPTION
target_ridTRUE接收消息者 username
customTRUE自定义 json object 消息
msg_body与 custom 二选一消息的 msg_body,用来实现消息转发功能
target_rnameFALSE接收者的展示名
extrasFALSE附加字段,字典类型

请求示例

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

免打扰管理

获取免打扰

JMessage#getNoDisturb()

请求参数:

请求示例

  1. JIM.getNoDisturb().onSuccess(function(data) {
  2. //data.code 返回码
  3. //data.message 描述
  4. //data.no_disturb.global 全局免打扰设置:0 关闭 1 打开
  5. //data.no_disturb.users[] 免打扰用户列表,比如示例
  6. //data.no_disturb.users[0].username 用户名
  7. //data.no_disturb.users[0].nickname 用户昵称
  8. //data.no_disturb.users[0].appkey 用户所属 appkey
  9. //data.no_disturb.groups[] 免打扰群组列表,比如示例
  10. //data.no_disturb.groups[0].gid 群组 id
  11. //data.no_disturb.groups[0].name 群名字
  12. //data.no_disturb.groups[0].appkey 群所属 appkey
  13. //data.no_disturb.groups[0].desc 群描述
  14. }).onFail(function(data) {
  15. //data.code 返回码
  16. //data.message 描述
  17. });

添加用户免打扰

JMessage#addSingleNoDisturb()

请求参数:

KEYREQUIREDESCRIPTION
target_nameTRUEusername
appkeyFALSE跨应用必填,默认不填表示本应用

请求示例

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

关闭用户免打扰

JMessage#delSingleNoDisturb()

请求参数:

KEYREQUIREDESCRIPTION
target_nameTRUEusername
appkeyFALSE跨应用必填,默认不填表示本应用

请求示例

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

添加群组免打扰

JMessage#addGroupNoDisturb()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组id

请求示例

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

关闭群组免打扰

JMessage#delGroupNoDisturb()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组id

请求示例

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

群屏蔽列表

JMessage#groupShieldList()

请求参数:

请求示例

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

添加群屏蔽

JMessage#addGroupShield()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组id

请求示例

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

关闭群屏蔽

JMessage#delGroupShield()

请求参数:

KEYREQUIREDESCRIPTION
gidTRUE群组id

请求示例

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

添加全局免打扰

JMessage#addGlobalNoDisturb()

请求参数:

请求示例

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

关闭全局免打扰

JMessage#delGlobalNoDisturb()

请求参数:

请求示例

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

黑名单管理

获取黑名单

JMessage#getBlacks()

请求参数:

请求示例

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

添加黑名单

JMessage#addSingleBlacks()

请求参数:

KEYREQUIREDESCRIPTION
member_usernamesTRUE用户列表示例:[{'username': 'name1', 'appkey': '跨应用必填,默认不填表示本应用'}]

请求示例

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

删除黑名单

JMessage#delSingleBlacks()

请求参数:

KEYREQUIREDESCRIPTION
member_usernamesTRUE用户列表示例:[{'username': 'name1', 'appkey': '跨应用必填,默认不填表示本应用'}]

请求示例

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

好友相关

好友列表

JMessage#getFriendList()

请求参数:

请求示例

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

添加好友

JMessage#addFriend()

请求参数:

KEYREQUIREDESCRIPTION
target_nameTRUE目标 username
whyTRUE邀请说明
appkeyFALSE跨应用查询时必填,目标应用的 appkey

添加好友请求示例

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

同意好友请求

Since 2.4.0

JMessage#acceptFriend()

请求参数:

KEYREQUIREDESCRIPTION
target_nameTRUE目标 username
appkeyFALSE跨应用查询时必填,目标应用的 appkey

添加好友请求示例

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

拒绝好友请求

Since 2.4.0

JMessage#declineFriend()

请求参数:

KEYREQUIREDESCRIPTION
target_nameTRUE目标 username
whyFALSE拒绝理由
appkeyFALSE跨应用查询时必填,目标应用的 appkey

添加好友请求示例

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

删除好友

JMessage#delFriend()

请求参数:

KEYREQUIREDESCRIPTION
target_nameTRUE目标 username
appkeyFALSE跨应用查询时必填,目标应用的 appkey

请求示例

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

更新好友备注

JMessage#updateFriendMemo()

请求参数:

KEYREQUIREDESCRIPTION
target_nameTRUE目标 username
memo_nameTRUE名称备注
memo_othersFALSE其他备注
appkeyFALSE跨应用查询时必填,目标应用的 appkey

请求示例

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

聊天消息实时监听

JMessage#onMsgReceive(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE消息接收处理函数

返回消息数组

KEYDESCRIPTION
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消息体

使用示例

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

离线消息同步监听

JMessage#onSyncConversation(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE消息接收处理函数

返回参数

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

使用示例

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

用户信息变更监听

JMessage#onUserInfUpdate(fn)

监听对象

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

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE处理函数

返回参数

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

使用示例

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

业务事件监听

JMessage#onEventNotification(fn)

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

KEYREQUIREDESCRIPTION
fnTRUE事件接收处理函数

返回参数

KEYDESCRIPTION
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群名
type0:单聊,1:群聊
group_name群名

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

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

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

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

好友邀请事件示例:event_type = 5

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

好友应答事件示例:event_type = 5

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

删除好友事件示例:event_type = 6

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

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

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

创建群组事件示例:event_type = 8

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

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

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

添加群组成员事件示例:event_type = 10

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

删除群组成员事件示例:event_type = 11

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

修改群信息事件示例:event_type = 12

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

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

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

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

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

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

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

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

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

消息被撤回事件示例:event_type = 55

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

入群申请事件示例:event_type = 56

Since 2.5.0

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

入群申请被拒绝事件示例:event_type = 57

Since 2.5.0

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

群用户禁言事件:event_type = 65

Since 2.5.0

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

多端在线好友变更事件示例:event_type =100

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

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

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

多端在线免打扰变更事件示例:event_type =102

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

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

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

多端在线消息已读回执变更事件示例:event_type =201

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

业务事件同步监听

JMessage#onSyncEvent(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE事件接收处理函数

返回参数 同业务事件监听

使用示例

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

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

Since 2.4.0

JMessage#onMsgReceiptChange(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE事件接收处理函数

返回参数

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

消息未读状态参数

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

使用示例

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

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

Since 2.4.0

JMessage#onSyncMsgReceipt(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE事件接收处理函数

返回参数

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

使用示例

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

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

Since 2.4.0

JMessage#onMutiUnreadMsgUpdate(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE事件接收处理函数

返回参数

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

使用示例

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

消息透传监听

Since 2.4.0

JMessage#onTransMsgRec(fn)

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE监听处理函数

返回参数

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

使用示例

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

聊天室消息监听

JMessage#onRoomMsg(fn)

Since 2.5.0

请求参数:

KEYREQUIREDESCRIPTION
fnTRUE消息接收处理函数

返回消息数组

KEYDESCRIPTION
room_id聊天室 id
msg_id消息 ID
ctime_ms消息生成时间,毫秒
content消息体

使用示例

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

高级应用

发送跨应用消息

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

以2.1发送单聊为例:

JMessage#sendSingleMsg()

请求参数:

KEYREQUIREDESCRIPTION
target_usernameTRUE接收消息者 username
target_nicknameTRUE接收消息者 nickname
contentTRUE消息文本
extrasFALSE附加字段,字典类型
appkeyFALSE跨应用查询时必填,目标应用的 appkey
其中 appkey 为目标 appkey,其他接口类似

发送、接收图片或文件

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

构造FormData示例:

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

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

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

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

图片、文件的接收需要通过 JMessage#getResource 接口传入资源 media_id 获取访问路径

发送和接收 Emoij 表情

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

错误码定义

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