Telegram Bot API

텔레그램 봇 API 제한 총정리: 전송 속도, 429 오류, 파일 크기, 메시지 길이

· 7 분 분량

텔레그램 봇 API 제한은 숫자만 보면 간단합니다. 한 채팅에 초당 약 1건, 그룹에 분당 20건, 모든 채팅을 합쳐 초당 약 30건입니다. 이를 넘기면 API가 retry_after 값과 함께 429 Too Many Requests를 반환합니다. 이 글에서는 전송 속도, 유료 브로드캐스트, 파일 크기, 텍스트 길이, 업데이트 관련 제한을 한곳에 모으고, 봇이 그 범위 안에서 동작하도록 하는 코드를 소개합니다.

메시지 전송 속도 제한(rate limit)

공식 Bots FAQ에 나온 일반(무료) 전송 제한은 다음과 같습니다.

범위제한참고
한 채팅초당 약 1건짧은 순간의 몰림은 허용되지만 이어지면 429 오류가 납니다.
한 그룹분당 20건그룹 채팅별로 계산됩니다.
대량 알림초당 약 30건유료 브로드캐스트를 쓰면 초당 최대 1000건.

이 수치는 계약 조건이 아니라 가이드라인으로 보아야 합니다. 텔레그램은 제한이 바뀔 수 있다고 밝히고 있으며, 테스트 환경에서도 플러드 제한은 완화되지 않습니다(오히려 더 엄격할 수 있습니다). retry_after를 존중하는 코드는 "30"을 하드코딩한 코드가 깨지는 변화에도 버팁니다.

429 Too Many Requests와 retry_after

플러드 제한에 걸리면 다음과 같은 응답이 옵니다.

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 17",
  "parameters": {"retry_after": 17}
}

retry_after는 요청을 다시 보낼 수 있을 때까지 남은 초입니다. 최소한 그만큼 기다린 뒤 같은 요청을 다시 보내십시오. 즉시 재시도하면 차단만 길어집니다. Python과 JavaScript 헬퍼 예제입니다.

import time
import requests

API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours"

def call(method, max_attempts=5, **params):
    for _ in range(max_attempts):
        r = requests.post(f"{API}/{method}", json=params, timeout=30).json()
        if r["ok"]:
            return r["result"]
        if r["error_code"] != 429:
            raise RuntimeError(f'{r["error_code"]}: {r["description"]}')
        time.sleep(r.get("parameters", {}).get("retry_after", 1) + 0.5)
    raise RuntimeError("계속 제한에 걸려 중단합니다")

