---
title: "Discord APIs & Bot Integration"
description: "Comprehensive technical reference for Discord REST API, Gateway WebSocket, Interactions, Webhooks, and Bot Architecture."
---

import { Card, CardGrid } from '@astrojs/starlight/components';

## Overview of the Discord Developer Platform

Discord exposes robust programming interfaces that enable automated moderation systems, forensic audit tooling, custom event handlers, and community management bots.

---

## Core API Architectures

<CardGrid>
  <Card title="REST API (HTTPS)" icon="document">
    Stateless CRUD operations over `https://discord.com/api/v10/`. Used for channels, roles, guild settings, bans, kicks, message modifications, and audit logs.
  </Card>
  <Card title="Gateway API (WebSockets)" icon="laptop">
    Bi-directional, real-time WebSocket connection (`wss://gateway.discord.gg`). Emits events such as `MESSAGE_CREATE`, `GUILD_MEMBER_ADD`, `INTERACTION_CREATE`, and guild state synchronizations.
  </Card>
  <Card title="Interactions & Slash Commands" icon="setting">
    Low-latency event-driven architecture. Supports slash commands (`/command`), user/message context menus, modal popups, and UI components (buttons, select menus).
  </Card>
  <Card title="Incoming Webhooks" icon="external">
    One-way posting endpoints allowing third-party services (GitHub, Sentry, Stripe, moderation scripts) to push rich embeds directly to channels without a full bot client.
  </Card>
</CardGrid>

---

## Rate Limits & Concurrency Management

Discord enforces strict rate limits to guarantee system stability and prevent abuse:

1. **Global Rate Limit**: Up to 50 requests per second per bot token across all REST endpoints.
2. **Per-Route Buckets**: Individual endpoints enforce distinct limits specified via HTTP response headers:
   - `X-RateLimit-Limit`: Maximum allowable requests in the current window.
   - `X-RateLimit-Remaining`: Remaining request allowance before exhaustion.
   - `X-RateLimit-Reset-After`: Seconds until the current bucket window replenishes.
   - `X-RateLimit-Bucket`: Unique hash identifying the route bucket.
3. **HTTP 429 Too Many Requests**: When exceeded, developers must honor the `retry_after` parameter to prevent temporary network IP bans.

---

## Gateway Intents & Privileged Data

Modern bot development requires declaring Gateway Intents:

- **Guilds (`1 << 0`)**: Guild lifecycle and metadata.
- **Guild Members (`1 << 1`)** *(Privileged)*: Track joins, leaves, member updates.
- **Guild Moderation (`1 << 2`)**: Audit log events, ban/unban dispatches.
- **Message Content (`1 << 15`)** *(Privileged)*: Required to inspect plain-text message contents for keyword filtering and custom regex automod.

---

## Security Best Practices for Bot Developers

- **Never Commit Bot Tokens**: Always store bot secrets in environment variables (`.env`) or secret vaults.
- **Principle of Least Privilege**: Grant only necessary permissions in the bot invite OAuth2 generator.
- **Ephemeral Responses for Staff Commands**: Use `flags: 64` (Ephemeral) on slash commands containing sensitive moderation logs or user warnings.