텔레그램 봇으로 Claude 작업 결과 받기

Claude나 Cowork에 일을 시켜놓고 다른 일을 보다가, “끝났나?” 싶어 매번 창을 열어 확인하는 분이 많습니다. 작업이 1분 안에 끝나면 괜찮지만, 5분·10분·30분짜리 에이전트 작업은 끝났는지 모르는 시간이 가장 비싼 시간입니다.

이 글에서는 에이전트가 일을 마치면 내 폰의 텔레그램으로 자동 알림이 오게 만드는 가장 간단한 방법을 4단계로 정리합니다. 코드 한 줄 짜지 않고도 가능합니다 — 텔레그램이 제공하는 봇 API를 Claude가 알아서 호출하면 되니까요.

이 글이 필요한 분: 장시간 에이전트 작업의 완료 알림을 받고 싶은 분, 일일 브리핑·크롤링 결과·에러 알림을 폰으로 즉시 받고 싶은 분, 이메일 알림(email 스킬 설정 가이드)과 함께 짧은 푸시 알림 채널을 하나 더 두고 싶은 분.

왜 텔레그램인가

알림 채널은 여러 가지가 있지만, 텔레그램 봇은 다음 조합이 강력합니다:

무료 — 봇 생성·메시지 발송 모두 무료. API 호출 한도도 개인 알림 용도로는 사실상 무제한
즉시 푸시 — 메시지 도착 즉시 폰의 알림 센터에 뜸. 슬랙·디스코드처럼 워크스페이스 가입·채널 세팅이 필요 없음
단순한 API — https://api.telegram.org/bot{TOKEN}/sendMessage 한 줄. Claude가 curl로 바로 호출 가능
공식 데스크톱·모바일 앱 — 어디서나 동일하게 알림 수신
봇 만드는 데 30초 — BotFather와 대화 한 번이면 끝

이메일이 길고 첨부 있는 결과에 강하다면, 텔레그램은 짧고 즉시성 있는 알림에 강합니다. 두 채널을 함께 쓰면 가장 자연스럽습니다.

Step 1: BotFather에서 봇 만들기

텔레그램의 모든 봇은 BotFather라는 공식 봇을 통해 만들어집니다. BotFather 자체도 봇입니다 — 메타입니다.

텔레그램 앱을 열고 검색창에 @BotFather 입력 → 파란 체크 마크가 붙은 공식 계정 선택
Start 버튼을 누르거나 /start 입력 → BotFather가 명령어 목록을 보여줌
/newbot 입력
BotFather가 두 가지를 차례로 묻습니다:
- 봇 이름 (display name) — 사람이 보는 이름. 자유롭게 입력 (예: 내 작업 알림)
- 봇 username — @로 시작하는 고유 식별자. 반드시 bot으로 끝나야 함 (예: mywork_alert_bot)

성공하면 BotFather가 다음과 같은 메시지를 보냅니다:

Done! Congratulations on your new bot. ...
Use this token to access the HTTP API:
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ_1234567890
Keep your token secure ...

이 토큰을 복사해서 안전한 곳에 보관하세요. 토큰은 봇의 비밀번호입니다. 노출되면 누구나 그 봇으로 메시지를 보낼 수 있으니, 공개 저장소에 절대 커밋하지 마세요.

참고: 토큰을 잃어버렸거나 노출된 것 같다면 BotFather에게 /revoke를 보내 새 토큰으로 갱신할 수 있습니다.

Step 2: 만든 봇과 첫 대화 시작하기

봇을 만들었다고 해서 바로 메시지를 받을 수 있는 건 아닙니다. 봇과 한 번 대화를 시작해야 텔레그램이 “이 사용자는 이 봇과 채팅 중”이라는 사실을 인지하고, 그 채팅방의 ID(=chat_id)를 발급합니다.

BotFather가 보낸 메시지에는 보통 t.me/<your_bot_username> 같은 링크가 함께 들어 있습니다. 그 링크를 누르면 새로 만든 봇의 채팅방으로 이동합니다.
채팅방에서 Start 버튼을 누르세요. (또는 /start라고 입력해도 동일)
이어서 아무 메시지나 한 줄 보내세요 — 예: 안녕. 메시지 내용은 중요하지 않고, 당신이 봇에게 말을 걸었다는 사실이 중요합니다. 이걸 안 하면 다음 Step 3에서 chat_id가 잡히지 않습니다.

Step 3: chat_id 알아내기

이제 내가 만든 봇 입장에서 나라는 사용자의 채팅방 ID를 알아내야 합니다. 텔레그램은 getUpdates API로 봇이 받은 최근 메시지 목록을 알려주는데, 그 응답 안에 chat.id가 들어 있습니다.

