dave
221 lines
11 KiB
HTML
221 lines
11 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Chat Transports — Huskies Docs</title>
|
|
<meta name="description" content="Connect huskies to Matrix, WhatsApp, Slack, Discord, or the built-in web UI.">
|
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
<link href="https://fonts.googleapis.com/css2?family=Bricolage+Grotesque:wght@400;500;600;700;800&family=Karla:ital,wght@0,300;0,400;0,500;1,300;1,400&display=swap" rel="stylesheet">
|
|
<link rel="stylesheet" href="docs.css">
|
|
</head>
|
|
<body>
|
|
|
|
<div class="shell">
|
|
<header class="reveal r1">
|
|
<a href="/" class="logo">huskies</a>
|
|
<nav>
|
|
<a href="/#how">How it works</a>
|
|
<a href="/#features">Features</a>
|
|
<a href="/docs/" class="active">Docs</a>
|
|
<a href="https://code.crashlabs.io/crashlabs/huskies">Source</a>
|
|
<a href="https://code.crashlabs.io/crashlabs/huskies/releases">Releases</a>
|
|
<a href="mailto:hello@huskies.dev" class="nav-cta">Get in touch</a>
|
|
</nav>
|
|
</header>
|
|
</div>
|
|
|
|
<div class="shell">
|
|
<div class="docs-layout">
|
|
<aside class="sidebar reveal r2">
|
|
<div class="sidebar-section">
|
|
<div class="sidebar-heading">Getting started</div>
|
|
<nav>
|
|
<a href="/docs/">Overview</a>
|
|
<a href="quickstart.html">Quickstart</a>
|
|
</nav>
|
|
</div>
|
|
<div class="sidebar-section">
|
|
<div class="sidebar-heading">Reference</div>
|
|
<nav>
|
|
<a href="configuration.html">Configuration</a>
|
|
<a href="commands.html">Bot commands</a>
|
|
<a href="cli.html">CLI</a>
|
|
</nav>
|
|
</div>
|
|
<div class="sidebar-section">
|
|
<div class="sidebar-heading">Guides</div>
|
|
<nav>
|
|
<a href="pipeline.html">Pipeline stages</a>
|
|
<a href="transports.html" class="active">Chat transports</a>
|
|
</nav>
|
|
</div>
|
|
</aside>
|
|
|
|
<main class="docs-main reveal r3">
|
|
<h1 class="page-title">Chat Transports</h1>
|
|
<p class="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 class="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:<port></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 — the bot connects outbound to your homeserver.</p>
|
|
|
|
<h3>Setup</h3>
|
|
<ol class="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 — 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'll need a public HTTPS URL pointing to your huskies server.</p>
|
|
|
|
<h3>Setup</h3>
|
|
<ol class="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'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 class="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'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>"meta"</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 — must match what you set in Meta'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>"pipeline_notification"</code>).</td></tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<h2>WhatsApp (Twilio)</h2>
|
|
<p>An alternative WhatsApp integration using Twilio'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 = "twilio"</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 — the bot connects outbound.</p>
|
|
|
|
<h3>Setup</h3>
|
|
<ol class="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 → 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 → 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 — the gateway aggregated stream works with any of the transports above. Configure the gateway's <code>.huskies/bot.toml</code> with your transport credentials and set <code>aggregated_notifications_enabled = true</code> (the default). See <a href="configuration.html#gateway-aggregated-stream">Configuration → Gateway aggregated stream</a> for the full reference.</p>
|
|
<div class="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 — the gateway picks it up automatically.
|
|
</div>
|
|
</main>
|
|
</div>
|
|
|
|
<footer class="reveal r3">
|
|
<span>© 2026 Libby Labs Ltd.</span>
|
|
<a href="/privacy.html">Privacy Policy</a>
|
|
</footer>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|