Telegram Bot API

텔레그램 테스트 서버: 텔레그램 봇 테스트 환경에서 봇을 테스트하는 방법

· 7 분 분량

텔레그램 테스트 서버는 계정과 봇이 따로 존재하는 별도의 테스트 환경으로, 봇은 https://api.telegram.org/bot<token>/test/METHOD_NAME 주소로 Bot API를 호출합니다. Mini App이나 Web Login에 일반 HTTP 링크를 써야 할 때, 버려도 되는 테스트 사용자가 필요할 때, 현재 테스트 서버에서만 켜져 있는 Bot API 기능을 써 보고 싶을 때 사용합니다. 일상적인 텔레그램 봇 테스트라면 운영 환경에 두 번째 봇을 하나 더 두는 것으로 충분한 경우가 많습니다. 이 글에서는 두 가지 방법과 함께 iOS, Desktop, macOS에서 테스트 환경에 로그인하는 방법, curl·Python·JavaScript와 Bot API Tester로 테스트 API를 호출하는 방법을 설명합니다.

방법 1: 운영 환경에 테스트용 봇 따로 만들기

사용자에게 영향을 주지 않고 텔레그램 봇을 테스트하는 가장 빠른 방법은 같은 코드를 다른 봇 계정으로 하나 더 실행하는 것입니다.

  1. @BotFather에서 /newbot으로 새 봇을 만듭니다(텔레그램 봇 만들기 참고).
  2. 새 봇의 토큰을 테스트 인스턴스 설정에 넣습니다. 예를 들어 별도의 .env 파일을 둡니다.
  3. 새 봇으로 마음껏 디버깅합니다. 운영 중인 봇은 그대로 동작합니다.

주의할 점이 하나 있습니다. file_id는 봇 id 하나에 묶여 있습니다. 테스트 봇은 메인 봇이 저장해 둔 file_id를 재사용할 수 없으므로, 미디어는 테스트 봇이 다시 업로드해야 합니다.

방법 2: 텔레그램 전용 테스트 환경

더 본격적인 테스트를 위해 텔레그램은 전용 테스트 환경도 운영합니다. 이 환경은 메인(운영) 환경과 완전히 분리되어 있어서 운영 환경의 계정, 봇, 채팅, 토큰이 존재하지 않습니다. 달라지는 점은 다음과 같습니다.

운영 환경테스트 서버
사용자 계정평소 쓰는 텔레그램 계정테스트 환경에서 새로 만든 계정
봇과 토큰운영 환경의 @BotFather에서 생성테스트 계정 안의 @BotFather에서 생성, 토큰도 별도
Bot API 주소/bot<token>/METHOD_NAME/bot<token>/test/METHOD_NAME
Mini App, Web Login 링크HTTPS만 가능TLS 없는 HTTP도 허용
Flood 제한표준 제한완화되지 않으며 때로는 더 엄격함
위젯(Bot API 10.4)봇과의 개인 채팅에서만그룹, 인라인 모드, 전달에서도 동작

iOS, Desktop, macOS에서 테스트 계정 만들기

공식 앱에서 다음과 같이 텔레그램 테스트 환경에 로그인합니다.

테스트 계정은 기존 계정 옆에 추가되므로 같은 앱에서 환경을 오가며 쓸 수 있습니다. 테스트 봇과의 채팅을 포함해 그 계정에서 하는 모든 일은 테스트 환경 안에만 남습니다.

테스트 서버에서 봇을 만들고 토큰 받기

테스트 계정에서 @BotFather를 열고 평소처럼 봇을 만듭니다. /newbot을 보내고 표시 이름을 정한 다음, bot으로 끝나는 사용자명을 입력합니다. BotFather가 테스트 환경용 토큰을 보내 줍니다. 생김새는 일반 토큰과 같지만 /test/가 붙은 API 주소에서만 동작합니다. 운영 토큰과 섞이지 않도록 TEST_BOT_TOKEN처럼 별도 이름으로 보관하십시오. 토큰 관리 원칙은 텔레그램 봇 토큰 가이드와 동일합니다.

텔레그램 테스트 서버에서 Bot API 호출하기

