Telegram Bot API

Tích hợp n8n với Telegram: kết nối bot, kích hoạt workflow và gửi tin nhắn

· 8 phút đọc

Để kết nối n8n với Telegram, bạn chỉ cần một thứ từ phía Telegram: token của bot. Lưu token vào trường Access Token của credential Telegram trong n8n, sau đó dùng node Telegram Trigger để chạy workflow khi có tin nhắn đến và node Telegram để gửi tin nhắn tới một chat id. Trigger hoạt động qua webhook của Bot API, nên instance n8n phải truy cập được qua URL HTTPS công khai. Bài này hướng dẫn cài đặt, cấu hình cần thiết cho n8n tự host và các lỗi hay gặp nhất.

Tích hợp n8n Telegram hoạt động thế nào

NodeChức năngBot API phía sauCần HTTPS công khai?
Telegram TriggerChạy workflow khi có update: tin nhắn, lượt bấm nút, bài đăng trong kênh…setWebhook, sau đó Telegram POST update tới n8nCó
TelegramGửi và sửa tin nhắn, gửi file, trả lời callback query, đọc thông tin chatsendMessage, sendPhoto, editMessageText, answerCallbackQuery…Không, chỉ gửi request ra ngoài

Vì trigger dùng webhook, mọi quy tắc webhook của Bot API cũng áp dụng cho n8n: chỉ HTTPS, cổng 443, 80, 88 hoặc 8443, mỗi bot một URL webhook, và không dùng được getUpdates khi webhook đang bật.

Bước 1: tạo bot và lấy token

  1. Mở @BotFather, gửi /newbot, chọn tên hiển thị và username kết thúc bằng bot.
  2. Copy token mà BotFather trả về, có dạng 123456789:AAEexampleTokenReplaceWithYours. Với bot có sẵn, mở /mybots → chọn bot → API Token.
  3. Kiểm tra token trước khi dán vào bất cứ đâu:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"

Token hợp lệ trả về "ok": true kèm thông tin bot; token sai trả về 401 Unauthorized. Bạn có thể kiểm tra tương tự bằng getMe trong Bot API Tester. Cách tìm, kiểm tra và thu hồi token có trong bài cách lấy token bot Telegram; nếu chưa có bot, hãy bắt đầu với bài cách tạo bot Telegram.

Bước 2: thêm credential Telegram trong n8n

n8n xác thực với Telegram chỉ bằng token bot. Tạo một credential Telegram mới và dán token vào trường Access Token. Node Telegram và node Telegram Trigger dùng cùng loại credential, nên mỗi bot chỉ cần một credential.

Hãy giữ token như mật khẩu: ai có token là điều khiển được bot. Nếu bị lộ, thu hồi trong @BotFather rồi cập nhật credential trong n8n.

Bước 3: nhận update bằng webhook của n8n Telegram Trigger

Thêm node Telegram Trigger, chọn credential và chọn loại update sẽ kích hoạt workflow. Lựa chọn thường gặp là Message cho tin nhắn đến và Callback Query cho lượt bấm inline button; * nghĩa là mọi update trừ update thành viên chat và reaction, khớp với mặc định của Bot API. Node cũng có thể giới hạn theo chat id hoặc user id cụ thể, và tải về ảnh, file đính kèm.

Khi bạn chạy thử hoặc publish workflow, n8n gọi setWebhook cho bot với một URL thuộc instance của mình. Từ đó Telegram gửi mọi update tới n8n bằng HTTPS POST. Điều này dẫn đến hai hệ quả:

Đưa n8n tự host ra ngoài qua HTTPS

n8n Cloud đã có sẵn địa chỉ HTTPS công khai. Instance tự host thì tạo URL webhook từ chính giao thức, host và cổng của nó — sau reverse proxy hoặc trên localhost thường là địa chỉ http://, và Telegram sẽ từ chối. Cách khắc phục:

  1. Đặt n8n sau một reverse proxy (nginx, Caddy, Traefik…) xử lý TLS bằng chứng chỉ hợp lệ trên cổng 443.
  2. Cho n8n biết địa chỉ công khai của nó. Các bản n8n hiện tại dùng N8N_WEBHOOK_URL; biến cũ WEBHOOK_URL đã deprecated từ n8n 2.35.0 nhưng vẫn được đọc, còn các bản trước 2.30.0 chỉ biết WEBHOOK_URL.
  3. Đặt N8N_PROXY_HOPS=1 và cho proxy chuyển tiếp các header X-Forwarded-For, X-Forwarded-Host và X-Forwarded-Proto.
  4. Bật proxy cho WebSocket, nếu không editor có thể như bị treo khi chờ sự kiện trigger lúc test.
  5. Khởi động lại n8n và kích hoạt lại workflow để trigger đăng ký URL HTTPS mới.
