Pengembangan bot

Bot suara

Saat seseorang menelepon bot dari aplikasi, model suara AI yang menjawab. Cara menyalakan, instruksi dan suara, notifikasi panggilan, tool, server MCP, kunci sendiri, transkrip, mode stream, hingga Apple Watch dan Simpan percakapan — panduan untuk pemilik bot.

Bot suara adalah bot yang bisa ditelepon dari aplikasi. Yang menjawab telepon bukan kode milik pemilik bot, melainkan model suara AI milik Pabal; lewat Bot API, pemilik bot menentukan instruksi, salam pembuka, suara, bahasa, dan batas yang harus diikuti model itu. Setiap kali panggilan dimulai dan berakhir, pemilik bot menerima update voice_call, dan selama panggilan ia bisa meminta model memanggil kode bot (tool) untuk mencari pesanan atau memeriksa reservasi. Ada juga mode stream, yaitu server Anda sendiri yang langsung menerima audionya sebagai ganti model AI. Jika ini bot pertama Anda, mulailah dari Membuat bot.

Status saat ini

• Penelepon (orang yang menelepon) harus berusia 19 tahun ke atas; sebelum menelepon ia melihat layar konfirmasi "An AI answers this call" ("Panggilan ini dijawab oleh AI"), dan setelah tersambung ia lebih dulu mendengar pengumuman suara tentang AI (Yang dilihat penelepon). Aplikasi tanpa layar konfirmasi (termasuk aplikasi Telegram asli dan klien seperti Telethon) tidak menampilkan tombol panggil bot.
• Audio panggilan terkelola dikirim ke Google — Gemini Live API milik Vertex AI, di Iowa, Amerika Serikat (Google Cloud us-central1). Pabal tidak menyimpan audio. Google tidak menyimpan audio maupun teks setelah membuat jawaban, tetapi konten yang dicurigai sebagai penyalahgunaan oleh pemeriksaan otomatisnya bisa dicatat hingga 90 hari (sama dengan isi layar konfirmasi). Hanya mesin ini yang dipakai di produksi, dan Pabal tidak diam-diam mengalihkan ke penyedia lain (tidak ada peralihan otomatis).
• Berbeda dengan panggilan antarmanusia, panggilan ke bot tidak dienkripsi ujung ke ujung: gateway suara Pabal mendekripsi audio lalu meneruskannya ke model AI. Layar konfirmasi penelepon memberitahukan hal ini.

Beginilah alur satu panggilan

Panggilan dari Apple Watch (sedang disiapkan)

Aplikasi jam tangan tidak memakai MTProto. Jam tangan masuk lewat API jam tangan di server (JSON lewat HTTPS), menerima daftar bot dan layar konfirmasi, lalu menelepon. Server menjalankan keputusan penerimaan yang sama seperti untuk panggilan dari aplikasi, lalu memberi jam tangan tiket sekali pakai (15 detik) yang hanya berlaku untuk panggilan itu, dan menyerahkan panggilan ke gateway. Jam tangan membawa tiket itu ke pintu masuk audio (WSS, pabal-voice-edge), dan pintu masuk menyambungkan audionya ke proses gateway yang menangani panggilan itu. Tidak ada pertukaran kunci (DH) maupun relay panggilan (coturn). Namun gateway tetap membuka audio untuk diteruskan ke model, jadi panggilannya tidak dienkripsi ujung ke ujung, dan audionya dikirim ke tempat yang sama. Pemilik bot menerima voice_call yang sama persis dengan panggilan dari aplikasi (hanya waktu started yang berbeda, lihat di bawah).

Menyalakan panggilan suara

Panggilan suara dinyalakan oleh manusia di @BotFather — menyetujui aturan bot suara adalah janji pemilik bot, bukan janji token. Pengaturan lainnya bisa diatur di @BotFather maupun lewat Bot API.

1. Minta operator mengizinkan bot Anda. Di server yang hanya menerima bot yang diizinkan (bawaannya), selama operator belum mengizinkan bot itu dengan ID bot (angka sebelum : di token) di tab Suara halaman admin, @BotFather tidak menampilkan tombol panggilan suara, dan mengubah pengaturan menghasilkan 403 VOICE_NOT_AVAILABLE. Sebelum peluncuran publik, minta juga agar akun yang akan Anda pakai untuk mencoba dijadikan penguji (ID pengguna Anda adalah message.from.id di getUpdates setelah Anda mengirim pesan ke bot).
2. Tulis instruksinya. Ini teks yang menjelaskan apa yang dilakukan bot di telepon. Atur dengan setVoiceCallSettings di bawah, atau kirim lewat tombol Instruksi (지시문) di layar panggilan suara @BotFather. Tanpa instruksi, fitur ini tidak bisa dinyalakan (kecuali mode stream).
3. Di @BotFather: /mybots → bot Anda → Panggilan suara (음성 통화) → Nyalakan (켜기). Pertama kali, aturan bot suara akan muncul; tekan Setujui aturan dan nyalakan (규칙에 동의하고 켜기) untuk menyalakan. Selanjutnya BotFather hanya bertanya "Nyalakan?" (켤까요?).
4. Tunggu izin ulang. Di server yang hanya menerima bot yang diizinkan, izin berlaku untuk instruksi, salam pembuka, dan tool pada saat itu, jadi jika Anda mengubah instruksi setelah diizinkan, hasilnya unavailable_reason: "awaiting_review". Bot baru menerima telepon lagi setelah operator memeriksa dan mengizinkannya kembali. Hal yang sama berlaku setiap kali Anda mengubah salah satu dari ketiganya (atau alamat stream dalam mode stream). Jika bahasa bot bukan bahasa Korea atau Inggris, bot baru menerima telepon setelah operator membaca instruksi dan salam pembukanya lalu mengizinkannya, bahkan di server yang menerima semua bot (Suara dan bahasa).
5. Pastikan available di getVoiceCallSettings bernilai true, lalu coba telepon lewat tombol panggil di profil bot dari build aplikasi yang memuat layar konfirmasi.

Saat ini BotFather membalas dalam bahasa Korea. Isi aturannya: 1. bot selalu mengaku sebagai AI dan tidak boleh dibuat berpura-pura menjadi manusia; 2. bot tidak boleh meniru lembaga, perusahaan, atau orang yang nyata; 3. bot tidak boleh dibuat menanyakan nomor kartu, nomor identitas kependudukan, kata sandi, atau kode verifikasi; 4. Pabal tidak menyimpan audio panggilan, dan audio itu dikirim ke Google (Vertex AI) untuk membuat jawaban; 5. hanya orang berusia 19 tahun ke atas yang boleh menelepon bot; 6. jika aturan dilanggar, operator bisa menghentikan panggilan suara atau botnya. Setelah disetujui, BotFather memberi tahu bahwa panggilan suara sudah menyala, menampilkan statusnya (suara Kore, bahasa Korea, …), dan mengingatkan bahwa setiap panggilan diawali pengumuman "You're now talking to an AI voice bot." sebelum bot menyapa.

Di server yang hanya menerima bot yang diizinkan, statusnya bisa tampil seperti ini: "켜짐 — 바뀐 지시문·인사말을 운영자가 확인할 때까지 전화를 받지 않아요" ("Menyala — tidak menerima telepon sampai operator memeriksa instruksi dan salam pembuka yang diubah") (langkah 4 di atas). Jika bahasa bot bukan bahasa Korea atau Inggris, di server mana pun statusnya tampil seperti ini sampai operator mengizinkannya: "켜짐 — 한국어·영어가 아닌 봇은 운영자가 지시문·인사말을 읽고 허용할 때까지 전화를 받지 않아요 (자동 규칙 검사가 한국어와 영어만 읽어요)" ("Menyala — bot yang bahasanya bukan bahasa Korea atau Inggris tidak menerima telepon sampai operator membaca instruksi dan salam pembukanya lalu mengizinkannya (pemeriksaan aturan otomatis hanya membaca bahasa Korea dan Inggris)").

Layar panggilan suara punya tombol nyalakan/matikan, instruksi, salam pembuka, suara, bahasa, batas, pemakaian, transkrip, kunci sendiri, mode stream, dan (di server yang MCP-nya menyala) server MCP. Bahkan setelah suara dimatikan atau izinnya dicabut, mematikan dan menghapus selalu bisa dilakukan — mematikan suara, menghapus kunci sendiri, mematikan mode stream, menghapus server MCP.

Nama bot juga diperiksa terhadap peniruan identitas, saat dinyalakan dan pada setiap panggilan. Bot yang memakai nama lembaga atau perusahaan yang nyata tidak bisa dinyalakan: VOICE_CONTENT_REFUSED: name: impersonation. Jika bot itu memang milik lembaga tersebut, hubungi layanan pelanggan server.

Pengaturan — setVoiceCallSettings

Menentukan pengaturan suara bot. Ini perubahan sebagian: hanya yang Anda kirim yang berubah; server memeriksa semuanya lalu menulisnya sekaligus, atau menolak semuanya. Jika tidak ada yang berubah, tidak ada yang ditulis.

curl -s "https://pabal.me/bot$BOT_TOKEN/setVoiceCallSettings" -H 'Content-Type: application/json' -d '{
  "instructions": "Anda adalah petugas telepon toko Bantu Pesan. Jawab dengan singkat dan sopan. Toko buka pukul 10.00 sampai 20.00.",
  "greeting": "Bantu Pesan, selamat siang. Ada yang bisa kami bantu?",
  "voice": "kore",
  "language": "ko-KR",
  "max_call_duration": 180
}'
# {"ok":true,"result":true}

• Aturan konten: instruksi, salam pembuka, dan deskripsi tool diperiksa saat disimpan dan pada setiap panggilan. Menyuruh bot mengaku manusia (claims_human), menyembunyikan bahwa ia AI (hides_ai), menyuruhnya mengabaikan aturan Pabal (overrides_rules), meniru lembaga atau perusahaan yang nyata (impersonation), memperkenalkan diri sebagai lembaga resmi (official_claim), menanyakan nomor kartu, nomor identitas kependudukan, kata sandi, atau kode verifikasi (asks_secrets), teks yang tampak seperti kunci rahasia (looks_like_secret), dan karakter tak terlihat (hidden_text) ditolak dengan VOICE_CONTENT_REFUSED: <kolom>: <kode>. Kalimat penyangkalan seperti "Jangan pernah menanyakan kata sandi" tetap lolos.
• Aturan dasar Pabal selalu didahulukan. Pada setiap panggilan, model membaca berurutan: aturan Pabal → instruksi pemilik bot → penutup aturan Pabal, dan instruksi ditempatkan di dalam blok yang ditandai sebagai "teks pemilik bot". Instruksi tidak bisa menggantikan atau mendahului aturan Pabal.
• Bisa diubah hingga 30 kali per jam (termasuk lewat @BotFather, dan hanya perubahan yang benar-benar terjadi yang dihitung). Jika lebih: 429 Too Many Requests: retry after N beserta parameters.retry_after.
• Jika dikirim sebagai formulir (-d name=value), isi tools sebagai string JSON.
• Bot yang hanya masuk lewat MTProto mengirim JSON yang sama dengan bots.sendCustomRequest (Bot MTProto).

Melihat pengaturan saat ini — getVoiceCallSettings

curl -s "https://pabal.me/bot$BOT_TOKEN/getVoiceCallSettings"

