home-services/discord-bot

discord-bot

discord-bot is a Discord slash-command service that talks to ha-gateway over plaintext gRPC and exposes common Home Assistant actions in Discord.

How It Works

Runtime flow:

1. The bot starts a Discord session and registers slash commands.
2. A user runs a slash command such as /light list or /light on.
3. The Discord adapter routes the interaction to the app layer.
4. The app layer calls ha-gateway through the secondary gRPC adapter.
5. ha-gateway talks to Home Assistant and returns the result.
6. The bot formats the response back into a Discord message.

The service follows the same hexagonal structure as ha-gateway:

• cmd/bot: process bootstrap
• internal/adapters/primary/discord: slash command registration and handlers
• internal/app: command orchestration and response formatting
• internal/adapters/secondary/gateway: gRPC client for ha-gateway
• internal/core/ports/driven: app-facing gateway interface
• internal/config: env loading
• internal/telemetry: OpenTelemetry setup

Command Behavior

• List commands respond as regular channel messages.
• Action commands use deferred ephemeral replies, then send a follow-up result.
• Light autocomplete is backed by ListLights from ha-gateway.
• Switch autocomplete support exists in code, but there is currently no switch action command that uses it.

Common Commands

List lights

/light list

Shows all discovered lights in a fixed-width block. Each line includes:

• state emoji: 🟢 on, 🔴 off, ⚠️ unavailable or other state
• friendly name
• raw state
• supported color modes
• kelvin range when available

Example output shape:

🟢 Desk Lamp       on           color_temp,xy 2000-6535K
🔴 Closet          off          hs,color_temp 2202-4000K
⚠️ Hall Group      unavailable  color_temp 2000-6535K hue-group

Turn on a light

/light on light:<entity> brightness:80 color_temp:3000

Options:

• light: required, autocomplete enabled
• brightness: optional, 1-100
• color_temp: optional, 2000-6535

The bot responds with a confirmation such as:

Turned on `Desk Lamp` (brightness 80%, 3000K).

Turn off a light

/light off light:<entity> transition:3

Options:

• light: required, autocomplete enabled
• transition: optional, 0-30 seconds

Toggle a light

/light toggle light:<entity>

Option:

• light: required, autocomplete enabled

List switches

/switch list

Shows discovered switches in a fixed-width block with:

• state emoji
• friendly name
• raw state
• device class

Configuration

Environment variables:

• DISCORD_TOKEN: required Discord bot token
• GUILD_ID: optional guild ID; if set, commands are registered to that guild
• HA_GATEWAY_ADDR: required gRPC address for ha-gateway
• OTEL_ENDPOINT: optional OTLP gRPC endpoint; empty disables telemetry

Example env file: .env.example

Local Run

Create an env file and fill in real values:

cp discord-bot/.env.example discord-bot/.env

Then run:

cd discord-bot
go run ./cmd/bot

Build

cd discord-bot
go build ./...

Docker

Build from the repo root:

docker build -f discord-bot/Dockerfile -t discord-bot:dev .

Current Limitations

• no switch on/off/toggle command is exposed yet
• the bot depends on ha-gateway being reachable and healthy
• list formatting is optimized for monospace code blocks, not rich embeds
• authentication/authorization is whatever Discord and the internal network provide; the bot does not add another auth layer itself