Creating a Client¶
Before working with Telegram’s API, you need to get your own API ID and hash:
- Follow this link and login with your phone number.
- Click under API Development tools.
- A Create new application window will appear. Fill in your application details. There is no need to enter any URL, and only the first two fields (App title and Short name) can currently be changed later.
- Click on Create application at the end. Remember that your API hash is secret and Telegram won’t let you revoke it. Don’t post it anywhere!
Once that’s ready, the next step is to create a
This class will be your main interface with Telegram’s API, and creating
one is very simple:
from telethon import TelegramClient, sync # Use your own values here api_id = 12345 api_hash = '0123456789abcdef0123456789abcdef' client = TelegramClient('some_name', api_id, api_hash)
'some_name' will be used to save your session (persistent
information such as access key and others) as
your disk. This is by default a database file using Python’s
It’s important that the library always accesses the same session file so that you don’t need to re-send the code over and over again. By default it creates the file in your working directory, but absolute paths work too.
Once you have a client ready, simply
This line connects to Telegram, checks whether the current user is authorized or not, and if it’s not, it begins the login or sign up process.
When you’re done with your code, you should always disconnect:
client = TelegramClient(...) try: client.start() ... # your code here finally: client.disconnect()
You can also use a
with block to achieve the same effect:
client = TelegramClient(...) with client: ... # your code here # or with TelegramClient(...) as client: ... # your code here
Wrapping it all together:
from telethon import TelegramClient, sync with TelegramClient('session_name', api_id, api_hash) as client: ... # your code
Just two setup lines.
Please note that if you fail to login around 5 times (or change the first
parameter of the TelegramClient, which is the session
name) you will receive a
FloodWaitError of around 22 hours, so be
careful not to mess this up! This shouldn’t happen if you’re doing things
as explained, though.
If you want to use a proxy, you have to install PySocks (via pip or manual) and then set the appropriated parameters:
import socks client = TelegramClient('session_id', api_id=12345, api_hash='0123456789abcdef0123456789abcdef', proxy=(socks.SOCKS5, 'localhost', 4444) )
proxy= argument should be a tuple, a list or a dict,
consisting of parameters described here.
Manually Signing In¶
Skip this unless you need more control when connecting.
If you need more control, you can replicate what
client.start() is doing behind the scenes
for your convenience. The first step is to connect to the servers:
You may or may not be authorized yet. You must be authorized before you’re able to send any request:
client.is_user_authorized() # Returns True if you can send requests
If you’re not authorized, you need to
phone_number = '+34600000000' client.send_code_request(phone_number) myself = client.sign_in(phone_number, input('Enter code: ')) # If .sign_in raises PhoneNumberUnoccupiedError, use .sign_up instead # If .sign_in raises SessionPasswordNeeded error, call .sign_in(password=...) # You can import both exceptions from telethon.errors.
If you send the code that Telegram sent you over the app through the
app itself, it will expire immediately. You can still send the code
through the app by “obfuscating” it (maybe add a magic constant, like
12345, and then subtract it to get the real code back) or any other
myself is your Telegram user. You can view all the information about
yourself by doing
print(myself.stringify()). You’re now ready to use
the client as you wish! Remember that any object returned by the API has
.stringify() method, and printing these might prove useful.
As a full example:
from telethon import TelegramClient, sync client = TelegramClient('session_name', api_id, api_hash) client.connect() if not client.is_user_authorized(): client.send_code_request(phone_number) me = client.sign_in(phone_number, input('Enter code: '))
Remember that this is the manual process and it’s so much easier to use the code snippets shown at the beginning of the page.
The code shown is just what
.start() will be doing behind the scenes
(with a few extra checks), so that you know how to sign in case you want
to avoid using
input() (the default) for whatever reason. If no phone
or bot token is provided, you will be asked one through
method also accepts a
You can use either, as both will work. Determining which is just a matter of taste, and how much control you need.
Remember that you can get yourself at any time with