IMSDK的API分为6个模块:Setting、Auth、Msg、Conv、Event、Logger。本文介绍IMSDK的接口说明。

Setting

Setting模块提供AIM IMSDK配置和初始化的API。

  • API
    方法 请求参数 返回值 描述
    set ISettingOptions void 初始化配置
    get - ISettingOptions 获取配置内容
  • 参数类型
    表 1. ISettingOptions
    名称 是否必选 类型 描述
    appKey String 分配给应用的key
    mediaHost String 多媒体上传服务器地址
    deviceId String 设备唯一ID,通过IMSDK取到
    debug Boolean 是否开启debug,控制台会输出调试信息
    appName String 应用名
    deviceName String 浏览器UA
    log ILogConfig 日志方法,用于上报日志
    authTokenCallback Promise<IToken> callback获取登录token的异步函数
    表 2. IToken
    名称 是否必填 类型 描述
    uid Number uid
    accessToken String 登录token
    refreshToken String 刷新token
    accessTokenExpiredTime String 过期时间
    表 3. ILogConfig
    名称 是否必填 类型 描述
    info Function info类型日志处理
    error Function error类型日志处理
  • 示例代码
    const deviceId = await IMSDK.getAuthService().getDeviceId();
    const Setting = {
      appKey, // 应用 key
      mediaHost: 'media 地址',
      deviceId, // 设备唯一id
      appName, // app_name 应用名称
      debug: true,
      wsUrl: url,
      log: {
        error(...args) { console.error(...args) },
        info(...args) { console.info(...args) }
      },
      async authTokenCallback(uid) {
        return fetch('服务端地址获取URL' )
          .then((res) => res.json())
          .then((res) => {
          if (res) {
              return { ...res, uid };
          }
          throw new Error('token is null');
        });
      },
    };
    
    IMSDK.getSettingService().set(Setting)
    IMSDK.getAuthService().login()

Auth

Auth模块提供登录状态、登录、登出等能力。在初始化之后,可调用login执行登录过程。

  • API
    方法 请求参数 返回值 描述
    getConnectionStatus - ConnectionStatus 获取连接状态
    login - Promise<void> 登录
    logout - Promise<void> 登出
    getMyUid - string或undefined 获取当前登录appUid
    getDeviceId - Promise<string> 获取设备ID,初始化时使用
  • 参数类型
    表 4. ConnectionStatus 连接状态
    枚举key 描述
    CONN_UNCONNECTED 0 未连接
    CONN_CONNECTING 1 正在连接
    CONN_CONNECTED 2 已连接
    CONN_AUTHING 3 正在登录
    CONN_AUTHED 4 登录成功

Msg