모든 Bot API 메서드는 똑같이 동작하며, 차이는 토큰 뒤에 붙는 /test/뿐입니다. 먼저 getMe로 토큰을 확인합니다.

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

코드에서는 기본 URL을 상수 하나로 관리하면 환경 전환이 한 줄 수정으로 끝납니다. 아래의 최소한의 에코 봇은 토큰을 확인한 뒤 getUpdates 롱 폴링으로 업데이트를 받고, 429가 오면 retry_after만큼 기다립니다.

import os
import time
import requests

TOKEN = os.environ["TEST_BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}/test"  # 운영 환경에서는 "/test"를 제거


def call(method, **params):
    while True:
        data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
        if data["ok"]:
            return data["result"]
        if data.get("error_code") == 429:  # flood 제한: 안내된 시간만큼 대기
            time.sleep(data["parameters"]["retry_after"])
            continue
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")


me = call("getMe")
print("테스트 서버에서 실행 중: @" + me["username"])

offset = 0
while True:
    for update in call("getUpdates", offset=offset, timeout=30):
        offset = update["update_id"] + 1
        msg = update.get("message")
        if msg and "text" in msg:
            call("sendMessage", chat_id=msg["chat"]["id"], text="테스트 에코: " + msg["text"])
const TOKEN = process.env.TEST_BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}/test`; // 운영 환경에서는 "/test"를 제거

async function call(method, params = {}) {
  while (true) {
    const res = await fetch(`${API}/${method}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(params),
      signal: AbortSignal.timeout(40_000),
    });
    const data = await res.json();
    if (data.ok) return data.result;
    if (data.error_code === 429) { // flood 제한: 안내된 시간만큼 대기
      await new Promise((resolve) => setTimeout(resolve, data.parameters.retry_after * 1000));
      continue;
    }
    throw new Error(`${method}: ${data.error_code} ${data.description}`);
  }
}

const me = await call("getMe");
console.log("테스트 서버에서 실행 중: @" + me.username);

let offset = 0;
while (true) {
  for (const update of await call("getUpdates", { offset, timeout: 30 })) {
    offset = update.update_id + 1;
    const msg = update.message;
    if (msg?.text) {
      await call("sendMessage", { chat_id: msg.chat.id, text: "테스트 에코: " + msg.text });
    }
  }
}

테스트 계정에서 봇에게 /start를 보내면 응답이 옵니다. JavaScript 버전은 최상위 await를 사용하므로 bot.mjs로 저장하고 Node.js 18 이상에서 실행하십시오.

웹훅도 같은 방식입니다. 테스트 주소로 setWebhook을 호출하면 되고, url, 포트, secret_token에 관한 규칙은 그대로 적용됩니다(텔레그램 웹훅 설정 가이드 참고). 결과는 역시 /test/를 거쳐 getWebhookInfo로 확인합니다.

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/setWebhook" \
  -d "url=https://example.com/telegram/webhook"
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/test/getWebhookInfo"

봇 라이브러리는 보통 기본 주소를 바탕으로 요청 URL을 만듭니다. 사용하는 라이브러리에서 Bot API 기본 URL을 바꿀 수 있다면 요청이 …/bot<token>/test/METHOD_NAME으로 가도록 설정하십시오. 옵션 이름은 라이브러리마다 다르니 해당 문서를 확인하시기 바랍니다.

Bot API Tester에서 테스트 서버 사용하기

Bot API Tester를 쓰면 코드 없이 테스트 환경으로 요청을 보낼 수 있습니다.

  1. Bot API Tester의 getMe를 엽니다.
  2. 토큰 입력란 옆의 TEST 스위치를 켜거나, 주소에 ?env=test를 붙여 테스터 페이지를 엽니다.
  3. 테스트 봇의 토큰을 붙여 넣고 Execute를 누릅니다. 이제 요청은 https://api.telegram.org/bot<token>/test/METHOD로 전송됩니다.

