Discord bot

The Caedral Discord bot is open source and self-hosted. You run it on your own infrastructure with your Discord application, a dedicated Postgres for tickets, and a Caedral API key. The bot registers with Caedral via heartbeat every 60 seconds. Ticket AI uses POST /v1/chat/completions on the same key — embed, rerank, and chat draw from your subscription usage pools.

#What you get

• Support tickets with AI assistant (local FAQ knowledge base + Caedral chat)
• Slash commands: docs, pricing, status, announcements (owner)
• Remote control from Dashboard → Discord Bots (enable/disable, rename, chat model, custom system prompt)
• Per-bot uptime and heartbeat history (not on the public /status page)
• Automatic Caedral changelog posts to your #updates and log channels

#Source repository

The bot lives in a dedicated public repository (not the Caedral platform monorepo): github.com/trycaedral/discord-bot — MIT licensed, includes the bot app and @caedral/knowledge package for ticket RAG.

#Requirements

• Caedral account with verified email
• API key from /dashboard/api-keys (cd_live_…)
• Active subscription for ticket AI usage (/dashboard/billing)
• Discord application with bot token and Message Content intent
• Docker (recommended) or Node.js 20+

#Quick setup (Docker)

1. Clone github.com/trycaedral/discord-bot and copy .env.example to .env
2. Set CAEDRAL_API_KEY, CAEDRAL_ASSISTANT_MODEL, DISCORD_BOT_TOKEN, DISCORD_CLIENT_ID, and channel IDs
3. From the repo root: docker compose up -d --build
4. Invite the bot to your server and run /setup-tickets (owner only)
5. Open /dashboard/bots — your instance appears after the first heartbeat

1git clone https://github.com/trycaedral/discord-bot.git caedral-discord-bot2cd caedral-discord-bot3cp .env.example .env4# edit .env5 6docker compose up -d --build7docker compose logs -f discord-bot

#Environment variables

#Knowledge base (first boot)

The bundled Postgres stores tickets and knowledge_chunks. On first boot, if the knowledge table is empty, the bot ingests the bundled Caedral FAQ (KNOWLEDGE_BASE.md) via Caedral Embed. Re-run with npm run knowledge:ingest inside the container. Set KNOWLEDGE_AUTO_INGEST=0 to disable auto-ingest.

#Changelog delivery

When Caedral publishes a changelog on caedral.com/changelog, a broadcast is queued for every registered bot. On the next heartbeat (~60s), your bot posts the entry to DISCORD_UPDATES_CHANNEL_ID and your log channel (DISCORD_CHANGELOG_LOG_CHANNEL_ID or DISCORD_TICKET_LOG_CHANNEL_ID). No inbound connection from Caedral to your VPS is required.

#Choosing a chat model

Set CAEDRAL_ASSISTANT_MODEL to a Caedral catalog chat model id: deepseek/deepseek-v4-flash, anthropic/claude-haiku-4.5, anthropic/claude-sonnet-4.5, or anthropic/claude-opus-5. You can also choose the model remotely in Dashboard → Discord Bots → Chat model (applied on the next heartbeat). If the model is invalid or included usage is exhausted, the bot posts a clear message in the ticket.

#Dashboard control

At /dashboard/bots you can monitor uptime (24h / 7d / 30d), view heartbeat history, see connected Discord servers, disable the bot remotely (stops within ~60s), rename the instance, set the chat model, and push a custom system prompt applied on the next heartbeat.

#Local development

Set CAEDRAL_BOT_ALLOW_UNREGISTERED=1 to skip platform registration when testing Discord flows locally. AI still requires CAEDRAL_API_KEY. Point GATEWAY_URL at a local api-gateway only for development — production self-hosted bots use https://api.caedral.com.