How to Automate Discord Event Reminders using the API

Understanding the Discord API

Setting Up Discord API Authentication

Bot tokens are static credentials that do not expire until reset. For event management, the bot needs Manage Events to create or delete events, and Send Messages in the announcement channel where reminders are posted. No privileged intents are required — scheduled events are accessible via REST without a Gateway connection.

1. 1Go to https://discord.com/developers/applications and click New Application.
2. 2Open the Bot tab. Click Reset Token — copy it immediately.
3. 3No privileged intents needed for REST-based event reminders.
4. 4Open OAuth2 > URL Generator. Select scopes: bot and applications.commands.
5. 5Under Bot Permissions, check: Manage Events, Send Messages, Embed Links, View Channels.
6. 6Copy the generated URL and invite the bot to your server.
7. 7Identify the announcement channel where reminders will be posted and copy its ID.
8. 8Store DISCORD_BOT_TOKEN, DISCORD_GUILD_ID, and DISCORD_ANNOUNCEMENT_CHANNEL_ID in environment variables.

1import os
2import requests
3
4BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
5BASE = "https://discord.com/api/v10"
6HEADERS = {"Authorization": f"Bot {BOT_TOKEN}", "Content-Type": "application/json"}
7
8# Verify authentication
9resp = requests.get(f"{BASE}/users/@me", headers=HEADERS)
10resp.raise_for_status()
11print(f"Authenticated as: {resp.json()['username']}")

Key endpoints

1{"channel_id":"voice_channel_id","name":"Weekly AMA","privacy_level":2,"scheduled_start_time":"2026-05-15T18:00:00+00:00","scheduled_end_time":"2026-05-15T19:00:00+00:00","description":"Ask me anything about our product roadmap","entity_type":2}

1{"id":"998877665544","guild_id":"555555555","channel_id":"voice_channel_id","name":"Weekly AMA","description":"Ask me anything","scheduled_start_time":"2026-05-15T18:00:00+00:00","scheduled_end_time":"2026-05-15T19:00:00+00:00","privacy_level":2,"status":1,"entity_type":2,"user_count":0}

1[{"id":"998877665544","guild_id":"555555555","name":"Weekly AMA","scheduled_start_time":"2026-05-15T18:00:00+00:00","status":1,"entity_type":2,"user_count":24}]

1{"content":"@here Event reminder!","embeds":[{"title":"Weekly AMA starts in 1 hour!","description":"Get your questions ready.","color":16776960,"fields":[{"name":"When","value":"<t:1747335600:F>","inline":true},{"name":"Interested","value":"24 members","inline":true}]}]}

1{"id":"112233445566","channel_id":"111222333444","content":"@here Event reminder!","embeds":[{"title":"Weekly AMA starts in 1 hour!"}],"timestamp":"2026-05-15T17:00:00.000Z"}

Step-by-step automation

1curl -X POST \
2  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Weekly AMA",
6    "entity_type": 3,
7    "scheduled_start_time": "2026-05-15T18:00:00+00:00",
8    "scheduled_end_time": "2026-05-15T19:00:00+00:00",
9    "privacy_level": 2,
10    "entity_metadata": {"location": "https://discord.com/invite/your-server"}
11  }' \
12  "https://discord.com/api/v10/guilds/$GUILD_ID/scheduled-events"

1curl -s -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
2  "https://discord.com/api/v10/guilds/$GUILD_ID/scheduled-events?with_user_count=true" \
3  | python3 -m json.tool

1UNIX_START=$(date -d "2026-05-15T18:00:00Z" +%s)
2curl -X POST \
3  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
4  -H "Content-Type: application/json" \
5  -d "{
6    \"content\": \"@here Event reminder!\",
7    \"embeds\": [{
8      \"title\": \"Weekly AMA starts in 1 hour!\",
9      \"description\": \"Get your questions ready!\",
10      \"color\": 16776960,
11      \"fields\": [
12        {\"name\": \"Starts\", \"value\": \"<t:$UNIX_START:F>\", \"inline\": true},
13        {\"name\": \"Countdown\", \"value\": \"<t:$UNIX_START:R>\", \"inline\": true}
14      ]
15    }]
16  }" \
17  "https://discord.com/api/v10/channels/$CHANNEL_ID/messages"

1# No cURL equivalent — this is application-level state management
2# Verify your sent-state file exists:
3ls -la sent_reminders.json 2>/dev/null || echo '{"sent": []}' > sent_reminders.json

Complete working code

A complete event reminder script that polls all scheduled events every 5 minutes, checks reminder windows, avoids duplicates via persistent state, and posts formatted embeds with Discord timestamps to the announcement channel. Run via cron (every 5 minutes) or as a long-running process with asyncio.sleep.

