Langsung ke konten utama

Tombol Menu Reply Markup Dengan Custom Keyboard dan Inline Keyboard

Membuat tombol menu di Bot Telegram dapat menambah aktraktif tampilan bot dan tentunya mengganti peran command bot dari yang masih konvensional dengan kode karakter.

BAHAN BAKU

Untuk mengimplementasikan eksperimen ini perlu dipersiapkan beberapa hal:

  1. Satu file Google Sheets yang telah di-publish dalam bentuk web, simak caranya di artikel ini.
  2. ID dari Google Sheets tersebut, cara mendapatkan ID silahkan simak dalam artikel ini.
  3. Bot Telegram berikut API Token, anda dapat menyimak cara membuatnya dan mendapatkan API Token pada artikel ini.
  4. ID dan Username dari bot tersebut yang bisa anda simak caranya di artikel ini.
  5. Satu file Apps Script, anda bisa menyimak cara membuatnya dan deployment Web Apps di artikel ini.
  6. Script eksperimen ini yang dapat unduh atau salin dari repository.
  7. ID User anda sebagai admin bot yang akan digunakan untuk menampung keterangan error bila terjadi kendala, gunakan @simrsinfobot untuk mengetahui ID User anda.

Di dalam script terdapat beberapa konstata yang harus anda isi dengan ID, API TOKEN, dan URL file bahan baku milik anda:

Bila anda menemui kendala saat deployment silahkan simak cara penanganannya pada artikel iniSiLiKiDi
video courtesy of Telegram

REPLY MARKUP

reply_markup adalah properti yang hampir selalu ada dalam setiap metode send di Telegram API. Di reply_markup inilah tempat untuk menyetel tombol menu berada. Misalkan pada metode sendMessage:


let dataPesan = {
    method: "post",
    payload: {
      method: "sendMessage",
      chat_id: String( chatID ),
      text: String( textMessage ),
      reply_markup: JSON.stringify( InlineKeyboardMarkup )
    }
};
Filosofi tombol menu disediakan untuk kemudahan user dalam memberikan input kepada bot, oleh karena itu fitur tombol menu hanya ada di setiap metode sendSiLiKiDi

reply_markup menyediakan 4 pilihan metode input:

CUSTOM KEYBOARD vs FORCE REPLY

Reply Keyboard alias Custom Keyboard dan ForceReply sama-sama berfungsi sebagai reply dari user berupa input tunggal. Masing-masing punya kekurangan dan kelebihan tergantung kebutuhan anda.

  1. Input pada ForceReply berupa pengetikan gaya bebas sehingga perlu validasi tambahan dan berpotensi berbeda typo untuk satu jawaban yang sama. Sedangkan Custom Keyboard bernilai baku tidak membutuhkan proses pengetikan di sisi user sehingga terhindar dari perbedaan typo untuk satu jawaban yang sama.

  2. Karena ForceReply berbentuk kontak input sehingga tidak banyak mengambil ruang tampilan melainkan satu baris input saja. Sedangkan Custom Keyboard karena bentuknya pilihan tombol-tombol sehingga lebih banyak mengambil ruang tampilan.

  3. ForceReply akan otomatis menghilang dari tampilan setelah user memberikan input. Sedangkan Custom Keyboard akan terus tampil sekalipun user sudah memberikan pilihan selama tidak diberi perintah menghilang dengan ReplyKeyboardRemove.

Contoh Tampilan ForceReply

Contoh Tampilan Custom Keyboard

INLINE KEYBOARD vs CUSTOM KEYBOARD

Perbedaan dalam kandungan nilai tombol:

  • Setiap tombol dalam Custom Keyboard membawa kandungan data yang sama nilainya dengan label tombol tersebut. Misalkan tulisan pada tombol custom keyboard berlabel Setuju maka nilai tombol tersebut sama pula "Setuju"

  • Sedangkan Inline Keyboard tidak hanya dapat bernilai sama dengan labelnya melainkan lebih banyak lagi menawarkan variasi kandungan data seperti callback_data, url, dan switch chat.

Perbedaan dalam aksi keluaran [output]:

  • Saat user menekan tombol Custom Keyboard, ia akan mengembalikan kandungan nilai dari tombol tersebut dengan mengirimkan pesan balik ke user berupa objek message

  • Sedangkan Inline Keyboard tidak merespon dengan pengiriman objek message melainkan mengirimkan kandungan nilai dari tombolnya berupa parameter untuk diolah di backend bila berjenis callback_data, atau langsung di eksekusi bila berjenis url dan switch chat.

Perbedaan dalam tampilan:

  • Custom Keyboard mengambil ruang tampilan bingkai chat tidak terpengaruh oleh dinamika konten dari chat itu sendiri [float/fixed position]

  • Inline Keyboard mengambil ruang tampilan di dalam chat dan menempel pada message sehingga posisi tampilannya tergantung urutan message di dalam chat.

Perbedaan dalam terminasi:

  • Custom Keyboard akan hilang dari tampilan dengan mengirimkan metode ReplyKeyboardRemove.

  • Inline Keyboard akan hilang dari tampilan dengan mengirimkan metode editMessageReplyMarkup.

