0
# Event System
1

2
Real-time event handling system for responding to Discord gateway events with comprehensive event types and flexible listener patterns.
3

4
## Capabilities
5

6
### Event Foundation
7

8
Base event system providing the foundation for all Discord gateway events.
9

10
```java { .api }
11
/**
12
 * Base interface for all JDA events.
13
 */
14
interface GenericEvent {
15
    /** Get JDA instance that fired this event */
16
    JDA getJDA();
17
    
18
    /** Get response number for event ordering */
19
    long getResponseNumber();
20
}
21

22
/**
23
 * Abstract base class providing empty implementations of all event handler methods.
24
 * Extend this class and override only the events you want to handle.
25
 */
26
abstract class ListenerAdapter {
27
    // Message Events
28
    void onMessageReceived(MessageReceivedEvent event);
29
    void onMessageUpdate(MessageUpdateEvent event);
30
    void onMessageDelete(MessageDeleteEvent event);
31
    void onMessageBulkDelete(MessageBulkDeleteEvent event);
32
    void onMessageReactionAdd(MessageReactionAddEvent event);
33
    void onMessageReactionRemove(MessageReactionRemoveEvent event);
34
    void onMessageReactionRemoveAll(MessageReactionRemoveAllEvent event);
35
    void onMessageReactionRemoveEmoji(MessageReactionRemoveEmojiEvent event);
36
    
37
    // Guild Member Events
38
    void onGuildMemberJoin(GuildMemberJoinEvent event);
39
    void onGuildMemberRemove(GuildMemberRemoveEvent event);
40
    void onGuildMemberUpdate(GuildMemberUpdateEvent event);
41
    void onGuildMemberRoleAdd(GuildMemberRoleAddEvent event);
42
    void onGuildMemberRoleRemove(GuildMemberRoleRemoveEvent event);
43
    void onGuildMemberUpdateNickname(GuildMemberUpdateNicknameEvent event);
44
    void onGuildMemberUpdateAvatar(GuildMemberUpdateAvatarEvent event);
45
    void onGuildMemberUpdateBoostTime(GuildMemberUpdateBoostTimeEvent event);
46
    void onGuildMemberUpdateTimeOut(GuildMemberUpdateTimeOutEvent event);
47
    void onGuildMemberUpdateFlags(GuildMemberUpdateFlagsEvent event);
48
    
49
    // Guild Events
50
    void onGuildReady(GuildReadyEvent event);
51
    void onGuildJoin(GuildJoinEvent event);
52
    void onGuildLeave(GuildLeaveEvent event);
53
    void onGuildAvailable(GuildAvailableEvent event);
54
    void onGuildUnavailable(GuildUnavailableEvent event);
55
    void onGuildUpdate(GuildUpdateEvent event);
56
    void onGuildBan(GuildBanEvent event);
57
    void onGuildUnban(GuildUnbanEvent event);
58
    
59
    // Channel Events
60
    void onChannelCreate(ChannelCreateEvent event);
61
    void onChannelDelete(ChannelDeleteEvent event);
62
    void onChannelUpdateName(ChannelUpdateNameEvent event);
63
    void onChannelUpdateTopic(ChannelUpdateTopicEvent event);
64
    void onChannelUpdatePosition(ChannelUpdatePositionEvent event);
65
    void onChannelUpdateNSFW(ChannelUpdateNSFWEvent event);
66
    void onChannelUpdateSlowmode(ChannelUpdateSlowmodeEvent event);
67
    void onChannelUpdateBitrate(ChannelUpdateBitrateEvent event);
68
    void onChannelUpdateUserLimit(ChannelUpdateUserLimitEvent event);
69
    
70
    // Voice Events
71
    void onGuildVoiceUpdate(GuildVoiceUpdateEvent event);
72
    void onGuildVoiceJoin(GuildVoiceJoinEvent event);
73
    void onGuildVoiceMove(GuildVoiceMoveEvent event);
74
    void onGuildVoiceLeave(GuildVoiceLeaveEvent event);
75
    void onGuildVoiceMute(GuildVoiceMuteEvent event);
76
    void onGuildVoiceDeafen(GuildVoiceDeafenEvent event);
77
    void onGuildVoiceSelfMute(GuildVoiceSelfMuteEvent event);
78
    void onGuildVoiceSelfDeafen(GuildVoiceSelfDeafenEvent event);
79
    void onGuildVoiceSuppress(GuildVoiceSuppressEvent event);
80
    void onGuildVoiceStream(GuildVoiceStreamEvent event);
81
    void onGuildVoiceVideo(GuildVoiceVideoEvent event);
82
    void onGuildVoiceRequestToSpeak(GuildVoiceRequestToSpeakEvent event);
83
    
84
    // Interaction Events
85
    void onSlashCommandInteraction(SlashCommandInteractionEvent event);
86
    void onUserContextInteraction(UserContextInteractionEvent event);
87
    void onMessageContextInteraction(MessageContextInteractionEvent event);
88
    void onButtonInteraction(ButtonInteractionEvent event);
89
    void onSelectMenuInteraction(SelectMenuInteractionEvent event);
90
    void onStringSelectInteraction(StringSelectInteractionEvent event);
91
    void onEntitySelectInteraction(EntitySelectInteractionEvent event);
92
    void onModalInteraction(ModalInteractionEvent event);
93
    void onCommandAutoCompleteInteraction(CommandAutoCompleteInteractionEvent event);
94
    
95
    // Role Events
96
    void onRoleCreate(RoleCreateEvent event);
97
    void onRoleDelete(RoleDeleteEvent event);
98
    void onRoleUpdate(RoleUpdateEvent event);
99
    
100
    // Thread Events
101
    void onThreadRevealed(ThreadRevealedEvent event);
102
    void onThreadHidden(ThreadHiddenEvent event);
103
    void onThreadMemberJoin(ThreadMemberJoinEvent event);
104
    void onThreadMemberLeave(ThreadMemberLeaveEvent event);
105
    
106
    // Generic update events
107
    void onGenericUpdate(GenericUpdateEvent event);
108
    void onGenericGuildUpdate(GenericGuildUpdateEvent event);
109
    void onGenericGuildMemberUpdate(GenericGuildMemberUpdateEvent event);
110
    void onGenericChannelUpdate(GenericChannelUpdateEvent event);
111
    void onGenericRoleUpdate(GenericRoleUpdateEvent event);
112
    void onGenericMessageReaction(GenericMessageReactionEvent event);
113
    void onGenericInteractionCreate(GenericInteractionCreateEvent event);
114
    
115
    // Status Events
116
    void onReady(ReadyEvent event);
117
    void onDisconnect(DisconnectEvent event);
118
    void onReconnect(ReconnectEvent event);
119
    void onResume(ResumedEvent event);
120
    void onShutdown(ShutdownEvent event);
121
    void onStatusChange(StatusChangeEvent event);
122
    void onException(ExceptionEvent event);
123
    void onGatewayPing(GatewayPingEvent event);
124
}
125
```
126

