Add support for message forwarding (#2744)

src/main/java/net/dv8tion/jda/api/entities/Message.java

@@ -30,6 +30,7 @@
 import net.dv8tion.jda.api.entities.emoji.Emoji;
 import net.dv8tion.jda.api.entities.emoji.RichCustomEmoji;
 import net.dv8tion.jda.api.entities.messages.MessagePoll;
+import net.dv8tion.jda.api.entities.messages.MessageSnapshot;
 import net.dv8tion.jda.api.entities.sticker.GuildSticker;
 import net.dv8tion.jda.api.entities.sticker.Sticker;
 import net.dv8tion.jda.api.entities.sticker.StickerItem;
@@ -57,6 +58,8 @@
 import net.dv8tion.jda.api.utils.messages.MessageRequest;
 import net.dv8tion.jda.internal.JDAImpl;
 import net.dv8tion.jda.internal.entities.ReceivedMessage;
+import net.dv8tion.jda.internal.entities.channel.mixin.middleman.MessageChannelMixin;
+import net.dv8tion.jda.internal.requests.restaction.MessageCreateActionImpl;
 import net.dv8tion.jda.internal.requests.restaction.pagination.PollVotersPaginationActionImpl;
 import net.dv8tion.jda.internal.utils.Checks;
 import net.dv8tion.jda.internal.utils.Helpers;
@@ -821,6 +824,19 @@ default List<Button> getButtonsByLabel(@Nonnull String label, boolean ignoreCase
     @Unmodifiable
     List<StickerItem> getStickers();
 
+    /**
+     * The {@link MessageSnapshot MessageSnaphots} attached to this message.
+     *
+     * <p>This is used primarily for message forwarding.
+     * The content of the forwarded message is provided as a snapshot at the time of forwarding.
+     * When the message is edited or deleted, this snapshot remains unchanged.
+     *
+     * @return Immutable {@link List} of {@link MessageSnapshot}
+     */
+    @Nonnull
+    @Unmodifiable
+    List<MessageSnapshot> getMessageSnapshots();
+
     /**
      * Defines whether or not this Message triggers TTS (Text-To-Speech).
      *
@@ -1674,6 +1690,40 @@ default MessageCreateAction replyFiles(@Nonnull Collection<? extends FileUpload>
         return getChannel().sendFiles(files).setMessageReference(this);
     }
 
+    /**
+     * Forwards this message into the provided channel.
+     *
+     * <p><b>A message forward request cannot contain additional content.</b>
+     *
+     * <p>Possible {@link net.dv8tion.jda.api.requests.ErrorResponse ErrorResponses} from forwarding include:
+     * <ul>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#REFERENCED_MESSSAGE_NOT_FOUND REFERENCED_MESSSAGE_NOT_FOUND}
+     *     <br>If the provided reference cannot be resolved to a message</li>
+     *     <li>{@link net.dv8tion.jda.api.requests.ErrorResponse#FORWARD_CANNOT_HAVE_CONTENT FORWARD_CANNOT_HAVE_CONTENT}
+     *     <br>If additional content is sent alongside a forwarded message</li>
+     * </ul>
+     *
+     * @param  channel
+     *         The target channel to forward to
+     *
+     * @throws InsufficientPermissionException
+     *         If the bot is missing {@link Permission#MESSAGE_SEND} in the target channel
+     * @throws IllegalArgumentException
+     *         If the target channel is null
+     *
+     * @return {@link MessageCreateAction}
+     */
+    @Nonnull
+    @CheckReturnValue
+    default MessageCreateAction forwardTo(@Nonnull MessageChannel channel)
+    {
+        Checks.notNull(channel, "Target channel");
+        if (channel instanceof MessageChannelMixin)
+            ((MessageChannelMixin<?>) channel).checkCanSendMessage();
+        return new MessageCreateActionImpl(channel)
+                .setMessageReference(MessageReference.MessageReferenceType.FORWARD, this);
+    }
+
     /**
      * Deletes this Message from Discord.
      * <br>If this Message was not sent by the currently logged in account, then this will fail unless the Message is from

src/main/java/net/dv8tion/jda/api/entities/MessageReference.java

@@ -38,6 +38,7 @@
  */
 public class MessageReference
 {
+    private final int type;
     private final long messageId;
     private final long channelId;
     private final long guildId;
@@ -47,8 +48,9 @@ public class MessageReference
     private final Guild guild;
     private Message referencedMessage;
 
-    public MessageReference(long messageId, long channelId, long guildId, @Nullable Message referencedMessage, JDA api)
+    public MessageReference(int type, long messageId, long channelId, long guildId, @Nullable Message referencedMessage, JDA api)
     {
+        this.type = type;
         this.messageId = messageId;
         this.channelId = channelId;
         this.guildId = guildId;
@@ -213,6 +215,27 @@ public Guild getGuild()
         return guild;
     }
 
+    /**
+     * The message reference type id
+     *
+     * @return The raw type id
+     */
+    public int getTypeRaw()
+    {
+        return type;
+    }
+
+    /**
+     * The type of this message reference
+     *
+     * @return The {@link MessageReferenceType} or {@link MessageReferenceType#UNKNOWN}
+     */
+    @Nonnull
+    public MessageReferenceType getType()
+    {
+        return MessageReferenceType.fromId(type);
+    }
+
     /**
      * Returns the message id for this reference, or 0 if no message id was provided.
      *
@@ -298,4 +321,53 @@ private void checkPermission(Permission permission)
         if (!selfMember.hasPermission(guildChannel, permission))
             throw new InsufficientPermissionException(guildChannel, permission);
     }
+
+    /**
+     * The type of message reference
+     */
+    public enum MessageReferenceType
+    {
+        /** This message reference indicates a replied to message */
+        DEFAULT(0),
+        /** This message reference indicates a forwarded message */
+        FORWARD(1),
+
+        UNKNOWN(-1);
+
+        private final int id;
+
+        MessageReferenceType(int id)
+        {
+            this.id = id;
+        }
+
+        /**
+         * Convert the raw type id to the message reference type enum
+         *
+         * @param  id
+         *         Raw type id
+         *
+         * @return Enum constant of the reference type or {@link #UNKNOWN}
+         */
+        @Nonnull
+        public static MessageReferenceType fromId(int id)
+        {
+            for (MessageReferenceType type : values())
+            {
+                if (type.id == id)
+                    return type;
+            }
+            return UNKNOWN;
+        }
+
+        /**
+         * The raw type id used in the API.
+         *
+         * @return The raw type id
+         */
+        public int getId()
+        {
+            return id;
+        }
+    }
 }