telegram-bot-workers/telegram-cli/README.md

Telegram Bot Web Chat UI

Cloudflare Worker로 변환된 웹 채팅 인터페이스 및 API 엔드포인트

기능

• 웹 채팅 UI (GET /): 브라우저에서 봇과 대화
• JSON API (POST /api/chat): Claude나 curl로 사용 가능
• Health Check (GET /health): 상태 확인

배포 방법

1. 의존성 설치

cd telegram-cli
npm install

2. Secrets 설정

# BOT_TOKEN 설정 (실제로는 사용하지 않지만 필수 변수)
wrangler secret put BOT_TOKEN

# WEBHOOK_SECRET 설정 (Bot Worker /api/test 인증용)
wrangler secret put WEBHOOK_SECRET

Vault에서 가져오기:

vault kv get secret/telegram-bot

3. 로컬 테스트

npm run dev

브라우저에서 http://localhost:8787 접속

4. 배포

npm run deploy

배포 후 URL: https://telegram-cli-web.your-subdomain.workers.dev

엔드포인트

GET /

웹 채팅 UI (HTML/CSS/JS 인라인)

특징:

• 다크 테마
• 실시간 응답 시간 표시
• 로딩 상태 표시
• Enter로 메시지 전송
• 자동 스크롤

사용법:

1. 브라우저에서 Worker URL 접속
2. 메시지 입력창에 텍스트 입력
3. Enter 키 또는 "전송" 버튼 클릭
4. 봇 응답 대기 (응답 시간 표시됨)

POST /api/chat

JSON API 엔드포인트

Request:

{
  "message": "서버 추천해줘"
}

Response:

{
  "response": "봇 응답 내용...",
  "time_ms": 1234
}

curl 예시:

curl -X POST https://telegram-cli-web.your-subdomain.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "서버 추천해줘"}'

Claude가 사용하는 경우:

# Claude는 이 API를 호출하여 봇과 대화할 수 있습니다
curl -X POST https://telegram-cli-web.your-subdomain.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "날씨 알려줘"}'

GET /health

Health check 엔드포인트

Response:

{
  "status": "ok",
  "timestamp": "2026-01-26T00:00:00.000Z"
}

환경변수

Secrets (wrangler secret put)

변수	설명	필수
BOT_TOKEN	Telegram Bot Token (실제로는 미사용)	✅
WEBHOOK_SECRET	Bot Worker /api/test 인증용	✅

Variables (wrangler.toml)

변수	기본값	설명
CHAT_ID	821596605	Telegram Chat ID
BOT_WORKER_URL	https://telegram-summary-bot...	Bot Worker URL

변경 방법:

# wrangler.toml
[vars]
CHAT_ID = "YOUR_TELEGRAM_ID"
BOT_WORKER_URL = "https://your-bot-worker.workers.dev"

아키텍처

브라우저 (Web UI)
      ↓
GET / → HTML/CSS/JS 반환
      ↓
POST /api/chat → telegram-cli-web Worker
                        ↓
                 Bot Worker (/api/test)
                   - message
                   - chat_id
                   - user_id
                   - username: 'web-tester'
                        ↓
                   Bot 응답 처리
                   - DB 작업
                   - AI 응답 생성
                   - Function Calling
                        ↓
                 Web UI로 응답 반환
                   { response, time_ms }

테스트 시나리오

1. 웹 UI 테스트

브라우저에서 접속 후:

# 기본 대화
"안녕하세요"
"날씨 알려줘"

# Function Calling 도구
"서울 날씨"
"ChatGPT 가격 검색"
"123 * 456"
"현재 시간"

# 도메인
"example.com 조회"
"도메인 추천해줘: 커피숍"

# 예치금
"잔액 조회"
"홍길동 5000원 입금"

2. API 테스트 (curl)

# 기본 대화
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "안녕하세요"}'

# 잔액 조회
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "/deposit"}'

# 도메인 조회
curl -X POST https://your-worker.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "example.com 조회"}'

3. Claude 사용 예시

Claude가 이 API를 사용하여 봇과 대화:

# Claude는 이 엔드포인트를 호출하여 봇의 기능을 테스트할 수 있습니다
curl -X POST https://telegram-cli-web.workers.dev/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "날씨 알려줘"}'

로그 확인

npm run tail

실시간 로그 스트리밍으로 요청/응답 확인 가능

개발 모드

npm run dev

로컬에서 http://localhost:8787 접속하여 테스트

로컬 개발 시 주의사항:

• Secrets는 .dev.vars 파일에 설정
• 또는 wrangler dev --remote로 프로덕션 Secrets 사용

기술 스택

• Runtime: Cloudflare Workers (V8 Isolate)
• Language: TypeScript
• Frontend: Vanilla JavaScript (인라인 HTML)
• CSS: 다크 테마, 애니메이션, 반응형

보안

• ✅ CORS 설정 완료 (모든 Origin 허용)
• ✅ Bot Worker의 /api/test 엔드포인트는 Bearer 토큰으로 인증
• ✅ Secrets는 Workers 환경변수로 안전하게 관리
• ⚠️ 웹 UI는 공개 접근 가능 (인증 없음)

문제 해결

Secrets 미설정 오류

증상:

Bot Worker error: 401 - Unauthorized

해결:

wrangler secret put WEBHOOK_SECRET
# Vault에서 가져온 값 입력

Bot Worker URL 변경

wrangler.toml 수정:

[vars]
BOT_WORKER_URL = "https://new-worker.workers.dev"

CHAT_ID 변경

wrangler.toml 수정:

[vars]
CHAT_ID = "123456789"

로컬 테스트 시 Secrets 설정

.dev.vars 파일 생성:

BOT_TOKEN=1234567890:ABC...
WEBHOOK_SECRET=your-webhook-secret

성능

• 응답 시간: 평균 200-500ms (Bot Worker 처리 시간 포함)
• Cold Start: ~100ms (Workers 특성상 매우 빠름)
• 동시 요청: 무제한 (Workers 스케일링)

라이센스

MIT

관련 파일

파일	역할
src/index.ts	Worker 메인 로직
wrangler.toml	Workers 설정
package.json	의존성 및 스크립트
../src/routes/api.ts	Bot Worker /api/test 엔드포인트
../openapi.yaml	API 문서

참고 자료

• Cloudflare Workers Docs
• Wrangler CLI
• Telegram Bot API