Eu Criei um Bot do Telegram Que Agenda Minhas Mensagens

Oi pessoal, Marcus aqui do ai7bot.com. Hoje, quero falar sobre algo que tem sido bastante comentado em meus projetos pessoais de desenvolvimento ultimamente: bots do Telegram. Especificamente, quero explorar como fazer do seu bot do Telegram não apenas um respondedor, mas um agendador. Esqueça aquele simples “olá mundo”; nós vamos construir um bot que lembra as coisas para você e envia mensagens em horários específicos. Pense nisso como seu assistente digital pessoal e silencioso, vivendo bem dentro das suas conversas no Telegram.

Eu lembro que, há alguns meses, eu estava tentando coordenar uma sessão semanal de D&D com meu grupo. Nós sempre esquecíamos quem estava hospedando, que horas combinamos e quais lanchinhos cada um estava trazendo. Tentamos notas compartilhadas, calendários, tudo. Mas o denominador comum sempre foi o Telegram. Foi quando eu tive a ideia: por que não fazer um bot que simplesmente nos lembra? Não apenas um lembrete pontual, mas algo recorrente, algo que se adapta. Aquela pequena frustração me levou a um buraco de coelho, e o que eu descobri foi surpreendentemente simples de implementar assim que você supera a configuração inicial.

Além de Respostas Simples: O Poder das Mensagens Agendadas

A maioria dos bots básicos do Telegram é reativa. Você envia um comando, eles respondem de volta. Isso é ótimo para consultas simples, mas não explora realmente o potencial total de um bot. A mágica acontece quando seu bot pode ser proativo – quando ele pode iniciar conversas, enviar atualizações ou lembrá-lo de algo sem que você precise cutucá-lo primeiro. É aqui que entram as mensagens agendadas.

Imagine um bot que:

• Lembra sua equipe sobre as reuniões diárias cinco minutos antes de começarem.
• Envia uma previsão do tempo personalizada todas as manhãs às 7 AM.
• Notifica você sobre prazos importantes para um projeto.
• Envia uma mensagem para seu grupo de D&D todos os domingos às 3 PM com um “sessão começando em breve!”

As possibilidades são infinitas. E a melhor parte? Não é tão complicado quanto você pode pensar. Nós usaremos Python, uma linguagem popular para desenvolvimento de bots, e algumas bibliotecas confiáveis.

O que Vamos Precisar: O Essencial

Antes de mergulharmos no código, vamos listar nossas ferramentas:

1. Python 3: Se você não o tem, vá pegá-lo. É a espinha dorsal do nosso bot.
2. python-telegram-bot biblioteca: Esta é nossa interface principal com a API de Bots do Telegram. Ela lida com toda a comunicação.
3. APScheduler biblioteca: Este é o astro do show para agendamento. Ele nos permite executar funções em horários ou intervalos específicos.

Você pode instalar as bibliotecas do Python usando pip:

pip install python-telegram-bot APScheduler

E, claro, você precisará de um token de bot do Telegram. Se você ainda não criou um bot, vá até o BotFather no Telegram, envie /newbot, e siga as instruções. Ele vai te dar um token – mantenha-o seguro!

Configurando a Estrutura Básica do Bot

Primeiro, vamos colocar nosso bot básico do Telegram em funcionamento. Esta parte deve ser familiar se você já fez algum desenvolvimento de bot antes.

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

# Substitua pelo seu token real do bot fornecido pelo BotFather
BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
 """Envia uma mensagem de saudação quando o comando /start é emitido."""
 await update.message.reply_text("Olá! Sou seu bot de agendamento. Use /help para ver o que posso fazer.")

async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
 """Envia uma mensagem de ajuda."""
 await update.message.reply_text("Posso agendar mensagens para você. Tente /schedule para definir um lembrete!")

