Events

Events let your bot respond to things happening on Discord — messages, member joins, reactions, and more. These are gateway events (real-time notifications Discord sends your bot over a WebSocket connection). Create handler files in src/events/ named after the event.

Terminal log output from a Robo.js bot showing multiple gateway events being handled, including a ready event with the bot tag and a messageCreate event processing a message

FocusThe terminal log lines showing different event types being handledZoom100%NotesShow terminal output from a running bot that handles ready and messageCreate events. The logs should show the bot processing these events with timestamps. Dark terminal theme.

For details on the priority field, concurrent execution, plugin options argument, and all config fields, see the @robojs/discordjs Events reference.

Creating Event Handlers

Create a file in src/events/ with the name of the Discord event you want to handle. The default export runs when that event fires.

src/events/ready.ts

import { getClient } from '@robojs/discordjs'

export default () => {
	const client = getClient()
	console.log(`Logged in as ${client.user?.tag}`)
}

src/events/ready.js

import { getClient } from '@robojs/discordjs'

export default () => {
	const client = getClient()
	console.log(`Logged in as ${client.user?.tag}`)
}

ready.tsClient ready event

Event Parameters

Different events pass different arguments to the handler function.

Event	File	Parameters
`ready`	`src/events/ready.ts`	`client: Client`
`messageCreate`	`src/events/messageCreate.ts`	`message: Message`
`guildMemberAdd`	`src/events/guildMemberAdd.ts`	`member: GuildMember`
`interactionCreate`	`src/events/interactionCreate.ts`	`interaction: Interaction`
`messageReactionAdd`	`src/events/messageReactionAdd.ts`	`reaction: MessageReaction, user: User`

The ready event passes a Client as its first argument. You can accept it as a parameter or use getClient() — both approaches work identically.

src/events/messageCreate.ts

import type { Message } from 'discord.js'

export default (message: Message) => {
	if (message.content === 'hello') {
		message.reply('Hello there!')
	}
}

src/events/messageCreate.js

export default (message) => {
	if (message.content === 'hello') {
		message.reply('Hello there!')
	}
}

Discord text channel showing a user sending 'hello' and the bot automatically replying with 'Hello there!' demonstrating a messageCreate event handler

FocusThe user message and bot reply exchangeZoom100%NotesShow a Discord text channel where a user sent 'hello' as a regular message and the bot replied with 'Hello there!'. This demonstrates the messageCreate event handler.

Stacked Handlers

Handle the same event with multiple files by creating a folder named after the event. Each file in the folder exports a default handler, and all of them run when the event fires.

log.tsLogs messages

greet.tsAuto-replies

Event Configuration

Export a config object to control how an event handler behaves.

src/events/ready.ts

import type { EventConfig } from '@robojs/discordjs'

export const config: EventConfig = {
	frequency: 'once'
}

export default () => {
	console.log('Bot is ready (runs once)')
}

src/events/ready.js

export const config = {
	frequency: 'once'
}

export default () => {
	console.log('Bot is ready (runs once)')
}

Field	Type	Default	Description
`frequency`	`'always' \| 'once'`	`'always'`	Run on every event or only the first
`priority`	`number`	`0`	Execution order (lower runs first)

Lifecycle Hooks

Robo.js provides framework-level lifecycle hooks that are not Discord events. Place these in src/robo/.

start runs after Robo.js initialization (before the Discord connection is established). Use it for setup tasks like database connections.
ready fires after connecting to Discord's gateway (this is a Discord event, so it stays in src/events/). Use it for anything that needs the Discord client.
stop runs on shutdown with a 5-second timeout. Use it for teardown tasks.

start.tsRuns on startup

stop.tsRuns on shutdown

restart.tsRuns on restart

ready.tsDiscord gateway ready

src/robo/start.ts

export default () => {
	console.log('Bot is starting up')
}

src/robo/start.js

export default () => {
	console.log('Bot is starting up')
}

The legacy src/events/_start.ts pattern still works but src/robo/start.ts is the recommended approach for v0.11+.

Intents

Events require specific intents (filters that tell Discord which events to send your bot) to be enabled. The plugin automatically infers required intents from your registered event handlers and warns about missing ones at startup. See the Intents reference for configuration details.

Next Steps

Sage Mode

Automatic replies, deferrals, and error handling.

Intents

Control which gateway events your bot receives.

Middleware

Intercept and control command execution.

Events

Creating Event Handlers

Event Parameters

Stacked Handlers

Event Configuration

Lifecycle Hooks

Intents

Next Steps

Sage Mode

Intents

Middleware

On this page