MANUAL

What is the Discord Channel?

The Discord channel connects a Discord bot with Fararoni, allowing users to interact with your AI assistant through the Discord application, both in direct messages (DMs) and servers.

Architecture

+----------------+     +-----------------+     +----------------+     +----------------+
|   User         | --> |   Discord API   | --> |  Sidecar DC    | --> |   Fararoni     |
|   Discord      |     |   (Bot Gateway) |     |   (:3002)      |     |   Gateway      |
+----------------+     +-----------------+     +----------------+     |   (:7071)      |
                                                                      +----------------+
                                                                             |
                                                                             v
                                                                      +----------------+
                                                                      |  LLM Agents    |
                                                                      +----------------+

Discord Advantages

Channel Comparison

Required Software

• Node.js 18 or higher
• npm (comes with Node.js)
• Fararoni Core installed
• Java 25+ with --enable-preview

Accounts

• Discord account
• Access to Discord Developer Portal

Ports

# Verify Node.js (must be 18+)
node --version

# Verify npm
npm --version

# Verify Java
java --version

# Verify Fararoni is running
curl http://localhost:7071/gateway/v1/health

Step 3.1: Access Developer Portal

1. Open your browser
2. Go to: https://discord.com/developers/applications
3. Log in with your Discord account
4. Click "New Application" (blue button, top right)

Step 3.2: Create the Application

1. Enter a name (e.g.: Fararoni Bot)
2. Accept the terms of service
3. Click "Create"

Step 3.3: Create the Bot

1. In the left sidebar, click "Bot"
2. Click "Add Bot"
3. Confirm by clicking "Yes, do it!"

Step 3.4: Configure Intents (VERY IMPORTANT)

On the Bot page, scroll to "Privileged Gateway Intents" and enable:

• MESSAGE CONTENT INTENT (REQUIRED)
• PRESENCE INTENT (optional)
• SERVER MEMBERS INTENT (optional)

CRITICAL: Without "Message Content Intent", the bot will receive EMPTY messages.

Click "Save Changes".

Step 3.5: Get the Token

1. In the "Bot" section, find "Token"
2. Click "Reset Token" or "Copy"
3. SAVE THIS TOKEN securely

WARNING: Never share your token. If exposed, regenerate it immediately in the Developer Portal.

Step 3.6: Invite Bot to Server

1. In the sidebar, click "OAuth2" -> "URL Generator"
2. In "SCOPES", select: bot
3. In "BOT PERMISSIONS": Send Messages, Read Message History, View Channels
4. Copy the generated URL, open it in your browser
5. Select the server and click "Authorize"

cd fararoni-sidecar-discord
npm install

This will install: discord.js, express, axios, dotenv

Create Configuration File

cp .env.example .env
nano .env

Configure Variables

# Discord bot token (REQUIRED)
DISCORD_TOKEN=MTIzNDU2Nzg5MDEyMzQ1Njc4OQ.GrWvSg.your_token_here

# Fararoni REST Gateway URL
GATEWAY_URL=http://localhost:7071/gateway/v1/inbound

# HTTP server port for Egress
SIDECAR_PORT=3002

# Allow server messages (requires bot mention)
ALLOW_GUILDS=false

# Allowed user IDs (comma-separated)
ALLOWED_USERS=

# Debug mode
DEBUG=false

Verify in ~/.fararoni/config/modules.yml:

gateway:
  rest:
    enabled: true
    port: 7071

channels:
  discord:
    enabled: true
    egress_url: "http://localhost:3002/send"

Prerequisites

• Create bot in Discord Developer Portal (Section 3)
• Enable MESSAGE CONTENT INTENT (Step 3.4)
• Get and save token in .env (Step 3.5)
• Install dependencies with npm install (Section 4)

Step 6.1: Start Fararoni Gateway

# Terminal 1: Fararoni Core
cd /path/to/fararoni
./start-server.sh

Step 6.2: Start Discord Sidecar

# Terminal 2: Discord Sidecar
cd fararoni-sidecar-discord
npm start

Expected Output

============================================================
  FARARONI SIDECAR - DISCORD (PHASE 71.6)
============================================================

[INFO]  12:34:56 [HTTP] Egress Server on port 3002
[INFO]  12:34:57 [DISCORD] Bot connected: FararoniBot#1234
[INFO]  12:34:57 [DISCORD] Servers: 2
[INFO]  12:34:57 [GATEWAY] Sending to: http://localhost:7071/gateway/v1/inbound
[INFO]  12:34:57 [SECURITY] DMs only (direct messages)
[INFO]  12:34:57 [READY] Sidecar ready to receive messages

------------------------------------------------------------

