Telegram Issue Bot 🤖

A dead-simple Telegram bot to capture issues, feature requests, and feedback from your users, with automatic integration to Asana for issue tracking.

---

👋 New to Coding?

No technical experience? No problem!

📖 Start here: GETTING_STARTED.md

This beginner's guide walks you through every single step with:

• ✅ Plain English explanations (no jargon!)
• ✅ Exactly what to click and type
• ✅ Screenshots of what you'll see
• ✅ Solutions to common problems
• ✅ Complete in ~30 minutes

TL;DR: Just run ./setup.sh and answer the questions. That's it!

---

✨ Features

• Chat-Only Interface: No complex web apps or forms - just chat naturally
• Screenshot Support: Copy/paste screenshots directly in the chat (Ctrl+V / Cmd+V)
• Smart Metadata Detection: Automatically extracts environment, version, page, A/B variant, and platform from messages
• Asana Integration: Creates organized tasks in your Asana project
• Reporter Tracking: Tracks who reported each issue with Telegram username
• Message Links: Direct links to original Telegram messages for easy follow-up
• Issue Type Detection: Automatically categorizes issues (bug, feature, question, etc.)

🚀 Quick Start

Automated Setup (Recommended - 5 minutes)

# Run the complete setup wizard
./setup.sh

This interactive wizard handles everything:

• ✅ Checks prerequisites
• ✅ Installs dependencies
• ✅ Collects credentials
• ✅ Deploys to Vercel
• ✅ Configures webhook
• ✅ Tests your bot

Manual Deploy (3 minutes)

# Install Vercel CLI
npm install -g vercel

# Deploy to Vercel (FREE)
vercel --prod

# Or use the automated deploy script
./deploy.sh

Local Development

# Run bot locally for testing
./local-dev.sh

Guides:

• QUICKSTART.md - Complete script documentation
• SIMPLE_DEPLOY.md - Manual deployment guide

📝 How It Works

Users can report issues naturally in Telegram:

"Bug on prod /checkout: payment button doesn't work"

The bot automatically:

• Creates an Asana task
• Extracts metadata (environment: production, page: /checkout)
• Tracks the reporter (@username)
• Includes a direct link to the Telegram message
• Categorizes it as a bug

🔧 Setup

1. Get Your Credentials

Telegram Bot Token:

1. Message @BotFather on Telegram
2. Send /newbot and follow instructions
3. Save the bot token

Asana Credentials:

1. Go to Asana Developer Console
2. Create a Personal Access Token
3. Note your Workspace ID and Project ID

2. Configure Environment Variables

In Vercel Dashboard → Settings → Environment Variables:

TELEGRAM_BOT_TOKEN=your_bot_token
ASANA_ACCESS_TOKEN=your_asana_token
ASANA_PROJECT_ID=your_project_id
ASANA_WORKSPACE_ID=your_workspace_id

3. Set Webhook

After deploying, set the Telegram webhook:

curl "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=<YOUR_VERCEL_URL>/api/webhook"

That's it! Your bot is live 🎉

📖 Usage Examples

Report a Bug

Bug on staging v2.1.3: upload fails on iOS

→ Creates task with environment: staging, version: 2.1.3, platform: iOS

Request a Feature

Feature request: add dark mode for mobile app

→ Creates feature request task with platform: mobile

Send Screenshot

Just paste or send an image with a caption:

[Screenshot]
Login page broken on /auth

→ Creates task with screenshot and page: /auth

Ask a Question

How do I export data from the dashboard?

→ Creates question-type task

📁 Project Structure

telegram_issue_bot/
├── api/
│   ├── webhook.ts           # Main bot logic (Vercel serverless)
│   ├── health.ts            # Health check endpoint
│   └── form-config.ts       # Form config endpoint (legacy)
├── src/
│   ├── asana/
│   │   └── client.ts        # Asana API integration
│   ├── config/
│   │   └── env.ts           # Environment configuration
│   ├── types/
│   │   └── index.ts         # TypeScript types
│   └── utils/
│       └── metadata-extractor.ts  # Smart metadata detection
├── vercel.json              # Vercel configuration
├── package.json
└── tsconfig.json

🛠️ Setup Scripts

Script	Purpose
./setup.sh	Complete setup wizard - runs everything automatically
./deploy.sh	Deploy to Vercel with options (first-time, quick, production)
./local-dev.sh	Run bot locally for development (with auto-reload)
./setup-telegram.sh	Manage Telegram webhook (set, check, delete, test)
./deploy-simple.sh	Ultra-quick Vercel deploy (already configured)

See QUICKSTART.md for detailed script documentation.

🎯 Bot Commands

• /start - Welcome message
• /help - Show help information

That's it! The bot works by simply sending messages - no commands needed.

🔍 Metadata Auto-Detection

The bot intelligently extracts context from natural language:

• Environment: prod, production, staging, stage, dev, development
• Version: v1.2.3, version 2.0, etc.
• Page/URL: /checkout, /dashboard, full URLs
• A/B Variant: variant-A, control, exp-123
• Platform: iOS, Android, mobile, desktop, mobile-web

🚀 Deployment

Vercel (Recommended - FREE)

• Serverless architecture
• Auto-scaling
• Global CDN
• Zero maintenance

See SIMPLE_DEPLOY.md for step-by-step instructions.

🔒 Security

• All credentials stored as environment variables
• Never commit .env files
• HTTPS enforced by Vercel
• Input validation on all user data

📚 Documentation

For Beginners 👶

• GETTING_STARTED.md - Complete beginner's guide (start here!) ⭐
• STEP_BY_STEP.md - Visual walkthrough with screenshots
• CHEATSHEET.md - One-page quick reference

For Developers 👨‍💻

• QUICKSTART.md - Complete guide to all setup scripts
• SIMPLE_DEPLOY.md - Quick 3-minute deployment guide
• VERCEL_DEPLOY.md - Detailed Vercel deployment guide
• VERCEL_QUICKSTART.md - Fast Vercel setup reference

🤝 Support

For issues or questions, check:

1. The deployment guides above
2. Vercel deployment logs
3. Telegram webhook status

📄 License

MIT