Pwrtelegram API

Version 2.
Licensed under AGPLv3.

API status

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:

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.

Features:

All of the official telegram bot API features plus:

How do I enable it?

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.

Then, if you intend to use the API to download/upload files, you must set a custom backend (scroll down to see how to do that).

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.

How do I use it?

Just use it as you would use the official telegram bot API, only bear in the following points.

Logging in as a normal user

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.

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

If the number you used doesn’t have a telegram account, the following json will be returned:

{"ok": false, "error_code": 401, "description": "Need to sign up: call the completesignup method"}

In this case you must complete login by calling the completesignup method (last_name is optional):

https://api.pwrtelegram.xyz/userhjJhh-_3838rhehhH2/completesignup?first_name=Urlencoded%20first%20name&last_name=last%20name

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):

A lot of other methods are supported, to see a full list click here.

Sending text buttons in inline keyboards and text mentions for users without a user id

Simply call the sendMessage method with the mtproto parameter set to true.

Inline keyboards with only the text field will be interpreted as text buttons and when the user will press that button the specified text will be sent in the chat, just like for normal keyboards.

To send text mentions use markdown or html links with the following syntax for the url: mention:userid or mention:@username. That will send a text mention with the text you specified in the markup mentioning the user you specified.

Please note that bot API object conversion isn’t 100% ready, so any message you’ve replied to won’t be shown.

Getting mtproto updates

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).

Uploading files with the mtproto api

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.

getChatByFile

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)

madeline

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.

getChat

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!

getUpdates and webhook requests.

The response of these requests will be passed trough a piece of code that will filter out messages from @pwrtelegramapi.

getFile requests.

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.

sendDocument, sendPhoto, sendVideo, sendAudio, sendVoice, sendSticker requests.

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:

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.

sendFile

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:

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.

uploadFile, uploadDocument, uploadAudio, uploadVideo, uploadVoice, uploadPhoto, uploadSticker

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:

Otherwise the error is returned.

deleteMessages

Use this method to delete any messages sent by the bot or by any user in any group or private char.
On success, if the message is deleted by the bot, a json array is returned with the following values:

Otherwise the error is returned.

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)
ids Integer Yes Json array containing the ids of the messages to delete

You can use both getupdates and webhooks to get updates

Only remember that you will have to repeat the setwebhook request to enable proxying trough the PWRTelegram API.

answerInlineQuery

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.

getBackend

This method returns a Chat object with info about the backend pwrtelegram user.

getMessage

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

sendChatAction

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.

getProfilePhotos

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.

Known bugs

See the issues of the repos of the pwrtelegram organization.

How can I help?

You can help by doing one or more of the following things:

More info

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