1import os, time, json, logging, requests
2from datetime import datetime, timezone
3from pathlib import Path
4
5logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
6
7BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
8GUILD_ID = os.environ["DISCORD_GUILD_ID"]
9ANN_CHANNEL = os.environ["DISCORD_ANNOUNCEMENT_CHANNEL_ID"]
10BASE = "https://discord.com/api/v10"
11HEADERS = {"Authorization": f"Bot {BOT_TOKEN}", "Content-Type": "application/json"}
12STATE_FILE = Path("sent_reminders.json")
13REMINDER_WINDOWS = {"1h": (55, 65), "15m": (10, 20)}
14POLL_INTERVAL = 300  # 5 minutes
15
16def load_sent():
17    if STATE_FILE.exists():
18        return set(tuple(x) for x in json.loads(STATE_FILE.read_text()).get("sent", []))
19    return set()
20
21def save_sent(sent):
22    STATE_FILE.write_text(json.dumps({"sent": [list(x) for x in sent]}))
23
24def get_events():
25    resp = requests.get(f"{BASE}/guilds/{GUILD_ID}/scheduled-events",
26                       params={"with_user_count": "true"}, headers=HEADERS)
27    resp.raise_for_status()
28    return [e for e in resp.json() if e["status"] == 1]
29
30def minutes_until(event):
31    start = datetime.fromisoformat(event["scheduled_start_time"].replace("Z", "+00:00"))
32    return (start - datetime.now(timezone.utc)).total_seconds() / 60
33
34def send_reminder(event, label):
35    start = datetime.fromisoformat(event["scheduled_start_time"].replace("Z", "+00:00"))
36    ts = int(start.timestamp())
37    colors = {"1h": 16776960, "15m": 16711680}
38    labels = {"1h": "starts in 1 hour", "15m": "starts in 15 minutes"}
39    payload = {
40        "content": "@here",
41        "embeds": [{
42            "title": f"{event['name']} {labels.get(label, 'is starting soon')}!",
43            "description": event.get("description", ""),
44            "color": colors.get(label, 5814783),
45            "fields": [
46                {"name": "Starts", "value": f"<t:{ts}:F>", "inline": True},
47                {"name": "Countdown", "value": f"<t:{ts}:R>", "inline": True},
48                {"name": "Interested", "value": str(event.get("user_count", 0)), "inline": True}
49            ]
50        }]
51    }
52    requests.post(f"{BASE}/channels/{ANN_CHANNEL}/messages",
53                  headers=HEADERS, json=payload).raise_for_status()
54    logging.info(f"Sent {label} reminder for '{event['name']}'")
55
56def run():
57    sent = load_sent()
58    while True:
59        try:
60            events = get_events()
61            active_ids = {e["id"] for e in events}
62            sent = {(eid, lbl) for eid, lbl in sent if eid in active_ids}  # Prune stale
63            for event in events:
64                mins = minutes_until(event)
65                for label, (lo, hi) in REMINDER_WINDOWS.items():
66                    if lo <= mins <= hi and (event["id"], label) not in sent:
67                        send_reminder(event, label)
68                        sent.add((event["id"], label))
69                        save_sent(sent)
70        except Exception as e:
71            logging.error(f"Poll error: {e}")
72        time.sleep(POLL_INTERVAL)
73
74if __name__ == "__main__":
75    run()
76

Error handling

Rate Limits for Discord API

1import time, random
2
3def poll_with_backoff(url, headers, max_retries=5):
4    import requests
5    for i in range(max_retries):
6        resp = requests.get(url, headers=headers)
7        remaining = int(resp.headers.get('X-RateLimit-Remaining', 1))
8        if resp.status_code == 429:
9            wait = resp.json().get('retry_after', 1) + random.uniform(0, 0.5)
10            time.sleep(wait)
11            continue
12        if remaining <= 2:
13            time.sleep(float(resp.headers.get('X-RateLimit-Reset-After', 1)))
14        return resp
15    raise RuntimeError('Max retries exceeded')

• Poll on a 5-minute interval — not faster. One poll per 5 minutes uses 1 API call; even with 20 events, reminder sends use at most 2 extra calls per poll.
• Read X-RateLimit-Remaining on every scheduled-events poll response and skip the next poll if it's 0.
• Store sent-reminder state in a database — JSON file is fine for small deployments but SQLite or Redis handle concurrent access and restarts better.
• Don't poll if you know no events are scheduled in the next 24 hours — check your database and skip polling until events exist.
• For servers with many events, filter SCHEDULED events (status=1) at the API level — the endpoint returns only non-expired events by default, but filtering on status reduces unnecessary processing.

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Use ISO 8601 timestamps with explicit UTC offset (+00:00) when creating events — never pass naive (timezone-unaware) datetimes.
• Store reminder state persistently (database or file) — in-memory state is lost on bot restart and causes duplicate reminders.
• Use Discord timestamp tags (<t:UNIX:F> and <t:UNIX:R>) in reminder embeds — they display in each viewer's local timezone automatically without any server-side conversion.
• Filter events to status=1 (SCHEDULED) only — ACTIVE (2), COMPLETED (3), and CANCELED (4) events should not trigger reminders.
• Set your polling window slightly larger than the poll interval — for a 5-minute poll, use a 10-minute wide reminder window (e.g., 55-65 minutes for the 1-hour reminder).
• Prune stale entries from your sent-reminders state after each poll — remove entries for events that are no longer in the SCHEDULED list to keep state small.
• Implement a startup check: on bot start, verify the announcement channel exists and the bot has Send Messages permission before starting the poll loop.

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations

Explore related guides

Guides from other topics that help with this issue