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:

  • 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 MessageChannelUnion getChannel()
      Returns the MessageChannel that this MessageHistory is related to.
      Returns:
      The MessageChannel of this history.

    • retrievePast

      @Nonnull @CheckReturnValue public RestAction<@Unmodifiable 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<@Unmodifiable 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 @Unmodifiable 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 TimeUtil.getDiscordTimestamp(long): 

      long timestamp = System.currentTimeMillis(); // or any other epoch millis timestamp
String discordTimestamp = Long.toUnsignedString(TimeUtil.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:

    • 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 TimeUtil.getDiscordTimestamp(long): 

      long timestamp = System.currentTimeMillis(); // or any other epoch millis timestamp
String discordTimestamp = Long.toUnsignedString(TimeUtil.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:

    • 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 TimeUtil.getDiscordTimestamp(long): 

      long timestamp = System.currentTimeMillis(); // or any other epoch millis timestamp
String discordTimestamp = Long.toUnsignedString(TimeUtil.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:

    • 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: