API Bot
Informasi Umum
Bot Telegram berkomunikasi dengan server Telegram melalui HTTP request. API Bot Telegram adalah salah satu bentuk spesifikasi dari interface tersebut. Isinya berupa daftar panjang dari berbagai method dan data type, yang biasa disebut dengan referensi atau reference. API ini mendefinisikan aksi apa saja yang bisa dilakukan oleh bot Telegram. Kamu dapat menemukannya tertaut di tab Sumber Daya di atas halaman.
Pemasangannya bisa dianalogikan seperti ini:
( ( ( Telegram ) API MTProto ) API HTTP Bot ) <-- bot melakukan koneksi ke sini
Jadi, ketika bot mengirim pesan, pesan tersebut akan dikirim sebagai HTTP request ke server API Bot (entah itu server milik tim Telegram, atau server milikmu sendiri). Server ini akan menerjemahkan request tadi menjadi protokol utama Telegram yang disebut MTProto, lalu meneruskannya ke backend Telegram yang bertugas mengirim pesan ke pengguna yang dituju.
Analogi yang sama juga berlaku ketika pengguna mengirim pesan ke bot, hanya saja alurnya dibalik.
Mengatasi Limitasi Ukuran File
Backend Telegram memungkinkan bot untuk mengirim file berukuran hingga 2000 MB. Namun, server API Bot—yang bertanggung jawab untuk menerjemahkan request ke HTTP—membatasi ukuran file hanya sebesar 20 MB untuk unduhan dan 50 MB untuk unggahan.
Untuk menyiasati batasan tersebut, kamu bisa meng
Catatan: Jika menangani file-file berukuran besar menggunakan long polling, kamu sebaiknya menggunakan grammY runner.
Memanggil API Bot
Setiap method API Bot juga identik dengan method milik grammY. Contohnya, send
baik di Referensi API Bot Telegram maupun di Referensi Api grammY keduanya sama-sama identik.
Memanggil Method
Kamu dapat memanggil method API melalui bot
, atau dengan cara yang sama melalui ctx
:
async function kirimHaloKe12345() {
// Kirim pesan ke 12345.
await bot.api.sendMessage(12345, "Halo!");
// Kirim pesan kemudian simpan hasil responnya.
// Respon tersebut berisi informasi mengenai pesan yang terkirim.
const sentMessage = await bot.api.sendMessage(12345, "Halo lagi!");
console.log(sentMessage.message_id);
}
2
3
4
5
6
7
8
9
Meskipun bot
mencakup seluruh API Bot, ia terkadang mengubah sedikit signatures function-nya agar lebih mudah digunakan. Sejatinya, semua method API Bot mengharapkan sebuah object JSON dengan sejumlah property tertentu. Namun, coba perhatikan bagaimana send
dalam contoh di atas hanya menerima dua argument: id chat dan sebuah string. grammY paham bahwa kedua nilai ini adalah property chat
dan text
, dari situ ia akan menyusun object JSON yang sesuai untukmu.
Seperti yang telah disebutkan sebelumnya, kamu bisa menentukan opsi lain di argument ketiga type Other
:
async function kirimHaloKe12345() {
await bot.api.sendMessage(12345, "<i>Halo!</i>", {
parse_mode: "HTML", // <-- opsi tambahan type `Other`
});
}
2
3
4
5
Disamping itu, grammY juga menyederhanakan hal-hal teknis lainnya agar kamu bisa dengan mudah menggunakan API ini. Sebagai contoh, beberapa property di method tertentu diharuskan melalui proses JSON
terlebih dahulu sebelum dikirim. Proses ini seringkali terlupakan, sulit untuk di-debug, dan dapat merusak type interface. Tetapi, grammY memudahkan kamu untuk menentukan berbagai object secara konsisten di seluruh API, serta memastikan property-property tersebut sudah di-serialized di balik layar sebelum dikirim.
Type Definition untuk API
grammY memiliki cakupan type API Bot yang cukup lengkap. Ia secara internal menggunakan type definition yang terdapat di repositori @grammyjs
. Selain itu, type definition tersebut juga sudah di-export langsung dari package inti grammy
supaya bisa digunakan di kode kamu.
Type Definition di Deno
Di Deno, kamu tinggal import type definition dari types
, yang mana berdampingan dengan file mod
:
import { type Chat } from "https://deno.land/x/grammy@v1.19.2/types.ts";
Type Definition di Node.js
Di Node.js, prosesnya lebih rumit. Kamu perlu meng-import type dari grammy
. Contohnya, untuk mengakses type Chat
, lakukan hal berikut:
import { type Chat } from "grammy/types";
Namun, Node.js—secara resmi—baru mendukung fitur import dari sub-path mulai dari versi Node.js 16. Sehingga, kamu perlu mengubah module
menjadi node16
atau nodenext
. Atur tsconfig
dengan benar lalu tambahkan baris yang disorot berikut:
{
"compilerOptions": {
// ...
"moduleResolution": "node16"
// ...
}
}
2
3
4
5
6
7
Terkadang ia juga bisa bekerja meski kita tidak mengatur konfigurasi Typescript-nya terlebih dahulu.
Keliru Menyetel Auto-complete
Jika kamu tidak mengubah file tsconfig
seperti yang telah dijelaskan di atas, kemungkinan besar auto-complete code editor kamu akan menyarankan untuk meng-import types dari grammy
atau semacamnya. Semua path yang dimulai dengan grammy
adalah file internal. Jangan digunakan! File tersebut bisa berubah sewaktu-waktu. Oleh karena itu, kami sangat menyarankan kamu untuk meng-import dari grammy
.
Membuat Panggilan Raw API
Ada kalanya kamu ingin menggunakan function signature yang asli, tetapi masih ingin mengandalkan kenyamanan yang API grammY tawarkan, misal melakukan serialize JSON saat diperlukan. grammY bisa melakukannya melalui property bot
(atau ctx
).
Kamu dapat memanggil raw method seperti ini:
async function sendHelloTo12345() {
await bot.api.raw.sendMessage({
chat_id: 12345,
text: "<i>Halo!</i>",
parse_mode: "HTML",
});
}
2
3
4
5
6
7
Pada dasarnya, semua parameter function signature disatukan satu dengan berbagai opsi object lainnya ketika kamu menggunakan raw API.