title	Serve Events
description	Complete reference for all events emitted via stdout in serve mode

Serve Events

When running discli serve, events are emitted as JSONL (one JSON object per line) on stdout. Every event includes an "event" field identifying the event type.

ready

Emitted once when the bot connects to the Discord gateway. This fires before slash commands are synced.

{
  "event": "ready",
  "bot_id": "123456789",
  "bot_name": "MyBot#1234"
}

Field	Type	Description
`bot_id`	string	Bot's user snowflake ID
`bot_name`	string	Bot's username and discriminator

slash_commands_synced

Emitted after slash commands have been registered with Discord (only if --slash-commands was provided).

{
  "event": "slash_commands_synced",
  "count": 3,
  "guilds": 2
}

Field	Type	Description
`count`	integer	Number of slash commands registered
`guilds`	integer	Number of guilds commands were synced to

message

Emitted when a message is sent in a visible channel. Bot messages from other bots are excluded; the bot's own messages are included by default (controlled by --include-self / --no-include-self).

{
  "event": "message",
  "server": "My Server",
  "server_id": "123456",
  "channel": "general",
  "channel_id": "789012",
  "author": "alice",
  "author_id": "111222",
  "is_bot": false,
  "content": "Hello everyone!",
  "timestamp": "2024-01-15T12:30:00+00:00",
  "message_id": "333444",
  "mentions_bot": false,
  "is_dm": false,
  "attachments": [],
  "reply_to": null
}

Field	Type	Description
`server`	string \| null	Server name, or `null` for DMs
`server_id`	string \| null	Server snowflake ID, or `null` for DMs
`channel`	string	Channel name, or `"DM"` for direct messages
`channel_id`	string	Channel snowflake ID
`author`	string	Message author's username
`author_id`	string	Author's user snowflake ID
`is_bot`	boolean	Whether the author is a bot
`content`	string	Message text content
`timestamp`	string	ISO 8601 timestamp
`message_id`	string	Message snowflake ID
`mentions_bot`	boolean	Whether the message @-mentions the bot
`is_dm`	boolean	Whether this is a direct message
`attachments`	array	List of `{"filename", "url", "size"}` objects
`reply_to`	string \| null	Message ID this is a reply to, or `null`

slash_command

Emitted when a user invokes a registered slash command. The interaction is automatically deferred (shows "thinking..."). You must respond using interaction_followup or stream_start with the interaction_token.

{
  "event": "slash_command",
  "command": "ask",
  "args": {"question": "What is discli?"},
  "channel_id": "789012",
  "user": "alice",
  "user_id": "111222",
  "guild_id": "123456",
  "interaction_token": "uuid-string",
  "is_admin": false
}

Field	Type	Description
`command`	string	Slash command name
`args`	object	Key-value map of command arguments (all values are strings)
`channel_id`	string	Channel where the command was invoked
`user`	string	Username of the invoking user
`user_id`	string	User snowflake ID
`guild_id`	string \| null	Server ID, or `null` for DM slash commands
`interaction_token`	string	Token for responding via `interaction_followup` or `stream_start`
`is_admin`	boolean	Whether the user has administrator permission in the guild

message_edit

Emitted when a non-bot user edits a message.

{
  "event": "message_edit",
  "server": "My Server",
  "server_id": "123456",
  "channel": "general",
  "channel_id": "789012",
  "author": "alice",
  "author_id": "111222",
  "message_id": "333444",
  "old_content": "Hello",
  "new_content": "Hello everyone!",
  "timestamp": "2024-01-15T12:35:00+00:00"
}

Field	Type	Description
`server`	string \| null	Server name
`server_id`	string \| null	Server snowflake ID
`channel`	string	Channel name
`channel_id`	string	Channel snowflake ID
`author`	string	Author username
`author_id`	string	Author user snowflake ID
`message_id`	string	Edited message snowflake ID
`old_content`	string \| null	Previous message content (may be null if uncached)
`new_content`	string	New message content
`timestamp`	string	ISO 8601 timestamp of the edit

message_delete

Emitted when a message is deleted.

