Telegram Bot API

Integrasi n8n Telegram: Hubungkan Bot, Jalankan Workflow, dan Kirim Pesan

· 8 menit baca

Untuk menghubungkan n8n ke Telegram, kamu hanya butuh satu hal dari Telegram: token bot. Simpan token itu sebagai Access Token di credential Telegram di n8n, lalu pakai node Telegram Trigger untuk menjalankan workflow saat ada pesan masuk dan node Telegram untuk mengirim pesan ke chat id. Trigger bekerja lewat webhook Bot API, jadi instance n8n kamu harus bisa diakses di URL HTTPS publik. Panduan ini membahas setup-nya, konfigurasi yang dibutuhkan n8n self-hosted, dan error yang paling sering muncul.

Cara kerja integrasi n8n Telegram

NodeFungsinyaBot API di baliknyaButuh HTTPS publik?
Telegram TriggerMenjalankan workflow saat ada update: pesan, klik tombol, postingan channel, dan sebagainyasetWebhook, lalu Telegram mengirim update ke n8n lewat POSTYa
TelegramMengirim dan mengedit pesan, mengirim file, menjawab callback query, membaca info chatsendMessage, sendPhoto, editMessageText, answerCallbackQuery…Tidak, hanya request keluar

Karena trigger memakai webhook, aturan webhook Bot API juga berlaku untuk n8n: hanya HTTPS, port 443, 80, 88, atau 8443, satu URL webhook per bot, dan getUpdates tidak bisa dipakai selama webhook terpasang.

Langkah 1: buat bot dan ambil token

  1. Buka @BotFather, kirim /newbot, pilih nama tampilan dan username yang diakhiri bot.
  2. Salin token yang diberikan BotFather. Bentuknya seperti 123456789:AAEexampleTokenReplaceWithYours. Untuk bot yang sudah ada, buka /mybots → pilih bot → API Token.
  3. Cek token sebelum menempelkannya di mana pun:
curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/getMe"

Token yang valid mengembalikan "ok": true beserta detail bot; token yang salah mengembalikan 401 Unauthorized. Pengecekan yang sama bisa dilakukan di getMe di Bot API Tester. Cara mencari, mengecek, dan mencabut token ada di panduan token bot Telegram; kalau belum punya bot, mulai dari cara membuat bot Telegram.

Langkah 2: tambahkan credential Telegram di n8n

n8n melakukan autentikasi ke Telegram hanya dengan token bot. Buat credential Telegram baru dan tempel token di field Access Token. Node Telegram dan node Telegram Trigger memakai jenis credential yang sama, jadi satu credential per bot sudah cukup.

Perlakukan token seperti password: siapa pun yang memegangnya bisa mengendalikan bot. Jika bocor, cabut di @BotFather dan perbarui credential di n8n.

Langkah 3: terima update dengan webhook n8n Telegram Trigger

Tambahkan node Telegram Trigger, pilih credential, lalu tentukan update mana yang menjalankan workflow. Pilihan yang umum adalah Message untuk pesan masuk dan Callback Query untuk klik tombol inline; * berarti semua update kecuali update anggota chat dan reaksi, sama seperti default Bot API. Node ini juga bisa dibatasi ke chat id atau user id tertentu, dan bisa mengunduh gambar serta file lampiran.

Saat kamu mengetes workflow atau mem-publish-nya, n8n memanggil setWebhook untuk bot kamu dengan URL dari instance-nya sendiri. Sejak itu, Telegram mengirim setiap update sebagai HTTPS POST ke n8n. Ada dua konsekuensinya:

Buat n8n self-hosted bisa diakses lewat HTTPS

n8n Cloud sudah punya alamat HTTPS publik. Instance self-hosted menyusun URL webhook dari protokol, host, dan port miliknya sendiri; di balik reverse proxy atau di localhost, hasilnya biasanya alamat http:// yang ditolak Telegram. Solusinya:

  1. Pasang n8n di balik reverse proxy (nginx, Caddy, Traefik, dan sejenisnya) yang menangani TLS dengan sertifikat valid di port 443.
  2. Beri tahu n8n alamat publiknya. Versi n8n terbaru memakai N8N_WEBHOOK_URL; WEBHOOK_URL yang lama sudah deprecated sejak n8n 2.35.0 tetapi masih dibaca, dan versi sebelum 2.30.0 hanya mengenal WEBHOOK_URL.
  3. Isi N8N_PROXY_HOPS=1 dan teruskan header X-Forwarded-For, X-Forwarded-Host, dan X-Forwarded-Proto dari proxy.
  4. Aktifkan proxy WebSocket, kalau tidak editor bisa terlihat macet saat menunggu event trigger tes.
  5. Restart n8n dan aktifkan ulang workflow agar trigger mendaftarkan URL HTTPS yang baru.