127
**Usage Examples:**
128

129
```java
130
import net.dv8tion.jda.api.hooks.ListenerAdapter;
131
import net.dv8tion.jda.api.events.message.MessageReceivedEvent;
132
import net.dv8tion.jda.api.events.guild.member.GuildMemberJoinEvent;
133

134
public class MyBot extends ListenerAdapter {
135
    @Override
136
    public void onMessageReceived(MessageReceivedEvent event) {
137
        String content = event.getMessage().getContentRaw();
138
        
139
        // Ignore bot messages
140
        if (event.getAuthor().isBot()) return;
141
        
142
        // Respond to ping
143
        if (content.equals("!ping")) {
144
            event.getChannel().sendMessage("Pong!").queue();
145
        }
146
    }
147
    
148
    @Override
149
    public void onGuildMemberJoin(GuildMemberJoinEvent event) {
150
        // Welcome new members
151
        String welcome = String.format("Welcome %s to %s!", 
152
            event.getUser().getName(), 
153
            event.getGuild().getName());
154
        
155
        // Send to system channel if available
156
        TextChannel systemChannel = event.getGuild().getSystemChannel();
157
        if (systemChannel != null) {
158
            systemChannel.sendMessage(welcome).queue();
159
        }
160
    }
161
}
162

163
// Register the listener
164
JDA jda = JDABuilder.createDefault(token)
165
    .addEventListeners(new MyBot())
166
    .build();
167
```
168

