Telegram API for bots and users

The API is an HTTP-based interface created for developers keen on building (user)bots for Telegram.

Moving a bot to

If the bot is logged in on more than one server simultaneously, there is no guarantee that it will receive all updates. To guarantee that your bot will receive all updates, you must deregister it with the server by calling the method logOut, e.g.{token}/logOut. After the bot is logged out, you can replace the address to which the bot sends requests with the address of instead and use it in the usual way, e.g.{token}/getMe.

Similarly, if you want to go back you can repeat the procedure with the server urls reversed.

User Mode

You can now log into the bot api with user accounts to create userbots running on your account.

Note: Never send your 2FA password over a plain http:// connection in the internet. Make sure you always use https://.

User Authorization Process

  1. Send a request to See userLogin.
  2. Send the received code to{user_token}/authCode. See authCode.
  3. Optional: Confirm with your 2FA password at{user_token}/authPassword if needed. See authPassword.


Used in the User Authorization process, to return the current state of the authorization and the token.

Field Type Description
authorization_state String Returns the current state of the authorization process. Is one of wait_code, wait_password, wait_registration, ready or unknown.
token String Optional. Token to be used for calling methods at the bot api. Only returned once after the userlogin method.
timeout Integer Optional. Timeout for entering the authorization code.
password_hint String Optional. The password hint for your 2fa password. May be empty even if you set a hint.
has_recovery_email_address Boolean Optional. True, if a recovery email address has been set up.


Prepares a user session for use, to generate a user11234:abc234 token. On success, an AuthorizationState object is returned. You can use the returned token just like a normal bot token on any the /user{user_token} endpoint as soon as you completed login.

Field Type Required Description
phone_number String Yes The phone number of your Telegram Account.


Supply a authentication code Telegram sent you (In-App or SMS code) to your ongoing login. On success, an AuthorizationState object is returned.

Field Type Required Description
code Integer Yes The code send to you by Telegram In-App or by SMS


Supply your set 2FA password to your ongoing login. This is only needed if you turned on 2-Factor-Authentication in your account's security settings. On success, an AuthorizationState object is returned.

Field Type Required Description
password String Yes The personal password you set for 2-Factor-Authentication.

You are now logged in and can use all methods like in the bot api, just replace the /bot{bot_token}/ in your urls with /user{token}/.

You only need to authenticate once, the account will stay logged in. You can use the logOut method to log out or simply close the session in your account settings.

Userbot limitations

Some methods are (obviously) not available as a user. This includes:

It is also not possible to attach a reply_markup to any message.

Your api wrapper may behave different in some cases, for examples command message-entities are not created in chats that don't contain any bots, so your command handler may not detect it if it relies on those.

It is possible to log in multiple times to the same account on the same API server. This will result in different user_tokens, and they can be used simultaneously.

Bot Mode

The bot mode can be used as usual.

Best to check out the OpenAPI documentation at for an interactive documentation, or if you prefer the tables telegram delivers, consult Telegram's Bot API Documentation. If you need a refresher what it's all about the official Introduction to Bots and Bot FAQ might be of help as well.

Disclaimer: We are not affiliated, associated, authorized, endorsed by, or in any way officially connected with Telegram or, or any of its subsidiaries or its affiliates.
The official Telegram website can be found at is powered by tdlight,