Telegraph API Wrapper

2.2.0 · active · verified Fri Apr 17

The `telegraph` library is a Python wrapper for the Telegraph publishing platform API, allowing programmatic creation and management of Telegraph pages and accounts. It supports both synchronous and asynchronous operations. The current version is 2.2.0, with releases occurring every few months for new features and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'telegraph.aio'
```
cause Attempting to import the asynchronous client incorrectly or using an outdated import path.

fix Ensure you are using `from telegraph.aio import Telegraph` for the async client. If you see this with the correct import, verify your `telegraph` library version is 2.1.0 or newer.
```
AttributeError: module 'telegraph' has no attribute 'upload_file'
```
cause Trying to use the old top-level `upload_file` function after version 2.1.0, where it was deprecated and moved.

fix Instantiate a `Telegraph` object and call the `upload_file` method on it: `telegraph_instance = Telegraph(); telegraph_instance.upload_file(...)`.
```
telegraph.exceptions.RetryAfterError: Flood control exceeded. Retry in X seconds.
```
cause The Telegraph API rate limits requests. You've sent too many requests in a short period.

fix Implement a retry mechanism with backoff, respecting the `retry_after` seconds provided in the exception. For example, use `asyncio.sleep` or `time.sleep`.

Warnings

breaking Python 2.x is no longer supported. Version 2.0.0 and above require Python 3.
Fix: Upgrade your Python environment to Python 3.6+ to use `telegraph` versions 2.0.0 or later.
deprecated The standalone `telegraph.upload_file` function is deprecated.
Fix: Use the `Telegraph.upload_file` *method* instead, accessible via an instantiated `Telegraph` object (e.g., `telegraph_instance.upload_file(...)`).
gotcha When providing HTML content to `create_page`, ensure it is valid Telegraph-compatible HTML. Invalid or unsupported tags/attributes will raise `telegraph.exceptions.NotAllowedTag`.
Fix: Refer to the Telegraph API documentation for a list of supported HTML tags and attributes. Use simple `p`, `h3`, `a`, `b`, `i`, `strong`, `em`, `ul`, `ol`, `li`, `br`, `img`, `iframe` for best compatibility.

Install

pip install telegraph Install stable version

Imports

Telegraph (sync client)
```
from telegraph import Telegraph
```
Telegraph (async client)
wrong:
```
from telegraph import Telegraph as AsyncTelegraph
```
correct:
```
from telegraph.aio import Telegraph
```
Async client moved to `telegraph.aio` module for clarity and to avoid name clashes.

exceptions

from telegraph.exceptions import RetryAfterError

Quickstart

Initializes the Telegraph client, creates a new account if no access token is provided (or uses an existing one), and then publishes a simple page. Ensure `TELEGRAPH_ACCESS_TOKEN` is set as an environment variable to reuse an existing token.

import os
from telegraph import Telegraph

# Create a Telegraph instance (can reuse existing access_token if available)
# For a fresh start, omit access_token to create a new one.
access_token = os.environ.get('TELEGRAPH_ACCESS_TOKEN', None)
telegraph = Telegraph(access_token=access_token)

if not telegraph.get_access_token():
    # If no access token is set, create a new account
    account_info = telegraph.create_account(
        short_name='MyTestAccount',
        author_name='Test User',
        author_url='https://example.com'
    )
    telegraph.access_token = account_info['access_token']
    print(f"New Telegraph account created. Access Token: {telegraph.access_token}")
else:
    print(f"Using existing Telegraph account with Access Token: {telegraph.access_token}")

# Create a new Telegraph page
response = telegraph.create_page(
    title='My First Telegraph Page',
    author_name='Test User',
    content='<p>Hello from <b>Python</b>!</p><p>This is a test page created programmatically.</p>',
    return_content=True
)

print(f"Page created: {response['url']}")
print(f"Page views: {response['views']}")

view raw JSON →