call("sendMessage", chat_id=123456789, text="안녕하세요")
const API = "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours";
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function call(method, params, maxAttempts = 5) {
  for (let i = 0; i < maxAttempts; i++) {
    const res = await fetch(`${API}/${method}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(params),
    });
    const data = await res.json();
    if (data.ok) return data.result;
    if (data.error_code !== 429) throw new Error(data.description);
    await sleep(((data.parameters?.retry_after ?? 1) + 0.5) * 1000);
  }
  throw new Error("계속 제한에 걸려 중단합니다");
}

큐로 대량 발송 속도 조절하기

재시도는 개별 요청을 살릴 뿐입니다. 뉴스레터나 알림처럼 대량으로 보낼 때는 전송 속도 자체를 조절해야 합니다. 예를 들어 전체 속도를 초당 30건보다 조금 낮게 맞춥니다.

def broadcast(chat_ids, text, per_second=25):
    for chat_id in chat_ids:
        try:
            call("sendMessage", chat_id=chat_id, text=text)
        except RuntimeError as e:
            print(chat_id, e)  # 403: 사용자가 봇을 차단함, 목록에서 제외
        time.sleep(1 / per_second)
async function broadcast(chatIds, text, perSecond = 25) {
  for (const chatId of chatIds) {
    try {
      await call("sendMessage", { chat_id: chatId, text });
    } catch (e) {
      console.log(chatId, e.message); // 403: 사용자가 봇을 차단함, 목록에서 제외
    }
    await sleep(1000 / perSecond);
  }
}

운영 환경에서는 이 작업을 백그라운드 워커에서 실행하고, 채팅별 마지막 전송 시각을 기록해 어떤 채팅에도 초당 1건을 넘지 않게 하십시오. 403을 반환한 채팅은 재시도하지 말고 목록에서 제외합니다. 유료 브로드캐스트 없이 대규모로 발송할 때는 8~12시간처럼 긴 시간에 걸쳐 나누어 보내라고 텔레그램은 권장합니다.

초당 30건으로 부족하다면 @BotFather에서 유료 브로드캐스트를 켜고 sendMessage, sendPhoto, sendMediaGroup 같은 전송 메서드에 "allow_paid_broadcast": true를 넘기십시오. 그러면 초당 최대 1000건까지 브로드캐스트할 수 있습니다. 무료 한도인 초당 30건을 넘는 메시지마다 봇 잔액에서 0.1 Telegram Stars가 차감되며, 성공적으로 전송된 메시지에만 과금됩니다. 사용하려면 최소 Stars 잔액이 필요하고(Bots FAQ에는 사용자 수 기준도 언급되어 있습니다), 수치는 바뀔 수 있으므로 계획을 세우기 전에 공식 문서에서 현재 조건을 확인하십시오.

텔레그램 봇 파일 크기 제한

작업제한
multipart/form-data로 파일 업로드50MB
사진 업로드10MB, 가로+세로 ≤ 10000, 가로세로 비율 ≤ 20
HTTP URL로 사진 전송5MB
HTTP URL로 기타 파일 전송20MB (URL로 보내는 sendDocument는 .PDF와 .ZIP만 가능)
getFile로 다운로드20MB, 다운로드 링크는 최소 1시간 유효
file_id로 재전송크기 제한 없음

로컬 Bot API 서버를 쓰면 가장 큰 두 가지 제약이 풀립니다. 업로드는 2000MB까지, 다운로드는 크기 제한 없이 가능하고, 웹훅도 임의 포트의 일반 HTTP로 받을 수 있습니다. 봇을 자체 서버로 옮기기 전에 logOut을 호출하십시오. 파일을 내려받기 전에 확인하려면 Bot API Tester의 getFile을 호출해 file_size와 file_path를 보면 됩니다.

메시지 길이와 기타 콘텐츠 제한

항목제한
메시지 텍스트엔티티 파싱 후 1~4096자
미디어 캡션0~1024자
리치 메시지(sendRichMessage)UTF-8 32768자, 블록 500개, 미디어 50개, 표 열 20개
callback_data1~64바이트
미디어 그룹2~10개
인라인 쿼리 응답결과 최대 50개
answerCallbackQuery 텍스트0~200자
setMyCommands명령어 100개, 명령어 1~32자, 설명 1~256자
딥 링크 start 파라미터최대 64자, A-Z a-z 0-9 _ -
미니앱 sendData최대 4096바이트

callback_data는 바이트 단위로 계산됩니다. 한글처럼 ASCII가 아닌 문자는 UTF-8에서 글자당 2~4바이트(한글은 3바이트)를 차지하므로, 버튼에는 짧은 ID만 넣고 자세한 내용은 데이터베이스에 저장하십시오. 4096자를 넘는 텍스트는 가능하면 줄바꿈 단위로 나누어 보냅니다.

def split_text(text, limit=4000):  # 안전하게 4096보다 조금 작게
    parts, current = [], ""
    for line in text.splitlines(keepends=True):
        if current and len(current) + len(line) > limit:
            parts.append(current)
            current = ""
        while len(line) > limit:
            parts.append(line[:limit])
            line = line[limit:]
        current += line
    if current:
        parts.append(current)
    return parts
function splitText(text, limit = 4000) { // 안전하게 4096보다 조금 작게
  const parts = [];
  let current = "";
  for (let line of text.split(/(?<=\n)/)) { // 줄 단위로 나누고 "\n"은 유지
    if (current && current.length + line.length > limit) {
      parts.push(current);
      current = "";
    }
    while (line.length > limit) {
      parts.push(line.slice(0, limit));
      line = line.slice(limit);
    }
    current += line;
  }
  if (current) parts.push(current);
  return parts;
}

업데이트와 웹훅 관련 제한

텔레그램 봇 API 제한에 걸리지 않는 방법

관련 가이드: 텔레그램 봇 API 메시지 보내기에서 서식과 메시지별 오류를, 텔레그램 웹훅 설정에서 대규모 업데이트 수신을, 텔레그램 봇 API 10의 새 기능에서 리치 메시지와 그 제한을 다룹니다.

자주 묻는 질문

텔레그램 봇 API의 전송 속도 제한은 얼마인가요?

텔레그램 Bots FAQ는 세 가지 수치를 제시합니다. 한 채팅에는 초당 1건을 넘기지 말 것, 그룹에는 분당 20건 이하로 보낼 것, 대량 알림은 초당 약 30건까지입니다. 이를 넘기면 429 Too Many Requests가 반환됩니다.

텔레그램 429 Too Many Requests는 어떻게 해결하나요?

오류 응답의 parameters.retry_after를 읽어 그 초만큼 기다린 뒤 같은 요청을 다시 보냅니다. 제한에 아예 걸리지 않으려면 채팅별·전체 전송 속도를 조절하는 큐를 거쳐 보내십시오.

텔레그램 봇의 파일 크기 제한은 얼마인가요?

봇은 최대 50MB(사진은 10MB)까지 업로드하고, getFile로 최대 20MB까지 다운로드할 수 있습니다. URL로 보낼 때는 사진 5MB, 기타 파일 20MB가 한도입니다. 로컬 Bot API 서버를 쓰면 업로드 2000MB, 다운로드는 크기 제한이 없습니다.

텔레그램 봇 메시지는 최대 몇 자까지 보낼 수 있나요?

텍스트 메시지는 엔티티 파싱 후 1~4096자, 미디어 캡션은 0~1024자이므로 더 긴 글은 나누어 보내야 합니다. 리치 메시지(Bot API 10.1 이상)는 UTF-8 기준 최대 32768자까지 허용합니다.

텔레그램 봇이 초당 30건보다 많이 보내려면 어떻게 하나요?

@BotFather에서 유료 브로드캐스트를 켜고 allow_paid_broadcast: true를 넘기면 초당 최대 1000건까지 보낼 수 있습니다. 무료 한도인 초당 30건을 넘는 메시지마다 0.1 Telegram Stars가 부과되며, 성공적으로 전송된 메시지에만 과금됩니다.

텔레그램은 봇의 업데이트를 얼마 동안 보관하나요?

전달되지 않은 업데이트는 최대 24시간 보관됩니다. getUpdates는 한 번에 최대 100건을 반환하며, 마지막 update_id + 1을 offset으로 넘겨 수신을 확인합니다.

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

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

텔레그램 봇 배포와 호스팅: VPS, Docker, 서버리스

텔레그램 봇 배포 방법: 폴링과 웹훅 선택, VPS의 systemd 서비스, Docker, secret_token을 검증하는 Cloudflare Workers, 출시 전 체크리스트까지 정리했습니다.

텔레그램 봇 API 10.0~10.5 변경 사항: 봇 설정, 위젯, 리치 메시지, 임시 메시지, 게스트 모드

텔레그램 봇 API 10.0~10.5의 새 기능을 정리했습니다. setMySettings와 BotFullInfo, HTML 위젯, 리치·임시 메시지, 게스트 모드를 JSON 예제와 함께 설명합니다.

텔레그램 봇 API 오류 총정리: 오류별 의미와 해결 방법

텔레그램 봇 API 오류를 코드별로 정리했습니다. 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after의 원인과 해결, 처리 코드까지 다룹니다.

텔레그램 봇 명령어 가이드: setMyCommands, 명령어 스코프, /start 딥링크

텔레그램 봇 명령어 설정 방법: @BotFather /setcommands, 스코프·언어별 setMyCommands, /start 딥링크 파라미터, 그룹의 /cmd@bot 처리를 예제로 설명합니다.

텔레그램 봇 키보드: 인라인 키보드, 콜백 버튼, 리플라이 키보드

텔레그램 봇 버튼 만드는 법을 정리했습니다. callback_data 인라인 키보드, answerCallbackQuery, 버튼을 누른 뒤 메시지 수정, 리플라이 키보드와 ForceReply까지 다룹니다.

n8n 텔레그램 연동 가이드: 봇 연결, 워크플로 트리거, 메시지 보내기

n8n 텔레그램 연동 방법: 봇 토큰을 Access Token으로 등록하고, 공개 HTTPS로 Telegram Trigger 웹훅을 받고, chat id로 메시지를 보내며 자주 나는 오류를 해결합니다.

텔레그램 봇 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의 의미, 결과가 비어 있을 때 해결법까지 설명합니다.

텔레그램 인라인 봇 가이드: 인라인 모드 활성화와 인라인 쿼리 응답

텔레그램 인라인 봇 만드는 법: @BotFather나 setMySettings로 인라인 모드를 켜고 inline_query에 answerInlineQuery로 답하는 과정을 Python·JS 예제로 설명합니다.

텔레그램 스타 결제 봇 가이드: 인보이스, 결제 전 확인, 환불, 구독

텔레그램 봇에서 스타(Stars) 결제 받는 법: XTR sendInvoice, pre_checkout_query, successful_payment, 환불, 구독까지 Python·JS 코드로 설명합니다.

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

텔레그램 테스트 서버 사용법을 정리했습니다. 테스트 환경 로그인, 테스트용 봇 만들기, /test/ 주소로 Bot API 호출하기, Bot API Tester의 TEST 스위치까지 다룹니다.

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

웹사이트에 텔레그램을 붙이는 방법을 정리했습니다. 새 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과의 차이를 정리했습니다.

텔레그램 미니앱 테스트 가이드: 브라우저 목 모드부터 실제 텔레그램까지

텔레그램 미니앱 테스트 방법을 단계별로 정리했습니다. 브라우저 목(mock) 모드, HTTPS 터널로 localhost 열기, 테스트 환경, 플랫폼별 DevTools, initData 검증까지 다룹니다.