From f1b4894d6edcd3b3f8cd28e035d30b0c9965e88d Mon Sep 17 00:00:00 2001 From: dave Date: Tue, 24 Mar 2026 18:10:37 +0000 Subject: [PATCH] docs: split bot.toml.example into per-transport example files Replace the monolithic bot.toml.example with separate files for each transport: matrix, whatsapp-meta, whatsapp-twilio, and slack. Add a chat bot configuration section to the README explaining that only one transport can be active at a time and how to set up each one. Co-Authored-By: Claude Opus 4.6 (1M context) --- .storkit/README.md | 24 ++++++++- .storkit/bot.toml.example | 61 ----------------------- .storkit/bot.toml.matrix.example | 26 ++++++++++ .storkit/bot.toml.slack.example | 23 +++++++++ .storkit/bot.toml.whatsapp-meta.example | 28 +++++++++++ .storkit/bot.toml.whatsapp-twilio.example | 24 +++++++++ 6 files changed, 124 insertions(+), 62 deletions(-) delete mode 100644 .storkit/bot.toml.example create mode 100644 .storkit/bot.toml.matrix.example create mode 100644 .storkit/bot.toml.slack.example create mode 100644 .storkit/bot.toml.whatsapp-meta.example create mode 100644 .storkit/bot.toml.whatsapp-twilio.example diff --git a/.storkit/README.md b/.storkit/README.md index ccb3bb2..88fdc7d 100644 --- a/.storkit/README.md +++ b/.storkit/README.md @@ -228,7 +228,29 @@ If a user hands you this document and says "Apply this process to my project": --- -## 6. Code Quality +## 6. Chat Bot Configuration + +Story Kit includes a chat bot that can be connected to one messaging platform at a time. The bot handles commands, LLM conversations, and pipeline notifications. + +**Only one transport can be active at a time.** To configure the bot, copy the appropriate example file to `.storkit/bot.toml`: + +| Transport | Example file | Webhook endpoint | +|-----------|-------------|-----------------| +| Matrix | `bot.toml.matrix.example` | *(uses Matrix sync, no webhook)* | +| WhatsApp (Meta Cloud API) | `bot.toml.whatsapp-meta.example` | `/webhook/whatsapp` | +| WhatsApp (Twilio) | `bot.toml.whatsapp-twilio.example` | `/webhook/whatsapp` | +| Slack | `bot.toml.slack.example` | `/webhook/slack` | + +```bash +cp .storkit/bot.toml.matrix.example .storkit/bot.toml +# Edit bot.toml with your credentials +``` + +The `bot.toml` file is gitignored (it contains secrets). The example files are checked in for reference. + +--- + +## 7. Code Quality **MANDATORY:** Before completing Step 3 (Verification) of any story, you MUST run all applicable linters, formatters, and test suites and fix ALL errors and warnings. Zero tolerance for warnings or errors. diff --git a/.storkit/bot.toml.example b/.storkit/bot.toml.example deleted file mode 100644 index 7e104a2..0000000 --- a/.storkit/bot.toml.example +++ /dev/null @@ -1,61 +0,0 @@ -homeserver = "https://matrix.example.com" -username = "@botname:example.com" -password = "your-bot-password" - -# List one or more rooms to listen in. Use a single-element list for one room. -room_ids = ["!roomid:example.com"] - -# Optional: the deprecated single-room key is still accepted for backwards compat. -# room_id = "!roomid:example.com" - -allowed_users = ["@youruser:example.com"] -enabled = false - -# Maximum conversation turns to remember per room (default: 20). -# history_size = 20 - -# Rooms where the bot responds to all messages (not just addressed ones). -# This list is updated automatically when users toggle ambient mode at runtime. -# ambient_rooms = ["!roomid:example.com"] - -# ── WhatsApp Business API ────────────────────────────────────────────── -# Set transport = "whatsapp" to use WhatsApp instead of Matrix. -# The webhook endpoint will be available at /webhook/whatsapp. -# You must configure this URL in the Meta Developer Dashboard. -# -# transport = "whatsapp" -# whatsapp_phone_number_id = "123456789012345" -# whatsapp_access_token = "EAAx..." -# whatsapp_verify_token = "my-secret-verify-token" -# -# ── 24-hour messaging window & notification templates ───────────────── -# WhatsApp only allows free-form text messages within 24 hours of the last -# inbound message from a user. For proactive pipeline notifications sent -# after the window expires, an approved Meta message template is used. -# -# Register the template in the Meta Business Manager: -# 1. Go to Business Settings → WhatsApp → Message Templates → Create. -# 2. Category: UTILITY -# 3. Template name: pipeline_notification (or your chosen name below) -# 4. Language: English (en_US) -# 5. Body text (example): -# Story *{{1}}* has moved to *{{2}}*. -# Where {{1}} = story name, {{2}} = pipeline stage. -# 6. Submit for review. Meta typically approves utility templates within -# minutes; transactional categories may take longer. -# -# Once approved, set the name below (default: "pipeline_notification"): -# whatsapp_notification_template = "pipeline_notification" - -# ── Slack Bot API ───────────────────────────────────────────────────── -# Set transport = "slack" to use Slack instead of Matrix. -# The webhook endpoint will be available at /webhook/slack. -# Configure this URL in the Slack App → Event Subscriptions → Request URL. -# -# Required Slack App scopes: chat:write, chat:update -# Subscribe to bot events: message.channels, message.groups, message.im -# -# transport = "slack" -# slack_bot_token = "xoxb-..." -# slack_signing_secret = "your-signing-secret" -# slack_channel_ids = ["C01ABCDEF"] diff --git a/.storkit/bot.toml.matrix.example b/.storkit/bot.toml.matrix.example new file mode 100644 index 0000000..2b30eff --- /dev/null +++ b/.storkit/bot.toml.matrix.example @@ -0,0 +1,26 @@ +# Matrix Transport +# Copy this file to bot.toml and fill in your values. +# Only one transport can be active at a time. + +enabled = true +transport = "matrix" + +homeserver = "https://matrix.example.com" +username = "@botname:example.com" +password = "your-bot-password" + +# List one or more rooms to listen in. +room_ids = ["!roomid:example.com"] + +# Users allowed to interact with the bot (fail-closed: empty = nobody). +allowed_users = ["@youruser:example.com"] + +# Bot display name in chat. +# display_name = "Assistant" + +# Maximum conversation turns to remember per room (default: 20). +# history_size = 20 + +# Rooms where the bot responds to all messages (not just addressed ones). +# This list is updated automatically when users toggle ambient mode at runtime. +# ambient_rooms = ["!roomid:example.com"] diff --git a/.storkit/bot.toml.slack.example b/.storkit/bot.toml.slack.example new file mode 100644 index 0000000..297e103 --- /dev/null +++ b/.storkit/bot.toml.slack.example @@ -0,0 +1,23 @@ +# Slack Transport +# Copy this file to bot.toml and fill in your values. +# Only one transport can be active at a time. +# +# 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 +# 5. Set your webhook URL in Event Subscriptions: https://your-server/webhook/slack + +enabled = true +transport = "slack" + +slack_bot_token = "xoxb-..." +slack_signing_secret = "your-signing-secret" +slack_channel_ids = ["C01ABCDEF"] + +# Bot display name (used in formatted messages). +# display_name = "Assistant" + +# Maximum conversation turns to remember per channel (default: 20). +# history_size = 20 diff --git a/.storkit/bot.toml.whatsapp-meta.example b/.storkit/bot.toml.whatsapp-meta.example new file mode 100644 index 0000000..33439ec --- /dev/null +++ b/.storkit/bot.toml.whatsapp-meta.example @@ -0,0 +1,28 @@ +# WhatsApp Transport (Meta Cloud API) +# Copy this file to bot.toml and fill in your values. +# Only one transport can be active at a time. +# +# Setup: +# 1. Create a Meta Business App at developers.facebook.com +# 2. Add the WhatsApp product +# 3. Copy your Phone Number ID and generate a permanent access token +# 4. Register your webhook URL: https://your-server/webhook/whatsapp +# 5. Set the verify token below to match what you configure in Meta's dashboard + +enabled = true +transport = "whatsapp" +whatsapp_provider = "meta" + +whatsapp_phone_number_id = "123456789012345" +whatsapp_access_token = "EAAx..." +whatsapp_verify_token = "my-secret-verify-token" + +# Optional: name of the approved Meta message template used for notifications +# sent outside the 24-hour messaging window (default: "pipeline_notification"). +# whatsapp_notification_template = "pipeline_notification" + +# Bot display name (used in formatted messages). +# display_name = "Assistant" + +# Maximum conversation turns to remember per user (default: 20). +# history_size = 20 diff --git a/.storkit/bot.toml.whatsapp-twilio.example b/.storkit/bot.toml.whatsapp-twilio.example new file mode 100644 index 0000000..30ed55b --- /dev/null +++ b/.storkit/bot.toml.whatsapp-twilio.example @@ -0,0 +1,24 @@ +# WhatsApp Transport (Twilio) +# Copy this file to bot.toml and fill in your values. +# Only one transport can be active at a time. +# +# Setup: +# 1. Sign up at twilio.com +# 2. Activate the WhatsApp sandbox (Messaging > Try it out > Send a WhatsApp message) +# 3. Send the sandbox join code from your WhatsApp to the sandbox number +# 4. Copy your Account SID, Auth Token, and sandbox number below +# 5. Set your webhook URL in the Twilio console: https://your-server/webhook/whatsapp + +enabled = true +transport = "whatsapp" +whatsapp_provider = "twilio" + +twilio_account_sid = "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +twilio_auth_token = "your_auth_token" +twilio_whatsapp_number = "+14155238886" + +# Bot display name (used in formatted messages). +# display_name = "Assistant" + +# Maximum conversation turns to remember per user (default: 20). +# history_size = 20