Telegram Bot API

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

· 8 menit baca

Perintah bot Telegram adalah /kata_kunci seperti /start atau /help yang disorot aplikasi Telegram di pesan, disarankan saat pengguna mengetik /, dan ditampilkan di menu bot. Daftarnya diatur lewat /setcommands di @BotFather atau dengan method setMyCommands, yang juga mendukung scope (perintah berbeda untuk grup, admin, atau satu chat) dan daftar per bahasa. Bot menerima perintah sebagai pesan teks biasa, dan /start bisa membawa parameter deep link. Panduan ini membahas semuanya dengan contoh curl, Python, dan JavaScript.

Cara kerja perintah bot Telegram

Perintah hanyalah pesan yang teksnya diawali /. Mendaftarkan perintah tidak mengubah apa yang diterima bot; itu hanya memberi tahu aplikasi Telegram apa yang perlu disarankan. Aturan daftar yang didaftarkan lewat setMyCommands (objek BotCommand):

Telegram meminta setiap bot mendukung perintah global /start (memulai interaksi, juga menerima parameter deep link) dan /help (apa yang bisa dilakukan bot dan daftar perintahnya), plus /settings jika bot punya pengaturan. Pilih perintah yang spesifik seperti /newlocation daripada /new generik yang butuh argumen tambahan.

Mengatur perintah lewat @BotFather

Cara tanpa kode, cocok untuk daftar yang tetap:

  1. Buka @BotFather dan kirim /setcommands.
  2. Pilih bot kamu.
  3. Kirim daftarnya, satu perintah per baris dengan format perintah - deskripsi:
start - Mulai bot
help - Cara memakai bot
settings - Pengaturan kamu

Kalau belum punya bot, mulai dari panduan cara membuat bot Telegram.

Mengatur perintah dengan setMyCommands

setMyCommands melakukan hal yang sama dari kode, jadi daftar perintah bisa disimpan di repository dan diperbarui saat deploy. Parameternya: commands (wajib, array BotCommand), scope (opsional, default scope default), dan language_code (opsional, kode dua huruf ISO 639-1). Method ini mengembalikan true:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands":[{"command":"start","description":"Mulai bot"},{"command":"help","description":"Cara memakai bot"}]}'

Untuk mencoba tanpa kode, buka setMyCommands di Bot API Tester, tempel token, isi perintah, lalu tekan Execute. Setelah itu panggil getMyCommands untuk melihat daftar yang tersimpan.

Scope perintah dan bahasa

Scope menentukan siapa yang melihat sebuah daftar. Ada 7 jenis BotCommandScope:

type scopeSiapa yang melihat daftarField tambahan
defaultSemua orang, jika tidak ada daftar yang lebih sempit—
all_private_chatsSemua chat pribadi dengan bot—
all_group_chatsSemua grup dan supergroup—
all_chat_administratorsAdmin di semua grup dan supergroup—
chatSatu chat tertentuchat_id
chat_administratorsAdmin di satu grup atau supergroupchat_id
chat_memberSatu anggota di satu grup atau supergroupchat_id, user_id

chat_id berupa ID numerik atau @username supergroup; channel dan chat pesan langsung channel tidak didukung. Setiap scope juga bisa punya daftar per bahasa: dengan language_code daftar itu tampil untuk pengguna dengan bahasa aplikasi tersebut, tanpa language_code untuk semua orang di scope itu yang tidak punya daftar khusus bahasanya.

Telegram menampilkan daftar pertama yang sudah diatur, dicek dari scope tersempit. Di chat pribadi urutannya chat → all_private_chats → default; di grup urutannya chat_member → chat_administrators → chat → all_chat_administrators → all_group_chats → default (scope admin hanya berlaku untuk admin). Di setiap langkah, daftar dengan language_code pengguna menang atas daftar tanpa bahasa.

Skrip ini mengatur daftar default, terjemahan bahasa Indonesia, dan perintah tambahan untuk admin grup, lalu membaca salah satunya kembali:

import os
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=10).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


# Daftar default untuk semua orang
call("setMyCommands", commands=[
    {"command": "start", "description": "Start the bot"},
    {"command": "help", "description": "How to use the bot"},
    {"command": "settings", "description": "Your settings"},
])

