Receive tip messages

Overview

The ZIM SDK converts some user operations on a group (such as group creation and disbandment) into tip messages, A tip message is a special type of message, whose enumeration value is 32. Tip messages can be generated only by the ZIM backend or ZIM SDK. Users cannot insert tip messages into local conversations, set the read receipt or response for them, or directly delete them. However, users can delete a tip message by deleting all messages in a conversation.

Note

Only ZIM SDK 2.15.0 or later supports tip messages.

Procedure

1. Enable the feature

To enable the tip message feature for the following events, contact ZEGOCLOUD technical support.

Type	Event
Group management	Note When enabling this event type, all events will be enabled. Group creation Group dismissal User joined User joined by invitation Member leave Member removal
Group profile Changes	Note When enabling this event type, please specify the events you need. Group name change Group avatar change Group notice change Group muting status change
Group member information change	Note When enabling this event type, please specify the events you need. Group ownership change Group member role change Group role muting status change

2. Receive a tip message

Listen for the receiveGroupMessage callback to receive the tip message when a group event occurs.

If the group event (ZIMTipsMessageEvent) is a group profile change (ZIMTipsMessageEvent.GROUP_INFO_CHANGED) or group member information change (ZIMTipsMessageEvent.GROUP_MEMBER_INFO_CHANGED), do the following:

Change the changeInfo in the tip message to ZIMTipsMessageGroupChangeInfo or ZIMTipsMessageGroupMemberChangeInfo.
Based on the type in the changeInfo, obtain the event type (ZIMTipsMessageChangeInfoType) and determine the field to be read from the changeInfo. The ZIM SDK does not assign values to irrelevant fields. For more information, see the sample code at the end of this topic.

The following table describes the relationship between the ZIMTipsMessageEvent and the ZIMTipsMessageChangeInfoType.

Event (`ZIMTipsMessageEvent`)	Enumeration	Value	Read from `ZIMTipsMessageGroupChangeInfo`
Group creation	GROUP_CREATED	1	Not required
Group disbandment	GROUP_DISMISSED	2
User joined	GROUP_JOINED	3
User joined by invitation	GROUP_INVITED	4
Member leave	GROUP_LEFT	5
Member removal	GROUP_KICKED_OUT	6
Group profile change	GROUP_INFO_CHANGED	7	Required
Extra information （ZIMTipsMessageChangeInfoType）	Enumeration	Value	Read from `ZIMTipsMessageGroupChangeInfo`
Change of multiple items of the group name, group avatar, and group notice	GROUP_DATA_CHANGED	1	Perform a bitwise operation based on the `groupDataFlag` to calculate multiple items of the group name, group notice, and group avatar.
Group notice change	GROUP_NOTICE_CHANGED	2	Read the `groupNotice` field from `ZIMTipsMessageGroupChangeInfo`.
Group name change	GROUP_NAME_CHANGED	3	Read the `groupName` field from `ZIMTipsMessageGroupChangeInfo`.
Group avatar change	GROUP_AVATAR_URL_CHANGED	4	Read the `groupAvatarUrl` field from `ZIMTipsMessageGroupChangeInfo`.
Group muting status change	GROUP_MUTE_CHANGED	5	Read the `groupMutedInfo` field from `ZIMTipsMessageGroupChangeInfo`.
Group member information change	GROUP_MEMBER_INFO_CHANGED	8	Depends on the extra information.
Extra information （ZIMTipsChangeInfoType）	Enumeration	Value	Read from `ZIMTipsMessageGroupMemberChangeInfo`
Group ownership change	GROUP_OWNER_TRANSFERRED	10	Not required
Group member role change	GROUP_MEMBER_ROLE_CHANGED	11	Read the `memberRole` field from `ZIMTipsMessageGroupMemberChangeInfo`.
Group role muting status change	GROUP_MEMBER_MUTE_CHANGED	12	Read the `muteExpiredTime` field from `ZIMTipsMessageGroupMemberChangeInfo`.

Untitled

