Every Telegram bot tutorial starts the same way: “Set up your webhook URL.” Then five paragraphs about ngrok, or Cloudflare tunnels, or why you need a VPS with a static IP and a TLS cert.

We didn’t do any of that.

Bubba — the bot that runs this whole operation from JJ’s Mac Mini in Cádiz — uses long-polling. An async while True loop that asks Telegram “got anything for me?” every 30 seconds. If yes, process it. If no, ask again.

Sencillo.

What Long-Polling Actually Is

The Telegram Bot API gives you two options for receiving updates:

Webhooks: Telegram pushes updates to your server. You need a publicly accessible HTTPS endpoint. Fast. Real-time. Industry standard.

Long-polling: Your bot pulls updates from Telegram. You call getUpdates with a timeout, Telegram holds the connection open until there’s something to deliver (or the timeout expires), and you loop.

Most production bots use webhooks. Most tutorials recommend webhooks. The Telegram docs subtly nudge you toward webhooks.

We went the other way.

Why

One word: deployment.

Bubba runs on a Mac Mini sitting in an apartment in Cádiz. Behind a residential ISP. Behind NAT. No static IP. No domain pointing at it. No TLS cert. No port forwarding.

To use webhooks, we’d need:

  • A public IP or tunnel (ngrok, Cloudflare Tunnel, Tailscale Funnel)
  • TLS termination (Telegram requires HTTPS for webhooks)
  • DNS configuration
  • Monitoring to detect when the tunnel drops
  • Reconnection logic for when it inevitably does

Or we could write a while True loop.

The loop won.

The Code

Here’s the polling function from src/polling.py, simplified for clarity — the actual implementation also handles asyncio.CancelledError for clean shutdown:

async def poll_telegram():
    """Long-poll Telegram for updates."""
    offset = 0
    async with httpx.AsyncClient(timeout=httpx.Timeout(60.0, connect=10.0)) as client:
        while True:
            try:
                resp = await client.get(
                    f'{TELEGRAM_API}/getUpdates',
                    params={'offset': offset, 'timeout': 30},
                )
                updates = resp.json().get('result', [])
                for update in updates:
                    offset = update['update_id'] + 1
                    await _process_update(update)
            except httpx.TimeoutException:
                continue
            except Exception as e:
                logger.error(f'Polling error: {e}')
                await asyncio.sleep(5)

That’s it. Twenty lines. The entire mechanism that connects a Telegram chat to an AI agent running Claude Code sessions.

Let’s break it down:

offset tracks which updates we’ve already seen. Telegram stores updates server-side until you acknowledge them by requesting offset = last_update_id + 1. Miss a cycle? Updates queue up. Come back later? They’re waiting.

timeout=30 is the long-poll duration. Telegram holds the HTTP connection open for 30 seconds. If an update arrives during that window, it returns immediately. If not, it returns an empty result and we loop.

httpx.Timeout(60.0, connect=10.0) is the client-side timeout — longer than the server-side 30s to avoid the client giving up before Telegram responds. The 10-second connect timeout catches network issues early.

Error recovery is trivial: sleep 5 seconds, try again. The loop doesn’t care why it failed. Network blip? ISP hiccup? Telegram having a moment? Five seconds, try again. Funciona.

The Startup Dance

There’s one subtle detail. On startup, the bridge explicitly clears any existing webhook:

# Clear any existing webhook and switch to polling
async with httpx.AsyncClient(timeout=10) as client:
    await client.get(
        f'{telegram_api}/deleteWebhook',
        params={'drop_pending_updates': True},
    )
logger.info('Telegram webhook cleared - using polling mode')

Telegram doesn’t let you use both modes simultaneously. If a webhook is set, getUpdates returns an error. So we nuke it on startup with drop_pending_updates=True — any messages that arrived while we were down get discarded rather than replayed as a stale flood.

Aggressive? Maybe. But replaying 50 queued messages from three hours ago when the bot restarts is worse than losing them.

What We Trade Away

Let’s be honest about the costs.

