Telegram

Control your CLI-JAW agent remotely through Telegram. Send messages, receive responses, forward agent output, handle voice messages with STT, and use slash commands -- all from your phone.

Setup

1. Create a Bot with BotFather

1. Open @BotFather in Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (looks like 123456:ABC-DEF...)

2. Configure settings.json

{
  "telegram": {
    "token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
    "allowedChatIds": [],
    "forwardAll": true
  }
}

3. Alternative: Use jaw init

jaw init --channel telegram --telegram-token "YOUR_TOKEN"

Sending and Receiving

• Text messages -- Send any text to your bot; it goes to the agent as a prompt
• Slash commands -- Use /model, /cli, /status, etc. directly in Telegram
• Photos and documents -- Attachments are downloaded, saved, and described to the agent
• Voice messages -- Transcribed via Gemini STT (or Whisper fallback) and sent as text

Forwarding

When forwardAll is true, the agent's agent_done results are automatically forwarded to your Telegram chat. Telegram-origin results are excluded to avoid echo.

/forward on   # Enable forwarding
/forward off  # Disable forwarding

File Delivery

The agent can send files to Telegram using the channel send API:

POST /api/telegram/send
POST /api/channel/send  # Unified endpoint (preferred)

Files are validated against a 20MB size limit. Telegram messages are chunked at 4096 characters and converted to Telegram HTML format.

Group Chat

In group/supergroup chats, the bot only responds when mentioned with @botUsername. The mention is automatically stripped from the message before processing.

Dashboard Telegram Hub (P0–P4)

Forum topics can route to different CLI-JAW instances. Manager UI configures (chatId, threadId) → port mappings. Hub commands: /setthread, /threads, /hubhelp. P4: per-topic model and systemPrompt overrides in Manager UI. See structure/telegram.md for the full hub-member relay model.

Watchdog diagnostics

When an agent turn stalls past the idle/progress watchdog threshold, kill diagnostics are relayed to the originating Telegram chat or forum topic so operators see why the turn ended.

Available Commands

51 slash commands are registered across CLI/Web/Telegram/Discord (37 visible in Telegram). Workflow helpers include /plan, /interview, /review, /search, /goal, /orchestrate, /task, /fork, /gd. Dynamic /skill:<id> is CLI/Web only. Bot-specific commands:

Environment Variables

Settings can be overridden via environment variables:

TELEGRAM_TOKEN=123456:ABC-DEF...
TELEGRAM_ALLOWED_CHAT_IDS=12345,67890