# n8n di balik reverse proxy yang melayani https://n8n.example.com
export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1
# n8n versi sebelum 2.30.0: pakai WEBHOOK_URL
# export WEBHOOK_URL=https://n8n.example.com/

Untuk development lokal, tunnel yang memberi hostname HTTPS publik bekerja dengan cara yang sama: masukkan hostname itu ke N8N_WEBHOOK_URL. Ingat bahwa webhook akan putus setiap kali alamat tunnel berubah.

Cek webhook yang terdaftar di Telegram untuk bot kamu

Jika trigger diam saja, tanyakan langsung ke Telegram dengan getWebhookInfo. Hasilnya menunjukkan URL yang terdaftar, jumlah update yang menunggu, dan error pengiriman terakhir. Skrip ini menampilkan diagnosis singkat:

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]  # token yang sama dengan credential di 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: token salah

info = data["result"]
print("URL webhook:", info["url"] or "(kosong: tidak ada Telegram Trigger yang aktif)")
print("Update menunggu:", info["pending_update_count"])
if info["url"] and not info["url"].startswith("https://"):
    print("Masalah: Telegram butuh URL HTTPS")
if "last_error_message" in info:
    print("Error pengiriman terakhir:", info["last_error_message"])
const TOKEN = process.env.BOT_TOKEN; // token yang sama dengan credential di 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: token salah
  process.exit(1);
}

const info = data.result;
console.log("URL webhook:", info.url || "(kosong: tidak ada Telegram Trigger yang aktif)");
console.log("Update menunggu:", info.pending_update_count);
if (info.url && !info.url.startsWith("https://")) {
  console.log("Masalah: Telegram butuh URL HTTPS");
}
if (info.last_error_message) {
  console.log("Error pengiriman terakhir:", info.last_error_message);
}

Simpan versi JavaScript sebagai check.mjs dan jalankan dengan Node.js 18 atau lebih baru. Cara membaca hasilnya: URL dari layanan lain berarti ada yang mengambil alih webhook bot; pending_update_count yang terus naik bersama last_error_message berarti Telegram tidak bisa menjangkau n8n atau n8n membalas dengan error. Tanpa kode, pakai getWebhookInfo di Bot API Tester.

Langkah 4: kirim pesan Telegram dari n8n

Tambahkan node Telegram, pilih resource Message dan operasi Send Message, pilih credential, lalu isi dua field:

Ada dua default yang sering bikin kaget. Node ini menambahkan baris This message was sent automatically with n8n; matikan Append n8n Attribution di additional fields untuk menghapusnya. Selain itu parse mode node ini default-nya HTML, jadi escape <, >, dan & di teks dinamis menjadi &lt;, &gt;, dan &amp;, atau Telegram menolak pesan dengan error can't parse entities.

Sebelum memasang chat id di workflow, kamu bisa memastikan ID itu benar dengan satu request di sendMessage di Bot API Tester. Untuk posting di channel, tambahkan bot sebagai admin channel lebih dulu. Telegram mengizinkan sekitar 30 pesan per detik untuk pengiriman massal dan sekitar satu pesan per detik di satu chat, jadi beri jeda di loop broadcast; lihat limit Telegram Bot API.

Mencari chat id

Sumber paling mudah adalah trigger itu sendiri: jalankan workflow, kirim pesan ke bot, lalu baca message.chat.id di output trigger. Pengguna punya ID positif, grup negatif, sedangkan supergroup dan channel berbentuk -1001234567890. Jika lebih suka getUpdates, panggil sebelum ada Telegram Trigger yang aktif untuk bot ini; selama webhook terpasang, method ini gagal dengan 409 Conflict. Semua cara, termasuk untuk grup, channel, dan topik forum, ada di panduan chat id Telegram.

Troubleshooting error n8n Telegram

