Chat History query options#

ChatHistoryQueryOptions is an optional options model that can be included with a VivoxService.Instance.GetDirectTextMessageHistoryAsync or VivoxService.Instance.GetChannelTextMessageHistoryAsync call to specify what messages to return.

SearchText#

Use the SearchText field of ChatHistoryQueryOptions to specify a string of text that should be in every message returned by the chat history query. For example, the following code will ensure that the historyMessages returned only include messages that contain the text "Hello, lobby!".

var options = new ChatHistoryQueryOptions();
options.SearchText = "Hello, lobby!";
var historyMessages =
    await VivoxService.Instance.GetChannelTextMessageHistoryAsync(LobbyChannelName, 10, options);

TimeStart - TimeEnd#

The TimeStart and TimeEnd fields of ChatHistoryQueryOptions are both DateTimes that delineate times after and before, respectively, that messages should have been sent in. For example, the following code will return the last 10 messages from between 24 hours before the request was made and 12 hours before the request was made. DateTime must be server time and not client side time.

var options = new ChatHistoryQueryOptions();
options.TimeStart = DateTime.Now().AddDays(-1);
options.TimeEnd = DateTime.Now().AddDays(-0.5);
var historyMessages =
    await VivoxService.Instance.GetChannelTextMessageHistoryAsync(LobbyChannelName, 10, options);

Note that chat history is only stored for seven days, unless you have enabled Text Evidence Management.

PlayerId#

For ChannelTextMessageHistory requests, the PlayerId field of ChatHistoryQueryOptions delineates the PlayerId that will be the sender of all returned messages. For example, the following code will return the last 10 messages sent from the specific participant in the specified channel.

IReadOnlyCollection<VivoxMessage> GetMessagesFromPlayerAsync(VivoxParticipant participant)
{
    var options = new ChatHistoryQueryOptions();
    options.PlayerId = participant.PlayerId;
    var historyMessages =
        await VivoxService.Instance.GetChannelTextMessageHistoryAsync(LobbyChannelName, 10, options);
    return historyMessages;
}

Channel-based chat history for blocked participants#

You can filter messages from blocked users when formatting the history_session query responses.

When retrieving the chat history from a channel, the SDK omits messages from blocked users. If User A has User B blocked in the application, User A does not see messages sent by User B.

History sessions when blocked participants are involved#

A history request can come back empty if all messages in the request are from a blocked participant. In this case, the response contains a cursor indicating that there are more messages in the channel on subsequent pages. The default amount of messages returned per history request is 10 per page. Use the cursor value in the following request to retrieve the next page of messages.

The maximum page size argument (Max) shows fewer messages than the number requested if there is a blocked user in the channel. When you request a specific page size for your chat history, be aware that history_session might display fewer messages than your chosen number if there are blocked users in the channel. This functionality is crucial to ensure privacy and prevent unwanted interactions.

The last read displays a count of unread messages. Vivox keeps track of your read messages and provides a count of unread messages. However, note that this count includes blocked messages, which are deliberately filtered from your response. The count of unread messages might be inaccurate if there are blocked users in the channel.

Account chat history for blocked participants#

When you submit a chat history request for an account, queries only show the user’s sent messages.