t1k:discord-mentions
| Field | Value |
|---|---|
| Module | t1k-human-comms |
| Version | 2.8.25 |
| Effort | low |
| Tools | Bash, 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
How to invoke
Section titled “How to invoke”/t1k:discord-mentionsmentions [hours] | reminders | link | webhook <https-url> | troubleshootDiscord Mentions: who tagged me
Section titled “Discord Mentions: who tagged me”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.
The one rule
Section titled “The one rule”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.
1. Get a bearer (once per hour)
Section titled “1. Get a bearer (once per hour)”export T1K_STUDIO_AUTH_BASE=https://auth-api.the1studio.orgAUTH=$(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.
2. Who tagged me (last 5 hours)
Section titled “2. Who tagged me (last 5 hours)”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=meis required (no default). Optional:guildId,channelId,since,before(ISO-8601),limit(default 50, max 100),cursor.- Newest first.
data.nextCursoris the empty string on the last page; otherwise pass it back ascursor=to get the next page. contentalready has names, not<@id>tokens. The only id field ismentionedUserIds.
3. First time: link your Discord account
Section titled “3. First time: link your Discord account”A 403 with code: "unlinkedCaller" means GitHub does not know which Discord account is yours.
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.
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
secretonce. Save it straight into your receiver’s secret store (t1k vaultfor shared ones). Do not print it, commit it, or paste it in chat;GETnever 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
httpson 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:
POSTJSON{ event: "discord.mention", deliveryId, mention }with headersX-Mention-Timestamp,X-Mention-Delivery-Id,X-Mention-Signature: sha256=<hex>. Verify: HMAC-SHA256 with your secret overtimestamp + "." + 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 averifyhook onexpress.json). -
Retries: up to 6 attempts, backoff from 30 s doubling to 6 h, 5 s timeout per attempt. Dedupe on
deliveryId. Respond2xxfast; 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_nudgestool (status,opt_out,opt_in), acts only for the person asking, and confirms before it writes. - Via the API:
GET /api/discord/mention-nudgeshows your status, next slot, last 10 nudges, scope and caps (3 replies per channel and 5 per person per run).PUT /api/discord/mention-nudgewith{"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).
What it does not cover
Section titled “What it does not cover”- Forward-only. Tags sent before the feature went live (2026-10-15) are not stored.
- Guild messages only, direct
@usertags 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.
Troubleshoot
Section titled “Troubleshoot”| You see | Meaning | Fix |
|---|---|---|
401 | No or bad bearer | Redo section 1 |
403 host_not_allowed (no token sent) | This host answers 403, not 401, when no bearer is sent | Send a bearer (section 1) |
403 credentialTooWeak (mention-nudge write) | Only the Cloudflare Access header was sent | Use a studio bearer |
403 unlinkedCaller | No Discord id on your user | Section 3 |
403 otherUserForbidden | userId is not you | Use userId=me |
403 “ownerIdentity” / “could not be matched” | Your GitHub id matches zero or two users | Ask in the platform channel; never edit the mapping by hand |
400 missingUserId | No userId param | Add userId=me |
404 on a path | Only mentions, mention-webhooks and link-codes are exposed | Check the path |
| Webhook signature mismatch everywhere | INTERNAL_SERVICE_SECRET was rotated | Recreate the webhook for a new secret |
| Empty list | Nobody tagged you in that window, or the bot did not see it | Widen since; compare with the Discord MCP |