> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formation.texturehq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discord

> Connect an agent's own Discord bot through outbound Gateway sessions.

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](https://discord.com/developers/applications).
   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](https://docs.formation.texturehq.com/runtime/durable-intake.md).
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.