Telegram AI Notes Bot - Project Summary

An intelligent note-taking system that processes Telegram messages using AI to automatically categorize, tag, and organize notes. Users send messages to a Telegram bot, which are processed by OpenAI to extract structured information and stored in a Supabase database.

• ✅ Automatic message processing with AI
• ✅ Smart categorization (notes, reminders, events, tasks, links, etc.)
• ✅ Intelligent tagging system
• ✅ Priority detection
• ✅ Date/time extraction for reminders and events
• ✅ URL and location detection
• ✅ Sentiment analysis
• ✅ User-specific data isolation

┌─────────────┐
│   Telegram  │
│     Bot     │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  Webhook (HTTP) │  ← Receives messages
│   Val.town Val  │  ← Validates & stores in SQLite
└────────┬────────┘
         │
         ▼
┌────────────────┐
│ SQLite Queue   │  ← Temporary message queue
└────────┬───────┘
         │
         ▼
┌─────────────────────┐
│ Worker (Interval)   │  ← Processes one message at a time
│   Val.town Val      │
└──────┬──────────────┘
       │
       ├─────────────┐
       ▼             ▼
┌──────────┐   ┌─────────────┐
│  OpenAI  │   │  Supabase   │
│   API    │   │  PostgreSQL │
└──────────┘   └─────────────┘
       │             │
       └──────┬──────┘
              ▼
       ┌─────────────┐
       │  Telegram   │  ← Confirmation message
       │   User      │
       └─────────────┘

1. Telegram Webhook (HTTP Val)

   • Receives incoming messages
   • Validates webhook secret
   • Stores messages in SQLite queue
   • Returns 200 OK to Telegram

2. Message Processor Worker (Interval Val)

   • Runs on scheduled intervals (e.g., every 10-30 seconds)
   • Fetches oldest unprocessed message (one at a time)
   • Processes with OpenAI API
   • Stores results in Supabase
   • Sends confirmation back to user
   • Marks message as processed

3. SQLite Queue

   • Temporary storage for incoming messages
   • Tracks processing status
   • Ensures messages are processed once

4. Supabase Database

   • Permanent storage for all notes and metadata
   • User management
   • Tag system
   • AI processing results

Stores Telegram users mapped to app users.

- id (UUID, PK)
- telegram_user_id (BIGINT, UNIQUE)
- username (TEXT)
- first_name (TEXT)
- last_name (TEXT)
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)

User-specific tags with visual properties.

- id (UUID, PK)
- user_id (UUID, FK → users)
- name (TEXT)
- color (TEXT) - hex color
- icon (TEXT) - emoji
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)
- UNIQUE(user_id, name)

Core table storing all processed notes.

- id (UUID, PK)
- user_id (UUID, FK → users)
- content (TEXT) - original message
- title (TEXT) - AI-generated title
- note_type (ENUM: note, reminder, event, link, reference, task, idea)
- priority (ENUM: low, medium, high, urgent)
- status (ENUM: active, completed, archived, deleted)
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)
- reminder_at (TIMESTAMP) - for reminders
- event_date (TIMESTAMP) - for events
- completed_at (TIMESTAMP) - for tasks
- telegram_message_id (BIGINT)
- url (TEXT) - extracted URL
- location (TEXT) - for events
- search_vector (TSVECTOR) - full-text search

Many-to-many relationship between notes and tags.

- note_id (UUID, FK → notes)
- tag_id (UUID, FK → tags)
- created_at (TIMESTAMP)
- PRIMARY KEY (note_id, tag_id)

Stores detailed AI processing results.

- id (UUID, PK)
- note_id (UUID, FK → notes)
- raw_response (JSONB) - full AI response
- extracted_title (TEXT)
- extracted_tags (TEXT[])
- extracted_type (note_type)
- extracted_priority (note_priority)
- extracted_reminder_date (TIMESTAMP)
- extracted_event_date (TIMESTAMP)
- extracted_url (TEXT)
- extracted_location (TEXT)
- sentiment (TEXT: positive, negative, neutral)
- confidence_score (DECIMAL)
- model_used (TEXT)
- processing_time_ms (INTEGER)
- created_at (TIMESTAMP)
- error (TEXT)
- success (BOOLEAN)

