Telegram Bot API

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

· 9 menit baca

Telegram menyediakan empat widget untuk website: Telegram Login (pengunjung bisa login dengan akun Telegram), widget post (embed pesan dari channel atau grup publik), widget diskusi (menampilkan komentar sebuah postingan channel), dan tombol share. Masing-masing berupa snippet kecil yang kamu tempel ke HTML situs sendiri. Ini bukan widget interaktif yang dikirim bot di dalam pesan chat sejak Bot API 10.4; untuk yang itu, baca widget Telegram di pesan bot.

Ringkasan widget Telegram untuk website

WidgetFungsinyaButuh bot?Cara mendapatkan kodenya
Telegram LoginDaftar dan login dengan akun Telegram (OpenID Connect)Ya, plus Allowed URLs dan Client ID dari @BotFatherConfigurator di core.telegram.org/bots/telegram-login
Login Widget (lama)Tombol login berbasis iframe versi lama, kini diarsipkanYa, dengan domain yang dihubungkan lewat /setdomaincore.telegram.org/widgets/login-legacy
Widget postMenyematkan pesan dari channel atau grup publikTidakLink t.me → EMBED, atau configurator post
Widget diskusiMenampilkan postingan channel beserta komentarnyaTidakConfigurator diskusi
Tombol sharePengunjung bisa mengirim link kamu ke chat, grup, channel, atau Saved MessagesTidakConstructor share atau link biasa

Telegram Login: cara baru login dengan Telegram (OpenID Connect)

