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 untuk seluruh permintaan, tetapi metode suara punya batas per jam sehingga bisa menghasilkan 429 Too Many Requests: retry after N (Panggilan suara). 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)

sendDocument

POST/bot<token>/sendDocument

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

Format (mime_type) ditentukan dari ekstensi nama berkas. Berkas yang dikirim dari sisi aplikasi bisa sampai 2GB, tetapi unggahan dan unduhan bot lewat HTTP dibatasi 20MB, sama seperti di Telegram.

sendLocation

POST/bot<token>/sendLocation

Mengembalikan: Message yang dikirim (dengan Location di location)

sendVenue

POST/bot<token>/sendVenue

Mengembalikan: Message yang dikirim (dengan Venue di venue, dan titik yang sama di location)

Tanpa title atau address, hasilnya 400 Bad Request: title and address are required.

sendContact

POST/bot<token>/sendContact

Mengembalikan: Message yang dikirim (dengan Contact di contact)

Kartu kontak yang dikirim bot tidak pernah membawa user_id, bahkan jika nomornya milik akun Pabal — bot tidak punya kontak, dan jika kolom itu diisi, bot bisa mengetahui milik siapa sebuah nomor dengan mengirim satu kartu untuk tiap nomor. Tanpa phone_number atau first_name, hasilnya 400 Bad Request: phone_number and first_name are required.

editMessageLiveLocation

POST/bot<token>/editMessageLiveLocation

Mengembalikan: Message yang sudah diedit

