Skip to content

t1k:discord-mentions

FieldValue
Modulet1k-human-comms
Version2.8.25
Effortlow
ToolsBash, Grep, Read

Keywords: discord mentions, discord webhook, discord-mentions.the1studio.org, link discord, mention api, mention reminders, mention webhook, nudge, tagged me, unanswered mention, unlinkedCaller, who tagged me

/t1k:discord-mentions
mentions [hours] | reminders | link | webhook <https-url> | troubleshoot

Owner: discord-bot-service (ClaudeAssistant). Full reference (auth matrix, payloads, SSRF rules, data model): https://github.com/The1Studio/ClaudeAssistant/blob/master/docs/discord-mention-api.md (private repo: org members only). This file is the how-to and stands alone for everyday use.

Host: https://discord-mentions.the1studio.org (bearer only, any T1K GitHub org member). To have tags delivered into a running session automatically (not only listed), use t1k-discord-inbound; this skill lists and registers.

You read only messages that tagged you, and manage only your own webhooks and link codes. Identity comes from your studio credential, never from the request. Another person’s id is 403. Never try to read someone else’s tags; there is no admin path for a person, only for services.

Terminal window
export T1K_STUDIO_AUTH_BASE=https://auth-api.the1studio.org
AUTH=$(bun "$HOME/.claude/scripts/studio-auth-headers.cjs" | jq -r .Authorization)

Keep AUTH in a shell variable. Never echo it, never paste it in chat or a ticket. A 401/403 after an hour means re-run the line. An agent session works the same way, but it acts as the user who started it; machine and service tokens are refused on purpose.

Terminal window
SINCE=$(date -u -d '5 hours ago' +%Y-%m-%dT%H:%M:%SZ)
curl -sS -H "Authorization: $AUTH" \
"https://discord-mentions.the1studio.org/api/discord/mentions?userId=me&since=$SINCE&limit=100" |
jq -r '.data.items[] | [.createdAt, .authorName, .channelName, .content, .jumpUrl] | @tsv'
  • userId=me is required (no default). Optional: guildId, channelId, since, before (ISO-8601), limit (default 50, max 100), cursor.
  • Newest first. data.nextCursor is the empty string on the last page; otherwise pass it back as cursor= to get the next page.
  • content already has names, not <@id> tokens. The only id field is mentionedUserIds.

A 403 with code: "unlinkedCaller" means GitHub does not know which Discord account is yours.

Terminal window
curl -sS -X POST -H "Authorization: $AUTH" \
https://discord-mentions.the1studio.org/api/discord/link-codes # -> { data: { code: "ABCD-EFGH" } }

Then in any server the bot is in, type /link code:ABCD-EFGH and press Confirm on the private reply. The code lasts 10 minutes and works once. Re-run the mentions call to check. 409 alreadyLinked means you are already linked: skip this step.

4. Advanced: push to your own HTTPS endpoint (webhook)

Section titled “4. Advanced: push to your own HTTPS endpoint (webhook)”

Most people should rely on the reminder nudge in section 5. Use a webhook only when your own service must receive each tag over HTTPS.

Terminal window
curl -sS -X POST -H "Authorization: $AUTH" -H 'Content-Type: application/json' \
-d '{"url":"https://your-host.example.com/discord-mention"}' \
https://discord-mentions.the1studio.org/api/discord/mention-webhooks
  • The response carries secret once. Save it straight into your receiver’s secret store (t1k vault for shared ones). Do not print it, commit it, or paste it in chat; GET never shows it.

  • Also: GET /api/discord/mention-webhooks (list yours), DELETE .../:id, POST .../:id/test (queues one synthetic delivery; use it to prove your receiver).

  • Receiver URL must be public https on port 443. http, other ports, private/loopback addresses and redirects are rejected. A laptop or a box behind NAT cannot receive a webhook: poll section 2 instead (an SSE stream is not built).

  • Delivery: POST JSON { event: "discord.mention", deliveryId, mention } with headers X-Mention-Timestamp, X-Mention-Delivery-Id, X-Mention-Signature: sha256=<hex>. Verify: HMAC-SHA256 with your secret over timestamp + "." + deliveryId + "." + rawBody (the exact raw bytes, not re-serialised JSON), constant-time compare, reject a timestamp older than 5 minutes (300 s). Node receiver:

    const crypto = require('node:crypto');
    const TOLERANCE_SECONDS = 300;
    // rawBody = the exact bytes received, not a re-stringified object.
    function verify(rawBody, headers, secret) {
    const ts = headers['x-mention-timestamp'];
    const id = headers['x-mention-delivery-id'];
    const sig = headers['x-mention-signature'];
    if (!ts || !id || !sig) return false;
    const age = Math.abs(Math.floor(Date.now() / 1000) - Number(ts));
    if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) return false;
    const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(`${ts}.${id}.${rawBody}`).digest('hex');
    const a = Buffer.from(expected);
    const b = Buffer.from(sig);
    return a.length === b.length && crypto.timingSafeEqual(a, b);
    }

    In Express capture the raw body (express.raw, or a verify hook on express.json).

  • Retries: up to 6 attempts, backoff from 30 s doubling to 6 h, 5 s timeout per attempt. Dedupe on deliveryId. Respond 2xx fast; do the work after.

5. Unanswered-mention reminders (default, no setup)

Section titled “5. Unanswered-mention reminders (default, no setup)”

The bot replies in place under a tag that nobody answered: weekdays at 09:00 Asia/Saigon, one reply per tagged message, pinging only the tagged person. On by default for linked people. Nothing to set up, and do not stand up a webhook receiver for reminders.

  • Check or change it in chat: ask the bot (“are my mention reminders on?”, “turn off my mention reminders”). It uses the manage_mention_nudges tool (status, opt_out, opt_in), acts only for the person asking, and confirms before it writes.
  • Via the API: GET /api/discord/mention-nudge shows your status, next slot, last 10 nudges, scope and caps (3 replies per channel and 5 per person per run). PUT /api/discord/mention-nudge with {"optedOut": true} or {"optedOut": false} changes it. Send a studio bearer (section 1); identity comes from the token, never from the body.
  • The dashboard switch is read-only for now. Point people to the bot.
  • Behaviour details (nudge timing, caps, scope) live with the mention service, a private repo (org members only).
  • Forward-only. Tags sent before the feature went live (2026-10-15) are not stored.
  • Guild messages only, direct @user tags only. No DMs, no @role/@everyone, no bot or self tags.
  • An edit that removes the tag does not remove the row. A deleted message drops out.
  • This is the bot’s capture, not live Discord. The Discord MCP reads live channels and can show a message the bot never saw; the two can differ.
You seeMeaningFix
401No or bad bearerRedo section 1
403 host_not_allowed (no token sent)This host answers 403, not 401, when no bearer is sentSend a bearer (section 1)
403 credentialTooWeak (mention-nudge write)Only the Cloudflare Access header was sentUse a studio bearer
403 unlinkedCallerNo Discord id on your userSection 3
403 otherUserForbiddenuserId is not youUse userId=me
403 “ownerIdentity” / “could not be matched”Your GitHub id matches zero or two usersAsk in the platform channel; never edit the mapping by hand
400 missingUserIdNo userId paramAdd userId=me
404 on a pathOnly mentions, mention-webhooks and link-codes are exposedCheck the path
Webhook signature mismatch everywhereINTERNAL_SERVICE_SECRET was rotatedRecreate the webhook for a new secret
Empty listNobody tagged you in that window, or the bot did not see itWiden since; compare with the Discord MCP