Processing queue in Supabase (alternative to SQLite).

- id (UUID, PK)
- user_id (UUID, FK → users)
- telegram_message_id (BIGINT)
- chat_id (BIGINT)
- text (TEXT)
- processed_at (TIMESTAMP)
- created_at (TIMESTAMP)
- note_id (UUID, FK → notes)
- processing_error (TEXT)
- retry_count (INTEGER)

Temporary queue for incoming Telegram messages.

- id (INTEGER, PK, AUTOINCREMENT)
- chat_id (INTEGER)
- username (TEXT)
- text (TEXT)
- timestamp (INTEGER)
- created_at (DATETIME)
- processed_at (DATETIME) - NULL when unprocessed

Raw Telegram message text from user.

The AI analyzes messages to extract:

• Title: Short descriptive title (max 60 chars)
• Type: note, reminder, event, link, reference, task, idea
• Priority: low, medium, high, urgent
• Tags: Array of relevant tags (max 5)
• Dates: Reminder and event dates in ISO format
• URL: Extracted links
• Location: Event locations
• Sentiment: positive, negative, neutral
• Confidence: 0.0 to 1.0

{
  "title": "Buy milk",
  "type": "task",
  "priority": "medium",
  "tags": ["shopping", "groceries"],
  "reminder_date": "2026-01-22T00:00:00Z",
  "event_date": null,
  "url": null,
  "location": null,
  "sentiment": "neutral",
  "confidence": 0.92
}

// Key features:
- POST-only endpoint
- Validates X-Telegram-Bot-Api-Secret-Token
- Stores messages in SQLite with processed_at = NULL
- Returns 200 OK immediately
- Logs all activity

// Key features:
- Interval-based execution
- Processes one message at a time (LIMIT 1)
- FIFO processing (ORDER BY created_at ASC)
- OpenAI integration for analysis
- Supabase CRUD operations
- User creation/lookup
- Tag management
- Confirmation messages to users
- Error handling
- Processing time tracking

• Calls OpenAI GPT-4o-mini
• Returns structured JSON with extracted data
• Uses response_format: { type: "json_object" }

• Checks if user exists by telegram_user_id
• Creates new user if not found
• Returns user object

• Inserts note into Supabase
• Returns created note with ID

• Gets or creates tags
• Links tags to note via note_tags table

• Creates formatted Telegram message
• Includes emojis for types and priorities
• Shows all extracted information

# Message @BotFather on Telegram
/newbot
# Follow prompts, save token

1. Go to https://supabase.com
2. Create new project
3. Run the database schema SQL
4. Get URL and service key from Settings → API

1. Create new HTTP Val on Val.town
2. Paste webhook code
3. Add environment variables
4. Get Val URL (https://username-valname.web.val.run)

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-val.web.val.run",
    "secret_token": "your-webhook-secret"
  }'

1. Create new Interval Val on Val.town
2. Paste worker code
3. Add environment variables
4. Set interval (recommended: 10-30 seconds)

Send a message to your bot on Telegram
Check Val.town logs
Verify data in Supabase

• Retry Logic: Handle failed AI processing with exponential backoff
• Batch Processing: Process multiple messages per worker run
• Message Editing: Update notes when user edits Telegram message
• Message Deletion: Delete notes when user deletes Telegram message
• Error Notifications: Notify users when processing fails
• Voice Messages: Transcribe and process voice notes
• Images: OCR and image analysis
• Documents: Extract text from PDFs, Word docs

• Bot Commands:
  • /list - Show recent notes
  • /search <query> - Search notes
  • /tags - Manage tags
  • /reminders - View upcoming reminders
  • /stats - Usage statistics
  • /settings - User preferences
• Inline Keyboards: Interactive buttons for actions
• Quick Actions: Mark as done, snooze, edit priority
• Bulk Operations: Archive old notes, delete by tag

