Skip to main content
The announcements feature lets moderators schedule messages to be sent to any text channel at a future time, or on a recurring schedule using cron expressions. Scheduled messages are stored in PostgreSQL and fire even after a bot restart.

​
Configuration

config.json
{
  "announce": {
    "enabled": false
  }
}
Set enabled to true to activate the feature. The /announce command is gated behind moderator permission.

​
Scheduling a one-time message

Use /announce once to send a message at a specific future time: 
/announce once time: in 2h  channel: #announcements  message: Server maintenance starts in 2 hours.
/announce once time: tomorrow 09:00  channel: #general  message: Good morning everyone!
/announce once time: 2026-04-01 14:00  channel: #events  message: April Fools event starts now.

​
Supported time formats

FormatExampleDescription
in Xhin 2hX hours from now
in Xmin 30mX minutes from now
in XhYmin 1h30mX hours and Y minutes from now
tomorrow HH:MMtomorrow 09:00Next day at the given 24-hour time
YYYY-MM-DD HH:MM2026-04-01 14:00Absolute date and time
The time must be in the future. Parsing is case-insensitive.

​
Scheduling a recurring message

Use /announce recurring with a 5-field cron expression: 
/announce recurring cron: 0 9 * * *  channel: #general  message: Good morning!
/announce recurring cron: 0 9 * * 1  channel: #general  message: Happy Monday, everyone.
/announce recurring cron: 0 17 * * 5  channel: #off-topic  message: It's Friday — ship it.
Cron format: 
┌───── minute (0–59)
│ ┌───── hour (0–23)
│ │ ┌───── day of month (1–31)
│ │ │ ┌───── month (1–12)
│ │ │ │ ┌───── day of week (0–6, Sunday=0)
│ │ │ │ │
* * * * *
Common expressions:
ExpressionFires
0 9 * * *Every day at 9:00 AM
0 9 * * 1Every Monday at 9:00 AM
0 17 * * 5Every Friday at 5:00 PM
0 12 1 * *First of every month at noon
The bot validates the cron expression and computes the next run time before saving. If the expression is invalid, the command returns an error with the expected format.

​
Managing scheduled messages

Lists all active scheduled messages for the server, ordered by next run time. Shows the message ID, type (once or recurring with cron), target channel, next fire time, and a content preview.Requires moderator permission.
Cancels a scheduled message by ID. Sets enabled = false in the database — the message is not deleted, just disabled.
OptionRequiredDescription
idYesScheduled message ID (shown in the /announce list output)
The original author can always cancel their own messages. Moderators can cancel any message.Requires moderator permission or ownership of the scheduled message.

​
Commands reference

Schedules a one-time message.
OptionRequiredDescription
timeYesWhen to send (see supported formats above)
channelYesTarget text channel
messageYesMessage content
Requires moderator permission.
Schedules a recurring message.
OptionRequiredDescription
cronYes5-field cron expression
channelYesTarget text channel
messageYesMessage content
Requires moderator permission.

​
How scheduling works

The scheduler polls the scheduled_messages table every minute looking for rows where next_run <= NOW() and enabled = true.
  • One-time messages — sent once, then marked enabled = false.
  • Recurring messages — sent, then next_run is updated to the next cron fire time. The message keeps firing until cancelled.
The /announce command is restricted to moderators. Ensure your moderator role IDs are configured in permissions.moderatorRoleIds before enabling this feature.

Build docs developers (and LLMs) love

Get started for freeTalk to us