Dokumentasi bot InfiTalk

Mulai cepat

1. Buat bot di Ruang pengembang dan salin tokennya (diawali itw_). Token hanya tampil sekali. Jangan pernah membagikannya atau menaruhnya di repo publik.
2. Pasang bot di server yang kamu kelola lewat tombol "Tambah ke server" di halaman yang sama. Bot sendiri tidak perlu ditinjau.
3. Unduh contoh dan jalankan dengan tokenmu:
   • echo-bot.js (Node.js 22+, tanpa paket)
   • echo_bot.py (Python 3.9+, pip install websockets)

INFITALK_TOKEN=itw_... node echo-bot.js

# PowerShell
$env:INFITALK_TOKEN="itw_..."; node echo-bot.js

SDK Python

Untuk bot yang lebih besar, pakai SDK resmi InfiArtt infitalk (Python 3.10+, lisensi MIT). SDK mengurus sambungan, resume, aturan 3 detik, dialog, tombol, dan suara, dan punya penguji lokal tanpa server.

pip install git+https://github.com/InfiArtt/infitalk-python

from infitalk import Bot

bot = Bot()  # INFITALK_TOKEN

@bot.command("echo", "Repeat what you write")
async def echo(ctx, text: str):
    await ctx.respond(text, public=True)

bot.run()

Contoh itu punya menu (Ctrl+Shift+P di InfiTalk) dengan perintah echo, dialog hello, dan nada pelan satu detik.

Sambungan ke gerbang

Alamatnya wss://tt.infiartt.com/bot. Setiap pesan adalah satu objek JSON dalam satu pesan teks WebSocket.

1. Gerbang menyapa:

   {"op":"hello","gateway":1,"heartbeat_interval":30000}

2. Bot mengirim token dalam 10 detik:

   {"op":"identify","token":"itw_...","resume":{"12":{"session":"...","seq":340}}}

   "resume" boleh kosong. Isinya sesi dan nomor kejadian terakhir per server dari sambungan sebelumnya.
3. Gerbang menjawab:

   {"op":"identified","bot":{"id":7,"name":"echo"},
    "servers":[{"server":12,"name":"Kafe Musik","awake":true}],
    "limits":{"messages_per_second":200,"audio_streams_per_server":2,"max_message":1048576}}

4. Kirim {"op":"heartbeat"} paling lambat setiap heartbeat_interval milidetik. Jawabannya {"op":"heartbeat_ack"}. Gerbang sendiri yang menjaga sambungan ke setiap server, jadi heartbeat per server tidak perlu.

Kalau sambungan putus, sambung lagi dengan "resume". Server menyimpan bot selama 60 detik dan 1000 kejadian terakhir (2 menit), jadi tidak ada yang hilang dan orang tidak melihat bot keluar-masuk.

Server

Satu sambungan melayani semua server tempat bot dipasang. Setiap pesan dari dan ke server membawa "server".

• ready: server bangun dan bot sudah masuk. Isinya nomor pengguna bot, channel yang boleh dilihat, izin, sesi, dan "resumed".
• server_sleeping: server tidur karena kosong. Gerbang menyambung lagi sendiri saat server bangun, lalu datang "ready" baru. Bot tidak membuat server tetap bangun.
• server_added / server_removed: bot dipasang atau dilepas di infiartt.com (berlaku dalam satu menit).

{"op":"say","server":12,"channel":5,"content":"Hello!"}

Yang dikirim bot

Setiap permintaan boleh membawa "ref". Jawabannya {"op":"result","ref":...,"ok":true|false,"error":...}.

{"op":"commands","server":12,"commands":[
  {"name":"echo","description":"Repeat what you write","category":"Fun",
   "options":[{"name":"text","label":"Text","type":"text","required":true}]},
  {"name":"stop","description":"Stop the music","permission":"moderator"}]}

Kejadian yang diterima bot

• command: orang memakai menu bot. Isinya interaction, command, values, user (dengan level), channel.
• action: tombol atau pilihan pada pesan bot ditekan.
• form, suggest, dialog_event: formulir diisi, orang mengetik di isian, atau ada kejadian di dialog.
• message: pesan yang menyebut bot (izin mentions), atau semua pesan (izin messages).
• direct: pesan pribadi ke bot.
• member: orang masuk atau keluar channel (izin members).

Aturan 3 detik: setiap interaction harus dijawab dalam 3 detik dengan respond, defer, dialog, atau dialog_update. Kalau tidak, orang itu mendengar bahwa bot tidak menjawab. Interaction bisa dijawab sampai 15 menit setelah defer.

Dialog

Dialog dibuat dari JSON dan ditampilkan klien sebagai kontrol Windows asli, jadi bisa dipakai dengan NVDA dan JAWS. Kontrolnya: label, text, number, checkbox, radio, select, slider, list, button, dan group.