{
  "ok": true,
  "result": {
    "enabled": true,
    "available": true,
    "suspended": false,
    "rules_accepted": true,
    "instructions": "Anda adalah petugas telepon toko Bantu Pesan. …",
    "greeting": "Bantu Pesan, selamat siang. Ada yang bisa kami bantu?",
    "voice": "kore",
    "language": "ko-KR",
    "max_call_duration": 180,
    "max_concurrent_calls": 2,
    "limits": {"max_call_duration": 600, "max_concurrent_calls": 2, "bot_minutes_per_day": 60, "owner_minutes_per_day": 120},
    "voices": [{"id": "zephyr", "name": "Zephyr", "description": "Bright"}, …],
    "languages": ["ko-KR", "en-US", "ja-JP", "cmn-CN", "fr-FR", "es-US", "id-ID", "vi-VN", "ar-EG"],
    "testers_only": true,
    "mode": "managed",
    "has_stream_secret": false,
    "owner_terms_accepted": false,
    "stream_available": false,
    "updated_date": 1790380712,
    "tools": [],
    "tool_limits": {"max_tools": 16, "max_definition_bytes": 8192, "definition_bytes": 0, "mcp_tools": 0},
    "tool_delivery": "none",
    "transcript": false,
    "transcript_available": false,
    "transcript_delivery": "get_updates",
    "has_api_key": false,
    "own_keys_available": false,
    "mcp_available": false
  }
}

Suara dan bahasa

Pilih dari 30 suara siap pakai Gemini Live (bawaan kore). Tidak ada fitur mengunggah atau mengkloning suara. Di tombol Suara (목소리) @BotFather, Anda memilih berdasarkan nama dan karakternya.

Bahasa (language) adalah salah satu dari 9 bahasa di bawah. Inilah bahasa yang diucapkan dan dipahami bot, dan bot menjawab dalam bahasa ini. Di @BotFather, pilih lewat tombol Bahasa (언어) di layar panggilan suara.

• Bot yang bahasanya bukan bahasa Korea atau Inggris baru menerima telepon setelah operator membaca instruksi dan salam pembukanya lalu mengizinkannya — bahkan di server yang menerima semua bot. Alasannya, pemeriksaan aturan otomatis saat pengaturan disimpan (berpura-pura menjadi manusia, peniruan identitas, dan sebagainya) hanya membaca bahasa Korea dan Inggris. Sebelum diizinkan, hasilnya unavailable_reason: "awaiting_review", dan jika instruksi, salam pembuka, atau tool diubah setelah diizinkan, bot kembali menunggu izin. Di layar pemilihan bahasa dan setelah bahasa dipilih, @BotFather memberi tahu: "한국어·영어가 아닌 언어는 자동 규칙 검사가 읽지 못해서, 운영자가 지시문·인사말을 읽고 허용한 뒤에 전화를 받아요." ("Bahasa selain bahasa Korea dan Inggris tidak bisa dibaca oleh pemeriksaan aturan otomatis, jadi bot baru menerima telepon setelah operator membaca instruksi dan salam pembukanya lalu mengizinkannya"). Di tab Suara halaman admin, bot itu tampil sebagai "한국어·영어가 아닌 봇 (자동 규칙 검사가 읽지 못함): 지시문·인사말을 읽어 주세요" ("Bot yang bahasanya bukan bahasa Korea atau Inggris (tidak terbaca oleh pemeriksaan aturan otomatis): bacalah instruksi dan salam pembukanya").
• Harus ada gateway yang bisa menangani panggilan dalam bahasa bot. Saat tersambung ke server, gateway menyatakan bahasa bot yang bisa ia tangani (sejak 0.7.0 mendukung kesembilannya), dan gateway yang tidak menyatakan bahasa dianggap hanya menangani bahasa Korea dan Inggris. Jika tidak ada gateway yang bisa menangani panggilan dalam bahasa bot itu, hasilnya no_gateway_with_language dan tombol panggil disembunyikan. Panggilan tidak dilayani dalam bahasa lain sebagai gantinya.
• Huruf besar dan kecil pada id tidak dibedakan (ja-jp pun diterima), dan id disimpan dalam bentuk yang ada di daftar. Nilai yang tidak ada di daftar ditolak dengan VOICE_LANGUAGE_INVALID: language is one of ko-KR, en-US, ja-JP, cmn-CN, fr-FR, es-US, id-ID, vi-VN, ar-EG, yang sekaligus menyebutkan id yang diterima.
• Jika bahasa yang dipilih kemudian dikeluarkan dari daftar, bot itu tidak menerima telepon meskipun pengaturannya tetap tersimpan (text_refused). Bot tidak menerima telepon dalam bahasa lain sebagai gantinya, jadi pilih lagi lewat Bahasa (언어) di @BotFather.
• Bahasa Khmer belum bisa dipilih sebagai bahasa bot. Model memang memahaminya, tetapi jawaban bebasnya belum diperiksa oleh penutur asli bahasa Khmer.

Jika penelepon terus berbicara dalam bahasa lain, model menjawab dalam bahasa itu. Pengumuman suara AI tidak memakai language bot, melainkan bahasa layar konfirmasi yang dilihat penelepon (Yang dilihat penelepon).

Menerima notifikasi panggilan — voice_call

Saat ada yang menelepon bot, update voice_call datang. Ketiga update suara (voice_call, voice_call_tool_query, voice_call_transcript) hanya datang jika diminta dengan menyebut namanya: masukkan ke allowed_updates milik getUpdates atau setWebhook. Dengan daftar kosong pun tidak datang (untuk jenis lain, daftar kosong berarti semuanya datang).

curl -s "https://pabal.me/bot$BOT_TOKEN/getUpdates" -H 'Content-Type: application/json' \
  -d '{"allowed_updates": ["message", "voice_call", "voice_call_tool_query"], "timeout": 30}'

{
  "update_id": 7,
  "voice_call": {
    "id": "4611686018427387905",
    "direction": "incoming",
    "event": "started",
    "from": {"id": 100002, "is_bot": false, "first_name": "Minji", "language_code": "ko"},
    "date": 1790380803,
    "max_duration": 180
  }
}

{
  "update_id": 9,
  "voice_call": {
    "id": "4611686018427387905",
    "direction": "incoming",
    "event": "ended",
    "from": {"id": 100002, "is_bot": false, "first_name": "Minji", "language_code": "ko"},
    "date": 1790380952,
    "start_date": 1790380803,
    "duration": 149,
    "max_duration": 180,
    "end_reason": "caller"
  }
}

• direction: "incoming" untuk panggilan ke bot, "outgoing" untuk panggilan yang dibuat bot (update panggilan dari bot). Membaca kolom yang tidak ada sebagai panggilan ke bot, seperti sebelumnya, tetap benar.
• allowed_updates adalah satu pengaturan per bot, dan yang tersimpan adalah nilai terakhir yang diberikan getUpdates atau setWebhook (jika tidak diberikan, nilai sebelumnya tetap berlaku). Karena itu, jika Anda memberi daftar seperti contoh di atas, jenis bawaan yang tidak Anda tulis di daftar (edited_message, callback_query) tidak akan datang lagi — tulis semua jenis yang dipakai bot Anda. Notifikasi panggilan yang terjadi sebelum Anda memintanya tidak ditumpuk, jadi tidak akan datang meskipun Anda memintanya belakangan.
• Dari penelepon (from), yang dikirim hanya ID, nama, dan bahasa aplikasinya. Nama pengguna dan nomor telepon tidak dikirim (itulah yang dijanjikan layar konfirmasi). Akun yang sudah dihapus muncul sebagai first_name: "Deleted Account".
• Dengan webhook, update ini datang berurutan lewat POST seperti update lain. Antrean getUpdates menyimpan 1.000 update terakhir per bot di memori dan hilang saat server dimulai ulang.
• Bot yang ditangguhkan atau dihapus tidak menerima apa pun.

end_reason: caller (penelepon menutup telepon) · bot (bot menutup, endVoiceCall) · max_length (durasi maksimum) · failed (sambungan gagal) · operator (operator atau sakelar darurat) · suspended (bot ditangguhkan atau dihapus).

Untuk setiap panggilan yang diteruskan ke gateway, catatan panggilan (durasi panggilan, atau "panggilan dibatalkan") tertinggal di obrolan antara penelepon dan bot (panggilan yang ditolak sebelum diterima tidak meninggalkan catatan). Salinan di sisi bot tidak datang sebagai update message — catatan milik bot adalah voice_call. Jika penelepon memilih Simpan percakapan, teks percakapannya tertinggal hanya di obrolan penelepon, tepat di bawah catatan panggilan, dan tidak ada apa pun yang tertinggal di sisi bot. Di server yang menyalakan Simpan percakapan, 30 nomor pesan setelah catatan panggilan dipesan lebih dulu, jadi nomor pesan berikutnya setelah catatan panggilan setidaknya 31 lebih besar daripada nomor catatan itu (juga untuk panggilan yang tidak disimpan).

Selama panggilan

Menutup telepon — endVoiceCall

curl -s "https://pabal.me/bot$BOT_TOKEN/endVoiceCall" -d voice_call_id=4611686018427387905

• farewell (Boolean, bawaan true): jika panggilan sudah tersambung, model mengucapkan salam perpisahan singkat lalu menutup. Jika belum tertutup dalam 10 detik, server yang mengakhirinya. Jika false, langsung ditutup. Panggilan mode stream selalu langsung ditutup.
• Untuk panggilan yang diakhiri dengan cara ini, voice_call.end_reason bernilai bot. Jika bukan panggilan aktif milik bot ini: 400 VOICE_CALL_NOT_FOUND.

Memberi catatan kepada model — sendVoiceCallContext

Memberi tahu model hal yang perlu ia ketahui selama panggilan. Model membacanya sebagai teks pemilik bot, bukan ucapan penelepon, dan aturan Pabal tetap didahulukan.

curl -s "https://pabal.me/bot$BOT_TOKEN/sendVoiceCallContext" -d voice_call_id=4611686018427387905 \
  --data-urlencode "text=Penelepon ini baru saja membatalkan pesanan A-1042. Jika ditanya, sampaikan hal itu." -d respond=false

• text: hingga 2.000 karakter (6.144 byte), diperiksa dengan aturan konten. Jika respond=true, model langsung bereaksi; jika false (bawaan), catatan dipakai pada giliran berikutnya.
• Catatan juga dikirim ke model (ke Google untuk panggilan terkelola), dan model bisa menyampaikannya kepada penelepon — isilah hanya hal yang boleh diketahui penelepon.
• Sebelum tersambung: 400 VOICE_CALL_NOT_ACTIVE; panggilan mode stream atau gateway yang tidak menerima catatan: 400 VOICE_CONTEXT_NOT_SUPPORTED; lebih dari 10 per menit per panggilan: 429 (retry_after 60).

Pemakaian — getVoiceCallUsage

curl -s "https://pabal.me/bot$BOT_TOKEN/getVoiceCallUsage?period=today"

{"ok": true, "result": {"period": "today", "from_date": 1790348400, "to_date": 1790434799,
 "calls": 3, "seconds": 412, "missed": 1,
 "refused": {"busy": 0, "budget": 0, "unavailable": 0},
 "platform_seconds": 412, "own_key_seconds": 0,
 "remaining_seconds_today": {"bot": 3188, "owner": 6788}}}

