Dokumentasi

Saka Chat adalah aplikasi chat berbasis cloud dengan server yang dikelola sendiri di Indonesia. Halaman ini untuk pengguna awal dan pengembang bot. Ini versi beta: fitur dan alamat bisa berubah, dan data beta dapat direset.

Membuat akun

Kode masuk lewat aplikasi. Bila nomor Anda sudah masuk di perangkat lain (web atau PC), kode masuk untuk perangkat baru dikirim sebagai pesan dari akun layanan Saka Chat (@sakachat) ke perangkat yang sudah masuk itu. Akun yang sama juga mengabari Anda setiap kali perangkat baru masuk, lengkap dengan platform dan alamat IP, supaya sesi asing bisa segera diakhiri dari Pengaturan, Perangkat. Kami tidak pernah meminta kode Anda lewat pesan apa pun.

1. Buka chat.hack.id di browser, atau unduh aplikasi dari halaman Unduh.
2. Masukkan nomor telepon dalam format internasional, misalnya +62812xxxxxxx.
3. Masukkan kode masuk. Pada masa beta, kode belum dikirim lewat SMS atau WhatsApp; minta kodenya ke pengelola beta.
4. Isi nama. Lalu pasang @username di Pengaturan supaya orang lain bisa menemukan Anda lewat pencarian.

Satu akun bisa dipakai di banyak perangkat sekaligus; riwayat tersimpan di server dan ikut ke perangkat baru. Perangkat yang masuk terlihat dan bisa diakhiri dari Pengaturan.

Membuat bot

Bot adalah akun khusus yang dikendalikan program lewat Bot API. Bot dibuat dari dalam aplikasi lewat percakapan dengan @botinduk, padanan BotFather:

1. Cari @botinduk di kolom pencarian dan kirim /newbot.
2. Jawab nama tampilan, lalu username yang berakhiran bot (huruf kecil, angka, garis bawah, 5 sampai 32 karakter).
3. Pembuat Bot membalas dengan token berbentuk <id>:<rahasia>. Simpan: siapa pun yang memegang token bisa mengendalikan bot.

Perintah lain: /mybots daftar bot Anda, /token @namabot membuat ulang token dan mencabut sesi lama, /setname dan /setdescription mengubah profil, /deletebot menghapus (dengan konfirmasi), /cancel membatalkan. Setiap akun boleh memiliki sampai 20 bot. Pengguna menemukan bot lewat pencarian @namabot.

Bot API

Bot API Saka Chat adalah API HTTP berbasis JSON: metode dipanggil lewat https://chat.hack.id/bot<token>/<metode>, update diterima lewat polling atau webhook. Bentuknya kompatibel dengan pustaka bot yang sudah banyak dipakai (grammY, telegraf, python-telegram-bot, aiogram, dan lainnya), jadi bot yang ada cukup mengganti alamat dasar.

Alamat dasar : https://chat.hack.id/bot<token>/<metode>
Parameter    : JSON, form, atau query string (POST atau GET)
Jawaban      : {"ok": true, "result": ...} atau {"ok": false, "error_code": 400, "description": "..."}

Menerima update

Dua cara yang saling eksklusif:

• Long polling: getUpdates dengan offset, limit, dan timeout (maksimal 50 detik). Update tersimpan sampai 24 jam atau 1.000 update terakhir.
• Webhook: setWebhook dengan url dan secret_token; Saka Chat mengirim POST JSON tiap update dengan header X-Telegram-Bot-Api-Secret-Token dan mencoba ulang bila jawaban bukan 2xx.

Contoh dengan curl

curl -s https://chat.hack.id/bot$TOKEN/getMe

curl -s https://chat.hack.id/bot$TOKEN/getUpdates -H 'Content-Type: application/json' \
  -d '{"timeout": 30}'

curl -s https://chat.hack.id/bot$TOKEN/sendMessage -H 'Content-Type: application/json' \
  -d '{"chat_id": 123456789012345, "text": "Halo dari bot", "reply_to_message_id": 98765}'

Metode yang tersedia

Format teks

