Version 2.
Licensed under AGPLv3.
This repository contains the source code for the pwrtelegram API, a boosted version of the official telegram bot API.
The PWRTelegram API makes use of:
- The Caddy web server.
- PHP 7
- php-mediainfo
- AN AWESOME+++ PHP MTProto client called MadelineProto
- A modified version of proxy.php
- telegram-lua-load
This API is written and maintained by danog (@danogentili on telegram) with the help of the folks over @BotDevelopment, especially itskenny0 (@shitposting on telegram) and Rondoozle (@POTUS on Telegram).
It is hosted by Botstack.
The new PWRTelegram logo was created by @BayernPars.
All of the official telegram bot API features plus:
-
NEW It can fetch any mtproto update, such as name changes, typing notifications, changes of the online status and much more!
-
NEW It can be used with a normal account (with a phone number)!
-
Support for deep telegram bots.
-
Downloading of files up to 1.5 GB in size
-
Anonymous file storage (the URL of downloaded files does not contain your bot's token)
-
Uploading of files up to 1.5 GB in size
-
Uploading of files using an URL
-
Re-uploading of files using a file ID and different file type or file name.
-
Uploading of any file/URL/file ID with automagical type recognition.
-
Uploading of any file/URL/file ID without sending the file to a specific user.
-
Automagical metadata recognition of sent files/URLs/file IDs.
-
Deleting of text messages sent from the bot.
-
Uploading of files bigger than 5 megabytes with inline queries (supports both URLs and direct uploads)
-
Automatical type recognition for files sent using answerinlinequery
-
Both webhooks and getupdates are supported.
-
webhook requests can be recieved even on insecure http servers.
-
Resolving of usernames not only with channels and groups but also with normal users and bots.
-
Added getMessage function!
-
The sendChatAction function now has a duration parameter!
-
Profile pictures of channels and chats can now be fetched!
-
It can obtain info about the user that uploaded a certain file based on the file's file id. Works with stickers (the creator of the sticker pack is shown) and anonymous channel media too.
To enable it simply substitute the URL of the bot telegram API (https://api.telegram.org) with the URL of the pwrtelegram API (https://api.pwrtelegram.xyz for normal bots and https://deepapi.pwrtelegram.xyz for deep telegram bots) in your telegram client.
You can use one of the following commands to do it:
sed -i 's/api\.telegram\.org/api\.pwrtelegram\.xyz/g' client.py
# OR
sed -i 's/api\.telegram\.org/deepapi\.pwrtelegram\.xyz/g' client.py
The client can be written in any language, not necessarily python.
Or you can manually substitute api.telegram.org with api.pwrtelegram.xyz or deepapi.pwrtelegram.xyz in your bot,
If you use webhooks you must recall the setwebhook method.
The API will automagically do the rest :)
Also please insert the following text in the response to the /start command:
This bot makes use of the @pwrtelegram bot API to enhance its features.
Just use it as you would use the official telegram bot API, only bear in the following points.
-
Please do not abuse of the API by uploading and/or downloading illegal or copyrighted material. The pwrtelegram API creator reserves the right to delete any illegal or copyrighted material that is found on his servers.
-
The PWRTelegram API does not store in any way your bot's token but it does store the bot's username, the sha256 sum of uploaded files and the file ID and the size of uploaded and downloaded files.
-
This API won't be able to send big files if getUpdate or webhook requests aren't proxied through it. This is because when the API uploads these files using MadelineProto it must obtain a file_id using the official bot API, and that can be done only by intercepting the incoming update with the file.
-
The methods used by the PWRTelegram API are the same ones used in the official telegram bot API, but they also have some additional features and in certain cases their behaviour is slightly modified (don't worry, that won't break your clients). There are also some methods that work only with the PWRTelegram API. Here's a list:
-
With this API you can use usernames to interact even with normal users and you can get info about bots using their username (with the getChat method).
-
Do not send more than 50 different files (as in files with different sha256sums) without processing updates. Once reached this limit, files will not be sent if there's an unprocessed message from a user that isn't @pwrtelegramapi in front of the message queue (this limitation is only present if you use getupdates).
To login using a phone number, call the phonelogin method while passing the phone number as the phone parameter:
https://api.pwrtelegram.xyz/phonelogin?phone=+3984748839
On success, a temporary access token will be returned:
{"ok": true, "result": "hjJhh-_3838rhehhH2"}
Use it to call the completephonelogin method with the code you received (2fa isn't supported yet).
https://api.pwrtelegram.xyz/userhjJhh-_3838rhehhH2/completephonelogin?code=77486
On success, the permanent access token will be returned:
{"ok": true, "result": "101384885:hjJhh-_3838rhehhH2"}
If 2FA is enabled, the following json will be returned:
{"ok": false, "error_code": 401, "description": "2FA is enabled: call the complete2FALogin method with the password as password parameter (hint: urhint)"}
In this case you must complete login by calling the complete2FALogin method:
https://api.pwrtelegram.xyz/userhjJhh-_3838rhehhH2/complete2FALogin?password=password
On success, the permanent access token will be returned:
{"ok": true, "result": "101384885:hjJhh-_3838rhehhH2"}
If you get a lot of flood wait errors while uploading/downloading files using a normal bot, you can set a custom backend for that bot:
https://api.pwrtelegram.xyz/botTOKEN/setbackend?backend_token=101384885:hjJhh-_3838rhehhH2
To call methods as a logged in user use the following url (params can be passed using GET and POST, arrays must be encoded using json):
https://api.pwrtelegram.xyz/user101384885:hjJhh-_3838rhehhH2/method?param=value
The methods that can be called using the user access token are the following (see https://daniil.it/MadelineProto for more info):
-
upload - Uploads the file uploaded using POST as the
fileparameter to telegram, returns an InputFile object that must be used to generate an InputMedia object, that can be later sent using the sendmedia method. -
enableGetupdates - Enables storing updates and fetching using getUpdates
-
disableGetupdates - Disables storing updates and fetching using getUpdates, you MUST call this method if you only want to use the user as a backend
-
setWebHook - Like in the bot API, enables automatic sending of incoming updates to an http(s) endpoint as a json payload. Custom certificates are supported, too. This method also calls the disableGetUpdates method automatically
-
deleteWebHook - Deletes the webhook
-
getWebHookInfo - Gets info about the set webhook
-
getUpdates - This method accepts an array of options as the first parameter, and returns an array of updates (an array containing the update id and an object of type Update).
-
getChat - Exactly the same usage and response as the getChat method of the main pwrtelegram API
A lot of other methods are supported, to see a full list click here.
NEW
To can fetch any mtproto update, such as name changes, typing notifications, changes of the online status, and so on, call the enableGetMTProtoUpdates method as the bot, and then fetch updates using the getMtprotoUpdates method.
To disable mtproto update fetching run the disableGetMtprotoUpdates method.
You can also set a webhook for mtproto updates, using the setmtprotowebhook method (deletemtprotowebhook unsets it, getmtprotowebhookinfo gets info about the webhook).
To upload a file call the upload method - it Uploads the file uploaded using POST as the file parameter to telegram, returns an InputFile object that must be used to generate an InputMedia object, that can be later sent using the sendmedia method.
Use this method to obtain info about the user that uploaded a certain file based on the file's file id. Works with stickers (the creator of the sticker pack is shown) and anonymous channel media too. Works only with file ids created between November 2016 and January 2017.
| Parameters | Type | Required | Description |
|---|---|---|---|
| file_id | String | Yes | File id of a file |
On success, the following object is returned:
| Name | Type | Required | Description |
|---|---|---|---|
| user_id | Integer | Yes | User id of the user that uploaded the file. For stickers, the creator of the sticker pack. |
| additional | Object | Optional | Additional info about the user id (basically the result of getchat with user_id, not always available) |
Calls an MTProto method using MadelineProto, for a full list of methods see here.
This method accepts the method to call as the method parameter, and the parameters as a json array in the params parameter.
The usage of this method is exactly the same as in the official API except that it supports using usernames of normal users and bots (as every other pwrtelegram method) and returns some additional info like the real_first_name, real_last_name, participants_count, admins_count, kicked_count, description, online (boolean specifying if the user is online), date (last time user was online), the bio and a lot of other info!
The response of these requests will be passed trough a piece of code that will filter out messages from @pwrtelegramapi.
The PWRTelegram API will then return a File object.
You must use the following anonymous url to download the file: https://storage.pwrtelegram.xyz/<file_path> (or https://deepstorage.pwrtelegram.xyz/<file_path> for deep telegram bots).
The anonymous download URL will be in one of the following formats:
https://storage.pwrtelegram.xyz/botusername/filename.ext
https://deepstorage.pwrtelegram.xyz/botusername/filename.ext
This way you will be able to safely share the download URL without exposing your bot's token.
All of the above requests will be processed using the PWRTelegram API.
The usage of these methods is exactly the same as in the official Telegram BOT API, except that if the request contains a file URL instead of the document (or photo, etc) the file will be downloaded and sent with the given parameters.
The same will happen if you send a file ID that links to a file which type is different from the one specified in the URL or if you also provide a file name along with the file ID.
The PWRTelegram API will automagically obtain the metadata of the provided file/URL and send it along with the file itself (only if it isn't already present in the request).
This is the metadata that will be obtained and sent:
-
Video: width, height and duration as width, height and duration
-
Audio: track name, author, duration as title, author, duration
-
Voice: duration as duration
You can also provide a file_name parameter containing the name of the file to be sent (this is useful when sending files from a URL). If this parameter is set the PWRTelegram API will rename the file/URL you sent and resend the file with the new file name.
Use this method to send any file/URL/file ID. This method will automagically recognize the type of file/URL uploaded and send it using the correct telegram method. It will also automagically read file metadata and attach it to the request (only if it isn't already provided in the request). On success, the sent Message is returned.
This is the metadata that will be obtained and sent (only if not present in the request) along with the file:
-
Video: width, height and duration as width, height and duration
-
Audio: track name, author, duration as title, author, duration
-
Voice: duration as duration
| Parameters | Type | Required | Description |
|---|---|---|---|
| chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel, group or user (in the format @username) |
| file | String | Yes | File to send. You can either pass a URL as String to send a file from a URL, or a file ID as a string to re-upload a file already present on the Telegram servers or upload a new file using multipart/form-data. |
| caption | String | Optional | File caption (will only be applied if the sent file/URL is a photo, a video or a document), 0-200 characters |
| duration | Integer | Optional | Duration of the sent file/URL in seconds (will only be applied if the sent file/URL is an audio file, a video or a voice recording) |
| performer | String | Optional | Performer of the sent file/URL (will only be applied if the sent file/URL is an audio file) |
| title | String | Optional | Title of the sent file/URL (will only be applied if the sent file/URL is an audio file) |
| width | Integer | Optional | Width of the sent file/URL (will only be applied if the sent file/URL is a video file) |
| height | Integer | Optional | Height of the sent file/URL (will only be applied if the sent file/URL is a video file) |
| file_name | String | Optional | Name of the file to be sent. If set, the file will be sent with the specified file name. |
| disable_notification | Boolean | Optional | Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
| reply_to_message_id | Integer | Optional | If the message is a reply, ID of the original message |
| reply_markup | InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardHide or ForceReply | Optional | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to hide reply keyboard or to force a reply from the user. |
These methods can be used to upload files to telegram without sending them to a particular user. Their usage is exactly the same as for their sendMethod counterparts, except that the chat_id, disable_notification, reply_to_message_id, reply_markup parameters will be ignored.
On success, they will return a json array containing the following elements:
-
ok => true
-
result =>
-
file_id => Uploaded file id
-
file_type => Uploaded file type
-
file_size => Uploaded file size
Otherwise the error is returned.
Use this method to delete text messages sent by the bot or via the bot (for inline bots).
On success, if the message is deleted by the bot, a json array is returned with the following values:
-
ok => true
-
result => "The message was deleted successfully."
Otherwise the error is returned.
| Parameters | Type | Required | Description |
|---|---|---|---|
| chat_id | Integer or String | No (see description) | Required if inline_message_id is not specified. Unique identifier for the target chat or username of the target channel, group or user (in the format @username) |
| message_id | Integer | No (see description) | Required if inline_message_id is not specified. Unique identifier of the sent message |
| inline_message_id | String | No (see description) | Required if chat_id and message_id are not specified. Identifier of the inline message |
Only remember that you will have to repeat the setwebhook request to enable proxying trough the PWRTelegram API.
The usage of this method is exactly the same as in the official telegram bot api, except that you can provide URLs to files bigger than 5 megabytes and you can set the file type to file to enable automatical type and metadata recognition.
You can also upload files using via POST: you just have to upload the files with parameter name equal to inline_file0 where 0 is the number of the file. The number has to be equal to the array index of the InlineQueryResult that will feature that file. The type_url field of that InlineQueryResult must also be empty.
Please note that it's better to upload the big files using the upload methods and store the file ids instead of uploading them directly using the answerInlineQuery method.
This method returns a Chat object with info about the backend pwrtelegram user.
This message returns a Message object with info about the provided message.
| Parameters | Type | Required | Description |
|---|---|---|---|
| chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel, group or user (in the format @username) |
| message_id | Integer | Yes | Unique identifier of the sent message |
The usage of this method is exactly the same as in the official telegram bot api, except that you can provide a duration parameter in order to keep the action active for a period of time longer than 5 seconds.
The duration parameter accepts an integer.
Use this method to get a list of profile pictures for a user, chat or channel. Returns a [UserProfilePhotos](https://core.telegram.org/bots/api#userprofilephotos] object.
| Parameters | Type | Required | Description |
|---|---|---|---|
| chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel, group or user (in the format @username) |
| offset | Integer | Optional | Sequential number of the first photo to be returned. By default, all photos are returned. |
| limit | Integer | Optional | Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. |
- Please note that this API is still in beta and there might be small bugs. To report them contact Daniil Gentili or open an issue or submit a pull request with a fix or write to @pwrtelegramgroup.
See the issues of the repos of the pwrtelegram organization.
You can help by doing one or more of the following things:
- Proofreading this documentation and sending a message to the official support group if you have some corrections.
- Peer reviewing the source code of this API and reporting bugs by contacting Daniil Gentili or opening an issue or submitting a pull request with a fix or writing to @pwrtelegramgroup.
- Starring the repositories of the project and sharing it around with your friends :)
For questions contact https://telegram.me/danogentili or the official support group.
Share this API and its official channel (https://telegram.me/pwrtelegram) with all of your friends! :)
Feel free to contribute with pull Requests.
Daniil Gentili (http://daniil.it)
Privacy Policy of pwrtelegram.xyz website
Cookie Policy of pwrtelegram.xyz website