파이썬으로 텔레그램 Echo Bot 만들기

목차

1. 프로젝트 개요
2. 학습 목표
3. Echo Bot이란?
4. 필요한 프로그램
5. BotFather로 텔레그램 봇 생성
6. 프로젝트 폴더 만들기
7. Python 가상환경 만들기
8. 라이브러리 설치
9. .env 파일로 토큰 관리
10. .gitignore 파일 만들기
11. bot.py 작성
12. 코드 상세 설명
13. Echo Bot 실행
14. 모바일 텔레그램에서 테스트
15. 봇 종료
16. 자주 발생하는 오류
17. Echo Bot 실습 문제
18. 전체 동작 정리

---

1. 프로젝트 개요

사용자가 텔레그램 앱에서 보낸 메시지를 Python 프로그램이 받아 그대로 응답하는 Echo Bot을 만듭니다.

사용자: 안녕하세요
봇: 받은 메시지: 안녕하세요

기능은 단순하지만 아래 흐름을 한 번에 확인할 수 있는 좋은 기초 프로젝트입니다.

텔레그램 모바일 앱
        ↓
Telegram Bot API
        ↓
Python 프로그램
        ↓
메시지 처리
        ↓
텔레그램으로 응답

텔레그램 봇은 @BotFather에서 생성하며, 발급받은 토큰으로 Python 프로그램과 연결합니다.

---

2. 학습 목표

텔레그램 봇의 기본 개념
BotFather를 이용한 봇 생성
Bot Token의 역할
Python 가상환경 사용
.env 파일을 이용한 토큰 관리
텔레그램 명령어 처리
일반 텍스트 메시지 처리
Polling 방식의 동작 원리

---

3. Echo Bot이란?

Echo는 입력한 내용을 그대로 돌려주는 것을 의미합니다.

입력: 파이썬 공부
출력: 파이썬 공부

이번 봇은 앞에 설명을 붙여 다음처럼 응답합니다.

입력: 파이썬 공부
출력: 받은 메시지: 파이썬 공부

Echo Bot은 복잡한 기능을 추가하기 전, 텔레그램과 Python이 정상적으로 연결됐는지 확인하는 통신 테스트용 프로그램입니다.

---

4. 필요한 프로그램

Telegram 모바일 앱
Python
Visual Studio Code
VS Code PowerShell 터미널

Python 설치 확인:

py --version

정상 예시:

Python 3.13.5

---

5. BotFather로 텔레그램 봇 생성

5.1 BotFather 검색

텔레그램 검색창에서 다음 계정을 찾습니다.

@BotFather

BotFather는 텔레그램에서 공식적으로 제공하는 봇 생성·관리 도구입니다.

5.2 새 봇 만들기

/newbot

봇 이름 (사용자 화면에 표시되는 이름) 입력 예:

Python Echo Bot

봇 사용자명 입력 예:

my_echo_bot

사용자명은 영문자·숫자·밑줄을 사용할 수 있으며 반드시 bot으로 끝나야 합니다. 다른 사람이 이미 사용 중인 이름은 등록할 수 없습니다.

5.3 Bot Token 발급

1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Bot Token = 텔레그램 봇의 비밀번호와 같은 값

⚠️ 토큰을 알고 있는 사람은 해당 봇을 제어할 수 있으므로 외부에 공개하면 안 됩니다. 노출된 경우 BotFather에서 새 토큰을 재발급받아야 합니다.

---

6. 프로젝트 폴더 만들기

C:\python\telegram_echo_bot

VS Code: File → Open Folder → telegram_echo_bot 폴더 선택

