Authorization Code flow, QR for desktop, cross-device polling. User clicks a link, confirms in the bot — you get their name, username and subscriber_id.
· Rate limit 5 sessions/hr, 300 s code TTL, atomic GETDEL
Without us
CSRF state, TTL store, one-time codes, atomic GETDEL against TOCTOU — non-trivial to build right.
User on desktop, bot on phone. You need: show QR, wait for confirmation, don't crash after 5 minutes — sessions, polling, expiration.
Without limits on session creation your site becomes a link generator. You need sliding window rate limits per project and per IP.
What's inside
Simple case — permanent t.me/bot?start=auth_SLUG. One click → confirmation → your callback_url?code=...
POST /v1/auth/session with your state. Returns session_id and bot links. Your state returns with the code — you tie it to your browser session.
Desktop login: QR with link + polling GET /v1/auth/session/:id/status every 2-3 seconds. When user confirms on phone — you get the code.
ensure_subscribed() after confirmation adds the user to your project subscribers — so you can send them notifications right away.
A Lua GET+DEL script prevents code reuse between two requests (TOCTOU-safe).
Event fires right after confirmation. You don't have to wait for the user to come back to the site — you can unblock their backend immediately.
How it works
The link opens @zapnotybot or the Max bot with an auth_SLUG deep link. The bot shows "Log into your project?" with Yes/No buttons.
Tapping "Yes" → auto-subscribe to notifications + one-time code in Redis. Bot edits the message to "Authorization confirmed ✅".
Your callback_url?code=CODE. POST /v1/auth/verify atomically consumes the code and returns user data: subscriber_id, first_name, username, lang.
FAQ
Telegram Login Widget requires your own bot, domain setup, and doesn't support Max. Zapnoty is a SaaS layer: you get both channels, auto-subscription to your notifications, and a ready-made session API.
Max works without a VPN in Russia. If a user is on desktop without Telegram — we show them a QR for Max and a browser link. Auth works either way.
subscriber_id (UUID), channel (telegram/max), first_name, username, lang (ru/en), tags (array). Email and phone — not returned (Telegram/Max don't expose them).
The code is one-time — a GETDEL Lua script invalidates it right after verify. TTL 300 seconds. Rate limit 5 sessions/hr per project.
1 credit per successful auth (bot confirmation). On free plan — up to 100/month, on basic — up to 700.
Yes. If employees already use Telegram or Max — messenger login is faster and easier than classic corporate OAuth.
No credit card. 100 free credits per month — enough to try every feature.
Solutions & use cases
Common scenarios where Zapnoty replaces a stack of 3-4 separate services.
10× cheaper than SMS, higher reach than email
OTP, order status, abandoned cart, promos
Forms with instant Telegram notification — no forgotten inboxes
Drip lessons, reminders, Q&A and bot login
Support in Telegram/Max, no heavy chat widget