parse_mode HTML menerima <b>, <i>, <u>, <s>, <code>, <pre>, <a href>, dan <tg-spoiler>; MarkdownV2 menerima *tebal*, _miring_, __garis bawah__, ~coret~, ||rahasia||, `kode`, ```blok```, dan [teks](url) dengan karakter khusus di-escape memakai \. Server menyimpan teks polos plus entities (offset UTF-16), dan mengembalikannya dalam setiap objek Message. Format yang rusak dijawab 400 can't parse entities.

Pengguna aplikasi juga bisa menulis dengan penanda **tebal**, __miring__, ~~coret~~, ||rahasia||, `kode`, dan ```blok``` di kotak pesan; bot menerimanya sebagai entities.

Tombol inline dan callback

curl -s https://chat.hack.id/bot$TOKEN/sendMessage -H 'Content-Type: application/json' -d '{
  "chat_id": 123456789012345, "text": "Pilih paket:",
  "reply_markup": {"inline_keyboard": [
    [{"text": "Hemat", "callback_data": "paket:hemat"}, {"text": "Pro", "callback_data": "paket:pro"}],
    [{"text": "Lihat harga", "url": "https://contoh.id/harga"}]]}}'

Saat pengguna menekan tombol, bot menerima update callback_query berisi id, from, message (dengan message_id dan chat), dan data. Jawab dengan answerCallbackQuery; sambil itu bot biasanya mengganti tombol lewat editMessageReplyMarkup atau mengubah teks lewat editMessageText. Batas: 100 baris, 8 tombol per baris, callback_data maksimal 64 byte, tombol harus punya url atau callback_data (salah satu). Hanya akun bot yang boleh mengirim tombol.

Tombol balas, sembunyikan papan, dan force_reply

curl -s https://chat.hack.id/bot$TOKEN/sendMessage -H 'Content-Type: application/json' -d '{
  "chat_id": 123456789012345, "text": "Mau pesan apa?",
  "reply_markup": {"keyboard": [["Kopi susu", "Teh tarik"], [{"text": "Lihat tagihan"}]],
    "resize_keyboard": true, "one_time_keyboard": true, "input_field_placeholder": "Pilih menu"}}'

Tombol balas (ReplyKeyboardMarkup) tampil di atas kotak pesan pengguna; menekannya mengirim teks tombol sebagai pesan biasa, jadi bot menerimanya lewat update message seperti ketikan tangan. one_time_keyboard menyembunyikan papan setelah satu tombol ditekan, resize_keyboard membuat tombol lebih padat, input_field_placeholder mengganti teks pengganti kotak pesan (maksimal 64 karakter). Pengguna bisa melipat dan membuka papan lewat ikon papan ketik di kotak pesan. Papan tetap berlaku sampai bot mengirim {"remove_keyboard": true} atau papan lain. {"force_reply": true} membuat kotak pesan pengguna langsung membalas pesan bot itu, berguna untuk alur tanya jawab. Batas: 100 baris, 12 tombol per baris, teks tombol maksimal 64 karakter; request_contact dan request_location diterima tetapi belum dilayani aplikasi (tombol tetap mengirim teksnya). Satu pesan memakai salah satu: tombol inline, tombol balas, remove_keyboard, atau force_reply.

Bot di grup dan mode privasi

Bot bisa ditambahkan ke grup oleh anggota (Info grup, Tambah) atau lewat tautan undangan. Dengan mode privasi aktif (bawaan), di grup dan supergrup bot hanya menerima: perintah (pesan dengan entitas bot_command, termasuk /perintah@namabot), pesan yang menyebut @namabot, balasan ke pesan bot itu sendiri, dan pesan layanan (anggota bergabung atau keluar). Percakapan pribadi dan kanal tidak terpengaruh. Pemilik bot mengubahnya lewat Pembuat Bot dengan /setprivacy; getMe melaporkan can_read_all_group_messages sesuai pengaturan, dan perubahan berlaku paling lambat dua menit kemudian tanpa perlu menjalankan ulang bot.

Batas laju

30 pesan per detik untuk seluruh bot, 1 pesan per detik per percakapan (ledakan singkat sampai 3), 20 pesan per menit per grup, dan 60 permintaan HTTP per detik per token. Saat terlampaui, API menjawab 429 dengan parameters.retry_after dan header Retry-After; tunggu selama itu lalu ulangi. Pustaka bot populer menangani ini otomatis.

Topik di grup

