DashCord

<p align="center"> <img src="docs/logo.png" width="180" alt="DashCord Logo"> </p> <h1 align="center">DashCord</h1> <p align="center"> <strong>The headless Discord-to-automation bridge.</strong><br> Turn Discord into a persistent UI for your home lab, n8n, and Make pipelines. </p> <p align="center"> <img src="https://img.shields.io/github/v/release/nextgearslab/DashCord?color=blue&style=flat-square" alt="Latest Release"> <img src="https://img.shields.io/github/license/nextgearslab/DashCord?color=orange&style=flat-square" alt="License"> <img src="https://img.shields.io/github/stars/nextgearslab/DashCord?style=flat-square" alt="Stars"> </p>

---

DashCord is a highly flexible, configuration-driven Discord bot that translates chat commands, file uploads, and interactive UI panels (buttons) into HTTP webhook requests.

Originally built for n8n, this bot works flawlessly with Make (Integromat), Zapier, Node-RED, or any custom API.

Instead of hardcoding new Discord commands every time you want to automate something, you simply define them in a routes.json file. The bot acts as a universal headless bridge between Discord and your automation platform.

| 🎛️ Interactive UI Panels | 📁 Advanced File Handling (TTS) | | :--- | :--- | | | | | 📊 System Automation Logs | 🏃 Manual Chat Commands | | | |

❓ Why use DashCord?

While platforms like n8n and Node-RED have native Discord nodes, they are often difficult to use for advanced UI management. DashCord acts as a specialized middleware that solves three specific pain points:

1. Persistent UI: Keeping button panels at the bottom of a busy chat (Sticky UI) is handled by the bot, not your workflow.
2. Binary Pipelines: Automatically converts multi-file uploads into Base64 and "fans them out" so your workflow only has to process one file at a time.
3. Clean Workflows: Keeps your automation canvas focused on logic rather than managing Discord API states and message IDs.

✨ Features

• ⚡ Dynamic Commands: Add new slash-free commands (e.g., !weather, !deploy) just by editing a JSON file.
• 🎛️ Sticky Dashboard Panels: Generate persistent UI button panels in specific channels. The bot can automatically "persist" these panels, moving them to the bottom of the chat so they never get buried. Users can click buttons to trigger workflows without typing.
• 📁 Intelligent File Fan-out: Forward files directly to your webhooks. Can auto-parse JSON attachments, convert to Base64, and dynamically fan-out requests (upload 5 files, it triggers 5 separate webhook calls).
• 🎭 Dynamic Body Templating: Inject Discord metadata (like {{discord.user_display}} or {{discord.channel_id}}) directly into the JSON payload sent to your webhook, molding the data to fit your API perfectly.
• 🔒 Security Built-In: Restrict specific commands to specific Discord channels or user IDs. Secures outbound requests with a custom X-DashCord-Token header.
• 💬 Native Discord Replies: Your webhook can respond with JSON containing plain text or rich Discord Embeds, and the bot will cleanly post it back to the channel.
• 👁️ Visual Status Indicators: Real-time emoji reactions (⏳, ✅, ❌) let users know exactly when a command is processing, succeeded, or failed without needing extra text replies.

---

🚀 Quick Start (Docker)

1. Clone the repository:

git clone https://github.com/nextgearslab/DashCord.git
cd DashCord

2. Setup Configuration:

cp .env.example .env
cp routes.json.example routes.json

3. Open .env and add your Discord Bot Token.

4. Configure your commands and endpoints in routes.json.

5. Run it (using the Docker Compose wrapper):

chmod +x start.sh
./start.sh

(To view live logs, simply run ./logs.sh)

⚠️ CRITICAL SETUP STEP: Because this bot reads chat commands (!weather), you must enable the Message Content Intent. Go to the Discord Developer Portal -> Your Bot -> Bot tab -> Scroll down to Privileged Gateway Intents -> Turn ON Message Content Intent.

---

⚙️ Configuration File (routes.json)

All routing logic is driven by routes.json. It has two main sections: commands and panels.

1. Defining a Command

Commands map a typed Discord message to a webhook URL.

"commands": {
  "ping": {
    "endpoint": "https://your-automation-tool.com/webhook/ping",
    "method": "POST",
    "allowed_users": ["1234567890"],
    "allowed_channels":[]
  }
}

Typing !ping test will send a POST request containing the arguments to that webhook. Because allowed_users has an ID, only that Discord user can trigger it.

