featuredImage: /assets/integrate-apis-part-3.png

Integrating AI Agents with External APIs - Part 3: Discord Integration

Slack covers internal comms; Discord is where your AI agent meets customers and community advocates. This chapter adapts the Escalation Concierge to community servers so gamers, partners, or beta users can see incident context, submit reports, and escalate without leaving Discord.

Scenario: Community Signal Corps

You run a public beta server. The agent must:

• Stream critical incident summaries into specific channels with embeds.
• Accept slash command reports that attach screenshots and metadata.
• Moderate spam or unsafe prompts before they hit the channel.
• Stay online even when Discord shuffles gateway connections or rate limits.

We will follow five sections that parallel the Slack article but respect Discord's guild, intent, and interaction model.

---

Section 1: Architecture and Intent Planning

Discord bots need the right gateway intents plus channel design before deployment.

Decision	Options	Guidance
Intents	GUILDS, GUILD_MESSAGES, MESSAGE_CONTENT, GUILD_MEMBERS	Enable only what you need; MESSAGE_CONTENT requires approval above 100 servers.
Deployment	Single process, clustered, sharded	Shard once you exceed 2,500 guilds or ~1,000 concurrent events per second.
Channel strategy	Incident feed, triage threads, DM concierge	Use forum channels for structured reports and keep incident feeds read only.
Permission model	Role based, channel overrides	Grant the bot a dedicated role above any role it must manage; avoid Administrator when possible.
Presence	Invisible, online, custom status	Set presence to reflect system health (e.g., "Watching incident queue").

Document approved intents in your security review. Discord will disable bots that request sensitive intents without justification.

---

Section 2: Authenticate and Connect to the Gateway

Discord uses bot tokens plus optional public key verification for interactions. Reuse the vault + rotation strategy from Part 1.

Node.js (discord.js v14)

// discord/gateway.js
import { Client, GatewayIntentBits, Partials, Events } from "discord.js";
import { trackAuthEvent } from "../observability/instrumentation.js";

export function bootstrapDiscord() {
  const client = new Client({
    intents: [
      GatewayIntentBits.Guilds,
      GatewayIntentBits.GuildMessages,
      GatewayIntentBits.MessageContent
    ],
    partials: [Partials.Channel]
  });

  client.once(Events.ClientReady, (readyClient) => {
    trackAuthEvent("discord_ready", {
      user: readyClient.user.tag,
      guilds: readyClient.guilds.cache.size
    });
  });

  client.login(process.env.DISCORD_BOT_TOKEN);
  return client;
}

Python (discord.py 2.x)

# discord/gateway.py
import os
import logging
import discord

logging.basicConfig(level=logging.INFO)

intents = discord.Intents.default()
intents.message_content = True
intents.members = False

client = discord.Client(intents=intents)

@client.event
async def on_ready():
    logging.info("Discord bot ready as %s", client.user)
    logging.info("Connected guilds: %d", len(client.guilds))

def start_gateway():
    client.run(os.environ["DISCORD_BOT_TOKEN"])

Checklist before you go live:

1. Store bot token + public key in your secret manager.
2. Restrict who can invite the bot by gating the OAuth2 URL behind your internal dashboard.
3. Monitor reconnect loops; excessive reconnects often mean invalid intents or permissions.

---

Section 3: Commands, Embeds, and Threads

Slash commands keep UX predictable. We will deploy them via REST and pair them with rich embeds so communities can skim incident context.

Node.js command deploy + handler

// discord/commands/register.js
import { REST, Routes, SlashCommandBuilder } from "discord.js";

const commands = [
  new SlashCommandBuilder()
    .setName("incident")
    .setDescription("Show live incident summary")
    .addStringOption((option) =>
      option.setName("id").setDescription("Incident ID").setRequired(true)
    )
    .toJSON(),
  new SlashCommandBuilder()
    .setName("report")
    .setDescription("Submit a community report")
    .addAttachmentOption((option) => option.setName("screenshot").setRequired(false))
    .toJSON()
];

const rest = new REST({ version: "10" }).setToken(process.env.DISCORD_BOT_TOKEN);
await rest.put(
  Routes.applicationCommands(process.env.DISCORD_APP_ID),
  { body: commands }
);

// discord/handlers/incident.js
import { EmbedBuilder } from "discord.js";
import { fetchIncidentSummary } from "../services/crm.js";

export async function handleIncident(interaction) {
  await interaction.deferReply({ ephemeral: true });
  const incidentId = interaction.options.getString("id");
  const summary = await fetchIncidentSummary(incidentId);

  const embed = new EmbedBuilder()
    .setTitle(`Incident #${incidentId}`)
    .setDescription(summary.description)
    .setColor(summary.status === "resolved" ? 0x57f287 : 0xed4245)
    .addFields(summary.toFields())
    .setTimestamp();

  await interaction.editReply({ embeds: [embed] });
}

Python interactions (discord.py app commands)

# discord/handlers/incident.py
import discord
from services.crm import fetch_incident_summary

