How We Built Zero-Setup Telegram Integration for Vyneron

The Problem: Personal Bot Setup Was the Conversion Killer

For most of Vyneron's first year, the Telegram side of the product worked like this:

1. Open Telegram, talk to @BotFather, create a new bot.
2. Copy the bot token (a 46-character secret that looked like garbage).
3. Open Vyneron settings, paste the token into "Bring Your Own Bot."
4. Wait for the webhook to register.
5. Now you could finally message your task list.

Every signup that wanted Telegram had to do all five. Most never finished step 2.

This wasn't because the people who signed up were unmotivated. It was because every step was the kind of thing only a developer enjoys: spawning a bot, naming it, choosing a username that wasn't already taken, copy-pasting a token between two apps, trusting that the paste actually saved. For someone who just wanted to send buy milk tomorrow from the same chat where they already coordinate dinner, the setup ritual was wildly out of proportion to the value.

So they bounced. And the Telegram surface — arguably the most differentiated thing about Vyneron — was sitting behind a friction wall the rest of the product wasn't.

This post is the story of removing that wall. What we shipped is a shared Telegram bot model: every Vyneron account talks to the same @VyneronAIBot, and the bot figures out whose workspace the message belongs to. No personal tokens. No copy-paste. No BotFather visit.

TL;DR

TL;DR: Vyneron replaced its per-tenant bot token model with a single shared @VyneronAIBot that any account can link in under ten seconds. Account binding happens via a short-lived 6-digit code generated in the web app and pasted into the bot chat. The web app remains the primary surface — Telegram is an optional companion layer for people who already live in their chat app. The full migration shipped in about 24 hours, with 33 commits, a one-time database migration, and a hard cutover that didn't break the two users who were already linked.

Why a Shared Bot Took a Year

The honest answer: per-tenant tokens were easier to ship first.

When Vyneron launched, "every account brings its own bot" was a clean isolation story. Each workspace's Telegram traffic flowed through its own webhook, the bot tokens were stored encrypted per company, and there was no shared identity to reason about. If something went wrong with one customer's bot, it was their bot — debugging stayed local, and there was nothing global to take down by accident.

The trade-off was the one above: every prospect who wanted Telegram had to be five steps into developer-tool territory before they got value. We tolerated that early because the user base was small enough to walk through setup individually. Once the friction started showing up in real funnel data — accounts that signed up, never connected Telegram, and quietly drifted away — the calculus changed.

So shared bot went from "would be nice" to "is the constraint." The job was to keep every isolation guarantee that per-tenant tokens were giving us, while collapsing the setup to a single message in the chat.

The Architecture in Plain Language

In the shared model, there is exactly one Telegram bot for the entire product: @VyneronAIBot. Telegram's webhook routes every incoming message to a single endpoint on Vyneron's backend, which has to answer a question before it can do anything useful:

Which Vyneron account is this Telegram user?

Before the user has linked, the answer is "nobody we know." Their message gets a friendly throttled prompt that points them at the signup page, and that's it — no task creation, no AI calls, no account leakage. (The throttle exists because a single shared bot's /start flow is also a great target for noise, so unbound senders get a polite reply at most once per minute.)

Once the user has linked, the answer is a row in a small table: telegram_user_id → user_id. From that point on, the backend treats incoming messages exactly like the old per-tenant flow did. Same AI pipeline, same task creation, same web push back to the dashboard. The shared bot is a router; the workspace logic is unchanged.

A simplified picture:

Telegram → @VyneronAIBot webhook → backend
                                     │
                                     ├─ telegram_user_id known?
                                     │      ├─ yes → load account → run pipeline
                                     │      └─ no  → throttled signup CTA
                                     │
                                     └─ pipeline writes to web app DB
                                              │
                                              └─ web app picks it up

The piece that took the most care was step three of the routing: turning a brand-new Telegram message from a stranger into a verified bind without ever asking the user to paste a token.

How Account Linking Actually Works

When a logged-in Vyneron user opens Settings → Integrations and clicks Connect Telegram, the backend mints a short link code:

code        = "8X4-K2Q"       # 6 chars, alphabet excludes 0/O/1/I
user_id     = 42
expires_at  = now + 10 minutes
consumed    = false

The web app shows the code and a one-tap deep link like t.me/VyneronAIBot?start=8X4-K2Q. From there the user has two equally short paths:

• Tap the deep link — Telegram opens, the bot greets them, and the start payload arrives in the first update.
• Type the code into the bot manually — same end state, just slower.

Either way, the backend ends up with a single Telegram update that contains a code plus a from.id field — the Telegram-side numeric user ID. From there:

