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.

Memanggil API Bot ​

Setiap method API Bot juga identik dengan method milik grammY. Contohnya, sendMessage baik di Referensi API Bot Telegram maupun di Referensi Api grammY keduanya sama-sama identik.

Memanggil Method ​

Kamu dapat memanggil method API melalui bot.api, atau dengan cara yang sama melalui ctx.api:

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);
}

Meskipun bot.api 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 sendMessage dalam contoh di atas hanya menerima dua argument: id chat dan sebuah string. grammY paham bahwa kedua nilai ini adalah property chat_id 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`
  });
}

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.stringify 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/types. 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.ts, yang mana berdampingan dengan file mod.ts:

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/types. 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 moduleResolution menjadi node16 atau nodenext. Atur tsconfig.json dengan benar lalu tambahkan baris yang disorot berikut:

{
  "compilerOptions": {
    // ...
    "moduleResolution": "node16"
    // ...
  }
}

Terkadang ia juga bisa bekerja meski kita tidak mengatur konfigurasi Typescript-nya terlebih dahulu.

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.api.raw (atau ctx.api.raw).

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",
  });
}

Pada dasarnya, semua parameter function signature disatukan satu dengan berbagai opsi object lainnya ketika kamu menggunakan raw API.