huskies: merge 1113 story [huskies-server repo] Convert static website to Next.js with static rendering
This commit is contained in:
dave
@@ -0,0 +1,384 @@
|
||||
/** 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:<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 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 — 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 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'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'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 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 → 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{' '}
|
||||
<Link href="/docs/configuration#gateway-aggregated-stream">
|
||||
Configuration → 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 — the gateway
|
||||
picks it up automatically.
|
||||
</div>
|
||||
</>
|
||||
)
|
||||
}
|
||||
Reference in New Issue
Block a user