// Receive a group message.
void zim_event_handler::onReceiveGroupMessage(
    zim::ZIM *, const std::vector<std::shared_ptr<zim::ZIMMessage>> &messageList,
    const std::string &fromGroupID) {

    for (const auto &message: messageList) {
        // It is a tip message.

        if (message->getType() == zim::ZIMMessageType::ZIM_MESSAGE_TYPE_TIPS) {
            auto tips_message = std::static_pointer_cast<zim::ZIMTipsMessage>(message);
            // It is a group profile change event.
            if (tips_message->getEvent() == zim::ZIMTipsMessageEvent::ZIM_TIPS_MESSAGE_EVENT_GROUP_INFO_CHANGED) {
                auto info = std::static_pointer_cast<zim::ZIMTipsMessageGroupChangeInfo>(tips_message->getChangeInfo());

                if (info->getType() == zim::ZIMTipsMessageChangeInfoType::ZIM_TIPS_MESSAGE_CHANGE_INFO_TYPE_GROUP_DATA_CHANGED) {
                    if (info->getGroupDataFlag() & ZIM_GROUP_DATA_FLAG_NAME) {
                        // Group name change.
                        auto new_group_name = info->getGroupName();
                    }

                    if (info->getGroupDataFlag() & ZIM_GROUP_DATA_FLAG_NOTICE) {
                        // Group notice change.
                        auto new_group_notice = info->getGroupNotice();
                    }

                    if (info->getGroupDataFlag() & ZIM_GROUP_DATA_FLAG_AVATAR_URL) {
                        // Group avatar change.
                        auto new_group_avatar_url = info->getGroupAvatarUrl();
                    }
                }
            
                ......//  The business logic.
            } else if (tips_message->getEvent() == zim::ZIMTipsMessageEvent::ZIM_TIPS_MESSAGE_EVENT_GROUP_MEMBER_INFO_CHANGED) {
                // It is a group member information change event.
                auto info = std::static_pointer_cast<zim::ZIMTipsMessageGroupMemberChangeInfo>(tips_message->getChangeInfo());
                ......// The business logic.
            }
            ......
        }
    }

}

Copied!

Untitled

// Receive a group message.
- (void)receiveGroupMessage:(ZIM *)zim 
                 messageList:(NSArray<ZIMMessage *> *)messageList 
                  fromGroupID:(NSString *)fromGroupID {
    
    for (ZIMMessage *message in messageList) {
        // It is a tip message.
        if (message.type == ZIMMessageTypeTips) {
            ZIMTipsMessage *tipsMessage = (ZIMTipsMessage *)message;
            // It is a group profile change event.
            if (tipsMessage.event == ZIMTipsMessageEventGroupInfoChanged) {
                ZIMTipsMessageGroupChangeInfo *info = (ZIMTipsMessageGroupChangeInfo *)tipsMessage.changeInfo;
                
                if (info.type == ZIMTipsMessageChangeInfoTypeGroupDataChanged) {
                    if (info.groupDataFlag & ZIMGroupDataFlagName) {
                        // Group name change.
                        NSString *newGroupName = info.groupName;
                    }
                    
                    if (info.groupDataFlag & ZIMGroupDataFlagNotice) {
                        // Group notice change.
                        NSString *newGroupNotice = info.groupNotice;
                    }
                    
                    if (info.groupDataFlag & ZIMGroupDataFlagAvatarUrl) {
                        // Group avatar change.
                        NSString *newGroupAvatarUrl = info.groupAvatarUrl;
                    }
                }
                
                // The business logic.
            } else if (tipsMessage.event == ZIMTipsMessageEventGroupMemberInfoChanged) {
                // It is a group member information change event.
                ZIMTipsMessageGroupMemberChangeInfo *info = (ZIMTipsMessageGroupMemberChangeInfo *)tipsMessage.changeInfo;
                
                // The business logic.
            }
            
            // Other business logic.
        }
    }
}

Copied!

3. Display a tip message

Based on the obtained tip message, generate the corresponding event string and display the event string on the UI.