Two-way bot commands

A bot can do more than send alerts. With the command link enabled, COM1 can relay a user-entered command to a backend you control. That backend decides which commands are allowed, performs the action, and returns a result that appears in COM1.

How it works

1. The owner enables the bot's COMMAND LINK with a reachable public HTTPS callback URL.
2. COM1 issues a dedicated secret for this command link. The owner copies it once and stores it on the backend.
3. An authorized user sends /bot @server01 status from a permitted chat.
4. COM1's com1-bot-command Edge Function checks permissions, records an audit entry and sends the command to the callback.
5. The backend validates authenticity, validates the requested operation, and responds. COM1 records the result in the bot conversation and command audit trail.

/bot
/bot @server01 status
/bot @server01 uptime
/bot @server01 lights status

Step 1 — Configure the callback

1. Deploy a server-side HTTPS endpoint reachable from the Supabase Edge Function, e.g. https://bot.example.com/com1/command.
2. In COM1, open BOT API → your bot → COMMAND LINK → CONFIGURE.
3. Paste the callback URL. COM1 returns a one-time command secret. Save it in your server secrets store immediately.
4. Turn on only safe command handlers (status, read-only diagnostics, carefully scoped automations) before allowing others to use them.

Step 2 — Grant a trusted handle access

Open SHARED ACCESS in the bot console, then choose a COM1 handle and access mode:

Shared users do not receive the owner's raw API tokens or callback secret. Revoking access stops future access; previously delivered packets cannot reliably be recalled from their devices.

Step 3 — Write a deliberately narrow handler

Your backend should treat incoming command text as untrusted input, even after verifying the signed request. Dispatch on fixed operation names rather than passing arbitrary text to a shell.

// PSEUDOCODE — not a deployable COM1 callback until the exact
// COM1-BOT-COMMAND/1 authentication envelope is verified.
async function onVerifiedCom1Command(commandText) {
  switch (commandText.trim()) {
    case 'status': return { ok: true, message: 'SERVER ONLINE' };
    case 'uptime': return { ok: true, message: 'UPTIME // 6 DAYS' };
    default: return { ok: false, message: 'COMMAND NOT ALLOWED' };
  }
}
// Required outside this handler:
// 1. Verify COM1 callback signature/secret and freshness.
// 2. Parse the documented envelope and enforce replay protection.
// 3. Return the exact response shape expected by the deployed Edge Function.

Command context & audit

COM1's SQL schema records command IDs, bot ID, actor/account context, origin conversation, status, HTTP status and completion time. The chat-sharing migration adds owner-approved read and command access and supports commands from other chats. Results can be made visible in the originating chat, subject to deployed code behavior.

Security checklist

• Always use HTTPS and validate the signed request or secret exactly as specified by the deployed Edge Function.
• Reject stale, duplicate and malformed requests. Log IDs/status, not tokens or message contents.
• Use allowlists for command names and arguments. Never expose unrestricted shell, SQL, SSH or device-control access.
• Run the callback using a low-privilege service account with restrictive network access.
• Rotate the command secret if it leaks; configuring the link again creates a new secret.
• Prefer command-only rights for trusted users and revoke access when unnecessary.
• For a private/home server with no public callback, do not forward arbitrary inbound ports. The outbound-only COM1 Agent remains planned.

Operational status

See Recipes and the outbound event endpoint for fully specified examples.