파이썬 텔레그램 봇 만들기 - BotFather 토큰 발급부터 자동 응답까지 30분 완성! (python-telegram-bot) ✈️

안녕하세요! Mojangcam입니다 😎

이 블로그에서 디스코드 봇 시리즈를 쭉 다뤄왔는데요, "디스코드는 안 쓰는데 폰으로 알림 받는 봇은 없나요?" 하는 분들께 딱 맞는 게 바로 텔레그램 봇이에요. 서버 상태 알림, 크롤링 결과 전송, 나만의 비서 봇까지 — 디스코드 봇보다 준비 과정이 훨씬 간단해서 30분이면 첫 봇을 띄울 수 있습니다!

이번 글에서 배울 것:

• BotFather로 봇 만들고 토큰 발급받기
• python-telegram-bot 라이브러리 설치
• /start 인사 봇 + 따라 말하는 에코 봇 만들기
• 명령어에 인자 받기 (/say 안녕)
• 자주 나는 에러와 해결법

🧠 텔레그램 봇, 디스코드 봇과 뭐가 다른가요?

개인 자동화 알림용이라면 텔레그램 쪽이 확실히 간단해요. 웹 크롤링으로 모은 정보를 폰으로 쏴주는 조합이 특히 인기예요!

📌 준비물

• Python 3.10 이상 (python --version으로 확인) — python-telegram-bot 22.x는 3.10 미만에서 설치되지 않아요!
• 텔레그램 계정 (폰에 앱 설치되어 있으면 OK)
• python-telegram-bot 라이브러리 — 이 글은 2026-07 기준 v22.8로 작성했어요
• (권장) 가상환경 — 만드는 법은 venv 완벽 정리 글 참고!

📌 1단계 - BotFather에서 봇 만들기

텔레그램 봇은 신기하게도 텔레그램 안에서 봇으로 만들어요. 봇들의 아버지, 공식 봇 @BotFather를 찾아갑니다.

1. 텔레그램 검색창에 BotFather 검색 → 파란 인증 체크 ✅ 있는 계정 선택
2. /newbot 입력
3. 봇 이름 입력 (예: 모장캠 알림봇) — 화면에 표시되는 이름이에요
4. 봇 아이디 입력 (예: mojangcam_alarm_bot) — 반드시 bot으로 끝나야 해요!
5. 완료되면 123456789:AAH... 형태의 토큰을 줍니다. 이걸 복사해두세요

⚠️ 토큰은 비밀번호와 같아요! 토큰만 있으면 누구나 내 봇을 조종할 수 있어요. 블로그·깃허브에 올리면 절대 안 됩니다. (깃허브에 올릴 땐 .env 파일로 분리 — 이건 다음에 자세히 다룰게요!)

📌 2단계 - 라이브러리 설치

# 가상환경 활성화 후 (권장)
pip install python-telegram-bot

설치 확인은 이렇게:

pip show python-telegram-bot
# Version: 22.8 처럼 나오면 성공!

참고로 예전(v13 이하) 문법을 쓰는 오래된 블로그 글이 아직 많은데, v20부터 문법이 완전히 바뀌었어요 (async 방식). 이 글 코드는 최신 22.x 기준이니 안심하고 따라오세요!

📌 3단계 - 첫 봇 실행: /start 인사 봇

bot.py 파일을 만들고 아래 코드를 붙여넣으세요.

# python-telegram-bot 22.x 기준 (2026-07)
from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("안녕하세요! 제 첫 텔레그램 봇이에요 🎉")

app = Application.builder().token("여기에_토큰_붙여넣기").build()
app.add_handler(CommandHandler("start", start))

print("봇이 실행됐어요! 종료는 Ctrl+C")
app.run_polling()

실행하고(python bot.py), 텔레그램에서 내 봇을 검색해 /start를 누르면 인사말이 옵니다!

하나씩 뜯어볼게요 💡

• async / await : 텔레그램 서버와 통신하는 동안 다른 일을 처리할 수 있게 해주는 비동기 문법이에요. 디스코드 봇을 만들어보셨다면 완전히 같은 패턴이라 익숙하실 거예요.
• Application : 봇의 본체예요. 토큰으로 만들고, 핸들러(기능)를 붙이는 구조입니다.
• CommandHandler("start", start) : /start 명령어가 오면 start 함수를 실행하라는 연결고리예요.
• run_polling() : 봇이 텔레그램 서버에 "새 메시지 있어요?" 하고 계속 물어보는 방식이에요. 별도 서버 없이 내 컴퓨터에서 바로 돌릴 수 있어요.

📌 4단계 - 에코 봇 + 인자 받는 명령어

이번엔 일반 메시지를 따라 말하고, /say 안녕처럼 인자도 받아볼게요. 토큰은 코드에 직접 쓰지 않고 환경변수로 빼고, 연결이 느리거나 막힌 환경을 대비해 타임아웃·재시도·프록시 옵션까지 넣은 버전이에요.

# python-telegram-bot 22.x 기준 (2026-07)
import os
from telegram import Update
from telegram.ext import (
    Application, CommandHandler, MessageHandler,
    ContextTypes, filters,
)

