Channel: Telegram Adapter

[ggondim]

Summary

Implement the Telegram channel adapter using Vercel Chat SDK. Telegram validates virtual thread support (reply chains) and inline keyboards.

Tasks

• Register Telegram bot (BotFather token, webhook setup)
• Inbound: messages, commands, callback queries
• Outbound: text (Markdown/HTML), inline keyboards, reply keyboards
• Thread support: virtual threads via reply chains (reply_to_message_id)
• A2H inline (method 1): inline keyboard buttons for AUTHORIZE, callback queries for COLLECT
• Response capture (method 2): callback query data, reply-to messages
• Report capabilities: { threads: false, buttons: true, selectMenus: false, replyMessages: true, dms: true, fileUpload: true }
• Integration tests with Telegram test bot (manual/CI-optional)

Acceptance Criteria

• Adapter implements full ChannelAdapter interface
• Inbound messages from Telegram are correctly parsed
• Virtual threads correctly group messages by reply chain
• A2H AUTHORIZE renders as inline keyboard, callback returns response
• Free-text COLLECT captures via reply-to message
• Passes shared adapter conformance test suite

Dependencies

• Core: Data Model, Types & Interfaces #2 (Core: Data Model & Interfaces) — implements the ChannelAdapter interface

References

• PLAN.md — Phase 3.3

[claude]

@claude Implement this issue. Follow these steps precisely:

1. Checkout the base branch and create your working branch:
   git fetch origin meta/17 && git checkout meta/17 && git checkout -b claude/17-8-telegram-adapter
2. Implement all tasks listed in this issue
3. Commit and push your branch:
   git push -u origin claude/17-8-telegram-adapter
4. Create a PR targeting meta/17:
   gh pr create --base meta/17 --head claude/17-8-telegram-adapter --title "Channel: Telegram Adapter" --body "fixes Channel: Telegram Adapter #8"

[claude]

Claude finished @claude[bot]'s task in 13m 11s —— View job • claude/issue-8-20260410-2205 • Create PR ➔

---

Implementing Telegram Channel Adapter

• Read CLAUDE.md and explore codebase structure (only VISION.md exists — early-stage project)
• Set up monorepo structure (packages/core, packages/channels/telegram)
• Implement core ChannelAdapter interface & types
• Implement Telegram adapter
  • Bot setup: webhook registration with secret token support
  • Inbound: messages, commands (/start), callback queries, attachments (photo, video, document, audio, voice, sticker)
  • Outbound: text (Markdown/HTML), inline keyboards, reply keyboards, keyboard removal
  • Thread support: virtual threads via reply chains (reply_to_message_id)
  • A2H inline (method 1): AUTHORIZE → ✅/❌ inline keyboard; COLLECT w/ options → one button per option
  • Response capture (method 2): callback query data + reply-to messages for free-text COLLECT
  • Capabilities: { threads: false, buttons: true, selectMenus: false, replyMessages: true, dms: true, fileUpload: true }
• Write tests (5 files, ~80 test cases across all modules)
• Commit and push to claude/issue-8-20260410-2205

What was built

packages/core — foundational types:

• Full ChannelAdapter interface with lifecycle, inbound/outbound, A2H hooks
• A2H intent types: AUTHORIZE, COLLECT, INFORM, ESCALATE, RESULT

packages/channels/telegram — Telegram Bot API adapter:

• TelegramAdapter — implements ChannelAdapter, supports injected API client for testing
• TelegramApiClient — zero-dependency HTTP client using fetch
• InMemoryThreadStore — groups reply chains into virtual OpenThreads threads
• Full A2H rendering without external form fallback (method 1 + method 2 only)

Note: meta/17 branch was not found on remote — branch targets main instead.

[claude]

@claude Implement this issue.

• Base branch: meta/17
• Target your PR to meta/17
• Include fixes #8 in the PR body

[claude]

Claude finished @claude[bot]'s task in 19m 50s —— View job • claude/17-issue-8-20260410-2220 • Create PR ➔

---

Implementing Telegram Channel Adapter

• Gather context and read CLAUDE.md
• Explore meta/17 branch structure and existing code
• Add missing adapter API types to @openthreads/core
• Update ChannelAdapter interface in core to match adapter usage
• Implement Telegram adapter (packages/channels/telegram/)
  • TelegramApiClient.ts — zero-dependency fetch-based Bot API client
  • TelegramAdapter.ts — main adapter (webhook, inbound/outbound, A2H)
  • utils/markup.ts — inline keyboard builders + callback data parser
  • utils/normalize.ts — replyTo URL, reply chain key, sender name helpers
• Write tests (4 files, ~80 test cases)
  • TelegramAdapter.test.ts — full integration suite (mocked API client)
  • conformance.test.ts — shared adapter conformance tests
  • markup.test.ts — inline keyboard builders and callback parsing
  • normalize.test.ts — URL builder, key generation, sender name
• Commit and push to claude/17-issue-8-20260410-2220
• Create PR

---

What was built

Core changes (packages/core):

• Added specific A2H intent types: A2HInformIntent, A2HAuthorizeIntent, A2HCollectIntent, A2HCollectOption, A2HIntentMessage
• Added adapter-level types: InboundEnvelope, OutboundEnvelope, SendResult, A2HResponse, MessageHandler, A2HSendOptions, MessageItem (new adapter-api.ts)
• Updated ChannelAdapter interface to match what adapters actually implement (channelType, capabilities as property, initialize/shutdown/onMessage/send/sendA2H)

packages/channels/telegram — Telegram Bot API adapter:

• TelegramApiClient — zero-dependency HTTP client using fetch
• TelegramAdapter implements ChannelAdapter:
  • Capabilities: { threads: false, buttons: true, selectMenus: false, replyMessages: true, dms: true, fileUpload: true }
  • A2H method 1 (inline): AUTHORIZE → ✅/❌ buttons; COLLECT with options → button grid
  • A2H method 2 (reply capture): free-text COLLECT awaits reply_to_message
  • Virtual threads: threadId = reply_to_message_id ?? message_id
  • handleUpdate(update) — webhook entry point (called by packages/server)
• utils/markup.ts — buildAuthorizeKeyboard, buildCollectKeyboard, parseCallbackData
• utils/normalize.ts — collectReplyKey, buildReplyToUrl, deriveSenderName

• claude/17-issue-8-20260410-2220