grammY 통합 (Telegram Bot API)

grammY를 사용하는 이유

  • TS 우선 Bot API 클라이언트로 long-poll + webhook 헬퍼, 미들웨어, 에러 처리, rate limiter가 내장되어 있습니다.
  • 수동으로 fetch + FormData를 다루는 것보다 깔끔한 미디어 헬퍼를 제공하며, 모든 Bot API 메서드를 지원합니다.
  • 확장 가능: 커스텀 fetch를 통한 프록시 지원, 세션 미들웨어(선택사항), 타입 안전 컨텍스트를 제공합니다.

구현된 기능

  • 단일 클라이언트 경로: fetch 기반 구현이 제거되었으며, grammY가 이제 유일한 Telegram 클라이언트(전송 + Gateway)이며 grammY throttler가 기본으로 활성화되어 있습니다.
  • Gateway: monitorTelegramProvider는 grammY Bot을 빌드하고, 멘션/허용목록 게이팅을 연결하며, getFile/download를 통한 미디어 다운로드를 수행하고, sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument로 응답을 전달합니다. long-poll 또는 webhookCallback을 통한 webhook을 지원합니다.
  • 프록시: 선택적 channels.telegram.proxy는 grammY의 client.baseFetch를 통해 undici.ProxyAgent를 사용합니다.
  • Webhook 지원: webhook-set.ts는 setWebhook/deleteWebhook을 래핑하며, webhook.ts는 헬스 체크 + 우아한 종료와 함께 콜백을 호스팅합니다. Gateway는 channels.telegram.webhookUrl이 설정되면 webhook 모드를 활성화합니다(그렇지 않으면 long-poll 사용).
  • 세션: 직접 채팅은 에이전트 메인 세션(agent:<agentId>:<mainKey>)으로 병합되며, 그룹은 agent:<agentId>:telegram:group:<chatId>를 사용합니다. 응답은 동일한 채널로 라우팅됩니다.
  • 설정 옵션: channels.telegram.botToken, channels.telegram.dmPolicy, channels.telegram.groups(허용목록 + 멘션 기본값), channels.telegram.allowFrom, channels.telegram.groupAllowFrom, channels.telegram.groupPolicy, channels.telegram.mediaMaxMb, channels.telegram.linkPreview, channels.telegram.proxy, channels.telegram.webhookSecret, channels.telegram.webhookUrl.
  • 드래프트 스트리밍: 선택적 channels.telegram.streamMode는 비공개 토픽 채팅에서 sendMessageDraft를 사용합니다(Bot API 9.3+). 이는 channel block 스트리밍과는 별개입니다.
  • 테스트: grammY 목(mock)은 DM + 그룹 멘션 게이팅 및 아웃바운드 전송을 다룹니다. 더 많은 미디어/webhook fixture가 환영받습니다.

미해결 질문

  • Bot API 429 오류 발생 시 선택적 grammY 플러그인(throttler) 적용 여부.
  • 더 많은 구조화된 미디어 테스트(스티커, 음성 메모) 추가.
  • webhook 리스닝 포트를 설정 가능하게 만들기(현재 Gateway를 통해 연결하지 않는 한 8787로 고정).
← 문서로 돌아가기