Skip to content

telegram

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

telegram

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

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.