README_SETUP.md

Via Telegram Setup Guide (Simple V1)

This guide gets your bot working on Telegram with:

• mocked Paytm-like MCP tools (local only)
• Groq inference APIs for LLM (and optional STT)

No real Paytm payment APIs are used.

1) Prerequisites

• Python 3.11+
• A Telegram account
• A bot token from @BotFather
• A public HTTPS URL for webhook testing (for local dev use ngrok)
• A Groq API key from Groq Console

2) Install and configure

From project root:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
cp .env.example .env

Set .env values:

APP_ENV=dev
TELEGRAM_BOT_TOKEN=<your_telegram_bot_token>
TELEGRAM_WEBHOOK_SECRET=<long_random_string>

GROQ_API_KEY=<your_groq_api_key>
LLM_INFERENCE_URL=https://api.groq.com/openai/v1/chat/completions
LLM_INFERENCE_API_KEY=
LLM_MODEL=llama-3.3-70b-versatile

STT_INFERENCE_URL=https://api.groq.com/openai/v1/audio/transcriptions
STT_API_KEY=
STT_MODEL=whisper-large-v3-turbo

DB_PATH=via.sqlite3

3) Run the API

source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Health check:

curl http://127.0.0.1:8000/health

Expected:

{"status":"ok","env":"dev"}

4) Expose local server to Telegram

In a second terminal:

ngrok http 8000

Copy the HTTPS forwarding URL, e.g. https://abc123.ngrok-free.app.

5) Register Telegram webhook

Replace placeholders and run:

curl -X POST "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://<YOUR_PUBLIC_HOST>/telegram/webhook",
    "secret_token": "<TELEGRAM_WEBHOOK_SECRET>"
  }'

Verify webhook:

curl "https://api.telegram.org/bot<TELEGRAM_BOT_TOKEN>/getWebhookInfo"

url should point to /telegram/webhook and last_error_message should be empty.

6) Test from Telegram app

Open your bot chat and send:

• show recent orders
• show settlement summary
• create payment link 250
• refund txn-2001 amount 50
• confirm
• /debug last_update_type (shows current Telegram update type and last processed type)

Voice test:

• Send a voice note like: refund txn-2001 amount 30
• Bot should reply with transcript + action prompt.

7) Expected behavior

• Orders/links/refunds/settlements come from local mock DB.
• Refund mutation is gated:
  • first message prepares action
  • confirm executes it
• Tool calls are audited in tool_audit table.

8) Quick troubleshooting

• 401 invalid webhook secret

  • .env secret and Telegram setWebhook secret_token must match exactly.

• Telegram webhook not hitting local app

  • ensure ngrok URL is alive and /telegram/webhook is reachable.
  • re-run setWebhook each time ngrok URL changes.

• LLM fallback generic/error response

  • verify GROQ_API_KEY is valid.
  • verify LLM_INFERENCE_URL is .../chat/completions.
  • check model name in LLM_MODEL.

• Voice transcription unavailable

  • verify STT_INFERENCE_URL ends with /audio/transcriptions.
  • verify STT_API_KEY (or GROQ_API_KEY) is present.
  • ensure your bot received a real Telegram voice message (not audio/file attachment).

9) Local validation before Telegram

Run tests:

python3 -m pytest -q

Seed richer mock scenarios (recommended before Telegram testing):

python3 -m scripts.seed_scenarios

This seeds multiple situations:

• healthy collections day
• UPI failure dip day
• pending + successful refunds
• multiple settlement payouts
• active/expired payment links

Manual webhook simulation:

curl -X POST http://127.0.0.1:8000/telegram/webhook \
  -H "Content-Type: application/json" \
  -H "X-Telegram-Bot-Api-Secret-Token: <TELEGRAM_WEBHOOK_SECRET>" \
  -d '{
    "message": {
      "chat": {"id": 12345},
      "text": "show settlement summary"
    }
  }'

---

If you want, next step can be a production-ready README.md with Render deploy instructions and persistent Postgres instead of SQLite.