# Perintah yang sama untuk pengguna dengan aplikasi Telegram berbahasa Indonesia
call("setMyCommands", language_code="id", commands=[
    {"command": "start", "description": "Mulai bot"},
    {"command": "help", "description": "Cara memakai bot"},
    {"command": "settings", "description": "Pengaturan kamu"},
])

# Perintah tambahan untuk admin semua grup
call("setMyCommands", scope={"type": "all_chat_administrators"}, commands=[
    {"command": "help", "description": "How to use the bot"},
    {"command": "stats", "description": "Group statistics"},
])

print(call("getMyCommands", scope={"type": "all_chat_administrators"}))
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;

async function call(method, params = {}) {
  const res = await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${method}: ${data.error_code} ${data.description}`);
  return data.result;
}

// Daftar default untuk semua orang
await call("setMyCommands", {
  commands: [
    { command: "start", description: "Start the bot" },
    { command: "help", description: "How to use the bot" },
    { command: "settings", description: "Your settings" },
  ],
});

// Perintah yang sama untuk pengguna dengan aplikasi Telegram berbahasa Indonesia
await call("setMyCommands", {
  language_code: "id",
  commands: [
    { command: "start", description: "Mulai bot" },
    { command: "help", description: "Cara memakai bot" },
    { command: "settings", description: "Pengaturan kamu" },
  ],
});

// Perintah tambahan untuk admin semua grup
await call("setMyCommands", {
  scope: { type: "all_chat_administrators" },
  commands: [
    { command: "help", description: "How to use the bot" },
    { command: "stats", description: "Group statistics" },
  ],
});

console.log(await call("getMyCommands", { scope: { type: "all_chat_administrators" } }));

Scope hanya mengatur apa yang terlihat oleh pengguna. Update tidak memberi tahu dari scope mana perintah berasal, dan pengguna bisa mengetik perintah apa pun, termasuk yang tidak pernah kamu daftarkan. Selalu cek di server bahwa perintah itu ada dan pengguna boleh menjalankannya (misalnya cek hak admin dengan getChatMember).

getMyCommands dan deleteMyCommands

getMyCommands mengembalikan array BotCommand untuk scope dan language_code tertentu, atau array kosong jika belum diatur. deleteMyCommands menghapus daftar untuk scope dan bahasa itu; pengguna terkait lalu melihat daftar berikutnya sesuai urutan pencarian:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/deleteMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"scope":{"type":"all_chat_administrators"}}'

Menangani perintah dan parameter /start

Perintah datang sebagai update message biasa dengan teks persis seperti yang diketik. Di grup, perintah bisa ditujukan ke bot tertentu sebagai /command@your_bot, jadi buang bagian @username dan abaikan perintah untuk bot lain. Deep link bekerja seperti ini:

Bot long polling yang mem-parsing perintah, menangani /start dengan dan tanpa parameter, serta membuat deep link base64url:

import base64
import os
import re
import requests

TOKEN = os.environ["BOT_TOKEN"]
API = f"https://api.telegram.org/bot{TOKEN}"
BOT_USERNAME = requests.get(f"{API}/getMe", timeout=10).json()["result"]["username"]
COMMAND_RE = re.compile(r"^/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+(.*))?$", re.S)


def make_start_link(payload: str) -> str:
    # base64url tanpa padding "=": hanya tersisa A-Z a-z 0-9 _ - (maks. 64 karakter)
    code = base64.urlsafe_b64encode(payload.encode()).decode().rstrip("=")
    return f"https://t.me/{BOT_USERNAME}?start={code}"


def read_start_param(code: str) -> str:
    return base64.urlsafe_b64decode(code + "=" * (-len(code) % 4)).decode()


def parse_command(text):
    m = COMMAND_RE.match(text)
    if not m or (m[2] and m[2].lower() != BOT_USERNAME.lower()):
        return None  # bukan perintah, atau perintah untuk bot lain
    return m[1].lower(), (m[3] or "").strip()


def send(chat_id, text):
    requests.post(f"{API}/sendMessage", json={"chat_id": chat_id, "text": text}, timeout=10)


print("Bagikan link ini:", make_start_link("ref:42"))
offset = 0
while True:
    resp = requests.get(f"{API}/getUpdates", params={"offset": offset, "timeout": 30}, timeout=40).json()
    for update in resp["result"]:
        offset = update["update_id"] + 1
        msg = update.get("message")
        parsed = parse_command(msg.get("text", "")) if msg else None
        if not parsed:
            continue
        name, args = parsed
        chat_id = msg["chat"]["id"]
        if name == "start" and args:
            try:
                send(chat_id, "Selamat datang! Kamu datang dari: " + read_start_param(args))
            except ValueError:
                send(chat_id, "Selamat datang! Parameter start tidak dikenal.")
        elif name == "start":
            send(chat_id, "Selamat datang! Kirim /help untuk melihat apa yang bisa saya lakukan.")
        elif name == "help":
            send(chat_id, "/start - mulai bot\n/help - pesan ini\n/settings - pengaturan kamu")
        elif name == "settings":
            send(chat_id, "Belum ada pengaturan.")
const TOKEN = process.env.BOT_TOKEN;
const API = `https://api.telegram.org/bot${TOKEN}`;
const BOT_USERNAME = (await (await fetch(`${API}/getMe`)).json()).result.username;
const COMMAND_RE = /^\/([A-Za-z0-9_]+)(?:@([A-Za-z0-9_]+))?(?:\s+([\s\S]*))?$/;

function makeStartLink(payload) {
  // base64url di Node tanpa padding "=": hanya tersisa A-Z a-z 0-9 _ - (maks. 64 karakter)
  const code = Buffer.from(payload).toString("base64url");
  return `https://t.me/${BOT_USERNAME}?start=${code}`;
}

function readStartParam(code) {
  return Buffer.from(code, "base64url").toString("utf8");
}

function parseCommand(text) {
  const m = COMMAND_RE.exec(text);
  if (!m || (m[2] && m[2].toLowerCase() !== BOT_USERNAME.toLowerCase())) {
    return null; // bukan perintah, atau perintah untuk bot lain
  }
  return { name: m[1].toLowerCase(), args: (m[3] ?? "").trim() };
}

async function send(chatId, text) {
  await fetch(`${API}/sendMessage`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ chat_id: chatId, text }),
  });
}

