Telegram Bot API 입문 가이드 (2026)

2026년 Telegram Bot API 초보자 가이드

Telegram 봇은 Telegram Bot API를 통해 작업 자동화, 알림 전송, 결제 처리, 퀴즈 실행, 심지어 완전한 AI 비서 역할까지 수행할 수 있습니다. 월간 활성 사용자 수가 9억 명을 넘어서는 Telegram은 사람들이 실제로 사용하는 봇을 구축하기에 가장 좋은 플랫폼 중 하나입니다.

이 가이드는 봇 토큰 획득부터 명령 처리, 미디어 전송, 그리고 프로덕션 배포에 이르기까지 Telegram 봇을 처음부터 만드는 과정을 안내합니다.

Telegram 봇으로 무엇을 할 수 있나요?

코드를 작성하기 전에, Bot API가 지원하는 기능은 다음과 같습니다.

기능	설명
텍스트 메시지	일반 텍스트 및 서식이 지정된 메시지 송수신
명령(Commands)	/start, /help 및 커스텀 명령 처리
인라인 키보드	메시지 내의 대화형 버튼
미디어	사진, 비디오, 오디오, 문서 및 스티커 전송
결제	Telegram 내장 결제 시스템을 통한 결제 수락
웹훅(Webhooks)	HTTP 콜백을 통해 실시간 업데이트 수신
그룹 관리	그룹 중재, 메시지 고정, 사용자 차단
인라인 모드	사용자가 어느 채팅창에서나 @yourbot query로 봇 호출 가능
미니 앱(Mini Apps)	Telegram 내부에서 실행되는 전체 웹 애플리케이션

1단계: BotFather로 봇 만들기

모든 Telegram 봇은 봇 관리를 위한 공식 봇인 BotFather에서 시작됩니다.

1. Telegram을 열고 @BotFather를 검색합니다.
2. /newbot 명령어를 보냅니다.
3. 표시 이름(예: "My First Bot")을 선택합니다.
4. bot으로 끝나는 사용자 이름(예: my_first_demo_bot)을 선택합니다.
5. BotFather가 HTTP API 토큰을 회신합니다. 형식은 다음과 같습니다.

7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw

이 토큰을 안전하게 보관하세요. 이 토큰을 가진 사람은 누구나 당신의 봇을 제어할 수 있습니다.

2단계: 첫 번째 메시지 보내기

일반 HTTP 요청을 사용하여 Bot API와 상호작용할 수 있습니다. cURL로 테스트해 보겠습니다.

# YOUR_BOT_TOKEN을 BotFather에게 받은 토큰으로 교체하세요
# CHAT_ID를 귀하의 Telegram 사용자 ID로 교체하세요

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/sendMessage" \
  -d "chat_id=CHAT_ID" \
  -d "text=Hello from my first bot!"

귀하의 chat ID를 찾으려면 봇에게 아무 메시지나 보낸 후 다음을 호출하세요.

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates"

응답에서 chat.id 필드를 확인하세요.

3단계: Python으로 봇 구축하기

python-telegram-bot 라이브러리는 Telegram Bot API를 위한 가장 인기 있는 Python 래퍼입니다.

라이브러리 설치

pip install python-telegram-bot

명령 핸들러가 포함된 기본 봇

from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters, ContextTypes

# 명령 핸들러
async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_text(
        "Welcome! I'm your bot. Use /help to see what I can do."
    )

async def help_command(update: Update, context: ContextTypes.DEFAULT_TYPE):
    help_text = """
사용 가능한 명령:
/start - 봇 시작
/help - 이 도움말 도움말 표시
/echo <text> - 메시지 메아리 전달
/weather <city> - 날씨 정보 가져오기
    """
    await update.message.reply_text(help_text)

async def echo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    user_text = " ".join(context.args) if context.args else "아무것도 말씀하지 않으셨어요!"
    await update.message.reply_text(user_text)

# 일반 텍스트 메시지 처리
async def handle_message(update: Update, context: ContextTypes.DEFAULT_TYPE):
    text = update.message.text
    await update.message.reply_text(f"입력하신 내용: {text}")

