Module 6: Real-World Integrations — Slack/Discord

Introduction to Real-World Integrations — Slack/Discord

Lesson overview

Phase 2 gave you integration patterns (M4) and reliability (M5) in the abstract: generic webhooks, conceptual queues, theoretical circuit breakers. This module lands it all on real production channels: Slack and Discord. The reason is strategic — the Capstone of the AI Engineering Path is an AI-Powered Knowledge Assistant that integrates with one or both channels. Without understanding how their APIs, their constraints, and their authentication patterns work, you can't design the Capstone architecture in M8.

Slack and Discord are not nice-to-have in 2026 AI systems — they are production channels. Most AI assistants in companies are accessed via Slack: the user writes in a channel, the bot processes with RAG, responds in the thread. Discord is the equivalent for communities and technical teams. Designing the integration requires specific knowledge:

Slack uses the Events API (HTTP webhooks) with a 3-second timeout for acknowledgment
Discord uses the Gateway (WebSocket) for real-time events with a different model
Both have aggressive rate limits: Slack ~1 msg/second per channel, Discord more permissive but with limited bursts
OAuth flows are different: Slack per workspace, Discord per server (guild)

This module is the most tangible in the guide. You can open Slack or Discord while you read and verify every concept. By the end, you'll have a Slack/Discord Bot Design Document that becomes the integration layer of the Capstone Architecture Design in M8.

By the end of the module you'll be able to:

Design the Slack API integration: Events API, Web API, Webhooks (outbound), request → processing → response flow
Design the Discord API integration: bot tokens, slash commands, interactions endpoint, message components
Plan OAuth 2.0 flows: scopes, token storage, refresh, multi-tenant
Design the integration architecture: separation between channel-specific logic and AI logic
Handle specific constraints: timeouts, rate limits, message formats
Choose Slack vs Discord vs both for your case with justified criteria

Where are we?

Phase 1: Architectural Foundations ✅
Phase 2: Integration & Patterns (Modules 4-6)
  └── Module 4: Integration Patterns ✅
  └── Module 5: Reliability at Scale ✅
  └── Module 6: Slack/Discord Integrations ← YOU ARE HERE

Phase 3: Trade-offs & Capstone Prep (Modules 7-8)

M6 closes Phase 2. It applies the abstract patterns of M4-M5 to concrete channels. After M6, you'll have designed the external pieces of the system (how it receives input, how it responds). M7 will give you the trade-off frameworks, and M8 will bring it all together in the Capstone Architecture Design.

Mental model: typical architecture

   ┌─────────────┐     ┌──────────────┐     ┌─────────────┐
   │    User     │     │              │     │ AI Service  │
   │  in Slack   │────▶│  API Gateway │────▶│  (RAG+LLM)  │
   │  /Discord   │     │              │     │             │
   └─────────────┘     └──────┬───────┘     └─────────────┘
         ▲                    │
         │                    ▼
         │            ┌───────────────┐
         │            │ Channel Logic │
         │            │ (Slack/Discord│
         │            │   adapter)    │
         │            └───────┬───────┘
         │                    │
         └────────────────────┘
              response

Key insight: the architecture has two separate layers:

Channel Logic: parses Slack/Discord events, authenticates, translates to your internal format. Changes if you add another channel.
AI Service: RAG + LLM + agent. Knows nothing about Slack/Discord. Receives your internal format, returns a response.

This separation is what lets you add Teams, Telegram, or web chat later without rewriting the AI service.

Module map

Lesson	Topic	Output
01	Introduction (this one)	Mental model, Slack/Discord decision
02	Slack Events API and Web API	How Slack sends events, how you respond
03	Discord Gateway and slash commands	Discord's model, differences with Slack
04	OAuth 2.0 for bots	Authorization flow, multi-tenant
05	Rate limits and timeouts per platform	Slack's 3s budget, specific rate limits
06	Rich message formatting	Block Kit (Slack), Embeds + Components (Discord)
07	Slack/Discord/both decision framework	Criteria for choosing
08	Project: Slack/Discord Bot Design Doc	Complete integration specification

A scenario that illustrates the module

An 80-person startup wants an internal AI assistant that answers questions from its knowledge base. The natural preference: Slack, because everyone already uses it.

The engineering team starts designing. Questions arise:

