텔레그램 봇 만들기: @BotFather로 생성하고 첫 메시지 보내기

최종 업데이트: 2026년 10월 29일 · 8 분 분량

텔레그램 봇 만들기는 텔레그램 앱에서 @BotFather에게 /newbot 명령을 보내는 것으로 시작합니다. 봇의 이름과 username을 정하면 봇 계정이 즉시 생성되고, Bot API를 호출할 때 쓰는 토큰이 발급됩니다. 이 가이드에서는 봇 생성, 토큰 확인(getMe), chat id 찾기(getUpdates), 첫 메시지 전송(sendMessage)까지 10분 안에 끝낼 수 있도록 단계별로 설명합니다.

시작하기 전에 준비할 것

• 텔레그램 계정: 스마트폰 앱이든 데스크톱 앱이든 상관없습니다. 이 계정이 봇의 소유자가 됩니다.
• 터미널 또는 Python 3: 예제는 curl과 Python requests 라이브러리(pip install requests)를 사용합니다. 브라우저만 있다면 Bot API Tester로 같은 요청을 보낼 수 있습니다.
• 서버는 아직 필요 없습니다: getUpdates 방식은 내 PC가 텔레그램 서버에 요청을 보내는 구조라서 공인 IP나 도메인 없이도 동작합니다. 서버와 HTTPS 주소는 나중에 웹훅으로 전환할 때 필요합니다.

봇 계정 자체는 코딩 없이 만들 수 있지만, 봇이 메시지에 답하게 하려면 Bot API를 호출하는 프로그램이 반드시 있어야 합니다. 이 글의 예제는 그 프로그램의 가장 작은 형태라고 보면 됩니다.

1단계: @BotFather에서 /newbot으로 텔레그램 봇 만들기

1. 텔레그램에서 @BotFather를 엽니다. 이름이 비슷한 사칭 계정이 있으므로 검색보다 이 링크로 여는 편이 안전합니다.
2. 시작(Start)을 누른 뒤 /newbot을 보냅니다.
3. 봇의 이름(name)을 입력합니다. 대화 목록과 프로필에 보이는 표시 이름으로 한글도 쓸 수 있고, 나중에 /setname으로 바꿀 수 있습니다. 예: 날씨 알림 봇
4. 봇의 username을 입력합니다. 5~32자의 라틴 문자, 숫자, 밑줄(_)만 쓸 수 있고 반드시 bot으로 끝나야 합니다(예: tetris_bot, TetrisBot). 대소문자는 구분하지 않으며, 이미 사용 중인 username이면 다른 이름을 요구합니다.
5. 생성에 성공하면 BotFather가 봇 링크 t.me/<username>과 함께 HTTP API에 접근할 때 쓰는 토큰을 보내 줍니다.

username은 검색, 멘션, t.me 링크에 쓰이며 이름과 달리 나중에 변경할 수 없습니다. 서비스 이름과 맞춰 신중하게 정하십시오. 채팅 명령 대신 같은 기능을 제공하는 BotFather의 Mini App 화면을 써도 결과는 같습니다.

2단계: 봇 토큰 복사하고 안전하게 보관하기

토큰은 123456789:AAEexampleTokenReplaceWithYours처럼 숫자, 콜론(:), 영문·숫자 문자열로 이루어집니다. 콜론 앞 숫자는 봇 자신의 ID이고 뒤쪽이 비밀 값입니다. 토큰을 아는 사람은 누구나 봇을 완전히 제어할 수 있으므로 비밀번호처럼 다뤄야 합니다.

• 코드에 직접 쓰지 말고 환경 변수나 .env 파일에 두며, .env는 .gitignore에 추가합니다.
• GitHub 공개 저장소, 웹 프런트엔드 코드, 스크린샷, 공개 채팅방에 토큰을 올리지 않습니다.
• 토큰을 어디에 두었는지 잊었다면 @BotFather에서 /mybots → 봇 선택 → API Token으로 현재 토큰을 다시 볼 수 있습니다. 유출됐다면 /revoke로 즉시 폐기합니다.

# macOS·Linux 터미널에서 현재 세션에만 등록
export TELEGRAM_BOT_TOKEN="123456789:AAEexampleTokenReplaceWithYours"

토큰 형식, 기존 토큰 찾기, 재발급 절차는 텔레그램 봇 토큰 가이드에서 자세히 다룹니다.

3단계: getMe로 토큰이 동작하는지 확인하기