169
### Message Events  
170

171
Events related to message lifecycle including creation, editing, deletion, and reactions.
172

173
```java { .api }
174
/**
175
 * Indicates that a Message was received in a MessageChannel.
176
 */
177
class MessageReceivedEvent extends GenericMessageEvent {
178
    /** Get the received message */
179
    Message getMessage();
180
    
181
    /** Get message author */
182
    User getAuthor();
183
    
184
    /** Get author as member (null if not in guild) */
185
    Member getMember();
186
    
187
    /** Check if message is from webhook */
188
    boolean isWebhookMessage();
189
    
190
    /** Get webhook that sent message (if applicable) */
191
    WebhookClient getWebhookClient();
192
}
193

194
/**
195
 * Indicates that a Message was edited in a MessageChannel.
196
 */
197
class MessageUpdateEvent extends GenericMessageEvent {
198
    /** Get updated message */
199
    Message getMessage();
200
    
201
    /** Get message author */
202
    User getAuthor();
203
    
204
    /** Get author as member */
205
    Member getMember();
206
}
207

208
/**
209
 * Indicates that a Message was deleted in a MessageChannel.
210
 */
211
class MessageDeleteEvent extends GenericMessageEvent {
212
    // Note: Message content is not available in delete events
213
    
214
    /** Get message ID that was deleted */
215
    long getMessageIdLong();
216
    String getMessageId();
217
}
218

219
/**
220
 * Indicates that multiple Messages were deleted at once.
221
 */
222
class MessageBulkDeleteEvent extends GenericMessageEvent {
223
    /** Get list of deleted message IDs */
224
    List<String> getMessageIds();
225
    
226
    /** Get count of deleted messages */
227
    int getMessageCount();
228
}
229

230
/**
231
 * Indicates that a reaction was added to a message.
232
 */
233
class MessageReactionAddEvent extends GenericMessageReactionEvent {
234
    /** Get user who added reaction */
235
    User getUser();
236
    
237
    /** Get member who added reaction */
238
    Member getMember();
239
    
240
    /** Get reaction that was added */
241
    MessageReaction getReaction();
242
    
243
    /** Get reaction emoji */
244
    MessageReaction.ReactionEmoji getReactionEmoji();
245
    
246
    /** Retrieve full message */
247
    RestAction<Message> retrieveMessage();
248
}
249

250
/**
251
 * Indicates that a reaction was removed from a message.
252
 */
253
class MessageReactionRemoveEvent extends GenericMessageReactionEvent {
254
    /** Get user who removed reaction */
255
    User getUser();
256
    
257
    /** Get member who removed reaction */
258
    Member getMember();
259
    
260
    /** Get reaction that was removed */
261
    MessageReaction getReaction();
262
    
263
    /** Get reaction emoji */
264
    MessageReaction.ReactionEmoji getReactionEmoji();
265
}
266
```
267

268
### Guild Member Events
269

270
Events related to guild membership changes, role updates, and member property modifications.
271

