Telegram setup

Telegram is Bestie’s first real chat channel after terminal chat. It runs locally with long polling and owner-only access.

Setup

Run the helper:

bestie channels telegram setup

The setup helper asks for an owner id or username and a bot token. If you leave the owner prompt blank, Bestie tries to detect the owner from the latest non-bot message sent to the bot. Send a message to the bot first, then run setup.

You can also detect the owner after setup:

bestie channels telegram whoami

whoami reads recent bot updates and prints the numeric id, username when present, and the channels.telegram.ownerUserId value you can use in config.

Or configure .bestie/config.json manually:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botTokenEnv": "BESTIE_TELEGRAM_BOT_TOKEN",
      "ownerUserId": "123456789"
    }
  }
}

Add the bot token to .bestie/.env:

BESTIE_TELEGRAM_BOT_TOKEN=123456:bot-token-here

Never commit .bestie/.env.

Run the bot

bestie channels telegram

For one update cycle during smoke/debug work:

bestie channels telegram --once

For background operation, use the daemon manager:

bestie daemon start --channel telegram
bestie daemon status --channel telegram

See Run Bestie in the background for restart, stop, stale state, and systemd service behavior.

Transcript logging

For smoke tests and integration debugging, write a local JSONL transcript:

bestie channels telegram --once --transcript .bestie/logs/telegram-smoke.jsonl

Transcript logging records polling, outbound messages, chat actions, attachment file metadata, attachment downloads, progress-message edits, and voice/audio sends when those flows run.

Identifiers such as chat ids, file ids, and Telegram file paths are hashed in transcript entries. Treat transcripts as local diagnostic data anyway: they can still reveal timing, message flow, file sizes, and operational details.

Supported commands

/start - owner-only readiness reply.
/help - supported commands.
/status - short local status summary without secrets.
/doctor - concise Doctor summary.
/memory or /memory list - memory status or recent-memory summary.
/memory pending - pending-memory review queue.
/memory pending inspect <id> - inspect one pending memory.
/memory pause and /memory resume - pause or resume local memory.
/approvals - list pending action approval requests.
/approve <id> and /deny <id> - record owner decisions. The current foundation records decisions without executing approved actions.

Unknown slash commands return a short fallback instead of going to the LLM.

Attachments

Telegram can download supported files into .bestie/workspace/telegram/..., forward caption and metadata, and include bounded previews for text-like files.

Important defaults:

downloadPolicy: allow
maxBytes: 20971520
parseMaxBytes: 5242880
visionPolicy: deny
transcriptionPolicy: deny

Uploaded content is untrusted. Full saved files can be read later through local read tools when permitted.

Tool progress

When a Telegram turn uses tools, Bestie should edit one progress message instead of spamming the chat. The final answer replaces the progress message when possible.

Progress text should be user-facing, for example:

Miu đang xem danh sách tệp trong src/cli
Miu đang tìm tệp khớp *.md trong docs
Miu đang gom tài liệu Markdown từ src

Raw internal tool names should not leak into the Telegram chat.

Verification checklist

npm run build
npm run smoke
npm run smoke:doctor:exit-code
bestie channels telegram whoami
bestie channels telegram --once
bestie channels telegram

Then send /start, /help, /status, /doctor, /memory, /memory pending, approval commands when pending approvals exist, and a normal owner text message.

Messages from any other Telegram user should be ignored.

Voice is no longer Telegram-only

Telegram remains a channel adapter for chat and bot interactions. Voice, however, is now a separate Bestie capability. If a Telegram bot supports voice messages, treat that as Telegram passing audio into the voice pipeline rather than Telegram owning the voice system.

Keep Telegram docs focused on bot setup, webhook/polling behavior, commands, and channel-specific permissions. Put reusable voice behavior in the voice guide.