Linux_post_install/DOC/howto/communication.md

How-To: pos communication

Telegram messaging and alerts. Tools: telegram-sender, telegram-listener, matrix.

Tool	What it does
pos communication telegram sender	Send messages/files/links/stickers, test, config (token + chat id)
pos communication telegram listener	Bot listener: map /command → bash and run it from chat (systemd user daemon)
pos communication matrix	Matrix/Synapse sender (extensible; not yet implemented)

telegram-sender is the workhorse: it backs the whole notify system — health digests, backup alerts, firewall changes — and can be used directly.

---

pos communication telegram sender

One-time setup

pos config telegram
# edit TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID (masked input), then test:
pos communication telegram sender test
# config lives in ~/.config/linux_post_install/telegram.env (chmod 600)

The bot token comes from @BotFather, the chat ID from @userinfobot (or by starting a chat and reading it). pos config telegram shows the current values (token masked).

Send

pos communication telegram sender send "hello from my server"    # plain text
pos communication telegram sender send --markdown "**bold** ok"  # parse as markdown
pos communication telegram sender send --help                    # list all flags
pos communication telegram sender send /path/to/report.pdf       # auto-detects file

Recipes:

• Alert when a backup finishes — automatic: pos system backup calls notify_send (below) on success and failure.
• Warn before a service update:

  pos communication telegram sender send "Maintenance: docker compose down in 2min"
  

• On-call file drop: pos communication telegram sender send ~/log/nginx-error.log

Troubleshooting:

• "Not configured (no token or chat id)" → run pos config telegram and set both values.
• Send succeeds but nothing arrives → the chat must have started the bot (press Start / send /start once).
• Markdown silently empty → Telegram uses its own MarkdownV2; unmatched syntax makes the message vanish. Use --markdown only when the text is Telegram-safe (the health digest output is).
• Webhook vs getUpdates: the sender uses polling (getUpdates), so a webhook registered on the bot (e.g. via BotFather) blocks sends; remove it with BotFather's /deletewebhook.

---

pos communication telegram listener

Turns your bot into a two-way remote control: map /command → bash, then message the bot from your phone to run it.

pos communication telegram listener             # edit the /command → bash map
pos communication telegram listener --status    # service state + mapped commands
pos communication telegram listener --enable    # install the systemd user daemon
pos communication telegram listener --disable   # remove it

• Map file: ~/.config/linux_post_install/telegram_commands.env (chmod 600), one /cmd=bash command per line — re-read on every message, so edits apply instantly. Example:

  /status=@quiet pos system health --send
  /temp=sensors | grep -i 'Tctl\|package id 0'
  /update=cd /path/to/repo && git pull
  

• Bot command menu: the mapped commands are pushed to the bot's / menu (setMyCommands) after every map edit, on --enable, and at daemon start (force it anytime with --sync-commands). Add a short description with the /cmd::description=bash command syntax — e.g. /backup::Encrypted nightly backup=@quiet pos system backup --send — or it falls back to the bash command. Telegram only registers lowercase [a-z0-9_] names (1–32 chars); /Status or /my-cmd are skipped from the menu but still work when typed. An empty map clears the menu.
• Owner-only: the bot only reacts to TELEGRAM_CHAT_ID (your own chat); others are ignored. /help lists mapped commands; unknown → "Unknown command".
• Runs as you: mapped commands execute as your user with a 60s timeout, stdout + stderr are replied to the chat (truncated ~3800 chars; empty → OK). sudo inside a command needs a NOPASSWD rule.
• @quiet prefix: a map value starting with @quiet runs the command but does NOT reply — for commands that already send their own notification, so you don't get it twice. /status=@quiet pos system health --send delivers one digest via the notify system and nothing else.
• Daemon lifecycle: the service is a systemd user unit; it stops at logout unless you enable linger: sudo loginctl enable-linger $(whoami). --enable prints this warning if linger is off.

Troubleshooting:

• Bot doesn't answer → send /help; if silent, check the service with systemctl --user status pos-telegram-listener.service.
• A webhook on the bot blocks getUpdates → remove it with BotFather's /deletewebhook.
• Needs jq (in preinstall PACKAGES).

---

The notify system (notify_send)

Every tool that announces something sends through lib/notify.sh instead of hard-coding Telegram:

# ~/.config/linux_post_install/notify.env
NOTIFY_PLATFORM=telegram        # default; comma-separated to fan out to all

• notify_send "msg" → delivers to every platform in NOTIFY_PLATFORM (current senders: telegram).
• Silent-fail: no platform configured → one WARN line, exit 0, never breaks the calling tool.
• New platform (e.g. Matrix): implement bin/pos-communication-<p> send <value> [--markdown], then list it in NOTIFY_PLATFORM. Details: DOC/DEV.md → Alerting.

---

pos communication matrix

Sender contract exists (send <value> [--markdown]) and the dispatcher routes to it, but no implementation ships yet. When present, add matrix to NOTIFY_PLATFORM and configure it via pos communication matrix config set ….

---

Related

• Reference + config file details: DOC/POS.md → communication
• Alerting contract: DOC/DEV.md → Alerting
• Health digest (uses --send --markdown): system.md