console.log("Bagikan link ini:", makeStartLink("ref:42"));
let offset = 0;
while (true) {
  const resp = await (await fetch(`${API}/getUpdates?offset=${offset}&timeout=30`)).json();
  for (const update of resp.result) {
    offset = update.update_id + 1;
    const msg = update.message;
    const parsed = msg ? parseCommand(msg.text ?? "") : null;
    if (!parsed) continue;
    const { name, args } = parsed;
    const chatId = msg.chat.id;
    if (name === "start" && args) {
      await send(chatId, "Selamat datang! Kamu datang dari: " + readStartParam(args));
    } else if (name === "start") {
      await send(chatId, "Selamat datang! Kirim /help untuk melihat apa yang bisa saya lakukan.");
    } else if (name === "help") {
      await send(chatId, "/start - mulai bot\n/help - pesan ini\n/settings - pengaturan kamu");
    } else if (name === "settings") {
      await send(chatId, "Belum ada pengaturan.");
    }
  }
}

Simpan versi JavaScript sebagai bot.mjs dan jalankan dengan Node.js 18+ (kode ini memakai top-level await). Perlakukan parameter start sebagai input yang tidak tepercaya: siapa pun bisa membuat link, jadi jangan pernah menaruh rahasia yang langsung memberi akses di dalamnya. getUpdates tidak berfungsi selama webhook terpasang; untuk produksi lihat panduan webhook telegram bot.

Perintah di grup dan privacy mode

Bot di grup secara default berjalan dalam privacy mode. Bot hanya menerima perintah yang ditujukan khusus untuknya (/command@your_bot), perintah umum seperti /start hanya jika bot itu yang terakhir mengirim pesan ke grup, balasan ke pesannya, dan pesan layanan. Jika ada beberapa bot dalam satu grup, minta pengguna mengetuk perintah dari daftar, karena cara itu otomatis menambahkan bagian @your_bot. Untuk menerima semua pesan, jadikan bot admin atau matikan privacy mode dengan /setprivacy di @BotFather.

