Skip to main content

Show Slack display names in mentions

Status: planned (#147). The bot-token integration + the mention-name preview described here are landing; this page ships alongside them.

Goal​

You'll connect a Slack bot token so that alert-rule Mentions work by name instead of by raw member ID: in the alert-rule form you type a person's name and pick them from your Slack workspace's members, and everywhere a mention is shown — the form's chips and the rule's page (including the read-only view a viewer sees) — it reads as the person's name (Jane Doe), not U012ABCDEF. The Slack message itself still pings the person with a live @-mention; the rule stores and sends the member ID under the hood.

Why a bot token (and not the webhook)?​

The Slack alert webhook delivers the message, but a webhook URL can't list your members or look up who U012ABCDEF is. Searching members by name uses Slack's users.list API, and resolving an ID to a name uses users.info — both need a bot token with the users:read scope. The two are different credentials with different jobs:

  • the webhook URL delivers the alert (keep it as-is);
  • the bot token lists members for the name picker and resolves member IDs to names for display.

One bot token per Slack workspace covers every member in that workspace, so you paste it once for the whole organization — not per alert rule.

Prereqs​

  • A role that can manage integrations: super admin or technical admin. (Minting the token is a step-up action — you may be asked to re-enter your password.)
  • A Slack app installed in your workspace with the users:read scope — and only that scope. It covers both calls Measured Cloud makes (users.list for the picker, users.info for resolving an ID). This token is read-only; it never posts messages (that stays the webhook's job).

Create the bot token​

  1. Go to https://api.slack.com/apps → Create app (or pick an existing one).
  2. Under OAuth & Permissions → Scopes → Bot Token Scopes, add users:read. Do not add chat:write or anything else — least privilege.
  3. Install to workspace and copy the Bot User OAuth Token (starts with xoxb-).

Connect it in Measured Cloud​

  1. Open Settings → Integrations → Slack.
  2. Paste the xoxb- token. Optionally record the Slack workspace name for your own reference.
  3. Save. The token is encrypted at rest (AES-256-GCM under your organization's key) and is never shown again — the page only tells you whether a token is set.

Verify​

  1. Open (or create) an alert rule with the Slack channel. You need a role that can manage alerts (editor or above).
  2. In Mentions, start typing a colleague's name. A list of matching Slack members appears — pick one with the arrow keys + Enter, or click it. It becomes a chip showing their name; the × on the chip removes it.
  3. Save the rule, then open it again (or view it as a viewer): the mention still reads as the person's name.
  4. To mention a Slack user group, paste its ID (S…) into the field and choose Add … by ID. Groups aren't looked up — they show as the raw ID tagged "group" and are sent unchanged.

What stays the same​

  • The Slack ping is unchanged. The rule stores the member ID and the delivered message keeps the live <@U012ABCDEF> mention, so Slack still renders it as a real, notifying @-mention. Sending the plain-text name would break the ping — so we don't.
  • Group mentions (<!subteam^…>) aren't resolved yet. They pass through unchanged (that needs a different Slack scope, usergroups:read, planned separately).
  • No token? No problem. Without a bot token the Mentions field stays the original paste-an-ID field (comma-separated U… / S… IDs), with a Connect a Slack bot token hint. If a token is connected but can't list members — most often because it's missing users:read — the form says so and falls back to the same ID field. During a Slack outage, mentions simply show the raw ID. Alerts never fail because a name couldn't be looked up.

How it works (API)​

  • GET /api/v1/organizations/{org_id}/slack/users?q=<name>&limit=<n> — the picker's search (editor+, can_manage_alert; rate-limited per user). Returns {"data": [{id, name, real_name, handle}], "token_configured": bool, "error": <Slack error code or null>}. The member list is fetched from Slack page by page and cached for your organization for 5 minutes, so typing searches the cache rather than calling Slack on every keystroke; a newly added Slack member shows up within that window. Bots, deactivated accounts and Slackbot aren't offered.
  • POST /api/v1/organizations/{org_id}/slack/resolve-mentions {"ids": [...]} — turns stored member IDs into names for display (viewer+, can_view_alert; at most 100 IDs per call, more is a 422). Returns {"data": {<id>: <name or null>}, "token_configured": bool}. Names are cached per ID for SLACK_NAME_CACHE_TTL_SECONDS.
  • Neither endpoint ever returns or logs the bot token; a Slack failure comes back as an empty result (plus a Slack error code on the search), never a server error.