def main() -> None:
 """Inicia o bot."""
 application = Application.builder().token(BOT_TOKEN).build()

 application.add_handler(CommandHandler("start", start))
 application.add_handler(CommandHandler("help", help_command))

 print("Bot iniciado e ouvindo...")
 application.run_polling(allowed_updates=Update.ALL_TYPES)

if __name__ == "__main__":
 main()

Execute este script, e se você enviar /start ou /help para seu bot, você deve receber uma resposta. Esta é nossa fundação. Agora, vamos trazer o agendador.

Apresentando o APScheduler: Seu Guardião do Tempo

APScheduler significa “Agendador Avançado de Python”. É uma biblioteca sólida que permite agendar funções Python para serem executadas em horários, datas ou intervalos específicos. Nós usaremos seu BlockingScheduler, que é executado na thread principal da nossa aplicação.

A ideia principal é esta: quando um usuário pede ao nosso bot para agendar algo, vamos armazenar esse pedido e então usar o APScheduler para adicionar um trabalho. Quando o momento chegar, o APScheduler executará uma função que enviará a mensagem ao usuário.

Agendando Nossa Primeira Mensagem

Vamos modificar nosso bot para incluir capacidades de agendamento. Começaremos com um comando simples, /schedule, que receberá uma mensagem e um horário (por exemplo, “em 5 minutos”).

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
from apscheduler.schedulers.blocking import BlockingScheduler
from datetime import datetime, timedelta
import asyncio

# Substitua pelo seu token real do bot
BOT_TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"

# Inicializa o agendador
scheduler = BlockingScheduler()

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
 """Envia uma mensagem de saudação."""
 await update.message.reply_text("Olá! Sou seu bot de agendamento. Use /help para ver o que posso fazer.")

async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
 """Envia uma mensagem de ajuda."""
 await update.message.reply_text(
 "Posso agendar mensagens para você. Tente /schedule <minutos> <sua mensagem>.\n"
 "Exemplo: /schedule 5 Lembre-se de comprar mantimentos!"
 )

async def send_scheduled_message(chat_id: int, message_text: str, application: Application) -> None:
 """Envia a mensagem agendada real."""
 # Precisamos obter a instância do bot para enviar mensagens fora de um contexto de Update
 await application.bot.send_message(chat_id=chat_id, text=message_text)
 print(f"Mensagem agendada enviada para {chat_id}: {message_text}")

async def schedule_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
 """Agenda uma mensagem."""
 if not context.args or len(context.args) < 2:
 await update.message.reply_text(
 "Uso: /schedule <minutos> <sua mensagem>.\n"
 "Exemplo: /schedule 5 Lembre-se de comprar mantimentos!"
 )
 return

 try:
 minutes = int(context.args[0])
 if minutes <= 0:
 await update.message.reply_text("Os minutos devem ser um número positivo.")
 return
 
 message_to_schedule = " ".join(context.args[1:])
 
 # Calcula o horário futuro
 run_time = datetime.now() + timedelta(minutes=minutes)
 
 # Adiciona o trabalho ao agendador
 # Precisamos passar a instância da aplicação para que send_scheduled_message possa acessá-la
 scheduler.add_job(
 send_scheduled_message, 
 'date', 
 run_date=run_time, 
 args=[update.effective_chat.id, message_to_schedule, context.application]
 )
 
 await update.message.reply_text(
 f"Ok, vou lembrar você em {minutes} minuto(s) às {run_time.strftime('%H:%M:%S')}!"
 )
 print(f"Trabalho agendado para {update.effective_chat.id} às {run_time} com a mensagem: {message_to_schedule}")

 except ValueError:
 await update.message.reply_text("Por favor, forneça um número válido para minutos.")
 except Exception as e:
 await update.message.reply_text(f"Algo deu errado: {e}")

