tencent cloud

PrevNext

文档反馈

请输入关键字

Recent Pages

文档
即时通信 IM
    文档
    Download PDF

    Web&小程序&uni-app

    最后更新时间：2023-04-03 16:29:04
    下载PDF

      功能描述

      消息扩展可以为消息增加 key/value 状态标识。基于消息扩展，我们可以实现投票、接龙、问卷调查等功能。

      • 在投票场景，我们可以先通过 createCustomMessage 接口创建一条用于投票的自定义消息，其中 data 存储投票的标题和选项，然后用消息扩展 key 存储投票用户 ID，用消息扩展 value 存储投票用户选项，有了每个用户的投票选项，我们就可以动态计算出投票选项的用户占比。
      • 在接龙场景，我们可以先通过 createCustomMessage 接口创建一条用于接龙的自定义消息，其中 data 存储接龙的标题，然后用消息扩展 key 存储接龙用户 ID，用消息扩展 value 存储接龙信息。
      • 在问卷调查场景，我们可以先通过 createCustomMessage 接口创建一条用于问卷调查的自定义消息，其中 data 存储问卷调查的标题和选项，然后用消息扩展 key 存储问卷调查的用户 ID，用消息扩展 value 存储问卷调查信息。
      说明：

      • 该功能仅对旗舰版客户开放，购买 旗舰版 后可使用。
      • 该功能 v2.25.0 及以上版本支持。
      • 该功能需要先在 即时通信 IM 控制台 > 功能配置 > 登录与消息 > 消息扩展设置中开启。
      • 社群（Community）和直播群（AVChatRoom）消息不支持该功能。

      设置消息扩展

      调用 setMessageExtensions 接口可以设置消息扩展，如果扩展 key 已经存在，则修改扩展的 value 信息，如果扩展 key 不存在，则新增扩展。设置成功后，自己和对端用户（C2C）或群组成员（Group）都会收到 TIM.EVENT.MESSAGE_EXTENSIONS_UPDATED 事件。

      接口

      tim.setMessageExtensions(message, extensions);

      参数

      Name Type Description
      message Message 消息实例
      extensions Array 消息扩展 key-value 列表，如果扩展 key 已经存在，则修改扩展的 value 信息，如果扩展 key 不存在，则新增扩展。
      说明：

      1. 消息需满足三个条件：
      • 消息的 isSupportExtension 属性必须为 true
      • 消息必须是发送成功的状态
      • 消息不能是社群（Community）和直播群（AVChatRoom）消息
      1. 扩展 key 最大支持 100 字节，扩展 value 最大支持 1KB，单次最多支持设置 20 个扩展，单条消息最多可设置 300 个扩展。
      2. 当多个用户同时设置或删除同一个扩展 key 时，只有第一个用户可以执行成功，其它用户会在设置回包收到 23001 错误码和最新的扩展信息，在收到错误码和扩展信息后，请按需重新发起设置操作。
      3. 我们强烈建议不同的用户设置不同的扩展 key，这样大部分场景都不会冲突，例如投票、接龙、问卷调查，都可以把自己的 userID 作为扩展 key。

      返回值

      Promise 对象。

      示例 

      let promise = tim.setMessageExtensions(message, [{ key: 'a', value: '1' }, { key: 'b', value: '2' }]);
      promise.then(function(imResponse) {
        // 设置消息扩展成功
         const { extensions } = imResponse.data;
         extensions.forEach((item) => {
           const { code, key, value } = item;
           if (code === 23001) {
             // 设置 key 冲突，请根据返回的最新扩展信息，按需进行重试
           }
         });
      }).catch(function(imError) {
        // 设置消息扩展失败
        console.warn('setMessageExtensions error:', imError);
      });

      获取消息扩展

      调用 getMessageExtensions 接口获取消息扩展列表。

      接口

      tim.getMessageExtensions(message);

      参数

      Name Type Description
      message Message 消息实例
      说明：


      消息需满足三个条件：

      • 消息的 isSupportExtension 属性必须为 true
      • 消息必须是发送成功的状态
      • 消息不能是社群（Community）和直播群（AVChatRoom）消息

      返回值

      Promise 对象。

      示例

      let promise = tim.getMessageExtensions(message);
      promise.then(function(imResponse) {
        // 获取消息扩展成功
         const { extensions } = imResponse.data;
         extensions.forEach((item) => {
           const { key, value } = item;
           // key - 消息扩展 key
           // value - 消息扩展 key 对应的 value 值
         });
      }).catch(function(imError) {
        // 获取消息扩展失败
        console.warn('getMessageExtensions error:', imError);
      });

      删除消息扩展

      调用 deleteMessageExtensions 接口删除指定消息扩展，如果 keyList 字段不传，则会清空所有消息扩展。删除成功后，自己和对端用户（C2C）或群组成员（Group）都会收到 TIM.EVENT.MESSAGE_EXTENSIONS_DELETED 事件。

      接口

      tim.deleteMessageExtensions(message, keyList);

      参数

      Name Type Description
      message Message 消息实例
      keyList Array|undefined 消息扩展 key 列表。
      说明：

      1. 消息需满足三个条件：
      • 消息的 isSupportExtension 属性必须为 true
      • 消息必须是发送成功的状态
      • 消息不能是社群（Community）和直播群（AVChatRoom）消息
      1. 当多个用户同时设置或删除同一个扩展 key 时，只有第一个用户可以执行成功，其它用户会收到 23001 错误码和最新的扩展信息，在收到错误码和扩展信息后，请按需重新发起删除操作。

      返回值

      Promise 对象。

      示例

      // 删除消息扩展 key
      let promise = tim.deleteMessageExtensions(message, ['a', 'b']);
      promise.then(function(imResponse) {
         // 删除消息扩展成功
         const { extensions } = imResponse.data;
         extensions.forEach((item) => {
           const { code, key, value } = item;
           if (code === 23001) {
             // 删除 key 冲突，请根据返回的最新扩展信息，按需进行重试
           }
         });
      }).catch(function(imError) {
        // 删除消息扩展失败
        console.warn('deleteMessageExtensions error:', imError);
      });
      // 清空所有消息扩展 key
      let promise = tim.deleteMessageExtensions(message);
      promise.then(function(imResponse) {
         // 清空消息扩展成功
         console.log('deleteMessageExtensions ok:', imResponse)
      }).catch(function(imError) {
        // 清空消息扩展失败
        console.warn('deleteMessageExtensions error:', imError);
      });

      消息扩展更新

      如果您提前注册了 TIM.EVENT.MESSAGE_EXTENSIONS_UPDATED 事件，当消息扩展发生了新增或者更新时，SDK 会派发 TIM.EVENT.MESSAGE_EXTENSIONS_UPDATED 事件，您可以在注册的回调中获取到更新的 key-value 信息。

      示例

      let onMessageExtensionsUpdated = function(event) {
        const { messageID, extensions } = event.data;
        // messageID - 消息 ID
        // extensions - 消息扩展列表
        extensions.forEach((item) => {
         const { key, value } = item;
         // key - 消息扩展 key
         // value - 消息扩展 key 对应的 value 值
        });
      };
      tim.on(TIM.EVENT.MESSAGE_EXTENSIONS_UPDATED, onMessageExtensionsUpdated);

      消息扩展删除

      如果您提前注册了 TIM.EVENT.MESSAGE_EXTENSIONS_DELETED 事件，当消息被删除时，SDK 会派发 TIM.EVENT.MESSAGE_EXTENSIONS_DELETED 事件，您可以在注册的回调中获取到被删除的 key。
      示例

      let onMessageExtensionsDeleted = function(event) {
        const { messageID, keyList } = event.data;
        // messageID - 消息 ID
        // keyList - 被删除的消息扩展 key 列表
        keyList.forEach((key) => {
         // console.log(key)
        });
      };
      tim.on(TIM.EVENT.MESSAGE_EXTENSIONS_DELETED, onMessageExtensionsDeleted);
      联系我们

      联系我们，为您的业务提供专属服务。

      联系我们
      技术支持

      如果你想寻求进一步的帮助，通过工单与我们进行联络。我们提供7x24的工单服务。

      提交工单
      7x24 电话支持
      Copyright © 2013-2023 Tencent Cloud. All Rights Reserved.
      隐私条款服务条款缓存条款