272
```java { .api }
273
/**
274
 * Indicates that a user joined a guild.
275
 */
276
class GuildMemberJoinEvent extends GenericGuildMemberEvent {
277
    /** Get user who joined */
278
    User getUser();
279
    
280
    /** Get guild member object */
281
    Member getMember();
282
    
283
    /** Get guild that was joined */
284
    Guild getGuild();
285
}
286

287
/**
288
 * Indicates that a user left a guild.
289
 */
290
class GuildMemberRemoveEvent extends GenericGuildEvent {
291
    /** Get user who left */
292
    User getUser();
293
    
294
    /** Get guild that was left */
295
    Guild getGuild();
296
    
297
    /** Get cached member (if available) */
298
    Member getMember();
299
}
300

301
/**
302
 * Indicates that a guild member's roles were modified.
303
 */
304
class GuildMemberRoleAddEvent extends GenericGuildMemberEvent {
305
    /** Get roles that were added */
306
    List<Role> getRoles();
307
    
308
    /** Get member whose roles changed */
309
    Member getMember();
310
}
311

312
/**
313
 * Indicates that roles were removed from a guild member.
314
 */
315
class GuildMemberRoleRemoveEvent extends GenericGuildMemberEvent {
316
    /** Get roles that were removed */
317
    List<Role> getRoles();
318
    
319
    /** Get member whose roles changed */
320
    Member getMember();
321
}
322

323
/**
324
 * Indicates that a guild member's nickname was changed.
325
 */
326
class GuildMemberUpdateNicknameEvent extends GenericGuildMemberUpdateEvent<String> {
327
    /** Get old nickname */
328
    String getOldNickname();
329
    
330
    /** Get new nickname */
331
    String getNewNickname();
332
}
333

334
/**
335
 * Indicates that a guild member was timed out or timeout was removed.
336
 */
337
class GuildMemberUpdateTimeOutEvent extends GenericGuildMemberUpdateEvent<OffsetDateTime> {
338
    /** Get old timeout end time */
339
    OffsetDateTime getOldTimeOutEnd();
340
    
341
    /** Get new timeout end time */
342
    OffsetDateTime getNewTimeOutEnd();
343
}
344
```
345

346
### Guild Events
347

348
Events related to guild lifecycle, properties, and availability.
349

350
```java { .api }
351
/**
352
 * Indicates that JDA has finished loading a guild.
353
 */
354
class GuildReadyEvent extends GenericGuildEvent {
355
    /** Get guild that became ready */
356
    Guild getGuild();
357
}
358

359
/**
360
 * Indicates that the bot joined a new guild.
361
 */
362
class GuildJoinEvent extends GenericGuildEvent {
363
    /** Get guild that was joined */
364
    Guild getGuild();
365
}
366

367
/**
368
 * Indicates that the bot left a guild.
369
 */
370
class GuildLeaveEvent extends GenericGuildEvent {
371
    /** Get guild that was left */
372
    Guild getGuild();
373
}
374

375
/**
376
 * Indicates that a guild became available.
377
 */
378
class GuildAvailableEvent extends GenericGuildEvent {
379
    /** Get guild that became available */
380
    Guild getGuild();
381
}
382

383
/**
384
 * Indicates that a guild became unavailable.
385
 */
386
class GuildUnavailableEvent extends GenericGuildEvent {
387
    /** Get guild that became unavailable */
388
    Guild getGuild();
389
}
390

391
/**
392
 * Indicates that a user was banned from a guild.
393
 */
394
class GuildBanEvent extends GenericGuildEvent {
395
    /** Get user who was banned */
396
    User getUser();
397
    
398
    /** Get guild where ban occurred */
399
    Guild getGuild();
400
}
401

402
/**
403
 * Indicates that a user was unbanned from a guild.
404
 */
405
class GuildUnbanEvent extends GenericGuildEvent {
406
    /** Get user who was unbanned */
407
    User getUser();
408
    
409
    /** Get guild where unban occurred */
410
    Guild getGuild();
411
}
412
```
413

414
### Voice Events
415

416
Events related to voice channel activity and voice state changes.
417

