텔레그램 봇 API 튜토리얼: 나만의 첫 봇 만들기

가장 빠른 텔레그램 봇 API 튜토리얼은 세 가지 명령으로 요약됩니다. BotFather에서 토큰을 받고, getUpdates를 호출하여 메시지를 읽고, sendMessage를 호출하여 답장하는 것입니다. 봇 개발의 모든 것은 이 반복적인 과정 위에 구축됩니다. 이 가이드는 첫 cURL 요청부터 웹훅과 라이브러리를 갖춘 실행 중인 봇에 이르기까지 전체 과정을 안내합니다.

봇 API는 HTTP 인터페이스이므로, 애플리케이션 코드를 한 줄도 작성하기 전에 curl로 테스트할 수 있습니다. 덕분에 배우기 쉬운 API 중 하나입니다. 오늘 당장 작동하는 봇을 만들고 싶은 개발자나, TeleClaw와 같은 노코드 플랫폼과 코딩을 저울질하는 빌더라면 제대로 찾아오셨습니다.

이 가이드를 마치면 API가 요청을 인증하는 방법, 메시지를 주고받는 방법, 롱 폴링과 웹훅의 차이점, 그리고 대부분의 첫 봇을 좌절시키는 속도 제한에 대해 이해하게 될 것입니다.

핵심 요약

• 봇은 그저 HTTP 클라이언트일 뿐입니다. 모든 메서드는 https://api.telegram.org/bot<TOKEN>/METHOD_NAME으로 보내는 요청이므로, cURL만으로도 시작할 수 있습니다.
• 세 가지 핵심 메서드로 시작할 수 있습니다. 토큰을 확인하는 getMe, 메시지를 읽는 getUpdates, 답장하는 sendMessage입니다.
• 롱 폴링과 웹훅은 상호 배타적입니다. 로컬 테스트에는 폴링을 사용하고, 프로덕션에는 웹훅으로 전환하세요.
• API는 무료이지만, 텔레그램은 다른 사용자에게 초당 약 30개의 메시지, 채팅당 초당 1개의 메시지로 대량 전송을 제한합니다.
• 봇이 스크립트 이상으로 성장하면 라이브러리가 시간을 절약해 줍니다. python-telegram-bot, aiogram 또는 Telegraf를 사용하세요.

텔레그램 봇 API란 무엇인가요?

텔레그램 봇 API는 코드를 봇을 통해 텔레그램에 연결하기 위한 HTTP 기반 인터페이스입니다. 텔레그램의 개발자 소개에 따르면, 봇은 전화번호가 필요 없는 특별한 계정으로, 서버에서 실행되는 코드의 인터페이스 역할을 합니다.

모든 요청은 사용자 계정 대신 봇 토큰으로 인증됩니다. 토큰은 봇을 식별하므로, 비밀번호처럼 취급하고 공개 저장소에 절대 커밋하지 마세요. 텔레그램 문서에는 명확하게 명시되어 있습니다. 토큰을 안전한 곳에 저장하고 공유하지 마세요.

API 자체는 무료입니다. 텔레그램은 출시 이후 봇 API를 무료로 제공해 왔으며, 메시지당 수수료나 생성할 수 있는 봇 수에 제한이 없습니다. 이것이 수많은 커뮤니티 도구, 지원 도우미 및 자동화가 이 API를 기반으로 실행되는 이유입니다. 플랫폼이 처음이라면, 텔레그램 봇 생성 방법 가이드에서 계정 설정 측면을 더 자세히 다루고 있습니다.

1단계: BotFather에서 봇 토큰 받기

텔레그램을 열고 다른 봇을 만들고 관리하는 공식 봇인 @BotFather를 검색하세요. 채팅을 시작하고 /newbot 명령을 보냅니다.

BotFather는 다음 두 가지를 순서대로 요청합니다.

1. 봇의 표시 이름 (예: “첫 API 봇”)
2. bot으로 끝나는 사용자 이름 (예: first_api_demo_bot)

완료하면 BotFather는 123456789:AAExampleTokenStringHere와 같은 API 토큰을 반환합니다. 이 토큰은 이 튜토리얼의 나머지 부분에서 필요한 유일한 자격 증명입니다.

주의: 토큰을 가진 사람은 누구나 봇을 제어할 수 있습니다. 소스 코드에 넣지 말고 환경 변수에 보관하세요. 유출되면 BotFather에게 /revoke를 보내 새 토큰을 받으세요.

2단계: 첫 봇 API 메서드 호출하기

어떤 프로그램도 작성하기 전에 토큰이 작동하는지 확인하세요. getMe 메서드는 봇에 대한 기본 정보를 반환하며 표준 상태 확인 방법입니다. <YOUR_TOKEN>을 BotFather에서 받은 값으로 바꾸세요.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe

성공적인 응답은 "ok": true와 봇의 ID, 이름, 사용자 이름이 포함된 JSON입니다. "ok": false가 표시되면 토큰이 잘못되었거나 오타가 있는 것입니다.

