telead

A Python library for the Telegram Ads API (https://promoteapi.telegram.org).

It covers every method in the API documentation — accounts, related accounts and budget transfers, ads, uploads, stats and reports, retargeting audiences, the Pixel Tag and the targeting catalogue — and adds what you would otherwise write yourself: typed responses, automatic idempotency keys, safe retries, pagination, schedule builders and local validation against the documented caps.

from telead import Client, InputAdTargetChannels

client = Client("<ACCESS_TOKEN>")

ad = client.create_ad(
    title="Autumn launch",
    text="Everything you need to know about the launch, in one channel.",
    promote_url="https://t.me/mychannel",
    cpm=2.5,
    placement="channel_post",
    target=InputAdTargetChannels(channel_ids=["@somechannel"]),
    initial_budget=50,
)
print(ad.ad_id, ad.status)

The access token is at ads.telegram.org/account/api.

Install

pip install telead

Python 3.9+. The only runtime dependency is requests. Upgrade with pip install -U telead; releases are listed on PyPI.

Documentation

https://elimeshi1.github.io/TeleAd/, built from docs/ with MkDocs Material.

Build the site locally with:

pip install -r docs/requirements.txt
mkdocs serve

At a glance

from telead import Client, InputAdSchedule, InputAdTargetUsers

with Client(token) as client:
    # Balances are in the account's own currency: EUR, TON or XTR.
    account = client.get_current_account()

    # Every ad, page after page.
    for ad in client.iter_ads():
        print(ad.ad_id, ad.status, ad.views, ad.ctr)

    # A photo ad for German-speaking Android users, weekday office hours.
    photo = client.upload_ad_photo("banner.jpg")
    client.create_ad(
        title="DACH — Android",
        text="Die App für dein Team.",
        photo_id=photo.photo_id,
        promote_url="https://t.me/mybot",
        cpm=3,
        placement="channel_post",
        target=InputAdTargetUsers(country_codes=["DE", "AT", "CH"], device="android"),
        schedule=InputAdSchedule.weekly(
            {d: range(9, 18) for d in ("mon", "tue", "wed", "thu", "fri")}, timezone=3600),
        initial_budget=100,
    )

    # Agencies: act on a related account, move budget, wait for the transfer.
    acme = client.with_account("rel-123")
    final = client.wait_for_transaction(client.increase_account_budget("rel-123", 50))

Calls that move money or create things carry an idempotency key automatically, so a retry after a dropped connection never runs them twice.

Examples

• examples/quickstart.py: the balance, and every ad with its numbers
• examples/create_channel_ad.py: resolve channels, upload a photo, create a scheduled ad
• examples/weekly_report.py: daily stats for every ad, as CSV
• examples/top_up_accounts.py: top up related accounts that run low

Tests

git clone https://github.com/Elimeshi1/TeleAd.git
cd TeleAd
pip install -U pip        # editable installs need pip 21.3 or newer
pip install -e ".[dev]"
pytest

License

MIT. telead is an independent library, not affiliated with or endorsed by Telegram.