Discord

​

At a glance

npx @deploybaseline/cli start --service discord

import { createEmulator } from "@deploybaseline/cli";

const discord = await createEmulator({ service: "discord" });
// discord.url is http://localhost:4000

{
  "discord": {
    "users": [
      {
        "username": "ada",
        "email": "[email protected]"
      }
    ],
    "applications": [
      {
        "name": "My Bot",
        "bot_token": "MTAwMDAwMDAwMDAwMDAwMDEx.baseline.discord-bot-token",
        "client_secret": "baseline-discord-client-secret",
        "redirect_uris": ["http://localhost:3000/callback"],
        "commands": [
          {
            "name": "ping",
            "description": "Replies with pong"
          }
        ]
      }
    ],
    "guilds": [
      {
        "name": "My Server",
        "owner": "ada",
        "channels": [
          {
            "name": "general",
            "topic": "Say hi"
          }
        ],
        "bots": [
          {
            "application": "My Bot",
            "permissions": ["ADMINISTRATOR"]
          }
        ]
      }
    ]
  }
}

​

Start

npx @deploybaseline/cli start --service discord

​

Default fixtures

import { Client, Events, GatewayIntentBits } from "discord.js";

const client = new Client({
  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent],
  rest: { api: `${process.env.DISCORD_EMULATOR_URL}/api` },
});

client.on(Events.MessageCreate, async (message) => {
  if (message.content === "!ping") await message.reply("pong");
});

await client.login("MTAwMDAwMDAwMDAwMDAwMDEx.baseline.discord-bot-token");

​

URL mapping

​

Auth

​

OAuth2

• GET /oauth2/authorize — Authorization page: also under /api/v10. Checks client_id, redirect_uri against the application’s redirect_uris, scope, and response_type (code or token), then shows a consent page to pick a seeded user. Cancelling redirects with error=access_denied
• The bot scope installs the application’s bot: the page asks for a server the user can manage (Manage Server), creates the bot’s managed role with the requested permissions, adds the bot, and dispatches GUILD_CREATE to it. With a redirect_uri (or response_type=code), the redirect carries code, guild_id, and permissions, and the code exchange returns the guild
• POST /api/oauth2/token — Token exchange: also under /api/v10. Takes the client by HTTP Basic auth or client_id and client_secret in the form body. Grants: authorization_code (single use codes valid for 10 minutes, PKCE with S256 or plain), refresh_token (rotates both tokens), and client_credentials (a token for the application owner, applications.commands.update included). Access tokens last 7 days
• POST /api/oauth2/token/revoke — Revoke token: revokes an access or refresh token, and GET /api/v10/oauth2/@me describes the current authorization

​

Errors

​

Rate limits

​

Users

​

Guilds

​

Channels

​

Messages

​

Pins

​

Reactions

​

Roles

​

Members

​

Bans

​

Application commands

​

Application

​

Gateway

• HELLO (op 10) with heartbeat_interval (41250 ms, or gateway.heartbeat_interval_ms). Heartbeats (op 1) get HEARTBEAT_ACK (op 11). A client that stops heartbeating is closed with 4009 after one and a half intervals
• IDENTIFY (op 2) checks the token (4004), the intents (4013 for unknown bits, 4014 for a privileged intent the application has not enabled), and the shard (4010), then sends READY with user, guilds (unavailable), session_id, resume_gateway_url, shard, and application, followed by a GUILD_CREATE for each guild when the Guilds intent is set
• RESUME (op 6) replays every event the session missed, in order, then sends RESUMED. A session stays resumable for five minutes after any close except 1000 and 1001; an unknown session or a sequence the buffer no longer covers gets INVALID_SESSION (op 9) with d: false
• REQUEST_GUILD_MEMBERS (op 8) answers with GUILD_MEMBERS_CHUNK (needs the Server Members intent). Presence and voice state updates (ops 3 and 4) are accepted
• Other close codes: 4001 unknown opcode, 4002 a payload that does not decode, 4003 a payload before identifying, 4005 a second identify, 4008 more than 120 payloads a minute, 4012 an unsupported version

​

Interactions

​

Simulating users

• command (the default): command (the name), options as a map checked against the command’s options ({ "text": "hi", "times": 2 }; subcommands as nested maps) or a raw option array, command_type 2 or 3 with target_id for context menu commands, and application_id when two applications have a command with that name
• autocomplete: as command, plus focused naming the option being typed
• component: message_id and custom_id of a button or select menu, and values for a select
• modal_submit: interaction_id of the interaction that opened the modal, and values keyed by text input custom_id

