# Bots on Blisscord Blisscord speaks Discord's own API: REST v9 and v10, the gateway, interactions, OAuth2 and voice. A bot written for Discord runs on Blisscord unchanged once its library is pointed at Blisscord's hosts instead of Discord's. You do not rewrite your bot, you reconfigure it. ## Use Discord's documentation Everything about how the API works (objects, endpoints, gateway events, intents, permissions, interactions, rate limits) is documented by Discord, and that is the reference to build against: - [Discord Developer Documentation](https://discord.com/developers/docs/intro) - [Gateway](https://discord.com/developers/docs/events/gateway) - [Interactions and application commands](https://discord.com/developers/docs/interactions/overview) - [OAuth2](https://discord.com/developers/docs/topics/oauth2) - [Rate limits](https://discord.com/developers/docs/topics/rate-limits) These pages only cover what is specific to Blisscord: which hosts to use, how to configure the common libraries, and the handful of places Blisscord behaves differently. ## What you change | | On Discord | On Blisscord | |---|---|---| | REST API | `https://discord.com/api/v10` | `https://discord.community/api/v10` (v9 also served; no version means v9) | | Gateway | from `GET /gateway/bot` | the same call answers `wss://gateway.discord.community` | | CDN (avatars, icons, attachments) | `https://cdn.discordapp.com` | `https://cdn.discord.community` | | OAuth2 authorize page | `https://discord.com/oauth2/authorize` | `https://discord.community/oauth2/authorize` | | OAuth2 token | `https://discord.com/api/oauth2/token` | `https://discord.community/api/oauth2/token` | | Developer portal | `https://discord.com/developers/applications` | [developers.discord.community](https://developers.discord.community) | | Bot token | from Discord's portal | from Blisscord's portal; a Discord token does not work here, and a Blisscord token does not work on Discord | Everything else (paths, JSON shapes, gateway opcodes, intents, permission bits, error codes, rate limit headers) is Discord's. ## Next 1. [Getting started](/docs/bots/getting-started): create the application, get a token, invite the bot. 2. [Configuring your library](/docs/bots/libraries): discord.js, discord.py, JDA, serenity, Eris and Athena, Lavalink, and anything else. 3. [Differences from Discord](/docs/bots/differences): the short list of things that behave differently here. 4. [Keeping your token off Discord](/docs/bots/keeping-tokens-safe): make sure nothing in your bot still calls Discord's hosts. Building a chat surface into your own product rather than a bot? See [chat integrations](/docs/chat). --- # Getting started Create an application on Blisscord, give it a bot, and invite it to a server. This mirrors Discord's own flow; only the portal is different. ## 1. Create the application 1. Sign in at [developers.discord.community](https://developers.discord.community) with your Blisscord account. 2. Create an application. Every application gets its bot account at once, and **the application's id is the bot's user id**, as on Discord. 3. Copy the bot token. It is shown when the application is created and again only when you reset it. Treat it like a password. ## 2. Intents The three privileged intents (presence, server members and message content) are **on by default** for every application. Turn off the ones you do not need on the application's Bot page. A bot that asks for a privileged intent that is switched off is disconnected with close code 4014, exactly as on Discord. See Discord's [gateway intents](https://discord.com/developers/docs/events/gateway#gateway-intents). ## 3. Invite the bot Build the invite link the way you would for Discord, on Blisscord's host: ``` https://discord.community/oauth2/authorize?client_id=YOUR_APPLICATION_ID&scope=bot%20applications.commands&permissions=PERMISSIONS ``` `permissions` is the usual decimal permission integer ([permissions](https://discord.com/developers/docs/topics/permissions)). Installing creates the bot's managed role with those permissions, and the bot receives `GUILD_CREATE` for the server. ## 4. Point your library at Blisscord Follow [Configuring your library](/docs/bots/libraries), start the bot, and it connects. Slash commands register through the usual `PUT /applications/{application_id}/commands` and show up in the client. ## 5. Get listed Verified bots are listed in the client's app directory. Verification is granted by Blisscord staff; ask in the Blisscord Community server. --- # Configuring your library Every library below has been run against Blisscord. Each needs the REST base moved to `https://discord.community`; most then learn the gateway address from `GET /gateway/bot`, which answers `wss://gateway.discord.community`. Where a library does not ask, it is set explicitly below. ## discord.js (v14) ```js const { Client, GatewayIntentBits } = require('discord.js'); const client = new Client({ intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages], rest: { api: 'https://discord.community/api', cdn: 'https://cdn.discord.community', }, }); client.login(process.env.TOKEN); ``` The gateway URL comes from `GET /gateway/bot`, so nothing else is needed. For `@discordjs/rest` on its own (for example a command deploy script), pass the same option: `new REST({ api: 'https://discord.community/api' })`. Verified with 14.27. ## discord.py (2.x) ```py import discord import yarl discord.http.Route.BASE = "https://discord.community/api/v10" discord.gateway.DiscordWebSocket.DEFAULT_GATEWAY = yarl.URL("wss://gateway.discord.community/") discord.asset.Asset.BASE = "https://cdn.discord.community" client = discord.Client(intents=discord.Intents.default()) client.run(TOKEN) ``` Set these before the client is created. An unsharded discord.py client dials `DEFAULT_GATEWAY` rather than asking `/gateway/bot`, so the second line is required. Verified with 2.7.1. ## JDA (5 and 6) ```java JDA jda = JDABuilder.createDefault(token) .setRestConfig(new RestConfig().setBaseUrl("https://discord.community/api/v10/")) .setSessionController(new SessionControllerAdapter() { @Override public String getGateway() { return "wss://gateway.discord.community/"; } }) .build(); ``` `setBaseUrl` moves REST only. JDA's gateway address comes from `SessionController.getGateway()`, which is hard-coded to Discord's gateway, so the override is required: without it JDA sends your token to Discord's gateway. JDA builds CDN links on `cdn.discordapp.com` itself. Verified with 6.7.0. ## serenity (0.12) ```rust let http = HttpBuilder::new(&token) .proxy("https://discord.community") .ratelimiter_disabled(true) .build(); let mut client = ClientBuilder::new_with_http(http, intents) .event_handler(Handler) .await?; ``` serenity ignores `proxy` while its client-side rate limiter is on (the limiter builds its requests without it, and `GET /gateway` went to Discord), so it has to be disabled; your bot then receives a 429 instead of being slowed down, so keep request volume modest or retry on 429. Verified with 0.12.5. ## Eris and Athena ```js const client = new Eris.Client(`Bot ${token}`, { intents: ['guilds', 'guildMessages'], rest: { domain: 'discord.community', https: true }, }); ``` `rest.domain` is a bare host name, not a URL. The gateway URL comes from `GET /gateway/bot`. Athena (Team Hydra's Eris fork) takes the same option; verified with Athena 4.6 and with Zira and HepBoat in production configuration. ## Lavalink and other voice clients Nothing to configure. A voice client connects to whatever endpoint `VOICE_SERVER_UPDATE` names, which is Blisscord's voice server. Verified with Lavalink 4.2.2 (Zira Music). See the voice notes in [Differences from Discord](/docs/bots/differences). ## HTTP interactions An application can receive interactions as signed HTTP POSTs to an Interactions Endpoint URL, set on the application's page in the portal, exactly as on Discord. Requests are signed with the application's Ed25519 key, shown in the portal as the public key, so `discord-interactions` and similar verifiers work unchanged. The URL must answer the verification PING before it is saved. ## Anything else For any other library or raw HTTP and WebSocket code, change three things: 1. The REST base: `https://discord.com/api` becomes `https://discord.community/api` (keep the version segment you use). 2. The gateway: use the `url` from `GET /gateway/bot`, or `wss://gateway.discord.community` if the library hard-codes one. JSON and ETF encodings, and `zlib-stream` and `zstd-stream` compression, are supported. 3. The CDN: `https://cdn.discordapp.com` becomes `https://cdn.discord.community`. Then read [Keeping your token off Discord](/docs/bots/keeping-tokens-safe): libraries often call Discord's hosts from somewhere you did not configure. --- # Differences from Discord Blisscord aims to behave exactly like Discord. These are the places it does not, or where something about this instance is worth knowing. ## Applications and ids - **An application's id is its bot's user id**, as on Discord. Applications created before 2026-10-03 were renumbered to match; their former ids still work everywhere an application id is accepted (invite links, OAuth2 `client_id`, API paths), so nothing you saved breaks. - **There are no real payments.** The monetization endpoints exist (SKUs, entitlements, test entitlements, consume), but no money can change hands on this instance, so treat paid features as test-only. ## The Blisscord Community server Every account on Blisscord, bots included, is a member of the Blisscord Community server. Your bot joins it automatically when it is created and cannot leave it. There it holds **no permissions until staff give it a role**: it cannot read or send messages, and its commands are not offered to members. Do not treat that server as one that invited you; ignore it unless staff ask you to activate your bot there. ## Gateway - **Restarts are resumable.** When Blisscord restarts it sends op 7 Reconnect, closes with 4000, and keeps every session resumable through the restart, so a library that resumes (all the common ones do) carries on with the missed events replayed. - **Sharding works as on Discord.** `GET /gateway/bot` recommends a shard count and reports `session_start_limit` with `max_concurrency` 1. ## Voice - **One region.** Every voice channel is served from the region `hydra`. - **No end-to-end encryption (DAVE).** The voice server offers transport encryption `aead_aes256_gcm_rtpsize` only and answers `dave_protocol_version: 0`, which voice libraries accept and fall back from. - **Voice does not survive a Blisscord restart.** Text sessions resume; a voice connection drops and the bot has to rejoin the channel. ## OAuth2 - The authorize page is `https://discord.community/oauth2/authorize` and the token endpoint `https://discord.community/api/oauth2/token`. Scopes, grants and token shapes are Discord's. - PKCE parameters (`code_challenge`, `code_verifier`) are accepted but not yet verified. ## Links and media - Message links that the official client opens are `https://app.discord.community/channels/...` in a browser; the desktop client handles `discord.com/channels/...` links itself. - Images are served from `https://cdn.discord.community`. A bot that builds CDN URLs on `cdn.discordapp.com` (some libraries do, regardless of configuration) produces links that point at Discord and do not load. Build them from the CDN host above where you can. ## Rate limits Buckets, headers and 429 bodies follow Discord's [rate limit](https://discord.com/developers/docs/topics/rate-limits) documentation, with the same default limits. --- # Keeping your token off Discord A Blisscord bot token is useless on Discord, but sending it there still hands a working credential for your bot to a third party. Libraries and bot code often call Discord's hosts from places your configuration does not reach, so check before you run. ## Where Discord's hosts hide Search your bot and its dependencies for these, and point each at Blisscord or remove it: - `discord.com`, `discordapp.com` (REST, OAuth2, invite and message links) - `gateway.discord.gg` (a hard-coded gateway) - `cdn.discordapp.com`, `media.discordapp.net` (images) - `discord.gg` (invite links) Known cases in libraries, all covered in [Configuring your library](/docs/bots/libraries): - **JDA** dials Discord's gateway unless its `SessionController` says otherwise. - **serenity** sends some requests to Discord while its rate limiter is enabled. - **discord.py** dials its built-in gateway constant when unsharded. Your own code may do the same: an emoji sync, a dashboard login that uses a stock "Discord" OAuth provider, a deploy script with its own base URL. ## When you cannot change the code If a dependency has Discord's hosts hard-coded and you cannot or do not want to change it, intercept them at the network level instead. This is how the team runs Zira and HepBoat on Blisscord unmodified: 1. Run a small reverse proxy (nginx works) next to the bot that answers for `discord.com`, `discordapp.com`, `gateway.discord.gg` and `cdn.discordapp.com`, and forwards to `discord.community`, `gateway.discord.community` and `cdn.discord.community`. 2. Give it a certificate for those names, signed by a private certificate authority you create. 3. Make the bot resolve those names to the proxy (for Docker, `extra_hosts`) and trust your authority (for Node.js, `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`; other runtimes have their own trust store setting). Nothing then leaves for Discord, whatever the code does. ## If a token did reach Discord Reset it on the application's Bot page in the [developer portal](https://developers.discord.community). The old token stops working at once.