Skip to content

README.md

Latest commit

 

History

History
47 lines (39 loc) · 2.23 KB

README.md

File metadata and controls

47 lines (39 loc) · 2.23 KB
Raw

Telegram Integration (Universal Bot, v2)

What works

  • Single webhook ingestion via /api/webhooks/telegram
  • Optional header verification with x-telegram-bot-api-secret-token
  • One bot can serve many groups/channels concurrently (route by chat_id)
  • Normalizes incoming Update objects (text/caption) into Commonly message buffer
  • Commands in Telegram:
    • /commonly-enable <code> to link a chat to a pod
    • /summary to post integration summary to Commonly
    • /pod_summary to post latest pod summary in Telegram

Config Fields

  • chatId (required once connected) — Telegram chat ID linked to the pod
  • chatTitle (optional) — stored for display
  • chatType (optional) — group, supergroup, channel, etc.
  • connectCode (required before linking) — generated by Commonly and used with /commonly-enable
  • secretToken (optional) — set as TELEGRAM_SECRET_TOKEN env and used in setWebhook

Environment Variables

  • TELEGRAM_BOT_TOKEN — universal bot token used to send command responses.
  • TELEGRAM_SECRET_TOKEN — optional webhook secret token (recommended).

Webhook Setup

  1. Call https://api.telegram.org/bot<botToken>/setWebhook with:
    • url: https://<your-host>/api/webhooks/telegram
    • secret_token: TELEGRAM_SECRET_TOKEN (optional but recommended)
    • Telegram requires HTTPS and ports 443/80/88/8443.
  2. Only one webhook is allowed; Telegram disables getUpdates when webhook is active.

Notes / Limitations

  • Attachments are not yet parsed; we keep text/caption content.
  • To avoid loops we ignore messages sent via bots (via_bot / from.is_bot).
  • Add the bot as admin in channels to receive channel_post.
  • Disable privacy mode in BotFather if you want all messages (not just commands).
  • The hourly scheduler consumes buffered messages and posts a bot summary to the pod.

UI

  • Sidebar Apps quick-add opens BotFather and shows a /commonly-enable command.
  • Use the generated connect code to link a chat to the pod.

Status

  • ⚠️ Legacy in-platform provider (will move to external service).
  • External service stub lives at external/commonly-provider-services/telegram-service/.

Next Steps

  • Parse common attachment types (photo/document/audio) for richer summaries.