Msg模块提供消息相关基础API,例如:删除消息、撤回消息、设置为已读等。
说明 发消息、拉取消息列表在DataSDK中。
  • API
    方法 请求参数 返回值 描述
    deleteMessage appCid、msgId、conversationType Promise<void> 删除消息
    batchDeleteMessage appCid、msgId[]、conversationType Promise<void> 批量删除消息
    recallMessage appCid、msgId、conversationType Promise<void> 撤回消息
    updateMessageToRead appCid、msgId[]、conversationType Promise<void> 将多条消息设置为已读,同步云端,更新发送者未读数量
    ListMessageReadStatus appCid、msgId Promise<MessageReadStatusModel[]> 根据消息ID,拉取接收者已读、未读状态
  • 参数类型
    参数 类型 描述
    appCid String 会话ID
    msgId String 消息ID
    conversationType Number 会话类型。取值:
    • 1:单聊
    • 2:群聊
    表 5. MessageReadStatusModel
    名称 是否必填 类型 描述
    uid String 用户ID
    status Number 消息阅读状态。取值:
    • 0:未读
    • 2:已读
    表 6. UserMessageModel
    名称 是否必填 类型 描述
    message MessageModel 消息数据类型
    readStatus Number 接收者是否读消息。取值:
    • 2:已读
    • 其他:未读
    msgStatus IMsgStatusType 消息状态。
    • 0:删除
    • 1:正常
    • 2:撤回
    • 3:指定接收者删除
    • 4:消息降级(拉首屏专用)
    recallFeature RecallFeatureModel 撤回相关数据
    表 7. RecallFeatureModel
    名称 是否必填 类型 描述
    showRecallStatusSetting Number 是否展示回撤状态消息。取值:
    • 空或0:不展示撤回状态消息
    • 1:展示撤回状态消息
    operatorType IRecallOperatorType 撤回操作者类型。取值:
    • 0:发送者撤回
    • 1:群主撤回
    • 2:系统撤回
    • 3:安全撤回
    • 101:自定义操作者
    code String 业务方自定义code
    operatorUid String 撤回操作者uid
    extension {[key: string]: string} 撤回扩展字段
    表 8. MessageModel
    名称 是否必填 类型 描述
    appCid String 消息所在会话ID
    uuid String 本地消息唯一标识,历史消息无uuid
    messageId String 消息ID
    sender String 发送者的uid
    createAt Number 消息创建时间
    content ContentModel 消息内容模型
    receiverCount Number 消息接收人数
    unreadCount Number 消息未读人数
    redPointPolicy Number 未读消息红点控制。取值:
    • 0:表示默认(以会话的mute_notification为准)
    • 1:不增加红点数
    receivers String[] 消息接收者列表
    msgReadStatusSetting Number 是否显示已读状态。取值:
    • 1:有已读状态
    • 2:无已读状态
    extension {[key: string]: string} 扩展字段
    表 9. ContentModel
    名称 是否必填 类型 描述
    contentType MsgContentType 消息类型。取值:
    • 1:text(文本)
    • 2:图片
    • 3:语音
    • 4:视频
    • 5:地理位置
    • 6:结构化消息
    • 7:链接消息
    • 8:@人消息(复用StructContentModel)
    • 9:文件消息
    • 10:引用回复消息
    • 11:合并转发
    • 101:自定义消息
    text contentType=1时有值 TextContentModel 文本消息内容
    custom contentType=101时有值 CustomContentModel 自定义消息内容
    photo contentType=2时有值 PhotoContentModel 图片消息内容
    audio contentType=3时有值 AudioContentModel 语音消息内容
    video contentType=4时有值 VideoContentModel 视频消息内容
    geo contentType=5时有值 GeoContentModel 地理位置消息内容
    structContent contentType=6或8时有值 StructContentModel 结构化消息内容
    link contentType=7时有值 LinkContentModel 链接消息内容
    fileContent contentType=9时有值 FileContentModel 文件消息内容
    replyContent contentType=10时有值 ReplyContentModel 引用回复内容
    combineForwardContent contentType=11时有值 CombineForwardContentModel 合并转发消息内
    表 10. TextContentModel
    名称 是否必填 类型 描述
    content String 文本内容
    表 11. CustomContentModel
    名称 是否必填 类型 描述
    type Number 自定义消息的子类型
    data String 内容,JSON数据
    表 12. PhotoContentModel
    名称 是否必填 类型 描述
    mediaId String 资源ID
    picSize Number 原始图片大小
    type Number 图片类型
    orientation Number 图片方向。取值:
    • 1:normal
    • 2:flip_horizontal
    • 3:rotate_180
    • 4:flip_vertical
    • 5:transpose
    • 6:rotate_90
    • 7:transverse
    • 8:rotate_270
    filename String 图片文件名
    extension {[key: string]: string} 扩展字段
    表 13. AudioContentModel
    名称 是否必填 类型 描述
    mediaId String 资源ID
    duration Number 语音时长
    表 14. VideoContentModel
    名称 是否必填 类型 描述
    mediaId String 资源ID
    fileName String 文件名
    fileType String 文件类型,取文件后缀
    fileSize Number 文件大小
    duration Number 视频时长
    width Number 视频宽度
    height Number 视频高度
    picMediaId String 封面图片的资源ID(mediaId)
    表 15. GeoContentModel
    名称 是否必填 类型 描述
    picMediaId String 封面图片的资源ID(mediaId)
    latitude Number 纬度
    longitude Number 经度
    locationName String 地理位置名称
    表 16. StructContentModel
    名称 是否必填 类型 描述
    elements ElementModel[] 元素项
    表 17. ElementModel
    名称 是否必填 类型 描述
    elementType Number 元素类型。取值:
    • 1:textElement
    • 3:atElement
    text TextElementModel elementType=1时
    atElement AtElementModel elementType=3时
    表 18. TextElementModel
    名称 是否必填 类型 描述
    content String 文本内容
    表 19. AtElementModel
    名称 是否必填 类型 描述
    uid String 用户ID
    isAtAll Boolean 是否为@所有人
    表 20. LinkContentModel
    名称 是否必填 类型 描述
    URL String 链接地址
    title String 标题
    desc String 描述
    picMediaId String 封面图片资源ID
    extension {[key: string]: string} 扩展字段
    表 21. FileContentModel
    名称 是否必填 类型 描述
    fileName String 文件名
    fileType String 文件类型
    mediaId String 文件资源ID
    fileSize Number 文件大小
    表 22. ReplyContentModel
    名称 是否必填 类型 描述
    referenceMessage ReferenceMessageModel 包含了发送者、消息ID、消息内容等,不支持合并转发消息
    replyContent InnerReplyContentModel 回复具体内容
    表 23. ReferenceMessageModel
    名称 是否必填 类型 描述
    sender String 发送者uid
    appCid String 会话ID
    messageId String 消息ID
    createAt Number 消息创建时间
    referenceContent ReferenceContentModel 消息content内容
    extension {[key: string]: string} 扩展字段
    表 24. InnerReplyContentModel
    名称 是否必填 类型 描述
    contentType MsgContentType 回复内容的消息类型。不支持引用回复和合并转发
    simpleContent SimpleContentModel 消息内容
    replyContent ReplyContentModel 回复的消息内容
    表 25. ReferenceContentModel
    名称 是否必填 类型 描述
    contentType MsgContentType 回复内容的消息类型。不支持引用回复和合并转发
    simpleContent SimpleContentModel 消息内容
    表 26. SimpleContentModel
    名称 是否必填 类型 描述
    text contentType=1时有值 TextContentModel 文本消息内容
    custom contentType=101时有值 CustomContentModel 自定义消息内容
    photo contentType=2时有值 PhotoContentModel 图片消息内容
    audio contentType=3时有值 AudioContentModel 语音消息内容
    video contentType=4时有值 VideoContentModel 视频消息内容
    geo contentType=5时有值 GeoContentModel 地理位置消息内容
    structContent contentType=6或8时有值 StructContentModel 结构化消息内容
    link contentType=7时有值 LinkContentModel 链接消息内容
    fileContent contentType=9时有值 FileContentModel 文件消息内容
    表 27. CombineForwardContentModel
    名称 是否必填 类型 描述
    combineForwardMessages CombineForwardMessageModel[] 合并转发消息列表
    表 28. CombineForwardMessageModel
    名称 是否必填 类型 描述
    sender String 发送者uid
    appCid String 会话ID
    messageId String 消息ID
    createAt Number 消息创建时间
    combineForwardContent InnerCombineForwardContentModel 消息content内容
    extension {[key: string]: string} 扩展字段
    表 29. InnerCombineForwardContentModel
    名称 是否必填 类型 描述
    contentType MsgContentType 消息类型
    simpleContent SimpleContentModel 消息内容
    replyContent ReplyContentModel 回复的消息内容
    表 30. MsgContentType 消息类型
    枚举key 描述
    text 1 文本消息
    photo 2 图片
    audio 3 语音
    video 4 视频
    geo 5 地理位置
    struct 6 结构化消息
    link 7 链接消息
    at 8 @人消息(复用结构化消息)
    file 9 文件消息
    reply 10 引用回复
    combineForward 11 合并转发
    custom 101 自定义消息
    表 31. IMsgStatusType 消息状态
    枚举key 描述
    deleted 0 删除
    normal 1 正常
    recall 2 撤回
    deletedOfReceiver 3 指定接收者删除
    degradation 4 消息降级(拉首屏专用)
    表 32. IRecallOperatorType
    枚举key 描述
    sender 0 发送者撤回
    groupOwner 1 群主撤回
    system 2 系统撤回
    safety 3 安全撤回

