Custom Message Types

In addition to using the built-in message types provided by the IMLib SDK, you can also create custom message types.

You need to select the appropriate message base class for your custom message type based on business requirements:

• RCMessageContent: Standard message content. For example, built-in message types like text messages and location messages that don't require media file uploads.
• RCMediaMessageContent: Multimedia message content. Inherits from RCMessageContent and adds logic for handling multimedia files. When sending or receiving messages, the IMLib SDK checks whether the message is a multimedia type and triggers the upload/download process accordingly.

For more information about message entity classes and message content, see Message Introduction.

Creating Custom Message Types

Custom message type classes must conform to the following three protocols:

• Encoding/Decoding Protocol (Required): RCMessageCoding specifies the message type name, encoding/decoding behavior during message transmission, and provides keywords for message search. This protocol is mandatory for all custom message types; otherwise, they cannot be transmitted or used properly.
• Storage Protocol (Required): RCMessagePersistentCompatible specifies whether the message type is stored on the client and server and whether it counts toward unread message totals.
• Content Digest Protocol (Optional): RCMessageContentView defines how to display a summary of this message type.

tip

• All custom message types must implement the RCMessageCoding and RCMessagePersistentCompatible protocols; otherwise, they cannot be transmitted or used properly.

Encoding/Decoding Protocol

Protocol Prototype:

@protocol RCMessageCoding <NSObject>

The encoding/decoding protocol (RCMessageCoding) has the following key functions:

• Provides a unique ID (ObjectName) for the custom message type.
• Encodes all message information into JSON data for transmission when sending a message.
• Decodes JSON data back into a message object when receiving a message.
• Provides data for message search.

To conform to this protocol, implement the following methods:

• Serialization: Encodes all message data into JSON for network transmission.

  - (NSData *)encode;

• Deserialization: Decodes JSON data from network transmission to reconstruct the message content.

  - (void)decodeWithData:(NSData *)data;

• Define Message Type Name: The message type name must be consistent across all platforms to ensure interoperability. Avoid using names starting with RC: to prevent conflicts with SDK default message types.

  + (NSString *)getObjectName;

• Provide Searchable Words: Returns keywords if the message should be searchable; otherwise, returns nil.

  - (NSArray<NSString *> *)getSearchableWords;

Storage Protocol

The storage protocol (RCMessagePersistentCompatible) is mandatory.

Protocol Prototype:

@protocol RCMessagePersistentCompatible <NSObject>

This protocol has two main functions:

• Specifies whether the message type is stored locally and on the server.
• Indicates whether the message counts toward unread message totals.

To conform to this protocol, implement the method to control message storage and counting policies:

+ (RCMessagePersistent)persistentFlag;

persistentFlag Property	Client Storage	Server Storage	Counts Toward Unread
MessagePersistent_NONE	Not stored	Supports offline messaging?	Excluded
MessagePersistent_ISCOUNTED	Stored	Supports offline messaging? and server history	Included
MessagePersistent_ISPERSISTED	Stored	Supports offline messaging? and server history	Excluded
MessagePersistent_STATUS	Not stored	Not stored	Excluded

tip

• MessagePersistent_NONE is typically used for operational messages that must be received but not displayed (e.g., commands from a management platform). If the recipient is offline, they will receive the message upon reconnecting.
• MessagePersistent_STATUS is for status messages (e.g., typing indicators). These messages are neither stored nor retransmitted if the recipient is offline.

Content Digest Protocol

The content digest protocol (RCMessageContentView) is optional.

Protocol Prototype:

@protocol RCMessageContentView

Message digests are displayed in:

• The conversation list
• Local notifications

To conform to this protocol, implement the method to set the message digest:

- (NSString *)conversationDigest;

Registering Custom Message Types

After defining a custom message class, you must register it with the IMLib SDK after initialization but before connecting to IM.

tip

Only registered message types can be properly encoded/decoded by the IMLib SDK. Unregistered types are treated as RC:UnknownMsg.

- (void)registerMessageType:(Class)messageClass;

Sending Custom Messages

Custom message types can be sent using the same methods as built-in message types.

tip

• For custom messages inheriting RCMessageContent, use the sendMessage interface for standard messages.
• For custom messages inheriting RCMediaMessageContent, use the sendMediaMessage interface for media messages.

For detailed sending methods and configurations, refer to:

• App with IMLib SDK Only: Sending Messages (one-to-one, group, chatroom), [Messaging] (ultra group)

Custom Message Push Notifications

To enable push notifications for custom messages, you must specify push content (pushContent) when sending the message. This content appears in the notification bar when the recipient receives the push.

• Specify push content directly via the pushContent parameter when sending the message.
• Alternatively, configure pushContent and other fields in the messagePushConfig of RCMessage for personalized push settings. The messagePushConfig settings take precedence. See Configuring Push Attributes for Messages.

tip

• If the RC server cannot retrieve pushContent for a custom message, push notifications will not be triggered (e.g., when the recipient is offline).
• Status messages (MessagePersistent_STATUS) do not support push notifications and do not require push content.

Example

Custom Message Demo