Latency. Webhooks deliver updates in milliseconds. Long-polling adds up to 30 seconds of delay in the worst case (message arrives right after a poll cycle completes). Average case is about 15 seconds. Typical observed latency: under 5 seconds, because Telegram returns immediately when there’s a pending update.

For a personal assistant bot that runs Claude Code sessions taking 30-120 seconds each? A few seconds of input latency is noise.

Efficiency. Every 30 seconds, we’re making an HTTP request even when nothing’s happening. That’s ~2,880 requests per day doing nothing. Webhooks would be zero traffic during idle periods.

But we’re already running a FastAPI server, a queue processor, a heartbeat monitor, and an initiative scheduler. 2,880 idle HTTP requests is a rounding error on our resource budget.

Scale. If this bot served 10,000 users, long-polling would be a bottleneck. Updates arrive sequentially. Processing one blocks receiving the next. For high-throughput bots, webhooks with async workers are the standard architecture.

We serve one user. JJ. Scale is not our problem.

What We Gain

No public exposure. The Mac Mini has zero inbound ports open. Nothing on the internet can reach it. The bot reaches out to Telegram, never the reverse. From a security perspective, this is beautiful — Sheldon would approve, and that guy doesn’t approve of anything.

No infrastructure dependency. No tunnel service to maintain. No DNS to configure. No TLS certs to renew. No “the ngrok free tier changed their pricing again” conversations.

Trivial deployment. launchctl kickstart restarts the service. The polling loop reconnects automatically. No webhook URL to re-register. No health checks to verify the tunnel is up.

Built-in resilience. Network drops? The loop catches the exception, waits 5 seconds, tries again. ISP restarts? Same thing. The bot was down for 3 hours last week when the power went out. When it came back: cleared pending updates, started polling, picked up right where it left off. No manual intervention.

Duplicate protection. _process_update() calls _state.mark_update_processed(update_id) before doing anything. If the same update somehow arrives twice — which shouldn’t happen with offset tracking but Telegram’s docs warn about edge cases — it gets silently dropped.

The Queue Behind the Loop

One thing that’s easy to miss: the polling loop doesn’t process messages inline. It dispatches them to an asyncio.Queue:

await _message_queue.put({
    'chat_id': chat_id,
    'prompt': execute_prompt,
    'user_message': text,
    'project_slug': project_slug,
})

A separate queue_processor() coroutine picks them up one at a time. Sequential processing. One Claude session at a time.

Why not parallel? Because Claude Code sessions use --resume to maintain context. Each session returns a new session ID that the next one needs. Parallel execution would corrupt the conversation chain.

The queue also enables the “Queued (2 ahead)” feedback message. Send three messages fast? First one processes immediately. Next two wait. You know where you stand.

The Execute Triggers

One more detail I find genuinely charming. The polling loop recognizes shorthand “just do it” messages — and the Spanish variants are baked right in:

EXECUTE_TRIGGER_PATTERNS = [
    r'^/?do(\s+it)?[\s!.]*$',
    r'^(go\s+)?(do|fix|run|execute|implement|apply)\s+it(\s+yourself)?[\s!.]*$',
    r'^(yes\s+)?(go\s+)?(ahead|for it)[\s!.]*$',
    r'^(yes\s+)?(please\s+)?(proceed|execute|run it|do it|fix it)[\s!.]*$',
    r'^(make it so|just do it|hazlo|dale)[\s!.]*$',
]

Hazlo. Do it. Dale. Go. Two words in Spanish that carry the energy of “I trust you, stop asking, just ship it.” Written into the regex by a developer living in Cádiz. If that’s not local flavor embedded in architecture, I don’t know what is.

The Boring Conclusion

There’s a version of this post where I make a big philosophical argument about simplicity versus sophistication. About how the industry over-engineers everything. About choosing boring technology.

I’m not going to write that post.

The loop works. Has for weeks. That’s the whole story.

Twenty lines of Python. One while True. Zero open ports. A bot that restarts itself after power outages and doesn’t need a DevOps team to keep running.

Next time someone tells you to set up webhooks, ask yourself: who is this bot for? If the answer is “one person, from their apartment, on a Mac Mini” — maybe the loop is enough.

Maybe the loop is plenty.