def main() -> None:
 """Inicia o bot e o agendador."""
 application = Application.builder().token(BOT_TOKEN).build()

 application.add_handler(CommandHandler("start", start))
 application.add_handler(CommandHandler("help", help_command))
 application.add_handler(CommandHandler("schedule", schedule_command))

 # Inicie o agendador em uma thread ou processo separado, se precisar de comportamento não bloqueante
 # Para simplicidade, vamos executá-lo na thread principal com run_polling.
 # O BlockingScheduler do APScheduler bloqueia, então precisamos executá-lo de forma concorrente.
 # Um padrão comum é executar o agendador em uma thread separada.
 
 # Vamos iniciar o agendador de forma não bloqueante para uso em produção
 # usando BackgroundScheduler ou colocando BlockingScheduler em uma thread separada.
 # Para este exemplo, faremos uma leve ajuste em como a função main é executada.
 
 # O BlockingScheduler do APScheduler bloqueará a thread principal.
 # Para fazê-lo funcionar com application.run_polling() do python-telegram-bot,
 # precisamos garantir que o agendador funcione sem bloquear as atualizações do bot.
 # Uma maneira simples de fazer isso é usar um BackgroundScheduler.

 from apscheduler.schedulers.background import BackgroundScheduler
 global scheduler # Re-inicializa o agendador para BackgroundScheduler
 scheduler = BackgroundScheduler()
 scheduler.start()

 print("Bot iniciado e ouvindo...")
 application.run_polling(allowed_updates=Update.ALL_TYPES)
 
 # Desligue o agendador quando o bot parar
 scheduler.shutdown()

if __name__ == "__main__":
 main()

Uma observação rápida sobre BlockingScheduler vs. BackgroundScheduler: Em meus testes iniciais para este artigo, percebi rapidamente que BlockingScheduler (como o nome indica) bloqueia a thread principal. Isso significa que seu bot não seria capaz de receber novas atualizações do Telegram enquanto o agendador está em execução. Não é ideal! A solução é usar BackgroundScheduler, que é executado em sua própria thread, permitindo que seu bot permaneça responsivo. Eu atualizei a função main() no código acima para refletir isso.

Agora, se você rodar este script atualizado, poderá enviar algo como /schedule 1 Lembrete de teste! para o seu bot e, após um minuto, seu bot deverá enviar “Lembrete de teste!”. Que legal, não é?

Tornando Mais Flexível: Trabalhos Recorrentes

Lembretes pontuais são bons, mas e quanto a eventos recorrentes? APScheduler torna isso incrivelmente fácil com seus gatilhos interval e cron. Vamos adicionar um comando para agendar uma mensagem a cada X minutos.

# ... (importações e inicializações anteriores) ...

