antigravity-skills-reference/skills/telegram/references/advanced-features.md

Recursos Avancados - Telegram Bot

Table of Contents

1. Inline Mode
2. Pagamentos (Telegram Stars)
3. Mini Apps (WebApps)
4. Conversation Handlers (FSM)
5. Stickers
6. Games
7. Passport
8. Business Bots
9. Message Drafts (Streaming)

---

Inline Mode

Permite que usuarios usem o bot em qualquer chat digitando @seubot consulta.

Habilitar: Fale com @BotFather e envie /setinline.

from telegram import Update, InlineQueryResultArticle, InputTextMessageContent
from telegram.ext import InlineQueryHandler

async def inline_query(update: Update, context):
    query = update.inline_query.query
    if not query:
        return

    results = [
        InlineQueryResultArticle(
            id="1",
            title=f"Resultado para: {query}",
            input_message_content=InputTextMessageContent(
                message_text=f"Voce buscou: {query}"
            ),
            description="Clique para enviar"
        ),
        InlineQueryResultArticle(
            id="2",
            title="Busca em maiusculas",
            input_message_content=InputTextMessageContent(
                message_text=query.upper()
            )
        )
    ]

    await update.inline_query.answer(results, cache_time=10)

app.add_handler(InlineQueryHandler(inline_query))

Tipos de resultado inline

• InlineQueryResultArticle - texto generico
• InlineQueryResultPhoto - foto com preview
• InlineQueryResultGif - GIF
• InlineQueryResultVideo - video
• InlineQueryResultAudio - audio
• InlineQueryResultDocument - documento
• InlineQueryResultLocation - localizacao
• InlineQueryResultVenue - local/estabelecimento
• InlineQueryResultContact - contato
• InlineQueryResultCachedPhoto - foto ja no servidor Telegram

---

Pagamentos (Telegram Stars)

Telegram permite pagamentos via Stars (moeda interna) para bens digitais.

from telegram import LabeledPrice

# Enviar invoice
await bot.send_invoice(
    chat_id=chat_id,
    title="Assinatura Premium",
    description="Acesso premium por 30 dias",
    payload="premium_30days",
    currency="XTR",  # XTR = Telegram Stars
    prices=[LabeledPrice("Assinatura Premium", 100)],  # 100 Stars
)

# Handler de pre-checkout
async def precheckout(update: Update, context):
    query = update.pre_checkout_query
    if query.invoice_payload == "premium_30days":
        await query.answer(ok=True)
    else:
        await query.answer(ok=False, error_message="Payload invalido")

# Handler de pagamento concluido
async def successful_payment(update: Update, context):
    payment = update.message.successful_payment
    await update.message.reply_text(
        f"Pagamento recebido! {payment.total_amount} Stars. "
        f"Seu acesso premium foi ativado."
    )

app.add_handler(PreCheckoutQueryHandler(precheckout))
app.add_handler(MessageHandler(filters.SUCCESSFUL_PAYMENT, successful_payment))

Provedores de pagamento externos

Para bens fisicos, use provedores como Stripe, YooMoney, etc:

await bot.send_invoice(
    chat_id=chat_id,
    title="Camiseta Bot Telegram",
    description="Camiseta tamanho M, algodao",
    payload="tshirt_m",
    provider_token="SEU_PROVIDER_TOKEN",  # do BotFather
    currency="BRL",
    prices=[
        LabeledPrice("Camiseta", 5990),  # R$ 59.90 (em centavos)
        LabeledPrice("Frete", 1500)       # R$ 15.00
    ],
    need_shipping_address=True,
    need_name=True,
    need_phone_number=True
)

---

Mini Apps (WebApps)

Mini Apps sao aplicacoes web que rodam dentro do Telegram.

from telegram import WebAppInfo, InlineKeyboardButton, InlineKeyboardMarkup

# Botao que abre Mini App
keyboard = InlineKeyboardMarkup([
    [InlineKeyboardButton(
        "Abrir App",
        web_app=WebAppInfo(url="https://seu-app.com")
    )]
])
await bot.send_message(chat_id, "Clique para abrir:", reply_markup=keyboard)

# Via Reply Keyboard
from telegram import ReplyKeyboardMarkup, KeyboardButton
keyboard = ReplyKeyboardMarkup([
    [KeyboardButton("Abrir App", web_app=WebAppInfo(url="https://seu-app.com"))]
])

Receber dados do Mini App

async def web_app_data(update: Update, context):
    data = update.effective_message.web_app_data.data
    # data e uma string JSON enviada pelo Mini App
    import json
    parsed = json.loads(data)
    await update.message.reply_text(f"Recebi do app: {parsed}")

app.add_handler(MessageHandler(filters.StatusUpdate.WEB_APP_DATA, web_app_data))

---

Conversation Handlers (FSM)

Para dialogos multi-passo (formularios, wizards):

from telegram.ext import ConversationHandler, CommandHandler, MessageHandler, filters

# Estados
NAME, AGE, CONFIRM = range(3)