GejalaPenyebabSolusi
Bad Request: bad webhook: An HTTPS URL must be provided for webhookn8n mendaftarkan URL http://: localhost, atau proxy tanpa TLSTangani TLS di proxy dan isi N8N_WEBHOOK_URL (atau WEBHOOK_URL) dengan alamat HTTPS
Error bad webhook terkait portURL publik memakai port selain 443, 80, 88, atau 8443Buka n8n di port 443 lewat proxy
409 Conflict dari getUpdatesTelegram Trigger menjaga webhook tetap terdaftarNonaktifkan workflow dan panggil deleteWebhook, atau ambil chat id dari trigger
Workflow hanya jalan saat tes atau hanya saat di-publishURL webhook test dan produksi saling menimpaUnpublish selama tes atau pakai bot tes terpisah
Trigger berhenti setelah workflow lain diaktifkanTrigger kedua, atau layanan lain, memanggil setWebhook dengan token yang samaSatu trigger per bot; cek URL dengan getWebhookInfo
Editor macet di “waiting for trigger event”Reverse proxy tanpa dukungan WebSocketAktifkan proxy WebSocket, lalu buka ulang workflow
Tidak ada update untuk pesan grupPrivacy mode: di grup bot hanya menerima perintah untuknya, balasan ke pesannya, dan pesan layananMatikan privacy mode dengan /setprivacy atau jadikan bot admin
401 UnauthorizedToken di credential salah atau sudah dicabutCek dengan getMe dan tempel token yang berlaku
400 Bad Request: chat not found saat mengirimChat id salah, atau bot tidak punya akses ke chat itu: pengguna belum pernah memulai bot, atau bot tidak ada di grupCek ulang ID; minta pengguna mengirim /start atau tambahkan bot ke grup

Untuk mulai dari kondisi bersih, nonaktifkan workflow, panggil deleteWebhook, pastikan getWebhookInfo menampilkan url kosong, lalu aktifkan workflow lagi agar n8n mendaftarkan URL-nya dari awal. Untuk mekanisme webhook secara umum (secret token, pengiriman ulang, sertifikat), lihat panduan webhook telegram bot.

Pertanyaan umum

Bagaimana cara menghubungkan Telegram ke n8n?

Buat bot lewat @BotFather, salin tokennya, lalu simpan sebagai Access Token di credential Telegram di n8n. Pakai node Telegram Trigger untuk menerima pesan dan node Telegram untuk mengirimnya; kedua node memakai credential yang sama.

Kenapa n8n Telegram Trigger menampilkan “An HTTPS URL must be provided for webhook”?

Trigger mendaftarkan webhook dengan setWebhook, dan Telegram hanya menerima URL HTTPS publik. Jika n8n berjalan di http://localhost atau di balik proxy tanpa TLS, isi alamat HTTPS publik instance kamu di N8N_WEBHOOK_URL (WEBHOOK_URL di versi lama) dan tangani TLS di reverse proxy.

Bisakah dua workflow n8n memakai trigger bot Telegram yang sama?

Tidak bisa diandalkan. Satu bot hanya punya satu URL webhook, jadi setiap aktivasi menimpa yang sebelumnya dan hanya workflow terakhir yang menerima update. Pakai satu trigger per bot, buat percabangan di dalam satu workflow, atau buat bot terpisah.

Kenapa getUpdates mengembalikan 409 Conflict setelah n8n dipasang?

Telegram Trigger yang aktif menjaga webhook tetap terdaftar untuk bot, dan getUpdates tidak berfungsi selama webhook terpasang. Nonaktifkan workflow dan panggil deleteWebhook jika butuh polling, atau ambil chat id dari output trigger.

Apakah butuh URL HTTPS publik hanya untuk mengirim pesan Telegram dari n8n?

Tidak. Node Telegram hanya membuat request keluar ke api.telegram.org, jadi pengiriman pesan tetap jalan dari n8n lokal. HTTPS publik hanya diperlukan untuk menerima update lewat Telegram Trigger.

Di mana mencari chat id untuk node Telegram di n8n?

Ambil dari output trigger (message.chat.id), atau kirim pesan ke bot lalu panggil getUpdates sebelum trigger diaktifkan. Channel publik juga menerima @channelusername.

Cara Membuat Bot Telegram: dari BotFather sampai Pesan Pertama

Cara membuat bot telegram langkah demi langkah: daftar di @BotFather, simpan token, cek dengan getMe, lalu kirim pesan pertama lewat curl dan Python.

Cara Deploy Bot Telegram: Hosting di VPS, Docker, dan Serverless

Cara deploy bot Telegram: polling vs webhook, service systemd di VPS, Docker, Cloudflare Workers dengan secret_token, plus checklist sebelum bot online.

Telegram Bot API 10.0–10.5: Pengaturan Bot, Widget, Rich Message, Ephemeral Message, Guest Mode, dan Lainnya

