Message history (Beta)

The Signaling message history feature allows you to store messages when publishing them to a channel. For example, if a user joins a channel midway through a conversation, you can retrieve messages that were published before the user joined. You can configure the message retention period for each project, ranging from 1 day to permanent storage.

When a message is published, it is stored using the channel name and the message timestamp. You can use this information to retrieve historical messages.

The historical message feature is currently available for User Channels and Message Channels, but not for Stream Channels.

Prerequisites

Before implementing this feature, ensure that you have:

Integrated the Signaling SDK in your project, and implemented the framework functionality from the SDK quickstart page.
Enabled the message history feature by contacting support@agora.io. You can request a storage duration of 1, 7, 30, 90, or 365 days, or opt for permanent storage.

Changes to storage duration only affect future messages.

Implement message history

This section shows how to store and retrieve messages from history.

Store messages

To store a message on the server, set setStoreInHistory to true in the publish() method. The following example shows the minimum code to store a message published to a message channel:

try {
  const result = await rtm.publish(
    "chatroom",
    "Hello world!",
    {
      channelType: "MESSAGE",
      customType: "STRING",
      storeInHistory: true, // Overrides the default storage option
    }
  );
} catch (status) {
  console.log(status);
}

To store a message in the history of a user channel, use the same parameter:

try {
  const result = await rtm.publish(
    "Tony", // User ID
    "Hello world!",
    {
      channelType: "USER",
      customType: "STRING",
      storeInHistory: true, // Overrides the default storage option
    }
  );
} catch (status) {
  console.log(status);
}

Retrieve messages

The SDK provides the getMessages() method to retrieve up to 100 history messages at a time. You can filter messages by setting the start and end parameters to define a time range. To retrieve only the most recent messages, such as those sent between the last offline time and now, set only the end parameter.

The following example retrieves the latest 50 messages sent before a specific time:

try {
  const result = await rtmClient.history.getMessages(
    "chat_room",
    "MESSAGE",
    {
      messageCount: 50,
      end: 1688978391800,
    }
  );
} catch (status) {
  const { operation, reason, errorCode } = status;
  console.log(`${operation} failed. Error code: ${errorCode}, reason: ${reason}.`);
}

The result includes a newStart field, which indicates whether there are unread messages in the history:

If newStart is 0, all messages have been retrieved.
If newStart is not 0, use this value as the new start parameter in the next getMessages() call to continue retrieving messages.

The following use-cases show how to specify the start and end parameters to retrieve messages in a specific range:

Retrieve before a start timestamp

Parameter	Behavior
`start`	Returns messages sent before the specified timestamp. The timestamp itself is excluded.

Timeline:
[Older messages] ------------ start timestamp ------------ [Newer messages]
[             ←-- n messages]

Retrieve messages up to an end timestamp

Parameter	Behavior
`end`	Returns the n most recent messages sent up to and including the specified timestamp.

Timeline:
[Older messages] ------------ end timestamp ------------ [Newer messages]
                                       [  ←-- n messages]

Retrieve messages between two timestamps

Parameter	Behavior
`start`	Returns messages sent before this timestamp (excluded).
`end`	Returns messages sent up to and including this timestamp.

Timeline:
[Older messages] ---- end timestamp ------------ start timestamp ---- [Newer messages]
                               [ ←-- n messages]

When a message is published, it is stored using the channel name and the message timestamp. You can use this information to retrieve historical messages.

The historical message feature is currently available for User Channels and Message Channels, but not for Stream Channels.

Prerequisites

Before implementing this feature, ensure that you have:

Integrated the Signaling SDK in your project, and implemented the framework functionality from the SDK quickstart page.
Enabled the message history feature by contacting support@agora.io. You can request a storage duration of 1, 7, 30, 90, or 365 days, or opt for permanent storage.

Changes to storage duration only affect future messages.

Implement message history

This section shows how to store and retrieve messages from history.

Store messages

To store a message on the server, set setStoreInHistory to true in the publish() method. The following example shows the minimum code to store a message published to a message channel:

PublishOptions options = new PublishOptions();
options.setCustomType("custom type");
options.setStoreInHistory(true);

String channelName = "chatRoom";
String message = "Hello world!";
rtm.publish(channelName, message, options, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        log(CALLBACK, "send message success");
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});

To store a message in the history of a user channel, use the same parameter:

PublishOptions options = new PublishOptions();
options.setChannelType(RtmChannelType.USER);
options.setCustomType("custom type");
options.setStoreInHistory(true);