How does the bot receive a message? → Slack Events API → needs a public endpoint + verification
In what time must it respond? → 3 seconds to acknowledge, then it can continue async
But the LLM takes 8 seconds? → they need a queue (M5-03) — immediate acknowledge, late response
How does it send the response? → Slack's Web API (chat.postMessage) — but it has a rate limit
How does it get installed in the workspace? → OAuth flow — an admin user authorizes it
And if the sister company wants to use it too? → multi-tenant OAuth — one codebase, several workspaces

Each of those questions is answered with a specific Slack pattern you'll learn in this module. Without this knowledge, the team improvises, does three iterations, discovers constraints after implementing, refactors painfully.

With this module, the team designs before coding and the implementation runs smoothly.

Slack vs Discord: fundamental differences

To get off on the right foot, the key differences:

Dimension	Slack	Discord
Main API	Events API (HTTP webhooks)	Gateway (WebSocket) + Interactions API (HTTP)
Event model	Push: Slack calls your endpoint	Pull: your bot keeps a WS connection open
Acknowledgment timeout	3 seconds	~3 seconds for interactions
Rate limits	~1 msg/second per channel	More permissive, but with limited bursts
Rich messages	Block Kit (structured JSON)	Embeds + Components (similar but different)
OAuth scope	Workspace	Server (guild)
Main client	Companies, professional teams	Communities, gaming, devs
Workspace cost	Paid (the serious features)	Free (with optional boosts)
DM support	✅ but with special permissions	✅
Threads	✅ first-class	✅ first-class
App distribution	Slack Marketplace + private installs	Discord Application Directory + direct invite

Key implication: Slack and Discord are not interchangeable. Designing for one doesn't give you the other for free. Your channel logic will be specific, even if the AI service behind it is the same.

Common traps while taking the module

Trap 1 — "I'm going to write a step-by-step tutorial on how to build a bot." No. This guide is about design, not implementation. The code goes in the Capstone. Here you design the architecture, the flows, the decisions — you don't type bot code.

Trap 2 — "Slack and Discord are interchangeable." Fundamentally different APIs. You'll see it in M6-02 and M6-03.

Trap 3 — "I'll ignore the 3-second timeout until I implement." The timeout is the main motivator of your architecture decision. Without understanding it, you'll design badly. We address it in M6-02 right away.

Trap 4 — "OAuth is technical config, not a design decision." OAuth has architectural implications: where do you store tokens? How do you handle refresh? Multi-tenant or single? We address it in M6-04.

Trap 5 — "My architecture assumes single-tenant." If you plan to sell your bot to multiple companies, multi-tenant is mandatory. Design with that in mind from the start.

Self-assessment question

Before moving on to M6-02:

Why are Slack and Discord not interchangeable even though both are "chat platforms"?
If Slack gives you 3 seconds to respond and your LLM takes 10, how do you solve it?
Your bot is going to be installed in 50 different workspaces. How do you handle the OAuth tokens?

Guide answers

Different APIs: Slack push (HTTP webhooks) vs Discord pull (WebSocket Gateway). A different event model requires different infrastructure. Slack is ideal for companies; Discord for communities. Each with its own scopes, rate limits, formats.
Async queue: the API receives the event, responds 200 OK immediately (meets the 3s budget), enqueues the processing. A background worker makes the LLM call (10s) and sends the response via the Web API to Slack when it finishes. The user sees "..." while it processes and the response when it arrives.
Multi-tenant: each workspace has its own access token. Your DB needs an installations(workspace_id, access_token, scopes, installed_at) table. When you receive an event, look up the corresponding token. You handle refresh if the provider expires them. You encrypt tokens at rest.

Evidence of success by the end of the module

You'll know you finished well if:

✅ You can explain the end-to-end flow from "user writes in Slack" to "user receives response"
✅ You know when to choose Slack vs Discord vs both with justified reasons
✅ You've designed the OAuth flow for multi-tenant
✅ You know how to handle the 3s timeout and each platform's rate limits
✅ You deliver a Slack/Discord Bot Design Document that the Capstone can use directly

Next lesson

02 — Slack Events API and Web API. We start with Slack because it's the most common case in companies. You'll understand how Slack sends events to your system, how you respond with the Web API, and why the 3-second timeout defines your entire architecture.

Resources

Slack API Documentation — official reference.
Discord Developer Portal — official reference.
Slack vs Discord for Bots — comparison — Slack overview.
Bolt for Python (Slack SDK) — Slack's official framework.
discord.py — Python library for Discord.

← PreviousProject: Reliability Design Document Next →Slack Events API and Web API