Pengembangan bot

Referensi Bot API

Semua metode yang diterima HTTP Bot API Pabal, objek yang dipertukarkan, dan error-nya, tanpa ada yang terlewat. Kompatibel dengan Bot API Telegram.

HTTP Bot API Pabal memakai format alamat, permintaan, respons, dan error yang sama dengan Bot API Telegram. Dokumen ini hanya mencantumkan apa yang benar-benar diterima Pabal. Metode yang tidak ada di sini mengembalikan 404 Not Found: method not found. Jika Anda baru mulai, bacalah tutorial membuat bot terlebih dahulu.

Mengirim permintaan

https://pabal.me/bot<token>/<metode>

• Metode HTTP: GET maupun POST bisa dipakai.
• Ada empat cara mengirim parameter — query string (?chat_id=1&text=hi), application/x-www-form-urlencoded, application/json, dan multipart/form-data saat mengunggah berkas. Boleh dicampur.
• Parameter berupa objek (reply_markup, commands, allowed_updates) dimasukkan apa adanya sebagai objek atau array di badan JSON, dan sebagai string JSON di formulir atau query.
• Nama metode tidak membedakan huruf besar dan kecil (sendMessage = sendmessage).
• Ukuran badan hingga 12MB (jika lebih, 413).
• Mengunduh berkas memakai alamat tersendiri, https://pabal.me/file/bot<token>/<file_path> (getFile).

Respons dan error

Respons selalu berupa JSON. Jika berhasil, Anda menerima HTTP 200 dan result; jika gagal, Anda menerima status HTTP tersebut, error_code yang sama dengan status itu, dan description yang bisa dibaca manusia.

{"ok": true, "result": { … }}

{"ok": false, "error_code": 400, "description": "Bad Request: chat not found"}

Pabal belum menerapkan pembatasan laju permintaan (429 Too Many Requests), tetapi karena bisa saja ditambahkan nanti, tulislah kode Anda agar saat menerima 429 ia menunggu selama parameters.retry_after detik lalu mengirim ulang.

Menerima update

Gunakan salah satu dari dua cara. Keduanya tidak bisa dipakai bersamaan.

getUpdates

POST/bot<token>/getUpdates

Mengambil update yang sedang menunggu (long polling). Jika webhook terpasang, hasilnya 409.

Mengembalikan: Array of Update

setWebhook

POST/bot<token>/setWebhook

Menerima update di alamat HTTPS. Penjelasan lengkapnya ada di dokumen Webhook.

Mengembalikan: True

deleteWebhook

POST/bot<token>/deleteWebhook

Menghapus webhook dan kembali ke getUpdates. Tetap berhasil meskipun tidak ada webhook.

Mengembalikan: True

getWebhookInfo

GET/bot<token>/getWebhookInfo

Status webhook. Tanpa parameter. Jika tidak ada webhook, url berupa string kosong.

Mengembalikan: WebhookInfo

Metode

getMe

GET/bot<token>/getMe

Dipakai untuk memeriksa apakah token benar. Tanpa parameter.

Mengembalikan: User — untuk bot, ditambah can_join_groups (true), can_read_all_group_messages (true), supports_inline_queries (false), can_connect_to_business (false), dan has_main_web_app (false).

sendMessage

POST/bot<token>/sendMessage

Mengembalikan: Message yang dikirim