def main():
    app = Application.builder().token("YOUR_BOT_TOKEN").build()

    # 핸들러 등록
    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("help", help_command))
    app.add_handler(CommandHandler("echo", echo))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, handle_message))

    # 업데이트 폴링 시작
    print("Bot is running...")
    app.run_polling()

if __name__ == "__main__":
    main()

봇 실행하기:

python bot.py

Telegram에서 봇을 찾아 /start를 보내세요. 즉시 응답할 것입니다.

4단계: 인라인 키보드 추가하기

인라인 키보드를 사용하면 메시지에 대화형 버튼을 추가할 수 있습니다.

from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update
from telegram.ext import CallbackQueryHandler, ContextTypes

async def menu(update: Update, context: ContextTypes.DEFAULT_TYPE):
    keyboard = [
        [
            InlineKeyboardButton("옵션 1", callback_data="option_1"),
            InlineKeyboardButton("옵션 2", callback_data="option_2"),
        ],
        [
            InlineKeyboardButton("웹사이트 방문", url="https://example.com"),
        ],
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text("옵션을 선택하세요:", reply_markup=reply_markup)

async def button_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
    query = update.callback_query
    await query.answer()  # 버튼 클릭 확인

    if query.data == "option_1":
        await query.edit_message_text("옵션 1을 선택하셨습니다!")
    elif query.data == "option_2":
        await query.edit_message_text("옵션 2를 선택하셨습니다!")

# 핸들러 등록
app.add_handler(CommandHandler("menu", menu))
app.add_handler(CallbackQueryHandler(button_callback))

5단계: 미디어 파일 전송

봇은 사진, 비디오, 문서 등을 보낼 수 있습니다.

async def send_photo(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # URL로 전송
    await update.message.reply_photo(
        photo="https://example.com/image.jpg",
        caption="웹에서 가져온 사진입니다!"
    )

async def send_document(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # 로컬 파일 전송
    with open("report.pdf", "rb") as doc:
        await update.message.reply_document(
            document=doc,
            caption="여기 보고서가 있습니다."
        )

async def send_video(update: Update, context: ContextTypes.DEFAULT_TYPE):
    await update.message.reply_video(
        video="https://example.com/video.mp4",
        caption="이 영상을 확인해 보세요!"
    )

6단계: Node.js로 봇 구축하기

JavaScript를 선호한다면 telegraf 라이브러리가 가장 보편적인 선택입니다.

npm install telegraf

const { Telegraf, Markup } = require("telegraf");

const bot = new Telegraf("YOUR_BOT_TOKEN");

// 명령 핸들러
bot.start((ctx) => {
  ctx.reply("환영합니다! /help를 사용하여 사용 가능한 명령을 확인하세요.");
});

bot.help((ctx) => {
  ctx.reply(`사용 가능한 명령:
/start - 봇 시작
/help - 도움말 표시
/menu - 옵션 메뉴 표시`);
});

// 인라인 키보드 예시
bot.command("menu", (ctx) => {
  ctx.reply(
    "옵션을 선택하세요:",
    Markup.inlineKeyboard([
      [Markup.button.callback("옵션 A", "action_a")],
      [Markup.button.callback("옵션 B", "action_b")],
      [Markup.button.url("사이트 방문", "https://example.com")],
    ])
  );
});

// 버튼 콜백 처리
bot.action("action_a", (ctx) => {
  ctx.answerCbQuery();
  ctx.editMessageText("옵션 A를 선택하셨습니다!");
});

bot.action("action_b", (ctx) => {
  ctx.answerCbQuery();
  ctx.editMessageText("옵션 B를 선택하셨습니다!");
});

// 텍스트 메시지 처리
bot.on("text", (ctx) => {
  ctx.reply(`입력하신 내용: ${ctx.message.text}`);
});

bot.launch();
console.log("Bot is running...");

// 정상 종료 처리
process.once("SIGINT", () => bot.stop("SIGINT"));
process.once("SIGTERM", () => bot.stop("SIGTERM"));

7단계: 프로덕션용 웹훅(Webhooks) 설정

개발 중에는 폴링(Polling)이 유용하지만, 프로덕션 봇은 더 나은 성능을 위해 웹훅을 사용해야 합니다.

# 웹훅과 함께 python-telegram-bot 사용
from telegram.ext import Application

app = Application.builder().token("YOUR_BOT_TOKEN").build()

# 핸들러 등록 생략...

# 웹훅 시작
app.run_webhook(
    listen="0.0.0.0",
    port=8443,
    url_path="YOUR_BOT_TOKEN",
    webhook_url=f"https://your-domain.com/{YOUR_BOT_TOKEN}"
)

또는 수동으로 웹훅을 설정할 수 있습니다.

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/setWebhook" \
  -d "url=https://your-domain.com/webhook/YOUR_BOT_TOKEN"

배포 옵션

플랫폼	비용	설정 난이도	적합한 용도
Railway	프리티어 제공	쉬움	빠른 배포
Render	프리티어 제공	쉬움	간단한 봇
AWS Lambda	프리티어 제공	중간	이벤트 기반 봇
Google Cloud Run	프리티어 제공	중간	확장 가능한 봇
VPS (Hetzner, DigitalOcean)	월 $4-5	중간	전체 제어 권한
Fly.io	프리티어 제공	쉬움	글로벌 배포

Railway에 배포하기

# Railway CLI 설치
npm install -g @railway/cli

# 로그인 및 배포
railway login
railway init
railway up

Railway 대시보드에서 BOT_TOKEN을 환경 변수로 추가하세요.

Bot API 호출 제한 (Rate Limits)

봇을 구축할 때 다음 제한 사항을 염두에 두세요.

제한 항목	값
사용자별 메시지 전송	초당 30개
그룹별 메시지 전송	분당 20개
대량 메시지 전송	모든 채팅 합산 초당 30개
파일 업로드	최대 50 MB
파일 다운로드	최대 20 MB
인라인 쿼리 결과	최대 50개

자주 묻는 질문 (FAQ)

Telegram Bot API의 비용은 얼마인가요? Telegram Bot API는 완전히 무료입니다. 사용료, 속도 기반 과금, 프리미엄 티어 등이 없습니다.

봇이 메시지 기록에 접근할 수 있나요? 봇은 그룹에 추가된 이후에 발생한 메시지만 볼 수 있으며, 적절한 권한이 있는 경우에만 가능합니다. 과거 메시지 기록은 읽을 수 없습니다.

그룹에서 봇이 작동하게 하려면 어떻게 하나요? 봇을 그룹에 추가하고 필요한 권한이 있는지 확인하세요. 메시지에 응답하려면 MessageHandler를 사용하거나 봇이 명령에만 응답하도록 설정하세요.

봇을 통해 결제를 받을 수 있나요? 네, Telegram은 Stripe 및 기타 업체를 통한 기본 결제를 지원합니다. sendInvoice 메서드를 사용하여 결제 요청을 생성하세요.

봇 토큰을 어떻게 안전하게 보관하나요? 소스 코드에 토큰을 하드코딩하지 마세요. 환경 변수나 비밀 관리 도구(secrets manager)를 사용하세요. 토큰이 유출된 경우 BotFather를 통해 /revoke 명령으로 즉시 재발급받으세요.

마치며

Telegram Bot API는 개발자에게 가장 친숙한 봇 플랫폼 중 하나입니다. 무제한 무료 사용, 우수한 문서, 단순한 명령형 봇부터 전체 미니 앱에 이르는 폭넓은 지원을 통해 자동화 도구 및 서비스를 구축하기 위한 이상적인 환경을 제공합니다.

이미지, 비디오 또는 말하는 아바타와 같은 AI 미디어를 생성하는 Telegram 봇을 구축 중이라면, Hypereal AI를 무료로 체험해 보세요. 카드 등록 없이 35크레딧을 제공합니다. 이 API는 주문형 AI 콘텐츠 생성을 위해 모든 Telegram 봇과 쉽게 통합됩니다.