Ping the current ads.telegram.org session.

Returns owner_id, cabinet (ton/eur/stars), currency, balance.
Does not return api_hash or cookies. Stars cabinets are reported but not used.
If ok=false with code=auth, tell the user to refresh cookies in .env and call reload_session.

Re-read .env (STEL_TOKEN / STEL_SSID / STEL_ADOWNER) and rebuild the HTTP session.

Use this after the user updates cookies on disk. Never pass cookie values as arguments.

List ad cabinets for this Telegram login. Works even on a Stars cabinet so you can switch away.

Switch the active ad cabinet. Then check_session / get_account.

Args:
    owner_id: From list_accounts.

Current cabinet card: owner_id, cabinet, currency (GRAM/EUR), balance.

List ads (100 per page). Filter by status client-side.

Args:
    offset_id: Pagination cursor from next_offset_id.
    status: any | active | on_hold.

Fetch a single ad by id (API method, HTML state, or list fallback).

Create an ad. Gram cabinets allow channels, bots, search, and users (geo). EUR too.

Always create on_hold. Budget "0" cannot go to review. IDs are semicolon-separated.
Search ads: do not pass text/picture/media.
Empty strings are stripped and not sent.

Edit an ad. Only provided fields are sent.

picture=True shows the avatar, picture=False turns it off (sends picture=0).
clear_media=True removes attached photo/video.
budget_action + budget_amount changes total budget (increase resumes a depleted ad).
Targeting cannot be changed after creation — clone_ad instead.

Delete an ad. First call without confirm_hash; pass the returned hash to confirm.

Duplicate an ad into a new draft. Targeting is copied; edit the clone if you need changes.

Validate promote URL + text before create/launch. Surfaces platform errors.

Submit (or resubmit) targeting for review. Requires a non-zero budget.

Create on_hold, add budget, submit for review. Does not activate.

Returns each step so you can see which one failed. Prefer this over calling
create_ad + edit_ad + send_target_to_review by hand.

Render a sponsored-message preview PNG for chat, and save it under TG_ADS_PREVIEW_DIR (default ./previews).

Upload a photo (JPEG/PNG 16:9, <5 MB) or video (MP4 3–60s, <20 MB).

Pass a local file_path OR media_base64 (+ filename). Returns a media hash
to feed into create_ad(media=...) / edit_ad(media=...).

Time-bucketed stats plus CTR / CPC / actual CPM.

period=5min → last 24h in 5-minute buckets. period=day → full lifetime daily.

Search targeting entities.

kind=channel|bot|query|location, or similar_channels/similar_bots (pass ids as semicolon-separated).
purpose=target (placement) vs promote (destination URL lookup). Bots use field=bots vs promote_url.

Countries / languages / topics for user-geo (Gram cabinets have this too) plus channel taxonomies.

Stars cabinets never reach this tool. Empty lists mean the form did not embed that taxonomy.

Custom audiences. action=list|create|rename|delete|clone.

create: pass file_path (one user id per line) or user_ids=[...].
delete/clone: two-step confirm_hash.

Conversion events and pixels. action=list|create|rename|delete|create_pixel.

Funds. Currency follows the cabinet (Gram or EUR) — amount is a string.

action=add (top-up request), transfer, withdraw, search (find a cabinet), list (linked cabinets).

Revoke and regenerate the cabinet API token (IP-whitelist token on ads.telegram.org).

Set the IP whitelist for the cabinet API token. Newline-separated IPs.

Log out of ads.telegram.org for this session. You will need fresh cookies in .env afterwards.