Skip to main content
Formation receives Discord direct messages, server-channel messages and messages in accessible threads through the authenticated Gateway, and replies as the agent’s dedicated bot. Each agent needs a separate Discord application and bot; never share a bot token between agents or supply a personal user token.

Set up the connection

  1. Create an application in the Discord Developer Portal. Copy its Application ID and create or reset its Bot token on the Bot page.
  2. Enable Message Content Intent on the Bot page. Formation requests guild, guild-message, direct-message and message-content intents, not member or presence intents. Obtain Discord approval if your application’s size requires approval for privileged intents.
  3. Choose Add connection → Discord on the agent’s Connections page. Enter the application ID and bot token in the setup form, not in conversation. Saving verifies that the token authenticates that application’s bot and stores it encrypted for this agent.
  4. Open the installation link shown after saving and choose a test server. Grant View Channels, Send Messages, Send Messages in Threads, Read Message History and Add Reactions only where the bot should work. Channel overrides and private-thread membership still apply; administrator permission is not required.
  5. Keep Formation running continuously with outbound HTTPS and WebSocket access to Discord. No interactions endpoint or inbound Discord webhook is needed. The connection uses the same durable intake and Temporal execution pipeline as other connectors; see durable intake.
  6. Send a DM, mention the bot in a server channel, and mention it in an accessible thread. Confirm the reply stays in that destination and the connection page reports both a received message and a provider-confirmed reply. Other visible channel messages supply context, not automatic permission to answer.

Behavior and privacy

  • Mentions and provider-resolved replies to this bot count as addressing it. Discord threads are separate channel destinations; ordinary reply references retain their parent message identity.
  • Replies suppress user, role and everyone pings, including automatic reply pings. Long replies are split within Discord’s UTF-16 message limit, retaining code fences. Existing bot replies can be edited through the connector’s edit contract.
  • Incoming attachments retain their metadata. Downloads are restricted to Discord attachment CDN hosts, reject redirects, carry no bot authorization header and are limited to 8 MiB. Signed links can expire; ask for a fresh upload then.
  • Lifecycle reactions show work in progress, failure, or the completed turn’s topic. A completed turn is not necessarily a successfully completed task.
  • DM readership is revalidated against the single recipient. Server-channel and thread readership remains unknown: guild membership does not prove who can read a channel. Formation does not use guessed membership to authorize private memory disclosure.

Recovery and troubleshooting

Only one runtime replica owns a bot route’s Gateway lease at a time. Resume checkpoints survive worker handoff and contain protocol metadata, not message bodies or bot tokens. Message intake must be durable before its sequence advances. A crash can replay a deduplicated event. Discord can expire a session; messages missed outside its replay window are not backfilled from channel history. Heartbeat acknowledgements are read independently of slow durable intake. Dispatches remain ordered; excess backlog disconnects and attempts Resume from the last durably accepted sequence. Adjacent sequence-only dispatches and full channel-cache resets share a checkpoint during bursts. Messages, READY and channel-specific updates remain ordered barriers; batching does not skip durable message acceptance.
  • No messages: check Message Content Intent, server installation, channel overrides, thread access, and whether Discord permits the user to DM the bot.
  • Invalid token: reset the bot token and save the replacement in this agent’s connection. Rejected outbound authentication waits for a credential revision change instead of repeatedly sending with the same rejected token.
  • Gateway stopped: inspect runtime logs for credential, intent, shard or provider-wait errors. Permanent failures stop that worker; after correcting Discord settings, restart the runtime or save replacement credentials.
  • Rate limits: reconnects honor usable provider retry hints. An unrepresentable positive wait stops for operator review rather than retrying too early.
  • Uncertain reply: a network failure, HTTP 408 or server error is not proof that Discord rejected the message. Formation retains uncertainty rather than blindly resending and risking duplicates.

Current limits and acceptance checklist

This connector is not yet full Slack feature parity. It supports text messages, existing Discord threads, incoming attachments and lifecycle reactions, but does not implement slash commands/interactions, voice, group DMs, outbound file uploads, automatic thread creation, historical backfill, or ingestion of message edits and deletions. Applications requiring multiple Gateway shards are rejected. Live Discord acceptance has not yet been performed for this implementation. Before production use, validate with a dedicated test bot and two distinct users:
  1. Confirm distinct attribution in a channel and private DM replies with no cross-user memory disclosure.
  2. Test a mention, a reply to the bot, a thread, a long Unicode/code reply and an attachment; check that outbound text does not trigger unsolicited pings.
  3. Restart the owning replica during traffic and confirm Resume and deduplication; remove channel access and confirm later accessible messages still work.
  4. Rotate the bot credential and confirm the old connection stops and pending rejected replies recover without replaying already confirmed parts.
Automated local protocol and database tests cover these safety boundaries, but are not a substitute for testing Discord permissions and delivery in your server.