Telegram Bot API

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

· 8 분 분량

n8n 텔레그램 연동에 텔레그램 쪽에서 필요한 것은 봇 토큰 하나뿐입니다. 토큰을 n8n의 Telegram credential에 Access Token으로 저장한 다음, 메시지가 들어오면 워크플로를 시작하는 Telegram Trigger 노드와 chat id로 메시지를 보내는 Telegram 노드를 쓰면 됩니다. 트리거는 Bot API 웹훅으로 동작하므로 n8n 인스턴스가 공개 HTTPS URL로 접속 가능해야 합니다. 이 글에서는 설정 절차, 셀프 호스팅 n8n에 필요한 구성, 가장 자주 만나는 오류를 차례로 설명합니다.

n8n 텔레그램 연동의 동작 방식

노드하는 일내부에서 쓰는 Bot API공개 HTTPS 필요?
Telegram Trigger메시지, 버튼 클릭, 채널 게시물 등 업데이트가 오면 워크플로 시작setWebhook 후 텔레그램이 n8n으로 업데이트를 POST필요
Telegram메시지 전송·수정, 파일 전송, 콜백 쿼리 응답, 채팅 정보 조회sendMessage, sendPhoto, editMessageText, answerCallbackQuery…불필요, 나가는 요청만

트리거가 웹훅을 쓰기 때문에 Bot API의 웹훅 규칙이 n8n에도 그대로 적용됩니다. HTTPS만 허용되고, 포트는 443, 80, 88, 8443 중 하나여야 하며, 봇당 웹훅 URL은 하나이고, 웹훅이 설정된 동안에는 getUpdates를 쓸 수 없습니다.

1단계: 봇을 만들고 토큰 받기

  1. @BotFather를 열고 /newbot을 보낸 뒤 표시 이름과 bot으로 끝나는 사용자명을 정합니다.
  2. BotFather가 알려 주는 토큰을 복사합니다. 123456789:AAEexampleTokenReplaceWithYours 같은 형태입니다. 기존 봇이라면 /mybots → 봇 선택 → API Token에서 확인합니다.
  3. 어딘가에 붙여 넣기 전에 토큰을 확인합니다.
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"

올바른 토큰이면 봇 정보와 함께 "ok": true가, 잘못된 토큰이면 401 Unauthorized가 반환됩니다. 같은 확인을 Bot API Tester의 getMe에서도 할 수 있습니다. 토큰 찾기, 확인, 폐기 방법은 텔레그램 봇 토큰 가이드에 자세히 나와 있고, 아직 봇이 없다면 텔레그램 봇 만들기부터 진행하십시오.

2단계: n8n에 Telegram credential 추가하기

n8n은 봇 토큰만으로 텔레그램에 인증합니다. 새 Telegram credential을 만들고 Access Token 필드에 토큰을 붙여 넣으십시오. Telegram 노드와 Telegram Trigger 노드는 같은 credential 유형을 쓰므로 봇당 credential 하나면 충분합니다.

토큰은 비밀번호처럼 다뤄야 합니다. 토큰을 가진 사람은 누구나 봇을 제어할 수 있습니다. 유출되면 @BotFather에서 폐기하고 n8n의 credential을 갱신하십시오.

3단계: n8n Telegram Trigger 웹훅으로 업데이트 받기

Telegram Trigger 노드를 추가하고 credential을 선택한 뒤 워크플로를 시작할 업데이트 종류를 고릅니다. 들어오는 메시지에는 Message, 인라인 버튼 클릭에는 Callback Query를 고르는 경우가 많습니다. *는 채팅 멤버 업데이트와 리액션 업데이트를 제외한 모든 업데이트를 뜻하며, Bot API 기본값과 같습니다. 특정 chat id나 user id로 범위를 제한할 수 있고, 첨부된 이미지와 파일을 내려받게 할 수도 있습니다.

워크플로를 테스트하거나 게시하면 n8n이 자기 인스턴스의 URL로 봇의 setWebhook을 호출합니다. 그때부터 텔레그램은 모든 업데이트를 n8n으로 HTTPS POST합니다. 여기서 두 가지 결과가 생깁니다.

셀프 호스팅 n8n을 HTTPS로 공개하기

n8n Cloud에는 이미 공개 HTTPS 주소가 있습니다. 셀프 호스팅 인스턴스는 자신의 프로토콜, 호스트, 포트로 웹훅 URL을 만드는데, 리버스 프록시 뒤나 localhost에서는 대개 텔레그램이 거부하는 http:// 주소가 됩니다. 해결 방법은 다음과 같습니다.

  1. n8n 앞에 유효한 인증서로 443 포트에서 TLS를 처리하는 리버스 프록시(nginx, Caddy, Traefik 등)를 둡니다.
  2. n8n에 공개 주소를 알려 줍니다. 현재 n8n 버전은 N8N_WEBHOOK_URL을 쓰며, 예전 WEBHOOK_URL은 n8n 2.35.0부터 deprecated지만 여전히 읽힙니다. 2.30.0 이전 버전은 WEBHOOK_URL만 인식합니다.
  3. N8N_PROXY_HOPS=1을 설정하고 프록시에서 X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto 헤더를 전달합니다.
  4. WebSocket 프록시를 켭니다. 그렇지 않으면 테스트 트리거 이벤트를 기다리는 동안 에디터가 멈춘 것처럼 보일 수 있습니다.
  5. n8n을 재시작하고 워크플로를 다시 활성화해 트리거가 새 HTTPS URL을 등록하게 합니다.
