Package net.dv8tion.jda.api.interactions

Interface InteractionHook

All Superinterfaces:

ISnowflake, WebhookClient<Message>

public interface InteractionHook
extends WebhookClient<Message>

Webhook API for an interaction. Valid for up to 15 minutes after the interaction.
This can be used to send followup messages or edit the original message of an interaction.

The interaction has to be acknowledged before any of these actions can be performed. First, you need to call one of:

• deferReply(...)
• reply(...)
• deferEdit()
• editMessage(...)

When IReplyCallback.deferReply() is used, the first message will act identically to editOriginal(...). This means that you cannot make your deferred reply ephemeral through this interaction hook. You need to specify whether your reply is ephemeral or not directly in deferReply(boolean).

See Also:

• IReplyCallback
• IMessageEditCallback
• editOriginal(String)
• deleteOriginal()
• WebhookClient.sendMessage(String)

Method Summary

Modifier and Type	Method	Description
default RestAction<Void>	deleteOriginal()	Delete the original reply.
default WebhookMessageEditAction<Message>	editOriginal(String content)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginal(MessageEditData message)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginalAttachments(Collection<? extends AttachedFile> attachments)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginalAttachments(AttachedFile... attachments)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginalComponents(Collection<? extends LayoutComponent> components)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginalComponents(LayoutComponent... components)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginalEmbeds(Collection<? extends MessageEmbed> embeds)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginalEmbeds(MessageEmbed... embeds)	Edit the source message sent by this interaction.
default WebhookMessageEditAction<Message>	editOriginalFormat(String format, Object... args)	Edit the source message sent by this interaction.
static InteractionHook	from(JDA jda, String token)	Creates an instance of InteractionHook capable of executing webhook requests.
long	getExpirationTimestamp()	The unix millisecond timestamp for the expiration of this interaction hook.
Interaction	getInteraction()	The interaction attached to this hook.
JDA	getJDA()	The JDA instance for this interaction
default boolean	isExpired()	Whether this interaction has expired.
default RestAction<Message>	retrieveOriginal()	Retrieves the original reply to this interaction.
InteractionHook	setEphemeral(boolean ephemeral)	Whether messages sent from this interaction hook should be ephemeral by default.

Methods inherited from interface net.dv8tion.jda.api.entities.ISnowflake

getId, getIdLong, getTimeCreated

Methods inherited from interface net.dv8tion.jda.api.entities.WebhookClient

deleteMessageById, deleteMessageById, editMessageAttachmentsById, editMessageAttachmentsById, editMessageAttachmentsById, editMessageAttachmentsById, editMessageById, editMessageById, editMessageById, editMessageById, editMessageComponentsById, editMessageComponentsById, editMessageComponentsById, editMessageComponentsById, editMessageEmbedsById, editMessageEmbedsById, editMessageEmbedsById, editMessageEmbedsById, editMessageFormatById, editMessageFormatById, getToken, retrieveMessageById, sendFiles, sendFiles, sendMessage, sendMessage, sendMessageComponents, sendMessageComponents, sendMessageEmbeds, sendMessageEmbeds, sendMessageFormat, sendMessagePoll

Method Details

getInteraction

@Nonnull
Interaction getInteraction()

The interaction attached to this hook.

Returns:

The Interaction

Throws:

IllegalStateException - If this instance was created through from(JDA, String)

getExpirationTimestamp

long getExpirationTimestamp()

The unix millisecond timestamp for the expiration of this interaction hook.
An interaction hook expires after 15 minutes of its creation.

Returns:

The timestamp in millisecond precision

See Also:

• System.currentTimeMillis()
• isExpired()

isExpired

default boolean isExpired()

Whether this interaction has expired.
An interaction hook is only valid for 15 minutes.

Returns:

True, if this interaction hook has expired

See Also:

• getExpirationTimestamp()

setEphemeral

@Nonnull
InteractionHook setEphemeral(boolean ephemeral)

Whether messages sent from this interaction hook should be ephemeral by default.
This does not affect message updates, including deferred replies sent with sendMessage(...) methods.
When a message is ephemeral, it will only be visible to the user that used the interaction.

Ephemeral messages have some limitations and will be removed once the user restarts their client.
Limitations:

• Cannot be reacted to
• Can only be retrieved using the InteractionHook

Note: Your message can appear ephemeral in several cases:

• In guilds the bot is not a member of, if the member is unable to use external application, this usually happens for user-installed commands
• If the interaction user is unable to send messages
• If the content contains elements the user does not have the permission to send (like files or embeds)
• If the content triggered AutoMod

Parameters:

ephemeral - True if messages should be ephemeral

Returns:

The same interaction hook instance

getJDA

@Nonnull
JDA getJDA()

The JDA instance for this interaction

Specified by:

getJDA in interface WebhookClient<Message>

Returns:

The JDA instance

retrieveOriginal

@Nonnull
@CheckReturnValue
default RestAction<Message> retrieveOriginal()

Retrieves the original reply to this interaction.
This doesn't work for ephemeral messages and will always cause an unknown message error response.

Returns:

RestAction - Type: Message

editOriginal

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginal(@Nonnull
 String content)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

Possible ErrorResponses include:

• UNKNOWN_WEBHOOK
  The webhook is no longer available, either it was deleted or in case of interactions it expired.
• UNKNOWN_MESSAGE
  The message for that id does not exist
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

content - The new message content to use

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If the provided content is null, empty, or longer than Message.MAX_CONTENT_LENGTH

editOriginalComponents

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginalComponents(@Nonnull
 Collection<? extends LayoutComponent> components)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

Possible ErrorResponses include:

