Messaging integration: Slack, Discord, Telegram

This doc describes how to bring messages from Slack, Discord, Telegram (and similar) into your Knowtation vault so they appear in the Hub and can be searched.

Contract

All integrations produce notes that follow the CAPTURE-CONTRACT: vault-relative path, frontmatter with source, date, and optional source_id, project, tags. Notes go to vault/inbox/ or vault/projects/<project>/inbox/.

Option 1: Hub capture endpoint (recommended)

If the Knowtation Hub is running, use its capture endpoint so you don’t need a separate webhook server.

Endpoint: POST /api/v1/capture
Auth: If CAPTURE_WEBHOOK_SECRET is set, send header X-Webhook-Secret: <secret>.

Body (JSON):

{
  "body": "Message text or markdown",
  "source": "slack",
  "source_id": "msg-123",
  "project": "myproject",
  "tags": "meeting, decision"
}

Example (curl):

curl -X POST http://localhost:3333/api/v1/capture \
  -H "Content-Type: application/json" \
  -d '{"body": "Decided to ship on Friday", "source": "slack", "project": "product", "tags": "decision"}'

Option 2: Standalone webhook server

Run the capture webhook script and point integrations at it:

node scripts/capture-webhook.mjs --port 3131

Then POST to http://localhost:3131/capture with the same JSON body as above. Use this when the Hub is not running or when you want capture on a different host/port.

Slack

• Slack Events API: Subscribe to message events; Slack sends POSTs to your endpoint. Use scripts/capture-slack-adapter.mjs to receive those events, extract message text, and forward to the capture contract (Hub or standalone webhook).
• Outgoing webhooks / Slash commands: Configure Slack to POST to your adapter URL when a keyword is used or a command is run; the adapter normalizes the payload and calls capture.
• Zapier / n8n: Use a “Slack – New Message” trigger and an “HTTP – POST” action to send the message body to your Hub capture URL or webhook server. Map Slack channel/thread to project or tags if desired.

Adapter: node scripts/capture-slack-adapter.mjs --port 3132
Listens for Slack event payloads; responds to url_verification; on message events, POSTs to CAPTURE_URL (default http://localhost:3333/api/v1/capture) or to the standalone webhook. Set CAPTURE_URL and optionally CAPTURE_WEBHOOK_SECRET, SLACK_SIGNING_SECRET.

Discord

• Discord webhooks / bot: Have a bot or webhook receiver that gets message events. Use scripts/capture-discord-adapter.mjs to accept a simplified JSON payload (e.g. content, id, channel_id) and POST to the capture endpoint.
• Zapier / n8n: Trigger on “Discord – New Message” and POST to your capture URL with a body like {"body": "<message content>", "source": "discord", "source_id": "<id>"}.

Adapter: node scripts/capture-discord-adapter.mjs --port 3133
Expects POST with JSON: { "content": "message text", "id?", "channel_id?", "project?", "tags?" }. Forwards to CAPTURE_URL.

Telegram

• Telegram Bot API: Use a bot that receives messages and forwards them to your capture endpoint. You can use the dedicated adapter to accept Telegram webhook payloads, or POST the contract directly.
• Adapter: node scripts/capture-telegram-adapter.mjs --port 3134 — Accepts Telegram Bot API update payloads or simplified JSON { "body": "message text", "source_id?", "project?", "tags?" }. Forwards to CAPTURE_URL. Env: CAPTURE_URL, CAPTURE_WEBHOOK_SECRET.
• Zapier / n8n: “Telegram – New Message” → HTTP POST to Hub capture or webhook.

WhatsApp

• WhatsApp Business API: To bring WhatsApp messages into the vault, use automation or a custom webhook. No dedicated adapter script is shipped.
• Zapier / n8n: Use a "WhatsApp – New Message" trigger and an "HTTP – POST" action. Map message content to body and POST to https://your-hub.example.com/api/v1/capture with JSON {"body": "<message text>", "source": "whatsapp", "source_id": "<unique_id>", "project": "optional"}. Add header X-Webhook-Secret if you use CAPTURE_WEBHOOK_SECRET.
• Custom webhook: If you run a receiver for WhatsApp Cloud API, normalize the payload to the capture contract (body, source, source_id, project, tags) and POST to the Hub or to node scripts/capture-webhook.mjs.

Automation (Zapier, n8n, etc.)

1. Trigger: “New message” (or “New reaction”, “New file”) from Slack / Discord / Telegram / email.
2. Action: HTTP request – POST to https://your-hub.example.com/api/v1/capture (or your webhook URL).
3. Body: Map trigger output to body, and optionally source, source_id, project, tags.
4. Auth: If you use CAPTURE_WEBHOOK_SECRET, add header X-Webhook-Secret.

Your vault stays the source of truth; messages become searchable notes and appear in the Hub.