Membuat Bot Telegram dengan Python (Webhook)

Oleh Sugeng 27 Agu 2026

Pendahuluan

Bot Telegram dapat dibuat dengan berbagai bahasa, termasuk Python. Ada dua cara menerima pesan: webhook (Telegram mengirim pesan ke URL HTTPS Anda) dan polling (bot menarik pesan lewat getUpdates). Artikel ini membahas webhook dengan Python menggunakan library resmi python-telegram-bot (PTB).

Webhook efisien untuk produksi karena server hanya bekerja saat ada pesan. Kelemahannya, butuh URL HTTPS publik. Jika lebih suka polling, baca Membuat Bot Telegram dengan Python (Polling).

Prasyarat

Webhook wajib HTTPS dan dapat diakses dari internet. http://localhost tidak akan menerima update.

Struktur Folder

text
bot-telegram-python-webhook/
├── main.py
├── requirements.txt
├── .env          (opsional: BOT_TOKEN, WEBHOOK_URL, WEBHOOK_SECRET)
└── venv/         (opsional, virtual environment)

Langkah 1: Siapkan Virtual Environment

bash
mkdir bot-telegram-python-webhook
cd bot-telegram-python-webhook
python3 -m venv venv
source venv/bin/activate

Langkah 2: Pasang Dependensi

Buat requirements.txt:

text
python-telegram-bot==20.7

Lalu pasang:

bash
pip install -r requirements.txt

Langkah 3: Tulis Kode

Buat berkas main.py:

python
# main.py
import os
from telegram import Update
from telegram.ext import Application, CommandHandler, MessageHandler, filters

TOKEN = os.environ.get("BOT_TOKEN")
PORT = int(os.environ.get("PORT", 8080))
WEBHOOK_URL = os.environ.get("WEBHOOK_URL")  # mis. https://bot.anda.com


async def start(update: Update, context):
    await update.message.reply_text("Halo! Saya bot Python dengan webhook.")


async def echo(update: Update, context):
    await update.message.reply_text(f"Anda mengetik: {update.message.text}")


def main():
    app = Application.builder().token(TOKEN).build()
    app.add_handler(CommandHandler("start", start))
    app.add_handler(MessageHandler(filters.TEXT & ~filters.COMMAND, echo))

    # run_webhook otomatis memanggil setWebhook ke WEBHOOK_URL
    app.run_webhook(
        listen="0.0.0.0",
        port=PORT,
        webhook_url=WEBHOOK_URL,
        secret_token=os.environ.get("WEBHOOK_SECRET"),
    )


if __name__ == "__main__":
    main()

Langkah 4: Siapkan Environment

bash
export BOT_TOKEN="TOKEN_DARI_BOTFATHER"
export WEBHOOK_URL="https://bot.anda.com"
export WEBHOOK_SECRET="kunci_rahasia_acak"
export PORT=8080

WEBHOOK_SECRET bersifat opsional namun disarankan: Telegram akan mengirim header X-Telegram-Bot-Api-Secret-Token, dan PTB memvalidasinya agar request palsu ditolak.

Langkah 5: Jalankan dan Arahkan Webhook

bash
python main.py

run_webhook akan menyetel webhook ke WEBHOOK_URL secara otomatis, lalu menerima POST di jalur /webhook (default PTB). Uji dengan mengetik /start.

Untuk uji lokal tanpa domain, pakai tunnel:

bash
ngrok http 8080
# lalu set WEBHOOK_URL ke URL https dari ngrok

Jika server berada di balik reverse proxy (misal Caddy), arahkan proxy ke http://127.0.0.1:8080 dan biarkan Caddy yang memegang sertifikat HTTPS.

Penjelasan Singkat

  • Application.builder().token(TOKEN) membuat objek aplikasi bot.
  • add_handler mendaftarkan fungsi untuk perintah (/start) dan pesan teks.
  • run_webhook(...) menjalankan server mini dan menyetel webhook otomatis.

Kelebihan dan Kekurangan (Webhook)

Kelebihan:

  • Hemat resource: server hanya bekerja saat ada pesan.
  • Respons cepat (push), cocok untuk produksi.
  • Mudah dijalankan di balik reverse proxy (Caddy/Nginx).
  • Mendukung secret_token untuk keamanan ekstra.

Kekurangan:

  • Wajib HTTPS publik; butuh domain atau tunnel.
  • Konfigurasi server lebih rumit daripada polling.
  • Sulit dijalankan di komputer lokal tanpa tunnel.

Webhook vs Polling: webhook lebih efisien dan aman untuk produksi; polling lebih praktis untuk belajar. Bandingkan di Membuat Bot Telegram dengan Python (Polling).

Troubleshooting

1. ValueError: webhook_url must be https WEBHOOK_URL harus HTTPS publik. Beri URL domain Anda atau hasil tunnel ngrok.

2. Conflict: terminated by other getWebhookInfo / 409 Instance lain (polling atau webhook) masih aktif. Hapus webhook dulu:

python
import asyncio
from telegram import Bot

async def clear():
    bot = Bot(os.environ.get("BOT_TOKEN"))
    await bot.delete_webhook()

asyncio.run(clear())

Lalu jalankan kembali python main.py.

3. SSLCertificateError / butuh HTTPS terminasi run_webhook tidak membuat sertifikat SSL. Jalankan di balik reverse proxy (Caddy/Nginx) yang memegang sertifikat, lalu arahkan ke port lokal, atau gunakan tunnel.

4. Secret token mismatch Header X-Telegram-Bot-Api-Secret-Token tidak cocok. Pastikan nilai WEBHOOK_SECRET di server sama dengan yang dikirim Telegram (atau kosongkan secret_token untuk menonaktifkan validasi).

5. TimeoutError / respon lambat Telegram menunggu balasan maksimal 60 detik. Kerjakan tugas berat secara asinkron (asyncio.create_task) agar webhook membalas cepat, lalu kirim hasil belakangan.

Kesimpulan

Webhook membuat bot Python produksi yang efisien dan responsif. Setelah dasarnya dikuasai, kembangkan fitur lebih jauh dan jalankan sebagai layanan systemd di VPS agar bot selalu menyala.

Artikel Terkait