스위치가 켜져 있는 동안에는 getUpdates 롱 폴링을 포함한 모든 메서드가 테스트 주소를 사용하므로, 테스트 계정에서 보낸 메시지가 업데이트 기록에 들어오는 것을 바로 볼 수 있습니다. 테스터는 스위치 상태를 브라우저에 기억하니, 운영 토큰을 붙여 넣기 전에 꺼 두십시오. 토큰은 언제나처럼 브라우저의 localStorage에만 저장되고, 요청은 api.telegram.org로 직접 전송됩니다.

일반 HTTP로 Mini App과 Web Login 테스트하기

Mini App 개발자가 테스트 환경을 쓰는 가장 큰 이유는 이것입니다. 테스트 환경에서는 WebAppInfo(Mini App)와 LoginUrl(Web Login 버튼)의 url에 TLS 없는 HTTP 링크를 쓸 수 있습니다. 덕분에 인증서나 터널을 준비하지 않고도 테스트 봇의 메뉴 버튼이나 web_app 버튼을 로컬 네트워크의 개발 서버에 바로 연결할 수 있습니다. 운영 환경의 링크는 반드시 HTTPS여야 합니다. 텔레그램 안에 띄우기 전에 Mini App Tester로 Telegram.WebApp API 동작을 브라우저에서 먼저 확인해 보는 것도 좋습니다.

테스트 서버에서 Bot API 10.4 위젯 사용하기

Bot API 10.4에 추가된 메시지 속 HTML 위젯은 현재 운영 환경에서 봇과의 개인 채팅에서만 동작합니다. 그룹, 인라인 모드, 전달된 메시지에서의 위젯은 당분간 테스트 서버에서만 동작하므로, 이런 시나리오는 테스트 서버에서 시험해 볼 수 있습니다. 위젯의 동작 방식은 텔레그램 위젯 가이드를 참고하십시오.

제한과 권장 사항

문제 해결

증상예상 원인해결 방법
401 Unauthorized운영 토큰을 /test/로 보냈거나, 테스트 토큰을 /test/ 없이 보냄두 환경은 분리되어 있습니다. 토큰과 URL(테스터에서는 TEST 스위치)을 맞추십시오
400 Bad Request: chat not found운영 환경의 chat id를 사용함. 해당 사용자와 채팅은 테스트 서버에 없음테스트 계정에서 테스트 봇에게 메시지를 보내고 getUpdates에서 chat id를 확인하십시오(텔레그램 chat id 확인방법)
검색에서 봇이 보이지 않음운영 계정에서 검색함봇을 만든 테스트 계정에서 검색하십시오
429 Too Many Requestsflood 제한(테스트 서버에서도 완화되지 않음)retry_after초만큼 기다린 뒤 요청 속도를 줄이십시오
HTTP 주소의 Mini App이 열리지 않음봇이나 계정이 운영 환경에 있음테스트 환경에서 만든 봇을 테스트 계정에서 여십시오

자주 묻는 질문

텔레그램 테스트 서버란 무엇인가요?

운영(프로덕션) 텔레그램과 완전히 분리된 전용 테스트 환경입니다. 사용자 계정과 봇이 따로 존재하며, 봇은 https://api.telegram.org/bot<token>/test/METHOD_NAME 주소로 Bot API를 호출합니다.

텔레그램 테스트 환경에는 어떻게 로그인하나요?

iOS에서는 설정 아이콘을 10번 탭한 뒤 Accounts → Login to another account → Test를 선택합니다. Telegram Desktop에서는 ☰ 설정을 열고 Shift + Alt를 누른 채 Add Account를 우클릭해 Test Server를 고릅니다. macOS에서는 설정 아이콘을 10번 클릭해 Debug Menu를 연 다음 ⌘ + 클릭으로 Add Account를 누릅니다.

운영 환경의 봇 토큰을 테스트 서버에서 쓸 수 있나요?

쓸 수 없습니다. 두 환경은 분리되어 있어 운영 환경에서 만든 봇은 테스트 서버에 존재하지 않고, 그 반대도 마찬가지입니다. 테스트 계정 안에서 @BotFather로 새 봇을 만드십시오. 환경에 맞지 않는 토큰을 쓰면 보통 401 Unauthorized가 반환됩니다.

텔레그램 테스트 서버에서는 요청 제한이 더 넉넉한가요?

