Self-improving AI Employees for everyone
Discord Service
Bot messaging, REST actions, gateway message triggers and slash commands.
Plugin folder: server/nodes/discord/.
Reference plugins this one follows: nodes/whatsapp_business/
for the media-on-the-deploy-path question and the webhook shape, and
nodes/telegram/ for the long-lived-connection
lifecycle.
Nodes
| Node | Kind | Purpose |
|---|---|---|
discordSend |
ActionNode, usable_as_tool |
Messages, embeds, one file attachment. Splits past 2000 characters. |
discordAction |
ActionNode, usable_as_tool |
Guilds/channels/messages/reactions/threads, download_attachments, interaction_respond, execute_webhook, custom. |
discordReceive |
TriggerNode (event) | Fires on an inbound message. |
discordInteraction |
TriggerNode (event) | Fires on a slash command or component click. |
Palette group discord, colour #5865F2. Icon is a local icon.svg (the
brand mark); the credential tile resolves discord.svg.
Why send is separate from action. The single-<service>Action convention
belongs to the CLI wrappers (githubAction, cloudflareAction, …). Both
messaging plugins here — telegram and whatsapp_business — keep send separate,
because send is the high-frequency agent-facing operation and a twenty-operation
union makes a poor LLM tool schema.
Why there is no media node. whatsappBusinessMedia exists because Meta
requires upload-then-reference. Discord attaches files directly in the send
multipart, so only the download side needs an operation.
Why interactions are a second trigger. canary_registry
maps one node type to exactly one CloudEvents type, because that string becomes
the Temporal EventType Search Attribute the listener is discovered by. One
node cannot subscribe to both. The payloads also share almost nothing, so
merging would mean a union output schema and weaker {{trigger.field}}
resolution. Same split, same reasons, as whatsappBusinessReceive vs
whatsappBusinessStatus.
Multi-account
API keys are stored under a {session_id}_{provider} key, so the session_id
column is a free scoping axis:
account_id "default" -> session_id "default" (what the modal writes)
account_id "<app_id>" -> session_id "discord:<app_id>"
_accounts.py is the only file that
knows this mapping. "default" is the row the unmodified credentials modal
already writes, so a single-bot install needs no account concept and
multi-account is purely additive. Every node carries an account_id param
backed by the discordAccounts option loader; blank means default.
Enumeration needs AuthService.list_key_scopes(provider) — added for this
plugin, generic, index-backed.
credential_customer_id is deliberately not used. It is per-execution-context
tenancy, so two nodes in one workflow could never target two different bots. It
is the tenancy axis, not the account axis, and
test_identity_namespaces.py
exists to keep them apart.
Security invariants
account_id is stripped from model arguments. Inbound Discord messages are
the realistic source of hostile tool arguments and account_id selects which
bot identity sends, so both nodes list it in server_controlled_fields. The
framework enforces that on every tool path: in process,
BaseNode.execute_as_tool drops locked
fields from the model's arguments before its {**node_params, **tool_args}
merge; on Temporal, where the agent workflow has already merged the arguments,
NodeExecutor puts back the saved value
(or the default). AccountScopedNode in
_base.py strips locked fields again as
defence in depth; it runs only in process, since the per-type activity calls
execute for an ActionNode. Tests drive both paths with a hostile account_id.
The interaction token never leaves the server. It is a 15-minute bearer
credential that can post as the app, and trigger output is persisted three ways,
broadcast twice, retained in the status cache and replayed into LLM context each
turn. discordInteraction emits an opaque interaction_ref;
discordAction[interaction_respond] trades it back through a process-local TTL
map. Refs do not survive a restart, which is not a gap — a workflow that
outlived a restart mid-interaction has already missed the window.
custom route paths are validated in _base.build_url, not at the call
site, so no future caller can skip it. Without the guard that operation would
send the bot token to any host a workflow named. Webhook URLs are host-whitelisted
by assert_discord_host, and neither a webhook URL nor an interaction URL is
ever echoed in an error — both embed credentials.
Snowflakes are stringified at the dispatch boundary. discord.py exposes them
as int while Discord's own JSON uses strings; past 2^53 a numeric comparison
collapses two distinct ids, and comparing an id is the most natural edge
condition a user writes (see commit 20d00a07).
Rate limiting
_ratelimit.py is pure state, no IO.
Reactive rather than predictive: it reads 429s and holds what follows, but does
not track X-RateLimit-Remaining to sleep before hitting zero. Three scopes,
and conflating any two is a bug:
- per account — the 50 req/s ceiling is per bot token.
- per account — a global 429 pauses that token entirely.
- per process — the invalid-request ban is enforced by Cloudflare on the source IP, not the token. Three misconfigured bots on one host share one budget and blowing it takes out the healthy accounts too. This is the piece most likely to be "simplified" into the per-account limiter later. It must not be.
A 429 with a non-JSON body is the Cloudflare edge ban, not a Discord rate limit,
and is reported as such. Any wait over ~30s becomes a retryable RuntimeError
(never NodeUserError, which is non-retryable) so Temporal's backoff releases
the worker slot instead of pinning it.
Gateway
discord.Client owns the socket. What it handles is exactly the part that
fails silently when hand-rolled: zlib framing, heartbeat/ACK with jitter,
RESUME versus IDENTIFY on the right close codes, resume_gateway_url, and
IDENTIFY concurrency. Client.start() is used, never run() — the latter
installs signal handlers and would fight uvicorn.
REST does not go through discord.py. The nodes must work with no gateway
connection at all, discordAction needs arbitrary routes the typed methods do
not expose, and the invalid-request guard has to be process-wide across
accounts, which a per-client limiter cannot express. Gateway and REST never
cross; calling client.http from node code would bypass the limiter that knows
the shared budget.
BaseSupervisor.get_instance() is a per-subclass singleton and cannot hold N
connections, so gateways live in a module-level registry keyed by account, each
registering its own label with services._supervisor so
shutdown_all_supervisors() still reaches them.
Terminal failures are not retried. PrivilegedIntentsRequired and
LoginFailure fail identically every attempt; backing off spends the
1000-IDENTIFY daily budget, which ends in a reset token and an email to the
app owner. Both are translated into actionable errors and the gateway refuses
further retries. Readiness races the connection task rather than awaiting
wait_until_ready() alone, because login failures raise inside start() —
awaiting readiness would sit out the full 60s timeout and then report "not
ready" for a bad credential.
Attachments
discordReceive emits attachment metadata only;
discordAction[operation="download_attachments"] fetches them via
fetch_to_workspace (SSRF guard, streaming,
25 MB cap, contained write, FileRef out).
The reason is the deploy path: the engine marks a deployed trigger
_pre_executed and passes _trigger_output through verbatim
(ExecutionContext.create in services/execution/models.py), so the node body
never runs and a download flag there would work on the canvas and silently do
nothing once deployed. whatsappBusinessMedia exists for the same reason and
documents it in its own module docstring.
kind is never "audio": that asserts a real container probe, and a download
measures nothing. Discord CDN URLs are signed and expire, so they are resolved
immediately before fetching and never trusted from a stored output.
Interactions endpoint
POST /api/discord/interactions[/{account_id}], a plugin-owned router rather
than a WebhookSource, for three reasons the generic intake cannot express:
- Discord's endpoint-validation probe sends a deliberately invalid signature
and requires 401.
WebhookSource.handleraises 400, and a 400 makes Discord refuse to save the endpoint URL at all. - The initial response is due within three seconds, but
handle()awaits shaping,emit(a Visibility query plus a Signal per consumer) and dispatch before the router writes a byte. - PING must be answered with
{"type": 1}, while the generic route returns a fixed envelope.
Flow: raw-body Ed25519 verify → 401 on failure → 503 fail-closed when no public key is stored → PING answers PONG → anything else defers (type 5, or type 6 for a component so the existing message is edited) and fans out in a background task whose reference is held, since the loop keeps only a weak one.
Discord calls the endpoint without a session cookie, so the plugin registers
/api/discord/interactions with register_public_ingress_path, and
AuthMiddleware lets it (and the per-account paths below it) through with
login on. The signature check above is what authenticates each request;
/api/discord/callback stays behind the login.
Per-account paths exist so the server never trial-verifies against every stored public key, which would be both a timing oracle and an availability multiplier.
DiscordEd25519Verifier is the first
asymmetric verifier in the tree — the four shipped ones are HMAC — and uses
cryptography, already a dependency. Do not add PyNaCl. It verifies over
the raw body, never re-serialised JSON: any difference in key order or
separators breaks authentic requests.
Gateway and HTTP interaction delivery are mutually exclusive per application.
Setting an Interactions Endpoint URL stops INTERACTION_CREATE arriving over
the socket.
Router mounting
The interaction routes are added onto the router
make_oauth_callback_router builds, rather than into a fresh APIRouter with
the factory's router included into it. On an APIRouter — unlike on an app —
include_router records a pathless placeholder instead of flattening the
child's routes: the callback silently never mounts, and the pathless entry
reads as an ungated route to TestPublicSurfaceInvariant. That test is what
caught it.
Credentials
One provider entry, kind: "apiKey", fields:
| Key | Required | Purpose |
|---|---|---|
apiKey |
yes | Bot token. Stored under provider id discord. |
discord_application_id |
no | Labels the bot when several are connected. |
discord_public_key |
no | Ed25519 public key; slash commands only. |
discord_client_id / discord_client_secret |
no | OAuth2 user-context. |
DiscordBotCredential overrides inject(): the inherited bearer mode
hardcodes the literal Bearer prefix and Discord bot auth is Bot <token>,
which otherwise fails as a silent 401.
The probe calls /users/@me then /applications/@me and reports whether the
Message Content privileged intent is enabled. Without it the gateway still
connects and delivers empty content with no error anywhere — which surfaces
as "the Discord node returns blank text".
DiscordUserCredential (discord_oauth) is the user-context identity, stored
under a separate id so connecting a user never overwrites the bot token. Scopes
are identify and guilds only.
Registration surfaces
Everything self-registers from __init__.py:
WS handlers, router, OAuth callback path, three option loaders, four output
schemas, two filter builders, a trigger precheck, service refresh, two canary
trigger types, the social send adapter, and a shutdown hook.
Outside the folder: nodes/groups.py, config/credential_providers.json,
config/node_allowlist.json, constants.py (both trigger frozensets), the
three lists in tests/test_plugin_self_containment.py, and
SOCIAL_PLATFORM_PLUGINS in tests/test_social_provider_registry.py, which
is what asserts the adapter is actually registered rather than just imported.
import discord never appears at module scope in any file the plugin
walker touches. nodes/__init__.py swallows
import errors during discovery, so a failing library import would make the
whole plugin silently disappear rather than report anything.
Both trigger frozensets are asserted. Omitting a trigger from
WORKFLOW_TRIGGER_TYPES is a silent failure: TriggerManager.find_trigger_nodes
filters on it, so deploy ignores the node with no listener and no warning (see
the comment inside WORKFLOW_TRIGGER_TYPES in constants.py;
deploy once skipped stripeReceive exactly this way). EVENT_TRIGGER_TYPES has no
production reader, but the tests assert membership in both.
Testing
server/tests/nodes/test_discord.py —
121 collected cases (80 test functions, several parametrized; pytest --collect-only -q
is the counting method), no live bot required. Covers account scoping, the path guard, error
classification, rate-limit parsing, content splitting, the tool-path account
lock, send/action shapes, event shaping, filters, gateway lifecycle, the
Ed25519 verifier, the endpoint's 401/503/PONG/defer behaviour, and route
mounting.
Not testable without a live bot: the gateway handshake, IDENTIFY limits, session resume, sharding, and Discord's own intent gating. Manual smoke checklist:
- Add a bot token in Credentials; confirm the probe reports the Message Content intent state.
- Connect from the modal; confirm the status shows the bot username and guild count.
- Send to a channel, with and without an attachment.
- Post a message in that channel and confirm
discordReceivefires on Run. - Deploy the workflow and confirm it still fires — this is the path the frozensets gate.
- For slash commands, set the Interactions Endpoint URL and confirm Discord accepts it (that is the 401 path being exercised).