가장 편한 방법은 스킬.잇다가 제공하는 전용 도구를 쓰는 것입니다.

방법 A — 스킬.잇다의 Telegram getUpdates 뷰어 사용 (권장)

브라우저에서 스킬.잇다의 Telegram getUpdates 뷰어로 이동
입력란에 Step 1에서 복사한 Bot Token을 붙여넣고 조회 클릭
JSON 응답이 표시되며 "chat": { "id": 42478249, ... } 부분에서 숫자(chat.id)를 클릭하면 클립보드에 자동 복사됩니다

이 도구의 좋은 점은:

토큰이 어디에도 전송되지 않습니다 — 브라우저에서 직접 api.telegram.org를 호출하므로, 스킬.잇다 서버는 토큰을 볼 수 없습니다
다음 방문 시 자동 채움을 위해 토큰은 이 브라우저의 localStorage에만 저장됩니다. 공용 PC에서 사용했다면 페이지 안의 저장된 Bot Token 삭제 버튼을 누르세요

자주 막히는 지점 — 응답이 빈 배열일 때

조회를 눌렀는데 "result":[]처럼 비어 있다면 거의 두 가지 원인 중 하나입니다.

봇과 첫 메시지를 아직 안 보냈을 때 — Step 2를 건너뛴 경우입니다. “왜 chat_id가 안 보이지?” 싶으면 십중팔구 이 경우입니다. 텔레그램 앱에서 봇 채팅창을 열고 아무 메시지나 한 줄 보낸 뒤 다시 조회하세요.
메시지를 보냈는데도 빈 배열일 때 — 텔레그램 서버 쪽 전파 지연이거나, 이전에 다른 클라이언트(혹은 직전 호출)가 같은 update를 이미 가져가 버린 경우입니다. 이때는 봇 채팅창에서 메시지를 2~3번 더 보내고 다시 조회해 보세요. 보통 그 안에 잡힙니다. 그래도 비어 있다면 약 1분 정도 기다렸다가 한 번 더 시도하면 됩니다.

Step 4: Claude에게 메시지 발송 부탁하기

이제 두 가지를 손에 넣었습니다:

Bot Token: 123456789:ABCdefGHI... (Step 1에서 복사)
Chat ID: 42478249 (Step 3에서 복사)

이 둘을 Claude에게 알려주면 끝입니다. Claude나 Cowork 대화창에서 다음과 같이 말하세요:

내 텔레그램 봇으로 메시지를 보내줘. Bot Token: 123456789:ABCdefGHI... Chat ID: 42478249 내용: “오늘 작업 완료. 결과는 곧 정리해서 보낼게.”

Claude는 이 정보를 받아 위의 curl 명령을 실행하고, 응답을 확인한 뒤 “보냈습니다” 같은 회신을 줍니다. 폰을 보면 메시지가 와 있을 겁니다.

한 걸음 더 — 파일·이미지·문서도 보내기

sendMessage로 텍스트만 보낼 수 있는 게 아닙니다. 텔레그램 Bot API는 거의 모든 형식의 파일 전송을 지원합니다. 결과 파일 자체를 폰으로 직접 받는 게 핵심입니다. 보고서 PDF, 차트 이미지, 데이터 ZIP 같은 산출물을 알림과 함께 그대로 받을 수 있죠.

자주 쓰는 발송 API

API	용도	크기 한도 (Bot API 기준)
`sendMessage`	텍스트 (마크다운/HTML 일부 지원)	4,096자
`sendPhoto`	이미지 (jpg, png) — 텔레그램이 자동 압축	10 MB
`sendDocument`	모든 형식의 파일 (pdf, zip, xlsx, csv, txt 등) — 압축 없이 원본 그대로	50 MB
`sendAudio`	음성·음악 (mp3, m4a)	50 MB
`sendVideo`	동영상 (mp4)	50 MB
`sendMediaGroup`	사진·동영상 묶어서 앨범으로 한 번에	항목당 위 한도

50 MB가 넘는 파일은 표준 Bot API로는 보낼 수 없습니다. 그보다 큰 결과물은 클라우드에 올린 뒤 링크만 텍스트로 보내는 편이 낫습니다.

Claude에게 파일 발송 부탁하기

원리는 텍스트 메시지와 같습니다. 파일 경로만 함께 알려주면 됩니다:

내 텔레그램 봇으로 이 보고서 파일 보내줘. Bot Token: 123456789:ABCdefGHI... Chat ID: 42478249 파일: /Users/me/Downloads/weekly-report.pdf 캡션: “이번 주 리포트”

Claude는 위 sendDocument curl 명령을 만들어 실행합니다. 이미지면 sendPhoto, 음성이면 sendAudio로 알아서 골라줍니다.

상시 알림 채널로 등록하기