💡 Note on Case Sensitivity Commands are case-insensitive for the end user (they can type !PING or !Ping). However, you must define the command keys in routes.json in all lowercase (e.g., "ping", not "Ping").

❓ Smart Help If a user types a command that doesn't exist, DashCord will automatically reply with a list of commands that the user actually has permission to use in that specific channel.

• Supported Methods: Both "POST" and "GET" are supported.
• GET Requests: If you choose GET, the entire JSON payload is stringified and passed as a URL query parameter (e.g., ?payload={"source":"discord", ...}).

2. Defining File Uploads

You can allow commands to accept attachments, or even fire automatically when a specific filetype is uploaded without a command at all.

"upload": {
  "endpoint": "https://your-webhook...",
  "method": "POST",
  "accept_attachments": true,
  "allow_without_command": true,
  "attachment_rules": {
    "extensions":[".json", ".csv"],
    "max_bytes": 2500000,
    "require_json": false
  }
}

💡 The "Fan-out" Rule DashCord handles multiple file uploads intelligently. If a user uploads 5 files at once, the bot will "fan-out" and trigger 5 separate webhook calls (one for each file). This makes it much easier to build your n8n/Make workflows, as you only ever have to handle one file at a time in your automation logic!

🎭 Attachment Feedback You can control how the bot replies to uploads using the attachment_reply block.

• mode: Set to "errors" (default) to only reply if something goes wrong, "always" to always confirm, or "none" for silence.
• success_template / error_template: Use {ok}, {bad}, and {total} as variables to customize the message.

3. Designing Interactive UI Panels

Panels create persistent messages with buttons. You can bind specific commands and background arguments to each button.

"panels": {
  "Server_Controls": {
    "channels":["1029384756"],
    "buttons":[
      {
        "label": "Restart Server",
        "command": "ping",
        "args": ["restart"],
        "style": "danger"
      },
      {
        "label": "Check Status",
        "command": "ping",
        "args": ["status"],
        "style": "primary"
      }
    ]
  }
}

Button Styles Available: | Style Name | Discord Color | Best Used For | | :--- | :--- | :--- | | primary | Blurple (Blue) | Main actions | | secondary| Grey | Neutral / Informational | | success | Green | Confirmations / Starts | | danger | Red | Restarts / Stops / Deletes |

Note: Clicking the "Restart Server" button above executes the ping command with the argument restart behind the scenes, exactly as if the user typed !ping restart.

Customizing Persistence per Panel: If you want one panel to "jump" to the bottom every 60 seconds but another to stay put, add a persist block directly to the panel:

"Server_Controls": {
  "channels": ["123456789"],
  "persist": {
    "enabled": true,
    "interval_seconds": 60,
    "cleanup_old_active": true
  },
  "buttons": [...]
}

4. Dynamic Body Templating (Optional)

By default, DashCord sends a standardized payload to your webhook. However, if your API requires a very specific JSON structure (or if you want to drop the bot straight into an existing integration without changing the API), you can define a body_template.

The body_template can be any valid JSON structure (deeply nested objects, arrays, etc.). DashCord will recursively scan your template and replace {{placeholders}} with real-time data using dot-notation.

"commands": {
  "ai-task": {
    "endpoint": "http://192.168.1.100/run/ai",
    "method": "POST",
    "body_template": {
      "settings": {
        "priority": "high",
        "dry_run": false
      },
      "user_info": {
        "name": "{{discord.user_display}}",
        "id": "{{discord.user_id}}"
      },
      "task_data": {
        "prompt": "{{raw}}",
        "file_name": "{{attachment.filename}}",
        "file_base64": "{{attachment_b64}}"
      }
    }
  }
}

Common Placeholders You Can Use:

• {{raw}}: The full text the user typed (e.g., !weather tomorrow).
• {{args}}: The list of arguments provided by the user (e.g., ['now', 'tomorrow']).
• {{nonce}}: A unique UUID generated for every single request. Use this for idempotency or as a database primary key.
• {{command}}: The name of the command triggered.
• {{discord.user_id}} / {{discord.user_display}}: Information about the triggering user.
• {{discord.channel_id}} / {{discord.channel_name}}: Information about the channel.
• {{attachment_b64}}: The fully encoded base64 string of the uploaded file.
• {{source_meta_b64}}: A Base64-encoded JSON object containing both the discord and attachment metadata blocks.
• {{attachment_text}}: The raw UTF-8 text of the file (great for .txt or .json uploads).
• {{attachment.filename}}: The original name of the uploaded file.

---

📦 Default Webho