• Natural Language Dates: "next Tuesday", "in 2 weeks"
• Recurring Reminders: Daily, weekly, monthly
• Smart Suggestions: Tag suggestions based on history
• Context Awareness: Learn from user patterns
• Related Notes: Link similar notes automatically
• Summary Digests: Daily/weekly summaries
• Calendar Integration: Sync events with Google Calendar

• Multi-language Support: Detect and process any language
• Action Items Extraction: Pull out todos from long messages
• Meeting Notes: Extract attendees, decisions, action items
• Smart Replies: AI suggests responses to messages
• Note Relationships: Automatically link related notes
• Knowledge Graph: Build connections between notes

• Web Dashboard:
  • View all notes in rich interface
  • Advanced search and filtering
  • Calendar view for events
  • Kanban board for tasks
  • Analytics and insights
• Mobile App: Native iOS/Android apps
• Browser Extension: Save web content as notes
• API: Public API for integrations

• Calendar Sync: Google Calendar, Apple Calendar
• Task Managers: Todoist, Asana, Trello
• Note Apps: Notion, Evernote, Obsidian
• Email: Send notes via email
• Slack/Discord: Team collaboration
• Zapier/Make: Connect to 1000+ apps

• Shared Notes: Collaborate with other users
• Teams/Workspaces: Organize by team
• Permissions: View/edit access control
• Comments: Discuss notes with team
• Activity Feed: See team activity

• Unlimited Storage: Remove message limits
• Advanced AI Models: GPT-4, Claude
• Priority Support: Faster response times
• Custom Integrations: Build custom connections
• White-label: Custom branding
• Export: Bulk export in various formats

• Current: Sequential processing (1 message per interval)
• Improvement: Implement concurrent processing with rate limiting
• Consideration: OpenAI rate limits (3,500 RPM for gpt-4o-mini)

• SQLite Limitations: Val.town SQLite is ephemeral
• Solution: Migrate queue to Supabase for persistence
• Alternative: Use Redis for message queue

• Single Point of Failure: If worker stops, messages pile up
• Solution: Implement health checks and alerts
• Monitoring: Track processing times, error rates

• RLS (Row Level Security): Enabled but bypassed by service key
• Improvement: Implement proper auth for future web app
• Consideration: Secure API keys, rotate regularly

• OpenAI Costs: ~$0.0001 per message (gpt-4o-mini)
• Supabase: Free tier: 500MB, 2GB bandwidth
• Val.town: Free tier: 10 vals, limited compute
• Monitoring: Track usage, set budgets

User sends message → Telegram Bot
                          ↓
                    Webhook receives
                          ↓
                  Validates secret
                          ↓
               Stores in SQLite queue
                          ↓
                    Returns 200 OK
                          ↓
            [Message in queue: processed_at = NULL]
                          ↓
              Worker runs (interval trigger)
                          ↓
         Fetches oldest unprocessed message
                          ↓
              Sends to OpenAI for analysis
                          ↓
            OpenAI returns structured JSON
                          ↓
           Get/Create user in Supabase
                          ↓
            Insert note into Supabase
                          ↓
         Insert AI results into Supabase
                          ↓
        Get/Create tags and link to note
                          ↓
      Format confirmation message with emojis
                          ↓
       Send confirmation back to Telegram
                          ↓
         Mark message as processed (SQLite)
                          ↓
                    Worker completes
                          ↓
            [Next interval: process next message]

vals/
├── telegram-webhook.ts      # HTTP endpoint for receiving messages
└── telegram-worker.ts        # Interval worker for processing

project/
├── telegram-notes-bot-summary.md  # This document
├── database-schema.sql            # Supabase schema
├── webhook.ts                     # Webhook implementation
└── worker.ts                      # Worker implementation

Solution: Check worker logs, verify OpenAI API key, check Supabase connection

Solution: Ensure processed_at is set correctly, check for worker conflicts

Solution: Verify "json" is in system prompt, handle parsing errors

Solution: Check user_id matching, verify tag creation logic

Solution: Verify BOT_TOKEN, check sendMessage error handling

• Average processing time per message
• OpenAI API response time
• Supabase query performance
• Worker execution time

