nous-hermeshub Telegram Bot API - Integracao Profissional
Overview
Integracao completa com Telegram Bot API. Setup com BotFather, mensagens, webhooks, inline keyboards, grupos, canais. Boilerplates Node.js e Python.
When to Use This Skill
- When the user mentions "telegram" or related topics
- When the user mentions "bot telegram" or related topics
- When the user mentions "telegram bot" or related topics
- When the user mentions "api telegram" or related topics
- When the user mentions "chatbot telegram" or related topics
- When the user mentions "mensagem telegram" or related topics
Do Not Use This Skill When
- The task is unrelated to telegram
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise
How It Works
Skill para implementar bots profissionais no Telegram usando a Bot API oficial. Suporta Node.js/TypeScript e Python.
Overview
A Telegram Bot API permite criar bots que interagem com usuarios via mensagens, comandos, inline keyboards, pagamentos e muito mais. Bots sao criados pelo @BotFather e autenticados via token unico.
Base URL: https://api.telegram.org/bot<TOKEN>/METHOD_NAME
Metodos HTTP: GET e POST
Formatos de parametros: query string, application/x-www-form-urlencoded, application/json, multipart/form-data (uploads)
Limite de arquivos: 50MB download, 20MB upload (via multipart), 50MB via URL
Portas suportadas para webhooks: 443, 80, 88, 8443
Pre-requisitos:
- Conta no Telegram
- Bot criado via @BotFather (fornece o token)
- Token no formato:
123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Se o usuario nao tem um bot criado, oriente a conversar com @BotFather no Telegram e enviar /newbot.
Decision Tree
O usuario precisa criar um bot?
├── SIM → Secao "Setup com BotFather" abaixo
└── NAO → Qual linguagem?
├── Node.js/TypeScript
└── Python
→ O que quer fazer?
├── Enviar mensagens → Secao "Tipos de Mensagem"
├── Receber mensagens → Secao "Receber Updates"
├── Teclados interativos → Secao "Keyboards"
├── Gerenciar grupos/canais → references/chat-management.md
├── Webhook setup → references/webhook-setup.md
├── Inline mode → references/advanced-features.md
├── Pagamentos → references/advanced-features.md
├── Bot de atendimento com IA → Secao "Automacao com IA"
└── Referencia completa da API → references/api-reference.md
Para iniciar um projeto do zero com boilerplate pronto:
python scripts/setup_project.py --language nodejs --path ./meu-bot-telegram
## Ou
python scripts/setup_project.py --language python --path ./meu-bot-telegram
Para testar se o token do bot funciona:
python scripts/test_bot.py --token "SEU_TOKEN"
Para enviar uma mensagem de teste:
python scripts/send_message.py --token "SEU_TOKEN" --chat-id "CHAT_ID" --text "Hello!"
Setup Com Botfather
- Abra o Telegram e busque @BotFather
- Envie
/newbot - Escolha nome de exibicao (ex: "Meu Bot Incrivel")
- Escolha username (deve terminar com "bot", ex:
meu_incrivel_bot) - BotFather retorna o token - guarde com seguranca
- Comandos uteis do BotFather:
/setdescription- descricao do bot/setabouttext- texto "sobre" do bot/setuserpic- foto de perfil/setcommands- lista de comandos/mybots- gerenciar bots existentes/setinline- habilitar inline mode/setprivacy- modo privacidade em grupos
Variaveis De Ambiente
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
Node.Js/Typescript
// Instalar: npm install telegraf dotenv
// Para TypeScript: npm install -D typescript
import { Telegraf } from 'telegraf';
import dotenv from 'dotenv';
dotenv.config();
const bot = new Telegraf(process.env.TELEGRAM_BOT_TOKEN!);
bot.start((ctx) => {
ctx.reply('Ola! Eu sou seu bot. Como posso ajudar?');
});
bot.on('text', (ctx) => {
if (!ctx.message.text.startsWith('/')) {
ctx.reply(`Voce disse: ${ctx.message.text}`);
}
});
bot.launch();
Python
## Instalar: Pip Install Python-Telegram-Bot Python-Dotenv
import os
from dotenv import load_dotenv
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes
load_dotenv()
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text('Ola! Eu sou seu bot. Como posso ajudar?')
async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
await update.message.reply_text(f'Voce disse: {update.message.text}')
app = Application.builder().token(os.getenv('TELEGRAM_BOT_TOKEN')).build()
app.add_handler(CommandHandler('start', start))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))
app.run_polling()
Sem Biblioteca (Http Puro)
import requests
TOKEN = "SEU_TOKEN"
BASE = f"https://api.telegram.org/bot{TOKEN}"
## Verificar Bot
r = requests.get(f"{BASE}/getMe")
print(r.json())
## Enviar Mensagem
r = requests.post(f"{BASE}/sendMessage", json={
"chat_id": "CHAT_ID",
"text": "Hello from pure HTTP!",
"parse_mode": "HTML"
})
print(r.json())
Tipos De Mensagem
O Telegram suporta diversos tipos de conteudo. Todos os metodos aceitam chat_id, reply_parameters (para responder), reply_markup (para keyboards), disable_notification e protect_content.
Html (Recomendado)
await bot.send_message( chat_id=chat_id, text="Negrito, italico, codigo, link", parse_mode="HTML" )
Markdownv2 (Escapar Caracteres Especiais: _ * [ ] ( ) ~ ` > # + - = | { } . !)
await bot.send_message(
chat_id=chat_id,
text="Negrito, italico, codigo, link",
parse_mode="MarkdownV2"
)
## Foto (Por Url, File_Id Ou Upload)
await bot.send_photo(chat_id, photo="https://example.com/img.jpg", caption="Legenda aqui")
## Documento
await bot.send_document(chat_id, document=open("relatorio.pdf", "rb"), caption="Relatorio mensal")
## Video
await bot.send_video(chat_id, video="https://example.com/video.mp4", caption="Assista!")
## Audio
await bot.send_audio(chat_id, audio=open("musica.mp3", "rb"), title="Minha Musica")
## Voz (Ogg Com Opus)
await bot.send_voice(chat_id, voice=open("audio.ogg", "rb"))
## Localizacao
await bot.send_location(chat_id, latitude=-23.5505, longitude=-46.6333)
## Contato
await bot.send_contact(chat_id, phone_number="+5511999999999", first_name="Joao")
## Enquete
await bot.send_poll(
chat_id, question="Qual sua cor favorita?",
options=["Azul", "Verde", "Vermelho"],
is_anonymous=False
)
## Grupo De Midias
await bot.send_media_group(chat_id, media=[
InputMediaPhoto("url1", caption="Foto 1"),
InputMediaPhoto("url2"),
InputMediaVideo("url3")
])
## Acao De Chat (Typing, Upload_Photo, Etc.)
await bot.send_chat_action(chat_id, action="typing")
Node.Js Equivalente
// Foto
bot.sendPhoto(chatId, 'https://example.com/img.jpg', { caption: 'Legenda' });
// Documento
bot.sendDocument(chatId, fs.createReadStream('relatorio.pdf'), { caption: 'Relatorio' });
// Localizacao
bot.sendLocation(chatId, -23.5505, -46.6333);
// Enquete
bot.sendPoll(chatId, 'Qual sua cor favorita?', ['Azul', 'Verde', 'Vermelho']);
Inline Keyboard (Botoes Dentro Da Mensagem)
from telegram import InlineKeyboardButton, InlineKeyboardMarkup
keyboard = InlineKeyboardMarkup([
[InlineKeyboardButton("Opcao A", callback_data="opt_a"),
InlineKeyboardButton("Opcao B", callback_data="opt_b")],
[InlineKeyboardButton("Abrir Site", url="https://example.com")],
[InlineKeyboardButton("Compartilhar", switch_inline_query="texto")]
])
await bot.send_message(chat_id, "Escolha uma opcao:", reply_markup=keyboard)
## Handler De Callback
async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
query = update.callback_query
await query.answer() # Importante: sempre responder o callback
await query.edit_message_text(f"Voce escolheu: {query.data}")
app.add_handler(CallbackQueryHandler(button_callback))
Reply Keyboard (Teclado Customizado)
from telegram import ReplyKeyboardMarkup, KeyboardButton
keyboard = ReplyKeyboardMarkup(
[[KeyboardButton("Enviar Localizacao", request_location=True)],
[KeyboardButton("Enviar Contato", request_contact=True)],
["Opcao 1", "Opcao 2"]],
resize_keyboard=True,
)
await bot.send_message(chat_id, "Escolha:", reply_markup=keyboard)
Remover Teclado
from telegram import ReplyKeyboardRemove
await bot.send_message(chat_id, "Teclado removido", reply_markup=ReplyKeyboardRemove())
Receber Updates
Existem duas formas de receber updates: Long Polling e Webhooks.
Long Polling (Desenvolvimento)
Mais simples, ideal para desenvolvimento. O bot faz requisicoes periodicas ao servidor do Telegram.
## Python-Telegram-Bot Ja Faz Isso Automaticamente
app.run_polling(allowed_updates=Update.ALL_TYPES)
// Telegraf com polling
const bot = new Telegraf(token);
bot.launch();
Webhooks (Producao)
Para producao, webhooks sao mais eficientes. O Telegram envia updates via POST para sua URL HTTPS.
Leia references/webhook-setup.md para configuracao completa com Express, Flask, ngrok e deploy.
Setup rapido:
## Flask Webhook
from flask import Flask, request
import requests
app = Flask(__name__)
TOKEN = "SEU_TOKEN"
BASE = f"https://api.telegram.org/bot{TOKEN}"
@app.route(f"/webhook/{TOKEN}", methods=["POST"])
def webhook():
update = request.get_json()
if "message" in update and "text" in update["message"]:
chat_id = update["message"]["chat"]["id"]
text = update["message"]["text"]
requests.post(f"{BASE}/sendMessage", json={
"chat_id": chat_id,
"text": f"Recebi: {text}"
})
return "OK", 200
## Registrar Webhook
requests.post(f"{BASE}/setWebhook", json={
"url": "https://seu-dominio.com/webhook/" + TOKEN,
"allowed_updates": ["message", "callback_query"],
"secret_token": "seu_secret_seguro_aqui"
})
Comandos Do Bot
Registre comandos para aparecerem no menu do Telegram:
from telegram import BotCommand
await bot.set_my_commands([
BotCommand("start", "Iniciar o bot"),
BotCommand("help", "Ver comandos disponiveis"),
BotCommand("settings", "Configuracoes"),
BotCommand("status", "Ver status do servico"),
])
Via HTTP:
curl -X POST "https://api.telegram.org/bot$TOKEN/setMyCommands" \
-H "Content-Type: application/json" \
-d '{"commands":[{"command":"start","description":"Iniciar o bot"},{"command":"help","description":"Ajuda"}]}'
Automacao Com Ia
Padrao para bot de atendimento com IA (Claude, GPT, etc.):
from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes
import anthropic # ou openai
client = anthropic.Anthropic()
user_conversations = {} # chat_id -> messages history
async def ai_response(update: Update, context: ContextTypes.DEFAULT_TYPE):
chat_id = update.message.chat_id
user_text = update.message.text
# Indicar que esta digitando
await context.bot.send_chat_action(chat_id, "typing")
# Manter historico
if chat_id not in user_conversations:
user_conversations[chat_id] = []
user_conversations[chat_id].append({"role": "user", "content": user_text})
# Chamar IA
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
system="Voce e um assistente prestativo. Responda em portugues.",
messages=user_conversations[chat_id]
)
reply = response.content[0].text
user_conversations[chat_id].append({"role": "assistant", "content": reply})
# Limitar historico (ultimas 20 mensagens)
if len(user_conversations[chat_id]) > 20:
user_conversations[chat_id] = user_conversations[chat_id][-20:]
await update.message.reply_text(reply)
app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, ai_response))
app.run_polling()
Editar Texto
await bot.edit_message_text( chat_id=chat_id, message_id=msg.message_id, text="Texto atualizado!", parse_mode="HTML" )
Editar Markup (Botoes)
await bot.edit_message_reply_markup( chat_id=chat_id, message_id=msg.message_id, reply_markup=new_keyboard )
Deletar Mensagem
await bot.delete_message(chat_id=chat_id, message_id=msg.message_id)
Encaminhar Mensagem
await bot.forward_message( chat_id=dest_chat_id, from_chat_id=source_chat_id, message_id=msg.message_id )
---
## Tratamento De Erros
```python
from telegram.error import TelegramError, BadRequest, TimedOut, NetworkError
async def safe_send(bot, chat_id, text, **kwargs):
"""Envio com retry e tratamento de erros."""
max_retries = 3
for attempt in range(max_retries):
try:
return await bot.send_message(chat_id, text, **kwargs)
except TimedOut:
if attempt < max_retries - 1:
await asyncio.sleep(2 ** attempt)
continue
raise
except BadRequest as e:
if "chat not found" in str(e).lower():
print(f"Chat {chat_id} nao encontrado")
return None
raise
except NetworkError:
if attempt < max_retries - 1:
await asyncio.sleep(2 ** attempt)
continue
raise
Rate Limits
- Mensagens em chat privado: ~30 msg/segundo
- Mensagens em grupo: ~20 msg/minuto por grupo
- Broadcast geral: ~30 msg/segundo no total
- Bulk notifications: use
asyncio.sleep(0.05)entre envios para evitar flood
Se receber erro 429 (Too Many Requests), respeite o retry_after retornado.
Referencia De Arquivos
| Topico | Arquivo |
|---|---|
| Setup de webhooks | references/webhook-setup.md |
| Gerenciamento de chats | references/chat-management.md |
| Recursos avancados | references/advanced-features.md |
| Referencia completa da API | references/api-reference.md |
| Boilerplate Node.js | assets/boilerplate/nodejs/ |
| Boilerplate Python | assets/boilerplate/python/ |
| Exemplos de payloads | assets/examples/ |
Best Practices
- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis
Common Pitfalls
- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis
Related Skills
instagram- Complementary skill for enhanced analysissocial-orchestrator- Complementary skill for enhanced analysiswhatsapp-cloud-api- Complementary skill for enhanced analysis
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.