Streaming Messages

This document describes how to use the IMLib SDK to retrieve streaming messages in one-to-one chats and group chats.

tip

This feature is supported starting from version 5.16.1.

Introduction to Streaming Messages

Streaming messages are triggered by the business server, generated by the RC IM server, and delivered to the client SDK. Upon receiving a streaming message, the client SDK can initiate message retrieval based on business requirements and handle corresponding event callbacks. Below is the sequence diagram:

The IMLib SDK defines the StreamMessage object, which inherits from MessageContent. The table below describes key attributes of the StreamMessage class. For a complete attribute list, refer to the API documentation.

StreamMessage data structure:

Attribute	Type	Description
content	String	Streaming message content.
type	String	Text format of the streaming message.
isComplete	boolean	Whether streaming message content generation is complete.
completeReason	int	Reason for abnormal termination of streaming message content, provided by the business server.
stopReason	int	Reason for abnormal termination of streaming message content, provided by RC server (0 indicates normal termination).
isSync	boolean	Flag indicating whether the client has completed streaming retrieval.
referMsg	ReferenceInfo	Reference information of the streaming message.

tip

• Streaming messages cannot be sent by the SDK; they can only be delivered by the server. After receiving a streaming message, the SDK passes it to the business layer via the RongCoreClient's addOnReceiveMessageListener(listener) callback interface.
• After receiving a streaming message, use the RongCoreClient's requestStreamMessageContent(params, callback) interface to retrieve the complete content.

Receiving Streaming Messages

The SDK does not support sending streaming messages. Developers must trigger streaming messages via server APIs, and recipients will receive them.

Adding Message Listeners

Applications can set up message reception listeners via the addOnReceiveMessageListener method and handle streaming messages in the callback.

RongCoreClient.addOnReceiveMessageListener(new OnReceiveMessageWrapperListener() {
    @Override
    public boolean onReceivedMessage(Message message, ReceivedProfile profile) {
        if (message.getContent() instanceof StreamMessage) {
            // TODO
        }
    }
});

Historical Streaming Messages

After receiving streaming messages, the SDK stores them in the local database. Developers can query streaming messages when calling [Retrieve Historical Messages] APIs.

Retrieving Streaming Messages

The content of a streaming message defaults to the initial packet content. After obtaining a streaming message, developers need to retrieve its complete content via the requestStreamMessageContent(params, callback) interface.

Adding Streaming Message Retrieval Event Delegates

Developers can call the addStreamMessageRequestEventListener() method to add streaming message retrieval event listeners.

RongCoreClient.getInstance().addStreamMessageRequestEventListener();

The streaming message retrieval process consists of three events: onInit, onData, and onComplete, corresponding to the following delegate methods:

interface StreamMessageRequestEventListener {
    /**
     * Callback when request preparation is complete. Cleans up abnormal data if the message was previously terminated abnormally.
     *
     * @param messageUid Unique message identifier
     */
    void onInit(String messageUid);

    /**
     * Callback when receiving streaming fragments (incremental data).
     *
     * @param message Message object
     * @param chunkInfo Streaming message fragment information
     */
    void onData(Message message, StreamMessageChunkInfo chunkInfo);

    /**
     * Callback when streaming fragment reception is complete (termination reason indicated by code).
     *
     * @param messageUid Unique message identifier
     * @param code Termination reason
     */
    void onComplete(String messageUid, IRongCoreEnum.CoreErrorCode code);
}

Parameters for onData:

Parameter	Type	Description
message	Message	Streaming message.
chunkInfo	StreamMessageChunkInfo	Streaming message fragment information.

Initiating Streaming Message Retrieval Requests

After obtaining a streaming message, developers can check the isSync parameter to determine if synchronization is complete. If false, developers can retrieve the streaming message as needed:

StreamMessageRequestParams params = StreamMessageRequestParams.obtain(message.getUId());
RongCoreClient.getInstance().requestStreamMessageContent(params, new IRongCoreCallback.OperationCallback() {
    @Override
    public void onSuccess() {
    }

    @Override
    public void onError(IRongCoreEnum.CoreErrorCode coreErrorCode) {
    }
});

tip

• The IRongCoreCallback.OperationCallback parameter in the request interface handles logical validation and request result callbacks, while the StreamMessageRequestEventListener handles streaming message event callbacks after the request is initiated.

Streaming Message Summaries

After the server completes streaming message content reception, it notifies the client of the message summary via Message Extension.

Registering Message Extension Update Listeners

Developers can register message extension update listeners via setMessageExpansionListener.

RongIMClient.getInstance().setMessageExpansionListener(listener);

Retrieving Streaming Message Summaries

When the client receives a message extension update, it can obtain the streaming message summary via the summary extension key (RC_Ext_StreamMsgSummary).

RongIMClient.getInstance().setMessageExpansionListener(new RongIMClient.MessageExpansionListener() {
    @Override
    public void onMessageExpansionUpdate(Map<String, String> expansion, Message message) {
        if (message.getContent() instanceof StreamMessage) {
            String summery = expansion.get("RC_Ext_StreamMsgSummary");
            // TODO
        }
    }

    @Override
    public void onMessageExpansionRemove(List<String> keyArray, Message message) {
    }
});

Retrieving Historical Streaming Message Summaries

When the client receives a message extension update, summary information is stored in the database. Developers can use the isComplete attribute of streaming messages to retrieve historical message summaries.

if (message.getContent() instanceof StreamMessage) {
    StreamMessage streamMessage = (StreamMessage) message.getContent();
    if (streamMessage.isComplete()) {
        String summery = message.getExpansion().get("RC_Ext_StreamMsgSummary");
        // TODO
    }
}