class Incident(discord.app_commands.CommandTree):
    def __init__(self, client):
        super().__init__(client)
        @self.command(name="incident", description="Show incident summary")
        async def incident(interaction: discord.Interaction, id: str):
            await interaction.response.defer(ephemeral=True)
            summary = await fetch_incident_summary(id)
            embed = discord.Embed(
                title=f"Incident #{id}",
                description=summary["description"],
                color=0x57F287 if summary["status"] == "resolved" else 0xED4245
            )
            for field in summary["fields"]:
                embed.add_field(name=field["name"], value=field["value"], inline=False)
            await interaction.followup.send(embed=embed, ephemeral=True)

Guidelines:

1. Always deferReply if fetching external data; Discord expects an initial response within 3 seconds.
2. Use ephemeral replies for sensitive data; send public embeds only after redacting PII.
3. Threads are ideal for long-running investigations. Use interaction.channel.create_thread to keep channels tidy.

---

Section 4: Moderation, Rate Limits, and Safety Nets

Discord communities move fast. Build moderation and quota protections into your agent rather than bolting them on later.

Node.js content filter + rate limit guard

// discord/moderation.js
import FastPriorityQueue from "fastpriorityqueue";

const riskTerms = [/credential/i, /leak/i, /ddos/i];
const queue = new FastPriorityQueue((a, b) => a.timestamp < b.timestamp);

export function shouldFlag(message) {
  return riskTerms.some((regex) => regex.test(message.content));
}

export function track(message) {
  queue.add({ channel: message.channelId, timestamp: Date.now() });
  cleanup();
}

function cleanup() {
  const cutoff = Date.now() - 15000;
  while (!queue.isEmpty() && queue.peek().timestamp < cutoff) {
    queue.poll();
  }
}

export function breached(channelId, threshold = 20) {
  return queue.toArray().filter((entry) => entry.channel === channelId).length > threshold;
}

client.on(Events.MessageCreate, async (message) => {
  if (message.author.bot) return;
  track(message);
  if (breached(message.channelId)) {
    await message.channel.send("Slow down, the bridge is throttling responses.");
    return;
  }
  if (shouldFlag(message)) {
    await message.delete();
    await message.channel.send("Message removed pending review.");
  }
});

Python automod hook

# discord/moderation.py
from collections import deque
from datetime import datetime, timedelta

WINDOW = timedelta(seconds=15)
MAX_MESSAGES = 20
recent = deque()
banned_terms = ["credential", "leak", "ddos"]

async def handle_message(message):
    if message.author.bot:
        return
    now = datetime.utcnow()
    recent.append((now, message.channel.id))
    while recent and now - recent[0][0] > WINDOW:
        recent.popleft()
    channel_hits = sum(1 for ts, cid in recent if cid == message.channel.id)
    if channel_hits > MAX_MESSAGES:
        await message.channel.send("Channel is rate limited by the agent.")
        return
    lowered = message.content.lower()
    if any(term in lowered for term in banned_terms):
        await message.delete()
        await message.channel.send("Removed message pending moderator review.")

Safety checklist:

1. Log every deletion with user id and moderator reference.
2. Respect Discord rate limits: the global bucket is ~50 req/sec per bot, but channel-specific limits vary.
3. Use per-guild configuration to let community managers set their own thresholds.

---

Section 5: Observability and Deployment

Discord bots maintain persistent gateways, so failures often show up as reconnect storms or missing heartbeats.

Node.js heartbeat monitor

// observability/discord-heartbeat.js
export function attachHeartbeat(client) {
  client.ws.on("heartbeat", (latency) => {
    console.log(JSON.stringify({ event: "discord_heartbeat", latency }));
  });

  client.ws.on("close", (code) => {
    console.error(JSON.stringify({ event: "discord_ws_close", code }));
  });
}

Python metrics exporter

# observability/metrics.py
import asyncio
from prometheus_client import Gauge, start_http_server

guilds_gauge = Gauge("discord_guilds", "Guilds connected")
latency_gauge = Gauge("discord_latency_ms", "WebSocket latency in ms")

def start_metrics(client, port=9105):
    start_http_server(port)
    async def update_metrics():
        while True:
            guilds_gauge.set(len(client.guilds))
            latency_gauge.set(client.latency * 1000)
            await asyncio.sleep(10)
    client.loop.create_task(update_metrics())

Deployment guidance:

1. Run the bot inside a process manager (PM2, systemd, supervisord) or container orchestrator.
2. Store command definitions in code and redeploy when you change scopes so your infra can track drift.
3. Build a runbook covering token rotation, intent approvals, shard scaling, and how to replay missed interactions.

---

Implementation Checklist

• Confirm required intents, channel plan, and permission model for each guild.
• Deploy the gateway service (Node or Python) with vault-managed secrets and auto restarts.
• Register slash commands plus interaction handlers with 3-second defer logic.
• Add moderation hooks, rate limiting, and per-guild config storage.
• Attach heartbeat/metrics exporters and document incident response procedures for Discord outages.

Part 4 moves to Zapier so the same Escalation Concierge can trigger finance or ops systems without custom code. Keep the shared auth, rate limiting, and observability modules close; we will reuse them again.