Package net.dv8tion.jda.api.entities

Class MessageHistory

java.lang.Object

net.dv8tion.jda.api.entities.MessageHistory

public class MessageHistory
extends Object

Represents an access point to the Message history of a MessageChannel.
Note: Message order is always in recent to past order. I.e: A message at index 0 of a list is more recent than a message at index 1.

See Also:

• MessageChannel.getHistory()
• MessageChannel.getHistoryAfter(String, int)
• MessageChannel.getHistoryBefore(String, int)
• MessageChannel.getHistoryAround(String, int)
• MessageChannel.getHistoryFromBeginning(int)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	MessageHistory.MessageRetrieveAction	Constructs a MessageHistory object with initially retrieved Messages before or after a certain pivot message id.

Constructor Summary

Constructors

Constructor	Description
MessageHistory(MessageChannel channel)	Creates a new MessageHistory object.

Method Summary

Modifier and Type	Method	Description
MessageChannel	getChannel()	Returns the MessageChannel that this MessageHistory is related to.
static MessageHistory.MessageRetrieveAction	getHistoryAfter(MessageChannel channel, String messageId)	Constructs a MessageHistory with the initially retrieved history of messages sent after the mentioned message ID (exclusive).
static MessageHistory.MessageRetrieveAction	getHistoryAround(MessageChannel channel, String messageId)	Constructs a MessageHistory with the initially retrieved history of messages sent around the mentioned message ID (inclusive).
static MessageHistory.MessageRetrieveAction	getHistoryBefore(MessageChannel channel, String messageId)	Constructs a MessageHistory with the initially retrieved history of messages sent before the mentioned message ID (exclusive).
static MessageHistory.MessageRetrieveAction	getHistoryFromBeginning(MessageChannel channel)	Constructs a MessageHistory with the initially retrieved history of messages sent.
JDA	getJDA()	The corresponding JDA instance for this MessageHistory
Message	getMessageById(long id)	Used to get a Message from the set of already retrieved message via it's message Id.
Message	getMessageById(String id)	Used to get a Message from the set of already retrieved message via it's message Id.
List<Message>	getRetrievedHistory()	The List of Messages, sorted starting from newest to oldest, of all message that have already been retrieved from Discord with this MessageHistory object using the retrievePast(int), retrieveFuture(int), and MessageChannel.getHistoryAround(String, int) methods.
boolean	isEmpty()	Whether this MessageHistory instance has retrieved any messages.
RestAction<List<Message>>	retrieveFuture(int amount)	Retrieves messages from Discord that were sent more recently than the most recently sent message in MessageHistory's history cache (getRetrievedHistory()).
RestAction<List<Message>>	retrievePast(int amount)	Retrieves messages from Discord that were sent before the oldest sent message in MessageHistory's history cache (getRetrievedHistory()).
int	size()	The amount of retrieved Messages by this MessageHistory.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

MessageHistory

public MessageHistory(@Nonnull
 MessageChannel channel)

Creates a new MessageHistory object.

Parameters:

channel - The MessageChannel to retrieval history from.

Method Details

getJDA

@Nonnull
public JDA getJDA()

The corresponding JDA instance for this MessageHistory

Returns:

The corresponding JDA instance

size

public int size()

The amount of retrieved Messages by this MessageHistory.
This returns 0 until any call to retrieve messages has completed. See retrievePast(int) and retrieveFuture(int)!

Returns:

Amount of retrieved messages

isEmpty

public boolean isEmpty()

Whether this MessageHistory instance has retrieved any messages.

Returns:

True, If this MessageHistory instance has not retrieved any messages from discord.

getChannel

@Nonnull
public MessageChannel getChannel()

Returns the MessageChannel that this MessageHistory is related to.

Returns:

The MessageChannel of this history.

retrievePast

@Nonnull
@CheckReturnValue
public RestAction<List<Message>> retrievePast(int amount)

Retrieves messages from Discord that were sent before the oldest sent message in MessageHistory's history cache (getRetrievedHistory()).
Can only retrieve a maximum of 100 messages at a time.
This method has 2 modes of operation: initial retrieval and additional retrieval.