Invite Bot to a Server

IMPORTANT: You can't search for a new bot on Discord if you don't share a server with it. First invite the bot to a server.

1. Open Discord and create a test server (button +)
2. Go to Developer Portal → your app → "OAuth2" → "URL Generator"
3. In SCOPES check bot; in BOT PERMISSIONS check Send Messages, Read Message History, View Channels
4. Copy the URL, open it, select your server and authorize

Direct Message (DM) Test

IMPORTANT: Open a private conversation (DM) with the bot, don't write in the server channel.

1. In the members panel, find your bot with the "BOT" badge
2. Right-click → "Message"
3. Type: Hello and press Enter

Verify in Terminal

[INFO]  15:45:xx [INGRESS] YourUser (DM) -> "Hello" (HTTP 202)
[INFO]  15:45:xx [EGRESS] 123456789 <- "Hello! How can I help you?"

DMs on Discord

"First Contact" Rule: Discord doesn't allow DMs to a bot without sharing a server. Use the server as a temporary bridge. Once the DM is created, access it from the Discord icon (Home) → Direct Messages.

Health Check

curl http://localhost:3002/health

{
  "status": "healthy",
  "service": "fararoni-sidecar-discord",
  "channel": "discord",
  "port": 3002,
  "bot": {
    "id": "123456789012345678",
    "username": "FararoniBot",
    "tag": "FararoniBot#1234"
  }
}

DM Mode (Default)

Bot ONLY responds to direct messages.

# .env
ALLOW_GUILDS=false

DM + Servers Mode (with Mention)

Bot responds to DMs and server messages only when mentioned.

# .env
ALLOW_GUILDS=true

Restricted Mode (Allowlist)

# .env
ALLOWED_USERS=123456789012345678,987654321098765432

How to get your User ID:

1. Discord → Settings → Advanced
2. Enable "Developer Mode"
3. Right-click any user → "Copy ID"

Token Protection

NEVER: Push token to GitHub, share in chats, include in source code.

ALWAYS: Use .env files (in .gitignore), regenerate if exposed, use environment variables in production.

Security Filters

Regenerate Compromised Token

1. Go to https://discord.com/developers/applications
2. Select your app → "Bot" → "Reset Token"
3. Update .env and restart the sidecar

Error: "TOKEN_INVALID"

Cause: Incorrect or regenerated token. Fix: Copy correct token from Developer Portal, update .env and restart.

Error: "Used disallowed intents"

1. Developer Portal → your app → "Bot"
2. Enable MESSAGE CONTENT INTENT
3. Click "Save Changes" and restart sidecar

Error: "ECONNREFUSED" to Gateway

# Verify Gateway
curl http://localhost:7071/gateway/v1/health

# If no response, start Fararoni
./start-server.sh

Bot doesn't respond in servers

Set ALLOW_GUILDS=true in .env, restart and mention the bot: @FararoniBot hello.

Port 3002 busy (EADDRINUSE)

lsof -i :3002
kill -9 <PID>
# Or change port: SIDECAR_PORT=3003

# Normal start
npm start

# Debug mode
npm run dev

# Health check
curl http://localhost:3002/health

# Detailed status
curl http://localhost:3002/status

# View logs
npm start 2>&1 | tee discord.log

# Kill process
pkill -f "fararoni-sidecar-discord"

Project Structure

fararoni-sidecar-discord/
├── index.js          # Main sidecar code
├── package.json      # Dependencies and scripts
├── .env.example      # Configuration template
├── .env              # Local config (don't push to git)
└── node_modules/     # Installed dependencies

Message Flow

1. User sends "Hello" via Discord DM
2. Discord API notifies bot (WebSocket)
3. Sidecar receives messageCreate event
4. Security filters validate the message
5. Sidecar sends POST to Gateway (:7071/gateway/v1/inbound)
6. Gateway publishes to SovereignEventBus
7. OmniChannelRouter routes to agent
8. Agent generates response with LLM
9. Gateway sends POST to Sidecar (:3002/send)
10. Sidecar sends response to Discord API
11. User sees the response in Discord

UniversalMessage Schema

{
  "messageId": "dc-1234567890",
  "channelId": "discord",
  "senderId": "1234567890123456789",
  "conversationId": "dm",
  "type": "TEXT",
  "textContent": "Hello, how are you?",
  "metadata": {
    "profileName": "User123",
    "globalName": "User",
    "discriminator": "1234",
    "userId": "9876543210987654321",
    "isDM": true,
    "guildName": null
  },
  "timestamp": "2026-02-20T12:34:56.789Z"
}

Generated for PHASE 71.6 - Fararoni Discord Sidecar