call-center/docs/runbooks/track15-telegram-chat.md

Track 15 - Telegram Chat Runbook

Required env

• TELEGRAM_BOT_ENABLED=1
• TELEGRAM_BOT_TOKEN
• TELEGRAM_WEBHOOK_SECRET
• TELEGRAM_DEFAULT_QUEUE_ID

Optional:

• TELEGRAM_BOT_API_BASE when running against a stub or proxy

Register the bot webhook

Use Telegram Bot API setWebhook with:

• URL -> your public telegram-adapter-service webhook path:
  • /integrations/telegram/bot/webhook
• secret token -> TELEGRAM_WEBHOOK_SECRET

Operator workflow

1. Open /operator
2. Go to the Telegram page
3. Wait for a real inbound bot message
4. Select the thread from the left list
5. Click Принять в работу
6. Reply from the composer
7. Close or escalate the thread if needed

Runtime behavior

• one Telegram thread is stored per chat_id
• new inbound messages reuse the same thread_id and interaction_id
• if the linked interaction was closed, a new inbound message reactivates it to new
• unsupported inbound Telegram content is stored as a visible system placeholder

QA check

• send one first message from Telegram -> thread appears
• send a second message from the same chat_id -> same thread is reused
• operator claim works
• operator reply appears in the thread and is sent via Bot API