Grup yang topiknya dinyalakan admin (Info grup, Nyalakan topik) melaporkan chat.is_forum: true. Pesan di dalam topik membawa message_thread_id dan is_topic_message: true; pesan di Umum tidak membawa keduanya. Bot membalas ke topik yang sama dengan menyertakan message_thread_id pada sendMessage, sendPhoto, sendDocument, atau sendSticker. Saat anggota membuka topik, bot menerima pesan layanan forum_topic_created dengan name; message_id pesan itu adalah message_thread_id topiknya. createForumTopic (chat_id, name), closeForumTopic, dan reopenForumTopic tersedia; topik tertutup hanya bisa ditulisi admin.

Stiker dan emoji kustom

sendSticker menerima sticker berupa file_id stiker yang pernah diterima (dari set mana pun), URL, atau unggahan webp/png maksimal 512 KB dan 512 piksel; parameter emoji opsional. Pesan stiker tampil di update sebagai objek sticker (file_id, width, height, emoji, set_name, type regular atau custom_emoji). getStickerSet dengan name (short_name) mengembalikan isi set, termasuk set resmi saka dan set emoji kustom saka_emoji. Emoji kustom di teks datang sebagai entitas custom_emoji dengan custom_emoji_id (id stiker dari set berjenis emoji); bot bisa mengirimkannya lewat entities. Pembuatan set lewat Bot API (createNewStickerSet) menyusul; saat ini set dibuat lewat protokol klien (CreateStickerSet).

Menu perintah, tombol Mulai, dan deep link

Perintah yang Anda daftarkan lewat setMyCommands disimpan di server dan tampil di aplikasi saat pengguna mengetik "/" di percakapan dengan bot (juga lewat tombol "/" di sebelah kotak pesan). Memilih perintah langsung mengirimnya, misalnya /harga. Nama perintah: huruf kecil, angka, garis bawah, 1 sampai 32 karakter; keterangan 1 sampai 256 karakter; maksimal 100 perintah. getMyCommands dan deleteMyCommands tersedia. Cakupan per chat dan per bahasa belum ada: satu daftar untuk semua.

Percakapan bot yang masih kosong menampilkan tombol Mulai sebagai pengganti kotak pesan; menekannya mengirim /start. Deep link: bagikan tautan https://chat.hack.id/@namabot?start=payload. Pengguna yang membukanya (setelah masuk) langsung berada di percakapan bot Anda dengan tombol Mulai, dan saat ditekan bot menerima pesan /start payload. Payload maksimal 64 karakter dari huruf, angka, _ dan -, dan tampil apa adanya di percakapan pengguna. Tautan https://chat.hack.id/@username tanpa payload membuka percakapan dengan pengguna atau kanal publik mana pun. Tautan undangan grup dan kanal berbentuk https://chat.hack.id/+<id>.<hash> (tersedia di Info grup): siapa pun yang membukanya langsung bergabung, termasuk bot yang Anda jalankan sendiri lewat protokol klien (JoinChannel dengan channel_id dan access_hash).

curl -s -X POST https://chat.hack.id/bot$TOKEN/setMyCommands \
  -H 'content-type: application/json' \
  -d '{"commands":[{"command":"start","description":"Mulai percakapan"},{"command":"harga","description":"Daftar harga terbaru"}]}'

Objek update

{"update_id": 12,
 "message": {"message_id": 8795234567890,
   "from": {"id": 4493451261952, "is_bot": false, "first_name": "Rani", "username": "rani"},
   "chat": {"id": 4493451261952, "type": "private", "first_name": "Rani"},
   "date": 1794731000, "text": "halo"}}

chat.type bernilai private, group, supergroup, atau channel. Pesan kanal datang sebagai channel_post, suntingan sebagai edited_message atau edited_channel_post.

Pustaka bot

Pustaka berikut bisa dipakai apa adanya dengan mengganti alamat dasar ke https://chat.hack.id.

Ganti alamat dasar ke https://chat.hack.id. Contoh:

// grammY (Node)
import { Bot } from "grammy";
const bot = new Bot(process.env.TOKEN, { client: { apiRoot: "https://chat.hack.id" } });
bot.on("message:text", (ctx) => ctx.reply("Diterima: " + ctx.message.text));
bot.start();

