SDK Integration

pip install sidekick-ads

# with framework extras:
pip install sidekick-ads[aiogram]    # aiogram 3.x
pip install sidekick-ads[ptb]        # python-telegram-bot 20+

from sidekick_ads import Sidekick

sk = Sidekick(
    api_key="sk_live_xxxxx",
    platform_id="plt_xxxxx",
)

# in your handler:
result = await sk.inject(
    user_id=message.from_user.id,
    message=llm_reply,
    language_code=message.from_user.language_code,
    is_premium=message.from_user.is_premium,
    keyboard=your_existing_keyboard,  # optional
    parse_mode="HTML",  # optional — matches your bot's parse_mode
    first_name=message.from_user.first_name,  # optional — better targeting
    user_message=message.text,  # optional — better targeting
)

await message.answer(result.message, reply_markup=result.keyboard, parse_mode="HTML")

from sidekick_ads import Sidekick

sk = Sidekick(api_key="sk_live_xxx", platform_id="plt_xxx")

result = await sk.fetch(
    user_id=ctx.from_user.id,
    language_code=ctx.from_user.language_code or "en",
    parse_mode="HTML",  # optional
)

if result.has_ad and result.ad is not None:
    await message.answer(
        f"{llm_reply}\n\n{result.ad.ad_text_formatted}",
        parse_mode="HTML",
        reply_markup={"inline_keyboard": [[
            {"text": result.ad.button_text, "url": result.ad.button_url}
        ]]},
    )
else:
    await message.answer(llm_reply)

from sidekick_ads import Sidekick
from aiogram.types import (
    InlineKeyboardMarkup, InlineKeyboardButton, BufferedInputFile,
)

sk = Sidekick(api_key=..., platform_id=...)

result = await sk.fetch_image(
    user_id=message.from_user.id,
    language_code="en",
    parse_mode="HTML",
)
if result.has_ad and result.ad:
    ad = result.ad
    # SDK already downloaded the bytes — hand straight to InputFile.
    media = BufferedInputFile(ad.image_data, filename=ad.image_filename)
    kb = InlineKeyboardMarkup(inline_keyboard=[[
        InlineKeyboardButton(text=ad.button_text, url=ad.button_url)
    ]])
    caption = ad.ad_text_formatted or ad.ad_text
    if ad.media_type == "animation":
        await message.answer_animation(media, caption=caption,
                                       parse_mode="HTML", reply_markup=kb)
    else:
        await message.answer_photo(media, caption=caption,
                                   parse_mode="HTML", reply_markup=kb)

from aiogram import Bot, Dispatcher, types
from sidekick_ads import Sidekick
from sidekick_ads.middleware import SidekickMiddleware

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

# Register middleware — injects `sidekick` into every handler
sidekick_middleware = SidekickMiddleware(
    api_key="sk_live_xxxxx",
    platform_id="plt_xxxxx",
)
dp.message.middleware(sidekick_middleware)

# Close the HTTP pool cleanly on dispatcher shutdown
dp.shutdown.register(sidekick_middleware.aclose)

@dp.message()
async def handle(message: types.Message, sidekick: Sidekick):
    llm_reply = await get_llm_response(message.text)

    # Your existing keyboard (if any)
    kb = types.InlineKeyboardMarkup(inline_keyboard=[
        [types.InlineKeyboardButton(text="👍", callback_data="like"),
         types.InlineKeyboardButton(text="👎", callback_data="dislike")],
    ])

    result = await sidekick.inject(
        user_id=message.from_user.id,
        message=llm_reply,
        language_code=message.from_user.language_code,
        is_premium=message.from_user.is_premium,
        keyboard=kb,
    )

    await message.answer(result.message, reply_markup=result.keyboard)

from aiogram import Bot, Dispatcher, types
from sidekick_ads import Sidekick

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

sk = Sidekick(api_key="sk_live_xxxxx", platform_id="plt_xxxxx")

@dp.message()
async def handle(message: types.Message):
    llm_reply = await get_llm_response(message.text)

    result = await sk.inject(
        user_id=message.from_user.id,
        message=llm_reply,
        language_code=message.from_user.language_code,
        is_premium=message.from_user.is_premium,
    )

    await message.answer(result.message, reply_markup=result.keyboard)

from telegram import Update, InlineKeyboardMarkup, InlineKeyboardButton
from telegram.ext import ApplicationBuilder, MessageHandler, ContextTypes, filters
from sidekick_ads import Sidekick

sk = Sidekick(api_key="sk_live_xxxxx", platform_id="plt_xxxxx")

async def handle(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user = update.message.from_user
    llm_reply = await get_llm_response(update.message.text)

    kb = InlineKeyboardMarkup([
        [InlineKeyboardButton("👍", callback_data="like"),
         InlineKeyboardButton("👎", callback_data="dislike")],
    ])

    result = await sk.inject(
        user_id=user.id,
        message=llm_reply,
        language_code=user.language_code,
        is_premium=user.is_premium,
        keyboard=kb,
    )

    await update.message.reply_text(result.message, reply_markup=result.keyboard)

app = ApplicationBuilder().token("BOT_TOKEN").build()
app.add_handler(MessageHandler(filters.TEXT, handle))
app.run_polling()

import httpx
from sidekick_ads import Sidekick

sk = Sidekick(api_key="sk_live_xxxxx", platform_id="plt_xxxxx")

async def on_message(user_id: int, text: str, lang_code: str | None, premium: bool | None):
    llm_reply = await get_llm_response(text)

    result = await sk.inject(
        user_id=user_id,
        message=llm_reply,
        language_code=lang_code,
        is_premium=premium,
    )

    # Send via any HTTP client
    async with httpx.AsyncClient() as client:
        await client.post(
            f"https://api.telegram.org/bot{BOT_TOKEN}/sendMessage",
            json={
                "chat_id": user_id,
                "text": result.message,
                **({"reply_markup": result.keyboard} if result.keyboard else {}),
            },
        )

from sidekick_ads import Sidekick
from sidekick_ads.router import sidekick_router

sk = Sidekick(api_key="sk_live_xxxxx", platform_id="plt_xxxxx")

# Handles every sk:* callback tap (consent / quiz steps) for you.
dp.include_router(sidekick_router(sk))

@dp.message()
async def handle(message: types.Message):
    llm_reply = await get_llm_response(message.text)

    result = await sk.inject(
        user_id=message.from_user.id,
        message=llm_reply,
        language_code=message.from_user.language_code,
        parse_mode="HTML",
        accept_formats=["text", "response", "card", "consent", "quiz"],
        capabilities={"rich_messages": True, "callbacks": True, "custom_emoji": True},
        bot_is_admin=False,  # groups: your cached getChatMember(chat, me) result
    )

    # Forwards result.send with chat_id merged in; degrades to the text
    # fallback (result.message + result.keyboard) on any Telegram error.
    await sk.send(bot, message.chat.id, result,
                  receiver_user_id=message.from_user.id)