{
  "event": "message_delete",
  "server": "My Server",
  "server_id": "123456",
  "channel": "general",
  "channel_id": "789012",
  "author": "alice",
  "author_id": "111222",
  "message_id": "333444",
  "content": "Hello everyone!"
}

Field	Type	Description
`server`	string \| null	Server name
`server_id`	string \| null	Server snowflake ID
`channel`	string	Channel name
`channel_id`	string	Channel snowflake ID
`author`	string \| null	Author username (null if uncached)
`author_id`	string \| null	Author user snowflake ID (null if uncached)
`message_id`	string	Deleted message snowflake ID
`content`	string \| null	Message content (null if uncached)

reaction_add

Emitted when a user adds a reaction to a message.

{
  "event": "reaction_add",
  "server": "My Server",
  "channel": "general",
  "channel_id": "789012",
  "message_id": "333444",
  "emoji": "thumbsup",
  "user": "alice",
  "user_id": "111222"
}

Field	Type	Description
`server`	string \| null	Server name
`channel`	string	Channel name
`channel_id`	string	Channel snowflake ID
`message_id`	string	Message snowflake ID
`emoji`	string	Emoji name or unicode character
`user`	string	Username of the user who reacted
`user_id`	string	User snowflake ID

reaction_remove

Emitted when a user removes a reaction from a message.

{
  "event": "reaction_remove",
  "server": "My Server",
  "channel": "general",
  "channel_id": "789012",
  "message_id": "333444",
  "emoji": "thumbsup",
  "user": "alice",
  "user_id": "111222"
}

Field	Type	Description
`server`	string \| null	Server name
`channel`	string	Channel name
`channel_id`	string	Channel snowflake ID
`message_id`	string	Message snowflake ID
`emoji`	string	Emoji name or unicode character
`user`	string	Username of the user
`user_id`	string	User snowflake ID

member_join

Emitted when a new member joins a server.

{
  "event": "member_join",
  "server": "My Server",
  "server_id": "123456",
  "member": "alice",
  "member_id": "111222"
}

Field	Type	Description
`server`	string	Server name
`server_id`	string	Server snowflake ID
`member`	string	New member's username
`member_id`	string	Member's user snowflake ID

member_remove

Emitted when a member leaves or is removed from a server.

{
  "event": "member_remove",
  "server": "My Server",
  "server_id": "123456",
  "member": "alice",
  "member_id": "111222"
}

Field	Type	Description
`server`	string	Server name
`server_id`	string	Server snowflake ID
`member`	string	Member's username
`member_id`	string	Member's user snowflake ID

voice_state

Emitted when a member's voice state changes (joins, leaves, moves between, or updates settings in a voice channel).

{
  "event": "voice_state",
  "action": "joined",
  "member": "alice",
  "channel": "General Voice",
  "channel_id": "789012"
}

Field	Type	Description
`action`	string	One of `joined`, `left`, `moved`, or `updated`
`member`	string	Member's username
`channel`	string	Voice channel name
`channel_id`	string	Voice channel snowflake ID

Voice events

Voice events are emitted by the engine when the bot connects, plays audio, or transcribes speech. Each has the standard event field plus a guild_id.

voice_connected

Emitted after the bot joins a voice channel.

{"event": "voice_connected", "guild_id": "767327865100304394", "channel_id": "1016638171854938152"}

voice_disconnected

Emitted after the bot leaves a voice channel.

{"event": "voice_disconnected", "guild_id": "767327865100304394"}

voice_playback_started

Emitted when TTS or file playback begins.

{"event": "voice_playback_started", "guild_id": "767327865100304394", "type": "tts"}

Field	Type	Description
`type`	string	`tts` or `file`
`source`	string	Source URL/path (for `file` type)

voice_playback_finished

Emitted when playback completes or is stopped.

{"event": "voice_playback_finished", "guild_id": "767327865100304394"}

voice_speech_detected

Emitted when STT returns a finalised transcription for a speaker. Interim partials are not surfaced — only finals.

{
  "event": "voice_speech_detected",
  "guild_id": "767327865100304394",
  "channel_id": "1016638171854938152",
  "user_id": "743173584935190620",
  "text": "okay let's get started",
  "confidence": 0.94,
  "is_final": true
}