REPLY KEYBOARD [CUSTOM KEYBOARD]

Disebutkan dalam dokumentasi Telegram Bot API bahwa Custom Keyboard berbentuk JSON-serialized object dengan properti:

  • keyboard: berbentuk Array of Array dari KeyboardButton atau tombol-tombol yang akan ditampilkan.
  • resize_keyboard: bernilai boolean true/false untuk menentukan pengaturan otomatis posisi setiap tombol.
  • one_time_keyboard: boolean true/false untuk menyembunyikan dari tampilan setiap kali user menekan salah satu tombol.
  • input_field_placeholder: berbentuk string berisi 1-64 karakter teks pemandu dalam kotak isian yang menyertai tombol.
  • selective: boolean true/false untuk menentukan ditujukan pada user tertentu dalam suatu grup chat.
Label tombol dapat disematkan tambahan emoji dan spasi kosongSiLiKiDi

Untuk membuat Custom Keyboard, anda harus terlebih dulu menambahkan parameter reply_markup pada payload metode send apapun karena Custom Keyboard merupakan properti milik reply_markup. Contoh penerapan dalam script:


let dataPesan = {
    method: "post",
    payload: {
      method: "sendMessage",
      chat_id: String( chatID ),
      text: String( textMessage ),
      reply_markup: JSON.stringify({
         "resize_keyboard": true,
         "keyboard": [ 
            [ { "text": "TOMBOL 1 👆" }, { "text": "TOMBOL 2 🤘" }, { "text": "TOMBOL 3 🤟" } ]
         ]
      })
    }
};

Pengaturan Posisi Tombol

Pengaturan posisi setiap tombol berada di properti keyboard, dan berikut ini akan menampilkan semua tombol dalam satu baris yang sama:


"keyboard": [
   [ { "text": "TOMBOL 1 👆" }, { "text": "TOMBOL 2 🤘" }, { "text": "TOMBOL 3 🤟" } ]
]

1 tombol di baris pertama lalu 2 tombol di baris kedua:


"keyboard": [
   [ { "text": "TOMBOL 1 👆" } ],
   [ { "text": "TOMBOL 2 🤘" }, { "text": "TOMBOL 3 🤟" } ]
]

2 tombol di baris pertama lalu 1 tombol di baris kedua:


"keyboard": [
   [ { "text": "TOMBOL 1 👆" }, { "text": "TOMBOL 2 🤘" } ],
   [ { "text": "TOMBOL 3 🤟" } ]
]

REPLY KEYBOARD REMOVE

ReplyKeyboardRemove satu-satunya opsi dalam reply_markup yang tidak berfungsi sebagai media input melainkan sebatas menghapus tampilan dari Custom Keyboard.

Cukup dengan mengirimkan modul berikut untuk menghapus tampilan Custom Keyboard yang sedang aktif:


let dataRemoveCustomKeyboard = {
    method: "post",
    payload: {
      method: "sendMessage",
      chat_id: String( chatID ),
      text: String( textMessage ),
      reply_markup: JSON.stringify({ "remove_keyboard": true })
    }
};
UrlFetchApp.fetch( telegramAPIURL + "/", dataRemoveCustomKeyboard );

INLINE KEYBOARD

Inline Keyboard berbentuk JSON-serialized object dengan properti lebih sedikit dibandingkan Custom Keyboard:

  • inline_keyboard: berbentuk Array of Array dari InlineKeyboardButton atau tombol-tombol yang akan ditampilkan.

InlineKeyboardButton adalah properti tempat pengaturan konten dari tombol itu sendiri dengan properti yang lebih banyak dari Custom Keyboard. Di sini hanya akan digunakan tiga properti populer saja sedangkan sisanya bisa anda lihat di dokumentasi.

  • text: berbentuk string label dari tombol.
  • url: string dari alamat link atau deep linking.
  • callback_data: berbentuk string dari data parameter yang akan dikirimkan ke backend dengan maksimal 1-64 bytes.
Berbeda dengan Inline Keyboard, pada Custom Keyboard properti text berperan ganda sebagai label tombol dan juga nilai dari tombol itu sendiriSiLiKiDi

Untuk membuat Inline Keyboard, anda harus terlebih dulu menambahkan parameter reply_markup pada payload metode send apapun karena Inline Keyboard merupakan properti milik reply_markup. Contoh penerapan dalam script:


let dataPesan = {
    method: "post",
    payload: {
      method: "sendMessage",
      chat_id: String( chatID ),
      text: String( textMessage ),
      reply_markup: JSON.stringify({
         "inline_keyboard": [
            [ 
               { "text": "👆 EMPTY", "callback_data": "emptyness" }, 
               { "text": "🤘 CALLBACK_DATA", "callback_data": "Hello world!" }, 
               { "text": "🤟 URL", "url": "https://telegram-bot-script.blogspot.com/" }
            ]
         ]
      })
    }
};

Pengaturan Posisi Tombol Inline