String userId = "Tony";
String message = "Hello world!";
rtm.publish(userId, message, options, new ResultCallback<Void>() {
    @Override
    public void onSuccess(Void responseInfo) {
        log(CALLBACK, "send message success");
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});

Retrieve messages

The following example retrieves the latest 50 messages sent before a specific time:

GetHistoryMessagesOptions options = new GetHistoryMessagesOptions();
options.setMessageCount(50);
options.setEnd(1688978391800);

String channelName = "chatRoom";
rtm.getHistory().getMessages(channelName, RtmChannelType.MESSAGE, options, new ResultCallback<GetMessagesResult>() {
    @Override
    public void onSuccess(GetMessagesResult result) {
        log(CALLBACK, "get history messages! new start: " + result.getNewStart());
        for (HistoryMessage message : result.getMessageList()) {
            log(INFO, message.toString());
        }
    }

    @Override
    public void onFailure(ErrorInfo errorInfo) {
        log(ERROR, errorInfo.toString());
    }
});

The result includes a newStart field, which indicates whether there are unread messages in the history:

If newStart is 0, all messages have been retrieved.
If newStart is not 0, use this value as the new start parameter in the next getMessages() call to continue retrieving messages.

The following use-cases show how to specify the start and end parameters to retrieve messages in a specific range:

Retrieve before a start timestamp

Parameter	Behavior
`start`	Returns messages sent before the specified timestamp. The timestamp itself is excluded.

Timeline:
[Older messages] ------------ start timestamp ------------ [Newer messages]
[             ←-- n messages]

Retrieve messages up to an end timestamp

Parameter	Behavior
`end`	Returns the n most recent messages sent up to and including the specified timestamp.

Timeline:
[Older messages] ------------ end timestamp ------------ [Newer messages]
                                       [  ←-- n messages]

Retrieve messages between two timestamps

Parameter	Behavior
`start`	Returns messages sent before this timestamp (excluded).
`end`	Returns messages sent up to and including this timestamp.

Timeline:
[Older messages] ---- end timestamp ------------ start timestamp ---- [Newer messages]
                               [ ←-- n messages]

When a message is published, it is stored using the channel name and the message timestamp. You can use this information to retrieve historical messages.

The historical message feature is currently available for User Channels and Message Channels, but not for Stream Channels.

Prerequisites

Before implementing this feature, ensure that you have:

Integrated the Signaling SDK in your project, and implemented the framework functionality from the SDK quickstart page.
Enabled the message history feature by contacting support@agora.io. You can request a storage duration of 1, 7, 30, 90, or 365 days, or opt for permanent storage.

Changes to storage duration only affect future messages.

Implement message history

This section shows how to store and retrieve messages from history.

Store messages

To store a message on the server, set setStoreInHistory to true in the publish() method. The following example shows the minimum code to store a message published to a message channel:

let message = "Hello Agora!"
let channel = "your_channel"

let publishOption = AgoraRtmPublishOptions()
publishOption.storeInHistory = true;

rtmKit.publish(channelName: channel, message: message, option: publishOption, completion: { res, error in
    if error != nil {
        print("\(error?.operation) failed! error reason is \(error?.reason)")
    } else {
        print("success")
    }
})

NSString* message = @"Hello Agora!";
NSString* channel = @"your_channel";

AgoraRtmPublishOptions* publish_option = [[AgoraRtmPublishOptions alloc] init];
publish_option.storeInHistory = true;

[_kit publish:channel message:message option:publish_option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

To store a message in the history of a user channel, use the same parameter:

let message = "Hello Agora!"
let user = "Tony"

let publishOption = AgoraRtmPublishOptions()
publishOption.channelType = .user
publishOption.storeInHistory = true;

rtmKit.publish(channelName: user, message: message, option: publishOption, completion: { res, error in
    if error != nil {
        print("\(error?.operation) failed! error reason is \(error?.reason)")
    } else {
        print("success")
    }
})

NSString* message = @"Hello Agora!";
NSString* user = @"Tony";

AgoraRtmPublishOptions* publish_option = [[AgoraRtmPublishOptions alloc] init];
publish_option.channelType = AgoraRtmChannelTypeUser;
publish_option.storeInHistory = true;

[_kit publish:user message:message option:publish_option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Retrieve messages

The following example retrieves the latest 50 messages sent before a specific time:

var option = AgoraRtmGetHistoryMessagesOptions()
 option.messageCount = 50
 option.end = 1688978391800

rtmKit.getHistory()?.getMessages(channelName: "channel_name", channelType: .message, options: option, completion: { response, error in
    if response != nil {
        print("total message count is: \(response!.messageList.count)")
            for msg in response!.messageList {
                print("publisher: \(msg.publisher)message content: \(msg.message.stringData!)time stamp: \(msg.timestamp)")
            }
            print("new start: \(response!.newStart)")
    } else {
        print("get history message failed")
    }
})

AgoraRtmGetHistoryMessagesOptions *option = [[AgoraRtmGetHistoryMessagesOptions alloc] init];
option.messageCount = 50;
option.end = 1688978391800;

[_kit getMessages:@"channel_name"
            channelType:AgoraRtmChannelTypeMessage
                options:option
             completion:^(AgoraRtmGetHistoryMessagesResponse *response, NSError *error) {
    if (response != nil) {
        NSLog(@"total message count is: %lu", (unsigned long)response.messageList.count);

        for (AgoraRtmMessage *msg in response.messageList) {
            NSLog(@"publisher: %@message content: %@time stamp: %lld", msg.publisher, msg.message.stringData, msg.timestamp);
        }

        NSLog(@"new start: %@", response.newStart);
    } else {
        NSLog(@"get history message failed: %@", error.localizedDescription);
    }
}];

The response includes a newStart field, which indicates whether there are unread messages in the history:

If newStart is 0, all messages have been retrieved.
If newStart is not 0, use this value as the new start parameter in the next getMessages() call to continue retrieving messages.

The following use-cases show how to specify the start and end parameters to retrieve messages in a specific range:

Retrieve before a start timestamp

Parameter	Behavior
`start`	Returns messages sent before the specified timestamp. The timestamp itself is excluded.

Timeline:
[Older messages] ------------ start timestamp ------------ [Newer messages]
[             ←-- n messages]

Retrieve messages up to an end timestamp

Parameter	Behavior
`end`	Returns the n most recent messages sent up to and including the specified timestamp.

Timeline:
[Older messages] ------------ end timestamp ------------ [Newer messages]
                                       [  ←-- n messages]

Retrieve messages between two timestamps

Parameter	Behavior
`start`	Returns messages sent before this timestamp (excluded).
`end`	Returns messages sent up to and including this timestamp.

Timeline:
[Older messages] ---- end timestamp ------------ start timestamp ---- [Newer messages]
                               [ ←-- n messages]

When a message is published, it is stored using the channel name and the message timestamp. You can use this information to retrieve historical messages.

The historical message feature is currently available for User Channels and Message Channels, but not for Stream Channels.

Prerequisites

Before implementing this feature, ensure that you have:

Integrated the Signaling SDK in your project, and implemented the framework functionality from the SDK quickstart page.
Enabled the message history feature by contacting support@agora.io. You can request a storage duration of 1, 7, 30, 90, or 365 days, or opt for permanent storage.

Changes to storage duration only affect future messages.

Implement message history

This section shows how to store and retrieve messages from history.

Store messages

To store a message on the server, set setStoreInHistory to true in the publish() method. The following example shows the minimum code to store a message published to a message channel:

let message = "Hello Agora!"
let channel = "your_channel"

let publishOption = AgoraRtmPublishOptions()
publishOption.storeInHistory = true;

rtmKit.publish(channelName: channel, message: message, option: publishOption, completion: { res, error in
    if error != nil {
        print("\(error?.operation) failed! error reason is \(error?.reason)")
    } else {
        print("success")
    }
})

NSString* message = @"Hello Agora!";
NSString* channel = @"your_channel";

AgoraRtmPublishOptions* publish_option = [[AgoraRtmPublishOptions alloc] init];
publish_option.storeInHistory = true;

[_kit publish:channel message:message option:publish_option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

To store a message in the history of a user channel, use the same parameter:

let message = "Hello Agora!"
let user = "Tony"

let publishOption = AgoraRtmPublishOptions()
publishOption.channelType = .user
publishOption.storeInHistory = true;

rtmKit.publish(channelName: user, message: message, option: publishOption, completion: { res, error in
    if error != nil {
        print("\(error?.operation) failed! error reason is \(error?.reason)")
    } else {
        print("success")
    }
})

NSString* message = @"Hello Agora!";
NSString* user = @"Tony";

AgoraRtmPublishOptions* publish_option = [[AgoraRtmPublishOptions alloc] init];
publish_option.channelType = AgoraRtmChannelTypeUser;
publish_option.storeInHistory = true;

[_kit publish:user message:message option:publish_option completion:^(AgoraRtmCommonResponse * _Nullable response, AgoraRtmErrorInfo * _Nullable errorInfo) {
    if (errorInfo == nil) {
        NSLog(@"publish success!!");
    } else {
        NSLog(@"publish failed, errorCode %d, reason %@", errorInfo.errorCode, errorInfo.reason);
    }
}];

Retrieve messages

The following example retrieves the latest 50 messages sent before a specific time:

var option = AgoraRtmGetHistoryMessagesOptions()
 option.messageCount = 50
 option.end = 1688978391800

rtmKit.getHistory()?.getMessages(channelName: "channel_name", channelType: .message, options: option, completion: { response, error in
    if response != nil {
        print("total message count is: \(response!.messageList.count)")
            for msg in response!.messageList {
                print("publisher: \(msg.publisher)message content: \(msg.message.stringData!)time stamp: \(msg.timestamp)")
            }
            print("new start: \(response!.newStart)")
    } else {
        print("get history message failed")
    }
})

AgoraRtmGetHistoryMessagesOptions *option = [[AgoraRtmGetHistoryMessagesOptions alloc] init];
option.messageCount = 50;
option.end = 1688978391800;

[_kit getMessages:@"channel_name"
            channelType:AgoraRtmChannelTypeMessage
                options:option
             completion:^(AgoraRtmGetHistoryMessagesResponse *response, NSError *error) {
    if (response != nil) {
        NSLog(@"total message count is: %lu", (unsigned long)response.messageList.count);

        for (AgoraRtmMessage *msg in response.messageList) {
            NSLog(@"publisher: %@message content: %@time stamp: %lld", msg.publisher, msg.message.stringData, msg.timestamp);
        }

        NSLog(@"new start: %@", response.newStart);
    } else {
        NSLog(@"get history message failed: %@", error.localizedDescription);
    }
}];

The response includes a newStart field, which indicates whether there are unread messages in the history:

If newStart is 0, all messages have been retrieved.
If newStart is not 0, use this value as the new start parameter in the next getMessages() call to continue retrieving messages.

The following use-cases show how to specify the start and end parameters to retrieve messages in a specific range:

Retrieve before a start timestamp

Parameter	Behavior
`start`	Returns messages sent before the specified timestamp. The timestamp itself is excluded.

Timeline:
[Older messages] ------------ start timestamp ------------ [Newer messages]
[             ←-- n messages]

Retrieve messages up to an end timestamp

Parameter	Behavior
`end`	Returns the n most recent messages sent up to and including the specified timestamp.

Timeline:
[Older messages] ------------ end timestamp ------------ [Newer messages]
                                       [  ←-- n messages]

Retrieve messages between two timestamps

Parameter	Behavior
`start`	Returns messages sent before this timestamp (excluded).
`end`	Returns messages sent up to and including this timestamp.

Timeline:
[Older messages] ---- end timestamp ------------ start timestamp ---- [Newer messages]
                               [ ←-- n messages]

When a message is published, it is stored using the channel name and the message timestamp. You can use this information to retrieve historical messages.

The historical message feature is currently available for User Channels and Message Channels, but not for Stream Channels.

Prerequisites

Before implementing this feature, ensure that you have:

Integrated the Signaling SDK in your project, and implemented the framework functionality from the SDK quickstart page.
Enabled the message history feature by contacting support@agora.io. You can request a storage duration of 1, 7, 30, 90, or 365 days, or opt for permanent storage.

Changes to storage duration only affect future messages.

Implement message history

This section shows how to store and retrieve messages from history.

Store messages

To store a message on the server, set setStoreInHistory to true in the publish() method. The following example shows the minimum code to store a message published to a message channel:

uint64_t requestId = 0;
std::string channelName = "chatRoom"
std::string message = "Hello world!";

PublishOptions options;
options.storeInHistory = true;
options.channelType = RTM_CHANNEL_TYPE_MESSAGE;
options.messageType = RTM_MESSAGE_TYPE_STRING;

rtmClient_->publish(channelName.c_str(), message.c_str(), message.size(), options,
                   requestId);

To store a message in the history of a user channel, use the same parameter:

uint64_t requestId = 0;
std::string userId = "Tony"
std::string message = "Hello world!";

PublishOptions options;
options.storeInHistory = true;
options.channelType = RTM_CHANNEL_TYPE_USER;
options.messageType = RTM_MESSAGE_TYPE_STRING;

rtmClient_->(userId.c_str(), message.c_str(), message.size(), options,
            requestId);

Retrieve messages

The following example retrieves the latest 50 messages sent before a specific time:

uint64_t requestId = 0;
std::string channelName = "chatRoom";

GetHistoryMessagesOptions options;
options.messageCount = 50;
options.end = 1688978391800;

rtmClient_->getHistory()->getMessages(channelName.c_str(), RTM_CHANNEL_TYPE_MESSAGE,
                                     options, requestId);

The result includes a newStart field, which indicates whether there are unread messages i the history:

If newStart is 0, all messages have been retrieved.
If newStart is not 0, use this value as the new start parameter in the next getMessages() call to continue retrieving messages.

The following use-cases show how to specify the start and end parameters to retrieve messages in a specific range:

Retrieve before a start timestamp

Parameter	Behavior
`start`	Returns messages sent before the specified timestamp. The timestamp itself is excluded.

Timeline:
[Older messages] ------------ start timestamp ------------ [Newer messages]
[             ←-- n messages]

Retrieve messages up to an end timestamp

Parameter	Behavior
`end`	Returns the n most recent messages sent up to and including the specified timestamp.

Timeline:
[Older messages] ------------ end timestamp ------------ [Newer messages]
                                       [  ←-- n messages]

Retrieve messages between two timestamps

Parameter	Behavior
`start`	Returns messages sent before this timestamp (excluded).
`end`	Returns messages sent up to and including this timestamp.

Timeline:
[Older messages] ---- end timestamp ------------ start timestamp ---- [Newer messages]
                               [ ←-- n messages]

When a message is published, it is stored using the channel name and the message timestamp. You can use this information to retrieve historical messages.

The historical message feature is currently available for User Channels and Message Channels, but not for Stream Channels.

Prerequisites

Before implementing this feature, ensure that you have:

Integrated the Signaling SDK in your project, and implemented the framework functionality from the SDK quickstart page.
Enabled the message history feature by contacting support@agora.io. You can request a storage duration of 1, 7, 30, 90, or 365 days, or opt for permanent storage.

Changes to storage duration only affect future messages.

Implement message history

This section shows how to store and retrieve messages from history.

Store messages

To store a message on the server, set setStoreInHistory to true in the publish() method. The following example shows the minimum code to store a message published to a message channel:

uint64_t requestId = 0;
std::string channelName = "chatRoom"
std::string message = "Hello world!";

PublishOptions options;
options.storeInHistory = true;
options.channelType = RTM_CHANNEL_TYPE_MESSAGE;
options.messageType = RTM_MESSAGE_TYPE_STRING;

rtmClient_->publish(channelName.c_str(), message.c_str(), message.size(), options,
                   requestId);

To store a message in the history of a user channel, use the same parameter:

uint64_t requestId = 0;
std::string userId = "Tony"
std::string message = "Hello world!";

PublishOptions options;
options.storeInHistory = true;
options.channelType = RTM_CHANNEL_TYPE_USER;
options.messageType = RTM_MESSAGE_TYPE_STRING;

rtmClient_->(userId.c_str(), message.c_str(), message.size(), options,
            requestId);

Retrieve messages

The following example retrieves the latest 50 messages sent before a specific time:

uint64_t requestId = 0;
std::string channelName = "chatRoom";

GetHistoryMessagesOptions options;
options.messageCount = 50;
options.end = 1688978391800;

rtmClient_->getHistory()->getMessages(channelName.c_str(), RTM_CHANNEL_TYPE_MESSAGE,
                                     options, requestId);

The result includes a newStart field, which indicates whether there are unread messages i the history:

If newStart is 0, all messages have been retrieved.
If newStart is not 0, use this value as the new start parameter in the next getMessages() call to continue retrieving messages.

The following use-cases show how to specify the start and end parameters to retrieve messages in a specific range:

Retrieve before a start timestamp

Parameter	Behavior
`start`	Returns messages sent before the specified timestamp. The timestamp itself is excluded.

Timeline:
[Older messages] ------------ start timestamp ------------ [Newer messages]
[             ←-- n messages]

Retrieve messages up to an end timestamp

Parameter	Behavior
`end`	Returns the n most recent messages sent up to and including the specified timestamp.

Timeline:
[Older messages] ------------ end timestamp ------------ [Newer messages]
                                       [  ←-- n messages]

Retrieve messages between two timestamps

Parameter	Behavior
`start`	Returns messages sent before this timestamp (excluded).
`end`	Returns messages sent up to and including this timestamp.

Timeline:
[Older messages] ---- end timestamp ------------ start timestamp ---- [Newer messages]
                               [ ←-- n messages]

Contact Us

Contact Us