• period: today (bawaan) atau month. Dengan month, Anda bisa memilih bulannya, misalnya month=2026-09 (bulan yang belum tiba menghasilkan VOICE_USAGE_PERIOD_INVALID).
• Batas hari dan bulan mengikuti zona waktu server (bawaan Asia/Seoul). remaining_seconds_today adalah batas harian dikurangi panggilan yang sudah selesai dan waktu yang sedang dicadangkan oleh panggilan yang masih berlangsung.
• Catatan pemakaian tiap panggilan (tanpa data penelepon) disimpan 180 hari setelah bulannya berakhir, dan total bulanan tetap ada selama bot masih ada.

Tool — memanggil kode bot selama panggilan

Jika penelepon bertanya "Pesanan A-1042 saya sudah sampai mana?", model memanggil tool check_order milik bot, server meneruskan kueri itu ke bot, lalu model menyampaikan jawaban bot secara lisan. Tool didefinisikan oleh pemilik bot, dan kode bot yang menjawabnya.

Mendefinisikan tool

curl -s "https://pabal.me/bot$BOT_TOKEN/setVoiceCallSettings" -H 'Content-Type: application/json' -d '{
  "instructions": "Anda adalah petugas telepon toko Bantu Pesan. Jawab dengan singkat dan sopan. Jika penelepon menyebut nomor pesanan, cari status pengirimannya dengan tool check_order lalu sampaikan.",
  "tools": [{
    "name": "check_order",
    "description": "Mencari status pengiriman berdasarkan nomor pesanan. Dipanggil saat penelepon menyebut nomor pesanan.",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string", "description": "Nomor pesanan, misalnya A-1042"}},
                   "required": ["order_id"]},
    "timeout_ms": 5000
  }]
}'

parameters hanya memakai sebagian dari JSON Schema yang diterima oleh kedua mesin.

• Kata kunci hanya sepuluh: type, description, enum, properties, required, items, minimum, maximum, minItems, maxItems. type hanya satu (string·number·integer·boolean·array·object).
• properties·required untuk object, items·minItems·maxItems untuk array (items wajib), minimum·maximum untuk angka, enum hanya untuk string (1–32 nilai, masing-masing 64 byte).
• Nama properti [A-Za-z_][A-Za-z0-9_]{0,63}, 24 properti per tool, object paling dalam 3 tingkat dan gabungan object dan array paling dalam 5 tingkat. Deskripsi parameter 512 byte.
• Parameter yang menanyakan rahasia ditolak: jika namanya berisi kata seperti pin·cvv·password·otp·ssn·rrn·cardnumber, atau deskripsinya menyebut nomor kartu, kata sandi, kode verifikasi, atau nomor identitas kependudukan, hasilnya asks_secrets.
• Error menyebutkan masalah pertama beserta jalurnya: VOICE_TOOL_INVALID: tools[0].parameters.properties.tags: items_missing, VOICE_TOOL_INVALID: tools[0].name: reserved, VOICE_CONTENT_REFUSED: tools[0].description: impersonation.
• Tool hanya diatur lewat Bot API. Layar panggilan suara @BotFather hanya menampilkan nama tool.
• Di server yang hanya menerima bot yang diizinkan, menambah atau mengubah tool membuat bot tidak menerima telepon sampai operator mengizinkannya lagi (awaiting_review, langkah 4 di Menyalakan).

Menerima kueri tool

{
  "update_id": 813,
  "voice_call_tool_query": {
    "id": "8190448532776044545",
    "voice_call_id": "4611686018427387905",
    "from": {"id": 100002, "is_bot": false, "first_name": "Minji", "language_code": "ko"},
    "name": "check_order",
    "arguments": "{\"order_id\":\"A-1042\"}",
    "budget_ms": 4700
  }
}

• arguments adalah teks sebuah objek JSON (paling banyak 4.096 byte dan kedalaman 8, sudah diperiksa server). Meski begitu, itu adalah nilai yang dibuat model dari ucapan penelepon, jadi periksa ulang di bot. Mengetahui nomor pesanan saja tidak boleh cukup untuk mendengar pesanan orang lain — beri tahu hanya data milik from.id (penelepon yang sudah diverifikasi Pabal).
• budget_ms adalah milidetik sejak bot menerimanya sampai jawaban harus tiba di server. Nilainya adalah timeout_ms tool dikurangi jalur kembali ke model (200 ms) dan jalur sampai ke bot (100 ms), jadi biasanya sekitar 300 ms lebih kecil dari timeout_ms. Jam kedua pihak tidak dipakai.

Jalur kueri menuju bot ditentukan dengan urutan ini (getVoiceCallSettings.tool_delivery).

1. Lewat webhook, jika ada. voice_call_tool_query harus ada di allowed_updates webhook; jika tidak ada, kueri tidak mencari jalur lain dan tidak sampai (tool_delivery_problem: "not_in_allowed_updates"). Kueri adalah POST yang dikirim terpisah, jadi tidak tertahan oleh antrean berurutan, dan tidak dikirim ulang.
2. Jika tidak ada webhook tetapi bot memanggil getUpdates dalam 15 detik terakhir, kueri ditaruh di urutan paling depan getUpdates berikutnya. Kueri juga harus ada di allowed_updates. Paling banyak 8 kueri menunggu per bot.
3. Selain itu, jika bot tersambung lewat MTProto, lewat updateBotWebhookJSONQuery (tidak bergantung pada allowed_updates).
4. Jika tidak ada satu pun jalur itu, kueri tidak sampai (tool_delivery_problem: "not_listening"), dan model mendengar "The tool could not be reached." ("Tool tidak dapat dihubungi").

Menjawab — answerVoiceCallToolQuery

• Tepat satu dari result dan error (tidak ada keduanya: TOOL_RESULT_EMPTY; ada keduanya: TOOL_RESULT_INVALID). Mengembalikan True.
• Jawaban tool dikirim ke model (ke Google untuk panggilan terkelola), dan model menyampaikan isinya kepada penelepon — isilah hanya hal yang boleh diketahui penelepon.
• Jawaban pertama bersifat final. Untuk kueri yang terlambat atau sudah berakhir: 400 TOOL_QUERY_EXPIRED: <alasan> — answered (sudah dijawab), timeout, cancelled (penelepon menyela dan model menariknya), call_ended, unreachable. ID yang tidak dikenal atau yang sudah lewat 10 menit: TOOL_QUERY_ID_INVALID.
• Jawaban juga diperiksa: karakter tak terlihat dibuang, sedangkan yang tampak seperti rahasia (looks_like_secret), kalimat yang mendorong pelanggaran aturan (overrides_rules·hides_ai·claims_human·asks_secrets), serta nomor kartu atau nomor identitas kependudukan (sensitive_data) menghasilkan TOOL_RESULT_REFUSED: <kode>. Data milik pemilik bot, seperti alamat, nomor telepon, atau URL toko, tetap lolos. Jika melebihi ukuran: TOOL_RESULT_TOO_LONG·TOOL_ERROR_TOO_LONG.
• Dengan webhook, Anda bisa menjawab lewat badan respons — cukup taruh ini di respons 200 untuk POST kueri tool (metode lain tidak dijalankan). Sebelum menjawab, pastikan selalu memeriksa header X-Telegram-Bot-Api-Secret-Token. Jika data pelanggan dimasukkan ke respons tanpa pemeriksaan itu, siapa pun yang mengirim kueri palsu ke alamat tersebut akan mendapatkan jawabannya.

{"method": "answerVoiceCallToolQuery", "tool_query_id": "8190448532776044545",
 "result": {"order_id": "A-1042", "status": "Sedang dikirim", "eta": "Tiba besok siang"}}

Contoh — python-telegram-bot

Ini bot yang menjawab tool check_order di atas. Bot menerima lewat getUpdates dan memproses kueri bersamaan dengan update lain (concurrent_updates) — jika tertunda karena memproses update sebelumnya, budget_ms bisa habis. Pesanan dicari berdasarkan ID pengguna Pabal milik orang yang memesan, dan hanya diberitahukan jika cocok dengan from.id kueri.

# order_voice_bot.py — pip install "python-telegram-bot==22.*"
# Jalankan: read -rs BOT_TOKEN && export BOT_TOKEN
#           CUSTOMER_ID=<ID pengguna Pabal milik pemesan> python3 order_voice_bot.py
# Untuk mencoba, isi CUSTOMER_ID dengan ID Anda sendiri — yaitu message.from.id di getUpdates setelah Anda mengirim pesan ke bot
import json
import os
import re

from telegram import Update
from telegram.error import TelegramError
from telegram.ext import Application, ContextTypes, TypeHandler

SERVER = "https://pabal.me"
CUSTOMER = int(os.environ.get("CUSTOMER_ID", "0"))
ORDERS = {                                    # tabel kecil untuk contoh; aslinya sistem pesanan toko
    (CUSTOMER, "A-1042"): {"status": "Sedang dikirim", "eta": "Tiba besok siang"},
}


def check_order(arguments, caller_id):
    """{"result": …} atau {"error": …} untuk diteruskan apa adanya ke answerVoiceCallToolQuery"""
    order_id = str(json.loads(arguments).get("order_id", "")).strip().upper()
    if not re.fullmatch(r"[A-Z]-\d{4}", order_id):     # argumen dibuat oleh model — periksa ulang
        return {"error": "Nomor pesanannya tidak bisa dipahami. Contoh: A-1042"}
    found = ORDERS.get((caller_id, order_id))          # hanya pesanan milik orang yang menelepon
    if found is None:                                  # pesanan orang lain dijawab sama seperti pesanan yang tidak ada
        return {"error": f"Pesanan {order_id} tidak ditemukan."}
    return {"result": json.dumps({"order_id": order_id, **found}, ensure_ascii=False)}


async def on_update(update: Update, context: ContextTypes.DEFAULT_TYPE):
    q = update.api_kwargs.get("voice_call_tool_query")  # jenis yang tidak dikenal PTB masuk ke api_kwargs
    if q is None:
        return
    if q["name"] == "check_order":
        answer = check_order(q["arguments"], q["from"]["id"])
    else:
        answer = {"error": "Tool tidak dikenal."}
    try:
        await context.bot.do_api_request("answerVoiceCallToolQuery",
                                         api_kwargs={"tool_query_id": q["id"], **answer})
    except TelegramError as e:                         # TOOL_QUERY_EXPIRED: terlambat atau panggilan sudah berakhir
        print("Jawaban tidak diterima:", e, flush=True)


app = (Application.builder().token(os.environ["BOT_TOKEN"])
       .base_url(f"{SERVER}/bot").base_file_url(f"{SERVER}/file/bot")
       .concurrent_updates(True).build())
app.add_handler(TypeHandler(Update, on_update))
app.run_polling(allowed_updates=["message", "voice_call", "voice_call_tool_query"], poll_interval=0, timeout=10)

Karena aiogram melewati jenis update yang tidak dikenalnya, Anda harus menangkap voice_call_tool_query dari update.model_extra lebih dulu di middleware luar dispatcher (dp.update.outer_middleware). Repositori Pabal memiliki contohnya (scripts/bots/voice_tools_aiogram.py); mintalah kepada operator server jika Anda membutuhkannya.

Yang didengar model dan penelepon

