mcpField
T
telegram-reminders

telegram-reminders

github.com/alexskuznetsovProductivity2151 installsUpdated 41w ago
Repository

About telegram-reminders

A skill for sending Telegram messages immediately or scheduling reminders through Convex Cloud. It provides scripts for attachments, scheduled-message management, and message history.

Key features

  1. 01Send immediate Telegram messages
  2. 02Schedule messages with attachments
  3. 03List and cancel pending messages
  4. 04View message history
  5. 05Timezone-aware scheduling

Use cases

  1. 01Sending a Telegram update immediately
  2. 02Scheduling a reminder with a document
  3. 03Checking or cancelling scheduled messages

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/alexskuznetsov/claude-skill-telegram --skill telegram-reminders

After installing, type/telegram-remindersin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

.gitignore
README.md
package-lock.json
package.json
tsconfig.json
convex/
crons.ts
telegram.ts
messages.ts
tsconfig.json
schema.ts
references/
architecture.md
error_handling.md
convex.md
telegram_api.md
initial_setup.md
scripts/
cancel_message.ts
send_message.ts
list_scheduled.ts
proxy-util.ts
logger.ts
schedule_message.ts
setup.ts
types.ts
view_history.ts

Details

From the project README

Telegram Reminders Skill

Send immediate messages and schedule reminders to Telegram with cloud-based scheduling powered by Convex. Your reminders run 24/7 in Convex Cloud with zero infrastructure management.

Quick Reference

IMPORTANT! Always use these commands in order:

  • Send now: tsx scripts/send_message.ts [message_text]
  • Send now with attachment: tsx scripts/send_message.ts [message_text] /path/to/file.pdf
  • Schedule: tsx scripts/schedule_message.ts [time expression] [title] [message_text] [file_path]
  • Schedule with attachment: tsx scripts/schedule_message.ts [time expression] [title] [message_text] /path/to/file
  • List pending: tsx scripts/list_scheduled.ts
  • Cancel: tsx scripts/cancel_message.ts <message_id>
  • History: tsx scripts/view_history.ts [limit]

Initial Setup

Prerequisites (user must provide):

  1. Bot Token: Message @BotFather → /newbot → copy token
  2. User ID: Message @userinfobot → copy numeric ID
  3. Deploy Key: dashboard.convex.dev → Create project → Settings → Deploy Keys → Create "Production" key

Setup steps:

# 1. Install dependencies
cd /mnt/skills/user/telegram-reminders && npm install

# 2. Save configuration
mkdir -p /mnt/user-data/outputs
cat > /mnt/user-data/outputs/telegram_config.json << 'EOF'
{
  "botToken": "YOUR_BOT_TOKEN",
  "userId": "YOUR_USER_ID",
  "deployKey": "YOUR_DEPLOY_KEY",
  "setupDate": "CURRENT_DATE"
}
EOF

# 3. Create .env.local
cat > .env.local << 'EOF'
CONVEX_DEPLOY_KEY=YOUR_DEPLOY_KEY
EOF


# 4. Set environment variables in Convex
npx convex env set TELEGRAM_BOT_TOKEN "YOUR_BOT_TOKEN"
npx convex env set TELEGRAM_USER_ID "YOUR_USER_ID"

# 5. Deploy to Convex
npx convex deploy

# 6. Test with a message
tsx scripts/send_message.ts "Setup complete!"

Critical: User must start a chat with their bot (search and press "Start") before the bot can send messages.

Core Operations

Send Immediate Message

Send text message:

tsx scripts/send_message.ts "Your message text here"

Example with special characters:

tsx scripts/send_message.ts "Hello! Here's a test message 🚀"

Timezone

All times use user's configured timezone. The Convex backend stores UTC internally; client scripts handle conversion via chrono-node.

Limitations

  • Files sent as documents (not inline images)
  • Maximum file size: 50MB (Telegram limit)
  • Cron granularity: 1 minute minimum
  • No message editing (cancel and reschedule instead)
  • Rate limits: 20 messages/minute per user

References

Comments

Markdown supported