이 단일 요청이 전체 패턴입니다. 모든 텔레그램 봇 API 메서드는 동일한 형태를 따릅니다. https://api.telegram.org/bot<TOKEN>/METHOD_NAME으로 HTTPS 호출을 하고, 쿼리 문자열 또는 POST 본문에 매개변수를 포함하며, JSON 객체를 반환합니다. 전체 목록은 봇 API 참조에 있으며, 필요한 모든 메서드와 객체를 문서화하고 있습니다.

3단계: 메시지 수신 및 전송

이제 봇을 유용하게 만들어 봅시다. 초보자를 놀라게 하는 한 가지 규칙이 있습니다. 봇은 대화를 시작할 수 없습니다. 사용자가 먼저 봇에게 메시지를 보내야 합니다. 그러니 텔레그램에서 봇을 열고 “hello”와 같은 아무 텍스트나 보내세요.

다음으로, 롱 폴링을 사용하여 들어오는 업데이트를 가져오고 업데이트 객체 배열을 반환하는 getUpdates로 해당 메시지를 읽습니다.

curl https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

응답에서 message.chat.id를 찾으세요. 이 chat_id는 답장할 주소입니다. 이를 복사한 다음 sendMessage를 호출합니다.

curl -X POST https://api.telegram.org/bot<YOUR_TOKEN>/sendMessage \
 -d chat_id=<CHAT_ID> \
 -d text="Hello from my first bot"

봇이 채팅에 답장합니다. getUpdates로 읽고 sendMessage로 응답하는 이 왕복 과정은 대부분의 텔레그램 봇 뒤에 있는 핵심 루프입니다. text 매개변수는 메시지당 최대 4096자를 허용하므로, 긴 답장은 분할해야 합니다.

이 텔레그램 봇 API 예제를 실제 코드로 확장할 때 기억해야 할 두 가지 세부 사항:

• 오프셋을 다시 계산하세요. 다음 getUpdates 호출 시 마지막 업데이트의 update_id에 1을 더한 값을 offset 매개변수로 전달해야 합니다. 그렇지 않으면 텔레그램이 동일한 업데이트를 계속 반환합니다.
• 한 번에 하나의 메서드만 사용하세요. 웹훅을 등록하는 순간 getUpdates는 작동을 멈춥니다. 이것이 다음 단계의 주제입니다.

4단계: 롱 폴링 또는 웹훅 선택

텔레그램은 업데이트를 수신하는 두 가지 방법을 제공하며, 봇당 한 번에 하나만 사용할 수 있습니다.

• 롱 폴링은 코드가 getUpdates를 반복적으로 호출하는 것을 의미합니다. 공개 URL이 필요 없고, 계속 실행되는 프로세스만 있으면 되므로 학습 및 로컬 개발에 가장 쉬운 방법입니다.
• 웹훅은 텔레그램이 각 업데이트를 발생 즉시 HTTPS 엔드포인트로 POST 요청으로 푸시하는 것을 의미합니다. 이는 프로덕션 표준입니다. 대기 시간이 짧고, 유휴 폴링이 없으며, 안정적인 트래픽에서 더 잘 확장됩니다.

웹훅으로 전환하려면 공개 HTTPS URL을 한 번 등록하세요.

curl "https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=https://yourdomain.com/webhook"

엔드포인트는 유효한 TLS 인증서가 필요하며 HTTP 200을 빠르게 반환해야 합니다. 업데이트가 도착하지 않으면 항상 오류를 검사하는 것이 첫 번째 조치입니다. 전체 등록, 확인 및 문제 해결 흐름은 텔레그램 봇 웹훅 설정 가이드를 참조하세요. 요약하자면, 개발 중에는 폴링으로 시작하고, 출시 전에 웹훅으로 전환하세요.

5단계: 라이브러리로 API 래핑하기

원시 cURL은 학습에 훌륭하지만, 프로덕션 봇은 라이브러리를 사용합니다. 라이브러리는 API 호출, 업데이트 파싱, 재시도 및 대화 상태를 처리하므로, 봇별 로직만 작성하면 됩니다. 텔레그램은 봇 API 샘플 페이지에서 거의 모든 언어에 대한 커뮤니티 라이브러리를 나열합니다.

이미 알고 있는 언어로 선택하세요.

• Python: python-telegram-bot은 순수 Python이며, 완전 비동기식이고, Python 3.10 이상을 지원합니다. aiogram과 pyTelegramBotAPI는 인기 있는 대안입니다.
• Node.js: Telegraf는 성숙하고 TypeScript 친화적입니다. node-telegram-bot-api는 오랫동안 사용되어 온 옵션입니다.

다음은 텔레그램 봇 API 파이썬 튜토리얼의 가장 일반적인 시작점인 Python으로 작성된 동일한 에코 봇입니다.

from telegram import Update
from telegram.ext import Application, MessageHandler, filters, ContextTypes

