[Daanish2003]

Summary

Spec 1 of the Messaging Channels Wayfinder. A user can now talk to their Bot on Telegram.

• Messaging Channel seam: a seam in the core channel plugin, with Channel accounts (a platform bot's token per Bot, encrypted under the ADR 0010 keyring). Listeners run one per account across instances, held by a Postgres advisory lock.
• Linked identities: proved by a 6-digit link code, so a Bot answers only its user.
• Inbound: messages from the Linked identity land in the Bot's Conversation as Messages and Triggers, with Attachments and a "via Telegram" mark.
• Outbound: replies and notification routes (telegram) reach Telegram.
• Rich controls: choices and Approvals show as buttons and can also be answered by typing. A Secret request only ever links into the app.
• @botsdk/channel-telegram: long polling with plain fetch, so no new dependency.
• Web app: installs the adapter. It has the Channels popover in the Bot header and Linked identities on Settings.

Closes #1044. Tickets #1045–#1050 are closed. #1051's Host wiring is merged, and the ticket stays open for the owner's manual checklist with a real @Botfather bot. ADR 0033 and the CONTEXT terms Channel account and Linked identity come in with this branch.

How it was tested

• Test-first integration tests at the spec's seams, driven through a new fakeMessagingAdapter in @botsdk/testing on real Postgres:
  • channel-accounts, linked-identities, channel-messaging-inbound, channel-messaging-out and channel-messaging-controls;
  • UI component tests for the popover, the Settings sections, the route pills and the "via" mark;
  • the Telegram package, tested against a local fake Bot API server.
• Each implementer broke the behaviour and saw its new tests go red.
• Full verify at d7d274f: lint, format and typecheck OK, then tests 283 files passed and 3 skipped, run in 3 shards.
• Full e2e at d6ab94e, after the web wiring: 58/58.
• The branch-review fixes (b3efea7) were checked with lint, format, root typecheck and the affected files: 252 tests, each new one seen red first.
• The full suite was not re-run after the review fixes, and CI was not waited for, at the owner's request.

Decisions I made

• Schema (owner-approved): bot_trigger.channel changed from an enum to text, so any adapter id can be recorded. notification_route gained telegram. Approved on Linked messages wake the Bot #1047 and on One platform bot per Bot, or one per Host #1036.
• Link-code guesses (owner-approved, from the branch review): a link code is void after 5 wrong guesses, counted in a link_code.attempts column inside the Linked identities and link codes #1046 migration.
• Public API (owner-approved): the SDK Logger gains an optional debug?. The silent drops of strangers and bad codes log there.
• Public API: the Email popover's nextChannel output widened from "web" | "email" to a string, which may be a platform id such as telegram.
• Telegram 403s: a 403 counts as a token rejection only on account-wide calls (getMe, getUpdates, deleteWebhook). One user blocking the bot doesn't mark the account needs attention.
• Moving a platform bot: saving a platform bot that sits on another of the user's own Bots moves it there (ADR 0033). One on another user's Bot is refused.
• Default route: the default route follows the user to Telegram when they last wrote from there and it can carry the Message. A messaging route without an installed adapter falls back to the defaults.
• Refused typed answers: a typed answer the domain refuses because the Bot is paused, or because it was already answered, goes on as an ordinary Message.
• Webhook Routines: approving a webhook Routine on Telegram replies with a link to the app for the webhook URL. The token is never sent on the Channel.
• "Other" answers: a pending "Other" answer is kept in memory per SDK instance and expires after 10 minutes.

Risk

• Migrations: four new bot migrations: channel_account, linked_identity (with link_code), trigger_channel_text (drops the bot_trigger_channel enum type) and route_telegram.
• Credentials: Channel account tokens are stored encrypted, never returned, and left out of the user export. rotateKeys covers them.
• Known gaps, for follow-ups:
  • A Host with only a messaging Channel has no app URL for links, because it comes from the email or push adapter. Fixing it needs a channel plugin option.
  • A multi-part send that fails partway resends the parts already sent.
  • The "Linked to your account" notice is lost if the token is rejected while sending it.
  • Voice transcription is out of scope.

🤖 Generated with Claude Code