Custom Message Types

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

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

• RCMessageContent, which is the content of a regular message. For example, text messages and location messages in the SDK's built-in message types.
• RCMediaMessageContent, which is a multimedia message type. Multimedia message content inherits from RCMessageContent and adds logic for handling multimedia files. When sending and receiving messages, the SDK will determine if the message type is a multimedia message. If it is, the upload or download process for multimedia files will be triggered.

For more information on message entity classes and message content, refer to Message Introduction.

Creating Custom Message Types

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

• Encoding and Decoding Protocol (Mandatory): RCMessageCoding specifies the message type name, the encoding and decoding behavior during message transmission, and provides keywords required for message search. This protocol must be implemented by all custom message types; otherwise, the message cannot be transmitted or used normally.
• Storage Protocol (Mandatory): RCMessagePersistentCompatible specifies whether this message type is counted in the unread message count and whether it is stored on the client and server.
• Content Summary Protocol (Optional): RCMessageContentView defines how to display the summary of this type of message.

Encoding and Decoding Protocol

tip

Any custom message type must implement the RCMessageCoding protocol; otherwise, it cannot be transmitted or used normally.

Protocol Prototype:

@protocol RCMessageCoding <NSObject>

The encoding and decoding protocol (RCMessageCoding) has the following main functions:

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

To comply with the encoding and decoding protocol, the following methods must be implemented:

• Serialization: The message content encodes all data into JSON through this method. The returned JSON data will be used for network transmission.

  - (NSData *)encode;

• Deserialization: The JSON data transmitted over the network is decoded through this method to retrieve all data in the message content and generate a valid message content.

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

• Define Message Type Name: The defined message type name must be consistent across all platforms; otherwise, messages cannot be exchanged. To avoid conflicts with the SDK's default message type names, do not use type names that start with RC:.

  + (NSString *)getObjectName;

• Provide Message Search Data: If the custom message needs to be searchable, return the keywords. If not, return nil directly.

  - (NSArray<NSString *> *)getSearchableWords;

Storage Protocol

The storage protocol (RCMessagePersistentCompatible) is mandatory.

Protocol Prototype:

@protocol RCMessagePersistentCompatible <NSObject>

The storage protocol has two main functions:

• Indicates whether this message type is stored locally and on the server.
• Indicates whether this message type is counted in the unread message count.

To comply with the storage protocol, the method for controlling the message storage count policy must be implemented:

+ (RCMessagePersistent)persistentFlag;

persistentFlag Property Description	Client Storage	Server Storage	Counted in Unread Messages
MessagePersistent_NONE	Not stored on client	Supports offline message? mechanism	Not counted in unread messages
MessagePersistent_ISCOUNTED	Stored on client	Supports offline message? mechanism and stored in server history	Counted in unread messages
MessagePersistent_ISPERSISTED	Stored on client	Supports offline message? mechanism and stored in server history	Not counted in unread messages
MessagePersistent_STATUS	Not stored on client	Not stored on server	Not counted in unread messages

tip

• MessagePersistent_NONE is generally used for messages that need to be received but not displayed, such as command information sent from an operations platform to a terminal. If the message recipient is offline, they can receive the message through the offline message mechanism when they come back online.
• MessagePersistent_STATUS is used for status messages. Status messages represent immediate states, such as typing status. Since status messages are not stored on the client or server, if the recipient is offline, they cannot receive the status message.

Content Summary Protocol

The content summary protocol (RCMessageContentView) is optional.

Protocol Prototype:

@protocol RCMessageContentView

The message content summary is displayed in the following places:

• In the conversation list.
• In local notifications.

To comply with the content summary protocol, the method for setting the message summary must be implemented:

- (NSString *)conversationDigest;

Registering Custom Message Types

After creating the custom message class, you need to register this custom message class after SDK initialization but before connecting.

tip

Only after registering the message type can the SDK correctly identify and encode/decode messages of this type.

- (void)registerMessageType:(Class)messageClass;

Sending Custom Messages

Custom message types can be sent directly using the methods for sending built-in message types. Please choose the appropriate core class and method based on the SDK, business, and message type currently in use:

• If the custom message type inherits from RCMessageContent, use the interface for sending regular messages.
• If the custom message type inherits from RCMediaMessageContent, use the interface for sending media messages.

If the custom message type needs to support push notifications, you must additionally specify the push content (pushContent) when sending the custom message. The push content is displayed in the notification bar when the recipient receives the push.

• When sending the message, you can directly specify the push content through the pushContent parameter.
• You can also configure the push notification for the message by setting the pushContent and other fields in the messagePushConfig of RCMessage. The configuration in messagePushConfig takes precedence. For details, refer to Configuring Push Attributes for Messages.

For specific methods and configuration details for sending messages, refer to the following documents:

• App Only Integrates IMLib SDK: Sending Messages (one-to-one chat, group chat, chatroom)

tip

• If RC's server cannot obtain the pushContent of the custom message, the message push cannot be triggered. For example, if the recipient is offline, they will not receive the push notification.
• If the custom message type is a status message (MessagePersistent_STATUS), it cannot support push notifications, and there is no need to specify push content.