Telegram Login versi sekarang terdiri dari library JavaScript dan provider OpenID Connect standar yang memakai Authorization Code Flow dengan PKCE. Kamu bisa memakai tombol bawaan library, library atau identity platform apa pun yang kompatibel dengan OIDC (Telegram menyebut Keycloak, Authentik, dan Auth0 sebagai contoh), atau SDK native untuk iOS dan Android.

  1. Siapkan bot yang mewakili situsmu (lihat cara membuat bot Telegram). Pengguna melihat nama dan foto profil bot di jendela konfirmasi, jadi samakan dengan nama dan logo situs.
  2. Daftarkan Allowed URLs. Buka mini app @BotFather, pilih bot, lalu Login Widget. Tambahkan origin tempat tombol dipasang (misalnya https://example.com) dan redirect URI OIDC (misalnya https://example.com/auth/callback). Telegram hanya memproses login dan redirect untuk URL yang sudah didaftarkan.
  3. Simpan Client ID dan Client Secret yang tampil di bagian yang sama. Client Secret hanya boleh ada di server.
  4. Pasang tombol di halaman.
  5. Validasi ID token di server sebelum memercayai data pengguna apa pun.

Kode embed dari configurator resmi kurang lebih seperti ini (data-request-access opsional: write mengizinkan bot mengirim pesan ke pengguna, phone meminta nomor telepon yang terverifikasi):

<script async src="https://oauth.telegram.org/js/telegram-login.js?6" data-client-id="123456789" data-onauth="onTelegramAuth(data)" data-request-access="write"></script>

<button class="tg-auth-button">Masuk dengan Telegram</button>

<script>
  function onTelegramAuth(data) {
    if (data.error) return console.warn(data.error);
    // Kirim data.id_token ke server dan verifikasi di sana
    fetch('/auth/telegram', {
      method: 'POST',
      headers: {'Content-Type': 'application/json'},
      body: JSON.stringify({id_token: data.id_token})
    });
  }
</script>

Callback menerima id_token (JWT OIDC), user (claim yang sudah di-decode), atau error. Library ini juga punya API JS: Telegram.Login.init(InitOptions, callback), Telegram.Login.open([callback]), dan Telegram.Login.auth(InitOptions, callback), dengan opsi client_id, scope, lang, dan nonce (string acak buatan server yang dimasukkan ke id_token untuk mencegah replay attack).

Popup dan COOP: telegram-login.js berkomunikasi dengan jendela popup. Jika situsmu mengirim header Cross-Origin-Opener-Policy: same-origin, login akan gagal; hapus header itu atau ganti dengan same-origin-allow-popups.

Scope dan endpoint OIDC

ScopeYang didapatClaim
openidWajib. ID unik dan waktu autentikasisub, iss, iat, exp
profileID pengguna, nama, username, URL fotoid, name, preferred_username, picture
phoneNomor telepon terverifikasi, dengan persetujuan penggunaphone_number
telegram:bot_accessBot boleh mengirim pesan ke pengguna setelah login—

Untuk klien OIDC, pakai discovery document https://oauth.telegram.org/.well-known/openid-configuration, response type code, dan PKCE dengan S256. Kalau mengimplementasikan alurnya sendiri, endpoint-nya adalah https://oauth.telegram.org/auth, https://oauth.telegram.org/token (POST dari server dengan Basic auth base64(client_id:client_secret)), dan https://oauth.telegram.org/.well-known/jwks.json. Telegram tidak punya endpoint UserInfo terpisah: semua data ada di ID token, jadi atur library agar melewati request userinfo jika library mengharapkannya.

Validasi ID token

Verifikasi tanda tangan JWT dengan key dari endpoint JWKS, lalu pastikan iss bernilai https://oauth.telegram.org, aud sama dengan ID bot (nilai yang kamu kirim sebagai client_id), dan exp belum lewat. Secara default token ditandatangani dengan RS256; ES256, EdDSA, dan ES256K bisa dipilih di Login Widget > Advanced di @BotFather (EdDSA dan ES256K hanya mengizinkan scope openid). Contoh Node.js dengan library jose:

import { createRemoteJWKSet, jwtVerify } from 'jose';

const JWKS = createRemoteJWKSet(new URL('https://oauth.telegram.org/.well-known/jwks.json'));

export async function verifyTelegramIdToken(idToken) {
  const { payload } = await jwtVerify(idToken, JWKS, {
    issuer: 'https://oauth.telegram.org',
    audience: '123456789' // Client ID kamu (ID bot)
  });
  return payload; // sub, id, name, preferred_username, picture, phone_number...
}

Telegram Login Widget versi lama (legacy)

Banyak situs masih memakai Login Widget berbasis iframe yang asli. Dokumentasinya sudah diarsipkan, jadi untuk proyek baru gunakan alur di atas. Tapi kalau kamu masih merawat situs lama, begini cara kerjanya.

  1. Kirim /setdomain ke @BotFather untuk menghubungkan domain situs ke bot.
  2. Pasang script-nya. Contoh dengan callback:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-login="your_bot" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"></script>
<script type="text/javascript">
  function onTelegramAuth(user) {
    alert('Login sebagai ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
  }
</script>

Sebagai ganti data-onauth, kamu bisa memakai data-auth-url="https://example.com/auth/telegram": pengguna diarahkan ke URL itu dengan query parameter id, first_name, last_name, username, photo_url, auth_date, dan hash. Opsi lain dari configurator: data-size (large, medium, small), data-userpic="false", data-radius, dan data-request-access="write".

Cek hash di server

Jangan percaya data sebelum diverifikasi. Algoritmanya: ambil semua field yang diterima kecuali hash, urutkan sesuai abjad, lalu gabungkan sebagai key=value dengan pemisah baris baru (\n) menjadi data-check-string. Secret key-nya adalah SHA256 dari token bot (dalam bentuk byte mentah). Hitung HMAC-SHA-256 dari data-check-string dengan key tersebut, lalu bandingkan bentuk hex-nya dengan hash. Setelah itu pastikan auth_date (Unix timestamp) masih baru. Masukkan hanya field yang dikirim Telegram, jangan ikutkan query parameter milikmu sendiri.

import hashlib
import hmac
import time

def check_telegram_auth(data: dict, bot_token: str, max_age: int = 86400) -> bool:
    fields = {k: v for k, v in data.items() if k != "hash"}
    data_check_string = "\n".join(f"{k}={fields[k]}" for k in sorted(fields))
    secret_key = hashlib.sha256(bot_token.encode()).digest()
    calc_hash = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(calc_hash, str(data.get("hash", ""))):
        return False
    return time.time() - int(fields["auth_date"]) <= max_age

# Flask: check_telegram_auth(request.args.to_dict(), BOT_TOKEN)
const crypto = require('crypto');

function checkTelegramAuth(data, botToken, maxAgeSec = 86400) {
  const { hash, ...fields } = data;
  const dataCheckString = Object.keys(fields).sort()
    .map((k) => `${k}=${fields[k]}`)
    .join('\n');
  const secretKey = crypto.createHash('sha256').update(botToken).digest();
  const calcHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
  if (typeof hash !== 'string' || hash.length !== calcHash.length) return false;
  if (!crypto.timingSafeEqual(Buffer.from(calcHash), Buffer.from(hash))) return false;
  return Date.now() / 1000 - Number(fields.auth_date) <= maxAgeSec;
}

// Express: checkTelegramAuth(req.query, process.env.BOT_TOKEN)

Penyebab hash tidak cocok yang paling sering adalah token yang salah. Pastikan token di server memang milik bot login dengan getMe di Bot API Tester: username yang dikembalikan harus sama dengan data-telegram-login. Kalau perlu mencari atau mengganti token, baca panduan token bot Telegram. Perlu dicatat, cara ini berbeda dengan validasi initData Mini App, yang membuat key-nya dengan HMAC dan string WebAppData.

Embed post Telegram

Kamu bisa menyematkan pesan apa pun dari channel atau grup publik. Buka link t.me-nya (misalnya t.me/durov/43) di browser lalu klik < > EMBED, atau tempel link tersebut ke configurator widget post. Hasilnya satu tag script:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-post="durov/43" data-width="100%"></script>

Opsi dari configurator: lebar (data-width, default 100%), foto penulis (data-userpic="true" untuk selalu tampil, "false" untuk menyembunyikan, hapus atribut untuk otomatis), warna aksen (data-color dengan nilai hex seperti 13B4C6), dan tema gelap (data-dark="1"; jika warna diatur, configurator bisa menambahkan data-dark-color).

Widget diskusi: komentar Telegram di situsmu

Widget diskusi menampilkan postingan channel publik beserta komentarnya. Berikan link ke postingan yang punya kolom komentar:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-discussion="contest/198" data-comments-limit="5"></script>

Kamu juga bisa hanya mengisi nama channel (data-telegram-discussion="your_channel"). Dengan begitu, setiap halaman artikel menampilkan diskusi dari postingan channel yang berisi link ke halaman itu, segera setelah link tersebut kamu posting di channel. Untuk mode ini, header halaman wajib berisi <link rel="canonical" href="%page_url%"> dengan URL kanonis halaman. Opsi: batas komentar (data-comments-limit, 3–50 di configurator), data-height, data-colorful="1" untuk warna nama yang berbeda-beda, data-color, dan data-dark="1".

Tombol share Telegram

Saat pengunjung menekan tombol share, Telegram memintanya memilih chat, grup, atau channel, dan teks opsional masih bisa diedit sebelum dikirim. Constructor di core.telegram.org/widgets/share menghasilkan:

<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="Coba lihat ini!" data-size="large"></script>

Hapus data-size untuk tombol ukuran sedang; data-text="notext" hanya menampilkan ikon. Kalau ingin desain sendiri, buat link ke https://t.me/share/url?url={url}&text={text} dengan kedua nilai di-URL-encode:

<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=Coba%20lihat%20ini%21">Bagikan ke Telegram</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
  + '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;

Troubleshooting

Langkah selanjutnya

Pertanyaan umum

Bagaimana cara menambahkan tombol login dengan Telegram ke website?

Siapkan bot, buka mini app @BotFather, pilih bot lalu Login Widget, tambahkan origin situs dan redirect URI sebagai Allowed URLs, lalu salin Client ID. Setelah itu pasang snippet telegram-login.js dengan data-client-id di halaman dan verifikasi id_token yang diterima di server.

Apakah Telegram Login Widget yang lama masih didukung?

Dokumentasinya sudah diarsipkan di core.telegram.org/widgets/login-legacy. Sekarang Telegram mendokumentasikan library Telegram Login dan alur OpenID Connect sebagai cara utama login dengan Telegram, jadi pakai itu untuk proyek baru.

Bagaimana cara memverifikasi data Telegram Login Widget di server?

Untuk widget lama, susun data-check-string dari semua field yang diterima kecuali hash, urutkan sesuai abjad dalam format key=value dan gabungkan dengan \n. Hitung HMAC-SHA-256 dengan SHA256(bot_token) sebagai key, bandingkan hasil hex-nya dengan hash, dan cek auth_date. Untuk login baru, validasi JWT id_token dengan JWKS milik Telegram.

Bagaimana cara embed post Telegram di website?

Buka link t.me postingan (misalnya t.me/durov/43) di browser lalu klik EMBED, atau pakai configurator di core.telegram.org/widgets/post. Hanya postingan dari channel dan grup publik yang bisa di-embed.

Bagaimana membuat tombol share Telegram sendiri?

Buat link ke https://t.me/share/url?url={url}&text={text}, dengan kedua nilai di-URL-encode, misalnya memakai encodeURIComponent di JavaScript. Teks bersifat opsional dan pengguna masih bisa mengubahnya sebelum mengirim.

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.

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.

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.

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.