docs(TSP-1265): add account linking consent flow documentation for Slack and Teams integrations

[claude]

Summary

• Adds a new "Linking your account via magic link" section to both the Slack and Microsoft Teams integration pages, documenting the consent flow introduced in PR #15067
• Adds a Troubleshooting section to the Slack page (matching the Teams page structure) with two new entries covering magic link expiry and wrong email addresses
• Adds two troubleshooting entries to the Teams page for the same scenarios
• Adds three FAQ entries to each page covering: what the magic link is, whether it's required, and what happens if the user isn't logged in

Details

The new /associate consent page (PR #15067) shows users their Relevance AI account email and external account details, requiring explicit confirmation before linking. Both pages now explain:

• The magic link redirects unauthenticated users to sign in first, then returns them to the consent page
• The magic link flow and the standard OAuth flow achieve identical results
• Magic links are time-limited; the OAuth flow on the Integrations page is the fallback

Related

• Linear: https://linear.app/relevance/issue/TSP-1265/
• Implementation PR: #15067

Test plan

• Both pages render correctly in Mintlify preview
• New headings follow sentence case
• All <Note> callouts use correct syntax (no attributes)
• Internal anchor links are not broken

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
relevanceai	🟢 Ready	View Preview	Jun 1, 2026, 7:39 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[linear]

TSP-1265

[github-actions]

🎯 Vibe check

Reviewed: 2 files (2 with issues, 0 clean)

Scores

	Dimension	Score	What's holding it back
🔴	Consistency	4/10	slack.mdx has 6 heading case violations (Title Case used throughout Advanced Trigger Settings and subsections), British collective noun ("team are"), banned-word-adjacent "seamless" in the page description. microsoft-teams.mdx has 6 Step/Accordion titles where "agent" and "trigger" are lowercase despite being Relevance AI product terms.
🟡	Technical clarity	7/10	slack.mdx uses a raw URL instead of a link (line 13), and the <Tip> callout on lines 58–63 contains a nested numbered list (violates callout rules, breaks mobile rendering). Initial setup steps on the Slack page are a plain numbered list rather than <Steps>, making them harder to scan than the equivalent Teams page.
🟡	Non-technical clarity	6/10	slack.mdx opens with a defensive affiliation disclaimer before explaining what the integration does — new readers don't know the integration's purpose until they scroll past the note and a 7-step list. The page description uses "seamless communication" (marketing tone). The Teams page fares better: it has a clear single-sentence intro explaining what the integration enables.
🟡	Structure	6/10	slack.mdx places the new "Linking your account via magic link" section at ## level immediately after setup steps but before a demo video, breaking the flow. The equivalent section in Teams is nested as ### under Step 1 — the heading levels should align across both pages. microsoft-teams.mdx uses <CardGroup> for a checklist-style prerequisites section and for a 2-step sequential overview; both would read better as lists or <Steps>.

Score key: 🟢 9–10, 🟡 6–8, 🔴 1–5.

✨ Overall vibe: The Teams page is a solid, well-researched doc — the magic link additions fit naturally and the troubleshooting/FAQ coverage is thorough. The Slack page is showing its age: the new magic link content is clean, but the surrounding page has accumulated heading-case drift, a callout misuse, and structural rough edges that make the additions feel inconsistent. Both pages need a pass on "agent" and "trigger" capitalization before merge.

🔧 Issues (18)

• integrations/popular-integrations/slack.mdx:3 — "seamless communication" in the page description frontmatter. "seamless" is the adjective form of the banned word "seamlessly" and carries the same marketing tone. Rewrite: "enabling direct communication between your AI Workforce and your team's Slack workspace."
• integrations/popular-integrations/slack.mdx:8 — <Note>Note: This integration…</Note> — "Note:" is redundant inside a <Note> callout. Drop the prefix: start with "This integration for Slack was developed…"
• integrations/popular-integrations/slack.mdx:13 — Raw URL https://app.relevanceai.com appears as plain text. Use linked text: [Relevance AI](https://app.relevanceai.com) or just describe the step without a URL ("Go to the Relevance AI dashboard").
• integrations/popular-integrations/slack.mdx:39 — "The Relevance AI team are constantly making improvements" — British collective noun agreement. American English: "The Relevance AI team is constantly making improvements."
• integrations/popular-integrations/slack.mdx:86 — Heading ### Advanced Trigger Settings → sentence case: ### Advanced trigger settings ("Trigger" here is an adjective modifier, not a standalone product noun)
• integrations/popular-integrations/slack.mdx:88 — Heading #### Live Status Updates → #### Live status updates
• integrations/popular-integrations/slack.mdx:93 — Heading #### Exclude Keywords → #### Exclude keywords
• integrations/popular-integrations/slack.mdx:104 — Heading #### No Agent Reply → #### No Agent reply ("Agent" stays capitalized as a product term; "Reply" is not a proper noun)
• integrations/popular-integrations/slack.mdx:117 — Heading ### Customize Message Formatting → ### Customize message formatting
• integrations/popular-integrations/slack.mdx:143 — Heading ## Agent Notifications → ## Agent notifications
• integrations/popular-integrations/slack.mdx:240 — Accordion title "When I setup a Slack trigger, I can't find channels…" — two issues: "setup" (noun) → "set up" (verb); "trigger" → "Trigger" (Relevance AI product term). Corrected: "When I set up a Slack Trigger, I can't find channels in my workspace."
• integrations/popular-integrations/microsoft-teams.mdx:160 — Step title "Open your agent's settings" → "Open your Agent's settings" (Agent = product term)
• integrations/popular-integrations/microsoft-teams.mdx:163 — Step title "Add a Microsoft Teams trigger" → "Add a Microsoft Teams Trigger"
• integrations/popular-integrations/microsoft-teams.mdx:174 — Step title "Configure trigger conditions (optional)" → "Configure Trigger conditions (optional)"
• integrations/popular-integrations/microsoft-teams.mdx:178 — Step title "Write agent instructions" → "Write Agent instructions"
• integrations/popular-integrations/microsoft-teams.mdx:271 — Step title "Add an agent notification" → "Add an Agent notification"
• integrations/popular-integrations/microsoft-teams.mdx:384 — Accordion title "Teams trigger option not visible in agent settings" → capitalize both product terms: "Teams Trigger option not visible in Agent settings"
• integrations/popular-integrations/microsoft-teams.mdx:388 — Accordion title "Trigger is configured but the agent isn't responding" → "Trigger is configured but the Agent isn't responding"

🧩 Component suggestions (4)

• integrations/popular-integrations/slack.mdx:58–63 — <Tip> contains a numbered list with bold section labels. CLAUDE.md requires callouts to be a single short paragraph. The content is a before/after comparison of two setup paths, not tip-level guidance. Either flatten to one sentence ("Use /invite @Relevance AI for channels; for DMs, just send the bot any message.") or pull the content into a proper ### Channels vs. DMs subsection with a two-row table or two short paragraphs.
• integrations/popular-integrations/slack.mdx:11–19 — The initial OAuth setup is a plain numbered list while the equivalent setup on the Teams page uses <Steps>. Switching to <Steps> would give Slack the same visual progress indicators and make the pages consistent.
• integrations/popular-integrations/microsoft-teams.mdx:15–28 — <CardGroup> used for four prerequisite checklist items. Per CLAUDE.md, cards work for navigable items or parallel choices — prerequisites are neither. A bulleted list, or four <Check> callout-style lines, would better match the checklist intent and not mislead readers into expecting clickable cards.
• integrations/popular-integrations/microsoft-teams.mdx:34–41 — <CardGroup> with "1." and "2." prefixed card titles presents a mandatory two-step sequence as parallel choices. This undercuts the <Warning> on line 32 ("Both are required"). Replace with a simple numbered list or a <Steps> component to reinforce that the order matters.

🏗️ Page structure (3)

• integrations/popular-integrations/slack.mdx:21 — "## Linking your account via magic link" is a top-level ## section wedged between the initial setup steps and a demo video embed. The equivalent section in microsoft-teams.mdx is ### nested under Step 1. Align the heading levels across both pages — making it a ### subsection after the setup steps would also fix the flow disruption.
• integrations/popular-integrations/slack.mdx:7–12 — The page opens with a defensive affiliation <Note> before explaining what the integration does. Readers arriving from search or the sidebar don't know the integration's value until they've scrolled past the note and a 7-step list. Move the affiliation note to a ## Disclaimer section (already present at line 277) or after the intro, and lead with what the integration enables.
• integrations/popular-integrations/slack.mdx:124–129 — "## Escalate your Agent to Slack" opens with <Warning>This feature may be deprecated…</Warning>. Documenting a feature actively flagged for deprecation creates future maintenance debt and confuses readers about whether to rely on it. If deprecation is confirmed, remove the section or archive it behind an accordion with a clear legacy label; if it's not confirmed, remove the warning.

✅ Clean files (0)

Both files have issues.

🔋 Credit usage

Item	Count
Files reviewed	2
Context pages read	0
Total lines processed	~743

Files read: integrations/popular-integrations/microsoft-teams.mdx (448 lines), integrations/popular-integrations/slack.mdx (295 lines)

[jordanc-relevanceai]

Consolidated into #659 (Slack connection + auth docs: magic link + Builder/SuperGTM). Closing in favor of that PR.