• Berhasil: hasilnya menjadi respons fungsi bagi model (sebagai nilai JSON jika berupa JSON). Teks di dalam hasil dibaca hanya sebagai data, tidak pernah sebagai perintah.
• Gagal: model mendengar kalimat pendek dari Pabal dalam bahasa panggilan, lalu menjelaskan keadaannya kepada penelepon — tenggat terlewat: "The tool did not answer in time." ("Tool tidak menjawab tepat waktu"); tidak tersambung: "The tool could not be reached." ("Tool tidak dapat dihubungi"); argumen seperti nomor kartu: "Pabal does not pass on card numbers or national ID numbers." ("Pabal tidak meneruskan nomor kartu atau nomor identitas kependudukan"); dan error dari bot apa adanya. Untuk argumen yang salah, model mendapat petunjuk bagian mana yang salah sehingga bisa memanggil ulang.
• Selama menunggu, gateway mengisi keheningan: setelah 1,5 detik hening, "One moment, let me check." ("Mohon tunggu sebentar, saya periksa dulu") sekali (langsung jika tool itu akhir-akhir ini lambat menjawab), lalu setelah 5 detik "Just a moment longer, please." ("Mohon tunggu sebentar lagi") sekali. Kedua kalimat ini diucapkan bukan dalam bahasa penelepon, melainkan dalam bahasa bot, dan jika belum ada rekaman dalam bahasa itu yang lolos telaah, keduanya diucapkan dalam bahasa Inggris (saat ini yang sudah lolos telaah baru bahasa Korea dan Inggris).
• Jika penelepon memotong pembicaraan (menyela), gateway bisa menarik kueri yang masih terbuka, dan jawaban yang datang setelahnya menghasilkan TOOL_QUERY_EXPIRED: cancelled.

Batas tool

Kueri yang terbuka bersamaan: 2 per panggilan, 8 per bot. Jumlah pemanggilan: 30 per menit per panggilan, 120 per menit per bot. Jika lebih, kueri tidak dikirim ke bot dan model langsung mendengar too_many_open·rate_limited.

Ketentuan pemilik bot

Transkrip, kunci model sendiri, mode stream, server MCP, dan panggilan dari bot hanya bisa dinyalakan setelah menyetujui ketentuan pemilik bot (versi 4). Persetujuan dilakukan oleh manusia di layar panggilan suara @BotFather (dari layar transkrip, kunci sendiri, mode stream, server MCP, atau panggilan dari bot mana pun) — tidak bisa lewat token. Meskipun Anda sudah menyetujui versi sebelumnya, persetujuan akan diminta lagi. Sebelum bagian pemilik bot dimuat di ketentuan layanan server, tombol persetujuan tidak muncul (jika dipanggil sebelum itu: 403 VOICE_OWNER_TERMS_NOT_ACCEPTED).

BotFather menampilkan ketentuan ini dalam bahasa Korea; tombol di bawahnya adalah Setujui ketentuan (약관에 동의하기). Intinya, pemilik bot berjanji:

1. Jika transkrip dinyalakan, Anda menerima teks percakapan yang ditulis AI saat panggilan berakhir; Anda yang memproses dan menjaganya.
2. Saat seseorang menelepon bot yang transkripnya menyala, pengumuman suara lebih dulu memberi tahu, saat tersambung, bahwa teks percakapan dikirim ke pemilik bot.
3. Anda menyimpan teks yang diterima hanya selama diperlukan, menghapusnya jika penelepon meminta, dan tidak memakainya untuk melatih model.
4. Jika memakai kunci model sendiri, audio dan teks panggilan dikirim ke penyedia kunci Anda di bawah kontrak Anda; pemrosesan itu menjadi tanggung jawab Anda, dan pemberitahuan privasi Anda harus menyebutkannya.
5. Dalam mode stream, audio panggilan dikirim ke server Anda, bukan ke model AI Pabal, dan Andalah yang menerima serta memprosesnya; suara dan ucapan penelepon hanya Anda pakai sejauh diizinkan hukum, dan Anda hapus jika tidak lagi diperlukan.
6. Jika penelepon bertanya, Anda memberi tahu di mana server Anda berada dan apa yang dilakukannya (sebaiknya ditulis di deskripsi bot).
7. Bot selalu mengaku sebagai AI dan jawabannya dibuat oleh AI: tidak ada manusia yang menjawab langsung, dan tidak ada rekaman suara manusia yang diputar seolah-olah jawaban AI. Dalam mode stream, Pabal memutar pengumuman "This is an AI voice bot. The call's audio goes to the bot developer's server." di awal panggilan.
8. Anda tidak menanyakan nomor kartu, nomor identitas kependudukan, kata sandi, atau kode verifikasi, dan tetap mematuhi aturan bot suara.
9. Pabal tidak menyimpan teks percakapan: setelah dikirim, teks dihapus dari server paling lambat 24 jam kemudian; kunci serta rahasia mode stream dan server MCP disimpan terenkripsi dan tidak dicatat di mana pun.
10. Jika Anda mendaftarkan server MCP, nilai yang diucapkan penelepon dikirim ke server itu saat model memanggil tool-nya selama panggilan; Anda bertanggung jawab atas pemrosesan oleh server itu dan pihak yang menerima data darinya, dan Anda melaporkan penerimanya dengan jujur.
11. Jika ketentuan ini dilanggar, operator bisa menghentikan panggilan suara atau botnya.

Butir 12–24 adalah yang Anda patuhi saat menyalakan panggilan dari bot: memakainya hanya untuk tujuan yang dinyatakan dan diizinkan operator, tanpa iklan; menyebut nama bot dan bahwa ia AI pada kata pertamanya; tidak memasukkan informasi sensitif ke context; tidak pernah mencoba menelepon orang di bawah 19 tahun; tidak menghindari jam tenang, jeda, atau batas; memakai yang Anda ketahui tentang orang yang ditelepon hanya untuk tujuan itu dan menghapusnya saat izin dimatikan; menjaga token. Panggilan yang dibuat bot tidak membawa transkrip (butir 24). Teks ketentuan bisa berubah setelah tinjauan hukum.

Server MCP

Jika Anda mendaftarkan server MCP yang Anda jalankan (atau yang Anda pakai berdasarkan kontrak), model bisa memanggil tool server itu selama panggilan. Yang memanggil bukan kode bot, melainkan Pabal — klien MCP Pabal mengirim permintaan ke server itu lewat proxy keluar Pabal sambil menegakkan tenggat, ukuran, dan pemeriksaan. Karena itu nilai yang diucapkan penelepon dikirim ke server tersebut (butir 10 ketentuan pemilik bot).

Yang harus dimiliki server MCP

• Streamable HTTP, POST (versi protokol 2024-11-05 atau lebih baru). https:// dengan sertifikat publik, tanpa pengalihan, dan hanya port yang diizinkan server (443 di pabal.me).
• Server yang memakai kredensial harus menolak dengan jujur (401) permintaan tanpa kredensial dan tidak menerima kredensial yang salah. Satu kredensial hanya boleh dipakai satu bot.
• Dokumen operator: operator server menaruh dokumen JSON (maksimal 32 KB, tanpa pengalihan) di https://<host>/.well-known/pabal-voice-mcp — pihak yang menjalankan, negara, kontak, tujuan, jenis dan lokasi data, penerima dan subpemroses, serta masa simpan. Inilah informasi penerima yang tampil di layar konfirmasi penelepon; jika tidak ada, pemilik bot melaporkannya saat mendaftar (lihat di bawah). Server publik yang bisa dipanggil siapa saja tanpa kredensial (auth.type: "none") harus menulis "accepts": "any" di entri endpoint dokumen ini untuk menyatakan bahwa ia menerima panggilan dari Pabal.
• Yang ditambahkan Pabal: _meta pada tools/call berisi sisa tenggat me.pabal/budget_ms (milidetik) dan batas ukuran hasil me.pabal/result_budget_bytes, dan bisa berisi asersi bertanda tangan Pabal (me.pabal/assertion, JWT). Penerbit asersi, sub (bot:<id bot>), dan kunci verifikasinya (JWKS) diberikan oleh getVoiceCallMcpBinding.
• tools/list paling besar 2 MB dan 20 halaman. Tidak boleh ada langkah yang memerlukan manusia (misalnya login di peramban).
• Setiap tool memberi klasifikasinya lewat _meta["me.pabal/voice"] — data (none·caller·third_party), content (system·third_party_text), effect (none·write·notify·financial), max_ms (paling besar 15.000), max_result_bytes (paling besar 65.536), dan opsional p95_ms. Jika server tidak memberikannya, pemilik bot menambahkannya dengan tools saat mendaftar.
• Spesifikasi 1.0 hanya memberi L1: hanya tool dengan data: "none" dan effect: "none" (tool yang hanya membaca informasi publik) yang disematkan pada panggilan. Tool yang menangani data penelepon (L2) atau menjalankan sesuatu (L3) hanya dicatat, tidak dipakai.
• Saat pendaftaran, Pabal menjalankan uji kesesuaian (alamat, TLS, versi, 401, daftar tool, struktur tool, cakupan kredensial, langkah manusia). Jika gagal, pendaftaran ditolak dengan MCP_CONFORMANCE_FAILED: CT-xx.

Mendaftarkan server

Rahasia hanya dikirim di badan permintaan (jika di query string: 400). Agar rahasia tidak tertinggal di baris perintah, simpan di berkas lalu kirim berkas itu.

umask 077
cat > mcp-shop.json <<'EOF'
{"label": "shop",
 "url": "https://mcp.example.com/mcp",
 "auth": {"type": "bearer", "token": "(token dari server MCP)"}}
EOF
curl -s "https://pabal.me/bot$BOT_TOKEN/setVoiceCallMcpServer" -H 'Content-Type: application/json' -d @mcp-shop.json

• label: [a-z][a-z0-9]{0,11}, tidak boleh diawali pabal. 2 server per bot. Nama tool yang dilihat model adalah label__namatool.
• auth.type: none, bearer (token), headers (hingga 3 header), client_credentials (token_url, client_id, client_secret, atau private_key_jwt: true — sebelumnya jalankan createVoiceCallMcpClientKey). authorization_code belum tersedia. none (server publik) baru bisa didaftarkan jika dokumen publik operator server itu menyatakan bahwa ia menerima panggilan dari Pabal (jika tidak, MCP_OPT_IN_REQUIRED).
• Perubahan yang mengganti penerima (server baru, alamat atau host token yang lain, laporan baru, tingkat yang lebih tinggi) dijawab dengan 400 MCP_CHANGE_NEEDS_CONFIRMATION, dan baru berlaku jika pemilik bot menekan tombol Konfirmasi (확인 — 이 변경을 적용) yang muncul di @BotFather dalam 5 menit. Tujuannya agar, meskipun token bocor, ucapan penelepon tidak diam-diam dikirim ke tempat lain. Rotasi yang hanya mengganti rahasia langsung berlaku.
• Jika operator server tidak menaruh dokumen publik, pemilik bot melaporkan penerimanya dengan jujur lewat declaration (pihak yang menjalankan, negara, kontak, tujuan, jenis data, lokasi, subpemroses, masa simpan). Penelepon melihatnya di layar konfirmasi, dan jika berubah, penelepon ditanya lagi.
• Pendaftaran dan pemeriksaan: 10 kali per jam per bot, 20 kali per pemilik. Metode lain: refreshVoiceCallMcpServer (periksa ulang), deleteVoiceCallMcpServer (selalu bisa), getVoiceCallMcpBinding (penerbit, sub, dan JWKS yang dipakai server Anda untuk mengenali panggilan dari Pabal), createVoiceCallMcpClientKey.
• Status server dan tool yang terdaftar muncul di getVoiceCallSettings.mcp_servers (tanpa path, query, atau rahasia). Naskah lengkap spesifikasinya (Pabal Voice MCP Profile 1.0) ada di repositori Pabal, di docs/app/voice-bot-mcp-profile.html; mintalah kepada operator server jika Anda membutuhkannya.