• UNKNOWN_WEBHOOK
  The webhook is no longer available, either it was deleted or in case of interactions it expired.
• UNKNOWN_MESSAGE
  The message for that id does not exist
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

components - The new component layouts for this message, such as ActionRows

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If the provided components are null, or more than 5 layouts are provided

editOriginalComponents

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginalComponents(@Nonnull
 LayoutComponent... components)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

Possible ErrorResponses include:

• UNKNOWN_WEBHOOK
  The webhook is no longer available, either it was deleted or in case of interactions it expired.
• UNKNOWN_MESSAGE
  The message for that id does not exist
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

components - The new component layouts for this message, such as ActionRows

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If the provided components are null, or more than 5 layouts are provided

editOriginalEmbeds

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginalEmbeds(@Nonnull
 Collection<? extends MessageEmbed> embeds)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

Possible ErrorResponses include:

• UNKNOWN_WEBHOOK
  The webhook is no longer available, either it was deleted or in case of interactions it expired.
• UNKNOWN_MESSAGE
  The message for that id does not exist
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

embeds - MessageEmbeds to use (up to 10 in total)

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If the provided embeds are null, or more than 10

editOriginalEmbeds

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginalEmbeds(@Nonnull
 MessageEmbed... embeds)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

Possible ErrorResponses include:

• UNKNOWN_WEBHOOK
  The webhook is no longer available, either it was deleted or in case of interactions it expired.
• UNKNOWN_MESSAGE
  The message for that id does not exist
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

embeds - The new MessageEmbeds to use

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If the provided embeds are null, or more than 10

editOriginal

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginal(@Nonnull
 MessageEditData message)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

Possible ErrorResponses include:

• UNKNOWN_WEBHOOK
  The webhook is no longer available, either it was deleted or in case of interactions it expired.
• UNKNOWN_MESSAGE
  The message for that id does not exist
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

message - The new message to replace the existing message with

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If the provided message is null

editOriginalFormat

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginalFormat(@Nonnull
 String format,
 @Nonnull
 Object... args)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

Possible ErrorResponses include:

• UNKNOWN_WEBHOOK
  The webhook is no longer available, either it was deleted or in case of interactions it expired.
• UNKNOWN_MESSAGE
  The message for that id does not exist
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Parameters:

format - Format string for the message content

args - Format arguments for the content

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If the formatted string is null, empty, or longer than Message.MAX_CONTENT_LENGTH

editOriginalAttachments

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginalAttachments(@Nonnull
 Collection<? extends AttachedFile> attachments)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

The following ErrorResponses are possible:

• REQUEST_ENTITY_TOO_LARGE
  If any of the provided files is bigger than Guild.getMaxFileSize()
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Parameters:

attachments - The new attachments of the message (Can be FileUploads or AttachmentUpdates)

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If null is provided

See Also:

• AttachedFile.fromAttachment(Message.Attachment)
• FileUpload.fromData(InputStream, String)

editOriginalAttachments

@Nonnull
@CheckReturnValue
default WebhookMessageEditAction<Message> editOriginalAttachments(@Nonnull
 AttachedFile... attachments)

Edit the source message sent by this interaction.
For IMessageEditCallback.editComponents(Collection) and IMessageEditCallback.deferEdit() this will be the message the components are attached to. For IReplyCallback.deferReply() and IReplyCallback.reply(String) this will be the reply message instead.

This method will be delayed until the interaction is acknowledged.

The following ErrorResponses are possible:

• REQUEST_ENTITY_TOO_LARGE
  If any of the provided files is bigger than Guild.getMaxFileSize()
• MISSING_ACCESS
  The request was attempted after the account lost access to the Guild typically due to being kicked or removed, or after Permission.VIEW_CHANNEL was revoked in the GuildMessageChannel
• UNKNOWN_MESSAGE
  The provided messageId is unknown in this MessageChannel, either due to the id being invalid, or the message it referred to has already been deleted. This might also be triggered for ephemeral messages.
• UNKNOWN_CHANNEL
  The request was attempted after the channel was deleted.
• MESSAGE_BLOCKED_BY_AUTOMOD
  If this message was blocked by an AutoModRule
• MESSAGE_BLOCKED_BY_HARMFUL_LINK_FILTER
  If this message was blocked by the harmful link filter

Resource Handling Note: Once the request is handed off to the requester, for example when you call RestAction.queue(), the requester will automatically clean up all opened files by itself. You are only responsible to close them yourself if it is never handed off properly. For instance, if an exception occurs after using FileUpload.fromData(File), before calling RestAction.queue(). You can safely use a try-with-resources to handle this, since FileUpload.close() becomes ineffective once the request is handed off.

Parameters:

attachments - The new attachments of the message (Can be FileUploads or AttachmentUpdates)

Returns:

WebhookMessageEditAction

Throws:

IllegalArgumentException - If null is provided

See Also:

• AttachedFile.fromAttachment(Message.Attachment)
• FileUpload.fromData(InputStream, String)

deleteOriginal

@Nonnull
@CheckReturnValue
default RestAction<Void> deleteOriginal()

Delete the original reply.

Returns:

RestAction

from

@Nonnull
static InteractionHook from(@Nonnull
 JDA jda,
 @Nonnull
 String token)

Creates an instance of InteractionHook capable of executing webhook requests.

Messages created by this client may not have a fully accessible channel or guild available, and getInteraction() throws. The messages might report a channel of type UNKNOWN, in which case the channel is assumed to be inaccessible and limited to only webhook requests.

Parameters:

jda - The JDA instance, used to handle rate-limits

token - The interaction token for the webhook

Returns:

The InteractionHook instance

Throws:

IllegalArgumentException - If null is provided or the token is blank