• Total messages processed
• Active users
• Notes created per day
• Tag usage statistics
• Note type distribution

• AI confidence scores
• User corrections/edits
• Error rate
• Retry rate

• Inbox: All recent notes
• Today: Today's tasks and reminders
• Calendar: Month/week view of events
• Search: Full-text search with filters
• Tags: Browse by tag
• Archive: Completed/archived notes

• Dark mode support
• Mobile-responsive design
• Drag-and-drop organization
• Keyboard shortcuts
• Quick capture
• Markdown support

User: "Buy milk tomorrow"
  ↓
AI Analysis:
  - Type: task
  - Priority: medium
  - Tags: ["shopping"]
  - Reminder: tomorrow 9am
  ↓
Stored in database
  ↓
User receives: "✅ Task: Buy milk
                Priority: 🟡 medium
                Tags: #shopping
                Reminder: Jan 22, 2026 9:00 AM"

User: "Team meeting Friday 2pm with John and Sarah"
  ↓
AI Analysis:
  - Type: event
  - Priority: medium
  - Tags: ["meeting", "work"]
  - Event date: Friday 2pm
  ↓
Stored in database
  ↓
User receives: "📅 Event: Team meeting Friday 2pm with John and Sarah
                Event: Jan 24, 2026 2:00 PM
                Tags: #meeting #work"

User: "https://blog.example.com/ai-trends great article about AI"
  ↓
AI Analysis:
  - Type: link
  - Priority: low
  - Tags: ["article", "ai"]
  - URL: https://blog.example.com/ai-trends
  ↓
Stored in database
  ↓
User receives: "🔗 Link: great article about AI
                URL: https://blog.example.com/ai-trends
                Tags: #article #ai"

• ✅ Receive and store messages
• ✅ Process with AI
• ✅ Extract structured data
• ✅ Store in database
• ✅ Send confirmations

• All note types working
• Accurate date parsing
• Reliable processing
• Error handling
• Basic commands

• Web dashboard
• Advanced search
• Reminders triggering
• Mobile app
• 100+ active users

• Telegram Bot API
• OpenAI API
• Supabase Docs
• Val.town Docs

• Val.town stdlib: OpenAI, SQLite, Fetch
• Supabase REST API
• Telegram Bot API

1. AI Prompts: Improve extraction accuracy
2. Features: Add new note types, commands
3. UI/UX: Design web dashboard
4. Testing: Write tests, find bugs
5. Documentation: Improve guides, add examples

1. Fork repository
2. Create feature branch
3. Test thoroughly
4. Submit pull request
5. Code review
6. Deploy to staging
7. Test in production
8. Merge to main

• Check logs in Val.town dashboard
• Review Supabase database
• Test with simple messages first
• Check environment variables

• Discord community
• GitHub issues
• Email support
• Documentation site

• ✅ Basic message reception
• ✅ AI processing
• ✅ Database storage
• ✅ Confirmation messages

• 0.2.0: Error handling, retry logic
• 0.3.0: Bot commands
• 0.4.0: Voice messages, images
• 1.0.0: Web dashboard
• 2.0.0: Mobile apps
• 3.0.0: Team collaboration

• Sequential processing prevents race conditions
• JSON mode in OpenAI ensures structured output
• Supabase RLS provides security
• Val.town simplifies deployment

• Natural language date parsing is complex
• Rate limiting requires careful handling
• User timezone detection needed
• SQLite persistence in Val.town

• Always validate webhook secrets
• Use environment variables for keys
• Log everything for debugging
• Return 200 OK quickly to Telegram
• Process asynchronously

1. Test with real users
2. Monitor error rates
3. Improve AI prompts
4. Add basic error handling

1. Implement retry logic
2. Add basic commands
3. Improve date parsing
4. Set up monitoring

1. Build web dashboard
2. Add voice message support
3. Implement reminders
4. Beta testing

1. Mobile apps
2. Team features
3. Advanced AI
4. Public launch

Last Updated: January 2026 Version: 0.1.0 Status: MVP - Active Development