• Initial Retrieval
  This mode is what is used when no Messages have been retrieved yet (getRetrievedHistory()'s size is 0). Initial retrieval starts from the most recent message sent to the channel and retrieves backwards from there. So, if 50 messages are retrieved during this mode, the most recent 50 messages will be retrieved.
• Additional Retrieval
  This mode is used once some Messages have already been retrieved from Discord and are stored in MessageHistory's history (getRetrievedHistory()). When retrieving messages in this mode, MessageHistory will retrieve previous messages starting from the oldest message stored in MessageHistory.
  E.g: If you initially retrieved 10 messages, the next call to this method to retrieve 10 messages would retrieve the next 10 messages, starting from the oldest message of the 10 previously retrieved messages.

Possible ErrorResponses include:

• UNKNOWN_MESSAGE
  Can occur if retrieving in Additional Mode and the Message being used as the marker for the last retrieved Message was deleted. Currently, to fix this, you need to create a new MessageHistory instance.
• MISSING_ACCESS
  Can occur if the request for history retrieval was executed after JDA lost access to the Channel, typically due to the account being removed from the Guild.
• MISSING_PERMISSIONS
  Can occur if the request for history retrieval was executed after JDA lost the Permission.MESSAGE_HISTORY permission.
• UNKNOWN_CHANNEL
  The send request was attempted after the channel was deleted.

Parameters:

amount - The amount of Messages to retrieve.

Returns:

RestAction - Type: List<Message>
Retrieved Messages are placed in a List and provided in order of most recent to oldest with most recent starting at index 0. If the list is empty, there were no more messages left to retrieve.

Throws:

IllegalArgumentException - The the amount is less than 1 or greater than 100.

retrieveFuture

@Nonnull
@CheckReturnValue
public RestAction<List<Message>> retrieveFuture(int amount)

Retrieves messages from Discord that were sent more recently than the most recently sent message in MessageHistory's history cache (getRetrievedHistory()). Use case for this method is for getting more recent messages after jumping to a specific point in history using something like MessageChannel.getHistoryAround(String, int).
This method works in the same way as retrievePast(int)'s Additional Retrieval mode.

Note: This method can only be used after Messages have already been retrieved from Discord.

Possible ErrorResponses include:

• UNKNOWN_MESSAGE
  Can occur if retrieving in Additional Mode and the Message being used as the marker for the last retrieved Message was deleted. Currently, to fix this, you need to create a new MessageHistory instance.
• MISSING_ACCESS
  Can occur if the request for history retrieval was executed after JDA lost access to the Channel, typically due to the account being removed from the Guild.
• MISSING_PERMISSIONS
  Can occur if the request for history retrieval was executed after JDA lost the Permission.MESSAGE_HISTORY permission.
• UNKNOWN_CHANNEL
  The send request was attempted after the channel was deleted.

Parameters:

amount - The amount of Messages to retrieve.

Returns:

RestAction - Type: List<Message>
Retrieved Messages are placed in a List and provided in order of most recent to oldest with most recent starting at index 0. If the list is empty, there were no more messages left to retrieve.

Throws:

IllegalArgumentException - The the amount is less than 1 or greater than 100.

IllegalStateException - If no messages have been retrieved by this MessageHistory.

getRetrievedHistory

@Nonnull
public List<Message> getRetrievedHistory()

The List of Messages, sorted starting from newest to oldest, of all message that have already been retrieved from Discord with this MessageHistory object using the retrievePast(int), retrieveFuture(int), and MessageChannel.getHistoryAround(String, int) methods.

This will be empty if it was just created using MessageChannel.getHistory() or similar methods. You first have to retrieve messages.

Returns:

An immutable List of Messages, sorted newest to oldest.

getMessageById

@Nullable
public Message getMessageById(@Nonnull
 String id)

Used to get a Message from the set of already retrieved message via it's message Id.
If a Message with the provided id has not already been retrieved (thus, doesn't not exist in this MessageHistory object), then this method returns null.

Note: This methods is not the same as MessageChannel.retrieveMessageById(String), which itself queries Discord. This method is for getting a message that has already been retrieved by this MessageHistory object.

Parameters:

id - The id of the requested Message.

Returns:

Possibly-null Message with the same id as the one provided.

Throws:

IllegalArgumentException - If the provided id is null or empty.

NumberFormatException - If the provided id cannot be parsed by Long.parseLong(String)

getMessageById

@Nullable
public Message getMessageById(long id)

Used to get a Message from the set of already retrieved message via it's message Id.
If a Message with the provided id has not already been retrieved (thus, doesn't not exist in this MessageHistory object), then this method returns null.

Note: This methods is not the same as MessageChannel.retrieveMessageById(long), which itself queries Discord. This method is for getting a message that has already been retrieved by this MessageHistory object.

Parameters:

id - The id of the requested Message.

Returns:

Possibly-null Message with the same id as the one provided.

getHistoryAfter

@Nonnull
@CheckReturnValue
public static MessageHistory.MessageRetrieveAction getHistoryAfter(@Nonnull
 MessageChannel channel,
 @Nonnull
 String messageId)

Constructs a MessageHistory with the initially retrieved history of messages sent after the mentioned message ID (exclusive).
The provided ID need not be valid!

Alternatively you can use MessageChannel.getHistoryAfter(...)

Example
MessageHistory history = MessageHistory.getHistoryAfter(channel, messageId).limit(60).complete()
Will return a MessageHistory instance with the first 60 messages sent after the provided message ID.

Alternatively you can provide an epoch millisecond timestamp using MiscUtil.getDiscordTimestamp(long):

 long timestamp = System.currentTimeMillis(); // or any other epoch millis timestamp
 String discordTimestamp = Long.toUnsignedString(MiscUtil.getDiscordTimestamp(timestamp));
 MessageHistory history = MessageHistory.getHistoryAfter(channel, discordTimestamp).complete();
 

Parameters:

channel - The MessageChannel

messageId - The pivot ID to use

Returns:

MessageRetrieveAction

Throws:

IllegalArgumentException - If any of the provided arguments is null; Or if the provided messageId contains whitespace

InsufficientPermissionException - If this is a TextChannel and the currently logged in account does not have the permission Permission.MESSAGE_HISTORY

See Also:

• MessageChannel.getHistoryAfter(String, int)
• MessageChannel.getHistoryAfter(long, int)
• MessageChannel.getHistoryAfter(Message, int)

getHistoryBefore

@Nonnull
@CheckReturnValue
public static MessageHistory.MessageRetrieveAction getHistoryBefore(@Nonnull
 MessageChannel channel,
 @Nonnull
 String messageId)

Constructs a MessageHistory with the initially retrieved history of messages sent before the mentioned message ID (exclusive).
The provided ID need not be valid!

Alternatively you can use MessageChannel.getHistoryBefore(...)

Example
MessageHistory history = MessageHistory.getHistoryBefore(channel, messageId).limit(60).complete()
Will return a MessageHistory instance with the first 60 messages sent before the provided message ID.

Alternatively you can provide an epoch millisecond timestamp using MiscUtil.getDiscordTimestamp(long):

 long timestamp = System.currentTimeMillis(); // or any other epoch millis timestamp
 String discordTimestamp = Long.toUnsignedString(MiscUtil.getDiscordTimestamp(timestamp));
 MessageHistory history = MessageHistory.getHistoryBefore(channel, discordTimestamp).complete();
 

Parameters:

channel - The MessageChannel

messageId - The pivot ID to use

Returns:

MessageRetrieveAction

Throws:

IllegalArgumentException - If any of the provided arguments is null; Or if the provided messageId contains whitespace

InsufficientPermissionException - If this is a TextChannel and the currently logged in account does not have the permission Permission.MESSAGE_HISTORY

See Also:

• MessageChannel.getHistoryBefore(String, int)
• MessageChannel.getHistoryBefore(long, int)
• MessageChannel.getHistoryBefore(Message, int)

getHistoryAround

@Nonnull
@CheckReturnValue
public static MessageHistory.MessageRetrieveAction getHistoryAround(@Nonnull
 MessageChannel channel,
 @Nonnull
 String messageId)

Constructs a MessageHistory with the initially retrieved history of messages sent around the mentioned message ID (inclusive).
The provided ID need not be valid!

Alternatively you can use MessageChannel.getHistoryAround(...)

Example
MessageHistory history = MessageHistory.getHistoryAround(channel, messageId).limit(60).complete()
Will return a MessageHistory instance with the first 60 messages sent around the provided message ID.

Alternatively you can provide an epoch millisecond timestamp using MiscUtil.getDiscordTimestamp(long):

 long timestamp = System.currentTimeMillis(); // or any other epoch millis timestamp
 String discordTimestamp = Long.toUnsignedString(MiscUtil.getDiscordTimestamp(timestamp));
 MessageHistory history = MessageHistory.getHistoryAround(channel, discordTimestamp).complete();
 

Parameters:

channel - The MessageChannel

messageId - The pivot ID to use

Returns:

MessageRetrieveAction

Throws:

IllegalArgumentException - If any of the provided arguments is null; Or if the provided messageId contains whitespace

InsufficientPermissionException - If this is a TextChannel and the currently logged in account does not have the permission Permission.MESSAGE_HISTORY

See Also:

• MessageChannel.getHistoryAround(String, int)
• MessageChannel.getHistoryAround(long, int)
• MessageChannel.getHistoryAround(Message, int)

getHistoryFromBeginning

@Nonnull
@CheckReturnValue
public static MessageHistory.MessageRetrieveAction getHistoryFromBeginning(@Nonnull
 MessageChannel channel)

Constructs a MessageHistory with the initially retrieved history of messages sent.

Alternatively you can use MessageChannel.getHistoryFromBeginning(...)

Example

MessageHistory history = MessageHistory.getHistoryFromBeginning(channel).limit(60).complete()
Will return a MessageHistory instance with the first 60 messages of the given MessageChannel.

Parameters:

channel - The MessageChannel

Returns:

MessageRetrieveAction

Throws:

IllegalArgumentException - If the provided MessageChannel is null;

InsufficientPermissionException - If this is a TextChannel and the currently logged in account does not have the permission Permission.MESSAGE_HISTORY

See Also:

• MessageChannel.getHistoryFromBeginning(int)