아닙니다. 테스트 환경에서도 flood 제한은 완화되지 않으며 때로는 더 엄격할 수 있습니다. 429 Too Many Requests는 retry_after에 맞춰 처리하고, 제한 값을 코드에 고정하지 마십시오.

테스트 환경에서는 Mini App에 HTTP 주소를 써도 되나요?

됩니다. 테스트 환경에서는 WebAppInfo(Mini App)와 LoginUrl(Web Login)의 url에 TLS 없는 HTTP 링크를 쓸 수 있습니다. 운영 환경에서는 반드시 HTTPS를 사용해야 합니다.

봇을 테스트하려면 꼭 테스트 서버가 필요한가요?

그렇지 않습니다. 대부분의 작업은 운영 환경에서 @BotFather로 만든 두 번째 봇으로 충분합니다. 별도 토큰을 쓰므로 실제 사용자에게 영향을 주지 않습니다. HTTP 링크, 별도의 테스트 계정, 테스트 서버에서만 제공되는 기능이 필요할 때 테스트 서버를 사용하십시오.

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

텔레그램 봇 만들기 가이드입니다. @BotFather의 /newbot으로 봇을 생성하고 토큰을 getMe로 확인한 뒤, getUpdates와 sendMessage로 첫 메시지를 보내는 과정을 curl과 Python 예제로 설명합니다.

텔레그램 봇 API로 메시지 보내기: sendMessage 사용법과 예제

텔레그램 봇 API 메시지 보내기 가이드입니다. sendMessage를 curl·Python·JavaScript로 호출하는 예제, HTML·MarkdownV2 서식, 인라인 버튼, 그룹·채널 전송, 400·403·429 오류 해결법을 정리했습니다.

텔레그램 봇 토큰: 발급부터 확인, 폐기, 안전한 보관까지

텔레그램 봇 토큰을 @BotFather에서 발급받는 법, 기존 봇의 토큰 찾기, getMe로 유효성 확인, 유출 시 폐기 방법을 정리했습니다. n8n·AI 비서 연동에 필요한 bot token과 chat id도 안내합니다.

텔레그램 웹훅 설정 가이드: setWebhook, secret_token, getWebhookInfo

텔레그램 봇 웹훅 설정 방법을 단계별로 정리했습니다. setWebhook 파라미터, secret_token 헤더 검증 코드, getWebhookInfo 상태 확인, deleteWebhook으로 되돌리기, 409·HTTPS 오류 해결까지 다룹니다.

텔레그램 chat id 확인방법: 개인, 그룹, 채널, 토픽별 chat id 찾기

텔레그램 chat id 확인방법을 개인 채팅, 그룹, 슈퍼그룹, 채널, 포럼 토픽별로 정리했습니다. getUpdates로 chat id를 찾는 법, -100으로 시작하는 ID의 의미, 결과가 비어 있을 때 해결법까지 설명합니다.

텔레그램 웹사이트 위젯: 로그인 위젯, 게시물 임베드, 댓글, 공유 버튼

웹사이트에 텔레그램을 붙이는 방법을 정리했습니다. 새 Telegram Login(OIDC), 기존 로그인 위젯과 hash 검증 코드, 게시물 임베드, 댓글, 공유 버튼까지 다룹니다.

TelegramWidget JavaScript API: 텔레그램 위젯 API 레퍼런스와 오류 코드, 제한

텔레그램 위젯의 TelegramWidget JavaScript API를 정리했습니다. 속성, request(), 이벤트, 오류 코드, CSS 변수, widget_query와 answerWidgetQuery, 모든 제한값까지 담았습니다.

텔레그램 위젯 예제: HTML과 Python 봇 코드 전체 공개

바로 실행할 수 있는 텔레그램 위젯 예제 모음입니다. 정적 주문 카드, widget_query 카운터, 실시간 공유 투표, 브라우저 미리보기까지 HTML과 Python 코드로 설명합니다.

텔레그램 위젯 가이드: 봇 메시지 안에서 동작하는 HTML 위젯

Bot API 10.4에 추가된 텔레그램 위젯의 개념, sendWidget 사용법, chat_data와 public_data, 현재 사용 가능한 범위와 Mini App과의 차이를 정리했습니다.