Skip to content

APIs

Jump to bottom
JoshLipan edited this page Dec 12, 2018 · 24 revisions

Contents

对于 ionic 项目，需要在 .ts 文件中声明 declare var JMessage: any

所有 API 基本为 do(params, successCallback, errorCallback) 的形式（有些方法不需要回调函数），其中 params 为 object， successCallback 和 errorCallback 为 function，并会通过参数返回调用结果。

errorCallback 形式如下：

function (error) {
  var code = error.code         // 错误码
  var desc = error.description  // 错误详细描述
}

错误码定义可参考：

初始化

init

初始化插件。建议在应用起始页的构造函数中调用。

示例

JMessage.init({ isOpenMessageRoaming: true })

参数说明

  • isOpenMessageRoaming: 是否开启消息漫游功能。打开消息漫游之后，用户多个设备之间登录时，会自动将当前登录用户的历史消息同步到本地，同步完成后会触发 syncRoamingMessage 事件。

setDebugMode

设置是否开启 debug 模式，开启后 SDK 将会输出更多日志信息，推荐在应用对外发布时关闭。

示例

JMessage.setDebugMode({ enable: true })

用户登录、注册及属性维护

register

用户注册。

示例

JMessage.register({ username: 'username', password: 'password', nickname: 'nickname',
  gender: 'male', extras: { key1: 'value1' }},
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 用户名。在应用中用于唯一标识用户，必须唯一。支持以字母或者数字开头，支持字母、数字、下划线、英文点（.）、减号、@。长度限制：Byte(4~128)。
  • password: 用户密码。不限制字符。长度限制：Byte(4~128)。
  • nickname: String，昵称。
  • address: String，具体地址。
  • birthday：Number, 生日。为具体日期的毫秒数。
  • gender：String，性别。支持 'male', 'female' 和 'unknown'。
  • region: String，地区。
  • extras: Object，自定义键值对，value 只能为字符串类型。

login

用户登录。

示例

JMessage.login({ username: 'username', password: 'password' },
  () => {

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 用户名。
  • password: 用户密码。

logout

用户登出。

示例

JMessage.logout()

getMyInfo

获取当前登录用户信息。如果未登录会返回空对象。

关于 UserInfo 的构成，可以查看文档。

示例

JMessage.getMyInfo((myInfo) => {
  // do something.
})

getUserInfo

获取用户信息。该接口可以获取不同 AppKey 下（即不同应用）的用户信息，如果 AppKey 为空，则默认为当前应用下。

示例

JMessage.getUserInfo({ username: 'username', appKey: 'your_app_key' },
  (userInfo) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

updateMyPassword

更新当前登录用户的密码。

示例

JMessage.updateMyPassword({ oldPwd: 'old_password', newPwd: 'new_password' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

updateMyAvatar

更新当前登录用户的头像。

示例

JMessage.updateMyAvatar({ imgPath: 'img_local_path' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • imgPath: 本地图片文件的绝对路径地址。注意在 Android 6.0 及以上版本系统中，需要动态请求 WRITE_EXTERNAL_STORAGE 权限。 两个系统中的图片路径分别类似于：

    • Android：/storage/emulated/0/DCIM/Camera/IMG_20160526_130223.jpg
    • iOS：/var/mobile/Containers/Data/Application/7DC5CDFF-6581-4AD3-B165-B604EBAB1250/tmp/photo.jpg

downloadThumbUserAvatar

下载用户头像缩略图（不会重复下载）。

示例

JMessage.downloadThumbUserAvatar({ username: 'username', appKey: 'target_user_appKey' },
  (result) => {
    var username = result.username
    var appKey = result.appKey
    var filePath = result.filePath  // 图片文件路径

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 用户名；
  • appKey: 用户所属应用的 AppKey，如果为空或不填则默认为当前应用。

downloadOriginalUserAvatar

下载用户头像原图（不会重复下载）。如果用户未设置头像，返回的 filePath 为空字符串。

示例

JMessage.downloadOriginalUserAvatar({ username: 'username', appKey: 'target_user_appKey' },
  (result) => {
    var username = result.username
    var appKey = result.appKey
    var filePath = result.filePath  // 图片文件路径

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 用户名；
  • appKey: 用户所属应用的 AppKey，如果为空或不填则默认为当前应用。

updateMyInfo

更新当前登录用户信息。包括了：昵称（nickname）、生日（birthday）、个性签名（signature）、性别（gender）、地区（region）和具体地址（address）。

示例

JMessage.updateMyInfo({ nickname: 'nickname' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • nickname: 昵称。不支持字符 "\n" 和 "\r"；长度限制：Byte (0~64)。
  • birthday: 生日日期的毫秒数；Number 类型。
  • gender: 必须为 'male', 'female' 和 'unknown' 中的一种。
  • 其余都为 string 类型，支持全部字符串；长度限制为 Byte (0~250)。

群组

目前支持创建、退出群组；添加、移除群成员以及向群组发送群聊会话。

createGroup

创建群组。

示例

JMessage.createGroup({ name: 'group_name', desc: 'group_desc' },
  (groupId) => {  // groupId: 新创建的群组 ID
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • name (string): 群组名。不支持 "\n" 和 "\r" 字符，长度限制为 0 ~ 64 Byte。
  • groupType (string): 创建群组类型 'private' | 'public' 默认为 'private'。
  • desc (string): 群组描述。长度限制为 0 ~ 250 Byte。

getGroupIds

获取当前用户所加入的群组 ID 列表。

示例

JMessage.getGroupIds((groupIdArr) => {  // 群组 id 数组
  // do something.

}, (error) => {
    var code = error.code
    var desc = error.description
})

getGroupInfo

获取群组信息。

示例

JMessage.getGroupInfo({id: 'groupId'},
  (groupInfo) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

updateGroupInfo

更新群组信息。

示例

JMessage.getGroupInfo({id: 'groupId', newName: 'new_group_name', newDesc: 'new_group_desc'},
  (groupInfo) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • id: 群组 id。
  • newName: 新的群组名称。不支持 "\n" 和 "\r" 字符，长度要求为 0 ~ 64 Byte。
  • newDesc: 新的群组详细描述。长度要求为 0 ~ 250 Byte。

addGroupMembers

添加群成员。

示例

JMessage.addGroupMembers({id: 'groupId', usernameArray: ['user1', 'user2'], appKey: 'appKey'},
  () => {

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • id: 群组 id。
  • usernameArray: 被添加的用户名数组。
  • appKey: 待添加用户所在应用的 AppKey。如果为空或不填，默认为当前应用。

removeGroupMembers

移除群组成员。

示例

JMessage.removeGroupMembers({ id: 'groupId', usernameArray: ['user1', 'user2'], appKey: 'appKey' },
  () => {

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • id: 群组 id。
  • usernameArray: 被添加的用户名数组。
  • appKey: 待添加用户所在应用的 AppKey。如果为空或不填，默认为当前应用。

getGroupMembers

获取群组成员列表。

示例

JMessage.getGroupMembers({ id: 'groupId' },
  (groupMemberInfoArray) => {  // 群成员数组
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • id: 群组 id。

exitGroup

退出群组。

示例

JMessage.exitGroup({ id: 'groupId'},
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • id: 群组 Id。

blockGroupMessage

设置是否屏蔽指定群组消息。

示例

JMessage.blockGroupMessage({ id: '15123', isBlock: true },
  () => {
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.desc
  })

参数说明

  • id: 群组 Id。
  • isBlock: true - 屏蔽；false - 取消屏蔽。

isGroupBlocked

查询指定群组是否被屏蔽。

示例

JMessage.isGroupBlocked({ id: '15123' },
  (result) => {
    var isBlocked = result.isBlocked
  }, (error) => {
    var code = error.code
    var desc = error.desc
  })

参数说明

  • id: 群组 Id。

getBlockedGroupList

获取被当前登录用户屏蔽的群组列表。

示例

JMessage.getBlockedGroupList((groupArr) => {
  for (groupInfo in groupArr) {
    // do something.
  }
}, (error) => {
  var code = error.code
  var desc = error.desc
})

返回值说明

dissolveGroup

解散群

示例

JMessage.dissolveGroup({ groupId: 'group_id' },
  () => {  // 
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 要解散的群组 id。

addGroupAdmins

批量添加管理员

示例

JMessage.addGroupAdmins({ groupId: 'group_id', usernames: ['ex_username1', 'ex_username2'] },
  () => {  // 
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。
  • usernames (array): 被添加的的用户名数组。

removeGroupAdmins

批量删除管理员

示例

JMessage.removeGroupAdmins({ groupId: 'group_id', usernames: ['ex_username1', 'ex_username2'] },
  () => {  // 
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。
  • usernames (array): 被移除的的用户名数组。

changeGroupType

修改群类型

示例

JMessage.changeGroupType({ groupId: 'group_id', type: 'public' },
  () => {  // 
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。
  • type (string): 要修改的类型可以为如下值 'private' | 'public'

getPublicGroupInfos

分页获取指定 appKey 下的共有群

示例

JMessage.getPublicGroupInfos({ appKey: 'my_appkey', start: 0, count: 20 },
  (groudArr) => {  //group = [{GroupInfo}] 
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • appKey (string): 获取指定 appkey
  • start (int): 开始的位置
  • count (int): 获取的数量

applyJoinGroup

申请入群（公开群）

示例

JMessage.applyJoinGroup({ groupId: 'group_id', reason: 'Hello I from ...' },
  () => {  
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

processApplyJoinGroup

批量处理入群（公开群）申请

示例

JMessage.processApplyJoinGroup({ events: ['ex_event_id_1', 'ex_event_id_2'], reason: 'Hello I from ...' },
  () => {  
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • events (array): eventId 数组,当有用户申请入群的时候(或者被要求)会回调一个 event(通过 addReceiveApplyJoinGroupApprovalListener 监听)，每个 event 会有个 id，用于审核入群操作。
  • reason (string): 入群理由。

transferGroupOwner

移交群主

示例

JMessage.transferGroupOwner({ groupId: 'group_id', username: 'ex_username', appKey: 'ex_appKey'},
  () => {  
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。
  • username (string): 待移交者用户名
  • appKey (string): 待移交者 appKey, 若传入空则默认使用本应用 appKey

setGroupMemberSilence

设置禁言或解禁用户

示例

JMessage.setGroupMemberSilence({ groupId: 'group_id', username: 'ex_username', appKey: 'ex_appKey', isSilence: true},
  () => {  
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。
  • username (string): 待设置群成员的 username
  • appKey (string): 待设置群成员的 appKey，传入空则默认使用本应用 appKey
  • isSilence (Boolean): true 设置禁言， false 取消禁言

isSilenceMember

判断用户是否被禁言

示例

JMessage.isSilenceMember({ groupId: 'group_id', username: 'ex_username', appKey: 'ex_appKey'},
  () => {  
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。
  • username (string): 待判断群成员的 username
  • appKey (string): 待判断群成员的 appKey，传入空则默认使用本应用 appKey

setGroupNickname

设置群成员昵称

示例

JMessage.setGroupNickname({ groupId: 'group_id', username: 'ex_username', appKey: 'ex_appKey', nickName: "ex_nikename"},
  () => {  
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。
  • username (string): 待设置群成员的 username
  • appKey (string): 待设置群成员的 appKey，传入空则默认使用本应用 appKey
  • nickName (string): 设置的昵称

groupSilenceMembers

获取群禁言列表 （注意在获取群列表成功后该方法才有效）

示例

JMessage.groupSilenceMembers({ groupId: 'group_id'},
  (groupMemberInfoArray) => {  // 群成员数组
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId (string): 指定操作的群 groupId。

聊天

注意在第一次发送消息之前，必须先调用 createConversation 方法。

sendTextMessage

发送文本消息。

示例

JMessage.sendTextMessage({ type: 'single', username: 'username', appKey: 'appKey',
  text: 'hello world', extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

// or

JMessage.sendTextMessage({ type: 'group', groupId: '1111', text: 'hello world',
  extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

// or

JMessage.sendTextMessage({ type: 'chatRoom', roomId: '1', text: 'hello world',
  extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  msg => {
    // do something.
  }, error => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single'，'group' 或 'chatRoom'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • roomId: 聊天室 id。
  • text: 消息内容。
  • extras:（可选）自定义键值对，value 必须为字符串类型。
  • messageSendingOptions:（可选）消息发送配置参数。支持的属性：
    • isShowNotification: 接收方是否针对此次消息发送展示通知栏通知。默认为 true。
    • isRetainOffline: 是否让后台在对方不在线时保存这条离线消息，等到对方上线后再推送给对方。默认为 true。
    • isCustomNotificationEnabled: 是否开启自定义接收方通知栏功能，设置为 true 后可设置下面的 notificationTitle 和 notificationText。默认未设置。
    • notificationTitle: 设置此条消息在接收方通知栏所展示通知的标题。
    • notificationText: 设置此条消息在接收方通知栏所展示通知的内容。

sendImageMessage

发送图片消息，在收到消息时 SDK 默认会自动下载缩略图，如果要下载原图，需调用 downloadOriginalImage 方法。

如果是发送外部存储中的图片，并且设备 Android 系统为 6.0 及以上，还需要动态请求 WRITE_EXTERNAL_STORAGE 权限。可使用 android-permissions plugin。

示例

JMessage.sendImageMessage({ type: 'single', username: 'username', appKey: 'appKey',
  path: 'image_path', extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

// or

JMessage.sendImageMessage({ type: 'group', groupId: '1111', path: 'image_path',
  extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • path: 本地图片的绝对路径。格式分别类似为：
    • Android：/storage/emulated/0/DCIM/Camera/IMG_20160526_130223.jpg
    • iOS：/var/mobile/Containers/Data/Application/7DC5CDFF-6581-4AD3-B165-B604EBAB1250/tmp/photo.jpg
  • extras: 自定义键值对，value 必须为字符串类型。
  • messageSendingOptions: 消息发送配置参数。支持的属性：
    • isShowNotification: 接收方是否针对此次消息发送展示通知栏通知。默认为 true。
    • isRetainOffline: 是否让后台在对方不在线时保存这条离线消息，等到对方上线后再推送给对方。默认为 true。
    • isCustomNotificationEnabled: 是否开启自定义接收方通知栏功能，设置为 true 后可设置下面的 notificationTitle 和 notificationText。默认未设置。
    • notificationTitle: 设置此条消息在接收方通知栏所展示通知的标题。
    • notificationText: 设置此条消息在接收方通知栏所展示通知的内容。

sendVoiceMessage

发送语音消息，在收到消息时 SDK 默认会自动下载语音文件，如果下载失败（即语音消息文件路径为空），可调用 downloadVoiceFile 手动下载。

如果是发送外部存储中的图片，并且设备 Android 系统为 6.0 及以上，还需要动态请求 WRITE_EXTERNAL_STORAGE 权限。可使用 android-permissions plugin。

示例

JMessage.sendVoiceMessage({ type: 'single', username: 'username', appKey: 'appKey',
  path: 'voice_file_path', extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

// or

JMessage.sendVoiceMessage({ type: 'group', groupId: '111', path: 'voice_file_path',
  extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • path: 本地音频文件的绝对路径。
  • extras:（可选）自定义键值对，value 必须为字符串类型。
  • messageSendingOptions:（可选）消息发送配置参数。支持的属性：
    • isShowNotification: 接收方是否针对此次消息发送展示通知栏通知。默认为 true。
    • isRetainOffline: 是否让后台在对方不在线时保存这条离线消息，等到对方上线后再推送给对方。默认为 true。
    • isCustomNotificationEnabled: 是否开启自定义接收方通知栏功能，设置为 true 后可设置下面的 notificationTitle 和 notificationText。默认未设置。
    • notificationTitle: 设置此条消息在接收方通知栏所展示通知的标题。
    • notificationText: 设置此条消息在接收方通知栏所展示通知的内容。

sendCustomMessage

发送自定义消息。在收到自定义消息时不会有通知提示。

示例

JMessage.sendCustomMessage({ type: 'single', username: 'username', appKey: 'appKey',
  customObject: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

// or

JMessage.sendCustomMessage({ type: 'group', groupId: '111', path: 'voice_file_path',
  customObject: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • customObject: 自定义键值对，value 必须为字符串类型。
  • messageSendingOptions:（可选）消息发送配置参数。支持的属性：
    • isShowNotification: 接收方是否针对此次消息发送展示通知栏通知。默认为 true。
    • isRetainOffline: 是否让后台在对方不在线时保存这条离线消息，等到对方上线后再推送给对方。默认为 true。
    • isCustomNotificationEnabled: 是否开启自定义接收方通知栏功能，设置为 true 后可设置下面的 notificationTitle 和 notificationText。默认未设置。
    • notificationTitle: 设置此条消息在接收方通知栏所展示通知的标题。
    • notificationText: 设置此条消息在接收方通知栏所展示通知的内容。

sendLocationMessage

发送地理位置消息，通常需要配合地图插件使用。

示例

JMessage.sendLocationMessage({ type: 'single', username: 'username', appKey: 'appKey',
  latitude: 22.54, longitude: 114.06, scale:1, address: '深圳市',
  extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

// or

JMessage.sendLocationMessage({ type: 'group', groupId: '111',
  latitude: 22.54, longitude: 114.06, scale:1, address: '深圳市',
  extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • latitude: 纬度。
  • longitude: 经度。
  • scale: 地图缩放比例。
  • address: 详细地址。
  • extras:（可选）自定义键值对，value 必须为字符串类型。
  • messageSendingOptions:（可选）消息发送配置参数。支持的属性：
    • isShowNotification: 接收方是否针对此次消息发送展示通知栏通知。默认为 true。
    • isRetainOffline: 是否让后台在对方不在线时保存这条离线消息，等到对方上线后再推送给对方。默认为 true。
    • isCustomNotificationEnabled: 是否开启自定义接收方通知栏功能，设置为 true 后可设置下面的 notificationTitle 和 notificationText。默认未设置。
    • notificationTitle: 设置此条消息在接收方通知栏所展示通知的标题。
    • notificationText: 设置此条消息在接收方通知栏所展示通知的内容。

sendFileMessage

发送文件消息。对方在收到文件消息时 SDK 不会自动下载，下载文件需手动调用 downloadFile 方法。

如果是发送外部存储中的图片，并且设备 Android 系统为 6.0 及以上，还需要动态请求 WRITE_EXTERNAL_STORAGE 权限。可使用 android-permissions plugin。

示例

JMessage.sendFileMessage({ type: 'single', username: 'username', appKey: 'appKey',
  path: 'file_path', fileName: 'file_name', extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

// or

JMessage.sendFileMessage({ type: 'group', groupId: '111', path: 'file_path', fileName: 'file_name', extras: {key1: 'value1'}, messageSendingOptions: JMessage.messageSendingOptions },
  (msg) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • path: 本地文件的绝对路径。
  • fileName:（可选）上传后文件的文件名。如果不填或为空，则默认使用文件原名。
  • extras:（可选）自定义键值对，value 必须为字符串类型。
  • messageSendingOptions:（可选）消息发送配置参数。支持的属性：
    • isShowNotification: 接收方是否针对此次消息发送展示通知栏通知。默认为 true。
    • isRetainOffline: 是否让后台在对方不在线时保存这条离线消息，等到对方上线后再推送给对方。默认为 true。
    • isCustomNotificationEnabled: 是否开启自定义接收方通知栏功能，设置为 true 后可设置下面的 notificationTitle 和 notificationText。默认未设置。
    • notificationTitle: 设置此条消息在接收方通知栏所展示通知的标题。
    • notificationText: 设置此条消息在接收方通知栏所展示通知的内容。

retractMessage

消息撤回。调用后被撤回方会收到一条 retractMessage 事件。并且双方的消息内容将变为不可见。

示例

JMessage.retractMessage({type: 'single', username: 'username', appKey: 'appKey', messageId: '1'},
  () => {
   // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • messageId: 要撤回的消息 id。

getHistoryMessages

从最新的消息开始获取历史消息。

当 limit 为 -1 而 from >= 0 时，返回从 from 开始余下的所有历史消息。如果 from 大于历史消息总数，则返回空数组。 例如：当 from = 0 && limit = -1 时，返回所有历史消息。

示例

JMessage.getHistoryMessages({ type: 'single', username: 'username',
  appKey: 'appKey', from: 0, limit: 10 },
  (msgArr) => { // 以参数形式返回消息对象数组
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: string, 会话类型。可以为 'single' 或 'group'。
  • username: string, 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: string, 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: string, 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • from: number, 第一条消息对应的下标，起始为 0。
  • limit: number, 消息数。当 from = 0 并且 limit = -1 时，返回所有的历史消息。

getMessageById

根据消息 id 获取消息对象。

示例

JMessage.getMessageById({ type: 'single', username: 'username', appKey: 'appKey', messageId: '1' },
  (msg) => {  // Message 对象
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: string, 会话类型。可以为 'single' 或 'group'。
  • username: string, 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: string, 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: string, 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • messageId: string, 消息对象中的 id。

deleteMessageById

根据 id 删除消息。

示例

JMessage.deleteMessageById({ type: 'single', username: 'username', appKey: 'appKey', messageId: '1' },
  (msg) => {  // Message 对象
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: string, 会话类型。可以为 'single' 或 'group'。
  • username: string, 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: string, 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: string, 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • messageId: string, 消息对象中的 id。

downloadThumbImage

下载图片消息缩略图。如果已经下载，会直接返回本地文件路径，不会重复下载。

示例

JMessage.downloadThumbImage({ type: 'single', username: 'username', messageId: '1' },
  (result) => {
    var msgId = result.messageId
    var imgPath = result.filePath
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 聊天对象的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 聊天对象所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 消息所属群组的 id。当 type 为 'group' 时，groupId 为必填。
  • messageId: 图片消息 id。

downloadOriginalImage

下载图片消息原图。如果已经下载，会直接返回本地文件路径，不会重复下载。

示例

JMessage.downloadOriginalImage({ type: 'single', username: 'username', messageId: '1' },
  (result) => {
    var msgId = result.messageId
    var imgPath = result.filePath
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 聊天对象的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 聊天对象所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 消息所属群组的 id。当 type 为 'group' 时，groupId 为必填。
  • messageId: 图片消息 id。

downloadVoiceFile

下载语音文件。如果已经下载，会直接返回本地文件路径，不会重复下载。

示例

JMessage.downloadVoiceFile({ type: 'single', username: 'username', messageId: '1' },
  (result) => {
    var msgId = result.messageId
    var imgPath = result.filePath

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • messageId: 语音消息 id。

downloadFile

下载文件。如果已经下载，会直接返回本地文件路径，不会重复下载。

示例

JMessage.downloadFile({ type: 'single', username: 'username',
  messageId: '1' },
  (result) => {
    var msgId = result.messageId
    var imgPath = result.filePath

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • messageId: 文件消息 id。

sendSingleTransCommand

发送单聊透传命令消息。

透传命令发送的命令后台不会为其离线保存，只会在对方用户在线的前提下将命令推送给对方。对方在收到命令之后也不会本地保存，不发送通知栏通知，整体快速响应。

开发者可以通过命令透传拓展一些在线场景下的辅助功能，如：输入状态提示等。

示例

JMessage.sendSingleTransCommand({ username:'target_username', appKey: '1251231412', message:'hello' },
  () => { // success
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 对方用户用户名；
  • appKey: 目标用户所属应用的 AppKey。如果不填，则默认为当前应用；
  • message: 透传消息内容。

sendGroupTransCommand

发送群聊透传命令消息。

示例

JMessage.sendGroupTransCommand({ groupId:'12512314', message:'hello' },
  () => { // success
    // do something.
  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • groupId: 目标群组 Id。
  • message: 透传消息内容。

会话

createConversation

创建聊天会话。

示例

JMessage.createConversation({ type: 'single', username: 'username', appKey: 'appKey' },
  (conversation) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 会话类型。可以为 'single'，'group' 或 'chatRoom'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • roomId: 聊天室 id。当 type 为 'chatRoom' 时，为必填。

deleteConversation

删除聊天会话，同时也会删除本地聊天记录。

示例

JMessage.deleteConversation({ type: 'single', username: 'username', appKey: 'appKey' },
  (conversation) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
 )

参数说明

  • type: 会话类型。可以为 'single'，'group' 或 'chatRoom'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • roomId: 聊天室 id。当 type 为 'chatRoom' 时，为必填。

enterConversation

(Android only) 进入聊天会话。当调用后，该聊天会话的消息将不再显示通知。

iOS 默认应用在前台时，就不会显示通知。

示例

JMessage.enterConversation({ type: 'single', username: 'username', appKey: 'appKey' },
  (conversation) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
 )

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。

exitConversation

(Android only) 退出聊天会话。调用后，聊天会话之后的相关消息通知将会被触发。

示例

JMessage.exitConversation({ type: 'single', username: 'username', appKey: 'appKey' },
  (conversation) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
 )

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。

getConversation

获取聊天会话对象。

示例

JMessage.getConversation({ type: 'single', username: 'username', appKey: 'appKey' },
  (conversation) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
 )

参数说明

  • type: 会话类型。可以为 'single'，'group' 或 'chatRoom'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。
  • roomId: 聊天室 id。当 type 为 'chatRoom' 时，为必填。

getConversations

从本地数据库获取会话列表。默认按照会话的最后一条消息时间降序排列。

示例

JMessage.getConversations((conArr) => { // conArr: 会话数组。
  // do something.

}, (error) => {
    var code = error.code
    var desc = error.description
})

getAllUnreadCount

获取所有会话未读消息总数

示例

JMessage.getAllUnreadCount(({count}) => {
  console.log(count)
})

resetUnreadMessageCount

重置会话的未读消息数。

示例

JMessage.resetUnreadMessageCount({ type: 'single', username: 'username', appKey: 'appKey' },
  (conversation) => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
 )

参数说明

  • type: 会话类型。可以为 'single' 或 'group'。
  • username: 对方用户的用户名。当 type 为 'single' 时，username 为必填。
  • appKey: 对方用户所属应用的 AppKey。如果不填，默认为当前应用。
  • groupId: 对象群组 id。当 type 为 'group' 时，groupId 为必填。

好友

JMessage SDK 本身是属于无好友模式，即 JMessage 中的任意两个用户不需要建立好友关系也能聊天。JMessage 仅提供好友关系的托管，以及相关好友请求的发送与接收。

除此之外更多基于好友关系之上的功能，比如仅允许好友间聊天需要开发者自行实现。

sendInvitationRequest

发送添加好友请求，调用后对方会收到 contactNotify 事件。

示例

JMessage.sendInvitationRequest({ username: 'username', appKey: 'appKey', reason: '请求添加好友'},
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 对方用户的用户名。
  • appKey: 对方用户所属应用的 AppKey，如果为空或不填则默认为当前应用。
  • reason: 申请理由。

acceptInvitation

接受申请好友请求，调用后对方会收到 contactNotify 事件。

示例

JMessage.acceptInvitation({ username: 'username', appKey: 'appKey' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 申请发送用户的用户名。
  • appKey: 申请发送用户所在应用的 AppKey，为空或不填则默认为当前用户。

declineInvitation

拒绝申请好友请求，调用成功后对方会收到 contactNotify 事件。

示例

JMessage.declineInvitation({ username: 'username', appKey: 'appKey', reason: '拒绝理由' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 申请发送用户的用户名。
  • appKey: 申请发送用户所在应用的 AppKey，为空或不填则默认为当前用户。
  • reason: 拒绝理由。长度要求为 0 ~ 250 Byte。

getFriends

获取好友列表。

示例

JMessage.getFriends((friendArr) => {  // 好友用户对象数组。
  // do something.

}, (error) => {
    var code = error.code
    var desc = error.description
})

removeFromFriendList

删除好友，调用成功后对方会收到 contactNotify 事件。

示例

JMessage.removeFromFriendList({ username: 'username', appKey: 'appKey' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

updateFriendNoteName

更新好友备注名。

示例

JMessage.updateFriendNoteName({ username: 'username', appKey: 'appKey', noteName: 'noteName' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • username: 好友的用户名。
  • appKey: 好友所属应用的 AppKey，如果为空或不填默认为当前应用。
  • noteName: 备注名。不支持 "\n" 和 "\r" 字符，长度要求为 0 ~ 64 Byte。

updateFriendNoteText

更新用户备注信息。

示例

JMessage.updateFriendNoteText({ username: 'username', appKey: 'appKey', noteText: 'noteName' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
 )

参数说明

  • username: 好友的用户名。
  • appKey: 好友所属应用的 AppKey，如果为空或不填默认为当前应用。
  • noteText: 备注名。长度要求为 0 ~ 250 Byte。

黑名单

当用户被加入到黑名单后，我方依旧能给对方发消息，但当对方给我们发消息时会返回指定错误码，提示发送消息失败。

addUsersToBlacklist

批量加入用户到黑名单。

示例

JMessage.addUsersToBlacklist({ usernameArray: ['user1', 'user2'], appKey: 'appKey' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • usernameArray: 待添加的用户名数组。
  • appKey: 待添加用户所属应用的 AppKey，如果为空或不填，默认为当前应用。

removeUsersFromBlacklist

批量将用户从黑名单中移除。

示例

JMessage.removeUsersFromBlacklist({ usernameArray: ['user1', 'user2'], appKey: 'appKey' },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
 )

参数说明

  • usernameArray: 待添加的用户名数组。
  • appKey: 待添加用户所属应用的 AppKey，如果为空或不填，默认为当前应用。

getBlacklist

获取被当前用户加入黑名单的用户列表。

示例

JMessage.getBlacklist((userArray) => {
  // do something.

}, (error) => {
  var code = error.code
  var desc = error.description
})

返回值说明

  • userArray: 在黑名单中用户的 UserInfo 数组。

免打扰

当设置免打扰后 SDK 不会弹出默认的通知提示，但消息事件照常触发。

setNoDisturb

设置对某个用户或群组是否免打扰。

示例

JMessage.setNoDisturb({ type: 'single', username: 'username', isNoDisturb: true },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • type: 'single' / 'group'，指明是用户还是群组。
  • username: 用户名。当 type 为 'single' 时必填。
  • appKey: 用户所在应用的 appKey，如果为空或不填，默认为当前应用。
  • groupId: 群组 id。当 type 为 'group' 时必填。
  • isNoDisturb: true / false

setNoDisturbGlobal

设置全局免打扰。

示例

JMessage.setNoDisturbGlobal({ isNoDisturb: true },
  () => {
    // do something.

  }, (error) => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • isNoDisturb: boolean 类型。true: 开启免打扰；false: 关闭免打扰。

isNoDisturbGlobal

判断当前是否开启了全局免打扰。

示例

JMessage.isNoDisturbGlobal((result) => {
  var isNoDisturb = result.isNoDisturb

}, (error) => {
  var code = error.code
  var desc = error.description
})

返回值说明

  • result:
    • isNoDisturb: 是否开启全局免打扰。

getNoDisturbList

获取免打扰列表。

示例

JMessage.getNoDisturbList((result) => {
  var userInfoArr = result.userInfoArray
  var groupInfoArr = result.groupInfoArray

}, (error) => {
  var code = error.code
  var desc = error.description
})

返回值说明

  • result:
    • userInfoArray: 处于免打扰状态的用户信息列表；
    • groupInfoArray: 处于免打扰状态的群组信息列表。

聊天室

聊天室和群组最大的区别在于，聊天室的消息没有推送通知和离线保存，也没有常驻成员的概念，只要进入聊天室即可接收消息，开始聊天。 一旦退出聊天室，便不再会再接收到任何消息、通知或提醒。

目前聊天室只能通过官网控制台或服务端（REST API）进行创建。

目前，仅支持发送文本消息（调用 sendTextMessage）。

getChatRoomInfoListOfApp

分页获取当前应用的聊天室信息。

示例

JMessage.ChatRoom.getChatRoomInfoListOfApp({ start: 0, count: 10 },
  messageArray => {
    for (msg in messageArray) {
      // do something.
    }
  }, error => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • start: 索引的起始位置，
  • count: 要查询的条数。

getChatRoomInfoListOfUser

获取当前登录用户加入的聊天室信息列表。

示例

JMessage.ChatRoom.getChatRoomInfoListOfUser(chatRoomInfoList => {
  for (chatRoomInfo in chatRoomInfoList) {
    // do something.
  }
}, error => {
  var code = error.code
  var desc = error.description
})

getChatRoomInfoListById

根据聊天室 id 获取聊天室信息。

示例

JMessage.ChatRoom.getChatRoomInfoListById({ roomIds: ['1', '2'] },
  chatRoomInfoList => {
    for (chatRoomInfo in chatRoomInfoList) {
      // do something.
    }
  }, error => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • roomIds: 字符串数组。待查询聊天室的 id 数组。

getChatRoomOwner

获得聊天室所有者的用户信息。

示例

JMessage.ChatRoom.getChatRoomOwner({ roomId: '1' },
  ownerInfo => {
    // do something.
  }, error => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • roomId: 字符串，聊天室 id。

enterChatRoom

进入聊天室。 用户只有成功调用此接口之后，才能收到聊天室消息，以及在此聊天室中发言。 成功进入聊天室之后，会将聊天室中最近若干条聊天记录同步到本地并触发 receiveChatRoomMessage 事件。

示例

JMessage.ChatRoom.enterChatRoom({ roomId: '1' },
  conversation => { // 成功回调中，将返回聊天室会话。
    // do something.
  }, error => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • roomId: 字符串，聊天室 id。

exitChatRoom

离开聊天室。 成功调用此接口之后，用户将能不在此聊天室收发消息。

示例

JMessage.ChatRoom.exitChatRoom({ roomId: '1' },
  () => { // success
    // do something.
  }, error => {
    var code = error.code
    var desc = error.description
  })

参数说明

  • roomId: 字符串，聊天室 id。

getChatRoomConversation

获取聊天室会话信息。

示例

JMessage.ChatRoom.getChatRoomConversation({ roomId: '1' },
  conversation => { // success
    // do something.
  }, error => {
    var code = error.code
    var desc = error.description
)

参数说明

  • roomId: 字符串，聊天室 id。

getChatRoomConversationList

从本地数据库中获取包含当前登录用户所有聊天室会话的列表。

示例

JMessage.ChatRoom.getChatRoomConversationList(conversationList => {
  for (conversation : conversationList) {
    // do something.
  }
}, error => {
  var code = error.code
  var desc = error.description
})

其他

setBadge

设置 JMessage 服务器角标。

示例

JMessage.setBadge({badge: 0})

事件监听

事件监听相关方法可参考 Events。

Clone this wiki locally