텔레그램 봇 웹훅 설정: 개발자를 위한 완벽 가이드

텔레그램 봇 웹훅 설정은 폴링 루프 대신 메시지가 실시간으로 도착하도록 서버를 텔레그램의 업데이트 스트림에 연결합니다. Bot API로 사용자 지정 봇을 구축하는 경우 웹훅은 표준 프로덕션 경로입니다. 텔레그램은 각 업데이트를 HTTPS 엔드포인트에 POST하고 코드가 응답합니다.

이 가이드는 전제 조건, 등록, 작동하는 핸들러 예제, 확인, 문제 해결, 그리고 자체 호스팅보다 TeleClaw와 같은 관리형 플랫폼이 더 적합한 경우에 대해 설명합니다.

주요 내용

• 웹훅과 롱 폴링은 상호 배타적입니다. 웹훅을 설정하면 제거할 때까지 getUpdates가 비활성화됩니다.
• HTTPS는 필수입니다. 엔드포인트에는 TLS 1.2+ 이상, 일치하는 인증서, 그리고 포트 443, 80, 88 또는 8443이 필요합니다.
• setWebhook으로 등록하고, getWebhookInfo로 확인합니다. 업데이트 흐름이 중단되면 last_error_message를 확인합니다.
• secret_token을 사용하여 요청이 무작위 스캐너가 URL을 공격하는 것이 아니라 텔레그램에서 온 것임을 확인합니다.
• 코드 없는 대안: TeleClaw는 호스팅 및 전달을 처리하므로 서버 계층을 완전히 건너뛸 수 있습니다.

웹훅 vs 롱 폴링: 어떤 것을 선택해야 할까요?

텔레그램은 업데이트를 받는 두 가지 방법을 제공합니다. 봇 FAQ에 따르면 봇당 하나의 메서드를 선택해야 합니다. 동시에 두 가지를 실행할 수 없습니다.

롱 폴링은 프로토타입을 만드는 가장 빠른 방법입니다. 봇은 루프에서 getUpdates를 호출하고, 각 배치를 처리하고, 오프셋을 진행합니다. 도메인, 인증서, 열린 포트가 필요 없습니다.

웹훅은 모델을 뒤집습니다. 누군가 봇에 메시지를 보낼 때마다 텔레그램은 HTTPS POST를 URL로 보냅니다. 이는 유휴 폴링 요청을 제거하고 반응 시간을 단축하여 지원 봇, 결제 흐름, 대규모 그룹 중재에 중요합니다.

아직 봇 자체를 등록 중이라면, 여기에서 계속하기 전에 BotFather에서 토큰을 얻기 위한 텔레그램 봇 생성 가이드를 참조하세요.

텔레그램 봇 웹훅 설정을 위한 전제 조건

setWebhook을 호출하기 전에 인프라가 공식 웹훅 가이드의 텔레그램 요구 사항을 충족하는지 확인하세요.

• @BotFather에서 받은 봇 토큰 (위에 링크된 봇 생성 가이드 참조).
• 유효한 TLS 인증서가 있는 공개 도메인. 자체 서명된 인증서는 certificate 매개변수를 통해 공개 키를 업로드하는 경우에만 작동합니다.
• 서버의 지원되는 포트: 443 (기본값), 80, 88 또는 8443. 다른 포트는 거부됩니다.
• 인증서 CN 또는 SAN은 웹훅 URL의 도메인과 일치해야 합니다. 와일드카드 인증서는 작동하지 않을 수 있습니다. 리디렉션은 지원되지 않습니다.
• 텔레그램 서브넷 149.154.160.0/20 및 91.108.4.0/22에서 인바운드 POST 액세스.

로컬 개발의 경우, 터널(ngrok, Cloudflare Tunnel 또는 유사한)을 통해 localhost를 노출하여 공개 HTTPS URL을 제공합니다. 웹훅을 등록하기 전에 터널이 POST 요청에 대해 HTTP 200을 반환하는지 테스트하세요.

1단계: 웹훅 엔드포인트 구축