Conv

Conv模块是会话相关模块,提供创建会话、置顶会话、移除会话、群加管理员、转让群等API。

会话分为单聊(1对1)、群聊两类。

  • API
    方法 请求参数 返回值 描述
    createSingleConversation CreateSingleChatConversationModel SingleChatUserConversationModel 创建单聊
    hide appCid、conversationType Promise<void> 隐藏/移除会话,会话将不可见,再次接收到消息会变为可见
    hideBatch appCid[]、conversationType Promise<void> hide的批量方法
    updateTypingStatus TypingModel Promise<void> 单聊中显示正在输入状态
    updateDraftMessage appCid、draft void 更新会话草稿,只在本地存储
    getDraftMessage appCid string 获取会话草稿
    mute appCid、isMute、conversationType Promise<void> 设置会话是否免打扰
    setTop appCid、isTop、conversationType Promise<number> 设置会话是否置顶
    clear appCid、conversationType Promise<void> 清空会话所有消息
    clearRedPoint ConversationClearRedPointModel[]、conversationType Promise<void> 批量清除会话红点
    addUserConversation appCid Promise<void> 将自己加入到已知群聊会话
    groupConversationCreate CreateGroupChatConversationV2Model Promise<GroupChatUserConversationModel> 创建群聊会话
    groupConversationDismiss appCid Promise<void> 解散会话
    groupConversationUpdateTitle appCid、title Promise<void> 更新群标题
    groupConversationUpdateIcon appCid、icon Promise<void> 更新群头像
    groupConversationJoin JoinV2Model Promise<void> 群加人
    groupConversationKick KickV2Model Promise<void> 群踢人
    groupConversationLeave appCid Promise<void> 退群
    groupConversationListAllMembers appCid Promise<MemberModel[]> 全量拉群成员
    groupConversationAddAdmins UpdateAdminsModel Promise<void> 添加管理员。调用权限:群主
    groupConversationRemoveAdmins UpdateAdminsModel Promise<void> 删除管理员。调用权限:群主
    groupConversationListAllAdmins appCid Promise<MemberModel[]> 查询全量群管理员。调用权限:群成员
    groupConversationSetOwner SetOwnerModel Promise<void> 转让群主。调用权限:群主
    groupConversationSetPermissionModel SetPermissionModel Promise<void> 设置普通群成员权限。调用权限:群主或群管理员
    groupConversationSilenceAll appCid Promise<void> 设置全员禁言,禁言后仅群主和管理员可发言。调用权限:群主或群管理员
    groupConversationCancelSilenceAll appCid Promise<void> 取消全员禁言。调用权限:群主或群管理员
    groupConversationSilenceAddWhitelist UpdateSilencedWhitelistModel Promise<void> 增加白名单用户。在设置全员禁言后,可以设置白名单,白名单中的用户、群主和管理员可以发言。调用权限:群主或群管理员
    groupConversationSilenceRemoveWhitelist UpdateSilencedWhitelistModel Promise<void> 删除白名单用户。调用权限:群主或群管理员
    groupConversationSilenceAddBlacklist UpdateSilencedBlacklistModel Promise<void> 增加禁言用户。调用权限:群主或群管理员
    groupConversationSilenceRemoveBlacklist UpdateSilencedBlacklistModel Promise<void> 删除禁言用户。调用权限:群主或群管理员
    groupConversationSilenceInfoGet appCid Promise<SilencedInfoModel> 拉取禁言用户列表。调用权限:群主或群管理员
  • 参数类型
    参数 类型 描述
    appCid String 会话ID
    msgId String 消息ID
    conversationType Number 会话类型。取值:
    • 1:单聊
    • 2:群聊
    draft String 草稿内容
    isMute Boolean 是否开启免打扰
    表 33. CreateSingleChatConversationModel
    名称 是否必填 类型 描述
    appCid String 单聊会话ID,双方uid以冒号分隔
    pairFirst String 单聊uid之一
    pairSecond String 单聊uid之一
    extension {[key: string]: string} 扩展字段,默认传“{}”
    表 34. TypingModel
    名称 是否必填 类型 描述
    conversationId String 即AppCid
    type Number 消息类型。取值:
    • 0:文字
    • 1:语音
    • 2:图片
    command Number typing状态。
    • 0:正在typing
    • 1:取消typing
    receiver String typing状态接收者
    表 35. ConversationClearRedPointModel
    名称 是否必填 类型 描述
    appCid String 会话ID
    messageId String 最后一条消息ID
    表 36. CreateGroupChatConversationV2Model
    名称 是否必填 类型 描述
    uuid String 客户端标识
    initMembers String[] 群成员ID列表
    title String 群名称
    icon String 群头像
    extension {[key: string]: string} 扩展字段
    表 37. InitialMemberModel
    名称 是否必填 类型 描述
    user String 群成员ID
    role Number

    成员角色。取值:

    • 1:群主
    • 2:管理员
    • 3:普通
    • 100~127:自定义
    joinTime Number 入群时间戳
    groupNick String 群昵称
    extension {[key: string]: string} 扩展字段
    表 38. JoinV2Model
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    initMembers String[] 群成员ID列表
    表 39. KickV2Model
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    users String[] 群成员ID列表
    表 40. MemberModel
    名称 是否必填 类型 描述
    uid String 成员ID
    role Number

    成员角色。取值:

    • 1:群主
    • 2:管理员
    • 3:普通
    • 100~127:自定义
    createAt Number 入群时间
    groupNick String 群昵称
    extension {[key: string]: string} 扩展字段
    表 41. UpdateAdminsModel
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    users String[] 群成员ID列表
    表 42. SetOwnerModel
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    owner String 群成员ID
    表 43. SetPermissionModel
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    permissionGroup String 权限组
    status Number 权限状态:
    • 0:权限关闭
    • 1:权限开启
    • 2:权限废弃
    表 44. PermissionModel
    名称 是否必填 类型 描述
    permissionGroup String 权限名称
    status Number 权限状态:
    • 0:权限关闭
    • 1:权限开启
    • 2:权限废弃
    表 45. UpdateSilencedWhitelistModel
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    members String[] 群成员ID列表
    表 46. UpdateSilencedBlacklistModel
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    members String[] 群成员ID列表
    silenceDuration Number 禁言时长,单位:ms。例如:5分钟则设置为300000(5×60×1000)
    表 47. SilencedInfoModel
    名称 是否必填 类型 描述
    appCid String 群聊会话ID
    blacklistInfo SilencedBlacklistMemberInfoModel[] 黑名单列表
    whitelistInfo SilencedWhitelistMemberInfoModel[] 白名单列表
    表 48. SilencedBlacklistMemberInfoModel
    名称 是否必填 类型 描述
    uid String 用户ID
    endTime Number 禁言截止时间。单位:ms
    operateTime Number 操作时间。单位:ms
    operateUid String 把uid加入黑名单的操作者ID
    表 49. SilencedWhitelistMemberInfoModel
    名称 是否必填 类型 描述
    uid String 用户ID
    operateTime Number 操作时间。单位:ms
    operateUid String 把uid加入黑名单的操作者ID
    表 50. UserConversationModel
    名称 是否必填 类型 描述
    type Number 会话类型。取值:
    • 1:单聊
    • 2:群聊
    singleChatUserConversation type=1时有值 SingleChatUserConversationModel 单聊数据模型
    groupChatUserConversation type=2时有值 GroupChatUserConversationModel 群聊数据模型
    表 51. SingleChatUserConversationModel
    名称 是否必填 类型 描述
    singleChatConversation SingleChatConversationModel 单聊详情数据模型
    visible Number 是否首屏显示。取值:
    • 0:首屏不显示
    • 1:首屏显示
    topRank Number 置顶值
    redPoint Number 会话红点数量
    muteNotification Number 免打扰状态。取值:
    • 0:免打扰关闭
    • 1:免打扰开启
    joinTime Number 会话加入时间
    modifyTime Number 会话变更时间
    lastMessage UserMessageModel 会话最后一条消息
    user_extension {[key: string]: string} 扩展信息
    last_message_time Number 最后一条消息时间
    表 52. SingleChatConversationModel
    名称 是否必填 类型 描述
    appCid String 单聊会话ID,双方uid以冒号分隔
    pairFirst String 单聊uid之一
    pairSecond String 单聊uid之一
    joinTime Number 会话创建时间,单位:ms
    extension {[key: string]: string} 业务扩展信息
    表 53. GroupChatUserConversationModel
    名称 是否必填 类型 描述
    groupChatConversation GroupChatConversationModel 群聊详情数据模型
    visible Number 是否首屏显示。取值:
    • 0:首屏不显示
    • 1:首屏显示
    topRank Number 置顶值
    redPoint Number 会话红点数量
    muteNotification Number 免打扰状态。取值:
    • 0:免打扰关闭
    • 1:免打扰开启
    joinTime Number 会话加入时间
    modifyTime Number 会话变更时间
    silencedStatus Number 禁言类型。取值:
    • 0:既不在白名单也不在黑名单
    • 1:白名单
    • 2:黑名单
    silencedEndTime Number 禁言截止时间点,单位:ms
    lastMessage UserMessageModel 会话最后一条消息
    表 54. GroupChatConversationModel
    名称 是否必填 类型 描述
    appCid String 群聊ID
    ownerUid String 群主ID
    title String 群标题/群名称
    icon String 群头像
    memberCount Number 群人数
    memberLimit Number 群人数上限
    createAt Number 群创建时间
    silenceAll Number 全员禁止发言。取值:
    • 0:可以发言
    • 1:全员禁言(仅群主或管理员可发言)
    admins String[] admins列表
    memberPermissions PermissionModel[] 普通群成员的权限设置
    extension {[key: string]: string} 业务扩展信息

Event

Event模块是事件相关模块,DataSDK会监听事件,然后更新DataSDK中store的数据。

  • API
    方法 请求参数 返回值 描述
    register EventNameEnum, data: any)=> Function 监听事件
    表 55. EventNameEnum
    枚举key 描述
    PaaSConnectionChanged 连接状态更新
  • 参数类型
  • 示例代码
    React.useEffect(() => {
      imsdk.getEventService().register((eventName: EventNameEnum, eventData: any) => {
        console.log('== event ==', { eventName, eventData })
        switch (eventName) {
          case EventNameEnum.PaaSConnectionChanged:
            setLoginStatus(eventData as ConnectionStatus) // 登录成功
            break;
        }
      })
    }, [])

Logger

Logger模块是日志和错误相关,包含info和error方法,会触发Setting模块配置的对应处理函数。

  • API
    方法 请求参数 返回值 描述
    info any void info日志
    error any void error日志
    表 56. LocalLogType
    枚举key 描述
    INFO INFO info类型日志
    ERROR ERROR error类型日志
  • 参数类型
  • 示例代码
    imsdk.getLoggerService().error(LocalLogType.ERROR, 'authTokenCallback catch')