async def start_form(update: Update, context):
    await update.message.reply_text("Qual seu nome?")
    return NAME

async def get_name(update: Update, context):
    context.user_data['name'] = update.message.text
    await update.message.reply_text("Qual sua idade?")
    return AGE

async def get_age(update: Update, context):
    context.user_data['age'] = update.message.text
    name = context.user_data['name']
    age = context.user_data['age']
    keyboard = InlineKeyboardMarkup([
        [InlineKeyboardButton("Confirmar", callback_data="confirm"),
         InlineKeyboardButton("Cancelar", callback_data="cancel")]
    ])
    await update.message.reply_text(
        f"Nome: {name}\nIdade: {age}\n\nConfirma?",
        reply_markup=keyboard
    )
    return CONFIRM

async def confirm(update: Update, context):
    query = update.callback_query
    await query.answer()
    if query.data == "confirm":
        await query.edit_message_text("Cadastro realizado com sucesso!")
    else:
        await query.edit_message_text("Cadastro cancelado.")
    return ConversationHandler.END

async def cancel(update: Update, context):
    await update.message.reply_text("Operacao cancelada.")
    return ConversationHandler.END

conv_handler = ConversationHandler(
    entry_points=[CommandHandler('cadastro', start_form)],
    states={
        NAME: [MessageHandler(filters.TEXT & ~filters.COMMAND, get_name)],
        AGE: [MessageHandler(filters.TEXT & ~filters.COMMAND, get_age)],
        CONFIRM: [CallbackQueryHandler(confirm)],
    },
    fallbacks=[CommandHandler('cancel', cancel)],
    conversation_timeout=300  # 5 minutos timeout
)
app.add_handler(conv_handler)

---

Stickers

# Enviar sticker por file_id
await bot.send_sticker(chat_id, sticker="CAACAgIAAxkBAAI...")

# Obter sticker set
sticker_set = await bot.get_sticker_set("set_name")
for sticker in sticker_set.stickers:
    print(f"Emoji: {sticker.emoji}, ID: {sticker.file_id}")

# Criar sticker set (requer imagem 512x512 PNG/WEBP)
await bot.create_new_sticker_set(
    user_id=user_id,
    name="meupack_by_meubot",
    title="Meu Sticker Pack",
    stickers=[InputSticker(
        sticker=open("sticker.webp", "rb"),
        emoji_list=["😀"],
        format="static"
    )]
)

# Adicionar sticker ao set
await bot.add_sticker_to_set(
    user_id=user_id,
    name="meupack_by_meubot",
    sticker=InputSticker(
        sticker=open("sticker2.webp", "rb"),
        emoji_list=["😎"],
        format="static"
    )
)

---

Games

# Enviar jogo (precisa registrar no BotFather com /newgame)
await bot.send_game(chat_id, game_short_name="meu_jogo")

# Handler de callback para jogo
async def game_callback(update: Update, context):
    query = update.callback_query
    await query.answer(url="https://seu-jogo.com/?user_id=" + str(query.from_user.id))

# Salvar score
await bot.set_game_score(
    user_id=user_id,
    score=150,
    chat_id=chat_id,
    message_id=game_message_id
)

# Obter high scores
scores = await bot.get_game_high_scores(
    user_id=user_id,
    chat_id=chat_id,
    message_id=game_message_id
)

---

Business Bots

Bots para contas Business do Telegram:

# Receber conexao business
async def business_connection(update: Update, context):
    conn = update.business_connection
    if conn.is_enabled:
        print(f"Bot conectado ao business de {conn.user.first_name}")
    else:
        print(f"Bot desconectado do business de {conn.user.first_name}")

# Receber mensagens business
async def business_message(update: Update, context):
    msg = update.business_message
    # Responder em nome do business
    await context.bot.send_message(
        chat_id=msg.chat.id,
        text="Obrigado pela mensagem! Responderemos em breve.",
        business_connection_id=msg.business_connection_id
    )

app.add_handler(BusinessConnectionHandler(business_connection))
app.add_handler(BusinessMessagesHandler(business_message))

---

Message Drafts (Streaming)

Para respostas longas (como de IA), use drafts para dar feedback em tempo real:

import requests

TOKEN = "SEU_TOKEN"
BASE = f"https://api.telegram.org/bot{TOKEN}"

def stream_response(chat_id, full_text):
    """Simula streaming enviando drafts parciais."""
    words = full_text.split()
    partial = ""

    # Enviar draft inicial
    for i, word in enumerate(words):
        partial += word + " "
        if i % 5 == 0:  # Atualizar a cada 5 palavras
            requests.post(f"{BASE}/sendMessageDraft", json={
                "chat_id": chat_id,
                "text": partial.strip() + "..."
            })

    # Enviar mensagem final
    requests.post(f"{BASE}/sendMessage", json={
        "chat_id": chat_id,
        "text": full_text
    })

Nota: sendMessageDraft e um metodo recente. Verifique disponibilidade na versao da API que esta usando.