Kunci model sendiri

Alihkan panggilan bot ke akun model milik pemilik bot sendiri. Biayanya dibebankan ke akun penyedia milik pemilik, dan panggilan berkunci sendiri tidak memakai batas harian platform untuk bot, pemilik, dan server (batas penelepon tetap berlaku). Ketentuan pemilik bot harus disetujui lebih dulu.

curl -s "https://pabal.me/bot$BOT_TOKEN/setVoiceCallApiKey" -d provider=google \
  --data-urlencode "api_key@vertex-sa.json"

• provider: google untuk kunci JSON akun layanan Vertex AI (hanya kolom yang diperlukan yang disimpan), openai untuk kunci API yang diawali sk-. Nilai lain: VOICE_PROVIDER_INVALID. Kunci hanya dikirim di badan permintaan (jika di query: 400) — jika dibaca dari berkas seperti di atas, kunci tidak tertinggal di baris perintah. Jangan menempelkannya di obrolan dengan @BotFather.
• Sebelum menerima kunci, server memastikan kunci benar-benar bisa dibuka lewat sesi uji gateway (paling lama 12 detik). Jika lolos, kunci disimpan dan hasilnya True. Jika penyedia menolak: API_KEY_INVALID; jika login berhasil tetapi tidak punya izin API real-time: API_KEY_NO_REALTIME_ACCESS; jika tidak ada gateway untuk menguji atau gateway sibuk: 503 API_KEY_CHECK_UNAVAILABLE: …: the key was not kept.
• Pengujian: 5 kali per jam per bot, 10 kali per pemilik (semua bot digabung). Hanya pengujian yang sampai ke gateway yang dihitung.
• Kunci tidak pernah ditampilkan di mana pun — di jawaban, error, log, maupun layar. getVoiceCallSettings.api_key hanya berisi penyedia, tanggal diatur, sidik jari (8 karakter), dan apakah bisa dipakai.
• Jika kunci yang diatur tidak bisa dipakai (ketentuan berubah, server tidak bisa membuka kunci, dan sebagainya), bot tidak menerima telepon — bot tidak diam-diam beralih ke kunci platform. Jika Anda menghapus kunci dengan deleteVoiceCallApiKey (selalu bisa), panggilan diterima dengan kunci platform, dan panggilan yang sedang berlangsung dengan kunci Anda berakhir.
• Panggilan berkunci sendiri tidak punya batas harian Pabal — yang berlaku hanya durasi satu panggilan, panggilan bersamaan, dan batas penelepon. Biayanya masuk ke akun Anda, jadi pasang peringatan anggaran di konsol penyedia.
• Kunci OpenAI baru dipakai jika operator gateway menyalakannya secara terpisah (bawaan gateway hanya kunci Google). Jika tidak ada gateway yang menyalakannya, pengujian kunci OpenAI menghasilkan 503 … no_gateway. Jalur kunci OpenAI belum pernah diuji dengan OpenAI yang sebenarnya (hanya dengan server tiruan), dan panggilan yang diterima dengan kunci OpenAI memakai suara OpenAI yang ditetapkan gateway (bawaan marin), apa pun pengaturan suara bot. Kunci Google dipakai di wilayah Vertex milik gateway (us-central1).
• Dalam mode stream, kunci hanya disimpan dan tidak dipakai.

Transkrip

Jika dinyalakan, pemilik bot menerima teks percakapan panggilan yang ditulis AI. Setujui ketentuan pemilik bot, lalu nyalakan sakelarnya.

curl -s "https://pabal.me/bot$BOT_TOKEN/setVoiceCallSettings" -d transcript=true

• Panggilan yang dibuat bot tidak punya transkrip (panggilan dari bot) — meskipun sakelarnya menyala.
• Saat seseorang menelepon bot yang transkripnya menyala, penelepon mendengar tepat setelah pengumuman AI: "What is said on this call is written down and sent to the bot's owner." ("Isi percakapan dalam panggilan ini dicatat dan dikirim ke pemilik bot"). Hanya ucapan setelah pengumuman selesai yang dicatat. Panggilan mode stream tidak punya transkrip.
• transcript ikut di dalam voice_call panggilan yang sudah berakhir (event: "ended"). Hanya inilah versi lengkapnya, jadi masukkan voice_call ke allowed_updates. Jika ingin menerima giliran satu per satu selama panggilan, masukkan juga voice_call_transcript (hanya lewat HTTP Bot API, tidak lewat MTProto).
• Giliran yang berisi nomor kartu atau nomor identitas kependudukan dikirim dengan semua angkanya diganti *. Nomor yang diucapkan terpisah dalam dua giliran atau dibacakan dengan kata-kata tidak terdeteksi, jadi tangani teks yang diterima dengan hati-hati juga.
• 4.096 byte per giliran, 256 KiB dan 4.000 giliran per panggilan. Jika lebih, sisanya dibuang dan truncated: true.
• Pabal tidak menyimpan teks percakapan: teks ada di memori selama panggilan, diserahkan sekali ke bot, dan yang tidak diambil dihapus setelah 24 jam. Teks hilang jika server dimulai ulang. Penyimpanan dan pemrosesan setelah diterima menjadi tanggung jawab pemilik bot.

"transcript": {
  "turns": [
    {"role": "bot", "text": "Bantu Pesan, selamat siang. Ada yang bisa kami bantu?", "offset_ms": 5200},
    {"role": "caller", "text": "Pesanan A-1042 saya sudah sampai mana?", "offset_ms": 9800}
  ],
  "truncated": false
}

{"update_id": 21, "voice_call_transcript": {"voice_call_id": "4611686018427387905", "seq": 2,
 "role": "caller", "text": "Pesanan A-1042 saya sudah sampai mana?", "is_final": true, "offset_ms": 9800, "date": 1790380813}}

role adalah caller (penelepon) atau bot (model), dan offset_ms adalah milidetik sejak audio panggilan dimulai.

Mode stream

Dalam mode stream, audio panggilan tidak dikirim ke model AI Pabal, melainkan ke server milik pemilik bot. Server Anda mendengarkan audio mentahnya dan mengirim balik jawaban dalam bentuk audio — AI apa yang dipakai, Anda yang menentukan (model real-time penyedia lain, gabungan pengenalan dan sintesis suara milik Anda). Pabal tetap memutar pengumuman suara AI di awal, dan tetap menegakkan konfirmasi penelepon, batas, durasi panggilan, serta batas panggilan bersamaan. Instruksi tidak diperlukan, sedangkan tool, kunci sendiri, dan transkrip hanya disimpan dan tidak dipakai (stream_ignores).

Pengaturan dan probe

Jalankan dulu server contoh di bawah di alamat publik (nama yang cocok dengan sertifikatnya). Probe langsung tersambung ke server itu saat Anda mengaturnya, dan kegagalan karena tidak bisa tersambung pun dihitung dalam batas 5 kali per jam.

Setelah menyetujui ketentuan pemilik bot (@BotFather → Panggilan suara (음성 통화) → Mode stream (원음 모드) → Setujui ketentuan pemilik bot (봇 주인 약관에 동의)), beri tahu alamat server dan rahasianya. Rahasia berupa 32–128 karakter ASCII yang dapat dicetak (tanpa spasi), dan alamat baru selalu dikirim bersama rahasia baru.

umask 077
openssl rand -hex 32 | tr -d '\n' > stream-secret.txt      # tidak boleh ada baris baru di akhir
curl -s "https://pabal.me/bot$BOT_TOKEN/setVoiceCallSettings" -d mode=stream \
  -d stream_url=wss://bot.example.com:8443/voice --data-urlencode "stream_secret@stream-secret.txt"

1. Format alamat: hanya wss://, tanpa nama pengguna, #, atau spasi, hanya ASCII (karakter lain di-percent-encode), paling panjang 2.048 karakter. Host berupa nama yang mengandung titik atau IP publik (localhost tidak boleh), port 443 atau 1024–65535. Jika tidak: 400 STREAM_URL_INVALID: ….
2. Batas probe dihitung sejak permintaan: 5 kali per jam per bot, 10 kali per pemilik, dan bersamaan paling banyak 1 per bot dan 2 per pemilik. Jika lebih: 429. Probe yang tidak tersambung ke mana pun karena gateway sibuk tidak dihitung.
3. Pemeriksaan alamat: jika nama itu mengarah ke satu saja alamat privat atau alamat yang dicadangkan, atau ke alamat Pabal sendiri: 400 STREAM_URL_INVALID: the host must resolve only to public addresses.
4. Probe: gateway mencoba tersambung sekali ("probe": true di start). Jika ready datang, fitur menyala dan rahasia disimpan terenkripsi di bawah kunci induk server. Jika gagal: 400 STREAM_PROBE_FAILED: <kode> — unreachable (nama, koneksi, waktu, atau TLS), handshake_failed (jawaban selain 101 — biasanya tanda tangannya ditolak), redirect, no_subprotocol, no_ready, bad_ready, address_refused, busy, url, dan lain-lain — kode lainnya diteruskan apa adanya dari gateway. Server menunggu paling lama 12 detik.
5. Jika mode stream dinyalakan atau alamatnya diubah lewat Bot API (token), @BotFather mengirimkan pemberitahuan kepada pemilik bot bahwa alamat stream telah berganti menjadi … (원음 주소가 … 로 바뀌었어요 (비밀 …)) beserta tombol Kembali ke mode terkelola (관리형으로 돌아가기); jika kembali ke mode terkelola, BotFather memberitahukannya beserta tombol Panggilan suara (음성 통화). Tujuannya agar, jika token bocor, audio tidak diam-diam dikirim ke server lain.

• Jika stream_secret dimasukkan ke query string, jawabannya 400 sebelum hal lainnya. Mode stream tidak bisa diatur lewat respons webhook.
• Untuk kembali ke mode terkelola: mode=managed (alamat dan rahasia dihapus). Jika bot menyala dan instruksinya kosong, hasilnya VOICE_INSTRUCTIONS_REQUIRED, jadi kirimkan instruksinya sekaligus.
• Di server yang hanya menerima bot yang diizinkan, bot baru menerima telepon setelah operator memeriksa alamat stream dan mengizinkannya kembali.
• getVoiceCallSettings hanya menampilkan stream_url dan sidik jari rahasianya. Pada panggilan mode stream, sendVoiceCallContext tidak bisa dipakai (VOICE_CONTEXT_NOT_SUPPORTED), dan endVoiceCall langsung menutup tanpa salam perpisahan.

Spesifikasi