서버에는 POST 요청을 수락하고, JSON Update 객체를 구문 분석하고, HTTP 200을 빠르게 반환하는 경로가 필요합니다. 느린 핸들러는 텔레그램이 재시도하고 결국 getWebhookInfo에 오류를 보고하게 합니다.

Express를 사용한 최소 Node.js 예제:

import express from 'express';

const app = express();
app.use(express.json());

const SECRET = process.env. WEBHOOK_SECRET;

app.post('/webhook', (req, res) => {
 if (SECRET && req.get('X-Telegram-Bot-Api-Secret-Token')!== SECRET) {
 return res.sendStatus(403);
 }

 const update = req.body;
 // update.message, update.callback_query 등을 처리합니다.
 console.log('Update ID:', update.update_id);

 res.sendStatus(200);
});

app.listen(443);

Flask를 사용한 Python도 동일한 패턴을 따릅니다. request에서 JSON을 읽고, 구성된 경우 비밀 헤더를 확인하고, 업데이트를 처리하고, 200을 반환합니다.

빠르게 응답하세요. 무거운 작업(데이터베이스 쓰기, AI API 호출)은 백그라운드 큐로 보내야 합니다. 텔레그램은 빠른 승인을 기대합니다. Bot API 웹훅 노트에 설명된 대로 별도의 API 호출을 하는 대신 method 필드가 있는 JSON 본문을 반환하여 인라인으로 회신할 수도 있습니다.

2단계: setWebhook으로 텔레그램 봇 웹훅 구성

엔드포인트가 활성화되면 Bot API에 등록합니다. <TOKEN>과 URL을 자신의 값으로 바꿉니다.

curl 사용:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -H "Content-Type: application/json" \
 -d '{
 "url": "https://yourdomain.com/webhook",
 "secret_token": "my_random_secret_abc123",
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"],
 "drop_pending_updates": false
 }'

매개변수 참조:

• url (필수): HTTPS 엔드포인트. 웹훅을 제거하려면 빈 문자열을 사용합니다.
• secret_token (선택 사항): 1-256자 (A-Z, a-z, 0-9, _, -). 텔레그램은 X-Telegram-Bot-Api-Secret-Token 헤더에 이를 보냅니다.
• max_connections (선택 사항): 1-100개의 동시 연결. 기본값은 40입니다.
• allowed_updates (선택 사항): 수신할 업데이트 유형을 제한합니다. 메시지만 처리하는 경우 페이로드 크기를 줄입니다.
• drop_pending_updates (선택 사항): 웹훅을 전환할 때 대기 중인 업데이트를 삭제하려면 true로 설정합니다.
• certificate (선택 사항): 자체 서명된 인증서의 공개 키 파일을 업로드합니다.

성공적인 응답은 {"ok":true,"result":true,"description":"Webhook was set"}과 같습니다.

3단계: getWebhookInfo로 확인

항상 즉시 등록을 확인하세요. 업데이트가 도착하지 않을 때 첫 번째 문제 해결 도구입니다.

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

예시 응답:

{
 "ok": true,
 "result": {
 "url": "https://yourdomain.com/webhook",
 "has_custom_certificate": false,
 "pending_update_count": 0,
 "max_connections": 40,
 "allowed_updates": ["message", "callback_query", "chat_join_request"]
 }
}

다음 필드를 확인하세요.

• url: 비어 있으면 웹훅이 활성화되지 않았음을 의미합니다 (봇은 롱 폴링 중).
• pending_update_count: 전달을 기다리는 대기 중인 업데이트. 숫자가 증가하면 전달 실패를 나타냅니다.
• last_error_date 및 last_error_message: 가장 최근의 실패 원인. 근본 원인을 수정하면 텔레그램이 자동으로 재시도합니다.
• ip_address: 현재 엔드포인트를 공격하는 텔레그램 IP.

실제 텔레그램 계정에서 봇에게 테스트 메시지를 보냅니다. pending_update_count가 0으로 유지되고 서버 로그에 POST가 표시되면 텔레그램 봇 웹훅 설정이 작동하는 것입니다.

텔레그램 봇 웹훅 예제: 가입 요청 핸들러

