tencent cloud

文档反馈

Web&小程序&uni-app

最后更新时间:2023-04-03 16:29:04

    功能描述

    消息扩展可以为消息增加 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 电话支持