Adstelo Python SDK

Monetize your Telegram bot with a single line of code.

Adstelo lets you earn revenue from ads displayed in your Telegram bot — just add two lines to your existing bot and start earning.

---

Table of Contents

• How It Works
• Installation
• Quick Start
• Supported Libraries
  • aiogram v3
  • python-telegram-bot v20+
  • pyTelegramBotAPI (telebot)
  • Telethon
• Configuration Reference
• Getting Your Keys
• FAQ

---

1. You register your bot on Adstelo and get a bot_secret + api_key.
2. You call adstelo.init(...) once at the top of your bot code.
3. The SDK records usage metrics to help Adstelo optimize ad delivery.
4. No message content is ever read or transmitted to Adstelo or any third party. Only high-level usage metrics are sent in the background.

Security: Your Telegram bot token is never transmitted. Only an opaque bot_secret is sent. All requests are HMAC-signed with your API key.

---

Installation

pip install adstelo

Requires Python 3.7+. The only dependency is aiohttp.

---

Quick Start

import adstelo

adstelo.init(
    bot_secret="your-bot-secret",   # From your Adstelo dashboard
    api_key="your-api-key",         # From your Adstelo dashboard
)

# ... rest of your bot code, completely unchanged

That's it. The SDK auto-detects whichever Telegram library you have installed and patches it transparently.

---

Supported Libraries

aiogram v3

import adstelo
from aiogram import Bot, Dispatcher

# ✅ Initialize Adstelo BEFORE creating the Dispatcher
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()

@dp.message()
async def handle_message(message):
    await message.answer("Hello!")

# Run your bot as usual
import asyncio
asyncio.run(dp.start_polling(bot))

---

python-telegram-bot v20+

import adstelo
from telegram.ext import Application, MessageHandler, filters

# ✅ Initialize Adstelo BEFORE building the Application
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

async def handle_message(update, context):
    await update.message.reply_text("Hello!")

app = Application.builder().token("YOUR_BOT_TOKEN").build()
app.add_handler(MessageHandler(filters.TEXT, handle_message))
app.run_polling()

---

pyTelegramBotAPI (telebot)

Synchronous:

import adstelo
import telebot

# ✅ Initialize Adstelo BEFORE creating the TeleBot instance
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

bot = telebot.TeleBot("YOUR_BOT_TOKEN")

@bot.message_handler(func=lambda m: True)
def handle_message(message):
    bot.send_message(message.chat.id, "Hello!")

bot.infinity_polling()

Async:

import adstelo
from telebot.async_telebot import AsyncTeleBot
import asyncio

adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

bot = AsyncTeleBot("YOUR_BOT_TOKEN")

@bot.message_handler(func=lambda m: True)
async def handle_message(message):
    await bot.send_message(message.chat.id, "Hello!")

asyncio.run(bot.polling())

---

Telethon

import adstelo
from telethon import TelegramClient, events

# ✅ Initialize Adstelo BEFORE creating the TelegramClient
adstelo.init(
    bot_secret="your-bot-secret",
    api_key="your-api-key",
)

client = TelegramClient("my_bot", api_id=12345, api_hash="your_api_hash")
client.start(bot_token="YOUR_BOT_TOKEN")

@client.on(events.NewMessage)
async def handle_message(event):
    await event.reply("Hello!")

client.run_until_disconnected()

---

Configuration Reference

Parameter	Type	Required	Description
bot_secret	str	✅ Yes	Your bot's secret from the Adstelo dashboard. Identifies your bot server-side without exposing your Telegram token.
api_key	str	✅ Yes	Your Adstelo API key. Used to authenticate requests and sign payloads.
cooldown	int | float	❌ No	Per-user event cooldown in seconds. Default: 2. Prevents duplicate events from rapid interactions.

---

Getting Your Keys

1. Sign up at adstelo.com and log in to your dashboard
2. Go to "Register Bot" and submit your bot's Telegram username
3. Once approved, your dashboard will show:
   • bot_secret — unique to each registered bot
   • api_key — tied to your account (used across all your bots)
4. Copy both values and pass them to adstelo.init()

Your api_key is like a password — keep it private and never commit it to version control. Use environment variables:

import os, adstelo
adstelo.init(
    bot_secret=os.environ["ADSTELO_BOT_SECRET"],
    api_key=os.environ["ADSTELO_API_KEY"],
)

---

FAQ

Does this slow down my bot? No. Events are dispatched asynchronously in the background and never block your handlers. The timeout for each request is 3 seconds and errors are silently swallowed.

What if I use a library that isn't listed? The SDK currently supports aiogram v3, python-telegram-bot v20+, pyTelegramBotAPI (sync & async), and Telethon. More libraries are on the roadmap. Open an issue or email support@adstelo.com.

What exactly is tracked? The SDK reports: user ID, chat ID, event type (message, button, photo, video, sticker, inline_query), a timestamp, and whether it was a /start command. No message content is ever read or transmitted.

What is the difference between bot_secret and api_key?

• bot_secret — identifies which bot generated the event. One per bot.
• api_key — authenticates your account. One per publisher account.

Do I need to change anything else in my bot? No. Call adstelo.init() once at startup before your Dispatcher/Application/Bot is created, and everything else stays exactly as-is.

When do I get paid? Earnings from ads displayed in your bot accumulate in your Adstelo dashboard. Withdrawals are processed on request. See adstelo.com for payout details.

---

License

Proprietary — © Adstelo. All rights reserved.