Skip to main content

Listeners

NestCord supports interacting with all discord events via the @On and @Once decorator.
While the best practice is to use the more specific decorators when possible, this is useful if you wish to use features NestCord doesn't support via custom decorators, to interact with the raw requests, or to listen to all events using a decorator such as interactionCreate.

src/app.service.ts
import {Injectable, Logger} from '@nestjs/common';
import {Once, On, Context, ContextOf} from '@globalart/nestcord';

@Injectable()
export class AppService {
private readonly logger = new Logger(AppService.name);

@Once('ready')
public onReady(@Context() [client]: ContextOf<'ready'>) {
this.logger.log(`Bot logged in as ${client.user.username}`);
}

@On('warn')
public onWarn(@Context() [message]: ContextOf<'warn'>) {
this.logger.warn(message);
}
}
Warning

If you use global filters, guards or interceptors, they will be triggered once per event!
This means if you are replying to the message in guards, you can run into issues with duplicated responses or invalid interactions. Have a look at the NestCordExecutionContext.getInfo() metadata to learn more about the current context.

Context

You might have noticed the @Context decorator in the last snippet: This is used to inject the event context within the method. As there are many type of events, its type must be inferred from the ContextOf<type: string> type.

You can access the context variables by using the @Context() decorator within your function, which will populate the variable with an array of arguments.

src/app.service.ts
@On('messageCreate')
public onMessageCreate(@Context() [message]: ContextOf<'messageCreate'>) {
console.log(message.content);
}

Custom Events

NestCord out of the box supports all the events provided by discord.js. You can also create custom events using the @CustomListenerHandler and @CustomListener decorators.

src/app.service.ts
import { Injectable } from '@nestjs/common';
import { CustomListener, CustomListenerHandler, BaseHandler, ContextOf } from '@globalart/nestcord';
import { User, UserFlagsBitField } from 'discord.js';

export type CustomUserUpdateEvents = {
userAvatarUpdate: [user: User, oldAvatar: string, newAvatar: string];
};

export type ContextOfCustomUserUpdate<K extends keyof E, E = CustomUserUpdateEvents> = E[K];


@Injectable()
@CustomListener('userUpdate')
export class UserUpdateHandler extends BaseHandler<CustomUserUpdateEvents> {
@CustomListenerHandler()
public handleUserAvatarUpdate([oldUser, newUser]: ContextOf<'userUpdate'>) {
if (oldUser.partial) return;

if (oldUser.displayAvatarURL() !== newUser.displayAvatarURL()) {
this.emit(
'userAvatarUpdate',
newUser,
oldUser.displayAvatarURL(),
newUser.displayAvatarURL()
);
}
}
}

And then you can listen to the custom event using the @On decorator.

src/app.service.ts
@On('userAvatarUpdate')
public onUserAvatarUpdate(
@Context() [user, oldAvatar, newAvatar]: ContextOfCustomUserUpdate<'userAvatarUpdate'>
) {
console.log(
`User ${user.tag} changed their avatar from ${oldAvatar} to ${newAvatar}`
);
}

Also supports custom events.

Channel Events

Event NameDescription
guildChannelPermissionsUpdateEmitted whenever a channel's permission overwrite for a guild is updated.

Guild Events

Event NameDescription
guildBoostLevelUpEmitted whenever a guild's boost level increases.
guildBoostLevelDownEmitted whenever a guild's boost level decreases.
guildBannerAddEmitted whenever a guild's banner is added.
guildAfkChannelAddEmitted whenever a guild's AFK channel is added.
guildVanityURLAddEmitted whenever a guild's vanity URL is added.
guildVanityURLUpdateEmitted whenever a guild's vanity URL is updated.
guildVanityURLRemoveEmitted whenever a guild's vanity URL is removed.
guildFeaturesUpdateEmitted whenever a guild's features are updated.
guildAcronymUpdateEmitted whenever a guild's acronym is updated.
guildOwnerUpdateEmitted whenever a guild's owner is updated.
guildPartnerAddEmitted whenever a guild's is partner of discord now
guildPartnerRemoveEmitted whenever a guild's is no longer partner of discord
guildVerificationAddEmitted whenever a guild's verification level is added.
guildVerificationRemoveEmitted whenever a guild's verification level is removed.

Guild Audit Log Events

Event NameDescription
guildAuditLogEntryAddEmitted whenever an entry is added to the audit log.
guildAuditLogEntryUpdateEmitted whenever an entry is updated in the audit log.
guildAuditLogEntryDeleteEmitted whenever an entry is removed from the audit log.
guildAuditLogEntryWebhookCreateEmitted whenever a webhook is created in the audit log.
guildAuditLogEntryWebhookUpdateEmitted whenever a webhook is updated in the audit log.
guildAuditLogEntryWebhookDeleteEmitted whenever a webhook is deleted in the audit log.

Guild Member Events

Event NameDescription
guildMemberBoostEmitted whenever a member's boost is activated.
guildMemberUnboostEmitted whenever a member's boost is deactivated.
guildMemberRoleAddEmitted whenever a role is added to a member.
guildMemberRoleRemoveEmitted whenever a role is removed from a member.
guildMemberNicknameUpdateEmitted whenever a member's nickname is updated.
guildMemberEnteredEmitted whenever a member enters a guild.
guildMemberAvatarAddEmitted whenever a member's avatar is added.
guildMemberAvatarRemoveEmitted whenever a member's avatar is removed.
guildMemberAvatarUpdateEmitted whenever a member's avatar is updated.

Role Update Events

Event NameDescription
rolePositionUpdateEmitted whenever a role's position is updated.
rolePermissionsUpdateEmitted whenever a role's permissions are updated.
roleIconAddEmitted whenever a role's icon is added.
roleIconRemoveEmitted whenever a role's icon is removed.
roleIconUpdateEmitted whenever a role's icon is updated.

Thread Update Events

Event NameDescription
threadStateUpdateEmitted whenever a thread's state is updated.
threadNameUpdateEmitted whenever a thread's name is updated.
threadLockStateUpdateEmitted whenever a thread's lock state is updated.
threadRateLimitPerUserUpdateEmitted whenever a thread's rate limit per user is updated.
threadAutoArchiveDurationUpdateEmitted whenever a thread's auto archive duration is updated.

Message Events

Event NameDescription
messagePinnedEmitted whenever a message is pinned.
messageContentEditedEmitted whenever a message is updated.

Presence Events

Event NameDescription
guildMemberOfflineEmitted whenever a member goes offline.
guildMemberOnlineEmitted whenever a member goes online.

User Events

Event NameDescription
userAvatarUpdateEmitted whenever a user's avatar is updated.
userUsernameUpdateEmitted whenever a user's username is updated.
userDiscriminatorUpdateEmitted whenever a user's discriminator is updated.
userFlagsUpdateEmitted whenever a user's flags are updated.

Voice Events

Event NameDescription
voiceChannelJoinEmitted whenever a member joins a voice channel.
voiceChannelLeaveEmitted whenever a member leaves a voice channel.
voiceChannelSwitchEmitted whenever a member switches voice channel.
voiceChannelMutestateEmitted whenever a member is muted or deafened in a voice channel.
voiceChannelUnmuteEmitted whenever a member is unmuted in a voice channel.
voiceChannelDeafEmitted whenever a member is deafened in a voice channel.
voiceChannelUndeafEmitted whenever a member is undeafened in a voice channel.
voiceStreamingStartEmitted whenever a member starts streaming.
voiceStreamingStopEmitted whenever a member stops streaming.