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](https://t.me/BotFather)
- A public HTTPS URL for webhook testing (for local dev use [ngrok](https://ngrok.com/))
- A Groq API key from [Groq Console](https://console.groq.com/keys)

## 2) Install and configure

From project root:

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

Set `.env` values:

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

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

Health check:

```bash
curl http://127.0.0.1:8000/health
```

Expected:

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

## 4) Expose local server to Telegram

In a second terminal:

```bash
ngrok http 8000
```

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

## 5) Register Telegram webhook

Replace placeholders and run:

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

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

```bash
python3 -m pytest -q
```

Seed richer mock scenarios (recommended before Telegram testing):

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

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