Package net.dv8tion.jda.api.entities

Class MessageHistory

    • Constructor Detail

      • MessageHistory

        public MessageHistory​(@Nonnull
                      MessageChannel channel)
        Creates a new MessageHistory object.
        Parameters:
        channel - The MessageChannel to retrieval history from.

    • Method Detail

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

        @Nonnull
@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.
        • 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.

      • getMessageById

        @Nullable
public Message getMessageById​(@Nonnull
                              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.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:
        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

        @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.