Announcements — Scheduled Announcements

GrumpyAnnouncements schedules one-time or recurring messages that the bot automatically posts to a channel at a set time — optionally with a role ping.

---

Activation

In configs/config.yml:

addons:
  announcements: true   # Default: true

There is no dedicated configs/modules/announcements.yml — the module is purely database-backed. Announcements are only created/managed via the /announce command, not via a config file.

---

How It Works

The bot checks every minute for due announcements:

1. All announcements with scheduledFor <= now are atomically "claimed" (a database update that includes the state change in the same operation, so overlapping ticks can't send the same one twice).
2. One-time announcements are then set to inactive.
3. Recurring announcements immediately get their next due date.
4. Only after that is the actual message sent to the target channel — if sending fails (e.g. channel deleted), the schedule still advances; there's no automatic retry loop for a permanently broken channel.

---

Recurrence

Value	Meaning
none (default)	One-time — automatically inactive afterward
daily	Daily, same time
weekly	Weekly, same weekday/time
monthly	Monthly, same day of the month

Monthly edge case: If the scheduled day doesn't exist in the target month (e.g. Jan 31 → February has no 31st), it's clamped to the last day of the target month (Feb 28/29) instead of rolling over into the following month.

No catch-up spam after downtime: If the bot was offline longer than the recurrence interval (e.g. several days for a daily announcement), on the next start it does not replay every missed occurrence in rapid succession. Instead, the schedule jumps straight to the next future point in time — the announcement is sent at most once per tick, no matter how many intervals were missed during the downtime.

---

Commands

/announce create

Schedules a new announcement.

Option	Required	Description
channel	✅	Target text channel (text or announcement channel)
in	✅	Time until first send, e.g. 30m, 2h, 1d, 1h30m
message	✅	Announcement text (max 1800 characters)
recurring	❌	none (default) | daily | weekly | monthly
ping-role	❌	Role to ping when it's sent

/announce create channel:#announcements in:2h message:"Server maintenance tonight at 10 PM!"
/announce create channel:#events in:1d message:"Weekly community night!" recurring:weekly ping-role:@Event-Ping

A maximum of 25 active announcements per server at once.

---

/announce list

Lists all active (not yet fired, or ongoing recurring) announcements with ID, channel, next send time (relative), recurrence, and a text preview.

/announce list

---

/announce cancel

Cancels a scheduled announcement. The id option offers autocomplete based on text/ID.

Option	Required	Description
id	✅	Announcement ID (autocomplete available)

/announce cancel id:12

---

Permissions

• Command usage: Manage Guild — set as the Discord default permission, additionally re-checked at runtime (defense-in-depth, in case a server admin has loosened the default permission via Integrations).
• Bot permission: The bot needs send permissions in the target channel, plus @&Role mention permissions when ping-role is used.