Telegram setup: bot token and account api_id/api_hash

Bot or account: which one do you need?

Bot vs account

How to create a Telegram bot and get its token

1. 1

   Send /newbot to @BotFather

   Open @BotFather in Telegram and send the /newbot command.

2. 2

   Choose a name and username

   The name appears in contact details. The username must be 5–32 characters of Latin letters, digits and underscores, and must end in bot (for example shop_support_bot).

3. 3

   Store the token

   BotFather returns a token like 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw. Anyone who has it controls the bot — keep it in an environment variable. If it leaks, generate a new one with /token in BotFather.

4. 4

   Configure privacy mode for groups

   By default a bot runs in privacy mode: in groups it receives only commands addressed to it, replies to its messages and service messages. To see everything, use /setprivacy → Disable, then remove the bot from the group and add it again. Admin bots receive all messages regardless.

5. 5

   Set the webhook

   setWebhook needs an HTTPS URL on port 443, 80, 88 or 8443. Pass a secret_token (1–256 characters: A-Z, a-z, 0-9, _, -) — Telegram sends it back in the X-Telegram-Bot-Api-Secret-Token header on every request. While a webhook is set, getUpdates doesn't work; undelivered updates are kept for no longer than 24 hours.

How to get api_id and api_hash and sign in to an account

1. 1

   Sign up in an official app

   Getting an api_id requires a Telegram account registered through an official Telegram app.

2. 2

   Register an app at my.telegram.org

   Log in to my.telegram.org with your phone number → API development tools → fill out the form. For now each phone number can have only one api_id.

3. 3

   Copy api_id and api_hash

   api_id is a number, api_hash is 32 hex characters. Never share the api_hash: it lets anyone sign in on behalf of your application.

4. 4

   Sign in with phone, code and 2FA

   auth.sendCode sends the code: most often it arrives as a service message inside the Telegram app, but it can also come by SMS, a call or other methods. The code goes to auth.signIn together with phone_code_hash. If two-step verification is enabled you get SESSION_PASSWORD_NEEDED and continue with the password. Other sessions are notified about the new login.

5. 5

   Keep the session secret

   The session string you get after signing in is equivalent to a password: store it encrypted. With it, the next run connects without a code.

How to connect Telegram in the Socialift dashboard

1. 1

   Connect the bot

   In “Ulanishlar” (Connections) → “Telegram bot” paste the token and click “Botni ulash” (Connect bot). Socialift checks the token with getMe right away — invalid tokens aren't saved. If privacy mode is on, you'll see a warning. A bot can be connected to only one Socialift user. Bots need nothing on the “Kalitlar” (Keys) page.

2. 2

   Point the bot webhook to Socialift if needed

   The Playground section “Webhook va universal chaqiruv” (Webhook and universal call) sets the bot's webhook to the Socialift server with a separate secret_token per bot. A bot has a single webhook URL: this replaces the one your own server set (and vice versa).

3. 3

   Add the key for accounts

   In “Kalitlar” (Keys) → “Telegram API (my.telegram.org)” enter api_id and api_hash and click “Saqlash va tekshirish” (Save and verify). Socialift checks the format and tests the pair against Telegram with MTProto auth.exportLoginToken — no phone number needed; API_ID_INVALID rejects the key. Without your own key, Socialift's key is used if one is configured.

4. 4

   Connect the account

   “Ulanishlar” → “Telegram akkaunt”: phone number (+998901234567) → “Kod yuborish” (Send code) → the code (usually delivered in the Telegram app, not by SMS) → “Tasdiqlash” (Confirm) → the password if 2FA is on → “Kirish” (Sign in). The intermediate login state lives about 10 minutes.

5. 5

   Disconnecting

   For an account, “Uzish” (Disconnect) also terminates the session on Telegram's side — even a leaked copy of the session stops working.

Bot: token and webhook in the Python SDK

Telegram.from_env() reads TELEGRAM_BOT_TOKEN.

import asyncio
import os

from socialift import Telegram


async def main() -> None:
    # TELEGRAM_BOT_TOKEN, SOCIALIFT_LICENSE_KEY
    async with Telegram.from_env() as bot:
        me = await bot.get_me()  # the cheapest way to validate the token
        print(me["username"], me.get("can_read_all_group_messages"))
        await bot.set_webhook(
            "https://example.com/tg",
            secret_token=os.environ["TG_WEBHOOK_SECRET"],
            allowed_updates=["message"],
        )


asyncio.run(main())

Account: api_id, api_hash and sign-in in the Python SDK

Requires pip install "socialift[telegram]". TelegramAccount.from_env() reads TELEGRAM_API_ID, TELEGRAM_API_HASH and TELEGRAM_SESSION.

import asyncio
import os
from getpass import getpass

from socialift import TelegramAccount


async def main() -> None:
    phone = "+998901234567"
    async with TelegramAccount(api_id=os.environ["TELEGRAM_API_ID"],
                               api_hash=os.environ["TELEGRAM_API_HASH"]) as tg:
        sent = await tg.send_code(phone)
        result = await tg.sign_in(phone, code=input("Code: "), phone_code_hash=sent["phone_code_hash"])
        if result.get("two_factor_required"):
            await tg.sign_in_password(getpass("2FA password: "))
        print(tg.export_session())  # equivalent to a password — store it encrypted


asyncio.run(main())

Common mistakes

• ▸The bot token is left in code, a repository or logs.
• ▸The bot doesn't see group messages — privacy mode is on, or the bot wasn't re-added after /setprivacy.
• ▸getUpdates is called while a webhook is set.
• ▸A webhook without secret_token — anyone who knows the URL can send fake updates.
• ▸The webhook uses an unsupported port or plain HTTP.
• ▸The same bot's webhook is set both on your server and in Socialift — the last setWebhook wins.
• ▸The api_hash is public, or the session string is stored unencrypted.
• ▸Mass messaging or flooding from an account — risk of a permanent ban.
• ▸Waiting for an SMS while the code was delivered in the Telegram app.