Notifications

Once a server is linked, ProcBoss Cloud can page you when things go wrong: a process crashes, a deploy fails, a server drops offline or comes back. Alerts go to the channels you connect — Telegram and Discord — plus the dashboard’s Alerts view. Nothing is enabled by accident: a channel only receives alerts after you connect it, and each event class has its own on/off switch.

Telegram#

Telegram pairing follows the same philosophy as pboss cloud connect: no tokens pasted through terminals, and the proof of intent is a short-lived code.

1. In the dashboard, open Settings → Integrations → Connect Telegram — or link straight from onboarding: the last onboarding step offers it (connect now, or skip — the same flow waits in Settings).
2. The panel shows a one-time code (6 characters, 15 minutes) and an Open Telegram button — t.me/<bot>?start=<code> opens the chat with the code pre-filled.
3. Send the message (or just tap Start in the opened chat). The bot replies “Connected to ProcBoss” and the dashboard flips to linked within a couple of seconds — no refresh needed.

From then on the chat receives crash alerts, deploy results, restart notices, resource-threshold warnings and server up/down transitions. The bot is also a remote control: the same agent channel the dashboard uses carries its commands, with the confirmation habit of a production tool.

Bot commands#

The / menu in any chat with the bot lists them (the menu is code-defined — scripts/set-telegram-webhook.ts pushes it with setMyCommands, so it never drifts from what the bot actually answers).

Names that exist on more than one server are pinned with name@server — the bot’s ambiguity reply shows a ready-to-copy example. Control commands (/restart, /stop, /kill) and /logs follow the dashboard’s plan gates: trials and subscriptions operate, free accounts monitor.

The /menu and /help replies ARE the tappable list — one full-width row per command (Status, Health, Alerts, Logs, Restart, Stop, Kill, Help) with its one-line description. Tapping a row sends the command exactly as if typed — no copy-paste, no separate button grid (Telegram cannot make bot-message text send on tap; code copies, plain text does nothing). A tap rides the same signed webhook and re-runs every guard: linked chat, plan gate, confirmation. The pairing welcome carries the same list. /unlink stays typed — it disconnects with no confirmation step.

Every control command carries three guards before anything moves: the update must be signed (the webhook secret), the chat must be linked to the account that owns the target, and a confirmation must complete — a tap on an inline Confirm button (2-minute validity, single-use), or the exact process name typed back for /kill. process.kill is the SIGKILL path: no graceful shutdown, no cleanup handlers — the process row survives and can be started again.

If the deployment has no bot configured (TELEGRAM_BOT_TOKEN unset), the panel says so instead of showing a broken pairing flow.

Server-side setup (self-hosters / the bot owner)#

The bot’s environment is part of the deployment’s own .env — the file is untracked (each deployment keeps its own copy; the key contract and production reference live in the tracked .env.example.txt template, and every key added to a local .env must be mirrored into it).

# one-time: create the bot with @BotFather, then put in .env
#   TELEGRAM_BOT_TOKEN=123456:…           (from @BotFather)
#   TELEGRAM_WEBHOOK_SECRET=…             (openssl rand -hex 32)
# and register the webhook:
bun scripts/set-telegram-webhook.ts \
  --url https://procboss.com

The script registers POST /api/integrations/telegram/webhook with Telegram, sets a shared secret (TELEGRAM_WEBHOOK_SECRET), and syncs the command menu (setMyCommands).

• Every update Telegram delivers carries the X-Telegram-Bot-Api-Secret-Token header; forged updates are rejected with 401 — unsigned updates can never read fleet state or run control commands.
• Without a configured secret the webhook runs in a reduced dev mode: pairing still works (knowing the code is the proof), but /status, /unlink and every control command refuse to run unsigned.
• One bot token carries ONE webhook URL — registering from a different deployment moves the webhook there. Register from the deployment that should receive your chats’ messages.
• The webhook listens for both message updates (commands) and callback_query updates (the Confirm buttons).

Discord#

Discord uses incoming webhooks — no bot token, no OAuth round-trip:

1. In your Discord server: channel settings → Integrations → Create Webhook, copy the URL.
2. Paste it into Settings → Integrations → Discord and click Connect.

ProcBoss verifies the webhook before saving it by posting a “ProcBoss connected” embed to the channel — if the embed doesn’t arrive, the URL is rejected and nothing is stored. Alerts arrive as embeds color-coded by severity (red critical / amber warning / green info).

Only https://discord.com / discordapp.com webhook URLs are accepted. Self-hosted relays can extend the list with DISCORD_WEBHOOK_ALLOWED_HOSTS (comma-separated; those entries may use plain http since you opted in explicitly).

Alert preferences#

Settings → Integrations → Alert preferences controls which events reach your connected channels:

Each test button sends a real message through the channel it belongs to — if delivery fails, the panel shows the recorded error (e.g. a revoked Discord webhook) instead of pretending it worked.

What the alert looks like#

🚨 payment-worker crashed
production-1 · process exited unexpectedly

✅ payment-worker restarted
production-1 · restart #4

⚠️ production-1 CPU at 96%
Sustained CPU above the 90% threshold.

✅ production-1 is back online
Agent reconnected and is reporting state again.

🚀 Deploy 8f12ca3 shipped to production-1
fix: retry after 429 — 6.1s, health checks green.

The dashboard’s Alerts view records every event with an honest channel label — telegram+discord means both channels confirmed delivery; none means the event fired but no channel accepted it (you’ll see why in the panel).

Security notes#

• Telegram chat ids and Discord webhook URLs are stored on your Integration row, never returned raw by the API (the dashboard shows masked forms — enough to recognize, not to replay).
• The Telegram webhook is the only public endpoint in the chain and it verifies a shared secret on every update.
• Channels are per-user: disconnecting a server, rotating a credential, or signing out sessions never touches them, and vice versa.