Package net.dv8tion.jda.core.entities

Class MessageHistory

java.lang.Object

net.dv8tion.jda.core.entities.MessageHistory

public class MessageHistory
extends java.lang.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.

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, java.lang.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, java.lang.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, java.lang.String messageId)	Constructs a MessageHistory with the initially retrieved history of messages sent before the mentioned message ID (exclusive).
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(java.lang.String id)	Used to get a Message from the set of already retrieved message via it's message Id.
java.util.List<Message>	getRetrievedHistory()	Returns a 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<java.util.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<java.util.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 Detail

MessageHistory

public MessageHistory(MessageChannel channel)

Creates a new MessageHistory object.

Parameters:

channel - The MessageChannel to retrieval history from.

Method Detail

getJDA

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

public MessageChannel getChannel()

Returns the MessageChannel that this MessageHistory is related to.

Returns:

The MessageChannel of this history.

retrievePast

@CheckReturnValue
public RestAction<java.util.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 or Group.
• 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:

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

retrieveFuture

@CheckReturnValue
public RestAction<java.util.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 or Group.
• 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:

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

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

getRetrievedHistory

public java.util.List<Message> getRetrievedHistory()

Returns a 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.

Returns:

A List of Messages, sorted newest to oldest.

getMessageById

public Message getMessageById(java.lang.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.getMessageById(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:

java.lang.IllegalArgumentException - If the provided id is null or empty.

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

getMessageById

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.getMessageById(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

public static MessageHistory.MessageRetrieveAction getHistoryAfter(MessageChannel channel,
                                                                   java.lang.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:

java.lang.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

public static MessageHistory.MessageRetrieveAction getHistoryBefore(MessageChannel channel,
                                                                    java.lang.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:

java.lang.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

public static MessageHistory.MessageRetrieveAction getHistoryAround(MessageChannel channel,
                                                                    java.lang.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:

java.lang.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)