Field	Type	Description
`user_id`	string	Speaker's user snowflake ID
`text`	string	Finalised transcript
`confidence`	number	Provider-reported confidence (`0.0` – `1.0`)
`is_final`	bool	Always `true` for this event (interim partials are filtered out)

component_interaction

Emitted when a user interacts with a message component (button click, select menu choice). Respond using interaction_respond, interaction_edit, or modal_send with the interaction_token.

{
  "event": "component_interaction",
  "custom_id": "ok",
  "component_type": 2,
  "values": [],
  "user": "alice",
  "interaction_token": "uuid-string"
}

Field	Type	Description
`custom_id`	string	The `custom_id` set on the component
`component_type`	integer	Component type (`2` = button, `3` = select menu)
`values`	array	Selected values (empty for buttons, populated for select menus)
`user`	string	Username of the interacting user
`interaction_token`	string	Token for responding to the interaction

modal_submit

Emitted when a user submits a modal form. Respond using interaction_respond or interaction_edit with the interaction_token.

{
  "event": "modal_submit",
  "custom_id": "feedback-form",
  "fields": {"name": "Alice", "message": "Great bot!"},
  "user": "alice",
  "interaction_token": "uuid-string"
}

Field	Type	Description
`custom_id`	string	The `custom_id` set on the modal
`fields`	object	Key-value map of field `custom_id` to submitted value
`user`	string	Username of the submitting user
`interaction_token`	string	Token for responding to the submission

disconnected

Emitted when the bot loses its connection to the Discord gateway.

{"event": "disconnected"}

No additional fields.

resumed

Emitted when the bot successfully reconnects to the Discord gateway after a disconnection.

{"event": "resumed"}

No additional fields.

response

Emitted as the reply to every stdin action. Contains "ok": true on success or an "error" string on failure. If the original action included a req_id, it is echoed back.

{"event": "response", "ok": true, "message_id": "789", "req_id": "1"}

{"event": "response", "error": "Channel not found: 999", "req_id": "2"}

Field	Type	Description
`ok`	boolean	Present and `true` on success
`error`	string	Present on failure with an error description
`req_id`	string	Echoed from the original action, if provided
(varies)		Additional fields depend on the action (see Serve Actions)

error

Emitted when an internal error occurs (e.g., invalid JSON on stdin, slash command sync failure).

{"event": "error", "message": "Invalid JSON: {bad input"}

Field	Type	Description
`message`	string	Error description

shutdown

Emitted when the bot process is shutting down (e.g., Ctrl+C).

{"event": "shutdown"}

No additional fields.

Event Filtering

Use the --events option to limit which events are emitted. Pass a comma-separated list of event categories:

Category	Events included
`messages`	`message`
`edits`	`message_edit`
`deletes`	`message_delete`
`reactions`	`reaction_add`, `reaction_remove`
`members`	`member_join`, `member_remove`
`voice`	`voice_state`, `voice_connected`, `voice_disconnected`, `voice_playback_started`, `voice_playback_finished`, `voice_speech_detected`

The ready, slash_command, slash_commands_synced, component_interaction, modal_submit, response, error, disconnected, resumed, and shutdown events are always emitted regardless of the filter.

Example:

discli serve --events messages,reactions

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Serve Events

ready

slash_commands_synced

message

slash_command

message_edit

message_delete

reaction_add

reaction_remove

member_join

member_remove

voice_state

Voice events

voice_connected

voice_disconnected

voice_playback_started

voice_playback_finished

voice_speech_detected

component_interaction

modal_submit

disconnected

resumed

response

error

shutdown

Event Filtering

FilesExpand file tree

serve-events.mdx

Latest commit

History

serve-events.mdx

File metadata and controls

Serve Events

ready

slash_commands_synced

message

slash_command

message_edit

message_delete

reaction_add

reaction_remove

member_join

member_remove

voice_state

Voice events

voice_connected

voice_disconnected

voice_playback_started

voice_playback_finished

voice_speech_detected

component_interaction

modal_submit

disconnected

resumed

response

error

shutdown

Event Filtering