Home »
Irenogram FAQ

Irenogram FAQ¶

Here you can find answers to the most common questions about Irenogram.

Why is the API key needed for bots?¶

Unlike the HTTP Bot API — which only requires a bot token — Irenogram directly implements the Telegram MTProto protocol. The MTProto protocol requires every client application to identify itself with an api_id and api_hash obtained from my.telegram.org.

This is not an Irenogram limitation. It is a Telegram requirement for all MTProto clients, whether they act as users or bots.

How to use webhooks?¶

Irenogram does not use webhooks. It is a long-polling MTProto client, meaning it keeps a persistent TCP connection open to Telegram’s servers and receives updates in real time without any HTTP server needed.

If you specifically require webhooks (e.g., for integration with a web framework), consider using the official Telegram HTTP Bot API with a library like python-telegram-bot or aiogram instead.

Using the same file_id across different accounts ¶

file_id values are account-specific. A file_id obtained with one account cannot be used to send files from a different account. This is a Telegram server restriction, not an Irenogram one.

If you need to share files across accounts, download the file first and re-upload it from the target account, or use a publicly accessible URL.

Using multiple clients at once on the same account ¶

Running multiple Client instances for the same account simultaneously is not supported by Telegram and will result in session conflicts and unpredictable behavior.

If you need to run multiple clients in a single script, use different accounts — one per Client instance — and then run them concurrently with compose():

from pyrogram import Client, compose

app1 = Client("account1")
app2 = Client("account2")
app3 = Client("account3")

compose([app1, app2, app3])

Client started, but nothing happens ¶

If your client starts without errors but handlers never fire, the most common causes are:

No event loop running — Make sure you are using app.run() or asyncio.run() rather than calling app.start() without a running loop.
Handler not registered — Double-check that your @app.on_message() decorators are placed before app.run().
Filters are too restrictive — Try removing all filters temporarily to confirm the handler fires at all.
Bot privacy mode — If you are using a bot in a group, ensure privacy mode is disabled via BotFather, or add the bot as an admin.

What are the IP addresses of Telegram Data Centers?¶

Telegram operates five data centers (DCs). Their IP addresses as of the latest known configuration:

DC	IP Address	Port
DC1	149.154.175.53	443
DC2	149.154.167.51	443
DC3	149.154.175.100	443
DC4	149.154.167.91	443
DC5	91.108.56.130	443

Note

These addresses may change. Always refer to the official Telegram developer resources for the latest information.

Migrating the account to another data center ¶

When you first sign in, Irenogram connects to the DC that Telegram assigns to your account. If Telegram migrates your account to a different DC (which can happen automatically), Irenogram handles the migration transparently during the next connection — no action is required from you.

Why is the client reacting slowly in supergroups/channels?¶

Telegram intentionally limits update delivery speed for clients that are members of many large supergroups or channels. This is a server-side rate limit and cannot be bypassed.

To mitigate this:

Reduce the number of large groups/channels the account is a member of.
Use Smart Plugins to ensure handlers are as fast as possible.
Consider processing updates asynchronously so that slow handlers do not block incoming updates.

PEER_ID_INVALID error ¶

This error means Irenogram cannot resolve the peer (user, group, or channel) you specified. Common causes:

You have never interacted with this peer — Telegram only knows about peers that have appeared in your contact list, common chats, or message history. Try forwarding a message from the target user/chat first.
Wrong ID format — Channel and supergroup IDs should be prefixed with -100 when used as integers. Irenogram handles this automatically when you pass a username or invite link.
The peer does not exist — The user/group/channel may have been deleted.

Code hangs when calling stop, restart, add/remove_handler ¶

This usually happens when stop() or restart() is called from within a handler that is still running. Since the client waits for all handlers to finish before stopping, a deadlock occurs.

The fix is to call these methods from a separate task:

import asyncio
from pyrogram import Client

app = Client("my_account")

@app.on_message()
async def handler(client, message):
    # Schedule stop without waiting for it inside the handler
    asyncio.create_task(client.stop())

UnicodeEncodeError: ‘…’ codec can’t encode …¶

This error occurs when your terminal or system encoding does not support certain Unicode characters (e.g., emoji, Arabic script, CJK characters) that appear in messages.

Fix it by setting the PYTHONIOENCODING environment variable before running your script:

$ PYTHONIOENCODING=utf-8 python my_script.py

On Windows, you can also run:

$ chcp 65001

Or configure it permanently in your terminal settings.

Uploading with URLs gives error WEBPAGE_CURL_FAILED ¶

This error means Telegram’s servers were unable to fetch the file from the URL you provided. Common reasons:

The URL is behind a login wall, CAPTCHA, or Cloudflare protection.
The server is blocking Telegram’s IP ranges.
The URL returns a redirect that Telegram does not follow.
The file at the URL is too large for Telegram’s downloader.

Solution: Download the file locally and upload it directly instead of passing a URL.

sqlite3.OperationalError: database is locked ¶

This error means another process is already using the same .session SQLite file.

Causes:

You are running two instances of the same client simultaneously.
A previous run crashed without closing the database properly.

Fix:

Make sure only one instance of your script is running.
If the error persists after a crash, delete the .session file and re-authorize, or switch to a different storage engine.

sqlite3.InterfaceError: Error binding parameter ¶

This error typically occurs when a value being stored in the session database is of an unexpected Python type. This is usually a bug — please open an issue on GitHub with a minimal reproducible example.

socket.send(), OSError(), TimeoutError(), Connection lost/reset, …¶

These are network-level errors that indicate the connection to Telegram’s servers was interrupted. Irenogram handles most of these automatically by reconnecting. If you see them frequently, check:

Your network connection stability.
Whether Telegram servers are having issues (check downdetector.com).
Whether you are behind a restrictive firewall or NAT. Consider using a proxy.
Whether your machine’s clock is significantly out of sync (MTProto is sensitive to clock skew).

How to avoid Flood Waits?¶

A FloodWait exception means you have exceeded Telegram’s rate limits for a particular action. Telegram does not publish exact limits, but general guidelines are:

Do not send more than ~20 messages per minute to the same chat.
Add delays between bulk operations (e.g., adding members, sending messages to many users).
Cache peer information to avoid repeated resolve_peer calls.
Handle FloodWait explicitly in your code:

import asyncio
from pyrogram.errors import FloodWait

async def safe_send(app, chat_id, text):
    while True:
        try:
            await app.send_message(chat_id, text)
            break
        except FloodWait as e:
            print(f"Flood wait: sleeping {e.value}s")
            await asyncio.sleep(e.value)

The account has been limited/deactivated ¶

If your account is displaying a “limited” or “deactivated” banner, this is a Telegram-side restriction and Irenogram cannot bypass it. Common reasons:

Sending spam or bulk unsolicited messages.
Rapidly joining and leaving groups.
Using automation in ways that violate Telegram’s Terms of Service.

To appeal, use the Telegram support bot or contact Telegram support directly.

Warning

Using Irenogram to automate actions that violate Telegram’s Terms of Service may result in a permanent ban. Always use the library responsibly.