1. Look up the code. If it doesn't exist, is expired, or is already consumed, reply with a clear error.
2. Mark it consumed atomically — the same code cannot be claimed twice, even by the same Telegram user in two parallel taps.
3. Write telegram_user_id = from.id onto the matching Vyneron account.
4. Reply in the chat: "✅ Connected to your workspace."

The whole flow is one HTTP request from the user's perspective and three database operations on the backend. There is no token. There is no copy-paste. There is no BotFather. And there is no scenario where a stranger to the account can link their Telegram ID without first being logged in to the web app and clicking the button that generated the code.

A few details that matter more than they look:

• The code is short. Six characters with a friendly alphabet make manual typing realistic on a mobile keyboard. Ten characters would have been technically safer; six was the right tradeoff against typo rates we'd measured during the migration.
• It expires in ten minutes. Long enough to walk from your laptop to your phone, short enough that a screenshot leaked to a chat isn't useful by the time anyone notices.
• Codes are single-use and invalidated when a new one is generated. Clicking "Connect Telegram" a second time burns the previous code, so the most recent attempt is always the only valid one. This kills the "I clicked it twice and now I'm not sure which code is live" footgun.

The 24-Hour Rollout

The full migration shipped in roughly one calendar day, in two phases.

Phase 1 — backend. Twenty-three commits to bring up the shared bot, the link-code table, the throttled CTA, and the routing. Then nine post-review fixes to close edge cases that only become visible when you stop trusting the happy path: the lifespan-managed background task that wasn't being awaited, the link code that could be consumed twice if two requests raced, the help command silently dropping for unbound senders, the timing-safe comparison the original commit had missed, an over-eager rate limit, and a few more.

Phase 2 — eight-test canary. Before flipping the front door, we ran an explicit script: unbound message gets the CTA, link code happy path works, the same code cannot be reused, regenerating a code invalidates the previous one, the help command behaves for bound and unbound users, the webhook returns 200 even when the message can't be processed (Telegram retries on non-200 forever), and the central bot still reports healthy in /api/health. Every check had to pass before the frontend cut over.

Phase 3 — frontend. The Settings UI for "Bring Your Own Bot" disappeared. In its place: a single Telegram section with three states — Not connected (button), Code visible (countdown, copy, deep link), and Connected (account card with Disconnect). Twenty-one new translation keys across six locales.

The hard cutover worked because the user base at this point was tiny (the founder plus one friend), and both of them re-linked through the new flow on the same evening. For a larger user base, the same migration would have wanted a feature flag and a grace window. We deliberately avoided that complexity because it would have cost more time than the entire user base.

What Stayed the Same (Web App Stays Primary)

Worth saying directly: none of this makes Telegram required.

The web app is and stays the primary surface for Vyneron. Tasks, routines, notes, files, and AI search all work in the browser without ever opening Telegram. If you signed up tomorrow and never linked the bot, you would get the full product. The activation email we send 24 hours after signup says exactly this — the web app is ready, and Telegram is an optional bonus surface for people who already live in their chat app.

The shared-bot work was about removing friction for the users who wanted Telegram, not about pushing the surface on people who didn't. Treating Telegram as a super-power instead of a requirement is the line we keep returning to. Plenty of Vyneron users will never link a Telegram account, and the product should still feel complete for them.

What's Next

The shared bot opens a few doors that the per-tenant model kept closed.

• Telegram Mini Apps. A single bot identity means we can attach a t.me/VyneronAIBot/app Web App URL and let users open the full PWA from inside Telegram with one tap, plus generate shareable deep links into specific tasks and notes. This is post-launch work — it scales with the user base, so it earns more ROI later.
• Inline mode. @VyneronAIBot search invoice from any other Telegram chat, with results inline. Real estate for that lives behind the same shared identity.
• Smart welcome flow. With one bot, we can iterate on the very first /start reply across all users at once — copy changes, command suggestions, language detection from from.language_code.

But before any of that, the most useful follow-up is the smallest one: keep the friction at zero. The win wasn't "shipped a shared bot." The win was that someone can now go from signup to a working Telegram task entry in under a minute, without a single developer ritual, and still own a primary web surface that doesn't care whether they ever open the bot at all.

That's the kind of work that's invisible when it lands, which is exactly the goal.

Vyneron is a Telegram-native AI productivity workspace with built-in 250+ country holiday awareness, BYOK pricing, and OCR for photos and files. The web app is the primary surface; Telegram is optional. Try Vyneron free or browse the Telegram task bot survey for ecosystem context.