huskies/website/app/docs/transports/page.tsx

/** Chat transports guide — Matrix, Slack, WhatsApp, Discord, and web UI setup. */
import type { Metadata } from 'next'
import Link from 'next/link'

/** Page metadata for the chat transports guide. */
export const metadata: Metadata = {
  title: 'Chat Transports — Huskies Docs',
  description:
    'Connect huskies to Matrix, WhatsApp, Slack, Discord, or the built-in web UI.',
}

/** Renders the chat transports setup guide for all supported platforms. */
export default function TransportsPage() {
  return (
    <>
      <h1 className="page-title">Chat Transports</h1>
      <p className="page-subtitle">
        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.
      </p>

      <div className="note">
        <strong>Configuration:</strong> Copy the relevant example file to{' '}
        <code>.huskies/bot.toml</code> and fill in your credentials. The file is gitignored. Restart
        huskies after changes.
      </div>

      <h2>Web UI</h2>
      <p>
        The built-in web interface is always available at <code>http://localhost:&lt;port&gt;</code>. No
        configuration required. It provides:
      </p>
      <ul>
        <li>Pipeline board showing all work items and their stages</li>
        <li>Agent status panel with live output streaming</li>
        <li>Chat interface for running commands and talking to Claude</li>
        <li>Coverage and cost dashboards</li>
      </ul>
      <p>
        No <code>bot.toml</code> is required for the web UI. If no transport is configured, huskies runs
        in web-only mode.
      </p>

      <h2>Matrix</h2>
      <p>
        Matrix uses the Matrix Client-Server API with long-polling sync. No public webhook URL is required
        &mdash; the bot connects outbound to your homeserver.
      </p>

      <h3>Setup</h3>
      <ol className="step-list">
        <li>
          <div>Register a Matrix account for the bot on your homeserver (e.g. <code>@huskies:example.com</code>).</div>
        </li>
        <li>
          <div>Invite the bot account to the rooms you want it to monitor.</div>
        </li>
        <li>
          <div>
            Copy the example config and fill in your credentials:
            <pre>
              <code>cp .huskies/bot.toml.matrix.example .huskies/bot.toml</code>
            </pre>
          </div>
        </li>
      </ol>

      <h3>bot.toml fields</h3>
      <table>
        <thead>
          <tr>
            <th>Key</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>homeserver</td>
            <td>
              Your Matrix homeserver URL (e.g. <code>https://matrix.example.com</code>).
            </td>
          </tr>
          <tr>
            <td>username</td>
            <td>
              Bot account Matrix ID (e.g. <code>@huskies:example.com</code>).
            </td>
          </tr>
          <tr>
            <td>password</td>
            <td>Bot account password.</td>
          </tr>
          <tr>
            <td>room_ids</td>
            <td>
              List of room IDs to listen in (e.g. <code>{`["!roomid:example.com"]`}</code>).
            </td>
          </tr>
          <tr>
            <td>allowed_users</td>
            <td>
              Matrix IDs allowed to interact. Empty list means nobody &mdash; always set this.
            </td>
          </tr>
          <tr>
            <td>ambient_rooms</td>
            <td>
              Rooms where the bot responds to all messages (not just addressed ones). Updated automatically
              by <code>ambient on/off</code>.
            </td>
          </tr>
        </tbody>
      </table>

      <h2>Slack</h2>
      <p>
        Slack uses event subscriptions over a webhook. You&apos;ll need a public HTTPS URL pointing to your
        huskies server.
      </p>

      <h3>Setup</h3>
      <ol className="step-list">
        <li>
          <div>
            Create a Slack App at{' '}
            <a href="https://api.slack.com/apps">api.slack.com/apps</a>.
          </div>
        </li>
        <li>
          <div>
            Add OAuth scopes: <code>chat:write</code>, <code>chat:update</code>.
          </div>
        </li>
        <li>
          <div>
            Subscribe to bot events: <code>message.channels</code>, <code>message.groups</code>,{' '}
            <code>message.im</code>.
          </div>
        </li>
        <li>
          <div>Install the app to your workspace and copy the bot token.</div>
        </li>
        <li>
          <div>
            Set your webhook URL in Event Subscriptions:{' '}
            <code>https://your-server/webhook/slack</code>
          </div>
        </li>
        <li>
          <div>
            Copy the example config:
            <pre>
              <code>cp .huskies/bot.toml.slack.example .huskies/bot.toml</code>
            </pre>
          </div>
        </li>
      </ol>

      <h3>bot.toml fields</h3>
      <table>
        <thead>
          <tr>
            <th>Key</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>slack_bot_token</td>
            <td>
              OAuth bot token starting with <code>xoxb-</code>.
            </td>
          </tr>
          <tr>
            <td>slack_signing_secret</td>
            <td>Signing secret from the app&apos;s Basic Information page.</td>
          </tr>
          <tr>
            <td>slack_channel_ids</td>
            <td>
              List of channel IDs to listen in (e.g. <code>{`["C01ABCDEF"]`}</code>).
            </td>
          </tr>
        </tbody>
      </table>

      <h2>WhatsApp (Meta Cloud API)</h2>
      <p>
        Connects huskies to WhatsApp Business via the Meta Cloud API. Requires a Meta Business account and
        a public webhook URL.
      </p>

      <h3>Setup</h3>
      <ol className="step-list">
        <li>
          <div>
            Create a Meta Business App at{' '}
            <a href="https://developers.facebook.com">developers.facebook.com</a>.
          </div>
        </li>
        <li>
          <div>Add the WhatsApp product and get a Phone Number ID.</div>
        </li>
        <li>
          <div>Generate a permanent access token.</div>
        </li>
        <li>
          <div>
            Register your webhook URL in Meta&apos;s dashboard:{' '}
            <code>https://your-server/webhook/whatsapp</code>
          </div>
        </li>
        <li>
          <div>
            Copy the example config:
            <pre>
              <code>cp .huskies/bot.toml.whatsapp-meta.example .huskies/bot.toml</code>
            </pre>
          </div>
        </li>
      </ol>

      <h3>bot.toml fields</h3>
      <table>
        <thead>
          <tr>
            <th>Key</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>whatsapp_provider</td>
            <td>
              Set to <code>&quot;meta&quot;</code> for the Meta Cloud API.
            </td>
          </tr>
          <tr>
            <td>whatsapp_phone_number_id</td>
            <td>Phone Number ID from the Meta dashboard.</td>
          </tr>
          <tr>
            <td>whatsapp_access_token</td>
            <td>Permanent access token.</td>
          </tr>
          <tr>
            <td>whatsapp_verify_token</td>
            <td>
              Webhook verify token &mdash; must match what you set in Meta&apos;s dashboard.
            </td>
          </tr>
          <tr>
            <td>whatsapp_allowed_phones</td>
            <td>
              Optional. List of phone numbers allowed to interact (e.g.{' '}
              <code>{`["+15551234567"]`}</code>). When absent, all numbers are allowed.
            </td>
          </tr>
          <tr>
            <td>whatsapp_notification_template</td>
            <td>
              Optional. Name of the approved Meta message template for out-of-window notifications
              (default: <code>&quot;pipeline_notification&quot;</code>).
            </td>
          </tr>
        </tbody>
      </table>

      <h2>WhatsApp (Twilio)</h2>
      <p>
        An alternative WhatsApp integration using Twilio&apos;s WhatsApp API. Requires a Twilio account.
      </p>
      <pre>
        <code>cp .huskies/bot.toml.whatsapp-twilio.example .huskies/bot.toml</code>
      </pre>
      <p>
        Set <code>whatsapp_provider = &quot;twilio&quot;</code> and fill in your Twilio account SID, auth
        token, and phone numbers. The webhook URL is the same:{' '}
        <code>https://your-server/webhook/whatsapp</code>.
      </p>

      <h2>Discord</h2>
      <p>
        Connects huskies to Discord using the Discord Gateway WebSocket. No public webhook URL required
        &mdash; the bot connects outbound.
      </p>

      <h3>Setup</h3>
      <ol className="step-list">
        <li>
          <div>
            Create a Discord Application at{' '}
            <a href="https://discord.com/developers/applications">
              discord.com/developers/applications
            </a>
            .
          </div>
        </li>
        <li>
          <div>Go to Bot, create a bot, and copy the token.</div>
        </li>
        <li>
          <div>
            Enable <strong>Message Content Intent</strong> under Privileged Gateway Intents.
          </div>
        </li>
        <li>
          <div>
            Go to OAuth2 &rarr; URL Generator, select the <code>bot</code> scope with permissions: Send
            Messages, Read Message History, Manage Messages.
          </div>
        </li>
        <li>
          <div>Use the generated URL to invite the bot to your server.</div>
        </li>
        <li>
          <div>
            Right-click target channels &rarr; Copy Channel ID (requires Developer Mode enabled in Discord
            settings).
          </div>
        </li>
        <li>
          <div>
            Copy the example config:
            <pre>
              <code>cp .huskies/bot.toml.discord.example .huskies/bot.toml</code>
            </pre>
          </div>
        </li>
      </ol>

      <h3>bot.toml fields</h3>
      <table>
        <thead>
          <tr>
            <th>Key</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>discord_bot_token</td>
            <td>Bot token from the Discord developer portal.</td>
          </tr>
          <tr>
            <td>discord_channel_ids</td>
            <td>
              List of channel IDs to listen in (e.g.{' '}
              <code>{`["123456789012345678"]`}</code>).
            </td>
          </tr>
          <tr>
            <td>discord_allowed_users</td>
            <td>
              Optional. Discord user IDs allowed to interact. When absent, all users in configured
              channels can interact.
            </td>
          </tr>
        </tbody>
      </table>

      <h2 id="gateway-aggregated">Gateway: aggregated notifications</h2>
      <p>
        When using <code>huskies --gateway</code>, you can configure the gateway bot to receive
        notifications from <strong>all</strong> registered projects in a single room. Events are prefixed
        with <code>[project-name]</code>.
      </p>
      <p>
        No additional transport is required &mdash; the gateway aggregated stream works with any of the
        transports above. Configure the gateway&apos;s <code>.huskies/bot.toml</code> with your transport
        credentials and set <code>aggregated_notifications_enabled = true</code> (the default). See{' '}
        <Link href="/docs/configuration#gateway-aggregated-stream">
          Configuration &rarr; Gateway aggregated stream
        </Link>{' '}
        for the full reference.
      </p>
      <div className="note">
        <strong>No per-project changes needed:</strong> Adding a new project to{' '}
        <code>projects.toml</code> does not require editing per-project bot configs &mdash; the gateway
        picks it up automatically.
      </div>
    </>
  )
}