# python-telegram-bot
app = Application.builder().token(TOKEN).base_url("https://chat.hack.id/bot").build()

// Telegraf
new Telegraf(TOKEN, { telegram: { apiRoot: "https://chat.hack.id" } })

# aiogram
Bot(TOKEN, session=AiohttpSession(api=TelegramAPIServer.from_base("https://chat.hack.id")))

Tentang ID

Semua ID (pengguna, chat, pesan) adalah bilangan bulat di bawah 2⁵³, jadi utuh di JavaScript tanpa BigInt. ID pengguna positif, ID grup negatif, ID kanal dan supergroup negatif dengan nilai besar. Pada protokol klien asli, ID dikirim sebagai string.

OpenClaw

OpenClaw menyambung ke Saka Chat lewat kanal telegram miliknya (nama kanal di konfigurasi OpenClaw) dengan alamat dasar khusus:

channels:
  telegram:
    botToken: "<token bot Saka Chat>"
    apiRoot: "https://chat.hack.id"      # hanya akar, tanpa /bot<token>

Setelah itu OpenClaw memakai getUpdates dan sendMessage seperti biasa; pengguna mengobrol dengan bot dari aplikasi Saka Chat. Tombol inline dan format Markdown/HTML sudah berjalan; yang belum tersedia untuk OpenClaw: kirim gambar dan berkas (media menyusul).

Hermes

Hermes Agent memakai python-telegram-bot dan mendukung server Bot API alternatif lewat konfigurasi:

# ~/.hermes/.env
TELEGRAM_BOT_TOKEN=<token bot Saka Chat>

# config Hermes
platforms:
  telegram:
    extra:
      base_url: "https://chat.hack.id/bot"
      base_file_url: "https://chat.hack.id/file/bot"

Lalu jalankan hermes gateway. Mode long polling berfungsi; webhook juga bisa dengan TELEGRAM_WEBHOOK_URL. Fitur Hermes yang bergantung pada topik forum, pesan kaya (sendRichMessage), dan unduh berkas belum didukung dan akan jatuh ke teks biasa.

Server MCP

Selain Bot API, agen yang mendukung Model Context Protocol (Claude Code, Claude Desktop, Hermes, OpenClaw) bisa memakai server MCP Saka Chat: agen bertindak sebagai bot dengan tool dialog_daftar, pesan_riwayat, pesan_baru, pesan_kirim, kanal_posting, kontak_cari, mengetik.

# stdio (untuk Claude Code / Claude Desktop), token lewat env
CHAT_INTI_BOT_TOKEN=<token> go run ./cmd/mcp -gateway wss://chat.hack.id/v1

# .mcp.json
{"mcpServers": {"chat-inti": {"command": "chat-mcp",
  "args": ["-gateway", "wss://chat.hack.id/v1"],
  "env": {"CHAT_INTI_BOT_TOKEN": "<token>"}}}}

# Streamable HTTP di /mcp
chat-mcp -gateway wss://chat.hack.id/v1 -http 127.0.0.1:8082

Batas dan status

Peta jalan untuk pengembang bot

Urutan fitur Bot API yang sedang dikerjakan, dari yang paling dekat:

Belum dinyalakan untuk pengguna; rancangannya: panggilan suara dan video satu lawan satu memakai WebRTC: suara dan gambar mengalir langsung antar perangkat dan terenkripsi ujung ke ujung oleh DTLS-SRTP, server hanya meneruskan sinyal (SDP dan kandidat ICE) serta mencatat riwayat "Panggilan suara, 3 menit" di percakapan. Bila koneksi langsung gagal karena NAT, lalu lintas dialihkan lewat server TURN yang tetap tidak bisa membaca isinya. Bot tidak bisa menerima panggilan; Bot API belum punya metode panggilan.

Lingkungan uji: jalankan server sendiri dengan go run ./cmd/server -embedded-pg -dev; kode masuk selalu 12345 dan tidak ada data nyata.

Protokol klien

Aplikasi resmi berbicara ke server lewat WebSocket wss://chat.hack.id/v1 dengan pesan Protobuf (satu frame = satu Envelope). Skema chat.proto, inti klien bersama dalam Rust, dan kode server ada di repositori proyek. Pembuat aplikasi pihak ketiga bisa memakai protokol yang sama; pendaftaran api_id menyusul.