Untuk mengirim ke seseorang, orang itu harus sudah lebih dulu mengirim pesan ke bot (403 Forbidden: bot can't initiate conversation with a user). Untuk mengirim ke grup, bot harus menjadi anggota grup itu.

sendPhoto

POST/bot<token>/sendPhoto

Mengembalikan: Message yang dikirim (dengan file_id baru di photo)

editMessageText

POST/bot<token>/editMessageText

Mengembalikan: Message yang sudah diedit. Perubahan langsung tampil di aplikasi, dan pesan yang diedit oleh manusia datang ke bot sebagai edited_message.

Jika teks dan tombol sama persis dengan sebelumnya, hasilnya 400 Bad Request: message is not modified: …; jika mencoba mengedit pesan milik orang lain, hasilnya 400 Bad Request: message can't be edited.

editMessageCaption

POST/bot<token>/editMessageCaption

Parameternya chat_id, message_id, caption (0–1.024 karakter; jika dihilangkan, keterangan dihapus), dan reply_markup. Mengembalikan: Message yang sudah diedit.

editMessageReplyMarkup

POST/bot<token>/editMessageReplyMarkup

Mengganti tombolnya saja, teks dibiarkan. Parameternya chat_id, message_id, dan reply_markup (jika dihilangkan, tombol dihapus). Mengembalikan: Message yang sudah diedit.

deleteMessage

POST/bot<token>/deleteMessage

Parameternya chat_id dan message_id. Menghapus pesan dari kedua sisi obrolan. Jika pesannya tidak ada, 400 Bad Request: message to delete not found. Mengembalikan: True.

answerCallbackQuery

POST/bot<token>/answerCallbackQuery

Menjawab tombol yang ditekan seseorang (CallbackQuery). Anda bisa menjawab dalam 10 detik dan hanya sekali.

Mengembalikan: True. Jika terlambat atau sudah dijawab, 400 Bad Request: query is too old and response timeout expired or query ID is invalid.

sendChatAction

POST/bot<token>/sendChatAction

Diterima demi kompatibilitas dan mengembalikan True, tetapi belum menampilkan "sedang mengetik…" di aplikasi.

getChat

GET/bot<token>/getChat?chat_id=…

Parameternya chat_id (angka). Untuk orang, orang tersebut; untuk grup, hanya grup yang anggotanya termasuk bot. Mengembalikan: Chat. Jika tidak ada atau tidak bisa dilihat, 400 Bad Request: chat not found.

getFile

GET/bot<token>/getFile?file_id=…

Mendapatkan jalur unduhan dari file_id foto yang diterima. Mengembalikan: File. Setelah itu, unduh dari alamat ini.

https://pabal.me/file/bot<token>/<file_path>

file_id juga merupakan hak untuk mengambil foto itu. Jika nilainya salah, 400 Bad Request: wrong file identifier/HTTP URL specified.

setMyCommands

POST/bot<token>/setMyCommands

Mengembalikan: True. Jika tidak sesuai aturan perintah, 400 Bad Request: BOT_COMMAND_INVALID.

getMyCommands

GET/bot<token>/getMyCommands

Parameternya language_code (opsional). Mengembalikan: Array of BotCommand.

deleteMyCommands

POST/bot<token>/deleteMyCommands

Parameternya language_code (opsional). Mengosongkan daftar itu. Mengembalikan: True.

logOut · close

Di Telegram, metode ini dipakai saat pindah ke server Bot API lokal. Di Pabal tidak ada tempat untuk pindah, jadi metode ini hanya diterima dan mengembalikan True. Untuk membatalkan token, gunakan /revoke di BotFather.

Objek

Tanda opsional di samping kolom berarti kolom itu bisa saja tidak ada. Kolom Telegram lain yang tidak tercantum di sini tidak dikirim oleh Pabal.

Update

Satu update baru. Berisi update_id dan salah satu dari tiga kolom di bawah.

User

Chat

Message

MessageEntity

Server otomatis menemukannya di dalam teks dan menambahkannya. Entitas format seperti tebal dan miring belum ada.

PhotoSize

File

CallbackQuery

InlineKeyboardMarkup

inline_keyboard: Array of Array of InlineKeyboardButton — array luar adalah baris, array dalam adalah tombol-tombol dalam satu baris. Maksimal 100 baris dan 100 tombol per pesan.

InlineKeyboardButton

Jenis lain seperti switch_inline_query, web_app, login_url, dan pay belum ada (400).

ReplyKeyboardMarkup

KeyboardButton

Satu string, atau objek yang berisi text dan kolom opsional request_contact (kirim kontak saya) serta request_location (kirim lokasi saya), keduanya Boolean.

ReplyKeyboardRemove

{"remove_keyboard": true} — menyembunyikan papan tombol. selective opsional.

ForceReply

{"force_reply": true} — aplikasi membuka kolom input dalam keadaan membalas pesan ini. selective dan input_field_placeholder opsional.

BotCommand

WebhookInfo

Perbedaan dengan Bot API Telegram

• Jenis update: hanya message, edited_message, dan callback_query. Postingan kanal, inline query, pembayaran, polling, perubahan anggota (my_chat_member), dan lainnya tidak ada.
• Format: parse_mode dan entities diabaikan, dan teks dikirim apa adanya. Hanya perintah, sebutan, URL, dan tagar yang ditandai otomatis.
• Jenis obrolan: hanya 1:1 dan grup biasa. Kanal, supergrup, dan topik forum tidak ada.
• Media: hanya foto. Dokumen, video, suara, stiker, album, dan pengiriman lewat URL tidak ada.
• Bot di grup: tidak ada mode privasi, jadi bot menerima semua pesan di grup.
• Antrean: update yang belum diambil disimpan di memori, hingga 1.000 update terbaru per bot, dan hilang saat server dimulai ulang (Telegram menyimpannya 24 jam).
• Webhook: dikirim satu per satu secara berurutan (max_connections hanya disimpan), sertifikat self-signed tidak diterima, dan tidak ada batasan port.
• ID: ID pengguna, pesan, dan berkas hanya bermakna di dalam server ini. Karena tidak ada kanal dan supergrup, ID berbentuk -100… juga tidak ada.
• Metode yang tidak ada: yang tidak tercantum di daftar di atas (forwardMessage, copyMessage, sendDocument, sendPoll, getChatMember, banChatMember, answerInlineQuery …) menghasilkan 404 Not Found: method not found.