API Telegram Bot: Guia Completo 2026

📚 Série: APIs Messaging → API WhatsApp Node.js | WhatsApp Business API | Bot Discord Python | Python Flask API

O que é API Telegram Bot?

API Telegram Bot é interface HTTP oficial (core.telegram.org/bots/api) gratuita e ilimitada para criar bots conversacionais no Telegram (500M+ usuários ativos): enviar/receber mensagens, processar comandos, inline keyboards interativos, pagamentos, grupos até 200k membros, channels broadcast, envio arquivos até 2GB, webhooks real-time. Diferente WhatsApp Business API (pago, limitado), Telegram oferece recursos avançados (bot games, web apps inline, crypto pagamentos) sem custos, rate limits generosos (30 msg/segundo), documentação completa e bibliotecas maduras (python-telegram-bot, Telegraf.js, Aiogram) permitindo criar desde chatbots simples até plataformas complexas.

Diferença crítica: Telegram API = grátis + recursos avançados vs WhatsApp Business = pago + restrições.

---

Criar Primeiro Bot: Passo a Passo

1. Obter Token API

Via @BotFather (bot oficial Telegram):

1. Abrir Telegram → Buscar @BotFather
2. Enviar: /newbot
3. Nome bot: "Meu Assistente IA"
4. Username: "meu_assistente_ia_bot" (deve terminar em _bot)
5. Receber token: 6234567890:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

NUNCA compartilhar token (acesso total bot)

2. Bot Python (python-telegram-bot)

Instalação:

pip install python-telegram-bot[job-queue]

Bot básico (echo):

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes

TOKEN = "SEU_TOKEN_AQUI"

# Comando /start
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(
        "Olá! Sou seu assistente. Como posso ajudar?"
    )

# Responder mensagens texto
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    texto_recebido = update.message.text
    await update.message.reply_text(f"Você disse: {texto_recebido}")

# Main
def main():
    app = Application.builder().token(TOKEN).build()

    # Handlers
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))

    # Rodar
    print("Bot iniciado!")
    app.run_polling()

if __name__ == "__main__":
    main()

Testar: Buscar bot Telegram → /start

3. Bot Node.js (Telegraf)

Instalação:

npm install telegraf

Código:

const { Telegraf } = require('telegraf');

const bot = new Telegraf('SEU_TOKEN_AQUI');

// Comando /start
bot.start((ctx) => {
    ctx.reply('Bem-vindo! Como posso ajudar?');
});

// Comando /ajuda
bot.command('ajuda', (ctx) => {
    ctx.reply(`
Comandos disponíveis:
/start - Iniciar bot
/ajuda - Ver comandos
/status - Status sistema
    `);
});

// Responder texto
bot.on('text', (ctx) => {
    const texto = ctx.message.text;
    ctx.reply(`Recebi: ${texto}`);
});

// Iniciar
bot.launch();
console.log('Bot rodando!');

// Graceful stop
process.once('SIGINT', () => bot.stop('SIGINT'));
process.once('SIGTERM', () => bot.stop('SIGTERM'));

---

Recursos Avançados Telegram API

1. Inline Keyboards (Botões)

Python:

from telegram import InlineKeyboardButton, InlineKeyboardMarkup

async def menu(update: Update, context: ContextTypes.DEFAULT_TYPE):
    keyboard = [
        [
            InlineKeyboardButton("📊 Relatório", callback_data='relatorio'),
            InlineKeyboardButton("⚙️ Config", callback_data='config')
        ],
        [
            InlineKeyboardButton("❓ Ajuda", callback_data='ajuda')
        ]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)

    await update.message.reply_text(
        "Escolha uma opção:",
        reply_markup=reply_markup
    )

# Processar clique botão
async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.callback_query
    await query.answer()  # Remover loading

    opcao = query.data

    if opcao == 'relatorio':
        await query.edit_message_text("Gerando relatório...")
    elif opcao == 'config':
        await query.edit_message_text("Configurações:")
    elif opcao == 'ajuda':
        await query.edit_message_text("Como posso ajudar?")

# Adicionar handler
app.add_handler(CallbackQueryHandler(button_callback))

Node.js (Telegraf):

const { Markup } = require('telegraf');

bot.command('menu', (ctx) => {
    ctx.reply(
        'Escolha opção:',
        Markup.inlineKeyboard([
            [
                Markup.button.callback('📊 Relatório', 'relatorio'),
                Markup.button.callback('⚙️ Config', 'config')
            ],
            [Markup.button.callback('❓ Ajuda', 'ajuda')]
        ])
    );
});

// Processar cliques
bot.action('relatorio', (ctx) => {
    ctx.answerCbQuery();
    ctx.editMessageText('Gerando relatório...');
});

bot.action('config', (ctx) => {
    ctx.answerCbQuery();
    ctx.editMessageText('Configurações...');
});

