Gateway adapters
An adapter maps one chat platform onto the Gateway port. This page holds the rules that every adapter keeps, and compares the platforms. Each implemented platform has its own page:
| Platform | Page | Code |
|---|---|---|
fake |
None. A test double, described in its module. | crates/fleet-gateway/src/fake.rs |
slack |
Slack adapter | crates/fleet-gateway/src/slack.rs |
discord |
Discord adapter | crates/fleet-gateway/src/discord.rs |
fleet version lists the platforms of a build: discord, fake and
slack. Telegram and Microsoft Teams are mapped on paper only, under the
cross-platform check.
An adapter's post carries ConversationController's refusals and busy
notices, GatewayController's posts for a tied Task, and its top-level log
posts in the gateway.logs channel. An adapter's open carries a Question
that opens a thread. An adapter's react adds and removes Fleet's queued,
working and replied reactions on a person's message. An adapter's link names a
thread in a log post. The Gateway controller lists what is
built.
Common rules #
Every adapter that reaches a real platform keeps these rules:
- One bounded
curlper call. Each call is onecurlprocess throughfleet-exec. Pastgateway.callTimeoutMs,fleet-execkills the whole process tree. One operation makes at most 10 calls. The port'soperation_boundis 10 worst-case calls. - Fleet holds no credential. The token lives in a curl config file that
the operator owns. The account names the file with
curlConfig. Fleet passes it with--configand never reads it. Fleet never constructs an Authorization header. - No text on a command line. A request body goes to
curlon stdin. - Event reading is pure.
eventmakes no call. So the receive verb runs it without the lease. - A long text is split. The adapter splits a text into consecutive posts
under derived keys that name the part and the count:
<key>/1/3,<key>/2/3,<key>/3/3. A split closes a code fence that it cuts, and opens it again in the next post. A text that needs more than 10 posts is a Known failure. A split that landed partly is Unknown. - Fleet's own posts are told by the bot id. A message whose author is the
account's
botisfleet. A Fleet post never mentions Fleet. - A refusal is Known; anything unclear is Unknown. A write that the
platform refused is
Failed. A write whose outcome Fleet cannot read is Unknown, and Fleet never takes it as absent. - A history read is complete or Unknown. A read pages under the budget of
calls. When the budget runs out, the answer is Unknown (
Incomplete), never a partial list. - A reaction is set, not counted. Adding a reaction that is there, or
removing one that is not, is a Known success. A refused reaction is
Failed; one whose outcome Fleet cannot read is Unknown. - A throttled read is Unknown with
retryAfter. HTTP 429 carries the platform's wait time where it gives one. A throttled write is per platform: see each platform's page.
Capabilities #
capabilities reports what the platform offers on an account. The
controllers decide on these values, never on the platform's name.
| Capability | fake |
slack |
discord |
|---|---|---|---|
history |
Set by the test | true |
true |
marker |
Set by the test | metadata |
nonce { windowMs: 60000 } |
unmentioned |
Set by the test | true |
messageContent and the application's message content flag |
threads |
Set by the test | true |
true |
reactions |
Set by the test, true by default |
true |
true |
| Reaction names | Recorded as given | Slack's emoji names, colons stripped | A name Fleet maps to Unicode (eyes, white_check_mark, hourglass_flowing_sand and a few more), a Unicode emoji as it is, or a custom emoji as name:id |
react |
One call, recorded | reactions.add or reactions.remove |
PUT or DELETE of the bot's own reaction |
| Recovery of an Unknown post | As the marker | One since read finds the key |
Resend under the same nonce inside the window |
inbound |
connection |
socket-mode or events-api |
discord-gateway |
| Text | The port's text | A markdown block, with a mrkdwn fallback |
Markdown, unchanged |
| Post limit | Set by the test | 4,000 characters | 2,000 characters |
| Open a thread | One call | One chat.postMessage |
A post, then Start Thread from Message |
Message key |
Read back with a metadata marker |
Message metadata | None |
When unmentioned is false, a tied thread relays only mentions. Its
Conversation raises NeedsAttention/MentionsOnly.
The marker decides how Fleet settles a post whose outcome is Unknown:
metadata: Fleet looks for the key in the mirror, then in onesinceread.nonce { windowMs }: Fleet looks for the key in the mirror. Then it resends the post under the same key while both conditions hold:- the time is before the first intent's
atpluswindowMs, - fewer than three attempts were made.
- the time is before the first intent's
none, or a nonce window that closed: Fleet raisesNeedsAttention/PostUnconfirmedand waits for a person.
Address format #
An address is <platform>:<chat>[:<thread>]. Only the adapter reads its parts.
| Platform | Thread | Channel | Parts |
|---|---|---|---|
fake |
fake:<chat>:<thread> |
fake:<chat> |
Any text. |
slack |
slack:C0123ABCD:1730000000.000100 |
slack:C0123ABCD |
A channel id (C, G or D, then uppercase letters and digits) and the parent's ts. |
discord |
discord:1300000000000000000:1300000000000000001 |
discord:1300000000000000000 |
The parent channel's snowflake and the thread's snowflake. A thread started from a message has that message's id. |
A route covers channels by their <chat> part. A thread belongs to the
route of its channel. A wildcard route covers every conversation that the
account's listener delivers in a channel no other route lists:
| Platform | A wildcard route covers |
|---|---|
fake |
Every chat. |
slack |
Every public and private channel the bot is a member of, with the message events the setup subscribes to. A group DM only when the operator also subscribes the app to message.mpim. A one-to-one DM only when the app subscribes to message.im and the account has no DM route. |
discord |
Every text and announcement channel the bot can view in the account's guild, and their public threads. Never a DM, a private thread or a forum channel: the adapter ignores them. |
A DM route, with "dm:*" in channels, covers every one-to-one DM that the
adapter marks direct and that no route lists:
| Platform | A delivery is direct when |
|---|---|
fake |
The payload holds "direct": true. |
slack |
The message event's channel_type is im. A group DM is mpim, and is not direct. |
discord |
Never. The adapter ignores every DM, so a Discord account refuses "dm:*". |
A thread address names a conversation. A channel address names where Fleet
opens a new thread, or where it posts a top-level log post. A post to a
channel address makes every part of its text a top-level post there and
starts no thread. The Slack and Discord adapters refuse a thread address in
open.
Cross-platform check #
Telegram and Microsoft Teams are mapped on paper only. The purpose is to check the port against platforms that differ. Each platform claim cites the platform's own documentation, read on 2026-10-26. A claim that those pages do not state is marked unverified.
| Slack | Telegram | Discord | Microsoft Teams | |
|---|---|---|---|---|
| Status | Implemented | On paper | Implemented | On paper |
| Conversation | A thread: channel and parent ts (slack-threads) |
A forum topic: chat and message_thread_id. Topics exist in supergroups, and in private chats with topics enabled (tg-message, tg-topics). Otherwise the conversation is the whole chat. reply_to_message is one level deep (tg-message), so reply chains are not threads. |
A thread, which is a channel with a parent_id (dc-threads). A thread started from a message has that message's id (dc-start). |
A channel reply chain: conversation.id ends with ;messageid=<root> (ms-channel). Group chats are not threaded (ms-concepts). |
| Mention | <@U…> in text (slack-format) |
mention and text_mention entities (tg-entity). With privacy mode on, the documented deliveries are commands, replies to the bot and messages via the bot. A bare mention is not listed (unverified) (tg-privacy). |
mentions array, <@id> (dc-message, dc-format) |
A mention entity whose mentioned.id is the bot (ms-rsc) |
| Unmentioned messages | Delivered with the history scopes (slack-message) | Only with privacy mode off, or with the bot an admin (tg-privacy) | Content only with the privileged MESSAGE_CONTENT intent. Mentions and DMs carry content without it (dc-intent). |
Only with the RSC permission ChannelMessage.Read.Group. By default, only mentions (ms-channel, ms-rsc). |
| Transport | Socket Mode or HTTPS events (slack-socket, slack-events) | getUpdates long poll: a higher offset confirms an update, and updates are kept 24 hours. Or a webhook, which excludes polling (tg-updates). |
The Gateway WebSocket. Resume replays lost events; an expired session does not (dc-gateway). HTTP webhook events carry no channel messages (dc-webhooks). | HTTPS POST to one messaging endpoint, JWT-signed. A retry comes after 15 seconds, so duplicates can occur (ms-auth, ms-concepts). |
| History | conversations.replies (slack-replies) |
No method for bots. None was found (unverified by absence). | GET /channels/{id}/messages with after, 100 per page (dc-messages) |
Microsoft Graph …/messages/{id}/replies, under ChannelMessage.Read.Group or .All (ms-graph) |
| Own posts | Bot id and message metadata (slack-metadata) | from.id equals getMe's id (tg-user). sendMessage has no metadata field (tg-send). |
author.id. A nonce with enforce_nonce returns the existing message for a repeat "in the past few minutes" (dc-create). |
28:<appId>; Graph from.application (ms-graph-from). No idempotency key is documented (unverified). |
| Allowlist identity | User id, per workspace, or global in Enterprise (slack-user, slack-ent) | Numeric User.id (tg-user) |
User snowflake. Usernames change (dc-user). | aadObjectId, unique to the user. The 29: id is per bot (ms-proactive). |
| Open a thread | One chat.postMessage |
createForumTopic, then sendMessage (tg-forum) |
A message, then Start Thread from Message (dc-start) | Create a conversation in the channel. The app must be installed, and the call needs the serviceUrl of an earlier inbound activity (ms-proactive). |
| Limits | 4,000 recommended, 40,000 truncated (slack-post) | 4,096 characters. One message a second per chat, 20 a minute per group (tg-send, tg-limits). | 2,000 characters (dc-create) | About 100 KB; aim for 80 KB (ms-format). 7 sends a second per conversation (ms-rate). |
| Breaks the model | Nothing. Events may be lost while disconnected. | No history and no marker, so an Unknown send can never be recovered. Mid-chat mentions see only what Fleet received. Bot-to-bot messages arrive when opted in (tg-b2b). | Opening is two calls. Recovery depends on a short nonce window. | Unmentioned replies never arrive without RSC. No marker. The Bot Framework SDK is archived in favour of the Teams SDK, which keeps the HTTPS endpoint (ms-sdk, ms-teams-sdk). |
What the platforms changed #
The interface and the resource already hold each correction:
- A thread is optional.
- Telegram chats without topics, direct messages and Teams group chats have no threads.
- The address is
platform:chat[:thread]. A chat with no threads is one conversation. - A route over such a chat ties the whole chat to one Task.
- "Every message is a turn" depends on delivery.
- Slack delivers every message in a channel that the bot is in.
- Telegram, Discord and Teams deliver unmentioned messages only under a platform permission.
- The adapter's
capabilitiesreports whether unmentioned messages reach Fleet on an account. - Without them, a tied thread relays only mentions. Its Conversation
raises
NeedsAttention/MentionsOnlyrather than pretending.
- Recognising Fleet's posts is a capability, not a given.
- Slack has a metadata marker. Discord has a nonce window. Telegram and Teams have nothing.
capabilitiesreportsmarkerasmetadata, asnoncewith its window, or asnone.- With
none, an Unknown post outcome raisesNeedsAttention/PostUnconfirmedand is never repeated. The conversation's later posts wait for a person.
- History is a capability.
- Slack, Discord and Teams (under a separate Graph permission) can read a thread. Telegram cannot.
- With no history, a mention partway through a chat carries only what the receive verb spooled. The join message says so.
- The backstop poll exists only where history does.
- Opening a thread is not one call everywhere.
- On Discord and Telegram, opening takes two calls. The adapter keys both steps from the one intent key.
- On Discord, the thread's id is the starter message's id. So a repeated second step finds the thread already there.
- Identity is an opaque id in a scope.
- No allowlist entry is a display name, a username or an email.
- Reason: Discord and Telegram usernames change, and Teams' per-bot ids are not the person's.
[gateway.people]maps a person's name to one id per account.
- Fleet's own bot is not the only bot.
- Telegram now delivers other bots' messages when a bot opts in (tg-b2b).
- Every adapter filters on Fleet's own id from
whoami. - Other bots are
botauthors. Admission ignores them unless a route lists them.
Adding a platform #
A new platform adds one section to this page, ## <Platform> adapter. The
section has these H3 headings, in this order, and no other H3:
### Setup: what the operator does on the platform, and what the listener does.### Configuration: the[gateway.accounts.<name>]keys, and their errors.### Address format: the thread and channel addresses, and how an event maps to one.### Capabilities: thecapabilitiesvalues, and how each port verb maps onto the platform's API.### Limits: the platform's limits, and every claim that its documentation does not state.### Troubleshooting: each symptom, its cause and its fix.
The same change also does these things:
- It adds a column to capabilities.
- It adds a row to address format.
- It moves the platform's column in the cross-platform check from "On paper" to "Implemented".
- It adds the platform to the account row in the native config.
Slack adapter #
The Slack adapter maps one Slack workspace onto the
Gateway port. Its code is
crates/fleet-gateway/src/slack.rs. It keeps the
common rules of every adapter.
Every Slack claim cites Slack's own documentation, read on 2026-10-26. The DM claims were read on 2026-11-04. A claim that those pages do not state is marked unverified.
Setup #
On the Slack side, the operator does these steps:
- Create an app for the one workspace. Keep it an internal app. Reason: since 2025-05-29, some commercially distributed apps get Tier 1 history limits on new installs. Internal customer-built apps are not affected (slack-limits2025).
- Give the bot user the history scopes
channels:historyandgroups:history(slack-message), andmessage_metadata:read. History reads need the last scope to return Fleet's marker (slack-metadata). Addreactions:write, so Fleet can mark a person's message queued, working and replied (slack-react-add, slack-react-remove). Without it, every reaction fails, and relays and posts go on. - Subscribe the app to the
message.channelsandmessage.groupsevents (slack-message). - Choose the listener's transport, and set
inboundto match:socket-mode: the listener holds an app-level token withconnections:write.apps.connections.opengives it a temporarywss://URL (slack-socket).events-api: the listener serves a public HTTPS endpoint, and verifies each request's signature (slack-events).
- Put the bot token in a curl config file that the operator owns, as an
Authorization header. Name the file in
curlConfig. - Invite the bot to every channel that a route lists. Message events and history reach the bot only in a channel where it is a member. On an account with a wildcard route, membership is the allowlist of channels: the wildcard covers every channel the bot is in.
- For one-to-one DMs, also do the steps under The DM route.
The listener is a program outside Fleet. It does these things:
- It reads its account from
fleet gateway account NAME --json. - It holds the Socket Mode connection, or serves the Events API endpoint.
- It runs
fleet gateway receive --account NAMEonce for each envelope, with the raw Socket Mode envelope or Events API body as the payload. - It acknowledges the envelope by its
envelope_idonly after the verb exits 0. The acknowledgement is due within three seconds, per Slack's Java SDK guide (slack-java). - It beats with
--beaton every state change, and at least everygateway.beatMs.
Configuration #
[gateway.accounts.slack-main]
platform = "slack"
team = "T0123ABCD" # the team id, or the enterprise id in an Enterprise org
bot = "U0BOT0001" # Fleet's bot user id, checked against auth.test
inbound = "socket-mode" # or "events-api"
cli = "curl"
curlConfig = "/etc/fleet/slack-curl.conf" # operator-owned; holds the bot token header
| Key | Required/default | Meaning |
|---|---|---|
platform |
Required | slack. |
team |
Optional | The team_id, or the enterprise_id in an Enterprise org. Slack advises keying stored data on the enterprise_id (slack-ent). When it is set, whoami checks it, and events of another workspace are ignored. |
bot |
Required | Fleet's bot user id. whoami compares it with the user_id of auth.test. |
inbound |
Required | socket-mode, an authenticated connection, or events-api, a signed HTTPS delivery. |
cli |
curl |
The client executable, a path or a name on PATH. |
curlConfig |
Required | An absolute path. Fleet passes it to curl --config and never reads it. |
A Slack account refuses messageContent. The manager refuses an account that
breaks these rules, with one of these errors:
inbound "X" is not how a Slack listener delivers; use "socket-mode" or "events-api"a slack account needs a curlConfigmessageContent is a Discord account's key, not "slack"'s
The wildcard route #
A wildcard route, channels = ["*"], covers these Slack conversations:
- Every public channel (
message.channels) and private channel (message.groups) where the bot is a member, apart from a channel id that another route lists and thegateway.logschannel. - A group DM, only when the app also subscribes to
message.mpim. A request there needs a mention, as in a channel. - A one-to-one DM, only when the app also subscribes to
message.imand the account has no DM route. A request there needs a mention.
The setup above subscribes to neither, so by default the wildcard covers no DM. A subscription is the operator's choice of which conversations reach Fleet.
Recommendation: to take requests in one-to-one DMs, add a DM route. Do not rely on the wildcard there. Reason: under the wildcard, a DM request must mention the bot, which people rarely do.
The DM route #
A DM route has "dm:*" in channels. It covers every one-to-one DM
between the bot and a user of the workspace, apart from a channel id that a
route lists. In such a DM:
- A top-level message from a person on
allowstarts a Task. It needs no mention. - A reply in a tied DM thread is a turn for that thread's Task. A new top-level message is a new thread, and it starts a new Task. To continue a Task, a person replies in its thread.
- A top-level message from anyone else earns the route's refusal, once per thread. It never becomes an instruction.
The adapter marks a delivery direct when the message event's
channel_type is im. Slack documents channel_type as the way to tell a
DM from other message events (slack-message-im). A group DM has
channel_type mpim (slack-message-mpim), so it is not direct. The
adapter does not read the channel id prefix. Reason: the documented group
DM example has a G… id, the prefix of a private channel too.
message_changed and message_deleted events may lack channel_type:
Slack's example shows none (unverified in general). The receive verb
still routes such an edit to its DM thread from the Conversation's
spec.direct.
To take DMs on an account, the operator makes these Slack app changes:
- Add the bot scope
im:history. It reads DM history, including throughconversations.replies(slack-message-im, slack-replies). - Subscribe the app to the
message.imevent (slack-message-im). - In App Home, switch on the Messages Tab (slack-app-home). Slack's
App Home page names
chat:writeandim:historyfor it. A checkbox that lets users send messages from that tab may also need to be on (unverified: the page does not name it). - Reinstall the app to the workspace, so that the new scope applies.
- In the Fleet config, add
"dm:*"to the route'schannels. Keep every person who may DM the bot under that route'sallow.
Group DMs need message.mpim and mpim:history (slack-message-mpim). They
are optional, and the wildcard covers them under the mention rule.
Address format #
A Slack conversation is a thread. Its address is
slack:<channel>:<parent ts>, for example slack:C0123ABCD:1730000000.000100.
A channel address, slack:<channel>, names where Fleet opens a thread.
- A channel id starts with
C,GorD, then uppercase letters and digits. - A
tsis<seconds>.<fraction>. It is unique within a channel (slack-threads). - A message is in a thread when it has
thread_ts. The parent is the message wherethread_ts == ts(slack-threads). - A message without
thread_tsstarts its own thread. Its address uses its ownts. - A reply is posted with the parent's
tsasthread_ts, never with a reply'sts(slack-post).
Capabilities #
| Capability | Value | Why |
|---|---|---|
history |
true |
conversations.replies reads a thread. |
marker |
metadata |
Every post carries the intent key as message metadata. |
unmentioned |
true |
Slack delivers every message in a channel the bot is in. |
threads |
true |
Every conversation is a thread. |
reactions |
true |
reactions.add and reactions.remove add and remove the bot's own reaction. |
The values are the same on every account. capabilities calls auth.test
first, so that a failing account answers Unknown.
Port mapping #
| Port item | Slack |
|---|---|
whoami |
auth.test. Its user_id is the identity. When team is set, the answer's team_id or enterprise_id must equal it. |
event |
Reads a Socket Mode envelope (type: events_api) or an Events API body (type: event_callback). Message events become Message, message_changed becomes Edited, and message_deleted becomes Removed. A delivery is direct when the event's channel_type is im (slack-message-im). |
| Delivery id | The event wrapper's event_id, which is globally unique (slack-events). |
| Ignored events | Other envelope types, events that are not messages, other workspaces, and message subtypes other than none, file_share, thread_broadcast and bot_message. |
| Mention | <@U…> or <@U…|name> with Fleet's bot user id in text (slack-format). The adapter does not rely on app_mention. Reason: app_mention needs app_mentions.read, and the reference does not state how it behaves inside threads (unverified) (slack-mention). |
| Authors | The account's bot is fleet. A message with a bot_id, or of subtype bot_message, is a bot. Anyone else is a person. |
history |
conversations.replies for a thread, conversations.history for a channel, both with include_all_metadata (slack-replies). Pages of 200 follow next_cursor. has_more without a cursor is Unknown (Incomplete). |
starter |
The parent message. A tombstone parent is removed. |
post |
chat.postMessage with thread_ts, one markdown block, a mrkdwn text, and unfurl_links and unfurl_media off (slack-post). |
open |
chat.postMessage without thread_ts. The new thread's address is the channel and the returned ts. Later chunks of a split text reply to it. |
post to a channel address |
chat.postMessage without thread_ts, for every chunk: a log post starts no thread. A since read of the channel uses conversations.history. |
react |
reactions.add to add, reactions.remove to remove, with channel, timestamp (the message's ts) and name (slack-react-add, slack-react-remove). name is Slack's emoji name, such as eyes or white_check_mark; surrounding colons are stripped. Both methods list JSON and form bodies as accepted. The adapter sends form arguments, as it does for every method other than chat.*. already_reacted and no_reaction mean the reaction already stands as asked: a Known success. |
link |
None. A Slack permalink needs the workspace's domain, which only a chat.getPermalink call gives, so a log post names a Slack thread by its address. |
| Marker | {"event_type": "fleet_post", "event_payload": {"key": "<intent key>"}} (slack-post). History reads it back (slack-metadata). |
| Idempotency | None on chat.postMessage: client_msg_id is not an argument (slack-post). Recovery uses the marker in a later since read. |
| Identity | User ids, unique in their workspace (slack-user). In an Enterprise org, every user has one global id that starts with U or W (slack-ent). |
Each post carries its text twice:
blocksholds onemarkdownblock with the Markdown as written. Slack renders standard Markdown in this block, tables included (slack-markdown).textholds the same Markdown converted tomrkdwn, Slack's own syntax (slack-format). Slack showstextin notifications. History readstextback.
In the markdown block, the adapter escapes with a backslash each < that
starts <@, <! or <# outside code. So a post makes no mention, no
broadcast and no channel link. Slack's reference does not state that a
markdown block parses these forms (unverified).
In text, the adapter escapes &, < and > (slack-format). Code spans
and fences stay code. A heading becomes one bold line. A table becomes a
code block, because mrkdwn has no table.
A Slack answer maps onto the port as follows:
| Answer | Port |
|---|---|
ok: true |
Known. |
HTTP 429, or the error ratelimited |
Unknown (Throttled), with Retry-After as retryAfter. |
ok: false with internal_error or fatal_error |
Unknown. Slack says some aspect of the operation may have succeeded. |
ok: false with any other error |
Refused: a Known failure for a write. |
An unreadable body, or no ok field |
Unknown. |
Limits #
- The adapter splits a text at 4,000 characters, Slack's recommended length. Slack truncates text over 40,000 (slack-post). So a text that needs more than 10 posts is refused, never cut.
- Slack allows 12,000 characters across the
markdownblocks of one payload (slack-markdown). One post holds one chunk of 4,000 at most. - Slack allows about one message a second per channel (slack-post).
conversations.repliesandconversations.historyare Tier 3: 50 or more calls a minute (slack-replies).- Message metadata is visible to every member of the
workspace (slack-post). So a key names a Task and its
uid, never a secret. - While the listener is disconnected, the app "may lose events". Slack refreshes connections every few hours (slack-socket).
- In a tied thread, the history backstop recovers a lost message. A new thread's first mention during an outage is lost, and the person mentions again.
- Socket Mode apps are not allowed in the public Marketplace (slack-compare). This does not matter for an internal app.
- The Events API needs a 2xx within three seconds. It retries up to three times: at once, after one minute and after five (slack-events).
These points are unverified:
- The Socket Mode page gives no acknowledgement limit. The three seconds come from the Java SDK guide (slack-java).
- The retry counts for Socket Mode (slack-socket).
- Whether
message.channelsdelivers without channel membership. - Whether the app receives its own posts as events. Bolt's
ignoreSelfimplies that it does (slack-ignoreself). So the adapter reads them asfleetauthors. - Whether
message_changedandmessage_deletedevents carrychannel_type. The receive verb does not need it for a DM thread that Fleet already mirrors. - Whether App Home needs a separate checkbox, besides the Messages Tab, so that users can send messages to the app.
- Whether
im:historyalone, withoutmpim:history, letsconversations.repliesread a one-to-one DM. The method lists all four history scopes (slack-replies).
Troubleshooting #
| Symptom | Cause | Fix |
|---|---|---|
| A DM to the bot starts no Task, and the receive verb logs nothing | The app does not subscribe to message.im, or App Home's Messages Tab is off. |
Do the steps under The DM route. |
| A DM to the bot is ignored as chatter | No route of the account holds "dm:*", so the wildcard covers the DM under the mention rule. |
Add "dm:*" to the route's channels. |
The manager refuses the config: inbound "X" is not how a Slack listener delivers |
inbound names another platform's method. |
Set socket-mode or events-api. |
The manager refuses the config: a slack account needs a curlConfig |
The account has no curlConfig. |
Name the operator's curl config file. |
Resolved is Unknown: auth.test answered for team …, not the account's … |
The token belongs to another workspace, or team is wrong. |
Fix team, or the token in the curl config. |
Resolved is False with IdentityMismatch |
bot is not the token's bot user. |
Set bot to the user_id that auth.test returns. |
Resolved is Unknown: auth.test: invalid_auth or a similar error |
The curl config holds no valid bot token. | Fix the token in the curl config. |
InboundReady is True, but no message arrives |
The bot is not in the channel, or the app has no message subscriptions. | Invite the bot. Subscribe to message.channels and message.groups. |
A post fails with chat.postMessage: not_in_channel |
The bot is not a member of the channel. | Invite the bot to the channel. |
A message gets no ⏳, 👀 or ✅, and the manager's report names reactions.add: missing_scope |
The app lacks reactions:write. |
Add the scope, and reinstall the app. |
NeedsAttention/PostUnconfirmed |
A post stayed Unknown, and no recovery read found its key. | Check the thread, then act as the Conversation describes. |
Discord adapter #
The Discord adapter maps one Discord guild onto the
Gateway port. Its code is
crates/fleet-gateway/src/discord.rs. It keeps the
common rules of every adapter.
crates/fleet-cli/tests/e2e_gateway_discord.rs tests it end to end against a
stub curl.
Every Discord claim cites Discord's developer documentation. The docs were read
on 2026-11-01 from the discord/discord-api-docs repository at commit
9d2128b (2026-10-30). A claim that those pages do not state is marked
unverified. Limits lists them.
The listener program is not part of this repository. Fleet ships the adapter
and the account's intents, and the operator runs a listener.
Setup #
On the Discord side, the operator does these steps:
- Create an application in the Developer Portal, and add a bot user.
- Copy the bot token into two places only:
- a curl config file that the operator owns, as
header = "Authorization: Bot <token>". The header form isAuthorization: TOKEN_TYPE TOKEN(authentication). - the listener's own secret store, for example a service-manager credential.
- a curl config file that the operator owns, as
- Enable the Message Content privileged intent only when
messageContent = true. At 100 guilds or more, the intent needs verification (message content intent). One guild needs none. - Invite the bot to the one guild with the
botscope (bot authorization flow). Grant the six permissions below on the route's channels (permissions). - Enable Developer Mode in the Discord client. Copy the guild id, the bot user
id and the channel ids into
fleet.toml.
| Permission | Bit | Why |
|---|---|---|
VIEW_CHANNEL |
1 << 10 |
See the route's channels and their threads. |
SEND_MESSAGES |
1 << 11 |
Post the opening message in a channel. It "does not allow sending messages in threads". |
SEND_MESSAGES_IN_THREADS |
1 << 38 |
Post in threads. |
CREATE_PUBLIC_THREADS |
1 << 35 |
Start a thread from a message. |
READ_MESSAGE_HISTORY |
1 << 16 |
Read history. Without it, "no messages will be returned". Adding a reaction also needs it. |
ADD_REACTIONS |
1 << 6 |
Add the queued, working and replied reactions. Discord asks for it only when nobody has reacted with that emoji yet (create reaction). |
Fleet never passes the token to the listener. The listener never reads Fleet's
curl config. No token appears in fleet.toml, in an envelope, in a heartbeat,
in a record or in a log.
The listener is a program outside Fleet. It does these things:
- It reads its account from
fleet gateway account NAME --json, includingintents. - It connects to the Gateway and Identifies with the bot token and those
intents(list of intents). - It keeps a map from thread id to parent channel id. It fills the map from
GUILD_CREATE,THREAD_CREATE,THREAD_UPDATEandTHREAD_LIST_SYNC. - For each
MESSAGE_CREATE,MESSAGE_UPDATEandMESSAGE_DELETEdispatch, it runsfleet gateway receive --account NAMEwith one envelope. The envelope claimsverified = "connection". The payload addsparentIdto every envelope: the thread's parent channel for a message in a thread, andnullfor a message in a channel. - It beats with
--beaton every state change, and at least everygateway.beatMs. - It persists
session_id,resume_gateway_urland the sequence number of the last event that the verb accepted (exit 0). After a reconnect, it resumes from that sequence number. Discord then replays the missed events (resuming). - On exit 1, 4 or 5, it retries the same envelope with backoff, and holds the later events.
- On close code 4004 or 4014, it beats
closingand stops. Neither code may reconnect (close codes).
{"verified": "connection", "receivedAt": 1730000300100,
"payload": {"dispatch": {"op": 0, "t": "MESSAGE_CREATE", "s": 42, "d": {"…": "…"}},
"parentId": "1300000000000000000"}}
Configuration #
[gateway.accounts.discord-main]
platform = "discord"
team = "1200000000000000000" # the guild id
bot = "1210000000000000000" # the bot user's snowflake
inbound = "discord-gateway" # the listener holds the Gateway WebSocket
messageContent = false # true only when the application holds MESSAGE_CONTENT
cli = "curl"
curlConfig = "/etc/fleet/discord-curl.conf" # operator-owned; holds the Authorization header
| Key | Required/default | Meaning |
|---|---|---|
platform |
Required | discord. |
team |
Required | The guild id, a snowflake. |
bot |
Required | The bot user's snowflake. whoami compares it with GET /users/@me. |
inbound |
Required | discord-gateway: the listener holds an authenticated Gateway WebSocket, so an envelope claims verified = "connection". |
messageContent |
false |
true when the application holds the privileged MESSAGE_CONTENT intent. Only a Discord account accepts the key. |
cli |
curl |
The client executable, a path or a name on PATH. |
curlConfig |
Required | An absolute path. Fleet passes it to curl --config and never reads it. |
A route's channels are text or announcement channels. A thread belongs to the
route of its parent channel. A wildcard route, channels = ["*"], covers
every text and announcement channel that the bot can view in the guild, and
their public threads, apart from a channel that another route lists and the
gateway.logs channel. On such an account, the VIEW_CHANNEL grants are the
allowlist of channels. A Discord account refuses the DM entry, "dm:*".
Reason: the adapter ignores every DM. A person's id under [gateway.people]
is a user snowflake, never a username.
fleet gateway account NAME --json prints intents for a Discord account:
messageContent |
Intents | Value |
|---|---|---|
false |
GUILDS (1 << 0), GUILD_MESSAGES (1 << 9) |
513 |
true |
The above, and MESSAGE_CONTENT (1 << 15) |
33281 |
The account's digest covers intents. So a change of messageContent makes a
running listener ListenerConfigOld. A Slack or fake account prints no
intents.
The manager refuses an account that breaks these rules, with one of these errors:
inbound "X" is not how a Discord listener delivers; use "discord-gateway"a discord account needs a team: its guild ida discord account's team and bot are snowflakesa discord account needs a curlConfigthe Discord adapter reads no direct message; "dm:*" needs a slack or fake account, on a route of the account that lists"dm:*"messageContent is a Discord account's key, not "slack"'s, on an account of another platform
Decisions #
- Text and announcement channels, and public threads, only. Forum
channels, private threads and DMs are out of scope. Reason: forum thread
creation takes no
nonce(start thread in forum). So an Unknown forum open could never be recovered. messageContentdefaults tofalse. Mentions-only is the safe default, and the Conversation says so withMentionsOnly.- The listener adds
parentId.eventis pure, so it cannot look up a thread's parent. The listener already sees every thread event. - Give Fleet its own application. The nonce check is "by the same author". So another program that posts as the bot could match Fleet's nonces.
Address format #
A Discord conversation is a thread. Its address is
discord:<parent channel>:<thread>. Both parts are snowflakes. A channel
address, discord:<channel>, names where Fleet opens a thread.
- A thread is a channel of type 10, 11 or 12, and its
parent_idis the channel it lives in (threads). A text channel'sparent_idis its category, so the listener maps thread ids only. - A thread started from a message has that message's id: "The id of the created thread will be the same as the id of the source message" (start thread from message).
- A top-level message
Min channelCis the conversationdiscord:C:M. The address exists before the thread does. Fleet starts the thread on its first post there. - A message in a thread
Tof channelCis the conversationdiscord:C:T.Ccomes from the envelope'sparentId.
Capabilities #
| Capability | Value | Why |
|---|---|---|
history |
true |
GET /channels/{id}/messages reads a thread. |
marker |
nonce { windowMs: 60000 } |
The only documented duplicate check is the nonce window. |
unmentioned |
messageContent, and the application holds the intent |
GET /applications/@me returns flags. GATEWAY_MESSAGE_CONTENT is 1 << 18, and GATEWAY_MESSAGE_CONTENT_LIMITED is 1 << 19 (application flags). |
threads |
true |
Every conversation is a thread. |
reactions |
true |
Create and delete own reaction add and remove the bot's reaction. |
When unmentioned is false, the Conversation shows
NeedsAttention/MentionsOnly. In a tied thread, a person then mentions the bot
on each turn.
Port mapping #
Every call goes to https://discord.com/api/v10. Every call carries
User-Agent: DiscordBot (https://github.com/Thurbeen/fleet, <version>), the
documented form (user
agent). Fleet sends
no Authorization header itself.
| Port item | Discord |
|---|---|
whoami |
GET /users/@me gives the identity. Then GET /guilds/{team} must succeed, else the answer is Unknown. |
capabilities |
GET /applications/@me, as above. |
event |
Reads the envelope's dispatch with op 0: MESSAGE_CREATE becomes Message, MESSAGE_UPDATE becomes Edited, and MESSAGE_DELETE becomes Removed (gateway events). |
| Delivery id | create/<id>, update/<id>/<edited_timestamp> or delete/<id>. The Gateway has no event id, so the adapter derives one. A replayed event gets the same id. |
| Ignored events | Other dispatches; another guild; DMs (no guild_id); private threads (channel_type 12); message types other than 0 (DEFAULT) and 19 (REPLY), such as 21 starter references; a MESSAGE_UPDATE without edited_timestamp or without content. |
| Unknown events | A payload without a dispatch object; a message without id or channel_id; an envelope without the parentId key; a public thread's message (channel_type 10 or 11) whose parentId is null. Reason: an edit or a removal carries no channel type, so only the listener can say whether its channel is a thread. |
| Mention | The bot's user id in the mentions array (message object). A role mention is not a mention of Fleet. |
| Authors | The account's bot is fleet. Another message with author.bot or a webhook_id is a bot. Anyone else is a person. The name is global_name, else username. |
| Message time | The snowflake's time: (snowflake >> 22) + 1420070400000 (snowflakes). |
startsThread |
true for a top-level message, false in a thread. |
Message key |
None. Fleet recognises its posts by author id. |
history |
Reads the starter with GET /channels/{C}/messages/{T}. Then reads GET /channels/{T}/messages?limit=100, under a budget of 10 calls. A first read pages backward with before until it holds the newest limit messages; its leftOut counts only the older messages it happened to read, so it is a lower bound. Every other read pages forward with after from its bound. The starter is one of the messages. A since read starts after the snowflake for that time. |
starter |
Error 10008 Unknown Message on the starter read makes it removed. |
post |
POST /channels/{T}/messages (create message). On error 10003 Unknown Channel, the thread is not started yet. The adapter starts it with POST /channels/{C}/messages/{T}/threads, then sends again. Error 160004 (a thread already exists) counts as started. |
open |
Posts the first chunk in C, then starts a thread from that post. The other chunks go into the thread. The answer is Opened { conversation: discord:C:M }. |
post to a channel address |
POST /channels/{C}/messages for every chunk. It starts no thread. |
react |
PUT /channels/{X}/messages/{M}/reactions/{emoji}/@me to add, DELETE of the same path to remove (create reaction, delete own reaction). X is the thread T, or the parent channel C for the thread's starter message M = T. emoji is URL-encoded, as Discord requires. The adapter maps a name such as eyes, white_check_mark or hourglass_flowing_sand to its Unicode emoji, takes a Unicode emoji as it is, and takes a custom emoji as name:id. Another name is a Known failure, and no call is made. Both endpoints answer 204 with no body. |
link |
https://discord.com/channels/{guild}/{T}, with the account's team as the guild: the link Discord copies for a channel or thread. |
| Identity | User snowflakes. A username is "not unique across the platform" (user object). |
A post's body has these fields:
content: Fleet's Markdown, unchanged. Discord renders Markdown itself.nonce: the first 25 hex characters ofsha256(<intent key>). Every resend of one key carries the same nonce.enforce_nonce: true.allowed_mentions: {"parse": []}. So a post mentions nobody (allowed mentions).flags: 4(SUPPRESS_EMBEDS). So Fleet's links never unfurl.
A new thread's name is the text's first non-empty line, at most 100 characters.
A text with no such line names the thread Fleet.
A Discord answer maps onto the port as follows:
| Answer | Port |
|---|---|
| 2xx | Known. |
| 429 | Nothing was done. A read is Unknown (Throttled), and retryAfter is the body's retry_after in seconds, else the Retry-After header (rate limits). A write is a Known failure, which the controller retries after its delay inside the nonce window (see Recovering a post). |
| Another 4xx | Refused: a Known failure for a write. The write was not made. |
| 5xx, or an unreadable body | Unknown. |
Recovering a post #
enforce_nonce makes Discord return the existing message for a repeated nonce
"in the past few minutes"
(create message).
ConversationController and GatewayController settle an Unknown post as
follows:
- It looks for the key in the mirror.
- It resends the post under the same key while both conditions hold:
- the time is before the first intent's
atpluswindowMs, - fewer than three attempts were made.
- the time is before the first intent's
- Otherwise it raises
NeedsAttention/PostUnconfirmedand waits for a person.
A resend keeps the first intent, so the window counts from the first send.
A refused post (a 4xx or a 429) is retried after the controller's delay
under the same rule: inside the first send's window, under the first intent.
Past the window, it raises NeedsAttention/PostFailed. Reason: an earlier
send under the key may have landed, and only the nonce window makes a resend
safe. A refused post is not retried in a pass that cannot read the
platform's capabilities.
The controller looks at a post's receipt on the next pass, not at the next poll. Reason: the window is shorter than the poll interval.
Two cases end with a person, although a later send would be safe:
- A post planned while the thread's Task create is pending or busy keeps
that create's interval. If its answer is lost, it raises
PostUnconfirmed. - A post refused twice, such as by two 429 answers, has its second retry
due past the 60-second window. It raises
PostFailed. Fleet never reads history to find a nonce. Reason: a read withoutREAD_MESSAGE_HISTORYis an empty list, so an empty read proves nothing.
Limits #
contentholds at most 2,000 characters. The adapter splits at 2,000 Unicode scalar values, into at most 10 posts. A longer text is a Known failure.- A nonce holds at most 25 characters.
- A history page holds at most 100 messages. A read that needs more than 10
calls is Unknown (
Incomplete). - A message can have only one thread created from it.
- Sending a message unarchives an archived thread, unless the thread is locked (active and archived threads).
- A failed resume loses the events of the gap. In a tied thread, the history backstop recovers them. A mention in an untied thread is lost, and the person mentions again.
- API v10 and v9 are listed as "Available" (API versioning).
These points are unverified:
- The exact length of the nonce window. Discord says "the past few minutes". Fleet trusts 60 seconds.
- The unit of the 2,000 "characters".
- The order and paging of
afterbeyond "newest to oldest", limit 1 to 100, default 50 (get channel messages). - The HTTP status of error 160004.
- What create reaction answers when the bot already has the reaction, and what delete own reaction answers when it has none. Fleet takes a 2xx as success and any 4xx as a refusal, which it tries at most three times.
- Whether a role mention of the bot carries content without
MESSAGE_CONTENT. The documented exceptions are the app's own messages, DMs, messages that mention the app, and a context menu command's target. - How long a Gateway session stays resumable. Discord says "a few minutes".
Troubleshooting #
| Symptom | Cause | Fix |
|---|---|---|
| The listener closes with 4014 | The listener asked for MESSAGE_CONTENT, and the application lacks it in the portal. |
Set messageContent = false, or enable the Message Content intent in the portal. |
| The listener closes with 4004 | The listener's token is wrong. | Fix the token in the listener's secret store. |
A message gets no ⏳, 👀 or ✅, and the manager's report names HTTP 403 50013 |
The bot lacks ADD_REACTIONS or READ_MESSAGE_HISTORY in the channel. |
Grant both. Relays and posts go on meanwhile. |
A message gets no reaction, and the manager's report names HTTP 400 10014 Unknown Emoji |
A custom emoji in gateway.reactions is not in the guild. |
Name a Unicode emoji, or a custom emoji of the guild as name:id. |
NeedsAttention/MentionsOnly |
messageContent is false, or the application lacks the intent. |
Mention the bot on each turn. Or enable the intent in the portal and set messageContent = true. |
fleet gateway receive exits 4: … the envelope has no parentId … or … the envelope's parentId is null |
The listener sent no parentId, or does not know the thread's parent. |
Send parentId on every envelope, and fix the listener's thread map. Discord replays the event after a resume. |
Resolved is Unknown: the bot cannot see guild … |
The bot is not in the guild, or team is wrong. |
Invite the bot to the guild, or fix team. |
Resolved is False with IdentityMismatch |
bot is not the token's bot user. |
Set bot to the id that GET /users/@me returns. |
ListenerConfigOld after a change of messageContent |
The digest covers intents. |
Restart the listener, so it Identifies with the new intents. |
NeedsAttention/PostUnconfirmed |
A post stayed Unknown past the nonce window, or after three attempts. | Check the thread, then act as the Conversation describes. |
A post fails with HTTP 403 50013 Missing Permissions |
The bot lacks a permission on the channel. | Grant the six permissions under Setup. |