• TLS 1.2 ke atas, dengan sertifikat publik yang cocok dengan nama di URL. Gateway tersambung ke IP yang sudah diperiksanya, tetapi SNI dan pemeriksaan sertifikat dilakukan dengan nama itu. Pengalihan (3xx) tidak diikuti.
• Subprotokol pabal.voice.v1 wajib dipilih (Sec-WebSocket-Protocol). Tanpa kompresi. Satu pesan paling besar 65.536 byte, pesan teks paling besar 4.096 byte (UTF-8).
• Gateway mengirim ping setiap 15 detik. Jika tidak ada pong dalam 15 detik, koneksi diputus (sebagian besar pustaka menjawabnya secara otomatis).
• Pesan teks adalah event JSON, pesan biner adalah audio. Format audionya hanya satu: PCM16 little-endian, mono, 24.000 Hz. call_id dan bot_id adalah string desimal.

• event yang tidak dikenal diabaikan. Teks yang bukan JSON, teks lebih dari 4 KiB, serta audio dengan jumlah byte ganjil atau lebih dari 64 KiB adalah pelanggaran spesifikasi dan mengakhiri panggilan (penelepon mendengar pengumuman permintaan maaf).
• Batas atas pengiriman: event teks rata-rata 50 per detik (sesaat 100), audio rata-rata 4 kali kecepatan real-time (sesaat 60 detik). Jika soket bot tidak membaca dan suara penelepon menumpuk lebih dari 30 detik (1.500 potongan), panggilan juga diakhiri.

Tanda tangan

Gateway menambahkan header ini pada permintaan upgrade.

X-Pabal-Voice-Signature: t=<detik Unix>,nonce=<16 byte hex>,call=<call_id>,v1=<hex>
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 kepada Pabal (huruf kecil, tanpa port). Jangan menghitungnya dari header Host permintaan — nilai itu ditulis oleh pengirim, sehingga tidak mengikat tanda tangan ke host mana pun. path?query adalah path dan query URL apa adanya (/ jika tidak ada). Pada probe, call adalah nomor probe.
• Server bot wajib memeriksa: |sekarang − t| ≤ 300 detik, setiap nonce hanya sekali, dan HMAC dibandingkan byte demi byte dengan fungsi waktu-konstan. Jika salah, berikan jawaban selain 101, misalnya 401.
• Lalu periksa apakah start.call_id sama dengan call di tanda tangan. Jika berbeda, tutup dengan 1008 — agar upgrade yang sudah ditandatangani tidak bisa dipakai ulang untuk panggilan lain. Server yang hanya melayani satu bot juga memeriksa apakah start.bot_id adalah bot miliknya.
• Nilai uji: rahasia example-stream-secret-of-the-bot-developer-0001, t=1790000000, nonce 00112233445566778899aabbccddeeff, call 4611686018427387905, host bot.example.com, path /voice?bot=100042 → v1=807517ff96ac75223bde35b48c775f49a2eda2fb4832a02c0ea832b914d70d0c.

Audio · penyelaan · mark · mengakhiri

• Buffer bot → penelepon: gateway mengeluarkan audio sesuai kecepatan putar, jadi Anda boleh mengirim semuanya sekaligus, tetapi jika menumpuk lebih dari 30 detik, kelebihannya dibuang dan buffer_full dikirim. Jeda 300 ms pada audio bot menandai berakhirnya satu "potongan" (satuan untuk mark dan clear).
• clear: membuang semua audio bot yang belum keluar, dan hening dimulai dari 10 ms berikutnya (terukur kurang dari 50 ms). Di jawaban cleared, played_ms adalah total audio bot yang benar-benar diputar dalam panggilan ini sejauh ini, dropped_ms adalah jumlah yang baru dibuang, dan marks adalah nama-nama mark pada potongan yang dibuang — dipakai untuk memberi tahu model "di mana pembicaraan terpotong".
• mark: kembali dengan nama yang sama setelah audio sebelumnya diputar. Sebaiknya audio sebelum mark diakhiri pada kelipatan 480 byte (10 ms); potongan yang tersisa diisi hening.
• Mengakhiri: bot mengirim hangup atau menutup dengan rapi menggunakan 1000 atau 1001. Penutupan lain atau putusnya TCP diperlakukan sama seperti pelanggaran spesifikasi (penelepon mendengar pengumuman permintaan maaf). Jika Pabal yang mengakhiri, stop.reason berupa kode pendek — hangup (penelepon menutup), max_length, bot_ended, disconnect, drain, kill_switch, operator, link_lost, media_failed … Perlakukan nilai yang tidak dikenal sebagai "sudah berakhir".
• start pada probe berisi "probe": true, caller kosong, dan max_seconds: 0. Setelah Anda mengirim ready, datang {"event":"stop","reason":"probe"} lalu koneksi ditutup. Jangan membuka sesuatu yang berbiaya, seperti sesi model, saat probe.

Contoh — server stream paling kecil

Server yang memeriksa seluruh spesifikasi tanpa AI: saat live, ia memutar bunyi penanda, lalu mengembalikan suara penelepon apa adanya (gema). Server ini memeriksa tanda tangan, waktu, nonce, panggilan, dan bot. Pastikan dulu dengan server ini bahwa panggilan berjalan sampai selesai, lalu ganti bagian gema dengan AI Anda. Repositori Pabal juga berisi scripts/bots/stream_echo_bot.py (dengan demo penyelaan) dan scripts/bots/stream_openai_relay.mjs (meneruskan ke Realtime dengan kunci OpenAI Anda — contoh yang belum pernah dijalankan); mintalah kepada operator server jika Anda membutuhkannya.

# stream_bot.py — pip install "websockets>=13"
# Jalankan: STREAM_SECRET_FILE=stream-secret.txt TLS_CERT=fullchain.pem TLS_KEY=privkey.pem \
#           PUBLIC_HOST=bot.example.com BOT_ID=<ID bot — angka sebelum : di token> python3 stream_bot.py
import asyncio
import hashlib
import hmac
import json
import math
import os
import ssl
import struct
import time

from websockets.asyncio.server import serve

