텔레그램 봇 키보드: 인라인 키보드, 콜백 버튼, 리플라이 키보드
텔레그램 인라인 키보드는 봇 메시지에 붙는 버튼 묶음입니다. sendMessage의 reply_markup 파라미터에 InlineKeyboardMarkup 객체를 넘기면 되고, 사용자가 콜백 버튼을 누르면 봇에 callback_query 업데이트가 전달되며 봇은 이를 answerCallbackQuery로 응답해야 합니다. 반면 리플라이 키보드(ReplyKeyboardMarkup)는 사용자의 문자 키보드를 미리 정해 둔 답변으로 바꿉니다. 이 글에서는 두 종류의 텔레그램 봇 버튼, 모든 버튼 타입, 버튼을 누른 뒤 메시지 수정, 그리고 Python과 JavaScript로 작성한 완전한 동작 예제를 다룹니다.
인라인 키보드와 리플라이 키보드 비교
| 인라인 키보드 | 리플라이 키보드 | |
|---|---|---|
| 객체 | InlineKeyboardMarkup | ReplyKeyboardMarkup |
| 표시 위치 | 특정 메시지 아래 | 사용자 키보드 자리 |
| 누르면 | 콜백 쿼리, URL 열기, 미니앱, 인라인 모드, 텍스트 복사 등 | 버튼 텍스트를 메시지로 전송, 또는 연락처·위치·사용자·채팅 공유 |
| 나중에 수정 | 가능, editMessageReplyMarkup 사용 | 불가, 새 키보드를 보내거나 제거 |
| 채널 | 지원 | 미지원 |
둘 다 ReplyKeyboardRemove, ForceReply와 함께 같은 reply_markup 파라미터에 넣습니다. 메시지 하나에는 이 네 객체 중 하나만 담을 수 있습니다.
텔레그램 인라인 키보드 보내기
inline_keyboard는 행의 배열이고, 각 행은 버튼의 배열입니다.
curl -X POST "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/sendMessage" \
-H "Content-Type: application/json" \
-d '{
"chat_id": 123456789,
"text": "옵션을 선택하세요:",
"reply_markup": {
"inline_keyboard": [
[{"text": "좋아요", "callback_data": "like"}, {"text": "도움말", "callback_data": "help"}],
[{"text": "Bot API 문서", "url": "https://core.telegram.org/bots/api"}]
]
}
}'
각 버튼에는 text 외에 버튼 타입을 정하는 필드가 정확히 하나 있어야 합니다.
| 필드 | 버튼 동작 |
|---|---|
callback_data | 이 문자열을 담은 콜백 쿼리를 봇에 보냄, 1~64바이트 |
url | HTTP 또는 tg:// 링크를 엶 |
web_app | 미니앱 실행, 사용자와 봇의 개인 채팅에서만 가능 |
login_url | HTTPS URL을 열고 사이트에 사용자를 인증 |
switch_inline_query, switch_inline_query_current_chat, switch_inline_query_chosen_chat | 다른 채팅, 현재 채팅, 또는 선택한 유형의 채팅 입력창에 봇 사용자명과 쿼리를 넣음 |
copy_text | {"text": "…"}(1~256자)를 클립보드에 복사 |
pay | 결제 버튼, 인보이스 메시지에서만 가능하며 첫 행의 첫 버튼이어야 함 |
callback_game | 게임 실행, 첫 행의 첫 버튼이어야 함 |
disabled | 아무 동작도 하지 않는 DisabledButton(Bot API 10.3) |
선택 필드 두 개로 버튼 모양을 바꿀 수 있습니다(Bot API 9.4, 리플라이 키보드 버튼에도 적용 가능). style은 "danger"(빨강), "success"(초록), "primary"(파랑) 중 하나이고, icon_custom_emoji_id는 텍스트 앞에 커스텀 이모지를 붙입니다. 커스텀 이모지는 봇이 사용할 수 있을 때만 표시됩니다. 즉 봇이 Fragment에서 추가 사용자명을 구매했거나, 봇 소유자가 Telegram Premium 사용자이고 메시지를 개인 채팅, 그룹, 슈퍼그룹에 직접 보내는 경우입니다.
callback_data 설계하기
64바이트 제한은 글자 수가 아니라 바이트 기준이므로 like, page:3, del:8812처럼 짧고 기계가 읽기 쉬운 값을 쓰고 실제 데이터는 데이터베이스에 두십시오. 한글은 UTF-8에서 글자당 3바이트이므로 21자만 넣어도 한도에 가까워집니다. API 문서는 받은 data에 해당하는 버튼이 메시지에 없을 수도 있다고 경고합니다. 따라서 신뢰할 수 없는 사용자 입력으로 취급해 파싱하고 검증하며, 사용자에게 해당 동작 권한이 있는지 확인하십시오. 값이 너무 길면 키보드를 보낼 때 거부되며, 보통 Bad Request: BUTTON_DATA_INVALID가 반환됩니다.
answerCallbackQuery로 모든 버튼 입력에 응답하기
콜백 버튼을 누르면 callback_query 필드가 담긴 업데이트가 옵니다. 여기에는 id, from(사용자), data, 그리고 봇이 보낸 메시지라면 원본 메시지인 message가 들어 있습니다. 버튼을 누른 뒤 텔레그램 클라이언트는 봇이 answerCallbackQuery를 호출할 때까지 진행 표시를 띄우므로, id 외에 다른 파라미터가 없더라도 매번 호출하십시오.
| 파라미터 | 의미 |
|---|---|
callback_query_id | 필수, 콜백 쿼리의 id |
text | 알림 텍스트 0~200자, 생략하면 아무것도 표시되지 않음 |
show_alert | true면 채팅 상단 알림 대신 경고창을 표시 |
url | 게임 URL(callback_game 버튼용) 또는 t.me/your_bot?start=XXXX 같은 링크 |
cache_time | 클라이언트가 결과를 캐시할 수 있는 시간(초), 기본값 0 |
응답은 빠르게 하십시오. 오래된 쿼리에 응답하면 Bad Request: query is too old and response timeout expired or query ID is invalid로 실패합니다. 자세한 내용은 answerCallbackQuery 레퍼런스를 참고하십시오.
버튼을 누른 뒤 메시지 수정하기
새 메시지를 보내는 것보다 기존 메시지를 수정하는 편이 빠르고 깔끔하며, 텔레그램도 설정 화면이나 페이지 넘김에 이 방식을 권장합니다. callback_query.message에서 chat.id와 message_id를 가져와 다음을 호출합니다.
editMessageText: 텍스트를 바꾸며, 필요하면 새reply_markup도 함께 넘깁니다.editMessageReplyMarkup: 키보드만 바꿉니다.reply_markup을 생략하면 키보드가 제거됩니다.
새 텍스트와 키보드가 현재와 완전히 같으면 API가 Bad Request: message is not modified를 반환하므로, 수정 전에 비교하거나 이 오류만 골라서 무시하십시오.
전체 예제: 콜백 버튼이 있는 인라인 메뉴
이 봇은 /start에 메뉴로 답하고, 메시지별로 좋아요 수를 세며, 도움말 버튼에는 경고창을 띄우고, 변경될 때마다 메시지를 수정합니다. getUpdates 롱 폴링을 쓰므로 웹훅 없이 localhost에서 실행됩니다. 먼저 환경 변수 BOT_TOKEN을 설정하십시오.
import os
import requests
TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
likes = {} # (chat_id, message_id) -> 좋아요 수
def call(method, **params):
data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
if not data["ok"]:
raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
return data["result"]
def menu(count):
return {"inline_keyboard": [
[{"text": f"좋아요 ({count})", "callback_data": "like", "style": "success"},
{"text": "초기화", "callback_data": "reset", "style": "danger"}],
[{"text": "도움말", "callback_data": "help"},
{"text": "Bot API 문서", "url": "https://core.telegram.org/bots/api"}],
]}
def on_callback(cq):
msg, data = cq.get("message"), cq.get("data")
if not msg or data not in ("like", "reset", "help"):
call("answerCallbackQuery", callback_query_id=cq["id"], text="알 수 없는 버튼입니다")
return
if data == "help":
call("answerCallbackQuery", callback_query_id=cq["id"], show_alert=True,
text="좋아요는 1씩 늘리고, 초기화는 0으로 되돌립니다.")
return
key = (msg["chat"]["id"], msg["message_id"])
old = likes.get(key, 0)
new = old + 1 if data == "like" else 0
call("answerCallbackQuery", callback_query_id=cq["id"],
text="감사합니다!" if data == "like" else "카운터를 초기화했습니다")
if new != old: # "message is not modified" 방지
likes[key] = new
call("editMessageText", chat_id=key[0], message_id=key[1],
text=f"좋아요: {new}", reply_markup=menu(new))
offset = 0
while True:
updates = call("getUpdates", offset=offset, timeout=30,
allowed_updates=["message", "callback_query"])
for update in updates:
offset = update["update_id"] + 1
if "callback_query" in update:
on_callback(update["callback_query"])
elif update.get("message", {}).get("text") == "/start":
chat_id = update["message"]["chat"]["id"]
call("sendMessage", chat_id=chat_id, text="좋아요: 0", reply_markup=menu(0))const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const likes = new Map(); // "chatId:messageId" -> 좋아요 수
async function call(method, params = {}) {
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) throw new Error(`${method}: ${data.error_code} ${data.description}`);
return data.result;
}
function menu(count) {
return { inline_keyboard: [
[{ text: `좋아요 (${count})`, callback_data: "like", style: "success" },
{ text: "초기화", callback_data: "reset", style: "danger" }],
[{ text: "도움말", callback_data: "help" },
{ text: "Bot API 문서", url: "https://core.telegram.org/bots/api" }],
] };
}
async function onCallback(cq) {
const msg = cq.message;
const data = cq.data;
if (!msg || !["like", "reset", "help"].includes(data)) {
await call("answerCallbackQuery", { callback_query_id: cq.id, text: "알 수 없는 버튼입니다" });
return;
}
if (data === "help") {
await call("answerCallbackQuery", { callback_query_id: cq.id, show_alert: true,
text: "좋아요는 1씩 늘리고, 초기화는 0으로 되돌립니다." });
return;
}
const key = `${msg.chat.id}:${msg.message_id}`;
const old = likes.get(key) ?? 0;
const next = data === "like" ? old + 1 : 0;
await call("answerCallbackQuery", { callback_query_id: cq.id,
text: data === "like" ? "감사합니다!" : "카운터를 초기화했습니다" });
if (next !== old) { // "message is not modified" 방지
likes.set(key, next);
await call("editMessageText", { chat_id: msg.chat.id, message_id: msg.message_id,
text: `좋아요: ${next}`, reply_markup: menu(next) });
}
}
let offset = 0;
while (true) {
const updates = await call("getUpdates", { offset, timeout: 30,
allowed_updates: ["message", "callback_query"] });
for (const update of updates) {
offset = update.update_id + 1;
if (update.callback_query) {
await onCallback(update.callback_query);
} else if (update.message?.text === "/start") {
await call("sendMessage", { chat_id: update.message.chat.id, text: "좋아요: 0",
reply_markup: menu(0) });
}
}
}JavaScript 버전은 최상위 await를 쓰므로 bot.mjs로 저장해 Node.js 18 이상에서 실행하십시오. 카운터는 메모리에 저장되며, 실제 봇이라면 데이터베이스에 저장해야 합니다. 기본 버튼 색상을 원하면 style 필드를 빼면 됩니다.
텔레그램 리플라이 키보드
리플라이 키보드는 미리 정해 둔 답변을 제공합니다. 일반 텍스트 버튼(문자열만으로도 표기 가능)은 사용자가 직접 입력한 것처럼 그 텍스트를 채팅에 보내므로, 봇은 다른 메시지와 똑같이 처리하면 됩니다.
{
"keyboard": [
["카탈로그", "장바구니"],
[{"text": "전화번호 공유", "request_contact": true},
{"text": "위치 보내기", "request_location": true}]
],
"resize_keyboard": true,
"one_time_keyboard": true,
"input_field_placeholder": "메뉴를 선택하세요"
}
| 필드 | 효과 |
|---|---|
resize_keyboard | 행 수에 맞게 높이를 조절합니다. 기본값은 표준 키보드와 같은 높이입니다. |
one_time_keyboard | 누른 뒤 키보드를 숨깁니다. 사용자는 키보드 아이콘으로 다시 열 수 있습니다. |
is_persistent | 일반 키보드가 숨겨져 있을 때 항상 이 키보드를 표시합니다. |
input_field_placeholder | 입력창의 플레이스홀더, 1~64자 |
selective | @멘션된 사용자나 답장 대상 메시지를 보낸 사람에게만 키보드를 표시합니다. |
특수 버튼은 개인 채팅에서만 동작합니다. request_contact는 사용자의 전화번호를 연락처로 보내고, request_location은 현재 위치를 보내며, request_poll은 투표를 만들도록 요청하고, web_app은 미니앱을 실행합니다. request_users(KeyboardButtonRequestUsers)와 request_chat(KeyboardButtonRequestChat)은 선택 화면을 열고 결과를 users_shared와 chat_shared 서비스 메시지로 돌려줍니다. 둘 다 메시지 안에서 고유한 부호 있는 32비트 정수 request_id가 필요합니다.
{"keyboard": [[
{"text": "사용자 선택", "request_users": {"request_id": 1, "user_is_bot": false, "max_quantity": 3}},
{"text": "내 그룹 선택", "request_chat": {"request_id": 2, "chat_is_channel": false, "chat_is_created": true}}
]], "resize_keyboard": true}
ReplyKeyboardRemove와 ForceReply
리플라이 키보드는 봇이 다른 키보드를 보낼 때까지 계속 표시됩니다. 제거하려면 {"remove_keyboard": true}를 담은 메시지를 보내십시오. ForceReply({"force_reply": true, "input_field_placeholder": "도시 이름"})는 사용자가 답장을 누른 것처럼 봇 메시지에 대한 답장 화면을 엽니다. 프라이버시 모드가 켜져 있어도 답변이 봇에 전달되므로 그룹에서 단계별로 입력받을 때 유용합니다. 리플라이 키보드와 마찬가지로 두 객체 모두 채널에서는 동작하지 않습니다.
Bot API Tester에서 직접 해 보기
- Bot API Tester의 sendMessage를 열고 토큰과 chat id를 입력합니다.
- 위의 JSON 키보드 중 하나를
reply_markup에 붙여 넣고 실행합니다. - 텔레그램에서 콜백 버튼을 누른 뒤 테스터에서
getUpdates를 실행해callback_query업데이트를 확인하고, answerCallbackQuery로 응답합니다.
텔레그램 봇 버튼 문제 해결
| 증상 | 원인과 해결 |
|---|---|
| 버튼을 누른 뒤 로딩 표시가 계속됨 | answerCallbackQuery를 호출하지 않았습니다. 모든 콜백 쿼리에 응답하십시오. |
callback_query 업데이트가 오지 않음 | allowed_updates에 callback_query가 없거나, 다른 프로세스(웹훅이나 두 번째 폴링 인스턴스)가 업데이트를 가져가고 있습니다. |
BUTTON_DATA_INVALID | callback_data가 비어 있거나 64바이트를 넘습니다. |
message is not modified | 수정 내용이 텍스트나 키보드를 바꾸지 않습니다. |
query is too old… | 응답이 너무 늦었습니다. 예를 들어 재시작 후 오래된 업데이트를 처리한 경우입니다. |
| 그룹에서 연락처·위치 버튼이 동작하지 않음 | 이 버튼들은 개인 채팅에서만 쓸 수 있습니다. |
오류 메시지 전체 목록은 텔레그램 봇 API 오류 총정리에서 확인하십시오. 서식과 그 밖의 sendMessage 옵션은 텔레그램 봇 API 메시지 보내기에서 다루며, 인라인 전환 버튼은 인라인 모드와 함께 쓰입니다.
자주 묻는 질문
텔레그램 인라인 키보드와 리플라이 키보드의 차이는 무엇인가요?
인라인 키보드(InlineKeyboardMarkup)는 특정 메시지에 붙으며, 버튼을 눌러도 채팅에 아무것도 전송되지 않습니다. 리플라이 키보드(ReplyKeyboardMarkup)는 사용자의 문자 키보드를 대신하며, 일반 텍스트 버튼은 그 텍스트를 일반 메시지로 보냅니다.
callback_data는 최대 몇 자까지 넣을 수 있나요?
1~64바이트입니다. 글자 수가 아니라 바이트이며, 한글 같은 비라틴 문자는 UTF-8에서 2바이트 이상을 차지합니다. item:42처럼 짧은 키를 넣고 실제 데이터는 서버에 보관하십시오.
버튼을 누른 뒤 로딩 표시가 계속 사라지지 않는 이유는 무엇인가요?
봇이 answerCallbackQuery를 호출하지 않았기 때문입니다. 텔레그램 클라이언트는 응답이 올 때까지 진행 표시를 띄우므로, text가 없더라도 모든 콜백 쿼리에 응답하십시오.
사용자가 버튼을 누른 뒤 버튼을 바꾸려면 어떻게 하나요?
callback_query.message의 chat_id와 message_id로 editMessageReplyMarkup을 호출하면 키보드만 바뀌고, editMessageText를 호출하면 텍스트와 키보드를 함께 바꿀 수 있습니다.
리플라이 키보드는 어떻게 없애나요?
reply_markup을 {"remove_keyboard": true}(ReplyKeyboardRemove)로 지정한 메시지를 보냅니다. 한 번 누른 뒤 숨기기만 하고 다시 열 수 있게 하려면 one_time_keyboard를 쓰십시오.
채널 메시지에도 버튼을 달 수 있나요?
인라인 키보드는 가능합니다. 리플라이 키보드, ReplyKeyboardRemove, ForceReply는 채널에서 지원되지 않습니다.
관련 가이드
텔레그램 봇 만들기: @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의 원인과 해결, 처리 코드까지 다룹니다.
텔레그램 봇 API 제한 총정리: 전송 속도, 429 오류, 파일 크기, 메시지 길이
텔레그램 봇 API 전송 제한을 정리했습니다. 초당 30건, 채팅당 초당 1건, 그룹 분당 20건 기준과 429 retry_after 처리, 파일 크기·메시지 길이 제한까지 다룹니다.
텔레그램 봇 명령어 가이드: setMyCommands, 명령어 스코프, /start 딥링크
텔레그램 봇 명령어 설정 방법: @BotFather /setcommands, 스코프·언어별 setMyCommands, /start 딥링크 파라미터, 그룹의 /cmd@bot 처리를 예제로 설명합니다.
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 검증까지 다룹니다.