Lokasi langsung yang sudah berakhir — dihentikan, atau periodenya habis — tidak bisa dipindahkan, juga tidak bisa dihidupkan lagi dengan memperpanjang periodenya (400 Bad Request: message can't be edited). Begitu pula pesan yang bukan lokasi langsung.

Perpindahan yang terjadi kurang dari 10 detik setelah perpindahan terakhir yang diterapkan, atau yang kurang dari 10 m, dilewati tanpa disimpan. Penghentian serta perubahan periode atau radius peringatan selalu diterapkan. Jika sebuah perpindahan dilewati, Message yang dikembalikan menunjukkan posisi terakhir yang diterapkan, jadi tidak masalah mengirim posisi setiap beberapa detik.

stopMessageLiveLocation

POST/bot<token>/stopMessageLiveLocation

Parameternya chat_id, message_id, dan reply_markup (opsional). Menghentikan lokasi langsung di posisi terakhirnya. Periode berbaginya dipendekkan menjadi waktu yang benar-benar berlalu, sehingga semua aplikasi menampilkannya sebagai sudah berakhir. Jika sudah dihentikan atau berakhir, hasilnya 400 Bad Request: message is not modified: …. Mengembalikan: Message yang sudah diedit.

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 tempat bot menjadi anggota. 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 sekaligus berfungsi sebagai izin untuk mengambil foto itu. Jika nilainya salah, 400 Bad Request: wrong file identifier/HTTP URL specified.

setMyCommands

POST/bot<token>/setMyCommands

Mengembalikan: True. Jika menu tidak sesuai aturan, tidak ada yang disimpan: 400 Bad Request: BOT_COMMAND_INVALID (perintah), BOT_COMMAND_DESCRIPTION_INVALID (deskripsi kosong atau lebih dari 256 karakter), BOT_COMMANDS_TOO_MUCH (lebih dari 100).

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 menonaktifkan 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 kolom di bawah.

User

Chat

Message

MessageEntity

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

PhotoSize

Document

Location

Lokasi langsung yang dibagikan seseorang datang lagi sebagai edited_message setiap kali server menerapkan sebuah perpindahan.

Venue

Contact

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

Panggilan suara

Metode-metode ini hanya ada di Pabal. Bot suara adalah bot yang bisa ditelepon dari aplikasi dan panggilannya dijawab oleh model suara AI; dengan metode ini Anda mengatur model itu dan menangani panggilan. Apa saja yang harus menyala, cara menyalakannya, dan contohnya ada di panduan Bot suara. Metodenya tetap ada di server yang fitur suaranya mati sehingga pengaturan bisa dibaca, tetapi bot yang suaranya mati atau belum diizinkan operator tidak bisa mengubah pengaturan selain untuk mematikan dan menghapus (403 VOICE_NOT_AVAILABLE).

setVoiceCallSettings

POST/bot<token>/setVoiceCallSettings

Mengubah pengaturan suara bot. Hanya yang dikirim yang berubah; server memeriksa semuanya lalu menulisnya sekaligus, atau menolak semuanya. 30 kali per jam per bot (termasuk lewat @BotFather).

Mengembalikan: True

getVoiceCallSettings

GET/bot<token>/getVoiceCallSettings

Tanpa parameter. Pengaturan saat ini; apakah bot bisa menerima telepon sekarang (available, unavailable_reason); batas server; daftar suara dan bahasa; ke mana kueri tool dan transkrip akan dikirim; serta status kunci sendiri, mode stream, dan server MCP. Kunci dan rahasia tidak ditampilkan, hanya sidik jarinya. Penjelasan kolomnya ada di Bot suara — Melihat pengaturan saat ini.

Mengembalikan: VoiceCallSettings (objek)

endVoiceCall

POST/bot<token>/endVoiceCall

Mengembalikan: True. Jika bukan panggilan aktif milik bot ini: 400 VOICE_CALL_NOT_FOUND.

sendVoiceCallContext

POST/bot<token>/sendVoiceCallContext

Mengembalikan: True. Sebelum tersambung: VOICE_CALL_NOT_ACTIVE; panggilan mode stream: VOICE_CONTEXT_NOT_SUPPORTED; terlalu panjang: VOICE_CONTEXT_TOO_LONG; lebih dari 10 per menit per panggilan: 429.

getVoiceCallUsage

GET/bot<token>/getVoiceCallUsage

Mengembalikan: period, from_date, to_date, calls, seconds, missed, refused (busy·budget·unavailable), platform_seconds, own_key_seconds, remaining_seconds_today (bot·owner), serta outbound (today·limits) untuk bot yang pernah menyalakan panggilan — batas tanggal mengikuti zona waktu server

startVoiceCall

POST/bot<token>/startVoiceCall

Bot menelepon seseorang. Hanya bot yang dinyalakan pemiliknya di @BotFather dan sudah ditinjau operator yang bisa menelepon, dan hanya kepada orang yang mengizinkan bot itu. Jawaban dan cara permintaan dinilai ada di Bot suara — Menelepon.

Mengembalikan: {"voice_call_id": "…"} — hanya berarti permintaan diterima; apakah berdering dan dijawab datang lewat update voice_call. Penolakan: 403 VOICE_OUTBOUND_OFF: <alasan>, 403 USER_UNAVAILABLE (isinya selalu sama), 429, 503 VOICE_UNAVAILABLE. Tidak bisa dipanggil dari jawaban webhook.

answerVoiceCallToolQuery

POST/bot<token>/answerVoiceCallToolQuery

Mengembalikan: True. Jawaban pertama bersifat final. Jika terlambat: 400 TOOL_QUERY_EXPIRED: answered|timeout|cancelled|call_ended|unreachable; ID tidak dikenal: TOOL_QUERY_ID_INVALID; jawaban ditolak: TOOL_RESULT_EMPTY·TOOL_RESULT_INVALID·TOOL_RESULT_TOO_LONG·TOOL_ERROR_TOO_LONG·TOOL_RESULT_REFUSED: <kode>. POST kueri tool dari webhook juga bisa dijawab lewat badan respons.

setVoiceCallApiKey · deleteVoiceCallApiKey

POST/bot<token>/setVoiceCallApiKey

Mengembalikan: True — kunci baru disimpan setelah lolos sesi uji gateway. API_KEY_INVALID, API_KEY_NO_REALTIME_ACCESS, 503 API_KEY_CHECK_UNAVAILABLE (tidak disimpan), 403 VOICE_OWN_KEY_NOT_AVAILABLE (server ini tidak menerima kunci sendiri). deleteVoiceCallApiKey tanpa parameter dan selalu mengembalikan True. Kedua metode tidak bisa dipanggil lewat bots.sendCustomRequest, dan setVoiceCallApiKey juga tidak bisa dipanggil lewat respons webhook. Detailnya di Kunci model sendiri.

Metode server MCP

auth dan rahasia hanya dikirim di badan permintaan. Di server yang MCP-nya mati: 403 VOICE_NOT_AVAILABLE: MCP tools are not available on this server. Detailnya di Bot suara — Server MCP.

Menerima update suara

voice_call, voice_call_tool_query, dan voice_call_transcript hanya datang jika diminta dengan menyebut namanya — tulis di allowed_updates milik getUpdates atau setWebhook. Dengan daftar kosong tidak datang, dan yang terjadi sebelum diminta tidak ditumpuk. Kueri tool datang lewat POST terpisah jika ada webhook, atau di urutan paling depan getUpdates berikutnya jika getUpdates dipanggil dalam 15 detik terakhir.

VoiceCall

VoiceCall tidak punya field yang menunjukkan apakah penelepon memilih Simpan percakapan. Ini disengaja — teks itu milik penelepon dan tidak dikirim ke bot. Karena itu, di server yang menyalakan Simpan percakapan, ended untuk semua panggilan yang bukan mode stream menunggu dengan lama yang sama, dan nomor pesan berikutnya setelah catatan panggilan selalu setidaknya 31 lebih besar daripada nomor catatan itu di semua panggilan (nomornya dipesan lebih dulu).

VoiceCallToolQuery

VoiceCallTranscript

Hanya datang lewat HTTP Bot API. Transkrip lengkap panggilan ada di transcript pada voice_call yang sudah berakhir.

Mode stream (mode=stream)

Dalam mode stream, audio panggilan dikirim ke server milik pemilik bot, bukan ke model AI Pabal. Jika Anda mengirim mode=stream, stream_url=wss://…, dan stream_secret=… (32–128 karakter ASCII yang dapat dicetak, hanya di badan permintaan) ke setVoiceCallSettings, gateway Pabal mencoba tersambung sekali ke alamat itu (probe), dan jika berhasil, mode ini menyala. Diperlukan ketentuan pemilik bot dan build aplikasi yang memuat layar konfirmasi mode stream. Pengaturan, hasil probe, dan contohnya ada di Bot suara — Mode stream.

• Koneksi: TLS 1.2 ke atas, sertifikat publik yang cocok dengan nama di URL, subprotokol pabal.voice.v1, tanpa kompresi, paling besar 64 KiB per pesan dan 4 KiB per teks, tanpa pengalihan.
• Tanda tangan: X-Pabal-Voice-Signature: t=…,nonce=…,call=…,v1=HMAC-SHA256(stream_secret, "pabal-voice-stream/1\n<t>\n<nonce>\n<call>\n<host>\n<path?query>"). host adalah host URL yang Anda berikan. Periksa 300 detik, nonce sekali pakai, perbandingan byte demi byte, dan apakah start.call_id sama dengan call (selengkapnya).
• Audio: pesan teks adalah event JSON, biner adalah PCM16 little-endian, mono, 24 kHz. Suara penelepon datang dalam potongan 20 ms (960 byte).
• Pabal → bot: start (sekali) · live (pengumuman AI selesai) · audio · mark · cleared · buffer_full · stop (→ tutup 1000).
• Bot → Pabal: ready (dalam 3 detik setelah start, paling pertama) · audio (setelah live) · clear · mark · hangup.

Bentuk setiap pesan ada di tabel Bot suara — Spesifikasi.

Error metode suara

Kode error metode suara dan artinya dikumpulkan di Bot suara — Error. 403 berbentuk Forbidden: <kode>: <keterangan> (VOICE_RULES_NOT_ACCEPTED, VOICE_NOT_AVAILABLE, VOICE_SUSPENDED, VOICE_OWNER_TERMS_NOT_ACCEPTED, VOICE_OWN_KEY_NOT_AVAILABLE, VOICE_STREAM_NOT_AVAILABLE, VOICE_OUTBOUND_OFF); USER_UNAVAILABLE selalu persis Forbidden: USER_UNAVAILABLE tanpa keterangan, dan jika batas per jam terlampaui, hasilnya 429 dengan retry_after.

Perbedaan dengan Bot API Telegram

• Jenis update: hanya message, edited_message, callback_query, dan jenis bot suara yang khusus ada di Pabal (voice_call, voice_call_tool_query, voice_call_transcript). Postingan kanal, inline query, pembayaran, jajak pendapat, 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, berkas (sendDocument), lokasi, lokasi langsung, tempat, dan kontak. Pesan yang diputar sebagai video atau suara, stiker, album (sendMediaGroup), jajak pendapat, dan pengiriman lewat URL tidak ada. Unggahan dan unduhan lewat HTTP dibatasi 20MB.
• Lokasi: peringatan kedekatan lokasi langsung (proximity_alert_radius) hanya disimpan, tidak pernah dikirim. Perpindahan dalam 10 detik atau 10 m dilewati tanpa diterapkan, dan kartu kontak yang dikirim bot tidak membawa user_id.
• 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, sendVideo, sendPoll, getChatMember, banChatMember, answerInlineQuery …) menghasilkan 404 Not Found: method not found.