# n8n chạy sau reverse proxy phục vụ https://n8n.example.com
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# n8n bản trước 2.30.0: dùng WEBHOOK_URL thay thế
# export WEBHOOK_URL=https://n8n.example.com/

Khi phát triển local, một tunnel cấp hostname HTTPS công khai cũng hoạt động y như vậy: đặt hostname đó vào N8N_WEBHOOK_URL. Lưu ý webhook sẽ hỏng mỗi khi địa chỉ tunnel thay đổi.

Kiểm tra Telegram đang lưu webhook nào cho bot

Khi trigger im lặng, hãy hỏi thẳng Telegram bằng getWebhookInfo. Phương thức này cho biết URL đã đăng ký, số update đang chờ và lỗi giao update gần nhất. Script sau in ra chẩn đoán ngắn gọn:

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]  # cùng token với credential trong n8n
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: sai token

info = data["result"]
print("URL webhook:", info["url"] or "(không có: không có Telegram Trigger nào đang bật)")
print("Update đang chờ:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
    print("Lỗi: Telegram cần URL HTTPS")
if "last_error_message" in info:
    print("Lỗi giao update gần nhất:", info["last_error_message"])
const TOKEN = process.env.BOT_TOKEN; // cùng token với credential trong n8n
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: sai token
  process.exit(1);
}

const info = data.result;
console.log("URL webhook:", info.url || "(không có: không có Telegram Trigger nào đang bật)");
console.log("Update đang chờ:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
  console.log("Lỗi: Telegram cần URL HTTPS");
}
if (info.last_error_message) {
  console.log("Lỗi giao update gần nhất:", info.last_error_message);
}

Lưu bản JavaScript thành check.mjs và chạy bằng Node.js 18 trở lên. Cách đọc kết quả: URL thuộc một dịch vụ khác nghĩa là có thứ khác đã chiếm webhook của bot; pending_update_count tăng dần kèm last_error_message nghĩa là Telegram không kết nối được tới n8n hoặc n8n trả về lỗi. Không muốn viết code thì dùng getWebhookInfo trong Bot API Tester.

Bước 4: gửi tin nhắn Telegram từ n8n

Thêm node Telegram, chọn resource Message và operation Send Message, chọn credential rồi điền hai trường:

Có hai mặc định hay khiến người dùng bất ngờ. Node tự thêm dòng This message was sent automatically with n8n; tắt Append n8n Attribution trong phần additional fields để bỏ dòng này. Ngoài ra parse mode mặc định của node là HTML, nên trong văn bản động phải escape <, > và & thành &lt;, &gt; và &amp;, nếu không Telegram sẽ từ chối tin nhắn với lỗi can't parse entities.

Trước khi đưa chat id vào workflow, bạn có thể kiểm tra bằng một request trong sendMessage trên Bot API Tester. Muốn đăng vào kênh, hãy thêm bot làm admin kênh trước. Telegram cho phép khoảng 30 tin nhắn mỗi giây khi gửi hàng loạt và khoảng một tin mỗi giây trong một chat, nên hãy giãn tốc độ các vòng lặp broadcast; xem bài giới hạn của Telegram Bot API.

Tìm chat id

Nguồn dễ nhất là chính trigger: chạy workflow, nhắn tin cho bot rồi đọc message.chat.id trong output của trigger. Người dùng có id dương, nhóm thường có id âm, còn supergroup và kênh có dạng -1001234567890. Nếu thích dùng getUpdates, hãy gọi trước khi bật bất kỳ Telegram Trigger nào cho bot này; khi webhook đang bật, nó sẽ lỗi 409 Conflict. Mọi cách lấy chat id, kể cả cho nhóm, kênh và topic diễn đàn, có trong bài chat id Telegram lấy ở đâu.

Sửa lỗi n8n Telegram thường gặp