2. Receber Arquivos (Fotos, Documentos)

Python:

# Receber foto
async def handle_photo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    photo = update.message.photo[-1]  # Maior resolução
    file = await photo.get_file()

    # Download
    await file.download_to_drive(f"foto_{photo.file_id}.jpg")

    await update.message.reply_text("Foto recebida!")

# Receber documento
async def handle_document(update: Update, context: ContextTypes.DEFAULT_TYPE):
    doc = update.message.document
    file_name = doc.file_name

    file = await doc.get_file()
    await file.download_to_drive(file_name)

    await update.message.reply_text(f"Documento {file_name} recebido!")

# Handlers
app.add_handler(MessageHandler(filters.PHOTO, handle_photo))
app.add_handler(MessageHandler(filters.Document.ALL, handle_document))

Enviar arquivo:

async def enviar_relatorio(chat_id):
    with open("relatorio.pdf", "rb") as f:
        await bot.send_document(
            chat_id=chat_id,
            document=f,
            caption="Seu relatório mensal"
        )

3. Webhooks (Produção)

Por que webhooks?

• Polling: Bot consulta API cada X segundos (ineficiente)
• Webhook: Telegram envia updates direto (real-time, escalável)

Setup Python (Flask):

from flask import Flask, request
from telegram import Update
from telegram.ext import Application

app = Flask(__name__)

TOKEN = "..."
WEBHOOK_URL = "https://seudominio.com/webhook"

# Criar application
application = Application.builder().token(TOKEN).build()

@app.route("/webhook", methods=["POST"])
async def webhook():
    update = Update.de_json(request.get_json(force=True), application.bot)
    await application.process_update(update)
    return "ok"

# Configurar webhook
async def setup_webhook():
    await application.bot.set_webhook(
        url=WEBHOOK_URL,
        allowed_updates=["message", "callback_query"]
    )

if __name__ == "__main__":
    import asyncio
    asyncio.run(setup_webhook())
    app.run(port=8080)

Node.js (Express):

const express = require('express');
const { Telegraf } = require('telegraf');

const app = express();
const bot = new Telegraf('TOKEN');

const WEBHOOK_URL = 'https://seudominio.com/webhook';

// Webhook route
app.use(bot.webhookCallback('/webhook'));

// Setar webhook
bot.telegram.setWebhook(WEBHOOK_URL);

app.listen(8080, () => {
    console.log('Webhook ativo na porta 8080');
});

Requisitos webhook:

• HTTPS (obrigatório)
• Certificado SSL válido
• Porta: 443, 80, 88, 8443

4. Grupos e Administração

Adicionar bot a grupo:

# Detectar quando bot adicionado
async def novo_membro(update: Update, context: ContextTypes.DEFAULT_TYPE):
    novos = update.message.new_chat_members

    for membro in novos:
        if membro.id == context.bot.id:  # Bot foi adicionado
            await update.message.reply_text(
                "Obrigado por me adicionar! Use /ajuda para ver comandos."
            )

app.add_handler(MessageHandler(filters.StatusUpdate.NEW_CHAT_MEMBERS, novo_membro))

Comandos admin:

from telegram import ChatPermissions

