Discord bot integration

Control Chord through a bot DM, a server text channel, or an existing public/private thread. Discord connects over an outbound Gateway WebSocket, so you do not need a public endpoint. Server and thread messages must explicitly mention the bot and come from the paired owner. Group DMs, voice channels, and posting to forum roots are outside this release.

Deployment checks with a real Discord account remain pending. Automated protocol tests alone do not establish readiness for unattended deployment.

Create and install the bot

Create an application in the Discord Developer Portal, add a bot, and copy its bot token (Bot page, shown once) and application ID (General Information page, same as client ID).
Open OAuth2 -> URL Generator (newer portal: Installation -> Install Link). Select the bot scope, then tick View Channel, Send Messages, and Send Messages in Threads. The page generates an install link with the combined value embedded, for example:
```
https://discord.com/oauth2/authorize?client_id=YOUR_APPLICATION_ID&permissions=274877910016&scope=bot
```
There is no save button here: the permissions= number lives inside that URL and is applied when the link is opened. To change permissions, re-tick and open the regenerated link again.
Open the generated link in a browser, select the server (you need Manage Server there), and click Authorize. The bot then appears in the server member list.
In the server, verify channel permission overrides for the bot role, and invite the bot to each private thread you intend to use. In your Discord privacy settings, allow DMs from the bot’s shared server, otherwise the pairing DM cannot be delivered.
Keep Message Content, Server Members, and Presence privileged intents disabled (Bot page, the only place with a Save Changes button for intents). Gateway uses GUILDS, GUILD_MESSAGES, and DIRECT_MESSAGES; DM text and explicit bot mentions are sufficient for this release. See Discord Gateway intents.

The gateway does not read message history. You do not need Read Message History, Administrator, or Manage Threads.

Save this configuration; both credential fields are required:

ims:
  discord:
    bot_token: your-bot-token
    application_id: "123456789012345678"

Treat the token as a secret. The application ID identifies the application; pairing records the authenticated bot user ID separately as owner.account_id. A different bot account requires a local reset rather than inheriting existing authorization.

When direct access to Discord is blocked, set proxy_url globally or under ims.discord. Both socks5:// and socks5h:// are accepted: the Gateway WebSocket normalizes socks5h to socks5 automatically (identical remote-DNS behavior), so a socks5h URL never has to be rewritten by hand. See configuration.

Pair and bind chats

Run chord-gateway -f config.yaml --pair in a foreground terminal. Allow DMs from the bot’s shared server in your Discord privacy settings, open the bot DM, and send:

/bind "/path/to/project" <pairing_code>

The directory must already exist on the gateway host. First pairing must happen in the Bot DM; server messages stay silent until an owner is paired, so starting with @Bot /bind in a channel gets no reply. After private pairing, the same owner can bind each server text channel or accessible thread separately:

@Bot /bind "/path/to/project"
@Bot /status
@Bot Explain the project structure

Select the actual bot mention in Discord. In DMs, send commands directly without a mention. In channels and threads, put the bot mention at the start when invoking commands such as /allow, /deny, /answer, or /cancel. Mentioning the bot later in the body submits ordinary task text; an embedded /bind is not promoted into a command. Other users, bots, webhooks, edits, and deletion events cannot start tasks.

Each thread has its own binding and session; it does not inherit its parent’s route. Existing forum-post threads are usable when accessible, but the gateway does not create threads or forum posts. Replies are visible to channel/thread members, so bind trusted spaces. See pairing and local reset.

Output and connection behavior

Replies use escaped text and split long output into segments of at most 1900 UTF-16 code units. Markdown, code fences, embeds, attachments, interactive components, and native slash commands are not provided in this release. Output mentions cannot notify users, roles, or everyone, and link embeds are suppressed.

Sending a result to an unlocked archived thread may automatically reactivate it. Locked, deleted, or inaccessible threads report failure; results are never redirected to the parent channel. See Discord’s thread rules.

Connection loss marks the platform unavailable while reconnecting. Already accepted inputs use the shared in-memory ingress and message-ID deduplication; Gateway Resume alone is not a cross-restart delivery guarantee. API rate-limit waits can be cancelled. Network timeouts and server errors leave send outcomes unconfirmed and are not automatically resent.

During Resume, candidate message events arriving before RESUMED retain their original text and command target, then enter the common ingress after the same session is ready. The temporary replay buffer holds at most 1024 useful events. Overflow stops the connection with replay_capacity_exceeded instead of silently skipping messages or continuing automatic reconnects. Inspect the original Chord session and current intake state on the host before restarting; do not blindly resend earlier messages. Process restart clears both the replay buffer and intake queue.

Official references

Rate limits — every bot may make up to 50 requests per second globally, on top of per-route buckets identified by X-RateLimit-Bucket. Discord explicitly asks apps not to hard-code limits, but to read X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset-After and the 429 Retry-After header. Repeated invalid requests (401/403/429) can additionally trip an IP-level limit of 10,000 per 10 minutes.
Gateway intents — intent reference behind step 5.
Threads — archive, lock and unarchive behavior referenced in the output section.

Troubleshooting and deployment checks

Symptom	Check
Bot DM cannot be opened or delivered	Allow DMs for the shared server and check Discord privacy settings.
Bot stays offline and nothing (DM or channel) gets a reply	The Gateway WebSocket never reached `Ready`, so no input is received at all. Check `proxy_url` (both `socks5://` and `socks5h://` work; the latter is normalized automatically), then the bot token / application ID pairing, then privileged intents.
A server message is ignored	Send from the paired owner and explicitly mention this bot; commands need the leading mention. Bind the channel/thread first. The first pairing must happen in a Bot DM: server messages stay silent until an owner is paired.
A reply to one of the bot’s messages is ignored	A guild reply counts only when it pings this bot: Discord adds that mention while the replier’s “ping on reply” setting is on, and the mention alone is still not enough because the Message Content intent is not requested, so the reply must also carry text. A dropped mention is reported at most once per minute in the log as `discord event=message_dropped category=contentless`.
`401` or authentication failure	Rotate an invalid bot token locally and ensure the application ID belongs to this bot.
`403` or missing access	Check channel overrides, View Channel, Send Messages, Send Messages in Threads, and private-thread access.
Gateway close `4014`	Confirm the deployed binary requests only the documented intents; do not enable privileged intents to work around a mismatch.
Archived thread becomes active	Expected when sending to an unlocked archived thread.
Locked thread cannot receive results	Ask a Discord administrator to unlock it; the gateway never requests Manage Threads or redirects replies.
`sharding_not_supported`	This release supports one shard only; choose a bot deployment that does not require multiple shards.
`replay_capacity_exceeded`	More than 1024 useful events arrived before Resume completed. The connection stops; inspect the original Chord session, its input queue, and local ingress records before restarting. Do not blindly replay earlier commands or tasks.

Before relying on a deployment, verify private pairing, channel binding, separate public/private thread binding, /status, /allow, /answer, /cancel, a task lasting more than 15 minutes, a background result in an unlocked archived thread, and a clear failure in a locked thread. Automated protocol tests do not replace this real-account check.

Stop the service before resetting: chord-gateway pairing reset --platform discord -f config.yaml. Reset removes Discord’s owner, bindings, and automatic pins while retaining credentials, workspaces, and other platforms. Restart with --pair; see operations for delivery and restart semantics.

Each WebSocket message is limited to 16 MiB to accommodate large READY payloads while bounding resource use. Exceeding it reports an error and interrupts the connection. This is a client budget, not a platform sending limit.