터미널 열기: Terminal → New Terminal (단축키: Ctrl+`)

---

7. Python 가상환경 만들기

가상환경이란? 프로젝트마다 라이브러리를 독립적으로 관리하는 공간입니다.

텔레그램 프로젝트 → 텔레그램용 라이브러리
다른 Python 프로젝트 → 해당 프로젝트용 라이브러리

가상환경은 프로젝트별로 Python 라이브러리와 버전을 분리해서 관리하기 위한 전용 작업공간입니다.

생성

py -m venv .venv

요소 의미

py	Windows에서 Python 실행 명령
-m	Python 모듈 실행 옵션
venv	가상환경 생성 모듈
.venv	생성될 폴더 이름

활성화

.venv\Scripts\Activate.ps1

실행 정책 오류 발생 시:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.venv\Scripts\Activate.ps1

정상 활성화 표시:

(.venv) PS C:\python\telegram_echo_bot>

---

8. 라이브러리 설치

라이브러리 역할

python-telegram-bot	텔레그램 메시지 수신 및 응답
python-dotenv	.env 파일의 설정값 읽기

pip install python-telegram-bot python-dotenv

관리 명령

pip list                          # 설치된 라이브러리 확인
pip freeze > requirements.txt     # 목록 저장
pip install -r requirements.txt   # 다른 PC에 동일 환경 설치

---

9. .env 파일로 토큰 관리

토큰을 코드에 직접 넣으면(예: TOKEN = "1234...") 소스코드 공유 시 함께 노출될 위험이 있습니다. 따라서 코드와 비밀정보를 분리합니다.

bot.py → Python 프로그램 코드
.env   → Telegram Bot Token 같은 설정값

.env 파일 생성 (파일명은 정확히 .env, .env.txt 아님)

TELEGRAM_BOT_TOKEN=BotFather에서_발급받은_실제_토큰

예시:

TELEGRAM_BOT_TOKEN=1234567890:AAxxxxxxxxxxxxxxxxxxxx

값에 따옴표는 넣지 않아도 됩니다.

---

10. .gitignore 파일 만들기

.env
.venv/
__pycache__/

항목 의미

.env	실제 Bot Token이 저장된 파일
.venv/	가상환경과 설치된 라이브러리
__pycache__/	Python이 자동 생성하는 임시 캐시

최종 폴더 구조

telegram_echo_bot
 ├─ .venv
 ├─ .env
 ├─ .gitignore
 ├─ bot.py
 └─ requirements.txt

---

11. bot.py 작성

import os

from dotenv import load_dotenv
from telegram import Update
from telegram.ext import (
    Application,
    CommandHandler,
    ContextTypes,
    MessageHandler,
    filters,
)


# 현재 프로젝트 폴더의 .env 파일을 읽습니다.
load_dotenv()

# .env 파일에서 Telegram Bot Token을 가져옵니다.
TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")


async def start(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    """사용자가 /start 명령을 입력했을 때 실행됩니다."""

    if update.message is None:
        return

    await update.message.reply_text(
        "안녕하세요. 텔레그램 Echo Bot입니다.\n"
        "메시지를 입력하면 그대로 응답합니다."
    )


async def echo(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    """사용자가 보낸 일반 텍스트를 그대로 응답합니다."""

    if update.message is None:
        return

    if update.message.text is None:
        return

    user_message = update.message.text

    await update.message.reply_text(
        f"받은 메시지: {user_message}"
    )


def main() -> None:
    """텔레그램 봇을 생성하고 실행합니다."""

    if not TOKEN:
        raise RuntimeError(
            "TELEGRAM_BOT_TOKEN을 찾을 수 없습니다.\n"
            ".env 파일과 토큰값을 확인하세요."
        )

    application = (
        Application.builder()
        .token(TOKEN)
        .build()
    )

    # /start 명령을 처리합니다.
    application.add_handler(
        CommandHandler("start", start)
    )

    # 명령어가 아닌 일반 텍스트를 처리합니다.
    application.add_handler(
        MessageHandler(
            filters.TEXT & ~filters.COMMAND,
            echo,
        )
    )

    print("텔레그램 Echo Bot이 실행되었습니다.")
    print("종료하려면 Ctrl+C를 누르세요.")

    # 텔레그램 서버에서 새로운 메시지를 계속 확인합니다.
    application.run_polling()


if __name__ == "__main__":
    main()

현재 python-telegram-bot 공식 문서도 Application.builder()로 애플리케이션을 만들고 CommandHandler, MessageHandler, filters를 조합하는 구조를 사용합니다.

---

12. 코드 상세 설명

12.1 모듈 가져오기

코드 역할

import os	운영체제 환경변수를 읽을 때 사용
from dotenv import load_dotenv	.env 내용을 프로그램 환경변수로 불러옴
from telegram import Update	메시지·사용자·채팅 정보가 담긴 업데이트 객체

12.2 .env 파일 읽기

load_dotenv()
TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")

처리 흐름

.env 파일 → load_dotenv() → 프로그램 환경변수 → os.getenv() → TOKEN 변수

12.3 /start 명령 처리

텔레그램 명령어는 /start, /help처럼 /로 시작하며, CommandHandler가 이를 처리합니다.

await update.message.reply_text(
    "안녕하세요. 텔레그램 Echo Bot입니다."
)

현재 채팅방에 메시지를 응답합니다. await는 텔레그램 서버 응답을 기다리며 비동기로 처리하기 위해 사용합니다.

12.4 일반 메시지 처리

user_message = update.message.text
await update.message.reply_text(f"받은 메시지: {user_message}")

사용자 입력 텍스트를 가져와 받은 메시지:를 붙여 응답합니다.

12.5 Application 생성

application = Application.builder().token(TOKEN).build()

Application = 텔레그램 봇 실행과 메시지 처리를 관리하는 중심 객체

12.6 Handler 등록

application.add_handler(CommandHandler("start", start))
application.add_handler(
    MessageHandler(filters.TEXT & ~filters.COMMAND, echo)
)

조건 의미

filters.TEXT	텍스트 메시지만 선택
~filters.COMMAND	/start 같은 명령어는 제외
echo	조건에 맞는 메시지를 처리할 함수

12.7 Polling 방식

application.run_polling()

프로그램이 텔레그램 서버에 새 메시지가 있는지 지속적으로 확인합니다.

/start 입력 → CommandHandler → start() 실행
일반 텍스트 입력 → MessageHandler → echo() 실행

12.8 프로그램 시작 위치

if __name__ == "__main__":
    main()

bot.py를 직접 실행했을 때만 main()을 호출합니다.

python bot.py

---

13. Echo Bot 실행

가상환경 활성화 확인:

(.venv) PS C:\python\telegram_echo_bot>

실행:

python bot.py

정상 결과:

텔레그램 Echo Bot이 실행되었습니다.
종료하려면 Ctrl+C를 누르세요.

터미널 입력 프롬프트가 돌아오지 않는 것은 오류가 아니라, 프로그램이 종료되지 않고 메시지를 기다리는 정상 상태입니다.

---

14. 모바일 텔레그램에서 테스트

봇 채팅방에서 시작 버튼 또는 /start 입력:

안녕하세요. 텔레그램 Echo Bot입니다.
메시지를 입력하면 그대로 응답합니다.

일반 메시지 테스트:

입력: 안녕하세요
응답: 받은 메시지: 안녕하세요

입력: 파이썬을 공부하고 있습니다
응답: 받은 메시지: 파이썬을 공부하고 있습니다

이 결과가 나오면 다음이 모두 정상입니다.

Bot Token 정상
Python 프로그램 실행 정상
Telegram 메시지 수신 정상
Python 메시지 처리 정상
Telegram 응답 전송 정상

---

15. 봇 종료

VS Code 터미널에서 Ctrl + C

bot.py 실행 중 → 봇 응답 가능
bot.py 종료   → 봇 응답 불가

---

16. 자주 발생하는 오류

오류 확인 사항

TELEGRAM_BOT_TOKEN을 찾을 수 없습니다	.env가 bot.py와 같은 폴더인지 / 파일명이 .env.txt가 아닌지 / 변수명 철자 / 토큰값 입력 여부 / python-dotenv 설치 여부
ModuleNotFoundError: No module named 'telegram'	pip install python-telegram-bot (가상환경 활성화 상태에서 설치)
ModuleNotFoundError: No module named 'dotenv'	pip install python-dotenv
모바일에서 응답 없음	bot.py 실행 중인지 / /start 눌렀는지 / 토큰 정확한지 / 인터넷 연결 / 같은 토큰을 여러 PC에서 동시 실행 중인지
PowerShell 가상환경 활성화 오류	Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass 실행 후 재시도

같은 Bot Token으로 Polling 프로그램을 여러 곳에서 동시에 실행하면 메시지 처리 충돌이 발생할 수 있으므로 한 곳에서만 실행합니다.

---

17. Echo Bot 실습 문제

실습 1. 응답 문구 변경

받은 메시지: 안녕하세요  →  당신이 보낸 내용은 '안녕하세요'입니다.

await update.message.reply_text(
    f"당신이 보낸 내용은 '{user_message}'입니다."
)

실습 2. 메시지 길이 표시

message_length = len(user_message)

await update.message.reply_text(
    f"받은 메시지: {user_message}\n"
    f"문자 수: {message_length}"
)

실습 3. 사용자 이름 표시

user = update.effective_user

await update.message.reply_text(
    f"{user.first_name}님이 보낸 메시지:\n"
    f"{user_message}"
)

실습 4. 특정 단어에 별도 응답

if user_message == "안녕하세요":
    await update.message.reply_text("반갑습니다.")
    return

실습 5. /help 명령 추가

async def help_command(
    update: Update,
    context: ContextTypes.DEFAULT_TYPE,
) -> None:
    if update.message is None:
        return

    await update.message.reply_text(
        "Echo Bot 사용법\n"
        "1. 텍스트 메시지를 입력합니다.\n"
        "2. 봇이 같은 내용을 응답합니다."
    )

application.add_handler(CommandHandler("start", start))
application.add_handler(CommandHandler("help", help_command))
application.add_handler(
    MessageHandler(filters.TEXT & ~filters.COMMAND, echo)
)

---

18. 전체 동작 정리

1. 사용자가 텔레그램에서 메시지를 입력한다.
2. Telegram 서버가 메시지를 보관한다.
3. Python의 run_polling()이 새 메시지를 확인한다.
4. MessageHandler가 일반 텍스트인지 확인한다.
5. echo() 함수가 메시지를 가져온다.
6. reply_text()가 응답을 전송한다.
7. 사용자가 모바일에서 응답을 확인한다.

핵심 구성 요소

구성 요소 역할

Application	텔레그램 봇 프로그램 생성 및 실행
Handler	어떤 메시지를 어떤 함수가 처리할지 연결
Callback 함수	실제 메시지를 처리하고 응답

Echo Bot은 사용자의 메시지를 그대로 돌려주는 간단한 프로그램이지만, 텔레그램 앱과 Python 프로그램 사이의 메시지 송수신 구조를 이해하기 위한 가장 기본적인 봇 프로젝트입니다. 정상 작동을 확인했다면 날씨 조회, 서버 상태 확인, AI 챗봇, 일정 관리 등으로 확장할 수 있습니다.

텔레그램_Echo_Bot_교육자료.md.pdf

0.56MB