# Silenciar usuário
async def mute(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if not await is_admin(update.effective_user.id, update.effective_chat.id):
        return await update.message.reply_text("Apenas admins!")

    # ID usuário para silenciar
    user_id = update.message.reply_to_message.from_user.id

    await context.bot.restrict_chat_member(
        chat_id=update.effective_chat.id,
        user_id=user_id,
        permissions=ChatPermissions(can_send_messages=False),
        until_date=None  # Permanente (ou timestamp)
    )

    await update.message.reply_text("Usuário silenciado.")

# Banir
async def ban(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.message.reply_to_message.from_user.id

    await context.bot.ban_chat_member(
        chat_id=update.effective_chat.id,
        user_id=user_id
    )

    await update.message.reply_text("Usuário banido.")

5. Pagamentos (Telegram Stars)

Aceitar pagamentos:

async def comprar(update: Update, context: ContextTypes.DEFAULT_TYPE):
    prices = [{"label": "Plano Premium", "amount": 1990}]  # R$ 19.90

    await context.bot.send_invoice(
        chat_id=update.effective_chat.id,
        title="Plano Premium",
        description="Acesso ilimitado features",
        payload="premium_plan",
        provider_token="",  # Telegram Stars (vazio)
        currency="BRL",
        prices=prices
    )

# Processar pagamento
async def pre_checkout(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.pre_checkout_query
    await query.answer(ok=True)

async def pagamento_sucesso(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("Pagamento confirmado! Bem-vindo ao Premium 🎉")

    # Ativar premium banco
    user_id = update.effective_user.id
    database.ativar_premium(user_id)

# Handlers
app.add_handler(PreCheckoutQueryHandler(pre_checkout))
app.add_handler(MessageHandler(filters.SUCCESSFUL_PAYMENT, pagamento_sucesso))

---

Bot Telegram + GPT-4 (IA Conversacional)

Assistente inteligente completo:

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes
from openai import OpenAI

TELEGRAM_TOKEN = "..."
OPENAI_KEY = "..."

openai_client = OpenAI(api_key=OPENAI_KEY)

# Memória conversas
conversas = {}

async def chat_ia(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id
    mensagem = update.message.text

    # Inicializar conversa
    if user_id not in conversas:
        conversas[user_id] = [
            {"role": "system", "content": "Você é assistente prestativo."}
        ]

    # Adicionar mensagem usuário
    conversas[user_id].append({"role": "user", "content": mensagem})

    # Enviar "digitando..."
    await update.message.chat.send_action("typing")

    # Chamar GPT-4
    response = openai_client.chat.completions.create(
        model="gpt-4-turbo",
        messages=conversas[user_id],
        max_tokens=500
    )

    resposta = response.choices[0].message.content

    # Salvar resposta IA
    conversas[user_id].append({"role": "assistant", "content": resposta})

    # Limitar histórico (últimas 10 msgs)
    if len(conversas[user_id]) > 20:
        conversas[user_id] = conversas[user_id][:1] + conversas[user_id][-19:]

    await update.message.reply_text(resposta)

# Comando resetar conversa
async def reset(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id
    conversas[user_id] = [
        {"role": "system", "content": "Você é assistente prestativo."}
    ]
    await update.message.reply_text("Conversa resetada!")

# Setup
app = Application.builder().token(TELEGRAM_TOKEN).build()
app.add_handler(CommandHandler("reset", reset))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, chat_ia))
app.run_polling()

Adicionar funções (consultar banco):

tools = [
    {
        "type": "function",
        "function": {
            "name": "consultar_pedido",
            "description": "Busca status pedido",
            "parameters": {
                "type": "object",
                "properties": {
                    "numero_pedido": {"type": "string"}
                }
            }
        }
    }
]

response = openai_client.chat.completions.create(
    model="gpt-4-turbo",
    messages=conversas[user_id],
    tools=tools
)

# Se IA chamar função
if response.choices[0].message.tool_calls:
    function_call = response.choices[0].message.tool_calls[0]
    args = json.loads(function_call.function.arguments)

    # Executar
    if function_call.function.name == "consultar_pedido":
        pedido = database.query(f"SELECT * FROM pedidos WHERE numero = '{args['numero_pedido']}'")

        # Retornar resultado pra IA
        conversas[user_id].append({
            "role": "function",
            "name": "consultar_pedido",
            "content": json.dumps(pedido)
        })

        # Gerar resposta final
        final_response = openai_client.chat.completions.create(
            model="gpt-4-turbo",
            messages=conversas[user_id]
        )

---

Casos Reais Telegram Bots

Caso 1: Atendimento E-commerce

Bot: @MinhaLojaBot

Features:

• Consultar pedido (número rastreio)
• Calcular frete (CEP)
• Buscar produtos (nome/categoria)
• Tirar dúvidas (GPT-4 + base conhecimento)

Código (consultar pedido):

async def rastreio(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # /rastreio AA123456789BR
    codigo = context.args[0] if context.args else None

    if not codigo:
        return await update.message.reply_text(
            "Envie: /rastreio SEU_CODIGO"
        )

    # Consultar Correios API
    status = correios_api.rastrear(codigo)

    mensagem = f"""
📦 *Rastreamento {codigo}*

Status: {status['situacao']}
Última atualização: {status['data']}
Local: {status['local']}

Previsão entrega: {status['previsao']}
    """

    await update.message.reply_text(mensagem, parse_mode="Markdown")

app.add_handler(CommandHandler("rastreio", rastreio))

Resultado:

• 2.400 atendimentos/mês via bot
• 73% resolvidos sem humano
• Satisfação: 4.5/5

Caso 2: Bot Finanças Pessoais

Bot: @MeuDinheiroBot

Features:

• Registrar gastos: /gasto 45.90 Almoço
• Ver resumo mês: /resumo
• Categorias: /categorias
• Metas: /meta comida 500

Código:

import sqlite3
from datetime import datetime

# Registrar gasto
async def gasto(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # /gasto 45.90 Almoço
    try:
        valor = float(context.args[0])
        descricao = " ".join(context.args[1:])
    except:
        return await update.message.reply_text(
            "Formato: /gasto VALOR DESCRIÇÃO\nEx: /gasto 45.90 Almoço"
        )

    user_id = update.effective_user.id

    # Salvar banco
    conn = sqlite3.connect("financas.db")
    conn.execute(
        "INSERT INTO gastos (user_id, valor, descricao, data) VALUES (?, ?, ?, ?)",
        (user_id, valor, descricao, datetime.now())
    )
    conn.commit()
    conn.close()

    await update.message.reply_text(f"✅ Gasto R$ {valor:.2f} registrado!")

# Resumo mês
async def resumo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id

    conn = sqlite3.connect("financas.db")
    cursor = conn.execute(f"""
        SELECT SUM(valor), COUNT(*)
        FROM gastos
        WHERE user_id = {user_id}
        AND strftime('%Y-%m', data) = strftime('%Y-%m', 'now')
    """)

    total, qtd = cursor.fetchone()
    conn.close()

    await update.message.reply_text(f"""
📊 *Resumo {datetime.now().strftime('%B')}*

Total gasto: R$ {total:.2f}
Transações: {qtd}
Média/dia: R$ {total/30:.2f}
    """, parse_mode="Markdown")

app.add_handler(CommandHandler("gasto", gasto))
app.add_handler(CommandHandler("resumo", resumo))

Usuários: 12k+ ativos

Caso 3: Bot Notificações Sistema

Bot: @MonitorServidorBot

Alertas automáticos:

import asyncio
import psutil

async def monitorar_servidor(bot, chat_id):
    while True:
        # CPU
        cpu = psutil.cpu_percent(interval=1)

        if cpu > 80:
            await bot.send_message(
                chat_id=chat_id,
                text=f"🚨 *ALERTA CPU*\nUso: {cpu}%",
                parse_mode="Markdown"
            )

        # RAM
        ram = psutil.virtual_memory().percent

        if ram > 85:
            await bot.send_message(
                chat_id=chat_id,
                text=f"🚨 *ALERTA RAM*\nUso: {ram}%",
                parse_mode="Markdown"
            )

        # Disco
        disco = psutil.disk_usage('/').percent

        if disco > 90:
            await bot.send_message(
                chat_id=chat_id,
                text=f"🚨 *ALERTA DISCO*\nUso: {disco}%",
                parse_mode="Markdown"
            )

        await asyncio.sleep(60)  # Checar cada 1min

# Iniciar monitoramento
chat_id_admin = 123456789

async def main():
    app = Application.builder().token(TOKEN).build()

    # Task background
    asyncio.create_task(monitorar_servidor(app.bot, chat_id_admin))

    await app.run_polling()

asyncio.run(main())

---

Rate Limits e Boas Práticas

Limites Telegram

Mensagens:

• Grupos: 20 msg/min por grupo
• Privado: 30 msg/segundo (global)

Evitar ban:

• Não spam
• Não enviar mesmo conteúdo múltiplos users
• Rate limiting interno

Código rate limit:

from collections import defaultdict
import time

rate_limits = defaultdict(list)

def check_rate_limit(user_id, max_requests=5, window=60):
    """Permitir max_requests em window segundos"""
    now = time.time()

    # Limpar requests antigos
    rate_limits[user_id] = [
        t for t in rate_limits[user_id]
        if now - t < window
    ]

    if len(rate_limits[user_id]) >= max_requests:
        return False  # Bloqueado

    rate_limits[user_id].append(now)
    return True  # Permitido

async def handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_id = update.effective_user.id

    if not check_rate_limit(user_id):
        return await update.message.reply_text(
            "Muitas requisições! Aguarde 1 minuto."
        )

    # Processar normalmente
    ...

Logging e Erros

import logging

logging.basicConfig(
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    level=logging.INFO
)

async def error_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
    logging.error(f"Update {update} causou erro {context.error}")

    # Notificar admin
    await context.bot.send_message(
        chat_id=ADMIN_ID,
        text=f"⚠️ Erro bot:\n{context.error}"
    )

app.add_error_handler(error_handler)

---

Próximos passos

1. API WhatsApp Node.js - WhatsApp bots completos
2. WhatsApp Business API - Alternativa WhatsApp
3. Bot Discord Python - Bots Discord
4. Python Flask API - APIs custom
5. Chatbot IA - IA conversacional
6. ChatGPT API Python - Integrar GPT-4

Precisa criar bot Telegram personalizado? A Agência Café Online já desenvolveu para 60+ empresas (ROI médio 800%). Consultoria grátis.

---

Sobre o autor: Felipe Zanoni desenvolve Telegram bots processando 100k+ mensagens/mês com integração GPT-4, webhooks e pagamentos para empresas de todos os tamanhos.

---

💬 Precisa de Ajuda para Implementar?

A Agência Café Online já ajudou dezenas de empresas a implementarem soluções de automação e IA, com resultados reais e mensuráveis.

Fale comigo:

• 📱 WhatsApp: Clique aqui para conversar
• 📸 Instagram: @fe_leads
• 🌐 Site: agenciacafeonline.com.br

💡 Consultoria inicial gratuita para avaliar seu caso e propor uma solução personalizada.

---