Pengaturan posisi setiap tombol berada di properti inline_keyboard, dan berikut ini akan menampilkan semua tombol dalam satu baris yang sama:


"inline_keyboard": [
   [
      { "text": "👆 EMPTY", "callback_data": "emptyness" }, 
      { "text": "🤘 CALLBACK_DATA", "callback_data": "Hello world!" }, 
      { "text": "🤟 URL", "url": "https://telegram-bot-script.blogspot.com/" }
   ]
]

1 tombol di baris pertama lalu 2 tombol di baris kedua:


"inline_keyboard": [
   [ { "text": "👆 EMPTY", "callback_data": "emptyness" } ], 
   [ { "text": "🤘 CALLBACK_DATA", "callback_data": "Hello world!" }, { "text": "🤟 URL", "url": "https://telegram-bot-script.blogspot.com/" } ]
]

2 tombol di baris pertama lalu 1 tombol di baris kedua:


"inline_keyboard": [
   [ { "text": "👆 EMPTY", "callback_data": "emptyness" }, { "text": "🤘 CALLBACK_DATA", "callback_data": "Hello world!" } ], 
   [ { "text": "🤟 URL", "url": "https://telegram-bot-script.blogspot.com/" } ]
]

OUTPUT JSON

JSON Respon Custom Keyboard

Hasil eksekusi Custom Keyboard berupa respon JSON Message yang sama dihasilkan dengan respon dari metode sendMessage.


{
    "update_id": 420112365,
    "message": {
        "message_id": 521,
        "from": {
            "id": 1850121251,
            "is_bot": false,
            "first_name": "JOHN",
            "last_name": "DOE",
            "username": "johndoe",
            "language_code": "en"
        },
        "chat": {
            "id": 1850121251,
            "first_name": "JOHN",
            "last_name": "DOE",
            "username": "johndoe",
            "type": "private"
        },
        "date": 1635810217,
        "text": "BUTTON 1 👆"
    }
}

Sehingga untuk menangkap datanya gunakan notasi berikut:


let dataDariUser = data.message.text;

JSON Respon Inline Keyboard

Sedangkan eksekusi Inline Keyboard berupa respon JSON Callback_query yang tidak ditampilkan di layar chat melainkan dikirimkan ke backend.


{
    "update_id": 420112307,
    "callback_query": {
        "id": "7866573844579717058",
        "from": {
            "id": 1850121251,
            "is_bot": false,
            "first_name": "JOHN",
            "last_name": "DOE",
            "username": "johndoe",
            "language_code": "en"
        },
        "message": {
            "message_id": 391,
            "from": {
                "id": 202666666207,
                "is_bot": true,
                "first_name": "FORM BOT",
                "username": "simrsformbot"
            },
            "chat": {
                "id": 1850121251,
                "first_name": "JOHN",
                "last_name": "DOE",
                "username": "johndoe",
                "type": "private"
            },
            "date": 1635743365,
            "text": "Demo inlinekeyboards_3",
            "reply_markup": {
                "inline_keyboard": [
                    [
                        {
                            "text": "👆 EMPTY",
                            "callback_data": "emptyness"
                        },
                        {
                            "text": "🤘 CALLBACK_DATA",
                            "callback_data": "Hello world!"
                        },
                        {
                            "text": "🤟 URL",
                            "url": "https://telegram-bot-script.blogspot.com/"
                        }
                    ]
                ]
            }
        },
        "chat_instance": "7721309288641021086",
        "data": "Hello world!"
    }
}

Sehingga untuk menangkap datanya gunakan notasi berikut:


let dataDariUser = data.callback_query.data;
Selengkapnya struktur JSON hasil respon dari keduanya dapat dilihat di repositorySiLiKiDi

FINAL SCRIPT

Final Script dapat diunduh di repository dan anda dapat mencobanya melalui @simrsformbot. Di dalam script ini dibahas:

  • Kolektif 4 variasi dalam satu konstanta dari reply_markup untuk memudahkan pengelolaan dan efisiensi script.
  • Mendeteksi setiap pesan masuk dengan penanda khas dari custom keyboard, inline keyboard, command bot, teks biasa, dll
  • Menyimpan ke Google Sheets
  • Menampilkan struktur JSON dari respon keyboard
  • Merespon teks biasa dengan kiriman sticker
  • Error handling

DEMO BOT

Demo Bot: @simrskeybot.

Dapatkan skrip semua materi di repository

Dukung donasi agar tutorial ini tetap operasional:
Trakteer Saya SiLiKiDi
Labels:

Komentar

Posting Komentar

Postingan populer dari blog ini

Kirim Pesan Ke Telegram Dengan Apps Script

Dengan koneksi webhook anda bisa mulai ujicoba mengirim pesan pertama ke Telegram dari Google Apps Script.
Posting Komentar
Read more »

Input User Dengan ForceReply Di Telegram

Metode ForceReply memungkinkan Bot memaksa user untuk memberikan input sebelum melanjutkan proses, dengan demikian anda dapat menggelar Step-by-Step formulir di Telegram.
Posting Komentar
Read more »