Triệu chứngNguyên nhânCách sửa
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n đã đăng ký URL http://: localhost hoặc proxy không có TLSXử lý TLS ở proxy và đặt N8N_WEBHOOK_URL (hoặc WEBHOOK_URL) thành địa chỉ HTTPS
Lỗi bad webhook liên quan đến cổngURL công khai dùng cổng khác 443, 80, 88 hoặc 8443Đưa n8n ra cổng 443 qua proxy
409 Conflict khi gọi getUpdatesTelegram Trigger đang giữ webhookTắt workflow và gọi deleteWebhook, hoặc lấy chat id từ trigger
Workflow chỉ chạy khi test hoặc chỉ chạy khi đã publishURL webhook test và production thay thế nhauUnpublish khi test hoặc dùng bot test riêng
Trigger ngừng chạy sau khi bật một workflow khácTrigger thứ hai, hoặc dịch vụ khác, đã gọi setWebhook với cùng tokenMỗi bot một trigger; kiểm tra URL bằng getWebhookInfo
Editor treo ở “waiting for trigger event”Reverse proxy không hỗ trợ WebSocketBật proxy WebSocket rồi mở lại workflow
Không nhận được tin nhắn trong nhómPrivacy mode: trong nhóm bot chỉ nhận lệnh dành cho nó, tin trả lời nó và tin nhắn dịch vụTắt privacy bằng /setprivacy hoặc cho bot làm admin
401 UnauthorizedToken trong credential sai hoặc đã bị thu hồiKiểm tra bằng getMe và dán token hiện tại
400 Bad Request: chat not found khi gửiSai chat id, hoặc bot không truy cập được chat: người dùng chưa từng bấm start, hoặc bot chưa ở trong nhómKiểm tra lại id; nhờ người dùng gửi /start hoặc thêm bot vào nhóm

Muốn làm lại từ đầu, hãy tắt workflow, gọi deleteWebhook, kiểm tra getWebhookInfo trả về url rỗng, rồi bật lại workflow để n8n đăng ký URL mới. Cơ chế webhook nói chung (secret token, gửi lại, chứng chỉ) có trong bài webhook Telegram bot.

Câu hỏi thường gặp

Làm sao kết nối Telegram với n8n?

Tạo bot bằng @BotFather, copy token và lưu vào trường Access Token của một credential Telegram trong n8n. Dùng node Telegram Trigger để nhận tin nhắn và node Telegram để gửi; cả hai node dùng chung credential đó.

Vì sao Telegram Trigger của n8n báo “An HTTPS URL must be provided for webhook”?

Trigger đăng ký webhook bằng setWebhook, mà Telegram chỉ chấp nhận URL HTTPS công khai. Nếu n8n chạy ở http://localhost hoặc sau proxy không có TLS, hãy đặt địa chỉ HTTPS công khai của instance vào N8N_WEBHOOK_URL (WEBHOOK_URL ở bản cũ) và xử lý TLS ở reverse proxy.

Hai workflow n8n có dùng chung trigger của một bot Telegram được không?

Không ổn định. Mỗi bot chỉ có đúng một URL webhook, nên mỗi lần kích hoạt sẽ ghi đè lần trước và chỉ workflow cuối cùng nhận được update. Hãy dùng một trigger cho mỗi bot, rẽ nhánh trong cùng một workflow, hoặc tạo bot riêng.

Vì sao getUpdates trả về 409 Conflict sau khi cài n8n?

Telegram Trigger đang hoạt động sẽ giữ webhook của bot, và getUpdates không chạy khi webhook đang bật. Nếu cần polling, hãy tắt workflow và gọi deleteWebhook, hoặc lấy chat id từ output của trigger.

Chỉ gửi tin nhắn Telegram từ n8n thì có cần URL HTTPS công khai không?

Không. Node Telegram chỉ gửi request ra ngoài tới api.telegram.org, nên n8n chạy local vẫn gửi được. HTTPS công khai chỉ cần khi nhận update bằng Telegram Trigger.

Lấy chat id cho node Telegram trong n8n ở đâu?

Lấy từ output của trigger (message.chat.id), hoặc nhắn tin cho bot rồi gọi getUpdates trước khi bật trigger. Kênh công khai cũng nhận @channelusername.

Cách tạo bot Telegram từ A đến Z: BotFather, token và tin nhắn đầu tiên

Tạo bot Telegram miễn phí với @BotFather: chọn username, lấy token, kiểm tra bằng getMe, tìm chat id và gửi tin nhắn đầu tiên bằng curl, Python.

Cách deploy bot Telegram: VPS, Docker và hosting serverless

Cách deploy bot Telegram: chọn polling hay webhook, chạy service systemd trên VPS, Docker, Cloudflare Workers với secret_token và checklist lên production.

Telegram Bot API 10.0–10.5: cài đặt bot, widget, rich message, tin nhắn ephemeral, guest mode và hơn thế

Tổng hợp thay đổi Telegram Bot API 10.0–10.5: setMySettings, BotFullInfo, widget HTML, rich message, tin nhắn ephemeral, guest mode, kèm ví dụ JSON.