418
```java { .api }
419
/**
420
 * Indicates that a guild voice event occurred.
421
 */
422
abstract class GenericGuildVoiceEvent extends GenericGuildEvent {
423
    /** Get member whose voice state changed */
424
    Member getMember();
425
    
426
    /** Get voice state */
427
    GuildVoiceState getVoiceState();
428
}
429

430
/**
431
 * Indicates that a member joined a voice channel.
432
 */
433
class GuildVoiceJoinEvent extends GenericGuildVoiceEvent {
434
    /** Get voice channel that was joined */
435
    AudioChannel getChannelJoined();
436
}
437

438
/**
439
 * Indicates that a member left a voice channel.
440
 */
441
class GuildVoiceLeaveEvent extends GenericGuildVoiceEvent {
442
    /** Get voice channel that was left */
443
    AudioChannel getChannelLeft();
444
}
445

446
/**
447
 * Indicates that a member moved between voice channels.
448
 */
449
class GuildVoiceMoveEvent extends GenericGuildVoiceEvent {
450
    /** Get voice channel that was left */
451
    AudioChannel getChannelLeft();
452
    
453
    /** Get voice channel that was joined */
454
    AudioChannel getChannelJoined();
455
}
456

457
/**
458
 * Indicates that a member was muted/unmuted.
459
 */
460
class GuildVoiceMuteEvent extends GenericGuildVoiceEvent {
461
    /** Check if member is now muted */
462
    boolean isMuted();
463
}
464

465
/**
466
 * Indicates that a member was deafened/undeafened.
467
 */
468
class GuildVoiceDeafenEvent extends GenericGuildVoiceEvent {
469
    /** Check if member is now deafened */
470
    boolean isDeafened();
471
}
472

473
/**
474
 * Indicates that a member muted/unmuted themselves.
475
 */
476
class GuildVoiceSelfMuteEvent extends GenericGuildVoiceEvent {
477
    /** Check if member is now self-muted */
478
    boolean isSelfMuted();
479
}
480

481
/**
482
 * Indicates that a member deafened/undeafened themselves.
483
 */
484
class GuildVoiceSelfDeafenEvent extends GenericGuildVoiceEvent {
485
    /** Check if member is now self-deafened */
486
    boolean isSelfDeafened();
487
}
488
```
489

490
### Channel Events
491

492
Events related to channel creation, deletion, and property updates.
493

494
```java { .api }
495
/**
496
 * Indicates that a channel was created.
497
 */
498
class ChannelCreateEvent extends GenericChannelEvent {
499
    /** Get channel that was created */
500
    Channel getChannel();
501
}
502

503
/**
504
 * Indicates that a channel was deleted.
505
 */
506
class ChannelDeleteEvent extends GenericChannelEvent {
507
    /** Get channel that was deleted */
508
    Channel getChannel();
509
}
510

511
/**
512
 * Indicates that a text channel's name was updated.
513
 */
514
class ChannelUpdateNameEvent extends GenericChannelUpdateEvent<String> {
515
    /** Get old channel name */
516
    String getOldName();
517
    
518
    /** Get new channel name */
519
    String getNewName();
520
}
521

522
/**
523
 * Indicates that a text channel's topic was updated.
524
 */
525
class ChannelUpdateTopicEvent extends GenericChannelUpdateEvent<String> {
526
    /** Get old channel topic */
527
    String getOldTopic();
528
    
529
    /** Get new channel topic */
530
    String getNewTopic();
531
}
532

533
/**
534
 * Indicates that a channel's position was updated.
535
 */
536
class ChannelUpdatePositionEvent extends GenericChannelUpdateEvent<Integer> {
537
    /** Get old channel position */
538
    int getOldPosition();
539
    
540
    /** Get new channel position */
541
    int getNewPosition();
542
}
543

544
/**
545
 * Indicates that a channel's NSFW status was updated.
546
 */
547
class ChannelUpdateNSFWEvent extends GenericChannelUpdateEvent<Boolean> {
548
    /** Get old NSFW status */
549
    boolean getOldNSFW();
550
    
551
    /** Get new NSFW status */
552
    boolean getNewNSFW();
553
}
554
```
555

556
### Session Events
557

558
Events related to JDA connection status and session management.
559