TOKEN = "YOUR_TOKEN"

async def echo(update: Update, context: ContextTypes. DEFAULT_TYPE):
 await update.message.reply_text(update.message.text)

app = Application.builder().token(TOKEN).build()
app.add_handler(MessageHandler(filters. TEXT & ~filters. COMMAND, echo))
app.run_polling()

그리고 Telegraf를 사용한 Node.js 버전입니다.

import { Telegraf } from 'telegraf'

const bot = new Telegraf(process.env. BOT_TOKEN)
bot.on('text', (ctx) => ctx.reply(ctx.message.text))
bot.launch()

둘 다 3단계의 cURL 루프와 동일한 작업을 수행하지만, 몇 줄의 코드로 복잡한 부분을 처리해 줍니다. 지원 봇을 프로토타이핑하는 백엔드 개발자 Maria는 cURL 테스트에서 python-telegram-bot으로 하루 만에 전환하여 명령 핸들러와 인라인 버튼을 같은 날 작동시켰습니다. 라이브러리가 동일한 HTTP 메서드 위에 얇은 래퍼이기 때문에 API 개념이 직접적으로 적용되었습니다.

알아야 할 속도 제한 및 할당량

API는 무료이지만 무제한은 아닙니다. 텔레그램의 봇 FAQ는 봇이 제한되지 않도록 하는 지침을 나열합니다.

• 채팅당 초당 한 메시지. 단일 대화에서는 이보다 빠르게 보내지 마세요.
• 여러 사용자에게 보낼 때 총 초당 약 30개의 메시지. 이를 초과하면 HTTP 429 “Too Many Requests” 응답을 받기 시작합니다.
• 동일 그룹에 분당 약 20개의 메시지.

방송이 정말 더 많은 메시지를 필요로 하는 경우, @BotFather에서 유료 방송을 활성화하여 초당 1000개 메시지까지 한도를 높일 수 있습니다. 초당 30개를 초과하는 메시지는 각각 0.1 텔레그램 스타가 부과됩니다. 대부분의 봇은 이 기능이 필요 없지만, 알림 기능을 설계하기 전에 한도가 존재한다는 것을 아는 것이 좋습니다.

텔레그램이 반환하는 retry_after 값을 읽고 해당 시간만큼 일시 중지하여 429 응답을 존중하세요. 라이브러리는 이를 자동으로 처리해 주므로, 트래픽이 실제가 되면 원시 요청에서 벗어나야 하는 또 다른 이유가 됩니다.

코드 없이 AI 봇 만들기: 서버가 필요 없는 방법

모든 프로젝트에 사용자 지정 코드베이스가 필요한 것은 아닙니다. 목표가 텔레그램 그룹의 AI 비서라면, 특히 호스팅, HTTPS 및 웹훅 계층과 같은 봇 API의 복잡한 부분을 직접 유지 관리하고 싶지 않을 수 있습니다.

TeleClaw는 봇을 대신 실행하고 Claude AI를 즉시 연결해 주는 노코드 플랫폼입니다. 그룹에 @claw를 추가하고, BotFather 토큰을 대시보드에 붙여넣고, setWebhook이나 속도 제한 처리 없이 동작을 구성할 수 있습니다. 4,000명 규모의 암호화폐 커뮤니티를 운영하는 Tomas는 반쯤 완성된 사용자 지정 봇을 TeleClaw로 교체하고 같은 날 저녁에 AI 중재 및 FAQ 답변을 활성화했습니다.

기본적으로 동일한 봇 API입니다. 서버 계층을 직접 운영할지, 아니면 플랫폼에 맡길지 선택하는 것입니다. TeleClaw 기능 페이지에서 어떤 기능을 제공하는지 살펴보고, 최고의 텔레그램 봇 모음에서 옵션을 비교해 보세요. 순수 대시보드 빌드의 경우, 노코드 텔레그램 챗봇 가이드를 참조하세요.

결론

이제 텔레그램 봇 API에 대한 작동 방식에 대한 이해를 갖게 되었습니다. BotFather에서 받은 토큰, getMe, getUpdates, sendMessage와 같은 HTTP 메서드, 롱 폴링과 웹훅 사이의 선택, 그리고 봇이 성장하면 모든 것을 래핑할 라이브러리까지 말이죠. API는 무료이고, 잘 문서화되어 있으며, 몇 분 안에 cURL로 테스트할 수 있을 만큼 접근하기 쉽습니다.

가장 빠른 다음 단계는 가장 작은 단계입니다. @BotFather를 열고 /newbot을 실행한 다음, 첫 getMe 요청을 보내 토큰을 확인하세요. 거기서부터 Python이나 Node로 구축하거나, 서버를 완전히 건너뛸 수 있습니다. 며칠이 아닌 몇 분 안에 AI 기반 봇을 출시하려면, 그룹에 @claw를 추가하고 TeleClaw 대시보드에서 구성하세요.