BotFather 토큰 발급과 환경변수 설정
업데이트: 2026-10-02
텔레그램 봇을 생성하고 프로그래밍 언어에서 제어하려면, 텔레그램 공식 관리 봇인 @BotFather로부터 고유한 HTTP API 인증 토큰을 발급받아야 합니다.
봇 생성부터 프로필 설정, 명령어 메뉴 등록, 그리고 DashCloud에 안전하게 암호화 환경변수로 주입하기까지의 전 과정을 상세히 다룹니다.
단계별 봇 생성 및 토큰 발급 5단계
텔레그램에서 @BotFather 검색 및 대화 시작
텔레그램 모바일 앱 또는 데스크톱 앱의 검색창에 @BotFather를 검색합니다.
반드시 사용자 이름 옆에 **텔레그램 공식 인증 배지(파란색 체크마크)**가 붙어 있는 @BotFather를 선택해야 합니다. 공식 인증이 없는 유사 사칭 계정에 토큰을 노출하지 않도록 주의하세요.
대화방에 입장한 후 하단의 시작 버튼을 누르면 사용 가능한 명령어 목록이 안내됩니다.
/newbot 명령어로 새 봇 생성
채팅창에 /newbot을 입력하고 전송합니다.
-
봇의 표시 이름 지정: 사용자 화면에 표시될 친근한 이름을 입력합니다. 한글이나 이모지를 포함할 수 있습니다.
> /newbot Alright, a new bot. How are we going to call it? Please choose a name for your bot. > 내 비서 알림봇 🤖 -
봇의 고유 사용자명 Username 지정: 전 세계에서 유일해야 하며, 반드시
bot으로 끝나야 합니다 (대소문자 무관, 언더스코어_허용).Good. Now let's choose a username for your bot. It must end in `bot`. Like this, for example: TetrisBot or tetris_bot. > my_personal_secretary_bot
API 토큰 확인 및 복사
사용자 이름이 중복되지 않고 정상 생성되면 BotFather가 축하 메시지와 함께 다음과 같은 형식의 HTTP API Token을 발급해 줍니다.
Use this token to access the HTTP API:
7123456789:AAF_kX8y-1234567890abcdefghijklmnopqrst
Keep your token secure and store it safely, it can be used by anyone to control your bot.- 앞부분의 숫자(
7123456789)는 봇의 고유 식별 번호입니다. - 콜론 뒤의 문자열(
AAF_kX8y-...)은 봇을 원격 조작할 수 있는 비밀 암호키입니다. - 이 토큰을 복사하여 안전한 곳에 보관합니다.
봇 프로필 및 명령어 메뉴 등록 (선택)
사용자가 봇을 편리하게 사용할 수 있도록 프로필 설명과 채팅창 좌측 하단의 명령어 자동완성 메뉴를 등록합니다.
-
명령어 메뉴 등록 (
/setcommands): BotFather에게/setcommands를 입력하고 내 봇을 선택한 뒤 아래 형식으로 입력합니다:start - 봇 시작 및 기본 안내 status - 서버 및 봇 가동 상태 확인 help - 사용 가능한 도움말 보기 alert - 알림 수신 설정 변경등록을 완료하면 사용자가 텔레그램 채팅창 좌측 하단의
Menu버튼을 눌렀을 때 해당 명령어들이 깔끔하게 노출됩니다. -
소개 문구 등록 (
/setdescription): 사용자가 봇 대화방에 처음 들어왔을 때 화면 중앙에 표시될 소개 글을 작성합니다. -
프로필 사진 등록 (
/setuserpic): 봇의 아바타 이미지를 전송하여 프로필 사진으로 지정합니다.
내 텔레그램 Chat ID 확인하기
봇이 특정 관리자(나 자신)에게만 시스템 장애 알림이나 개인 메시지를 보내게 하려면 내 텔레그램 계정의 고유 숫자 ID(Chat ID)를 알아야 합니다.
- 텔레그램 검색창에
@userinfobot을 검색하고 대화를 시작합니다. - 봇이 즉시 내 프로필 정보와 함께
Id: 123456789형태의 숫자를 알려줍니다. - 이 숫자를 복사해 둡니다 (환경변수
TELEGRAM_ADMIN_CHAT_ID로 활용).
DashCloud에 토큰 안전하게 주입하기
발급받은 토큰을 절대 파이썬 코드(main.py)나 깃허브 공개 저장소에 직접 붙여넣지 마세요. 깃허브 봇 탐지기에 의해 토큰이 1분 만에 유출되어 계정이 해킹당할 수 있습니다.
DashCloud의 암호화 환경변수 기능을 사용해 안전하게 주입합니다.
- DashCloud 대시보드에서 내 프로젝트 상세 페이지로 이동합니다.
- 상단 탭 중 환경변수 메뉴를 선택합니다.
- 아래 표와 같이 키-값 쌍을 입력하고 저장을 클릭합니다:
| 변수 이름 | 입력 값 (Value 예시) | 용도 설명 |
|---|---|---|
TELEGRAM_BOT_TOKEN | 7123456789:AAF_kX8y-... | 텔레그램 Bot API 통신용 마스터 인증 토큰 |
TELEGRAM_ADMIN_CHAT_ID | 123456789 | 에러 알림 및 비상 리포트를 수신할 관리자 고유 ID |
TZ | Asia/Seoul | 봇 내부 시간대를 한국 표준시 KST로 동기화 |
대시보드에 등록된 환경 변수는 데이터베이스에 평문으로 남지 않고 AES-256-GCM 방식으로 즉시 암호화됩니다. 프로젝트 샌드박스가 가동되는 찰나에만 프로세스 메모리에 직접 주입되므로 외부 유출이 원천 차단됩니다.
코드에서 환경변수 로드하기 (파이썬 예시)
import os
import sys
import logging
from telegram.ext import Application
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# 환경변수 안전 로드
BOT_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")
ADMIN_ID = os.environ.get("TELEGRAM_ADMIN_CHAT_ID")
if not BOT_TOKEN:
logger.critical("❌ 환경변수 TELEGRAM_BOT_TOKEN이 등록되지 않았습니다! 대시보드를 확인하세요.")
sys.exit(1)
logger.info("토큰 로드 성공. 봇 애플리케이션을 기동합니다.")
app = Application.builder().token(BOT_TOKEN).build()토큰 유출 사고 시 1분 비상 대응 매뉴얼
만약 실수로 봇 토큰을 깃허브 공개 저장소나 디스코드 채팅창에 노출했다면, 악의적인 공격자가 봇의 모든 대화방에 스팸을 뿌리거나 채널 권한을 탈취할 수 있습니다. 즉시 다음 조치를 취하세요:
- BotFather에게
/revoke전송: 텔레그램@BotFather대화방에서/revoke를 입력하고 유출된 봇을 선택합니다. 기존 토큰이 즉각 폐기되며 새로운 토큰이 재발급됩니다. - DashCloud 환경변수 갱신:
DashCloud 대시보드의 환경 변수 메뉴로 이동하여
TELEGRAM_BOT_TOKEN값을 새로 발급받은 토큰으로 교체하고 저장합니다. - 원클릭 재시작: 대시보드 우측 상단의 서비스 재시작 버튼을 누르면, 1초 만에 새 토큰으로 안전하게 24시간 가동이 재개됩니다.