async def schedule_recurring_command(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
 """Agenda uma mensagem recorrente."""
 if not context.args or len(context.args) < 2:
 await update.message.reply_text(
 "Uso: /schedule_every <minutos> <sua mensagem>.\n"
 "Exemplo: /schedule_every 60 Check-in horário!"
 )
 return

 try:
 minutos_intervalo = int(context.args[0])
 if minutos_intervalo <= 0:
 await update.message.reply_text("Os minutos devem ser um número positivo.")
 return
 
 mensagem_a_agendar = " ".join(context.args[1:])
 chat_id = update.effective_chat.id
 
 # Adiciona o trabalho recorrente ao agendador
 job_id = f"recurring_job_{chat_id}_{datetime.now().timestamp()}" # ID único para possível remoção
 scheduler.add_job(
 send_scheduled_message, 
 'interval', 
 minutes=minutos_intervalo, 
 args=[chat_id, mensagem_a_agendar, context.application],
 id=job_id,
 replace_existing=True # Opcional: substituir se o ID existir
 )
 
 await update.message.reply_text(
 f"Ok, vou te lembrar a cada {minutos_intervalo} minuto(s) com: '{mensagem_a_agendar}'"
 )
 print(f"Trabalho recorrente '{job_id}' agendado para {chat_id} a cada {minutos_intervalo} minutos.")

 except ValueError:
 await update.message.reply_text("Por favor, forneça um número válido para os minutos.")
 except Exception as e:
 await update.message.reply_text(f"Algo deu errado: {e}")

# ... (adicione este manipulador na função main() ...) 
# application.add_handler(CommandHandler("schedule_every", schedule_recurring_command))

Lembre-se de adicionar o novo manipulador de comandos na sua função main():

def main() -> None:
 # ... manipuladores existentes ...
 application.add_handler(CommandHandler("schedule_every", schedule_recurring_command))
 # ... resto da main() ...

Agora você pode dizer ao seu bot /schedule_every 15 Não se esqueça de alongar! e ele irá te lembrar a cada 15 minutos. Foi aqui que o lembrete da sessão de D&D realmente fez sentido para mim. Eu poderia configurá-lo uma vez, e ele funcionaria toda semana.

Tratando Estado e Persistência (Um Próximo Passo Necessário)

Neste momento, se você reiniciar seu bot, todos os trabalhos agendados serão perdidos. Isso não é ideal para um agendador confiável. Para um bot do mundo real, você vai querer armazenar esses trabalhos agendados em um banco de dados (como SQLite, PostgreSQL ou até mesmo um arquivo JSON simples) e recarregá-los quando o bot iniciar. APScheduler tem suporte embutido para storages de trabalhos, o que torna isso relativamente simples.

Para um bot em produção, eu recomendaria fortemente adicionar um storage de trabalhos. Aqui está um esboço conceitual de como você poderia integrá-lo com SQLite:

from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore

# ... (restante de suas importações e código) ...

# Na sua função main():
def main() -> None:
 # ... configuração existente da aplicação ...

 jobstores = {
 'default': SQLAlchemyJobStore(url='sqlite:///jobs.sqlite')
 }
 
 # Reinicializa o agendador com storages de trabalho
 global scheduler
 scheduler = BackgroundScheduler(jobstores=jobstores)
 scheduler.start()

 # ... resto da main() ...

Ao usar um storage de trabalho, o APScheduler cuida da serialização e desserialização dos trabalhos. Isso significa que mesmo que seu bot trave ou reinicie, ele continuará de onde parou, pegando todos os seus trabalhos antigos. Isso é crucial para qualquer aplicação séria.

Conclusões Práticas para Seu Próprio Bot

Construir um bot que pode agendar mensagens abre um novo mundo de possibilidades. Aqui está o que eu aprendi e o que você deve considerar:

1. Comece Simples: Não tente construir o agendador mais complexo de imediato. Primeiro, faça um lembrete pontual básico funcionar, depois adicione trabalhos recorrentes.
2. Tratamento de Erros é Fundamental: Os usuários inevitavelmente inserir comandos errados ou horários inválidos. Seu bot precisa ser sólido o suficiente para lidar com isso de maneira elegante. Adicione blocos try-except!
3. Permanência é Inegociável: Para qualquer bot que você espera que funcione por mais do que alguns minutos, você definitivamente precisa armazenar os trabalhos agendados. Os storages de trabalho do APScheduler facilitam isso. SQLite é um excelente ponto de partida para armazenamento local.
4. Feedback do Usuário: Sempre confirme com o usuário que seu agendamento foi definido. “Ok, vou te lembrar em 5 minutos!” faz toda a diferença.
5. Instruções Claras: Forneça boas mensagens de /help com exemplos. Isso ajuda os usuários a entenderem como interagir com seu bot.
6. Considere Fusos Horários: Para um bot global, fusos horários podem ser um pesadelo. O APScheduler pode lidar com eles, mas adiciona complexidade. Para um bot pessoal, você pode conseguir apenas usar UTC ou o horário local do servidor.

Esta jornada de um simples lembrete de D&D para um bot agendador mais capaz tem sido incrivelmente gratificante. Mostra que com algumas boas bibliotecas e um pouco de Python, você pode elevar seus bots do Telegram de meros respondedores a assistentes realmente proativos. Experimente, faça experiências e me diga quais ideias legais de agendamento você desenvolver!

Boa construção de bots!

🕒 Published: April 2, 2026