curl -X POST $DISCORD_EMULATOR_URL/_discord/simulate/interaction \
  -H "Content-Type: application/json" \
  -d '{"user_id": "100000000000000001", "channel_id": "100000000000000101", "command": "ping"}'

​

Seed config

{
  "discord": {
    "users": [
      {
        "id": "200000000000000001",
        "username": "ada",
        "global_name": "Ada Lovelace",
        "email": "[email protected]"
      },
      {
        "username": "grace"
      }
    ],
    "applications": [
      {
        "name": "Deploy Bot",
        "owner": "ada",
        "bot_token": "MjAwMDAwMDAwMDAwMDAwMDEx.baseline.deploy-bot",
        "client_secret": "deploy-bot-secret",
        "private_key": "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60",
        "redirect_uris": ["http://localhost:3000/callback"],
        "privileged_intents": ["guild_members", "message_content"],
        "commands": [
          {
            "name": "ping",
            "description": "Replies with pong"
          },
          {
            "name": "deploy",
            "description": "Deploy a service",
            "guild": "Acme",
            "options": [
              {
                "type": 3,
                "name": "service",
                "description": "Which service",
                "required": true
              }
            ]
          }
        ]
      }
    ],
    "guilds": [
      {
        "name": "Acme",
        "owner": "ada",
        "everyone_permissions": [
          "VIEW_CHANNEL",
          "SEND_MESSAGES",
          "READ_MESSAGE_HISTORY",
          "USE_APPLICATION_COMMANDS"
        ],
        "roles": [
          {
            "name": "Moderator",
            "permissions": ["MANAGE_MESSAGES", "KICK_MEMBERS"],
            "hoist": true
          }
        ],
        "channels": [
          {
            "name": "Text Channels",
            "type": "category"
          },
          {
            "name": "general",
            "topic": "Say hi",
            "parent": "Text Channels"
          },
          {
            "name": "staff",
            "parent": "Text Channels",
            "permission_overwrites": [
              {
                "role": "@everyone",
                "deny": ["VIEW_CHANNEL"]
              },
              {
                "role": "Moderator",
                "allow": ["VIEW_CHANNEL"]
              }
            ]
          },
          {
            "name": "Voice",
            "type": "voice"
          }
        ],
        "members": ["grace"],
        "bots": [
          {
            "application": "Deploy Bot",
            "permissions": ["ADMINISTRATOR"]
          }
        ],
        "messages": [
          {
            "channel": "general",
            "author": "ada",
            "content": "Hello from the seed"
          }
        ]
      }
    ],
    "gateway": {
      "heartbeat_interval_ms": 41250
    },
    "rate_limits": {
      "limit": 50,
      "window_ms": 1000,
      "global_per_second": 50,
      "routes": {
        "POST /channels/:channel_id/messages": {
          "limit": 5,
          "window_ms": 5000
        }
      }
    }
  }
}

• interactions_endpoint_url (not set above, for example http://localhost:3000/api/interactions).
• IDs are optional everywhere; generated ones are snowflakes. References (owners, members, authors, parents, roles in overwrites) take a username, name, or ID
• Permissions take a bitfield (number or string) or a list of names such as SEND_MESSAGES
• bot_token, client_secret, and private_key (an Ed25519 seed as 64 hex characters, from which the public key is derived) are generated when left out; the inspector shows them
• privileged_intents defaults to all three (guild_members, guild_presences, message_content); list fewer to test a 4014 close
• bots installs an application’s bot with a managed role holding permissions. Seeded bots’ roles sit above the other roles, as if an admin dragged them up
• rate_limits.enabled: false stops counting (the headers still show a full bucket)

​

Inspector

​

Limits

• The Gateway speaks JSON only: no ETF encoding and no zlib-stream transport compression (compress in IDENTIFY is ignored). Presence and voice state updates are accepted but not dispatched, and there is no voice
• No webhooks other than interaction webhooks, threads, forum posts, stickers, custom emoji management, scheduled events, audit logs, invites, stage instances, auto moderation, polls, entitlements, or application role connections
• Message components and embeds are checked for Discord’s limits and stored as sent; components v2 layouts are accepted but not validated in depth
• Interactions are created only by the simulate endpoint; application command permissions are not enforced
• Gateway sessions and rate limit counters live in memory and reset on restart

​

Conformance