Lỗi Telegram Bot API: ý nghĩa từng lỗi và cách khắc phục

Giải thích lỗi Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Nguyên nhân, cách sửa và code xử lý.

Giới hạn Telegram Bot API: rate limit, lỗi 429, dung lượng file và độ dài tin nhắn

Giới hạn Telegram Bot API: 30 tin/giây, 1 tin/giây mỗi chat, 20 tin/phút trong group, xử lý lỗi 429 retry_after, dung lượng file và độ dài tin nhắn.

Lệnh bot Telegram: setMyCommands, scope của lệnh và deep link cho /start

Cài lệnh cho bot Telegram: /setcommands trong @BotFather, setMyCommands theo scope và ngôn ngữ, tham số deep link của /start và lệnh /cmd@bot trong nhóm.

Bàn phím bot Telegram: inline keyboard, nút callback và reply keyboard

Thêm nút bấm cho bot Telegram: inline keyboard với callback_data, answerCallbackQuery, sửa tin nhắn sau khi bấm, reply keyboard và ForceReply, có code mẫu.

API gửi tin nhắn Telegram: hướng dẫn sendMessage với curl, Python và JavaScript

Dùng API gửi tin nhắn Telegram qua sendMessage: ví dụ curl, Python requests, JavaScript fetch, định dạng HTML, MarkdownV2, nút inline và lỗi 400, 403, 429.

Cách lấy token bot Telegram: tìm lại, kiểm tra bằng getMe và thu hồi khi bị lộ

Cách lấy token bot Telegram từ @BotFather, xem lại token của bot cũ, kiểm tra bằng getMe, sửa lỗi 401 Unauthorized và thu hồi token khi bị lộ.

Webhook Telegram bot: cài setWebhook, bảo mật bằng secret_token và dùng với n8n

Cài webhook Telegram bot từng bước: yêu cầu HTTPS và cổng, setWebhook với secret_token, kiểm tra getWebhookInfo, sửa lỗi 409 Conflict và webhook n8n.

Chat id Telegram lấy ở đâu? Cách lấy chat id cho người dùng, group, kênh và topic

Chat id Telegram lấy ở đâu: cách lấy chat id bot cho chat riêng, group, supergroup, kênh và topic bằng getUpdates, kèm cách sửa lỗi result rỗng, 409.

Bot inline Telegram: cách bật inline mode và trả lời inline query

Hướng dẫn làm bot inline Telegram: bật inline mode qua @BotFather hoặc setMySettings, xử lý update inline_query và trả kết quả bằng answerInlineQuery.

Thanh toán Telegram Stars cho bot: hóa đơn, pre-checkout, hoàn tiền và thuê bao

Nhận thanh toán Telegram Stars trong bot: sendInvoice với XTR, pre_checkout_query, successful_payment, hoàn tiền, gói thuê bao và code Python/JS.

Test server Telegram: cách test bot trong môi trường thử nghiệm của Telegram

Cách dùng test server Telegram: đăng nhập môi trường test, tạo bot test, gọi Bot API qua /test/ và bật chế độ TEST trong công cụ tester của chúng tôi.

Widget Telegram cho website: Login Widget, nhúng bài đăng, bình luận và nút chia sẻ

Đăng nhập bằng Telegram trên website: Telegram Login mới (OIDC), Login Widget cũ kèm code kiểm tra hash, nhúng bài đăng, bình luận và nút chia sẻ.

TelegramWidget JavaScript API: thuộc tính, sự kiện, mã lỗi và giới hạn

Tra cứu TelegramWidget JavaScript API: thuộc tính, request(), sự kiện, mã lỗi, biến CSS, widget_query, answerWidgetQuery và mọi giới hạn của widget.

Ví dụ widget Telegram: HTML hoàn chỉnh và code bot Python

Ví dụ widget Telegram chạy được kèm code đầy đủ: thẻ đơn hàng tĩnh, bộ đếm dùng widget_query, bình chọn trực tiếp dạng widget dùng chung và stub xem thử.

Widget Telegram: HTML tương tác ngay trong tin nhắn của bot

Widget Telegram (Bot API 10.4) là gì: cách sendWidget, chat_data và public_data hoạt động, widget chạy ở đâu và khác Mini App như thế nào.

Cách test Telegram Mini App: từ mock trên trình duyệt đến Telegram thật

Hướng dẫn test Telegram Mini App: chạy mock trên trình duyệt, localhost qua tunnel HTTPS, môi trường test, DevTools từng nền tảng và xác thực initData.