Telegram.rest
Telegram API for bots and users
The API is an HTTP-based interface created for developers keen on building (user)bots for Telegram.
- To lean how to set up a userbot, see User Mode below.
- To learn how to create and set up a bot, please consult Telegram's Introduction to Bots and Bot FAQ, or the Bot API Documentation.
- An OpenAPI specification can be found at telegram.rest/docs.
Moving a bot to telegram.rest
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 https://api.telegram.org server by calling the method logOut, e.g. https://api.telegram.org/bot{token}/logOut.
After the bot is logged out, you can replace the address to which the bot sends requests with the address of https://telegram.rest instead and use it in the usual way, e.g. https://telegram.rest/bot{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
- Send a request to
https://telegram.rest/userLogin. See userLogin. - Send the received code to
https://telegram.rest/user{user_token}/authCode. See authCode. - Optional: Confirm with your 2FA password at
https://telegram.rest/user{user_token}/authPasswordif needed. See authPassword.
AuthorizationState
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. |
userLogin
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. |
authCode
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 |
authPassword
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. |
Profit
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:
answerCallbackQuerysetMyCommandseditMessageReplyMarkupuploadStickerFilecreateNewStickerSetaddStickerToSetsetStickerPositionInSetdeleteStickerFromSetsetStickerSetThumbsendInvoiceanswerShippingQueryanswerPreCheckoutQuerysetPassportDataErrorssendGamesetGameScoregetGameHighscores
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 telegram.rest/docs 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.