Membuat Bot Telegram dengan Node.js (Webhook)

Oleh Sugeng 27 Agu 2026

Pendahuluan

Bot Telegram adalah program yang berjalan di server dan merespons pesan pengguna lewat Bot API. Ada dua cara bot menerima pesan:

  • Webhook: Telegram mengirimkan setiap pesan langsung ke URL HTTPS milik Anda (metode push). Efisien untuk produksi.
  • Polling: bot Anda yang aktif menarik pesan baru dari server Telegram tiap beberapa detik (metode getUpdates). Lebih sederhana untuk belajar.

Artikel ini fokus ke webhook dengan Node.js memakai library telegraf dan express. Jika lebih suka metode polling, baca Membuat Bot Telegram dengan Node.js (Polling).

Prasyarat

  • Node.js terpasang. Bila perlu, ikuti Memasang NodeJS di Debian 13.
  • Token bot dari @BotFather: kirim /newbot, lalu salin token panjang seperti 123456789:ABCdef....
  • URL HTTPS publik yang menunjuk ke server Anda. Bisa berupa domain sendiri (misal lewat Caddy reverse proxy) atau tunnel seperti ngrok/cloudflared untuk uji coba lokal.
Webhook wajib HTTPS dan dapat diakses dari internet. http://localhost tidak akan pernah menerima update dari Telegram.

Struktur Folder

text
bot-telegram-node-webhook/
├── index.js
├── package.json
├── .env          (opsional: BOT_TOKEN, WEBHOOK_URL, PORT)
└── node_modules/ (otomatis setelah npm install)

Langkah 1: Inisialisasi Proyek

bash
mkdir bot-telegram-node-webhook
cd bot-telegram-node-webhook
npm init -y
npm install telegraf express

Langkah 2: Tulis Kode

Buat berkas index.js:

javascript
// index.js
const express = require('express');
const { Telegraf } = require('telegraf');

const BOT_TOKEN = process.env.BOT_TOKEN;
const PORT = process.env.PORT || 3000;
const WEBHOOK_URL = process.env.WEBHOOK_URL; // mis. https://bot.anda.com

const bot = new Telegraf(BOT_TOKEN);

bot.start((ctx) => ctx.reply('Halo! Saya bot Node.js dengan webhook.'));
bot.on('text', (ctx) => ctx.reply('Anda mengetik: ' + ctx.message.text));

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

// Telegram mengirim tiap update ke jalur ini
app.post('/webhook', bot.webhookCallback());

app.get('/', (req, res) => res.send('Bot berjalan.'));

async function main() {
  await bot.telegram.setWebhook(WEBHOOK_URL + '/webhook');
  console.log('Webhook aktif di:', WEBHOOK_URL + '/webhook');
  app.listen(PORT, () => console.log('Server mendengarkan port', PORT));
}

main();

Isi berkas package.json (pastikan start mengarah ke index.js):

json
{
  "name": "bot-telegram-node-webhook",
  "version": "1.0.0",
  "description": "Bot Telegram Node.js dengan webhook",
  "main": "index.js",
  "scripts": {
    "start": "node index.js"
  },
  "dependencies": {
    "express": "^4.19.2",
    "telegraf": "^4.16.3"
  }
}

Langkah 3: Siapkan Environment

Buat berkas .env (opsional, bisa juga export langsung di terminal):

bash
export BOT_TOKEN="TOKEN_DARI_BOTFATHER"
export WEBHOOK_URL="https://bot.anda.com"
export PORT=3000

Untuk memuat .env otomatis, pasang dotenv lalu tambahkan require('dotenv').config(); di baris paling atas index.js.

Langkah 4: Jalankan dan Arahkan Webhook

bash
node index.js

Pastikan domain/port memang mencapai server (misal lewat Caddy). Telegram akan mengirim POST ke https://bot.anda.com/webhook. Uji dengan mengetik /start di chat bot.

Untuk uji lokal tanpa domain, gunakan tunnel:

bash
ngrok http 3000
# lalu set WEBHOOK_URL ke URL https yang diberikan ngrok

Penjelasan Singkat

  • bot.telegram.setWebhook(...) memberitahu Telegram ke mana mengirim pesan.
  • app.post('/webhook', bot.webhookCallback()) menangani request masuk lalu memanggil handler bot.
  • express.json() diperlukan agar body JSON bisa dibaca.

Kelebihan dan Kekurangan (Webhook)

Kelebihan:

  • Hemat resource: server hanya bekerja saat ada pesan.
  • Latensi rendah: pesan sampai hampir instan (push).
  • Cocok untuk produksi dan traffic tinggi.
  • Mudah digabung dengan layanan lain di server yang sama.

Kekurangan:

  • Wajib HTTPS publik; butuh domain atau tunnel.
  • Konfigurasi server (reverse proxy, firewall) lebih rumit.
  • Sulit dijalankan di komputer lokal tanpa alat bantu tunnel.

Webhook vs Polling: webhook lebih efisien dan responsif, tetapi polling lebih mudah dipasang karena tidak butuh URL publik. Pelajari polling di Membuat Bot Telegram dengan Node.js (Polling).

Troubleshooting

1. Error 401 Unauthorized Token salah atau ada karakter tercecer. Salin ulang token dari BotFather dan pastikan BOT_TOKEN benar.

2. 409 Conflict: can't set webhook / webhook lama masih aktif Kemungkinan bot sebelumnya memakai polling. Hapus webhook dulu:

javascript
await bot.telegram.deleteWebhook();
await bot.telegram.setWebhook(WEBHOOK_URL + '/webhook');

3. Pesan tidak masuk padahal server menyala Pastikan: WEBHOOK_URL benar-benar HTTPS dan bisa diakses dari internet (bukan localhost); firewall/cloud membuka port 443; jalur webhook (/webhook) cocok antara setWebhook dan app.post.

4. Webhook can't be set: bad webhook URL tidak HTTPS atau tidak reachable saat Telegram mencobanya. Nyalakan server dan arahkan domain ke IP Anda sebelum menjalankan setWebhook.

5. Respon lambat / Timed out Telegram menunggu balasan maksimal 60 detik. Jika ada kerjaan berat (API luar, database lambat), pindahkan ke antrean/worker, balas cepat, lalu kirim hasil belakangan.

Kesimpulan

Webhook adalah pilihan terbaik untuk bot Node.js produksi karena efisien dan cepat. Setelah menguasai dasarnya, kembangkan fitur dengan membaca Membangun Bot Telegram CRUD dengan Node.js dan Telegraf atau Membuat Bot Telegram Pengingat dengan Node.js.

Artikel Terkait