Telegram — 가장 인기 있는 봇 플랫폼

Telegram을 사용해 본 적이 있다면, 왜 이 플랫폼이 봇을 운영하기에 이렇게 훌륭한 곳인지 이미 알고 있을 거예요. 빠르고, 모든 기기에서 작동하며, 엄청난 사용자 기반을 갖추고 있죠. 하지만 여기서 중요한 점은 이겁니다: Telegram은 단순히 봇이 존재하는 곳이 아니라, 여러분의 Hermes 에이전트가 진정으로 빛을 발할 수 있는 곳이라는 거예요.

Hermes를 Telegram에 연결하면, 어디서든 대화할 수 있는 모든 기능을 갖춘 대화형 봇을 얻게 됩니다. 음성 메모를 보내면 자동으로 텍스트로 변환되고, 예약된 리포트를 요청하면 채팅창으로 바로 도착하죠. 봇을 그룹 채팅에 추가해서 대화에 참여시킬 수도 있어요. 텍스트, 음성, 이미지, 파일 첨부까지 모두 처리할 수 있으며, 이 모든 것이 탄탄한 python-telegram-bot 라이브러리를 기반으로 작동합니다.

이제 단계별로 설정 과정을 살펴볼게요.

1단계: BotFather로 봇 만들기

모든 Telegram 봇은 Telegram 공식 봇 관리자인 @BotFather에게서 받은 API 토큰으로 시작합니다. 토큰을 받는 방법은 다음과 같아요:

Telegram을 열고 @BotFather를 검색하거나 t.me/BotFather로 이동하세요.
/newbot 명령어를 보내세요.
표시 이름을 정하세요. “Hermes Agent”처럼 마음에 드는 이름이면 됩니다.
사용자 이름을 선택하세요. 이 이름은 고유해야 하며 bot으로 끝나야 합니다 (예: my_hermes_bot).
BotFather가 다음과 같은 형식의 API 토큰을 답장으로 보내줍니다:

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

토큰은 절대 공유하지 마세요! 이 토큰만 있으면 누구나 여러분의 봇을 제어할 수 있습니다. 만약 토큰이 유출되었다면, BotFather에서 /revoke 명령어로 즉시 토큰을 폐기하세요.

2단계: 봇 커스터마이징 (선택 사항이지만 추천!)

몇 가지 간단한 BotFather 명령어만으로 봇을 세련되고 전문적으로 보이게 만들 수 있어요:

명령어	용도
`/setdescription`	대화를 시작하기 전에 표시되는 “이 봇이 무엇을 할 수 있나요?” 설명 텍스트
`/setabouttext`	봇 프로필 페이지에 표시되는 짧은 소개글
`/setuserpic`	봇의 프로필 사진 업로드
`/setcommands`	명령어 메뉴 정의 (채팅창의 `/` 버튼)
`/setprivacy`	봇이 그룹의 모든 메시지를 볼 수 있는지 제어 (3단계 참고)

/setcommands의 경우, 다음과 같은 기본 명령어 세트가 유용합니다:

help - 도움말 정보 표시
new - 새 대화 시작
sethome - 이 채팅을 홈 채널로 설정

온라인/오프라인 상태 표시기 (선택 사항)

Telegram 봇은 일반 사용자 계정처럼 초록색 “온라인” 표시가 없어요. 가장 비슷한 기능은 봇의 짧은 설명(short description) — 프로필 페이지에서 이름 아래에 표시되는 한 줄입니다.

status_indicator를 활성화하면 Hermes가 게이트웨이 연결 시 해당 설명을 Online으로, 정상 종료 시 Offline으로 설정합니다:

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

참고 사항 몇 가지: 이 설명은 전역적으로 표시되며(모든 사용자에게 보임), “Offline” 상태가 기록되는 것은 정상 종료 시에만 해당합니다. 갑작스러운 크래시가 발생하면 마지막 상태가 그대로 유지되죠. 봇의 프로필을 변경하기 때문에 기본값은 비활성화되어 있습니다.

명령어 메뉴 우선순위 및 상한선 (선택 사항)

Hermes는 Telegram 게이트웨이가 시작될 때 명령어 메뉴를 자동으로 등록합니다. 기본적으로 최대 60개의 명령어로 제한되며, 이는 모든 기본 명령어와 일반적인 스킬을 포함하기에 충분한 수치입니다. / 선택기에 계속 표시되어야 하는 플러그인 명령어가 있다면 우선순위를 지정할 수 있어요:

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

prepend: 여러분의 명령어가 먼저, 그 다음 Hermes 기본 명령어
append: Hermes 기본 명령어가 먼저, 그 다음 여러분의 명령어
replace: 우선순위 정렬에 여러분의 목록만 사용

Telegram은 최대 100개의 명령어를 허용하지만, 큰 페이로드는 실패할 수 있습니다. Hermes는 안정성을 위해 기본값을 60으로 설정하며, 값을 1..100 범위로 제한합니다.

3단계: 프라이버시 모드 — 그룹에서 매우 중요!

그룹에서 봇을 사용할 때 가장 혼란스러운 부분 #1: 프라이버시 모드는 기본적으로 ON입니다.

프라이버시 모드가 ON인 경우, 봇은 다음만 볼 수 있습니다:

/로 시작하는 메시지
봇 자신의 메시지에 대한 답글
서비스 메시지 (참여, 퇴장, 고정)
봇이 관리자인 채널의 메시지

프라이버시 모드가 OFF인 경우, 봇은 그룹의 모든 메시지를 볼 수 있습니다.

프라이버시 모드를 끄려면:

@BotFather에게 메시지를 보내세요.
/mybots 명령어를 전송하세요.
봇을 선택하세요.
Bot Settings → Group Privacy → Turn off로 이동하세요.

중요: 이 설정을 변경한 후에는 봇을 그룹에서 제거하고 다시 추가해야 합니다. Telegram은 봇이 그룹에 참여할 때 프라이버시 상태를 캐시하므로, 다시 추가하기 전까지는 업데이트되지 않습니다.

대안: 봇을 그룹 관리자로 승격시키세요. 관리자 봇은 항상 모든 메시지를 수신하므로 프라이버시 토글 설정이 필요 없습니다.

자동 응답 없이 그룹 대화 관찰하기

봇이 그룹 메시지를 보기만 하고 언급될 때만 응답하길 원하시나요? 다음과 같이 설정하세요:

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

허용된 채팅에서 온 언급되지 않은 메시지는 세션 기록에 관찰된 컨텍스트로 추가되지만, 에이전트를 트리거하지는 않습니다. 이후에 @봇이름으로 언급해야만 실제 응답이 전송됩니다.

이게 전부예요! 이 세 가지 단계만 거치면 Hermes 에이전트로 구동되는 완전한 기능의 Telegram 봇을 갖게 됩니다. 이제 음성 메모를 보내보고, 그룹에 추가해보고, 마법이 펼쳐지는 걸 지켜보세요.