Voidcom for developers
Applications

Start here

Authentication & applications

What an application is, how the bot token works, rotation, gateway intents, the install link and the fields the portal stores for later.

Applications and bot users

An application is the thing you register on https://developers.voidcom.app: a name, a description, one bot user, one token, a set of gateway intents, an Ed25519 public key and an optional interactions endpoint URL. Every application belongs to the Voidcom account that created it; only that account can see or change it.

The bot user is a normal Voidcom account flagged as a bot. It has its own snowflake id (GET /users/@me), is a member of the servers it was added to, and is what your messages, reactions and slash-command responses are attributed to. Bot users cannot sign in to the developer portal.

The bot token

Authorization: Bot YOUR_VOIDCOM_BOT_TOKEN
  • Send it as the Authorization header on every REST call under https://api.voidcom.app/api/v10, and as token in the gateway IDENTIFY and RESUME payloads.
  • The token is shown once, when the application is created or the token is rotated. The server stores no copy; the portal does not log it.
  • The token carries the application's intents at the time it was minted. Changing intents in the portal applies to tokens minted after the next rotation.
  • Webhooks you create with the token post as your bot user and stop working when the application is deleted.

Rotation

Rotate on the application page mints a new token and increments the application's token version. Every request presenting an older token is refused from that moment on, on every replica — there is no grace period. Rotate immediately if a token was committed, pasted into a chat or otherwise exposed; deploy the new token first if you can afford no downtime, because the old one dies the instant the new one exists.

Gateway intents

Intents use Discord's bit values (GUILDS = 1 << 0, GUILD_MESSAGES = 1 << 9, MESSAGE_CONTENT = 1 << 15, …). The portal shows one toggle per intent. Three are privileged: GUILD_MEMBERS, GUILD_PRESENCES and MESSAGE_CONTENT. They are disabled with "requires approval" until an administrator approves them for your application; v1 grants non-privileged intents only, and there is no self-service approval flow yet.

Two rules that differ from what you may expect:

  • Request in IDENTIFY the intents your application has enabled in the portal, and keep the two identical. The gateway filters events against the intents in IDENTIFY; REST content gating uses the intents carried by the token. A mismatch does not fail anything — you get events or content from one side and not the other.
  • MESSAGE_CONTENT gates content, embeds, components and attachments on server messages, both in gateway events and in GET /channels/{id}/messages. Without it you still receive the message envelope (ids, author, timestamp).

The full mapping from intents to events is the gateway events table.

Installing the bot on a server

There is no OAuth2 authorize URL and no scope=bot flow. Installation is a Voidcom-account action on the developer portal: the application page shows a copyable install link,

https://developers.voidcom.app/install/<application id>

Whoever opens it signs in with their Voidcom account, picks a server they have Manage Server (or Administrator, or ownership) on, and clicks Add. The portal calls the server's AddBotToServer; the bot becomes a member and your gateway session receives GUILD_CREATE. The application owner sees every installed server on the application page and can Remove the bot per server; a server admin can also kick or ban the bot user like any member, which arrives as GUILD_DELETE.

A bot token cannot join a server, create a server or create an invite. DELETE /users/@me/guilds/{id} still leaves.

Stored for later

Two fields on the application page exist so that libraries expecting them have something to read, but nothing uses them in v1:

  • Interactions endpoint URL — stored (https only), not called. Interactions are delivered over the gateway only; see Interactions.
  • Public key (Ed25519, hex) — the key that would sign endpoint deliveries. Shown for completeness; there are no deliveries to verify.

Deleting an application

Delete in the danger zone removes the application and takes its bot user out of every server; its token, webhooks and slash commands stop working at once.