Fitur baru Telegram Bot API 10.0–10.5: setMySettings dan BotFullInfo, widget HTML, rich message, ephemeral message, guest mode, lengkap dengan contoh JSON.

Error Telegram Bot API: Arti Setiap Error dan Cara Mengatasinya

Daftar error Telegram Bot API: 400 chat not found, 403 bot was blocked by the user, 409 Conflict, 429 retry_after. Penyebab, solusi, dan kode penanganan.

Limit Telegram Bot API: Rate Limit, Error 429, Ukuran File, dan Panjang Pesan

Limit Telegram Bot API: 30 pesan/detik, 1 pesan/detik per chat, 20/menit di grup, cara menangani 429 retry_after, batas ukuran file dan panjang pesan.

Perintah Bot Telegram: setMyCommands, Scope Perintah, dan Deep Link /start

Cara membuat perintah bot Telegram: /setcommands di @BotFather, setMyCommands dengan scope dan bahasa, parameter deep link /start, dan /cmd@bot di grup.

Keyboard Bot Telegram: Inline Keyboard, Tombol Callback, dan Reply Keyboard

Cara membuat tombol bot Telegram: inline keyboard dengan callback_data, answerCallbackQuery, edit pesan setelah tombol ditekan, reply keyboard, ForceReply.

Kirim Pesan Bot Telegram dengan Telegram Bot API (sendMessage)

Kirim pesan bot telegram lewat Bot API: contoh sendMessage dengan curl, Python, dan JavaScript, format HTML/MarkdownV2, tombol inline, dan solusi error.

Telegram Bot Token: Cara Mendapatkan, Mengecek, dan Mencabut Token

Cara mendapatkan token bot telegram dari @BotFather, melihat token bot lama, mengecek dengan getMe, dan me-revoke token yang bocor. Lengkap dengan contoh.

Webhook Telegram Bot: Cara Setting setWebhook, Secret Token, dan Mengatasi Error

Panduan webhook telegram bot: syarat HTTPS dan port, setWebhook dengan secret_token, cek getWebhookInfo, deleteWebhook, serta solusi error 409 dan n8n.

Chat ID Telegram Dimana? Cara Mendapatkan Chat ID User, Grup, dan Channel

Chat id telegram dimana? Cara mendapatkan chat id user, grup, supergroup, dan channel lewat getUpdates, plus solusi saat result kosong atau error 409.

Bot Inline Telegram: Cara Mengaktifkan Mode Inline dan Menjawab Inline Query

Cara membuat bot inline Telegram: aktifkan mode inline lewat @BotFather atau setMySettings, tangani update inline_query, lalu balas via answerInlineQuery.

Pembayaran Telegram Stars untuk Bot: Invoice, Pre-Checkout, Refund, dan Langganan

Cara menerima pembayaran Telegram Stars di bot: sendInvoice dengan XTR, pre_checkout_query, successful_payment, refund, langganan, plus kode Python/JS.

Server Test Telegram: Cara Test Bot di Lingkungan Test Telegram

Cara memakai server test Telegram untuk bot: login ke lingkungan test, buat bot test, panggil Bot API lewat /test/, lalu aktifkan TEST di tester kami.

Widget Telegram untuk Website: Login dengan Telegram, Embed Post, Komentar, dan Tombol Share

Pasang widget telegram untuk website: login dengan Telegram (OIDC), Login Widget lama dengan cek hash, embed post, komentar channel, dan tombol share.

API JavaScript TelegramWidget: Referensi, Event, Kode Error, dan Batasan

Referensi API JavaScript TelegramWidget: properti, request(), event, kode error, variabel CSS, widget_query dan answerWidgetQuery, plus semua batasannya.

Contoh Widget Telegram: Kode HTML dan Bot Python Lengkap

Contoh widget telegram lengkap dengan kode: kartu pesanan statis, counter dengan request widget_query, polling live sebagai widget shared, preview lokal.

Widget Telegram: HTML Interaktif di Dalam Pesan Bot

Widget telegram (Bot API 10.4): apa itu, cara kerja sendWidget, chat_data dan public_data, di mana bisa dipakai saat ini, dan bedanya dengan Mini App.

Cara Tes Telegram Mini App: Dari Mock di Browser sampai Telegram Asli

Cara tes Telegram Mini App: mode mock di browser, localhost lewat tunnel HTTPS, test environment, DevTools per platform, dan validasi initData di server.