telegram
Integracao completa com Telegram Bot API. Setup com BotFather, mensagens, webhooks, inline keyboards, grupos, canais. Boilerplates Node.js e Python.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- telegram
- risk
- critical
- tags
- [ "messaging", "telegram", "bots", "webhooks" ]
- tools
- [ "claude-code", "antigravity", "cursor", "gemini-cli", "codex-cli" ]
- author
- renat
- source
- community
- date_added
- 2026-03-06
- description
- Integracao completa com Telegram Bot API. Setup com BotFather, mensagens, webhooks, inline keyboards, grupos, canais. Boilerplates Node.js e Python.
02 资源文件 19
- 资产文件assets/boilerplate/nodejs/.env.example286 B
- 资产文件assets/boilerplate/nodejs/package.json559 B
- 脚本assets/boilerplate/nodejs/src/bot-client.ts2.5 KB
- 脚本assets/boilerplate/nodejs/src/handlers.ts2.2 KB
- 脚本assets/boilerplate/nodejs/src/index.ts951 B
- 资产文件assets/boilerplate/nodejs/tsconfig.json394 B
- 资产文件assets/boilerplate/python/.env.example286 B
- 脚本assets/boilerplate/python/bot.py3.6 KB
- 资产文件assets/boilerplate/python/requirements.txt77 B
- 脚本assets/boilerplate/python/webhook_server.py3.0 KB
- 资产文件assets/examples/inline-keyboard.json1.9 KB
- 资产文件assets/examples/webhook-payloads.json3.6 KB
- 参考文档references/advanced-features.md9.5 KB
- 参考文档references/api-reference.md7.7 KB
- 参考文档references/chat-management.md7.6 KB
- 参考文档references/webhook-setup.md7.6 KB
- 脚本scripts/send_message.py5.4 KB
- 脚本scripts/setup_project.py3.6 KB
- 脚本scripts/test_bot.py5.5 KB
03 SKILL.md 正文
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 node-telegram-bot-api dotenv
// Para TypeScript: npm install -D @types/node-telegram-bot-api typescript
import TelegramBot from 'node-telegram-bot-api';
import dotenv from 'dotenv';
dotenv.config();
const bot = new TelegramBot(process.env.TELEGRAM_BOT_TOKEN!, { polling: true });
bot.onText(/\/start/, (msg) => {
bot.sendMessage(msg.chat.id, 'Ola! Eu sou seu bot. Como posso ajudar?');
});
bot.on('message', (msg) => {
if (msg.text && !msg.text.startsWith('/')) {
bot.sendMessage(msg.chat.id, `Voce disse: ${msg.text}`);
}
});
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="<b>Negrito</b>, <i>italico</i>, <code>codigo</code>, <a href='https://example.com'>link</a>", 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,
one_time_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)
// node-telegram-bot-api com polling
const bot = new TelegramBot(token, { polling: true });
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.
04 同仓库更多 Skills
vercel-sandbox
Run agent-browser + Chrome inside Vercel Sandbox microVMs for browser automation from any Vercel-deployed app. Use when the user needs browser automation in a Vercel app (Next.js, SvelteKit, Nuxt, Remix, Astro, etc.), wants to run headless Chrome without binary size limits, needs persistent browser sessions across commands, or wants ephemeral isolated browser environments. Triggers include "Vercel Sandbox browser", "microVM Chrome", "agent-browser in sandbox", "browser automation on Vercel", or any task requiring Chrome in a Vercel Sandbox.
slack
Interact with Slack workspaces using browser automation. Use when the user needs to check unread channels, navigate Slack, send messages, extract data, find information, search conversations, or automate any Slack task. Triggers include "check my Slack", "what channels have unreads", "send a message to", "search Slack for", "extract from Slack", "find who said", or any task requiring programmatic Slack interaction.
electron
Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include "automate Slack app", "control VS Code", "interact with Discord app", "test this Electron app", "connect to desktop app", or any task requiring automation of a native Electron application.
dogfood
Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", "test this app/site/platform", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams.
agent-browser
Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
shadcn
Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui.