Connect your own turnstile bot

Connecting a bot is what turns the Telegram gate on for your account: it validates the token with Telegram, saves it (encrypted — the panel only ever shows a mask), and registers the webhook so /start starts flowing to you immediately.

Before you start

You need a public webhook host configured on the backend (tg_turnstile_webhook_host) — this is server-side config, not something the panel exposes, so if it's missing every connect attempt fails with webhook_host_not_configured regardless of how good the token is.

Create the bot and get a token

1. Open @BotFather in Telegram and send /newbot.
2. Pick a name and a username ending in bot.
3. Copy the token BotFather gives you — it looks like 123456789:AAExampleTokenAbcDefGhi.

Connect it

In the panel, paste the token into Bot token from @BotFather and click Connect the bot (if a bot is already connected, click Change bot first — a new token replaces the current one). Or call the endpoint directly:

curl -X POST https://app.tease.link/api/admin/tg/gate/connect \
  -H "Authorization: Bearer $TEASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "token": "123456789:AAExampleTokenAbcDefGhi" }'

This is a workspace-owner-only action — a team member's request gets a 403. On success:

• The token is validated against Telegram (getMe) before anything is saved.
• Your greeting, split, and rule settings survive a reconnect — only the bot identity changes.
• A per-bot webhook secret is minted the first time (stable after that), and the webhook is registered for you against https://<host>/api/tgbot/webhook.
• The gate is turned on (enabled: true) — reconnecting always re-enables it.
• The bot's Telegram profile (name, bio, avatar) is pulled in as a best-effort step; a hiccup there never fails the connect itself — see Sync or edit the bot's Telegram profile.

How to know it worked

The bot card's status dot should read running (green) — that means the webhook is set and the bot is enabled. If it instead reads webhook not set (amber), the token was accepted but setWebhook didn't stick; use Re-register the webhook to retry it without reconnecting. Then message your bot's /start from a real Telegram account — you should get the localized greeting and a button back within a couple of seconds.

If it didn't work

• 400 invalid_token — Telegram's getMe rejected the token. Double-check you copied the whole string from BotFather, with no leading/trailing whitespace.
• 400 webhook_host_not_configured — the backend has no public webhook host set; this is an infra-side fix, not something to retry from the panel.
• 502 telegram_unreachable — a network fault reaching Telegram's API; retry.

What's next

• Set up a junk-traffic split or route with rules to decide where different visitors land.
• Customize the bot's greeting.