⚡ Teleflow Agent

Autonomous Conversational Lead Qualification & Edge CRM Router for Telegram

An ultra-responsive, zero-fluff agentic bot that engages prospective inbound clients on Telegram 24/7, qualifies project requirements via interactive inline keyboards and deterministic state machine reasoning, schedules discovery calls via Cal.com, and synchronizes qualified leads to databases and CRM webhooks.

Explore Live Demo • View Portfolio • Report Issue

---

🏛 Architecture Overview

                      ┌──────────────────────────────────────────────┐
                      │             TELEGRAM ECOSYSTEM               │
                      │  User Chat / Direct Message / Channel Link   │
                      └──────────────────────┬───────────────────────┘
                                             │
                                  HTTPS / JSON Payload
                                             ▼
                      ┌──────────────────────────────────────────────┐
                      │          TELEFLOW INGESTION ENGINE           │
                      │   • Webhook Route (/webhook)                 │
                      │   • Resilient Long-Poller (Dev / Worker)     │
                      │   • Secret Token Header Verification         │
                      └──────────────────────┬───────────────────────┘
                                             │
                                             ▼
                      ┌──────────────────────────────────────────────┐
                      │     4-PHASE DETERMINISTIC STATE MACHINE      │
                      │   INITIAL ──► DISCOVERY ──► QUALIFICATION    │
                      │                    └──► CONFIRMED            │
                      └───────┬──────────────────────────────┬───────┘
                              │                              │
              Interactive UI  │                              │ Multi-Sink Dispatch
                              ▼                              ▼
             ┌──────────────────────────────┐ ┌──────────────────────────────┐
             │ • Inline Keyboard Buttons    │ │ • Supabase Database Sink     │
             │ • Callback Query Router      │ │ • Outbound Signed Webhook    │
             │ • Cal.com Scheduling Bridge  │ │ • Admin Instant Push Alert   │
             └──────────────────────────────┘ └──────────────────────────────┘

---

🎯 Key Capabilities

1. 4-Phase Conversational State Machine

• INITIAL: Welcomes the prospective client, highlights core capabilities, and presents one-tap service selection buttons.
• DISCOVERY: Analyzes natural language project briefs, maps requests to verified service categories, and extracts initial scopes.
• QUALIFICATION: Requests target launch timelines and contact details with dynamic inline keyboard chips (Urgent < 1 Wk, 2–4 Weeks, 1–2 Months, Flexible).
• CONFIRMED: Packages the validated intake schema, stores the lead in the persistent CRM, sends real-time push alerts, and provides a 1-click Cal.com booking link.

2. Interactive Inline Keyboards & Callback Routing

• Fully responsive Telegram InlineKeyboardMarkup integration.
• Zero client spinner delay via sub-10ms answerCallbackQuery acknowledgment.
• Seamless state transitions whether the user types text or taps an interactive chip.

3. Cal.com / Dynamic Scheduling Bridge

• Qualified prospects receive a direct [ 📅 Book Architecture Call ] button.
• Automatically encodes name, verified email, and technical project brief as URL query parameters directly into Cal.com or Google Calendar booking widgets.

4. Pluggable Multi-Sink CRM Dispatcher

• Database Storage: Directly inserts into Supabase inquiries table with full metadata.
• Signed Webhooks: Dispatches outbound lead.qualified events with HMAC SHA-256 signature (X-Teleflow-Signature) to Zapier, Make, n8n, or custom CRM backends.
• Admin Push Alerts: Instantly alerts the operator's personal Telegram chat with direct deep-links to the lead in the command center.

5. Dual-Mode Deployment

• Edge / Serverless Webhook Mode (Default): Lightweight HTTP listener designed for Vercel Serverless, Cloudflare, Fly.io, or Railway.
• Long-Polling Mode (--poll): Zero-tunneling local development mode. Automatically cleans old webhooks and polls Telegram directly.

---

📊 Benchmarks & Performance

Metric	Measured Value	Standard / Environment
Turn Execution Latency	~284ms	Cold/warm turns on Vercel Node runtime
Callback Acknowledgment	< 25ms	Instant spinner dismissal
Docker Image Size	< 95MB	Multi-stage Node 22-alpine build
Memory Footprint	~38MB RSS	Zero bloated dependencies; native fetch
Test Suite Duration	159ms	11 automated assertions, 100% pass

---

🚀 Quickstart

1. Clone & Install

git clone https://github.com/Sam-CodesAI/teleflow-agent.git
cd teleflow-agent
npm install

2. Configure Environment

Copy .env.example to .env:

cp .env.example .env

Populate the required keys:

TELEGRAM_BOT_TOKEN="your_bot_token_from_botfather"
TELEGRAM_ADMIN_CHAT_ID="your_telegram_chat_id"
TELEGRAM_WEBHOOK_SECRET="optional_secret_token"
CAL_BOOKING_URL="https://cal.com/samarth/discovery"

3. Run Locally

Option A — Long Polling Mode (Fastest for local testing, no tunnel needed):

npm run poll

Option B — Webhook Server Mode:

npm run dev
# Starts HTTP server listening at http://localhost:3000/webhook

4. Run Test Suite

npm test

---

🐳 Docker Deployment

Run with Docker

# Build production image
docker build -t teleflow-agent .

# Run container
docker run -d \
  -p 3000:3000 \
  --name teleflow-agent \
  --env-file .env \
  teleflow-agent

Run with Docker Compose

docker compose up -d

Check health status:

curl http://localhost:3000/health
# {"status":"online","agent":"teleflow-agent","version":"1.2.0"}

---

🛠 API & Webhook Reference

Set Webhook Endpoint

To register this bot with Telegram's Webhook infrastructure:

curl -F "url=https://your-domain.com/webhook" \
     -F "secret_token=your_webhook_secret" \
     https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook

Webhook Dispatch Format (Outbound to CRM)

When a lead reaches CONFIRMED phase, Teleflow dispatches an outbound event to EXTERNAL_CRM_WEBHOOK_URL:

{
  "event": "lead.qualified",
  "timestamp": "2026-09-06T06:15:00.000Z",
  "payload": {
    "name": "Jane Doe",
    "email": "jane@techcorp.io",
    "contactMethod": "Telegram (@janedoe) / jane@techcorp.io",
    "serviceRequested": "Workflow & Business Automation",
    "message": "[LEAD INTAKE]\n• Service: Workflow & Business Automation\n• Brief: Sync WhatsApp with HubSpot CRM\n• Timeline: 2–4 weeks"
  }
}

---

👨‍💻 Author

Samarth Nimangre (Sam)
17-year-old AI Developer & Automation Builder based in Karnataka, India.

• Portfolio: sam-codes.vercel.app
• GitHub: @Sam-CodesAI
• Telegram: @samarth_master_bot / @Samarth1306
• LinkedIn: Samarth Nimangre
• X / Twitter: @Sam_CodeAI
• Instagram: @samarth.buildss

---

📜 License

Licensed under the MIT License.