Setup guide

Telegram bot OTP verification, end to end

This guide walks through connecting a BotFather bot to TeleAuth and delivering your first verification code. It takes a few minutes and needs no server of your own.

Start building freeRead docs

1. Create the bot

Open BotFather in Telegram, send /newbot, pick a display name and a username ending in bot. BotFather replies with an HTTP API token — treat it like a password.

2. Connect it to a project

In the TeleAuth dashboard open Bots, choose Connect new bot, select the project and paste the token. TeleAuth validates the token against Telegram, loads the bot name, description and photo, and registers the webhook automatically.

  • Tokens are stored server-side only and are never returned to the browser
  • Editing or deleting a bot re-runs the same webhook wiring
  • The Bots page shows webhook status and how many users are linked

3. Send a test code

Use the Playground to send a code to your own Telegram username, then verify it. Once that works, copy the same request into your backend.

Send OTP
curl -X POST https://teleauth.run.place/api/public/v1/otp/send \
  -H "x-api-key: $TELEAUTH_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "username": "ada_lovelace" }'

4. Handle failures cleanly

Telegram only allows a bot to message users who have started a conversation with it. Prompt new users to open your bot and press Start before you attempt delivery, and surface the bot link in your UI.

FAQ

Common questions

Why did delivery fail with a chat-not-found style error?

The recipient has never started your bot. Telegram blocks unsolicited messages, so the user must open the bot and press Start once.

Can one bot serve several projects?

Use one bot per project. The webhook is registered per project so events stay isolated and logs stay readable.

Keep reading

Related guides

More ways to use Telegram for authentication and verification.

Telegram OTP API

Send and verify one-time passwords through Telegram with two REST calls. Project API keys, 5-minute code expiry, signed webhooks and delivery logs.

Telegram username verification

Verify Telegram usernames with one-time codes delivered by your own bot. No phone number, no SMS, no contact sharing.

Telegram webhook authentication

Receive signed authentication events from TeleAuth: HMAC-SHA256 signatures, replay protection and delivery logs for every send and verify.

Try telegram bot otp verification with TeleAuth

Create a project, connect your Telegram bot, and send your first OTP in minutes.

Create free account