# 토큰은 코드에 박지 말고 환경변수로!
# PowerShell:  $env:TG_TOKEN="새_토큰"   (BotFather /revoke 로 재발급 권장)
TOKEN = os.environ.get("TG_TOKEN", "임시 토큰 입력")

# 텔레그램이 방화벽/ISP로 막힌 환경이면 프록시 주소를 넣으세요. 아니면 None.
PROXY = None  # 예: "http://127.0.0.1:1080"

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text("안녕하세요! /say 뒤에 할 말을 적어보세요")

async def say(update: Update, context: ContextTypes.DEFAULT_TYPE):
    if context.args:
        await update.message.reply_text(" ".join(context.args))
    else:
        await update.message.reply_text("사용법: /say 안녕하세요")

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(f"따라쟁이: {update.message.text}")

builder = (
    Application.builder()
    .token(TOKEN)
    # 타임아웃 넉넉하게 (느린 연결 대응)
    .connect_timeout(30)
    .read_timeout(30)
    .write_timeout(30)
    .pool_timeout(30)
    .get_updates_connect_timeout(30)
    .get_updates_read_timeout(30)
)

if PROXY:
    builder = builder.proxy(PROXY).get_updates_proxy(PROXY)

app = builder.build()
app.add_handler(CommandHandler("start", start))
app.add_handler(CommandHandler("say", say))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))

print("봇이 실행됐어요! 종료는 Ctrl+C")
# 첫 연결 실패 시 바로 죽지 않고 몇 번 재시도
app.run_polling(bootstrap_retries=3)

하나씩 뜯어볼게요 💡

• os.environ.get("TG_TOKEN", ...) : 토큰을 코드에 직접 박지 않고 환경변수에서 읽어와요. 깃허브에 코드를 올려도 토큰이 새지 않죠. PowerShell에서는 $env:TG_TOKEN="토큰"으로 설정해요.
• connect/read/write timeout : 인터넷이 느리거나 텔레그램 응답이 늦을 때 바로 끊기지 않도록 여유를 준 설정이에요.
• PROXY : 방화벽·ISP 때문에 텔레그램이 막힌 환경이라면 프록시 주소를 넣어 우회할 수 있어요. 평소엔 None으로 두면 됩니다.
• context.args : /say 안녕 반가워라고 치면 ["안녕", "반가워"]처럼 리스트로 들어와요.
• MessageHandler + filters : 명령어가 아닌(~filters.COMMAND) 텍스트(filters.TEXT) 메시지만 골라 받는 필터예요.
• bootstrap_retries=3 : 봇 시작 시 첫 연결이 실패해도 바로 죽지 않고 3번까지 재시도해요.

💡 자주 쓰는 핸들러 모음

📌 자주 나는 에러

1. InvalidToken 원인: 토큰을 잘못 붙여넣었거나 앞뒤에 공백이 들어간 경우예요. 해결: BotFather 메시지에서 토큰을 다시 복사하세요. 123456789:AAH... 형태 전체가 토큰이에요.

2. Conflict: terminated by other getUpdates request 원인: 같은 토큰으로 봇이 두 개 이상 실행 중일 때 나요 (이전 터미널 창이 살아있는 경우가 대부분!). 해결: 다른 터미널 창의 봇을 Ctrl+C로 종료하고 하나만 실행하세요.

3. AttributeError: 'Updater' object has no attribute 'dispatcher' 원인: 구버전(v13) 예제 코드를 최신 라이브러리에서 실행한 경우예요. 해결: Updater·dispatcher 대신 이 글처럼 Application.builder() 방식으로 바꿔주세요.

4. TimedOut / NetworkError (연결이 자꾸 끊겨요) 원인: 인터넷이 느리거나 방화벽·ISP가 텔레그램을 막은 경우예요. 해결: 위 코드처럼 타임아웃을 늘리고, 그래도 안 되면 PROXY에 프록시 주소를 넣어보세요.

5. 봇에게 말을 걸었는데 반응이 없어요 원인: 봇 프로그램이 꺼져 있거나, 봇과 아직 대화를 시작하지 않은 경우예요. 해결: 터미널에서 봇이 실행 중인지 확인하고, 봇 프로필에서 시작(/start) 버튼을 먼저 눌러주세요.

📌 마무리

오늘은 텔레그램 봇의 처음부터 끝까지를 다뤄봤어요. 정리하면 — ① BotFather에게 /newbot으로 토큰 발급 ② pip install python-telegram-bot ③ Application + 핸들러로 기능 연결 ④ run_polling()으로 실행! 디스코드 봇보다 훨씬 간단하죠? 😄

다음 단계로는 인라인 버튼 달기, 크롤링 결과 자동 전송, 서버에 올려 24시간 돌리기로 확장할 수 있어요. 시리즈로 이어갈 예정이니 기대해주세요 🙌

함께 보면 좋은 글:

• 파이썬 가상환경(venv) 완벽 정리 - 만들기부터 활성화·삭제까지
• 파이썬 업무 자동화 #2 - 웹 크롤링 입문 (requests + BeautifulSoup)
• 파이썬 이메일 자동 발송하기 - 지메일(Gmail) 자동화 스크립트
• 디스코드 봇 만들기 #9 - AI(Claude·ChatGPT API) 연동하기