diff --git a/docs/channels/discord.md b/docs/channels/discord.md index ce9dc04f3..809a0ecd1 100644 --- a/docs/channels/discord.md +++ b/docs/channels/discord.md @@ -57,6 +57,7 @@ Minimal config: 12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `channels.discord.actions.*`). - Reaction removal semantics: see [/tools/reactions](/tools/reactions). - The `discord` tool is only exposed when the current channel is Discord. + - User reactions on the bot's messages can **trigger** the session (yes/no style) when `guilds..reactionTrigger` is enabled; see [Reaction trigger](#reaction-trigger). 13. Native commands use isolated session keys (`agent::discord:slash:`) rather than the shared `main` session. Note: Name β†’ id resolution uses guild member search and requires Server Members Intent; if the bot can’t search members, use ids or `<@id>` mentions. @@ -266,6 +267,12 @@ Outbound Discord API calls retry on rate limits (429) using Discord `retry_after slug: "friends-of-clawd", requireMention: false, reactionNotifications: "own", + reactionTrigger: { + enabled: true, + windowSeconds: 60, + positiveEmojis: ["πŸ‘", "βœ…", "πŸ‘Œ"], + negativeEmojis: ["πŸ‘Ž", "❌"] + }, users: ["987654321098765432", "steipete"], channels: { general: { allow: true }, @@ -311,6 +318,7 @@ ack reaction after the bot replies. - `guilds..channels`: channel rules (keys are channel slugs or ids). - `guilds..requireMention`: per-guild mention requirement (overridable per channel). - `guilds..reactionNotifications`: reaction system event mode (`off`, `own`, `all`, `allowlist`). +- `guilds..reactionTrigger`: optional config to turn user reactions on the bot's messages into session triggers. When enabled, positive/negative emoji reactions on the bot's recent messages (within a time window) dispatch an inbound message to the session instead of only emitting a system event. See [Reaction trigger](#reaction-trigger) below. - `textChunkLimit`: outbound text chunk size (chars). Default: 2000. - `chunkMode`: `length` (default) splits only when exceeding `textChunkLimit`; `newline` splits on blank lines (paragraph boundaries) before length chunking. - `maxLinesPerMessage`: soft max line count per message. Default: 17. @@ -332,6 +340,32 @@ Reaction notifications use `guilds..reactionNotifications`: - `all`: all reactions on all messages. - `allowlist`: reactions from `guilds..users` on all messages (empty list disables). +#### Reaction trigger + +When `guilds..reactionTrigger.enabled` is `true`, reactions on the **bot's own messages** within a short time window are treated as session triggers: the agent receives an inbound message describing the reaction (e.g. positive/negative and who reacted), and can reply in the same channel. Useful for yes/no or confirm/cancel flows without typing a new message. + +- **Scope**: only reactions on messages sent by the bot; only within `reactionTrigger.windowSeconds` (default 60) after the bot message. +- **Classification**: emoji are classified as positive (e.g. πŸ‘ βœ… πŸ‘Œ) or negative (e.g. πŸ‘Ž ❌). Custom lists: `reactionTrigger.positiveEmojis` and `reactionTrigger.negativeEmojis`. Neutral emoji do not trigger. +- **Behavior**: when a positive or negative reaction matches, a system event is enqueued and an inbound message is dispatched to the session; the agent can reply. Regular reaction notifications are not emitted for that reaction. + +Example: + +```json5 +"YOUR_GUILD_ID": { + "requireMention": false, + "reactionNotifications": "own", + "reactionTrigger": { + "enabled": true, + "windowSeconds": 60, + "positiveEmojis": ["πŸ‘", "βœ…", "πŸ‘Œ"], + "negativeEmojis": ["πŸ‘Ž", "❌"] + }, + "channels": { "general": { "allow": true } } +} +``` + +Omit `positiveEmojis`/`negativeEmojis` to use built-in default lists. + ### Tool action defaults | Action group | Default | Notes | diff --git a/docs/gateway/configuration.md b/docs/gateway/configuration.md index 1d270974d..e4e1f8f25 100644 --- a/docs/gateway/configuration.md +++ b/docs/gateway/configuration.md @@ -1090,6 +1090,12 @@ Multi-account support lives under `channels.discord.accounts` (see the multi-acc slug: "friends-of-clawd", requireMention: false, // per-guild default reactionNotifications: "own", // off | own | all | allowlist + reactionTrigger: { // optional: turn reactions on bot messages into session triggers + enabled: true, + windowSeconds: 60, + positiveEmojis: ["πŸ‘", "βœ…", "πŸ‘Œ"], + negativeEmojis: ["πŸ‘Ž", "❌"] + }, users: ["987654321098765432"], // optional per-guild user allowlist channels: { general: { allow: true }, @@ -1121,11 +1127,12 @@ Multi-account support lives under `channels.discord.accounts` (see the multi-acc Moltbot starts Discord only when a `channels.discord` config section exists. The token is resolved from `channels.discord.token`, with `DISCORD_BOT_TOKEN` as a fallback for the default account (unless `channels.discord.enabled` is `false`). Use `user:` (DM) or `channel:` (guild channel) when specifying delivery targets for cron/CLI commands; bare numeric IDs are ambiguous and rejected. Guild slugs are lowercase with spaces replaced by `-`; channel keys use the slugged channel name (no leading `#`). Prefer guild ids as keys to avoid rename ambiguity. Bot-authored messages are ignored by default. Enable with `channels.discord.allowBots` (own messages are still filtered to prevent self-reply loops). -Reaction notification modes: +Reaction notification modes (`guilds..reactionNotifications`): - `off`: no reaction events. - `own`: reactions on the bot's own messages (default). - `all`: all reactions on all messages. - `allowlist`: reactions from `guilds..users` on all messages (empty list disables). +Optional `guilds..reactionTrigger`: when enabled, positive/negative reactions on the bot's recent messages (within `windowSeconds`, default 60) dispatch an inbound message to the session instead of only emitting a system event. See [Discord](/channels/discord#reaction-trigger). Outbound text is chunked by `channels.discord.textChunkLimit` (default 2000). Set `channels.discord.chunkMode="newline"` to split on blank lines (paragraph boundaries) before length chunking. Discord clients can clip very tall messages, so `channels.discord.maxLinesPerMessage` (default 17) splits long multi-line replies even when under 2000 chars. Retry policy defaults and behavior are documented in [Retry policy](/concepts/retry). diff --git a/docs/tools/reactions.md b/docs/tools/reactions.md index 364f38695..ea77604e7 100644 --- a/docs/tools/reactions.md +++ b/docs/tools/reactions.md @@ -13,7 +13,8 @@ Shared reaction semantics across channels: Channel notes: -- **Discord/Slack**: empty `emoji` removes all of the bot's reactions on the message; `remove: true` removes just that emoji. +- **Discord**: Inbound reaction notifications emit system events per guild via `channels.discord.guilds..reactionNotifications` (`off` | `own` | `all` | `allowlist`); see [Discord](/channels/discord). Reactions on the bot's messages can also **trigger** the session when `reactionTrigger` is enabled for the guild (see [Discord](/channels/discord#reaction-trigger)). Empty `emoji` removes all of the bot's reactions on the message; `remove: true` removes just that emoji. +- **Slack**: empty `emoji` removes all of the bot's reactions on the message; `remove: true` removes just that emoji. - **Google Chat**: empty `emoji` removes the app's reactions on the message; `remove: true` removes just that emoji. - **Telegram**: empty `emoji` removes the bot's reactions; `remove: true` also removes reactions but still requires a non-empty `emoji` for tool validation. - **WhatsApp**: empty `emoji` removes the bot reaction; `remove: true` maps to empty emoji (still requires `emoji`).