Di chat pribadi, tombol menu di samping kolom input secara default membuka daftar perintah. Kamu bisa mengarahkannya ke Mini App, atau kembali ke daftar perintah, dengan setChatMenuButton; tanpa chat_id perubahan berlaku sebagai default untuk semua chat:

curl "https://api.telegram.org/bot123456789:AAEexampleTokenReplaceWithYours/setChatMenuButton" \
  -H "Content-Type: application/json" \
  -d '{"menu_button":{"type":"commands"}}'

Jenis lainnya adalah web_app (dengan text dan web_app) dan default. Sejak Bot API 10.2, BotCommand juga bisa punya is_ephemeral: true: perintah seperti ini yang dikirim di grup tidak terlihat oleh anggota dan bot lain, dan hanya bot kamu yang menerimanya.

Tips perintah bot yang baik

Troubleshooting

GejalaKemungkinan penyebabSolusi
400 dengan BOT_COMMAND_INVALIDAda huruf besar, tanda hubung, / di depan, atau lebih dari 32 karakter di commandPakai 1–32 huruf kecil, angka, dan garis bawah, tanpa garis miring
Perintah sudah diatur, tapi pengguna melihat daftar lainScope yang lebih sempit atau daftar untuk bahasa pengguna lebih diprioritaskanCek setiap scope dan bahasa dengan getMyCommands
Bot mengabaikan /start di grupPrivacy mode dan bot lain yang terakhir mengirim pesanKirim /start@your_bot, atau ubah privacy mode
Parameter start tidak sampaiAda karakter di luar A-Z a-z 0-9 _ - (misalnya padding =) atau lebih dari 64 karakterEncode dengan base64url, buang padding, perpendek payload
401 UnauthorizedToken salah atau sudah dicabutLihat panduan token bot Telegram

Pertanyaan umum

Bagaimana cara menambahkan perintah ke bot Telegram?

Kirim /setcommands ke @BotFather lalu pilih bot, atau panggil method Bot API setMyCommands dengan daftar objek BotCommand. Aplikasi Telegram kemudian menyarankan perintah saat pengguna mengetik / dan menampilkannya di menu.

Karakter apa saja yang boleh dipakai di perintah bot Telegram?

Di setMyCommands, teks perintah sepanjang 1–32 karakter dan hanya boleh berisi huruf kecil bahasa Inggris, angka, dan garis bawah. Deskripsi 1–256 karakter. Maksimal 100 perintah per scope dan bahasa.

Bagaimana cara mengirim parameter ke /start?

Pakai deep link seperti https://t.me/your_bot?start=airplane. Bot menerima pesan /start airplane. Parameter maksimal 64 karakter dari A-Z, a-z, 0-9, _, dan -; untuk data lain pakai base64url.

Kenapa bot tidak melihat perintah di grup?

Dengan privacy mode aktif (default), bot di grup menerima perintah yang ditujukan khusus untuknya, seperti /command@your_bot, sedangkan perintah umum seperti /start hanya jika bot itu yang terakhir mengirim pesan di sana. Pakai bentuk @your_bot, jadikan bot admin, atau matikan privacy mode dengan /setprivacy.

Bagaimana cara menampilkan perintah berbeda untuk admin grup?

Panggil setMyCommands dengan scope berisi {"type": "all_chat_administrators"} untuk semua grup, atau {"type": "chat_administrators", "chat_id": ...} untuk satu grup. Tetap cek izin di server: update tidak memberi tahu dari scope mana perintah berasal.

Bagaimana cara menghapus semua perintah bot?

Panggil deleteMyCommands untuk setiap scope dan language_code yang pernah kamu atur. Setelah dihapus, pengguna melihat daftar berikutnya sesuai urutan pencarian, misalnya perintah default.

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.

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.

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

Cara menghubungkan n8n ke Telegram: token bot sebagai Access Token, webhook Telegram Trigger via HTTPS publik, kirim pesan via chat id, dan solusi error.

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.