Telegram 메신저 안에서 바로 동작하는 AI 비서 봇 만들기
ChatGPT나 Claude를 자주 쓰시나요? 브라우저를 열고 사이트에 접속해서 질문을 입력하고… 매번 이 과정이 귀찮지 않으셨나요?
이 글에서는 Telegram 메신저 안에서 바로 동작하는 AI 비서 봇을 만듭니다. Telegram에 메시지를 보내면 LLM이 답변하고, 필요하면 웹 검색도 하고, 이미지도 분석합니다. 코딩은 Python으로 약 100줄이면 충분하며, VPS에 배포해서 24시간 온라인 상태로 만드는 전체 과정을 다룹니다.
왜 Telegram인가?
Telegram은 전 세계 9억 명이 쓰는 메신저입니다. 그리고 봇 API가 무료로 열려 있습니다. 카카오톡이나 라인과 달리, 개발자가 자유롭게 봇을 만들고 배포할 수 있습니다. Slack 봇과 비슷하지만, 개인용으로 쓰기에 더 가볍고 접근성이 좋습니다.
한 번 만들면 친구들에게 공유할 수도 있고, 팀 프로젝트에 연동할 수도 있습니다. 재미있는 점은, 이 봇에 기능을 계속 붙여나갈 수 있다는 것입니다. 날씨 확인, 번역, 일정 관리… 원하는 것을 다 넣을 수 있습니다.
1. BotFather로 봇 생성하기
먼저 Telegram에서 봇을 생성합니다. Telegram 앱을 열고 BotFather를 검색합니다. @BotFather는 Telegram이 공식적으로 제공하는 봇 관리 도구입니다. 자세한 내용은 Telegram Bot 공식 문서를 참고하세요.
/newbot 명령을 보내면, 봇 이름과 사용자명을 물어봅니다. 이름은 자유롭게, 사용자명은 “bot”으로 끝나야 합니다. 예를 들어 my_ai_assistant_bot 같은 형식입니다.
생성이 완료되면, BotFather가 API 토큰을 줍니다. 이 토큰이 봇의 비밀번호 역할을 합니다. 절대 공개된 곳에 올리지 마세요.
토큰 형태
123456789:ABCdefGhIJKlmNoPQRstuVWxyz이 토큰을 환경 변수로 저장합니다. .env 파일에 넣거나, 직접 환경 변수로 등록합니다.
2. Python 환경 설정
Python 환경을 설정합니다. 먼저 가상환경을 만드는 것부터 시작합니다. 가상환경은 프로젝트마다 독립된 패키지 공간을 제공해서, 다른 프로젝트와 충돌하지 않게 해줍니다. Python 3.8 이상이 필요합니다.
python3 -m venv venv
source venv/bin/activate # Linux/macOS
# Windows: venv\Scripts\activate가상환경을 활성화하면 터미널 프롬프트 앞에 (venv)가 표시됩니다. 이 상태에서 패키지를 설치하면 프로젝트 폴더 안에만 설치됩니다.
필수 패키지 3개
pip install python-telegram-bot openai python-dotenv- python-telegram-bot — Telegram Bot API를 Python에서 쉽게 쓸 수 있게 해주는 라이브러리. 비동기 처리를 기본으로 지원해서, 여러 사용자가 동시에 메시지를 보내도 순차 대기 없이 처리
- openai — LLM 호출용. OpenAI API를 쓸 수도 있고, Anthropic, 로컬 Ollama 등 원하는 LLM으로 교체 가능
- python-dotenv —
.env파일에서 환경 변수를 읽어오는 도구
설치가 끝나면 requirements.txt로 패키지 목록을 저장합니다. 나중에 VPS에 배포할 때 이 파일 하나로 동일한 환경을 재현할 수 있습니다.
pip freeze > requirements.txt환경 변수 관리
# .env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRstuVWxyz
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxx.env 파일은 .gitignore에 반드시 추가하세요. API 토큰을 코드에 직접 적으면 GitHub에 올렸을 때 토큰이 노출됩니다.
3. 기본 봇 코드 — 메시지 수신부터 답장까지
가장 기본적인 구조는, 사용자가 메시지를 보내면 봇이 LLM에게 물어보고 답변을 반환하는 것입니다. 전체 코드는 약 40줄입니다.
import os
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters
from openai import OpenAI
TELEGRAM_TOKEN = os.environ["TELEGRAM_BOT_TOKEN"]
OPENAI_API_KEY = os.environ["OPENAI_API_KEY"]
client = OpenAI(api_key=OPENAI_API_KEY)
# 사용자별 대화 기록 저장
chat_history = {}
async def handle_message(update, context):
user_id = update.effective_user.id
user_message = update.message.text
# 대화 기록 가져오기 (없으면 초기화)
messages = chat_history.get(user_id, [
{"role": "system", "content": "You are a helpful AI assistant. Reply in Korean."}
])
# 사용자 메시지 추가
messages.append({"role": "user", "content": user_message})
# LLM 호출
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=messages,
max_tokens=1000
)
ai_reply = response.choices[0].message.content
# 대화 기록 업데이트
messages.append({"role": "assistant", "content": ai_reply})
chat_history[user_id] = messages[-20:] # 최근 20턴만 유지
# Telegram에 답장
await update.message.reply_text(ai_reply)
async def start(update, context):
await update.message.reply_text("안녕하세요! 무엇을 도와드릴까요?")
# 봇 실행
app = Application.builder().token(TELEGRAM_TOKEN).build()
app.add_handler(CommandHandler("start", start))
app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))
app.run_polling()핵심 로직 5단계 설명
1단계: handle_message 함수
사용자가 일반 텍스트 메시지를 보낼 때마다 이 함수가 자동으로 호출됩니다. Telegram 라이브러리가 이벤트 루프를 돌면서 새 메시지를 감지하면, update 객체에 메시지 정보를 담아서 넘겨줍니다. update.effective_user.id로 사용자를 식별하고, update.message.text로 메시지 내용을 가져옵니다.
2단계: chat_history 딕셔너리
키는 사용자 ID, 값은 메시지 리스트입니다. 각 사용자마다 독립된 대화 기록을 유지합니다. 사용자 A가 묻는 질문이 사용자 B의 문맥에 섞이지 않습니다. 대화 기록이 없는 첫 메시지에서는 system prompt로 초기화합니다.
system prompt는 봇의 성격과 역할을 정의하는 곳입니다. “You are a helpful AI assistant. Reply in Korean.”이라고 했는데, 이걸 바꾸면 봇의 톤과 전문 분야를 조정할 수 있습니다. 예: “너는 IT 기술 전문 비서야. 전문 용어는 영어로 유지하고, 초보자에게 쉽게 설명해”
3단계: LLM 호출
chat.completions.create에 model과 messages를 넘겨서 답변을 받습니다. gpt-4o-mini는 비용 효율적인 모델입니다. 정확도가 더 필요하면 gpt-4o로 올리고, 비용을 더 아끼려면 더 가벼운 모델로 내리면 됩니다. max_tokens 1000은 답변 길이 상한선입니다. 너무 긴 답변은 Telegram에서 읽기 불편하므로 적절한 제한입니다.
4단계: 대화 기록 관리
messages 리스트의 마지막 20개만 유지합니다. 이게 20턴, 즉 사용자 10문 AI 10답입니다. 이 제한은 토큰 사용량과 비용을 제어하기 위해서입니다. 대화가 길어지면 과거 메시지를 버립니다. 이 숫자를 늘리면 더 긴 문맥을 기억하지만 비용이 올라가고, 줄이면 비용은 절약되지만 이전 대화를 잊어버립니다.
5단계: async/await 비동기 처리
Telegram 라이브러리는 비동기로 동작합니다. handle_message 앞에 async가 붙어 있고, reply_text 앞에 await가 붙어 있습니다. 이건 한 사용자의 답변을 기다리는 동안 다른 사용자의 메시지도 처리할 수 있다는 뜻입니다. LLM 응답이 3초 걸려도 그 사이 다른 사람의 메시지가 큐에 쌓여서 순차적으로 처리됩니다.
4. 실행과 테스트
환경 변수를 설정하고 main.py를 실행합니다:
export TELEGRAM_BOT_TOKEN="your_token"
export OPENAI_API_KEY="your_key"
python main.py콘솔에 “Started polling”이 나오면, Telegram에서 봇을 찾아서 메시지를 보냅니다.
테스트 시나리오
- 첫 번째 질문: “파이썬에서 리스트와 튜플의 차이가 뭐야?” — 2~3초 안에 AI가 한국어로 답변합니다.
- 두 번째 질문: “그러면 언제 튜플을 쓰는 게 좋아?” — 대화 기록이 작동합니다. 봇이 이전 질문의 문맥을 기억하고, 리스트와 튜플 비교를 이어서 설명합니다.
- 에러 테스트:
OPENAI_API_KEY를 잘못된 값으로 바꾸면AuthenticationError가 발생합니다.try-except로 감싸서 사용자에게 “일시적 오류” 메시지를 보내게 처리할 수 있습니다.
네트워크 오류도 테스트해 봅니다. Wi-Fi를 끄고 메시지를 보내면, 봇이 응답하지 않습니다. 하지만 polling 루프는 계속 돌고 있어서, Wi-Fi를 다시 켜면 다음 polling 주기에 메시지가 처리됩니다.
5. 기능 확장 — /summary, /translate 명령어
기본 봇이 작동하면 기능을 추가해 봅시다. 두 가지를 넣겠습니다.
/summary — 긴 텍스트 3문장 요약
async def summarize(update, context):
"""긴 텍스트를 3문장으로 요약"""
text = " ".join(context.args)
if not text:
await update.message.reply_text("/summary 뒤에 요약할 텍스트를 붙여주세요.")
return
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Summarize the following text in 3 sentences in Korean."},
{"role": "user", "content": text}
]
)
await update.message.reply_text(response.choices[0].message.content)뉴스 기사 전문을 붙여넣었을 때 핵심 내용이 3문장으로 압축됩니다. 회의록이나 긴 이메일도 같은 방식으로 요약할 수 있습니다. system prompt를 “3문장으로 요약해”에서 “핵심 포인트 5개를 불릿으로 정리해”로 바꾸면 요약 형식도 자유롭게 조정할 수 있습니다.
/translate — 영한 번역
async def translate(update, context):
"""영한 번역"""
text = " ".join(context.args)
if not text:
await update.message.reply_text("/translate 뒤에 번역할 텍스트를 붙여주세요.")
return
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[
{"role": "system", "content": "Translate the following English text to Korean naturally."},
{"role": "user", "content": text}
]
)
await update.message.reply_text(response.choices[0].message.content)영문 기사나 기술 문서를 통째로 붙여넣으면 자연스러운 한국어로 번역됩니다. 구글 번역기와 다른 점은 문맥을 이해한다는 것입니다. 기술 용어는 기술 용어로, 일상 표현은 일상 표현으로 번역합니다.
확장 가능성
- 이미지 분석: Telegram에서 사진을 보내면 봇이 설명. OpenAI vision 모델(gpt-4o-mini) 사용
- 날씨 API:
/weather 서울명령어로 실시간 날씨 - RAG 연동: 내 문서 기반으로 답변하는 봇. PDF 업로드 → 문서 내용에서 답변
새 기능을 추가하는 방법이 명확합니다: CommandHandler를 등록하고, 함수에서 LLM을 호출하고, 결과를 reply_text로 보냅니다. 이 패턴으로 원하는 기능을 계속 붙일 수 있습니다.
6. VPS 배포 — 24시간 운영
로컬에서 돌리면 컴퓨터를 끌 때 봇도 죽습니다. 메신저 봇은 24시간 응답해야 하니까, VPS에 올려서 상시 운영해야 합니다.
VPS 선택
이 봇은 CPU 부하가 거의 없습니다. LLM 연산은 OpenAI 서버에서 처리하고, 봇은 메시지를 주고받기만 합니다. 따라서 가장 저렴한 VPS로 충분합니다. 월 5달러짜리 1코어 1GB RAM이면 넉넉합니다. Vultr, DigitalOcean, AWS Lightsail 중에서 고르면 됩니다. 리전은 사용자와 가까운 곳을 선택하세요. 한국 사용자라면 도쿄나 서울 리전이 응답 속도에 유리합니다.
systemd 서비스 등록
VPS에 접속해서 Python 환경을 구성하고, systemd 서비스로 등록합니다. Restart=always를 쓰면 봇이 크래시해도 자동으로 재시작됩니다.
# /etc/systemd/system/tg-bot.service
[Unit]
Description=Telegram AI Bot
After=network.target
[Service]
ExecStart=/usr/bin/python3 /opt/tg-bot/main.py
Environment=TELEGRAM_BOT_TOKEN=your_token
Environment=OPENAI_API_KEY=your_key
Restart=always
RestartSec=3
User=ubuntu
WorkingDirectory=/opt/tg-bot
[Install]
WantedBy=multi-user.targetsudo systemctl enable --now tg-bot이제 봇이 24시간 온라인입니다. 어디서든 Telegram으로 메시지를 보내면 답장이 옵니다.
비용 관리
gpt-4o-mini는 1메시지당 약 1~2원 수준으로 저렴하지만, 사용자가 많아지면 토큰 비용이 누적됩니다. 1인용 봇이면 하루 수십 원 수준이지만, 공개 봇으로 만들면 rate limit을 걸어야 합니다. 사용자별로 하루 요청 수를 제한하는 로직을 추가하세요.
보안 체크리스트
- API 토큰은 systemd의
Environment로 넣거나.env파일로 관리. 코드에 하드코딩 금지 - 방화벽은 SSH 포트만 열어둠. 봇은 polling 방식이라 외부 포트 불필요
- SSH 비밀번호 대신 키 인증 사용
journalctl -u tg-bot로 로그 모니터링
요약: AI 비서 봇 구축의 전체 과정
Telegram Bot API와 LLM을 연결해서, 메신저 안에서 동작하는 AI 비서를 만들었습니다. 전체 과정을 요약하면:
- BotFather로 봇 생성, 토큰 발급
- Python 환경 설정: python-telegram-bot, openai, python-dotenv
- 기본 봇 코드 약 40줄: 메시지 수신 → LLM 호출 → 답장
- 기능 확장: /summary, /translate 명령어 추가
- VPS 배포: systemd로 24시간 운영
이 봇은 여러분만의 비서입니다. RAG를 붙이면 내 문서 기반 질의응답 봇이 되고, 웹 검색을 붙이면 실시간 정보 비서가 됩니다. 기능은 여러분이 원하는 대로 확장할 수 있습니다.
수정하고 싶은 부분이 있으면, system prompt부터 바꿔보세요. 거기서 봇의 성격이 결정됩니다.
더 읽어보기
- Telegram Bot API 공식 문서 — 모든 봇 기능의 레퍼런스
- python-telegram-bot 라이브러리 문서 — Python으로 Telegram 봇 만들기 가이드
- OpenAI API 모델 가이드 — gpt-4o-mini 및 다른 모델 비교
이 채널에서 매주 AI 실전 프로젝트를 다룹니다. 구독과 알림 설정 부탁드립니다. 여러분의 다음 AI 프로젝트가 더 수월해지길 바랍니다.