모든 Bot API 요청은 https://api.telegram.org/bot<token>/메서드이름 형식입니다. 토큰 바로 앞에 bot이라는 글자가 붙는다는 점에 주의하십시오. 가장 먼저 호출할 메서드는 봇 자신의 정보를 돌려주는 getMe입니다.

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"

토큰이 올바르면 봇의 User 객체가 반환됩니다. 아래는 주요 필드만 추린 예시입니다.

{
  "ok": true,
  "result": {
    "is_bot": true,
    "first_name": "날씨 알림 봇",
    "username": "weather_alert_bot",
    "can_join_groups": true,
    "can_read_all_group_messages": false,
    "supports_inline_queries": false
  }
}

can_read_all_group_messages가 false라면 그룹 프라이버시 모드가 켜져 있다는 뜻입니다(기본값). 반대로 {"ok":false,"error_code":401,"description":"Unauthorized"}가 나오면 토큰이 틀렸거나 폐기된 것이니, 복사할 때 앞뒤 공백이나 줄바꿈이 섞이지 않았는지 확인하십시오. 터미널 없이 확인하려면 Bot API Tester의 getMe에 토큰을 붙여 넣고 실행하면 됩니다.

4단계: /start를 보내고 첫 메시지 전송하기

봇은 사용자에게 먼저 말을 걸 수 없습니다. 사용자가 대화를 시작해야 봇이 그 채팅으로 메시지를 보낼 수 있으므로, 먼저 내 계정으로 봇에게 말을 걸어 chat id를 알아냅니다.

1. t.me/<username> 링크로 봇을 열고 시작을 누릅니다. 봇에게 /start 메시지가 전달됩니다.
2. getUpdates를 호출해 봇이 받은 업데이트를 확인합니다.
3. 응답에서 message.chat.id 값을 찾습니다. 이것이 나와 봇 사이 개인 채팅의 chat id입니다.

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getUpdates"

{
  "ok": true,
  "result": [
    {
      "update_id": 870000001,
      "message": {
        "message_id": 1,
        "from": {"id": 123456789, "is_bot": false, "first_name": "민준", "language_code": "ko"},
        "chat": {"id": 123456789, "first_name": "민준", "type": "private"},
        "date": 1793266200,
        "text": "/start"
      }
    }
  ]
}

chat id를 알았다면 sendMessage로 첫 메시지를 보냅니다. 한글 텍스트를 URL에 직접 넣으면 인코딩 문제가 생기기 쉬우므로 POST와 JSON 본문을 쓰는 편이 간단합니다.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "안녕하세요! 첫 번째 봇 메시지입니다."}'

같은 과정을 Python으로 작성하면 다음과 같습니다. 가장 최근 메시지의 chat id를 읽어 그 채팅에 답장합니다.

import os
import requests

TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN", "123456789:AAEexampleTokenReplaceWithYours")
API = f"https://api.telegram.org/bot{TOKEN}"

updates = requests.get(f"{API}/getUpdates", timeout=10).json()
if not updates["ok"]:
    raise SystemExit(f'{updates["error_code"]}: {updates["description"]}')

messages = [u["message"] for u in updates["result"] if "message" in u]
if not messages:
    raise SystemExit("메시지가 없습니다. 봇에게 /start를 먼저 보내십시오.")

chat_id = messages[-1]["chat"]["id"]
resp = requests.post(f"{API}/sendMessage",
                     json={"chat_id": chat_id, "text": "Python에서 보낸 첫 메시지입니다."},
                     timeout=10).json()
if not resp["ok"]:
    raise SystemExit(f'{resp["error_code"]}: {resp["description"]}')
print("전송 완료, message_id =", resp["result"]["message_id"])

휴대폰에 봇의 메시지가 도착했다면 텔레그램 봇 만들기의 핵심 과정은 끝났습니다. 그룹이나 채널의 chat id를 찾는 방법은 텔레그램 chat id 확인방법에, 서식과 버튼을 넣는 방법은 텔레그램 봇 API 메시지 보내기에 정리했습니다.

5단계(선택): 소개 문구와 명령어 메뉴 설정

사용자가 봇을 처음 열었을 때 무엇을 하는 봇인지 바로 알 수 있도록 프로필을 채워 둡니다. 모두 @BotFather에서 설정합니다.

/setcommands에서는 한 줄에 하나씩 명령어 - 설명 형식으로 입력합니다. 같은 작업을 코드로 하려면 setMyCommands를 호출합니다. 명령어는 1~32자의 영문 소문자, 숫자, 밑줄만 쓸 수 있고 설명은 1~256자이며, 한 번에 최대 100개까지 등록할 수 있습니다. language_code를 ko로 지정하면 앱 언어가 한국어인 사용자에게만 보이는 목록을 따로 둘 수 있습니다.

curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{
    "commands": [
      {"command": "start", "description": "봇 시작하기"},
      {"command": "help", "description": "사용 방법 보기"},
      {"command": "settings", "description": "알림 설정"}
    ],
    "language_code": "ko"
  }'

language_code 없이 한 번 더 호출해 기본 목록도 등록해 두면 다른 언어 사용자에게도 메뉴가 보입니다. 텔레그램은 모든 봇이 /start와 /help를, 설정 기능이 있다면 /settings도 지원하도록 권장합니다.

텔레그램 AI 봇 만들기: 무엇이 달라지나

대화형 AI 모델을 연결한 텔레그램 AI 봇도 만드는 순서는 같습니다. @BotFather로 봇을 만들고 토큰을 받은 다음, 서버 코드가 다음 작업을 반복합니다.

1. getUpdates 또는 웹훅으로 사용자 메시지를 받습니다.
2. 메시지 텍스트를 사용하는 AI 모델의 API에 전달합니다.
3. 생성된 답변을 sendMessage로 같은 chat id에 보냅니다.

답변 생성에 몇 초 이상 걸린다면 개인 채팅에서 sendMessageDraft로 작성 중인 답변을 스트리밍할 수 있습니다. 같은 draft_id로 텍스트를 계속 갱신하면 변경이 애니메이션으로 이어지고, 빈 텍스트를 보내면 "Thinking..." 자리 표시가 나타납니다. 초안은 약 30초 동안만 보이는 임시 미리보기이므로 완성된 답변은 반드시 sendMessage로 다시 보내야 채팅에 남습니다. can_stop을 켜면 사용자가 생성을 멈출 수 있고, 이때 봇은 stopped_message_generation 업데이트를 받습니다.

이미 만들어진 AI 비서나 n8n 같은 자동화 도구를 텔레그램에 연결하는 경우에도 첫 단계는 이 글과 같습니다. 이런 도구는 대부분 봇 토큰과 chat id를 요구하므로 1~4단계에서 얻은 값을 그대로 입력하면 됩니다.

자주 막히는 부분

• getUpdates의 result가 빈 배열: 봇에게 아직 메시지를 보내지 않았거나, 24시간이 지나 업데이트가 삭제됐거나, 이미 다른 프로그램이 업데이트를 가져간 경우입니다. 봇에게 새 메시지를 보낸 뒤 다시 호출하십시오.
• 401 Unauthorized: 토큰 오타 또는 폐기된 토큰입니다. /mybots → 봇 선택 → API Token에서 현재 값을 다시 복사합니다.
• 404 Not Found: URL에서 bot 접두사가 빠졌거나 메서드 이름에 오타가 있습니다.
• 409 Conflict: 같은 토큰으로 다른 프로그램이 getUpdates를 호출하고 있거나 웹훅이 설정돼 있습니다. 업데이트를 받는 프로그램은 토큰당 하나만 두십시오.
• 400 Bad Request: chat not found: chat id가 틀렸거나 사용자가 아직 봇을 시작하지 않았습니다.

다음 단계: 폴링과 웹훅, 라이브러리, Mini App

• 업데이트 받는 방식: 개발 중에는 getUpdates에 timeout을 주는 롱 폴링이 간편합니다. 운영 서버에서는 텔레그램이 HTTPS 주소로 업데이트를 보내 주는 웹훅이 효율적입니다. 두 방식은 동시에 쓸 수 없으며, 설정 방법은 텔레그램 웹훅 설정 가이드를 참고하십시오.
• 라이브러리: HTTP를 직접 호출해도 되지만 업데이트 처리, 재시도, 핸들러 라우팅을 맡길 라이브러리를 쓰면 편합니다. Python은 python-telegram-bot, aiogram, pyTelegramBotAPI, Node.js는 grammY와 Telegraf, Go는 telebot과 go-telegram-bot-api가 많이 쓰입니다.
• Mini App: 버튼과 명령어만으로 부족하다면 텔레그램 안에서 열리는 웹 화면(Mini App)을 붙일 수 있습니다. @BotFather의 /newapp으로 직접 링크를 만들거나 메뉴 버튼에 연결하며, Mini App Tester로 Telegram.WebApp API를 미리 시험해 볼 수 있습니다.
• 전체 메서드: Bot API 10.3의 185개 메서드는 메서드 레퍼런스(영어·러시아어)와 Swagger 문서에서 확인할 수 있습니다.