SECRET = open(os.environ["STREAM_SECRET_FILE"], "rb").read().strip()
PUBLIC_HOST = os.environ["PUBLIC_HOST"].lower()   # host stream_url yang diberikan ke Pabal (bukan header Host)
BOT_ID = os.environ.get("BOT_ID", "")             # jika kosong, menerima panggilan dari bot mana pun
PATH = os.environ.get("STREAM_PATH", "/voice")
PORT = int(os.environ.get("PORT", "8443"))
CHIME = b"".join(struct.pack("<h", int(8000 * math.sin(2 * math.pi * 880 * i / 24000)))
                 for i in range(24000 * 6 // 10))  # 880 Hz selama 0,6 detik, PCM16 24 kHz
seen = {}                                         # nonce yang sudah dipakai


def signed_call(header, target):
    """Memeriksa X-Pabal-Voice-Signature dan mengembalikan call id yang ditandatangani. None jika salah."""
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t, nonce, call, v1 = int(parts["t"]), parts["nonce"], parts["call"], parts["v1"]
    except (KeyError, ValueError):
        return None
    now = time.time()
    if abs(now - t) > 300 or nonce in seen:
        return None
    text = f"pabal-voice-stream/1\n{t}\n{nonce}\n{call}\n{PUBLIC_HOST}\n{target}"
    expected = hmac.new(SECRET, text.encode("utf-8", "surrogateescape"), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected.encode(), v1.encode("utf-8", "surrogateescape")):  # byte demi byte
        return None
    for old in [n for n, at in seen.items() if at < now - 600]:
        del seen[old]
    seen[nonce] = now
    return call


def check(connection, request):
    if request.path.split("?", 1)[0] != PATH:
        return connection.respond(404, "not here\n")
    call = signed_call(request.headers.get("X-Pabal-Voice-Signature", ""), request.path)
    if call is None:
        return connection.respond(401, "bad signature\n")
    connection.signed_call = call                 # start harus menyebut panggilan ini
    return None


async def handle(ws):
    if ws.subprotocol != "pabal.voice.v1":
        await ws.close(1002, "pabal.voice.v1 only")
        return
    start = json.loads(await asyncio.wait_for(ws.recv(), 5))
    if (start.get("event") != "start" or start.get("call_id") != ws.signed_call
            or (BOT_ID and start.get("bot_id") != BOT_ID)):
        await ws.close(1008, "not this call")
        return
    await ws.send(json.dumps({"event": "ready"}))    # dalam 3 detik, paling pertama
    live = False
    async for message in ws:
        if isinstance(message, bytes):
            if live:
                await ws.send(message)            # mengembalikan 20 ms suara penelepon apa adanya (gema)
            continue
        event = json.loads(message)
        if event.get("event") == "live" and not start.get("probe"):   # pengumuman AI sudah selesai
            live = True
            await ws.send(CHIME)
            await ws.send(json.dumps({"event": "mark", "name": "chime"}))
        elif event.get("event") == "stop":
            print("Selesai:", start["call_id"], event.get("reason"), flush=True)
            break


async def main():
    tls = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
    tls.minimum_version = ssl.TLSVersion.TLSv1_2
    tls.load_cert_chain(os.environ["TLS_CERT"], os.environ["TLS_KEY"])
    async with serve(handle, "0.0.0.0", PORT, ssl=tls, subprotocols=["pabal.voice.v1"],
                     process_request=check, max_size=65536, compression=None):
        print(f"Mendengarkan: wss://{PUBLIC_HOST}:{PORT}{PATH}", flush=True)
        await asyncio.get_running_loop().create_future()


asyncio.run(main())

Yang dilihat penelepon

• Tombol panggil: tombol telepon muncul di kepala obrolan dan di profil bot suara. Tombol ini hanya tampil jika server menilai bisa menerima panggilan dari orang itu di perangkat itu (sebelum peluncuran publik, hanya untuk penguji). Tidak ada panggilan video.
• Layar konfirmasi (sebelum izin mikrofon): judul "An AI answers this call"; bot bukan manusia dan suaranya dibuat oleh AI; panggilan tidak dienkripsi ujung ke ujung; ke mana audio dikirim (Google, Gemini Live API milik Vertex AI) serta negara dan wilayahnya ("United States (Iowa, Google Cloud us-central1)"); apa yang dikirim (suara selama panggilan, teks percakapan dan jawaban AI, catatan yang dimasukkan bot selama panggilan, dan hasil fungsi bot); penyimpanan (Pabal tidak menyimpan audio dan hanya menyimpan catatan panggilan selama 180 hari; Google tidak menyimpan apa pun setelah membuat jawaban, tetapi konten yang dicurigai sebagai penyalahgunaan oleh pemeriksaan otomatisnya bisa dicatat hingga 90 hari); apa yang diterima pemilik bot (nama, nomor akun, bahasa, waktu dan durasi panggilan, nilai yang dipakai tool — bukan nomor telepon dan bukan audio); usia 19 tahun ke atas. Tombolnya "I'm 19 or older · Call" dan Batal. Usia tidak diverifikasi identitasnya, melainkan dikonfirmasi sendiri oleh penelepon. Tombol telepon adalah tombol utama (berisi warna aksen) dan Batal adalah tombol sekunder. Di server yang menyalakan Simpan percakapan, kotak centang "Keep this call's conversation as text in my chat" (awalnya tidak dicentang) ditambahkan setelah penjelasan.
• Seberapa sering: di desktop dan Android, saat pertama kali menelepon bot itu (dan ditanya lagi jika penerima atau versi layarnya berubah); di iPhone dan Apple Watch, setiap kali. Jam tangan selalu menampilkan layar lengkap, dan posisi awal sakelar Simpan percakapan adalah pilihan pada panggilan terakhir ke bot itu. Aplikasi mengirim persetujuan ke server pada setiap panggilan, dan server memakai satu persetujuan — dari perangkat yang sama, untuk bot yang sama, dan berumur kurang dari 2 menit — hanya sekali untuk panggilan itu.
• Saat tersambung: pengumuman suara AI "You're now talking to an AI voice bot." (untuk bot mode stream: "This is an AI voice bot. The call's audio goes to the bot developer's server.") → (untuk bot bertranskrip) pengumuman transkrip → salam pembuka bot. Pemilik bot tidak bisa mematikan pengumuman ini, dan ucapan penelepon sebelum pengumuman selesai tidak dikirim ke model. Simpan percakapan tidak punya pengumuman suara — penelepon sendiri yang memilihnya di layar.
• Bahasa pengumuman: pengumuman suara tidak memakai language bot, melainkan bahasa layar konfirmasi yang dibaca penelepon. Semua pengumuman dalam satu panggilan memakai satu bahasa — pengumuman AI, pengumuman transkrip, dan permintaan maaf saat sambungan terputus (untuk bot mode stream, pengumuman mode stream dan permintaan maaf). Jika salah satunya belum punya rekaman dalam bahasa itu yang lolos telaah, semuanya diucapkan dalam bahasa Inggris. Saat ini bahasa yang sudah lolos telaah baru bahasa Korea dan Inggris. Layar konfirmasi dan pengumuman dalam 8 bahasa lainnya (bahasa Jepang, Tionghoa, Prancis, Spanyol, Indonesia, Vietnam, Khmer, dan Arab) masih berupa draf yang menunggu telaah hukum dan pemeriksaan penutur asli, jadi penelepon yang memakai aplikasi dalam bahasa-bahasa itu pun untuk sementara melihat layar konfirmasi berbahasa Inggris dan mendengar pengumuman berbahasa Inggris. Rekaman bahasa Khmer dan versi bahasa Jepang dari "Just a moment longer, please." ("Mohon tunggu sebentar lagi") masih menunggu didengarkan dan dipilih oleh manusia. Sebelum pengumuman pertama dalam panggilan dan sebelum pengumuman transkrip selalu ada jeda hening minimal 300 ms — agar jalur telepon tidak menelan kata pertama.
• Layar panggilan: di bawah nama, "@{username} · AI · Bot" dan "AI-generated voice · Call audio is processed by Google". Tidak ada kunci emoji maupun keterangan enkripsi.
• Jika sambungan bermasalah, penelepon mendengar "Sorry, we've lost the connection. Ending the call now." lalu telepon ditutup. Semua penolakan berakhir dengan nada sibuk.

Penjelasan untuk pengguna aplikasi ada di Menggunakan aplikasi — Menelepon bot suara.

Panggilan dari bot

Bot suara juga bisa menelepon seseorang lebih dulu: untuk memastikan janji, membangunkan pada jam yang dipilih, atau mengabarkan pengiriman. Kode pemilik bot memintanya dengan startVoiceCall, server menilai permintaan itu lalu membunyikan perangkat orang tersebut; jika ia menjawab, pengumuman Pabal diputar lebih dulu, lalu model suara AI berbicara sesuai instruksi bot. Bagaimana panggilan berakhir datang dalam update voice_call.

• Hanya kepada orang yang mengizinkan. Orang itu harus mengizinkan bot tersebut meneleponnya di aplikasi Pabal (Izin penerima panggilan) dan bisa mematikannya kapan saja.
• Bukan untuk iklan. Ada empat tujuan — pengingat, bangun, pengiriman, dan janji — dan iklan, penawaran penjualan, serta promosi tidak diperbolehkan (ketentuan pemilik bot, butir 12–24).
• Panggilan dari bot tidak terenkripsi ujung ke ujung — suara melewati server Pabal dan penyedia AI. Setelah orang itu menjawab, suara dikirim ke Google selama panggilan — Gemini Live API dari Vertex AI, Iowa, Amerika Serikat (Google Cloud us-central1). Pabal tidak menyimpan suara.
• Tidak ada teks percakapan yang dikirim ke pemilik bot. Panggilan yang dibuat bot tidak punya transkrip. Yang diterima pemilik bot adalah lima hal di Yang dilihat dan didengar penerima panggilan.

Alurnya

Menyalakan — @BotFather

Panggilan dari bot dinyalakan hanya oleh pemilik bot di @BotFather, tidak pernah lewat token (mengirim kolom panggilan ke setVoiceCallSettings menghasilkan 400 VOICE_FIELD_NOT_AVAILABLE). Panggilan suara harus menyala lebih dulu. /mybots → bot → Panggilan suara (음성 통화) → Panggilan dari bot (봇이 거는 전화) → Nyalakan (켜기).

BotFather menjawab dalam bahasa Korea. Pesan pertama menanyakan apakah bot boleh menelepon orang: hanya orang yang mengizinkan, tidak pernah pada jam tenang mereka atau saat dijeda, dengan batas harian (sekarang 50) dan batas server, dan hanya setelah operator meninjau dan mengizinkan nama, foto, instruksi, suara, dan tujuan bot (dan meninjau lagi setiap kali ada yang berubah); panggilan dari bot tidak terenkripsi ujung ke ujung. Pesan kedua menampilkan layar bot setelah menyala: menyala, menunggu operator, tujuan pengiriman, batas 50, permintaan hari ini.

• Ketentuan versi 4: jika Anda belum menyetujuinya, ketentuan pemilik bot muncul sebelum fitur menyala. Butir 12–24 adalah janji untuk panggilan dari bot.
• Tujuan: fitur hanya menyala dengan sedikitnya satu dari reminder (pengingat) · wake_up (bangun) · delivery (pengiriman) · appointment (janji). Setiap permintaan menyebut salah satunya; tujuan yang tidak dipilih bot menghasilkan 400. Mengubah tujuan akan meminta izin lagi kepada orang yang sudah mengizinkan, dan operator meninjau ulang.
• Batas harian: jumlah permintaan yang boleh dikirim bot per hari — 10, 20, atau 50 (bawaan 50).
• Tinjauan operator: operator melihat nama, @nama pengguna, foto, instruksi, salam pembuka, tool, suara, bahasa, mode, tujuan, dan nama pemilik bot di halaman admin, lalu mengizinkannya. Jika salah satunya berubah, bot tidak bisa menelepon sampai diizinkan lagi (403 VOICE_OUTBOUND_OFF: review).
• Token: mengubah pengaturan suara lewat token (kecuali mematikan suara) membekukan panggilan dari bot selama 24 jam (frozen). Jika Anda sendiri yang mengubahnya, cabut dengan Saya yang mengubahnya (내가 바꿨어요, vdk·vdK) di @BotFather. Menerbitkan ulang token juga membekukan 24 jam, mengakhiri panggilan yang sedang berjalan, dan menghapus webhook bot yang panggilannya menyala.
• Hanya bot berbahasa Korea atau Inggris (ko-KR·en-US) yang bisa menelepon. Bot dalam mode stream, dengan kunci sendiri, tool, atau server MCP tidak bisa (mode).

Izin penerima panggilan

Bot tidak bisa memperoleh izin sendiri. Orang itu membuka layar izin bot tersebut di aplikasi Pabal dan mengetuk "I am 19 or older · Allow" (Saya berusia 19 tahun ke atas · Izinkan). Layar itu menyebut bahwa AI yang menelepon, tujuan, nama pemilik bot, ke mana suara dikirim, dan jam tenang (Menggunakan aplikasi — Mengizinkan bot menelepon Anda). Ada tiga cara membukanya.

• Menu bot: "Allow calls…" (Izinkan panggilan…) di obrolan atau profil bot.
• Tautan di obrolan 1:1: bot mengirim https://pabal.me/<nama pengguna bot>?callme=1 ke obrolan 1:1 dengan orang itu, sebagai tautan di teks atau tombol URL inline. Layar hanya terbuka untuk pesan yang dikirim bot itu di obrolan itu — tautan yang diteruskan ke obrolan lain, pratinjau, atau web hanya membuka obrolan. Seseorang bisa membuka layar dari tautan sekali sehari (semua bot dihitung bersama), dan tidak sama sekali jika ia belum pernah menulis ke bot.
• Daftar di pengaturan "Bots allowed to call me" (Bot yang boleh menelepon saya): melihat bot yang diizinkan, mematikan, dan mengizinkan lagi.

curl -s "https://pabal.me/bot$BOT_TOKEN/sendMessage" -d chat_id=$USER_ID \
  --data-urlencode "text=Mau kami telepon sebelum pesanan Anda tiba?" \
  --data-urlencode 'reply_markup={"inline_keyboard": [[{"text": "Izinkan panggilan", "url": "https://pabal.me/order_helper_bot?callme=1"}]]}'

• Server yang di-host sendiri: aplikasi hanya mengenal tautan pabal.me. Untuk server lain, host-nya harus ditambahkan ke aturan tautan versi aplikasi agar tautan bisa membuka layar (menu dan daftar pengaturan tetap berfungsi).
• Untuk saat ini: hanya akun dengan nomor +82, di perangkat yang zona waktunya Korea (Seoul) dan sudah masuk setidaknya 24 jam, yang bisa menyalakan izin (operator menentukan negaranya). Orang yang menjawab berusia di bawah 19 tahun tidak bisa melakukan panggilan dengan bot selama setahun.
• Jika nama, pemilik, atau tujuan bot berubah, atau setahun setelah izin diberikan, izin ditanyakan lagi; sampai saat itu bot tidak bisa menelepon.

Menelepon — startVoiceCall

curl -s "https://pabal.me/bot$BOT_TOKEN/startVoiceCall" -d user_id=$USER_ID -d purpose=delivery \
  --data-urlencode "context=Pesanan A-1042 tiba hari ini sekitar pukul 15.00. Tanyakan apakah ia bisa menerimanya saat itu." \
  -d max_duration=180 -d ring_timeout=30

{"ok": true, "result": {"voice_call_id": "8812345678901234"}}

{"ok": false, "error_code": 403, "description": "Forbidden: USER_UNAVAILABLE"}

Sisi orang itu dinilai setelah 200. Meski ada izin, pada jam tenang orang itu, saat dijeda, melewati batas harian dengan orang itu atau batas harian dan jarak waktunya sendiri, tanpa perangkat yang bisa dibunyikan, atau saat ia sedang dalam panggilan lain, tidak ada yang berdering dan not_answered datang sekitar ring_timeout + 12 detik setelah permintaan — sama dengan dering yang tidak dijawab. Izin tidak mengubah sisi bot (403, 429, 503).

Pengaturan dan penggunaan

"outbound": {
  "enabled": true,
  "purposes": ["delivery"],
  "daily_cap": 50,
  "reviewed": true,
  "frozen_until": 0,
  "suspended": false,
  "available": true
}

"outbound": {
  "today": {"requests": 4, "answered": 2, "not_answered": 2, "minutes": 3},
  "limits": {"daily": 50, "owner_daily": 100, "owner_minutes": 30}
}

• outbound di getVoiceCallSettings selalu ada: yang diatur di @BotFather (enabled·purposes·daily_cap), tinjauan operator (reviewed), kapan pembekuan token berakhir (frozen_until, 0 jika tidak dibekukan), penghentian otomatis (suspended), dan apakah bot bisa menelepon sekarang (available). unavailable_reason hanya ada jika available bernilai false (di sisi bot, nilainya sama dengan alasan 403 VOICE_OUTBOUND_OFF; di sisi server, voice_off · kill_switch · no_relay · outbound_off — keempatnya berpasangan dengan 503 VOICE_UNAVAILABLE).
• outbound di getVoiceCallUsage hanya ada untuk bot yang pernah menyalakan panggilan: permintaan, dijawab, tidak dijawab, dan menit hari ini, serta batas harian yang berlaku untuk bot ini. Jumlah dering tidak diberikan. calls·seconds·missed·refused tidak pernah menghitung panggilan yang dibuat bot. Namun panggilan yang dibuat bot memakai menit panggilan per hari bot dan pemiliknya yang sama dengan panggilan ke bot: detik panggilan yang dijawab ditagihkan sehingga bot dan owner di remaining_seconds_today berkurang — selama berdering pun sudah berkurang sebesar yang dipesan panggilan itu, dan kembali jika tidak dijawab.
• setVoiceCallSettings tidak bisa mengubahnya (400 VOICE_FIELD_NOT_AVAILABLE).

Update

Datang sebagai update voice_call yang sama dengan panggilan ke bot (tulis voice_call di allowed_updates). direction bernilai "outgoing", dan orang itu hanya muncul sebagai id di to (tanpa nama, nama pengguna, atau nomor telepon).

{
  "update_id": 83,
  "voice_call": {
    "id": "8812345678901234",
    "direction": "outgoing",
    "event": "not_answered",
    "to": {"id": 100005},
    "purpose": "delivery",
    "date": 1790000123
  }
}

{
  "update_id": 81,
  "voice_call": {
    "id": "8812345678901234",
    "direction": "outgoing",
    "event": "started",
    "to": {"id": 100005},
    "purpose": "delivery",
    "date": 1790000130,
    "max_duration": 180
  }
}

{
  "update_id": 82,
  "voice_call": {
    "id": "8812345678901234",
    "direction": "outgoing",
    "event": "ended",
    "to": {"id": 100005},
    "purpose": "delivery",
    "date": 1790000250,
    "start_date": 1790000130,
    "duration": 120,
    "max_duration": 180,
    "end_reason": "callee"
  }
}

{
  "update_id": 84,
  "voice_call": {
    "id": "8812345678901234",
    "direction": "outgoing",
    "event": "failed",
    "to": {"id": 100005},
    "purpose": "delivery",
    "date": 1790000110
  }
}

end_reason: callee (orang itu menutup) · bot (bot menutup, atau tokennya diterbitkan ulang) · max_length (lama maksimum) · failed (sambungan gagal setelah dijawab) · operator (operator atau sakelar darurat) · suspended (bot atau pemilik ditangguhkan). Panggilan yang dibuat bot tidak punya missed, refused, atau ringing — kecepatan menjawab akan menunjukkan apakah orang itu ada di dekat ponselnya — dan tidak punya transcript (dimatikan secara desain).

Selama panggilan

• endVoiceCall: sebelum bot diberi tahu hasilnya, menarik permintaan, baik saat berdering maupun belum (true, lalu not_answered). Mengakhiri panggilan yang sudah dijawab (end_reason bot). Menarik permintaan dalam 15 detik membuat pasangan itu dijeda satu jam.
• sendVoiceCallContext: hanya setelah orang itu menjawab (sebelumnya, VOICE_CALL_NOT_FOUND). Tiga kali per panggilan, 1.000 karakter dan 3.072 byte, aturan konten yang sama dengan context. Jika gateway tidak menerima catatan, VOICE_CONTEXT_NOT_SUPPORTED.

Yang dilihat dan didengar penerima panggilan

• Dering: "(AI)" setelah nama bot, dan "AI voice bot · Pabal never asks for codes" (bot suara AI · Pabal tidak pernah meminta kode).
• Saat dijawab, sebuah pengumuman diputar sebelum bot: "This is a Pabal AI voice call. We never ask for passwords, codes or money transfers. To stop these calls, turn off call permission in the bot's chat." (Ini panggilan suara AI Pabal. Kami tidak pernah meminta kata sandi, kode, atau transfer uang. Untuk menghentikan panggilan ini, matikan izin panggilan di obrolan bot.) — dalam bahasa layar izin yang dibaca orang itu (Korea atau Inggris); dari aplikasi berbahasa lain, dalam bahasa Inggris. Pemilik bot tidak bisa mematikannya.
• Kata pertama bot: nama bot, bahwa ia AI, dan tujuan panggilan. context dipakai sesudahnya.
• Cara mematikan: "Stop calls from this bot" (Hentikan panggilan dari bot ini) di menu, memblokir bot, dan melaporkannya selalu mematikan. Mengatakan dengan jelas saat panggilan sesuatu seperti "jangan telepon saya lagi" langsung mematikannya (sekadar "berhenti" tergantung penilaian model).
• Dijeda: setelah penolakan, dering yang tidak dijawab, atau menutup dalam 10 detik setelah menjawab, bot tidak bisa menelepon orang itu selama 24 jam.
• Catatan panggilan tak terjawab: jika sebuah perangkat benar-benar berdering, orang itu tidak memblokir bot, dan obrolan bot tidak punya pesan yang belum dibaca, tersimpan "Missed AI bot call" (panggilan bot AI tak terjawab — sudah dibaca, tanpa notifikasi). Jika ada pesan yang belum dibaca, atau tidak berdering karena jam tenang atau jeda, tidak ada catatan. Setiap permintaan bot tersimpan tanpa kecuali di bukti laporan (30 hari).
• Yang diterima pemilik bot (dalam urutan layar izin):
  1. id Pabal orang itu
  2. apakah izinnya menyala (terlihat dari jawaban atas permintaan panggilan)
  3. apakah orang itu menjawab
  4. kapan panggilan dimulai dan berapa lama
  5. siapa yang menutup
  Panggilan tak terjawab dan panggilan yang ditolak terlihat sama. Isi pembicaraan tidak dikirim.
• Perangkat bersama: perangkat mana pun yang sedang masuk bisa menjawab, dan bot menyebut tujuan serta keterangan yang diberikan kepada siapa pun yang menjawab. Di komputer yang dipakai bersama, ingatkan untuk keluar.
• Layar kunci: di Android 14 dan yang lebih baru, jika orang itu tidak mengizinkan notifikasi layar penuh, panggilan datang sebagai notifikasi, bukan layar panggilan di atas layar kunci. iPhone dan Apple Watch berdering seperti panggilan telepon.
• Simpan percakapan menyimpannya hanya di obrolan orang itu sendiri, jika ia memilihnya di layar izin. Dengan Jawab di jam tangan yang dinyalakan di aplikasi Pabal untuk Apple Watch, Apple Watch juga berdering.
• Panggilan dari bot tidak terenkripsi ujung ke ujung — suara melewati server Pabal dan penyedia AI.

Batas · jam tenang · jeda · penghentian otomatis

• "Per hari" adalah satu hari menurut zona waktu server (TELEGRAM_VOICE_TIME_ZONE). Panggilan tidak pernah lebih dari 300 detik.
• Panggilan dari bot juga memakai menit panggilan per hari yang sama dengan panggilan ke bot (bot 60 menit · pemilik 120 menit). Jika sudah habis, startVoiceCall mendapat 429, dan panggilan ke bot itu juga ditolak (refused, budget).
• Jeda berakhir saat waktunya habis, saat orang itu menelepon bot, mengetuk "I can take calls now" (Saya bisa menerima panggilan sekarang), atau mengizinkannya lagi. Pesan atau tombol dari bot tidak mengakhirinya.
• Penghentian otomatis hanya menghentikan panggilan bot kepada orang (403 VOICE_OUTBOUND_OFF: suspended) dan berlangsung sampai operator memeriksa dan mencabutnya: tingkat jawaban di bawah 20% dari 20 panggilan terakhir, 3 laporan dalam 7 hari dari orang yang pernah ia buat berdering, 30% atau lebih orangnya mematikan izin (dengan sedikitnya 10 orang), 2 panggilan terkena aturan selama panggilan, 5 penarikan dalam 15 detik, atau 2 orang atau kurang yang menjawab dengan 60 menit atau lebih panggilan yang dijawab.

Batas

Dari Apple Watch, bot yang memakai tool, server MCP, kunci sendiri, mode stream, atau transkrip pemilik bot tidak bisa ditelepon. Penolakan ini hanya sampai ke penelepon (403 WATCH_NOT_YET di aplikasi jam tangan), dan bot tidak menerima update refused.

Durasi satu panggilan adalah yang terkecil di antara sisa waktu hari ini untuk penelepon, bot, pemilik, dan server, serta batas atas panggilan. Saat panggilan diterima, durasi itu dicadangkan di keempat batas, dan setelah selesai hanya detik yang sebenarnya menurut jam server yang ditagihkan. Panggilan berkunci sendiri tidak memakai batas bot, pemilik, dan server (batas penelepon tetap berlaku).

Error

Error berbentuk sama seperti metode lain: {"ok": false, "error_code": 400, "description": "Bad Request: VOICE_…"}. 403 berbentuk Forbidden: <kode>: <keterangan> (kecuali USER_UNAVAILABLE, yang selalu persis Forbidden: USER_UNAVAILABLE tanpa keterangan), dan 429 disertai parameters.retry_after.

Bot yang tersambung lewat MTProto

• Bot yang hanya masuk lewat MTProto memanggil metode suara dengan bots.sendCustomRequest (JSON yang sama, dengan nama metodenya). Yang bisa: setVoiceCallSettings, getVoiceCallSettings, answerVoiceCallToolQuery, endVoiceCall, sendVoiceCallContext, getVoiceCallUsage, startVoiceCall, dan lima metode MCP. Selain itu: METHOD_INVALID. Jawaban startVoiceCall adalah {"voice_call_id": "…"}, dan penolakan datang sebagai error RPC (USER_UNAVAILABLE, VOICE_OUTBOUND_OFF: review, FLOOD_WAIT_n, VOICE_UNAVAILABLE).
• Metode yang tidak bisa dipanggil dari jawaban webhook: setVoiceCallApiKey, startVoiceCall, serta metode pendaftaran dan kunci MCP. Jika diletakkan di isi jawaban atas POST webhook, metode itu tidak dijalankan — agar tidak ada pesan dari seseorang yang langsung berubah menjadi panggilan telepon lewat jawaban webhook. Panggil dengan permintaan tersendiri.
• Kunci sendiri hanya lewat HTTPS: setVoiceCallApiKey dan deleteVoiceCallApiKey tidak bisa dipanggil lewat sendCustomRequest. Untuk menghapus kunci, pakai HTTP Bot API atau @BotFather.
• Untuk bot tanpa webhook yang tidak memanggil getUpdates dalam 15 detik terakhir, voice_call (termasuk untuk panggilan yang dibuat bot) didorong sekali lewat updateBotWebhookJSON (tidak bergantung pada allowed_updates, tidak dikirim ulang). Kueri tool datang lewat updateBotWebhookJSONQuery dan dijawab dengan bots.answerWebhookJSONQuery berisi {"result": …} atau {"error": "…"}. voice_call_transcript tidak datang lewat MTProto (transcript pada update akhir panggilan tetap datang).
• Untuk error RPC, 429 menjadi FLOOD_WAIT_n, dan sisanya adalah kode huruf besar apa adanya.