매번 토큰과 chat_id를 알려주는 건 번거롭습니다. 아래 템플릿을 지침 영역에 한 번 넣어두면 Claude가 알림이 필요할 때마다 알아서 사용합니다.

Claude Code: 프로젝트의 CLAUDE.md 또는 사용자 전역 ~/.claude/CLAUDE.md에 붙여넣기 — 모든 세션에서 자동 로드
Cowork: 로컬 파일 시스템(~/.claude/CLAUDE.md)을 읽지 못하므로, 프로젝트의 시스템 프롬프트·지침 영역에 붙여넣거나 세션 시작 시 한 번 주입

## 비상연락망 (Emergency Contact)

급히 알려야 할 사항이 있을 때 아래 텔레그램으로 메시지를 전송한다.

- **Bot Token**: `123456789:ABCdefGHI...`
- **Chat ID**: `42478249`

### 메시지 전송 (curl)

```bash
curl -s -X POST "https://api.telegram.org/bot123456789:ABCdefGHI.../sendMessage" \
  -d chat_id=42478249 \
  -d text="메시지 내용"
```

### 사용 시점

- 장시간 백그라운드 작업 완료/실패 시
- 사용자 확인이 필요한 중요 이슈 발생 시
- 자동화 작업에서 에러가 반복될 때

이렇게 한 번 적어두면 다음부터는 “끝나면 텔레그램으로 알려줘” 한 줄로 충분합니다.

보안 주의 [HARD]: Bot Token은 봇의 비밀번호입니다. 절대 다음 위치에 두지 마세요:

공개 GitHub 저장소 (CLAUDE.md를 커밋하는 경우 특히 주의)

공유 문서, 슬랙 채널, 디스코드

스크린샷·블로그 글의 본문

노출되었다면 즉시 BotFather에게 /revoke를 보내 토큰을 갱신하세요. Claude Code를 쓴다면 개인 머신의 사용자 전역 ~/.claude/CLAUDE.md처럼 나만 접근하는 곳에 두는 것이 안전합니다. Cowork에서는 해당 경로를 읽지 못하므로 프로젝트 지침 영역에만 두고, 프로젝트를 외부에 공유하지 않도록 주의하세요.

활용 예시

토큰·chat_id를 등록해 두면, 알림 채널로 활용할 수 있는 시나리오는 사실상 무한합니다:

장시간 에이전트 작업 완료 알림 — 30분짜리 크롤링이 끝나면 폰으로 “완료” 푸시
에러 알림 — 백그라운드 스크립트가 3회 연속 실패하면 즉시 알림
일일 브리핑 — 매일 아침 08:50, 어제 환율·뉴스 요약을 폰으로 직배송
빌드/배포 알림 — bun astro build 성공/실패 결과
스케줄 작업의 결과 요약 — 스킬이 자동 실행된 직후 한 줄 요약
결과 파일 직배송 — 주간 리포트 PDF, 차트 이미지, 데이터 ZIP을 sendDocument로 폰에 직접 받기 (50 MB까지)

PART 5(Cowork 자동화)에서 다루는 스케줄 실행·폴더 감시·커넥터 어느 트리거와도 조합할 수 있습니다.

이메일 알림과 비교

알림 채널은 이메일과 텔레그램 두 가지를 함께 두는 것이 가장 자연스럽습니다.

항목	이메일 (SMTP)	텔레그램 봇
적합한 길이	길고 첨부 있는 결과	짧고 즉시성 있는 알림
도착 속도	보통 (몇 초~수 분)	즉시 (1초 이내)
첨부 파일	O (원본 결과·보고서)	O (이미지·문서, 50MB까지)
검색·아카이브	강함	약함 (스크롤로만)
설정 가이드	Email 스킬 설정 가이드	(이 글)

규칙은 단순합니다:

결과물(보고서, 첨부)은 → 이메일
알림(완료, 에러, 짧은 요약)은 → 텔레그램

두 채널을 같이 쓰면 “끝났나?” 확인하러 창을 열 일이 거의 사라집니다.

정리

텔레그램 봇으로 Claude 작업 알림을 받기까지 4단계:

BotFather에서 /newbot → Bot Token 복사
만든 봇과 첫 메시지 한 줄 주고받기
스킬.잇다의 Telegram getUpdates 뷰어에서 토큰 입력 → chat_id 복사
Claude에게 “이 토큰과 chat_id로 메시지 보내줘” — 끝

시간으로 따지면 처음 한 번은 3분, 두 번째부터는 그냥 “끝나면 알려줘” 한 줄입니다. 이메일 설정(Email 스킬 설정 가이드)도 함께 해두면, 에이전트가 일하는 동안 다른 일을 마음 편히 볼 수 있습니다.