• Setiap kontrol kecuali label wajib punya label. Server menolak dialog tanpa label.
• Tanda & di label memberi huruf Alt. Kalau tidak ada atau bentrok, klien memilihkannya.
• Paling banyak 100 kontrol, 200 pilihan per kontrol, 64 KB.
• dialog_update mengganti kontrol di tempat tanpa menutup dialog; "announce" dibacakan pembaca layar.

{"op":"dialog","server":12,"interaction":881,"dialog":{"id":"eq","title":"Equalizer","focus":"bass",
 "controls":[
  {"type":"slider","id":"bass","label":"&Bass","min":-12,"max":12,"step":1,"unit":"dB","value":0,"notify":true},
  {"type":"select","id":"preset","label":"&Preset","options":[{"value":"flat","label":"Flat"},{"value":"pop","label":"Pop"}]},
  {"type":"button","id":"save","label":"&Save","default":true},
  {"type":"button","id":"close","label":"Close","close":true}]}}

Suara

• Format: PCM 48 kHz, stereo, 16-bit signed little-endian, dikodekan base64. Server mengubahnya ke Opus channel.
• Kirim dalam waktu nyata, misalnya potongan 20 ms (3840 byte) setiap 20 ms. Server menampung paling banyak 3 detik.
• Bot harus berada di channel itu (join) dan punya izin bicara di sana.
• Paling banyak 2 aliran suara sekaligus per bot per server. Server anggota memutar paling banyak 7 channel sekaligus.
• audio_end memutar sisa tampungan lalu berhenti; "drop":true berhenti seketika (stop, skip).
• Jaga volume tetap wajar. Pendengar punya volume sendiri untuk bot, tapi suara keras tetap mengganggu.

{"op":"join","server":12,"channel":5}
{"op":"audio","server":12,"channel":5,"pcm":"AAAAAP7/..."}
{"op":"audio_end","server":12,"channel":5}

Izin

Bot meminta izin saat dibuat. Pemilik server melihatnya di layar persetujuan dan boleh mengurangi. Tanpa izin yang perlu, permintaan dijawab missing_permission.

• mentions: pesan yang menyebut bot atau membalas pesan bot.
• direct: pesan pribadi yang dikirim langsung ke bot.
• send: menulis pesan di channel dan menjawab untuk seluruh channel.
• manage_own: mengubah dan menghapus pesan yang ditulis bot itu sendiri.
• speak: mengirim suara ke channel, misalnya musik.
• dialogs: membuka jendela berisi tombol, daftar, dan slider untuk orang yang memakainya.
• commands: punya menu perintah (Ctrl+Shift+P) yang bisa dipakai orang.
• everywhere: bot tampil di channel setiap orang tanpa bunyi masuk/keluar, dan bisa memutar suara di beberapa channel sekaligus (misalnya bot musik). Tidak pernah di channel pribadi.
• messages: semua pesan di channel yang boleh dibaca bot, tidak pernah dari channel pribadi. Perlu alasan yang jelas. (izin istimewa)
• members: siapa yang masuk ke channel yang boleh dilihat bot. (izin istimewa)
• presence: melihat siapa yang sedang online di server. Belum dipakai. (izin istimewa)

Bot tidak pernah menerima pesan pribadi antara dua orang, isi channel pribadi yang tidak mengizinkannya, kata sandi, alamat IP, atau ID perangkat.

Batas dan kode galat

• Pesan paling besar 1 MiB. Paling banyak 200 pesan per detik per bot (sesaat boleh 400).
• Pesan ke channel: 5 per 5 detik per channel dan 50 per menit.
• Paling banyak 20 sambungan dari satu alamat, dan 30 identify per menit.

Galat dalam "result": identify_first, unknown_server, server_asleep, rate_limited (dengan retry_after), too_many_streams, missing_permission (dengan permission), not_in_channel, not_allowed, invalid_token, bad_json.

Galat terakhir dan waktu sambungan terakhir bot tampil di Ruang pengembang.

Katalog dan aturan

Bot yang diajukan ke katalog ditinjau tim InfiArtt sebelum bisa dipasang semua pemilik server. Syarat sebelum mengajukan: deskripsi dalam bahasa Indonesia dan Inggris, halaman bantuan, kebijakan privasi, dan bot sudah pernah tersambung. Yang diperiksa:

• Bot menyala, menjawab dalam 3 detik, dan semua perintahnya berfungsi
• Menu, dialog, dan pesannya diuji dengan NVDA: semua kontrol berlabel, huruf Alt masuk akal, teks tidak terlalu panjang dibacakan
• Izin yang diminta sesuai kegunaannya, dan izin istimewa punya alasan
• Halaman bantuan dan kebijakan privasi ada dan jelas
• Tidak ada spam, konten berbahaya, atau suara yang mengganggu

Bot yang meminta izin baru keluar dari katalog sampai ditinjau lagi; server yang sudah memasangnya tetap memakai izin lama. Bot yang melanggar aturan (spam, mengumpulkan data tanpa izin, suara yang mengganggu) dimatikan.