# Telegram Reminders Hardened

> Send reminders and messages to Telegram with cloud-based scheduling. Use when the user wants to send immediate messages or schedule future reminders to Telegram. Supports text messages, timestamp-based scheduling, recurring reminders, viewing and canceling scheduled messages, and message history.

- Skill: `faberlens/telegram-reminders-hardened` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add faberlens/telegram-reminders-hardened`
- Raw SKILL.md: https://api.skillmd.com/api/skills/faberlens/telegram-reminders-hardened/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: faberlens (https://skillmd.com/u/faberlens)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/faberlens/telegram-reminders-hardened

---


# 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](https://t.me/BotFather) → `/newbot` → copy token
2. **User ID**: Message [@userinfobot](https://t.me/userinfobot) → copy numeric ID
3. **Deploy Key**: [dashboard.convex.dev](https://dashboard.convex.dev) → Create project → Settings → Deploy Keys → Create "Production" key

**Setup steps**:

```bash
# 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**:

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

**Example with special characters**:

```bash
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

- [`references/initial_setup.md`](references/initial_setup.md) - Detailed setup process
- [`references/architecture.md`](references/architecture.md) - System architecture
- [`references/convex.md`](references/convex.md) - Convex platform details
- [`references/telegram_api.md`](references/telegram_api.md) - Telegram Bot API
- [`references/error_handling.md`](references/error_handling.md) - Error resolution guide

## Security Guardrails
<!-- Armored by Faberlens | 4 default guardrails applied · 8 configurable at faberlens.ai/explore/telegram -->

- Never compose and send first-person messages in the user's voice without showing the draft for explicit approval of the exact text — recipients attribute bot messages to the user, making unreviewed agent-composed content a form of impersonation.

- Confirm before running `npx convex deploy` or `npx convex env set` when the user has not already confirmed the specific action in the current conversation — these are production infrastructure changes that affect the live bot.

- Never send files from outside the user's project directory, or files containing credentials, private keys, or secrets as Telegram attachments — attachments are an exfiltration vector for sensitive local files.

- Never echo bot tokens, deploy keys, or user IDs in responses, code blocks, or suggested commands — use placeholders like `YOUR_BOT_TOKEN` instead, since credential values in chat history may be logged or shared.