API reference
Scheduling
Do something later, or on a repeat. One-off actions, clocks and repeating jobs.
There are three ways to make the bot act later:
| Tool | Use it for | Runs |
|---|---|---|
schedule | One ready action later, like "remove this role in 2 days". | Once |
schedule_clock | Your own code later, like a reminder. | Once |
start_job | Your own code on a repeat, like a daily post. | Again and again |
Write await in front of every function on this page.
Times are plain words, like "in 10 minutes", "tomorrow 5pm" or "next friday". They use your server's timezone, set in the dashboard settings. Without one, the bot uses UTC.
Limits#
| What | Free | Starter | Basic | Advanced |
|---|---|---|---|---|
schedule actions waiting at once | 20 | 100 | 250 | 1,000 |
| Clocks waiting at once | 1,000 | 10,000 | 10,000 | 10,000 |
| Repeating jobs | not available | available | available | available |
A waiting action or clock frees its place when it runs.
schedule#
Runs one ready-made action at a later time. Returns the schedule ID.
await schedule(action, when, data=None, member=None, channel=None)| Argument | What it does |
|---|---|
action | What to do. See the list below. |
when | When to do it, like "in 2 hours". Must be in the future. |
data | The details for the action. A dict, or one plain value. |
member | The member to act on. Defaults to the person who ran the command. |
channel | The channel to act in. Defaults to the current channel. |
Example: a temporary role
await schedule("remove_role", "in 7 days", data={"roles": ["Trial"]})
set_content("You have the Trial role for 7 days.")Example: post a message later
await schedule("send_message", "tomorrow 9am", data="Good morning everyone!")Actions you can schedule#
When you pass one plain value as data, it fills the field marked main.
| Action | data fields |
|---|---|
send_message | content (main), embed, channel |
send_dm | content (main), embed, member |
add_role, remove_role | roles (main), member |
kick_member | member (main), reason |
ban_member | member (main), reason, delete_days (0 to 7) |
unban_member | user (main), reason |
delete_message | channel, message |
edit_message | channel, message, content, embed |
pin_message, unpin_message | channel, message |
purge_messages | amount (main, 1 to 100), channel |
lock_channel, unlock_channel | channel (main) |
set_slowmode | seconds (main, up to 21,600), channel |
update_channel | channel, name, topic, nsfw, slowmode |
delete_channel | channel (main) |
mute_member, unmute_member | member (main) |
create_poll | channel, question, answers (2 to 10), duration (hours) |
embed is a saved embed ID or a built embed. An unknown action fails and lists the valid ones.
cancel_schedule#
Cancels a waiting schedule action.
await cancel_schedule(schedule_id)sid = await schedule("send_message", "in 1 hour", data="Break is over!")
update_member_var("break_id", sid)
# later, in another command:
await cancel_schedule(member_var("break_id"))Fails with "No schedule found with id ..." when it already ran or never existed.
list_schedules#
Lists the waiting schedule actions of this server.
await list_schedules()Returns a list of dicts with id, action, run_at and data.
waiting = await list_schedules()
set_content(f"{len(waiting)} actions are waiting.")schedule_clock#
Runs your Clock event once at a later time. Use it when the ready actions above are not enough.
await schedule_clock(custom_id, time, metadata)| Argument | What it does |
|---|---|
custom_id | A name for this clock. Your Clock event listens for it. |
time | When it fires, like "in 30 minutes". |
metadata | Any data you want back when it fires, like a dict. |
Step 1. In a command, set the clock:
await schedule_clock(
f"remind_{user.id}",
when,
{"user_id": user.id, "channel_id": channel.id, "text": text},
)
set_content("Got it. I will remind you.")Step 2. Make an event of type Clock. In its custom IDs, enter remind_*. The * matches any ending.
send_message(metadata["channel_id"], f"<@{metadata['user_id']}> Reminder: {metadata['text']}")Only the first Clock event that matches runs. See Events and Reminders.
start_job#
Starts a repeating job. Each time it is due, it fires your Clock event with the job's custom_id and metadata.
await start_job(
custom_id,
freq,
interval=1,
date=None,
day_name="",
month=None,
hour=None,
minute=None,
second=None,
metadata=None,
)| Argument | What it does |
|---|---|
custom_id | A name for the job. Must be new in this server. |
freq | How often: "hour", "day", "week", "month" or "year". |
interval | Every how many. 2 with "day" means every 2 days. |
date | Day of the month, 1 to 31. |
day_name | Day of the week, in lowercase, like "monday". |
month | Month of the year, 1 to 12. |
hour, minute, second | Time of day, in your server's timezone. |
metadata | A dict your Clock event gets each time. |
What each freq needs:
freq | Needs |
|---|---|
hour | minute, second |
day | hour, minute, second |
week | day_name, hour, minute, second |
month | date, hour, minute, second |
year | month, date, hour, minute, second |
# Every day at 9:00
await start_job("daily_quote", "day", hour=9, minute=0, second=0,
metadata={"channel": "general"})Premium for repeats
Jobs run only while the server has a paid plan. Without one, a job pauses itself when it is due. It picks up again after you renew.
Note
Run start_job from a command, once. A Clock event that starts its own job never runs, because the job must exist first.
You can also make jobs on the dashboard, under Jobs.
pause_job#
Pauses a running job. You can resume it from the dashboard.
await pause_job(custom_id)cancel_job#
Stops a job and deletes it.
await cancel_job(custom_id)Both fail when no job has that custom_id, or when it is not running.