텔레그램 봇 API 제한 총정리: 전송 속도, 429 오류, 파일 크기, 메시지 길이
텔레그램 봇 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시간처럼 긴 시간에 걸쳐 나누어 보내라고 텔레그램은 권장합니다.
유료 브로드캐스트: 초당 최대 1000건
초당 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_data | 1~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 partsfunction 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;
}업데이트와 웹훅 관련 제한
- 수신 업데이트는 봇이 받아 갈 때까지 텔레그램 서버에 최대 24시간 보관됩니다.
getUpdates는 한 번에 1~100건을 반환합니다(limit, 기본값 100). 롱 폴링에는timeout을 쓰고,offset= 마지막update_id+ 1로 수신을 확인합니다.- 웹훅이 설정된 동안에는
deleteWebhook을 호출하기 전까지getUpdates가 동작하지 않습니다(409 Conflict). setWebhook의max_connections는 1~100(기본값 40)이며 포트는 443, 80, 88, 8443만 허용됩니다. 로컬 Bot API 서버는 최대 100000 연결과 임의 포트를 지원합니다.
텔레그램 봇 API 제한에 걸리지 않는 방법
- 모든 전송을 하나의 큐로 모아 전체 속도는 초당 30건 미만, 채팅별로는 초당 1건 이하로 유지합니다.
- 진행 상황은 새 메시지를 여러 개 보내는 대신
editMessageText로 메시지 하나를 수정해 보여 줍니다. - 미디어는 다시 업로드하지 말고
file_id로 재전송합니다. retry_after를 지키고, 403 오류는 절대 재시도하지 않습니다.allowed_updates를 지정해 실제로 처리하는 업데이트 종류만 받습니다.
관련 가이드: 텔레그램 봇 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 검증까지 다룹니다.