# https://n8n.example.com을 제공하는 리버스 프록시 뒤의 n8n
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# n8n 2.30.0 이전 버전: 대신 WEBHOOK_URL 사용
# export WEBHOOK_URL=https://n8n.example.com/

로컬 개발에서는 공개 HTTPS 호스트명을 주는 터널을 같은 방식으로 쓸 수 있습니다. 그 호스트명을 N8N_WEBHOOK_URL에 넣으면 됩니다. 다만 터널 주소가 바뀔 때마다 웹훅이 끊긴다는 점을 기억하십시오.

텔레그램에 등록된 봇의 웹훅 확인하기

트리거가 반응하지 않으면 getWebhookInfo로 텔레그램에 직접 물어보십시오. 등록된 URL, 대기 중인 업데이트 수, 마지막 전달 오류를 보여 줍니다. 다음 스크립트는 간단한 진단 결과를 출력합니다.

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]  # n8n credential과 같은 토큰
API = f"https://api.telegram.org/bot{TOKEN}"

data = requests.get(f"{API}/getWebhookInfo", timeout=10).json()
if not data["ok"]:
    raise SystemExit(f"{data['error_code']} {data['description']}")  # 401: 잘못된 토큰

info = data["result"]
print("웹훅 URL:", info["url"] or "(없음: 활성화된 Telegram Trigger 없음)")
print("대기 중인 업데이트:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
    print("문제: 텔레그램에는 HTTPS URL이 필요합니다")
if "last_error_message" in info:
    print("마지막 전달 오류:", info["last_error_message"])
const TOKEN = process.env.BOT_TOKEN; // n8n credential과 같은 토큰
const API = `https://api.telegram.org/bot${TOKEN}`;

const data = await (await fetch(`${API}/getWebhookInfo`)).json();
if (!data.ok) {
  console.error(`${data.error_code} ${data.description}`); // 401: 잘못된 토큰
  process.exit(1);
}

const info = data.result;
console.log("웹훅 URL:", info.url || "(없음: 활성화된 Telegram Trigger 없음)");
console.log("대기 중인 업데이트:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
  console.log("문제: 텔레그램에는 HTTPS URL이 필요합니다");
}
if (info.last_error_message) {
  console.log("마지막 전달 오류:", info.last_error_message);
}

JavaScript 버전은 check.mjs로 저장해 Node.js 18 이상에서 실행합니다. 결과는 이렇게 해석합니다. 다른 서비스의 URL이 보이면 다른 무언가가 봇의 웹훅을 가져간 것이고, pending_update_count가 늘면서 last_error_message가 있다면 텔레그램이 n8n에 접속하지 못하거나 n8n이 오류로 응답하고 있는 것입니다. 코드 없이 확인하려면 Bot API Tester의 getWebhookInfo를 쓰십시오.

4단계: n8n에서 텔레그램 메시지 보내기

Telegram 노드를 추가하고 Message 리소스와 Send Message 작업을 고른 뒤, credential을 선택하고 두 필드를 채웁니다.

사람들이 자주 놀라는 기본값이 두 가지 있습니다. 노드는 This message was sent automatically with n8n이라는 줄을 덧붙이는데, 추가 필드의 Append n8n Attribution을 끄면 없어집니다. 또 노드의 parse mode 기본값이 HTML이므로, 동적 텍스트의 <, >, &는 &lt;, &gt;, &amp;로 이스케이프해야 합니다. 그렇지 않으면 텔레그램이 can't parse entities 오류로 메시지를 거부합니다.

워크플로에 chat id를 연결하기 전에 Bot API Tester의 sendMessage에서 요청 한 번으로 동작을 확인할 수 있습니다. 채널에 게시하려면 먼저 봇을 채널 관리자로 추가하십시오. 텔레그램은 대량 전송 시 초당 약 30개, 한 채팅에는 초당 약 1개의 메시지를 허용하므로 일괄 발송 루프에는 속도 조절을 넣으십시오. 자세한 내용은 텔레그램 Bot API 제한에 있습니다.

chat id 찾기

가장 쉬운 방법은 트리거 자체를 이용하는 것입니다. 워크플로를 실행하고 봇에게 메시지를 보낸 뒤 트리거 출력에서 message.chat.id를 읽으십시오. 사용자는 양수, 그룹은 음수이고, 슈퍼그룹과 채널은 -1001234567890 형태입니다. getUpdates를 쓰고 싶다면 이 봇의 Telegram Trigger가 활성화되기 전에 호출하십시오. 웹훅이 설정된 동안에는 409 Conflict로 실패합니다. 그룹, 채널, 포럼 토픽을 포함한 모든 방법은 텔레그램 chat id 확인방법에 정리되어 있습니다.

n8n 텔레그램 오류 해결

증상원인해결
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n이 http:// URL을 등록함: localhost 또는 TLS 없는 프록시프록시에서 TLS를 처리하고 N8N_WEBHOOK_URL(또는 WEBHOOK_URL)을 HTTPS 주소로 설정
포트 관련 bad webhook 오류공개 URL이 443, 80, 88, 8443 이외의 포트를 사용프록시를 통해 n8n을 443 포트로 공개
getUpdates에서 409 ConflictTelegram Trigger가 웹훅을 등록해 두고 있음워크플로를 비활성화하고 deleteWebhook 호출, 또는 chat id는 트리거에서 확인
워크플로가 테스트에서만 또는 게시 상태에서만 동작테스트용과 운영용 웹훅 URL이 서로 덮어씀테스트 중에는 게시 해제, 또는 테스트용 봇을 따로 사용
다른 워크플로를 활성화한 뒤 트리거가 멈춤두 번째 트리거나 다른 서비스가 같은 토큰으로 setWebhook을 호출함봇당 트리거 하나, getWebhookInfo로 URL 확인
에디터가 “waiting for trigger event” 상태로 멈춤리버스 프록시가 WebSocket을 지원하지 않음WebSocket 프록시를 켜고 워크플로를 다시 열기
그룹 메시지 업데이트가 오지 않음프라이버시 모드: 그룹에서는 봇을 향한 명령어, 봇에 대한 답장, 서비스 메시지만 받음/setprivacy로 프라이버시 모드를 끄거나 봇을 관리자로 지정
401 Unauthorizedcredential의 토큰이 잘못되었거나 폐기됨getMe로 확인하고 현재 토큰을 붙여 넣기
전송 시 400 Bad Request: chat not foundchat id가 틀렸거나, 사용자가 봇을 시작하지 않았거나 봇이 그룹에 없어 접근할 수 없는 채팅ID를 다시 확인하고, 사용자가 /start를 보내게 하거나 봇을 그룹에 추가

처음부터 깨끗한 상태로 시작하려면 워크플로를 비활성화하고 deleteWebhook을 호출한 뒤, getWebhookInfo의 url이 비어 있는지 확인하고 워크플로를 다시 활성화해 n8n이 URL을 새로 등록하게 하십시오. 시크릿 토큰, 재시도, 인증서 등 웹훅 동작 전반은 텔레그램 웹훅 설정 가이드를 참고하십시오.

자주 묻는 질문

n8n과 텔레그램은 어떻게 연결하나요?

@BotFather로 봇을 만들어 토큰을 복사하고, n8n에서 Telegram credential의 Access Token으로 저장합니다. 메시지를 받을 때는 Telegram Trigger 노드를, 보낼 때는 Telegram 노드를 쓰며 두 노드가 같은 credential을 사용합니다.

n8n Telegram Trigger에서 “An HTTPS URL must be provided for webhook” 오류가 납니다.

트리거는 setWebhook으로 웹훅을 등록하는데, 텔레그램은 공개 HTTPS URL만 받습니다. n8n이 http://localhost나 TLS가 없는 프록시 뒤에서 실행 중이라면 인스턴스의 공개 HTTPS 주소를 N8N_WEBHOOK_URL(구버전은 WEBHOOK_URL)에 설정하고 리버스 프록시에서 TLS를 처리하십시오.

n8n 워크플로 두 개에서 같은 텔레그램 봇 트리거를 쓸 수 있나요?

안정적으로는 불가능합니다. 봇의 웹훅 URL은 하나뿐이라 활성화할 때마다 이전 URL을 덮어쓰고, 마지막 워크플로만 업데이트를 받습니다. 봇당 트리거를 하나만 두고 한 워크플로 안에서 분기하거나 봇을 따로 만드십시오.

n8n을 설정한 뒤 getUpdates가 409 Conflict를 반환하는 이유는 무엇인가요?

활성화된 Telegram Trigger가 봇에 웹훅을 등록해 두고 있고, 웹훅이 설정된 동안에는 getUpdates가 동작하지 않습니다. 폴링이 필요하면 워크플로를 비활성화하고 deleteWebhook을 호출하거나, chat id는 트리거 출력에서 확인하십시오.

n8n에서 텔레그램 메시지를 보내기만 할 때도 공개 HTTPS URL이 필요한가요?

아닙니다. Telegram 노드는 api.telegram.org로 나가는 요청만 보내므로 로컬 n8n에서도 전송이 됩니다. 공개 HTTPS는 Telegram Trigger로 업데이트를 받을 때만 필요합니다.

n8n Telegram 노드에 넣을 chat id는 어디서 찾나요?

트리거 출력(message.chat.id)에서 가져오거나, 트리거를 활성화하기 전에 봇에게 메시지를 보내고 getUpdates를 호출합니다. 공개 채널은 @channelusername도 쓸 수 있습니다.

텔레그램 봇 만들기: @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 처리를 예제로 설명합니다.

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

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

텔레그램 봇 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 검증까지 다룹니다.