가입 요청 봇(Guardian 스타일 입장 흐름)에는 chat_join_request 업데이트 유형이 필요합니다. Guardian 봇 가이드는 제품 측면을 다룹니다. 다음은 웹훅 연결입니다.

가입 요청이 활성화된 상태로 등록:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
 -d "url=https://yourdomain.com/webhook" \
 -d "allowed_updates=[\"chat_join_request\",\"message\"]"

핸들러 로직 (의사 코드):

if (update.chat_join_request) {
 const { chat, from, invite_link } = update.chat_join_request;
 // 심사 로직을 실행한 다음 Bot API를 통해 승인 또는 거부
 await approveChatJoinRequest(chat.id, from.id);
}

텔레그램은 가입 요청을 푸시 업데이트로 전달하므로 웹훅은 요청이 만료되기 전에 응답해야 하는 입장 봇에 자연스럽게 적합합니다.

텔레그램 봇 웹훅 제거 및 폴링으로 다시 전환

getUpdates로 로컬에서 디버깅해야 하나요? 먼저 웹훅을 제거하세요.

옵션 A: deleteWebhook 사용:

curl -X POST "https://api.telegram.org/bot<TOKEN>/deleteWebhook" \
 -d "drop_pending_updates=true"

옵션 B: setWebhook과 빈 URL 사용:

curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url="

두 가지 방법 모두 롱 폴링을 다시 활성화합니다. 이 단계를 건너뛰면 웹훅이 여전히 프로덕션 URL에 등록되어 있으므로 getUpdates는 아무것도 반환하지 않습니다.

일반적인 웹훅 오류 문제 해결

getWebhookInfo에 오류가 표시되면 메시지를 수정 사항과 일치시킵니다.

프로덕션 환경에서 getWebhookInfo를 정기적으로 실행하세요. last_error_message를 조기에 감지하면 몇 시간 동안의 조용한 메시지 손실을 방지할 수 있습니다.

서버 건너뛰기: TeleClaw를 사용한 관리형 봇

모든 봇이 사용자 지정 웹훅 인프라를 필요로 하는 것은 아닙니다. 그룹 또는 비즈니스 채널을 위한 AI 비서가 목표라면 호스팅 및 업데이트 전달은 해결된 문제입니다.

TeleClaw는 BotFather 토큰을 OpenClaw 기반의 관리형 런타임에 연결합니다. 대시보드에서 성격, 지식 기반 및 중재 규칙을 구성합니다. 플랫폼은 HTTPS 엔드포인트, 스케일링 및 AI 모델 라우팅을 처리합니다. 그룹 관리자로 @claw를 추가하고 웹훅 핸들러를 작성하지 않고도 라이브로 전환할 수 있습니다.

TeleClaw 기능 페이지에서 관리형 봇이 무엇을 할 수 있는지 알아보세요. 전체 코드 없는 워크스루는 코드 없는 텔레그램 챗봇 가이드를 참조하세요.

사용자 지정 웹훅은 독점 백엔드, 규제된 데이터 상주 또는 비표준 업데이트 처리와 같이 완전한 제어가 필요할 때 여전히 유용합니다. 다른 모든 경우에 인증서 관리, 모니터링 및 재시도 처리의 운영 비용은 빠르게 증가합니다.

결론

텔레그램 봇 웹훅 설정은 HTTPS 엔드포인트 배포, setWebhook 호출, getWebhookInfo로 확인, 오류 모니터링의 네 가지 단계로 요약됩니다. 요청 유효성 검사를 위해 secret_token을 사용하고, 처리하는 내용으로 allowed_updates를 제한하며, 핸들러를 빠르게 유지하세요.

서버를 실행하지 않고 프로덕션 푸시 전달을 원하는 개발자는 대신 TeleClaw를 사용할 수 있습니다. 토큰을 붙여넣고 AI 동작을 구성하며 업데이트가 어떻게 도착하는지보다 봇이 무엇을 말하는지에 집중하세요.

웹훅 관리 없이 AI 봇을 출시할 준비가 되셨나요? 텔레그램 그룹에 @claw 추가 →