Telegram Web Client

웹소켓을 이용해 Telegram 봇(telegram-bot-workers)과 대화하는 웹 앱

Stack

• Backend: Python + Telethon v2 + FastAPI WebSocket
• Frontend: React + TypeScript + Vite + Zustand
• Infrastructure: Incus 컨테이너 (Debian 13) on jp1

Setup

1. Telegram API 자격증명 획득

1. https://my.telegram.org 접속
2. "API development tools" 클릭
3. API_ID와 API_HASH 복사

2. 환경 변수 설정

# 컨테이너에 접속
incus exec jp1:telegram-web-client -- bash

# .env 파일 생성
cd /opt/telegram-web-client/backend
cp .env.example .env

# 편집
vi .env
# TELEGRAM_API_ID=your_api_id
# TELEGRAM_API_HASH=your_api_hash
# BOT_USERNAME=telegram_summary_bot

3. 서비스 시작

# systemd 서비스 등록
incus file push telegram-web-client.service jp1:telegram-web-client/etc/systemd/system/

# 서비스 활성화 및 시작
incus exec jp1:telegram-web-client -- systemctl daemon-reload
incus exec jp1:telegram-web-client -- systemctl enable telegram-web-client
incus exec jp1:telegram-web-client -- systemctl start telegram-web-client

# 상태 확인
incus exec jp1:telegram-web-client -- systemctl status telegram-web-client

4. 프론트엔드 빌드

# 컨테이너 내에서
cd /opt/telegram-web-client/frontend
npm install
npm run build

Development

로컬 개발 (macOS)

# Backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Edit .env with your credentials
uvicorn main:app --reload --port 8000

# Frontend (별도 터미널)
cd frontend
npm install
npm run dev

컨테이너 접속

incus exec jp1:telegram-web-client -- bash

로그 확인

incus exec jp1:telegram-web-client -- journalctl -u telegram-web-client -f

Architecture

┌─────────────────┐     WebSocket      ┌─────────────────────────────┐
│  React Frontend │◄──────────────────►│  FastAPI Backend (Debian)   │
│  (브라우저)      │                    │                             │
└─────────────────┘                    │  ┌─────────────────────┐    │
                                       │  │ Telethon v2 Client  │    │
                                       │  │ (MTProto)           │    │
                                       │  └──────────┬──────────┘    │
                                       └─────────────┼───────────────┘
                                                     │
                                                     ▼
                                       ┌─────────────────────────────┐
                                       │  Telegram API (MTProto)     │
                                       │  ↔ telegram-bot-workers 봇  │
                                       └─────────────────────────────┘

WebSocket Messages

Client → Server

Type	Data	Description
check_auth	{}	인증 상태 확인
send_code	{phone}	인증 코드 전송 요청
verify_code	{phone, code, phone_code_hash}	코드 검증
verify_password	{password}	2FA 비밀번호 검증
send_message	{text}	메시지 전송
get_history	{}	채팅 기록 조회

Server → Client

Type	Data	Description
connected	{session_id}	연결 완료
auth_status	{authenticated, user_id, ...}	인증 상태
code_sent	{phone, phone_code_hash}	코드 전송됨
need_password	{message}	2FA 필요
auth_success	{user_id, username, ...}	인증 성공
auth_error	{message}	인증 실패
history	{messages}	채팅 기록
message_sent	{id, text, date, ...}	메시지 전송됨
new_message	{id, text, date, ...}	새 메시지 수신

Container Info

• Name: jp1:telegram-web-client
• IP: incus exec jp1:telegram-web-client -- ip a
• Port: 8000 (Backend API/WebSocket)