560
```java { .api }
561
/**
562
 * Indicates that JDA has finished loading and is ready to operate.
563
 */
564
class ReadyEvent extends GenericEvent {
565
    /** Get number of guilds available */
566
    int getGuildAvailableCount();
567
    
568
    /** Get number of guilds unavailable */
569
    int getGuildUnavailableCount();
570
    
571
    /** Get total number of guilds */
572
    int getGuildTotalCount();
573
}
574

575
/**
576
 * Indicates that JDA has disconnected from Discord.
577
 */
578
class DisconnectEvent extends GenericEvent {
579
    /** Get time when disconnection occurred */
580
    OffsetDateTime getTimeDisconnected();
581
    
582
    /** Get disconnect code */
583
    CloseCode getCloseCode();
584
    
585
    /** Get disconnect reason */
586
    String getCloseReason();
587
    
588
    /** Check if disconnect was by server */
589
    boolean isClosedByServer();
590
}
591

592
/**
593
 * Indicates that JDA has reconnected to Discord.
594
 */
595
class ReconnectedEvent extends GenericEvent {
596
    // No additional methods
597
}
598

599
/**
600
 * Indicates that JDA has resumed a previous session.
601
 */
602
class ResumedEvent extends GenericEvent {
603
    // No additional methods
604
}
605

606
/**
607
 * Indicates that JDA is shutting down.
608
 */
609
class ShutdownEvent extends GenericEvent {
610
    /** Get time when shutdown occurred */
611
    OffsetDateTime getTimeShutdown();
612
    
613
    /** Get shutdown code */
614
    int getCode();
615
}
616

617
/**
618
 * Indicates that JDA's status has changed.
619
 */
620
class StatusChangeEvent extends GenericEvent {
621
    /** Get old status */
622
    JDA.Status getOldStatus();
623
    
624
    /** Get new status */
625
    JDA.Status getNewStatus();
626
}
627

628
/**
629
 * Indicates that an exception occurred in JDA.
630
 */
631
class ExceptionEvent extends GenericEvent {
632
    /** Get exception that occurred */
633
    Throwable getCause();
634
    
635
    /** Check if exception is logged */
636
    boolean isLogged();
637
}
638
```
639

640
## Types
641

642
```java { .api }
643
// Close codes for websocket disconnections
644
enum CloseCode {
645
    NORMAL_CLOSURE, GOING_AWAY, PROTOCOL_ERROR, UNSUPPORTED_DATA,
646
    NO_STATUS_CODE, ABNORMAL_CLOSURE, INVALID_FRAME_PAYLOAD,
647
    POLICY_VIOLATION, MESSAGE_TOO_BIG, MANDATORY_EXTENSION,
648
    INTERNAL_SERVER_ERROR, SERVICE_RESTART, TRY_AGAIN_LATER,
649
    BAD_GATEWAY, TLS_HANDSHAKE_FAILURE, UNKNOWN_ERROR,
650
    UNKNOWN_OPCODE, DECODE_ERROR, NOT_AUTHENTICATED, 
651
    AUTHENTICATION_FAILED, ALREADY_AUTHENTICATED,
652
    INVALID_SEQUENCE, RATE_LIMITED, SESSION_TIMEOUT,
653
    INVALID_SHARD, SHARDING_REQUIRED, INVALID_API_VERSION,
654
    INVALID_INTENTS, DISALLOWED_INTENTS
655
}
656

657
// Gateway intents for filtering events
658
enum GatewayIntent {
659
    GUILDS, GUILD_MEMBERS, GUILD_MODERATION, GUILD_EMOJIS_AND_STICKERS,
660
    GUILD_INTEGRATIONS, GUILD_WEBHOOKS, GUILD_INVITES, GUILD_VOICE_STATES,
661
    GUILD_PRESENCES, GUILD_MESSAGES, GUILD_MESSAGE_REACTIONS, GUILD_MESSAGE_TYPING,
662
    DIRECT_MESSAGES, DIRECT_MESSAGE_REACTIONS, DIRECT_MESSAGE_TYPING, MESSAGE_CONTENT,
663
    GUILD_SCHEDULED_EVENTS, AUTO_MODERATION_CONFIGURATION, AUTO_MODERATION_EXECUTION
664
}
665
```