# Chat Transports — Huskies Docs
Connect huskies to Matrix, WhatsApp, Slack, Discord, or the built-in web UI.

# Chat Transports

Huskies can be controlled via bot commands in any of five transports. Only one external transport can be active at a time. The web UI is always available regardless.

Configuration: Copy the relevant example file to `.huskies/bot.toml` and fill in your credentials. The file is gitignored. Restart huskies after changes.

## Web UI

The built-in web interface is always available at `http://localhost:<port>`. No configuration required. It provides:

- Pipeline board showing all work items and their stages
- Agent status panel with live output streaming
- Chat interface for running commands and talking to Claude
- Coverage and cost dashboards

No `bot.toml` is required for the web UI. If no transport is configured, huskies runs in web-only mode.

## Matrix

Matrix uses the Matrix Client-Server API with long-polling sync. No public webhook URL is required — the bot connects outbound to your homeserver.

### Setup

1. Register a Matrix account for the bot on your homeserver (e.g. `@huskies:example.com`).
2. Invite the bot account to the rooms you want it to monitor.
3. Copy the example config and fill in your credentials:

       cp .huskies/bot.toml.matrix.example .huskies/bot.toml

### bot.toml fields

Key | Description
--- | ---
homeserver | Your Matrix homeserver URL (e.g. `https://matrix.example.com`).
username | Bot account Matrix ID (e.g. `@huskies:example.com`).
password | Bot account password.
room_ids | List of room IDs to listen in (e.g. `["!roomid:example.com"]`).
allowed_users | Matrix IDs allowed to interact. Empty list means nobody — always set this.
ambient_rooms | Rooms where the bot responds to all messages (not just addressed ones). Updated automatically by `ambient on/off`.

## Slack

Slack uses event subscriptions over a webhook. You'll need a public HTTPS URL pointing to your huskies server.

### Setup

1. Create a Slack App at api.slack.com/apps.
2. Add OAuth scopes: `chat:write`, `chat:update`.
3. Subscribe to bot events: `message.channels`, `message.groups`, `message.im`.
4. Install the app to your workspace and copy the bot token.
5. Set your webhook URL in Event Subscriptions: `https://your-server/webhook/slack`
6. Copy the example config:

       cp .huskies/bot.toml.slack.example .huskies/bot.toml

### bot.toml fields

Key | Description
--- | ---
slack_bot_token | OAuth bot token starting with `xoxb-`.
slack_signing_secret | Signing secret from the app's Basic Information page.
slack_channel_ids | List of channel IDs to listen in (e.g. `["C01ABCDEF"]`).

## WhatsApp (Meta Cloud API)

Connects huskies to WhatsApp Business via the Meta Cloud API. Requires a Meta Business account and a public webhook URL.

### Setup

1. Create a Meta Business App at developers.facebook.com.
2. Add the WhatsApp product and get a Phone Number ID.
3. Generate a permanent access token.
4. Register your webhook URL in Meta's dashboard: `https://your-server/webhook/whatsapp`
5. Copy the example config:

       cp .huskies/bot.toml.whatsapp-meta.example .huskies/bot.toml

### bot.toml fields

Key | Description
--- | ---
whatsapp_provider | Set to `"meta"` for the Meta Cloud API.
whatsapp_phone_number_id | Phone Number ID from the Meta dashboard.
whatsapp_access_token | Permanent access token.
whatsapp_verify_token | Webhook verify token — must match what you set in Meta's dashboard.
whatsapp_allowed_phones | Optional. List of phone numbers allowed to interact (e.g. `["+15551234567"]`). When absent, all numbers are allowed.
whatsapp_notification_template | Optional. Name of the approved Meta message template for out-of-window notifications (default: `"pipeline_notification"`).

## WhatsApp (Twilio)

An alternative WhatsApp integration using Twilio's WhatsApp API. Requires a Twilio account.

    cp .huskies/bot.toml.whatsapp-twilio.example .huskies/bot.toml

Set `whatsapp_provider = "twilio"` and fill in your Twilio account SID, auth token, and phone numbers. The webhook URL is the same: `https://your-server/webhook/whatsapp`.

## Discord

Connects huskies to Discord using the Discord Gateway WebSocket. No public webhook URL required — the bot connects outbound.

### Setup

1. Create a Discord Application at discord.com/developers/applications.
2. Go to Bot, create a bot, and copy the token.
3. Enable Message Content Intent under Privileged Gateway Intents.
4. Go to OAuth2 → URL Generator, select the `bot` scope with permissions: Send Messages, Read Message History, Manage Messages.
5. Use the generated URL to invite the bot to your server.
6. Right-click target channels → Copy Channel ID (requires Developer Mode enabled in Discord settings).
7. Copy the example config:

       cp .huskies/bot.toml.discord.example .huskies/bot.toml

### bot.toml fields

Key | Description
--- | ---
discord_bot_token | Bot token from the Discord developer portal.
discord_channel_ids | List of channel IDs to listen in (e.g. `["123456789012345678"]`).
discord_allowed_users | Optional. Discord user IDs allowed to interact. When absent, all users in configured channels can interact.

## Gateway: aggregated notifications

When using `huskies --gateway`, you can configure the gateway bot to receive notifications from all registered projects in a single room. Events are prefixed with `[project-name]`.

No additional transport is required — the gateway aggregated stream works with any of the transports above. Configure the gateway's `.huskies/bot.toml` with your transport credentials and set `aggregated_notifications_enabled = true` (the default). See Configuration → Gateway aggregated stream for the full reference.

No per-project changes needed: Adding a new project to `projects.toml` does not require editing per-project bot configs — the gateway picks it up automatically.