grammY를 활용한 Telegram Bot API 통합

텔레그램 봇을 개발하다 보면 미디어 파일을 업로드하거나 복잡한 에러 상황을 처리하는 게 꽤 번거롭다는 걸 느끼셨을 거예요. fetch를 직접 써서 FormData를 맞추고, 속도 제한(Rate Limit)을 하나하나 관리하다 보면 정작 중요한 서비스 로직보다 인프라적인 부분에 더 많은 시간을 쓰게 되죠.

이런 번거로움을 해결하기 위해 우리는 grammY를 도입했습니다. grammY는 TypeScript 우선의 Bot API 클라이언트로, 미들웨어와 에러 핸들링은 물론 미디어 헬퍼 기능까지 갖추고 있어 훨씬 깔끔한 코드를 작성할 수 있게 도와줍니다.

필요한 것

• Telegram Bot Token (channels.telegram.botToken)
• Node.js 환경
• 웹훅 사용 시: webhookUrl 및 webhookSecret
• 프록시 사용 시: undici.ProxyAgent 설정

빠른 시작

이제 fetch 기반의 구현 대신 grammY가 전송(send)과 Gateway 역할을 모두 담당합니다. 5분 만에 설정을 마칠 수 있어요.

1. Gateway 구축: monitorTelegramProvider를 사용해 grammY Bot 인스턴스를 만드세요. 이 Gateway가 멘션 감지, 허용 목록(allowlist) 필터링, 그리고 getFile과 download를 통한 미디어 다운로드 로직을 자동으로 연결해 줍니다.
2. 연결 모드 결정: channels.telegram.webhookUrl과 channels.telegram.webhookSecret을 설정하면 웹훅 모드로 동작합니다. 이 값이 없으면 자동으로 long-polling 모드를 사용해요.
3. 메시지 전송: sendMessage, sendPhoto, sendVideo, sendAudio, sendDocument 메서드를 사용해 사용자에게 답장을 보낼 수 있습니다.
4. 세션 관리: 개인 채팅은 agent:<agentId>:<mainKey> 세션으로 통합되고, 그룹 채팅은 agent:<agentId>:telegram:group:<chatId> 형식을 사용하여 관리됩니다.

문제 해결

• Bot API 429 에러: 요청이 너무 많아 429 에러가 발생한다면, 기본으로 활성화되어 있는 grammY throttler 플러그인 설정을 확인해 보세요.
• 웹훅 포트 문제: 현재 웹훅 리스닝 포트는 8787로 고정되어 있습니다. Gateway를 통해 연결하지 않을 경우 포트 설정이 의도대로 작동하지 않을 수 있으니 주의하세요.

궁금한 점이 있거나 설정 중 도움이 필요하다면 AI Setup Assistant에게 언제든 물어보세요!

다음 단계

• webhook-set.ts: 웹훅 설정 및 삭제 로직 확인하기
• webhook.ts: 헬스 체크 및 Graceful Shutdown이 포함된 콜백 호스팅 알아보기
• monitorTelegramProvider: Gateway 구현 디테일 살펴보기
• channels.telegram.streamMode: Bot API 9.3+ 기반의 드래프트 스트리밍 설정하기