Durations & time

Lots of commands take a duration (tempban, timeout, temprole) or a point in time (reminder, lockdown until, schedule). Both are flexible about how you write them.

Durations

A duration is a number followed by a unit. Units can be combined, and spaces are optional.

!tempban @someone 7d
!timeout @someone 30m
!temprole @someone @VIP 1w
!mute @someone 2h30m

Unit	Accepted as
Years	`y`, `year`, `years`
Months	`mo`, `month`, `months`
Weeks	`w`, `week`, `weeks`
Days	`d`, `day`, `days`
Hours	`h`, `hr`, `hrs`, `hour`, `hours`
Minutes	`m`, `min`, `mins`, `minute`, `minutes`
Seconds	`s`, `sec`, `secs`, `second`, `seconds`

Combining works in any sensible order, largest first:

!tempban @someone 1w3d
!timeout @someone 1h30m
!temprole @someone @VIP 2mo1w

m is minutes, mo is months. !tempban @someone 3m is a three-minute ban, not a three-month one. This is the single most common mistake with duration arguments.

Clock notation also works where a duration is expected:

!timeout @someone 1:30
!timeout @someone 2 days, 4:00

Limits

Discord and the bot both impose caps:

Context	Maximum
`timeout`	28 days (Discord’s limit)
Antinuke `--duration`	12 hours
Antiraid invite pause	24 hours (Discord’s limit)
Message deletion on ban	7 days (Discord’s limit)
Slowmode	6 hours (Discord’s limit)
Most durations	10 seconds minimum

Points in time

Commands that take a when rather than a how long accept natural language:

!reminder tomorrow at 5pm call mama
!reminder in 3 hours check the oven
!lockdown until 6pm
!lockdown all until midnight
!schedule add #general every day at 12am

Things that parse:

You write	Means
`5pm`, `17:00`	Today at that time, or tomorrow if it’s passed
`tomorrow at 5pm`	Tomorrow
`in 3 hours`, `3h`	Relative to now
`next monday`	The coming Monday
`march 14`, `14 march`	That date
`every day at 12am`	A recurring schedule
`every sunday at 6pm`	A recurring weekly schedule

Put the time first and the message after — !reminder 2h check the oven. If the parser eats part of your message, quote the time: !reminder "tomorrow at 5pm" call mama.

Timezones

Times are interpreted in your timezone once you’ve set one:

!timezone set America/New_York
!timezone set Chicago
!timezone set EST

Accepts IANA names (Europe/London), city names (Tokyo) and common abbreviations (EST, PST, GMT). Without one, times are UTC. Check yours with !timezone, or someone else’s with !timezone @someone. This affects reminders, scheduled messages, lockdown until, birthdays and anything else time-based.

Dates

Birthday and date arguments are lenient:

!birthday set March 14
!birthday set 14 March
!birthday set 3/14
!birthday set 14/03

Ambiguous numeric dates like 3/4 are a coin flip between March 4th and April 3rd. Write the month name to be sure.

How durations are displayed

Output is written the way a person would say it — 2 hours, 3 days, 4 hours, 1 month. In scripts, a duration variable renders the same way, and date variables render as Unix timestamps you can drop into Discord’s timestamp markdown:

{description: expires <t:{expires_at}:R>}

See timestamps.

​Durations

​Limits

​Points in time

​Timezones

​Dates

​How durations are displayed

Durations

Limits

Points in time

Timezones

Dates

How durations are displayed