Konsep Dasar

Halaman ini ngerangkum hal-hal yang berlaku di semua endpoint. Sekali baca, sisanya bakal kerasa jauh lebih gampang.

Base URL

Semua endpoint ada di bawah:

https://api-zate.azickri.com

Request dan response pakai JSON. Buat endpoint yang ada body-nya, jangan lupa kirim header Content-Type: application/json.

Sesi: id + session-id

Zate nggak pakai API key atau token. Sebagai gantinya, tiap akun Telegram yang login punya satu sesi, dan sesi itu dikenali dari dua nilai yang kamu dapet dari Buat Session:

Header	Diisi dengan	Contoh
id	id dari Buat Session	68b3f0a2c1d4e5f6a7b8c9d0
session-id	sessionId dari Buat Session	0b2f7059-8a90-4f6d-8684-b0e1ce6f0310

Semua endpoint, kecuali POST /session dan link media, wajib bawa dua header itu:

curl "https://api-zate.azickri.com/group" \
  -H "id: 68b3f0a2c1d4e5f6a7b8c9d0" \
  -H "session-id: 0b2f7059-8a90-4f6d-8684-b0e1ce6f0310"

Perlakukan kayak password

Siapa pun yang pegang id dan session-id kamu bisa kirim pesan pakai akun Telegram kamu, baca grup dan channel kamu, dan ganti tujuan webhook kamu. Simpan di server aja, jangan di frontend atau aplikasi mobile.

Satu sesi = satu login Telegram. Di Telegram, sesi Zate muncul sebagai perangkat bernama Zate di Settings → Devices. Kalau mau pakai beberapa akun, bikin beberapa sesi.

Siklus Hidup Sesi

Sesi itu "hidup": bisa nyambung, putus, nyambung lagi, sampai akhirnya dihapus. Ini yang terjadi di tiap kondisi:

Kondisi	Yang terjadi
Baru dibuat	isConnected: false. Beberapa detik kemudian qrcode terisi, dan ganti kira-kira tiap 30 detik.
QR nggak di-scan dalam 3 menit	Sesi dihapus otomatis. Request berikutnya dapet 404 session not found.
QR udah di-scan	isConnected: true, qrcode kosong, name, username, phone, dan picture terisi.
QR di-scan, akun pakai verifikasi dua langkah	qrcode kosong, isPasswordRequired: true. Kirim password lewat Kirim Password.
Koneksi putus sebentar	Zate nyambung ulang sendiri dengan jeda yang makin lama (0 detik, 2 detik, 4 detik, dst., maksimal 30 detik).
Kamu keluarin perangkat Zate dari Telegram	Ketahuan dalam sekitar 30 detik. Login-nya dihapus dan Zate langsung nyiapin QR baru, dengan batas 3 menit yang sama.
Terputus lebih dari 30 menit	Sesi dihapus otomatis, termasuk semua datanya. Ini juga berlaku buat sesi yang nggak kunjung dikirim password-nya.
Kamu panggil Reset Session	Perangkat Zate keluar dari Telegram dan Zate nyiapin QR baru.
Kamu panggil Hapus Session	Perangkat Zate keluar dari Telegram, dan semua data sesi dihapus.

Pantau koneksinya

Ambil Session aman dipanggil kapan aja, bahkan waktu sesinya lagi putus. Cek isConnected secara berkala (misalnya tiap beberapa menit) biar kamu tahu kapan harus scan ulang, sebelum 30 menitnya habis.

Tujuan Pesan

Kirim Pesan dan Kirim Typing butuh tujuan. Isi salah satu kolom ini:

Kolom	Isinya	Contoh	Dapet dari mana?
group	ID grup, atau username grup publik	-1001234567890	Ambil Group
channel	ID channel, atau username channel publik	-1001234567890	Ambil Channel
user	ID user Telegram	123456789	Ambil Member Group, atau chatId di webhook
username	Username, boleh pakai @ atau link t.me	@azickri	Profil Telegram tujuan
phone	Nomor HP format internasional	6281234567890	Nomor tujuan

Kalau kamu isi lebih dari satu kolom, yang dipakai urutannya group, channel, user, username, lalu phone. Kirim ke channel cuma bisa ke channel yang kamu kelola, dan Kirim Typing nggak nerima channel.

ID di Telegram

ID Telegram itu angka, dan tanda di depannya nunjukin jenisnya:

Bentuk	Jenis
123456789	User
-123456789	Grup biasa (basic group)
-1001234567890	Supergroup atau channel

ID cuma bisa dipakai kalau akun kamu udah "kenal" chat-nya: ada di daftar chat kamu, atau orangnya barusan muncul di Ambil Member Group. Kalau dapet 400 chat not found, pakai username, atau panggil Ambil Member Group grupnya dulu.

Username

Username boleh ditulis azickri, @azickri, t.me/azickri, atau https://t.me/azickri. Zate ngebuang awalannya sendiri. Kalau formatnya nggak valid (misalnya ada spasi atau nggak diawali huruf), kamu dapet 400 invalid chat.

Nomor HP

Biar nggak ribet, Zate ngerapihin nomor yang kamu kirim, sama kayak Zawa:

• Karakter selain angka dibuang, jadi +62 812-3456-7890 tetap jalan.
• Awalan 0 otomatis diganti 62, jadi 081234567890 jadi 6281234567890.
• Setelah dirapihin, nomornya minimal harus 8 digit. Kalau kurang, kamu dapet 400 invalid receiver.

Nomor HP nggak selalu bisa dipakai

Beda sama WhatsApp, di Telegram orang bisa nyembunyiin diri dari pencarian nomor (Settings → Privacy and Security → Phone Number → Who can find me by my number). Kalau nomornya nggak terdaftar atau disembunyiin, kamu dapet 400 phone is not on telegram or hidden by its privacy settings. Username atau ID user selalu lebih bisa diandelin.

Format Teks

Secara bawaan, teks dikirim apa adanya. Karakter kayak * dan _ nggak diubah jadi format apa pun. Kalau mau teks tebal, miring, atau link, isi parseMode:

parseMode	Yang didukung	Contoh
(kosong)	Teks biasa	Halo *semua* tampil persis begitu
markdown	**tebal**, __miring__, ~~coret~~, `kode`, ```blok kode```	Halo **semua**
html	<b>, <i>, <u>, <s>, <code>, <pre>, <a href>, <blockquote>, <spoiler>	Halo <b>semua</b>, <a href="https://zate.azickri.com">Zate</a>

Markdown versi Telegram ini nggak sama kayak Markdown biasa, contohnya *satu bintang* nggak bikin miring. Buat link, garis bawah, spoiler, atau kutipan, pakai html. parseMode juga berlaku buat caption gambar, video, dan dokumen.

Kirim Media dari URL

Zate nggak nerima upload file. Kamu cukup kasih URL, nanti Zate yang download terus kirim ke Telegram. Biar lancar:

• URL harus publik dan langsung mengarah ke file-nya, bisa dibuka tanpa login. Link halaman preview (misalnya halaman share Google Drive) nggak bakal jalan.
• Gambar dikirim ulang sebagai JPEG. Zate ngecilin gambar sampai sisi terpanjangnya maksimal 2560 piksel, biar lolos batas foto Telegram.
• Video dikirim sebagai MP4 yang bisa di-stream. Ukuran dan durasinya dibaca langsung dari file. thumbnail itu opsional: kalau kosong, Zate ngambil frame pertama videonya.
• Audio dikirim sebagai file audio biasa, bukan voice note. Nama file di URL jadi judulnya kalau file-nya nggak punya tag.
• Dokumen tampil dengan nama dari name, dan ekstensinya yang nentuin jenis file di Telegram. Jadi pastiin name ada ekstensinya, misalnya invoice.pdf.
• mimetype tetap wajib diisi, misalnya image/jpeg, video/mp4, audio/mpeg, atau application/pdf, biar request-nya sama persis kayak Zawa.

Ada juga batas waktunya:

Batas	Nilai
Server file harus mulai ngirim data	60 detik
Download macet (nggak ada data masuk)	30 detik
Download thumbnail video	30 detik
Total proses kirim satu pesan atau story	4 menit
Ukuran body JSON	25 MB

Link Media Publik

Media di Telegram nggak punya URL publik. Biar tetap gampang dipakai, semua media yang Zate kasih ke kamu, baik dari Ambil Pesan Channel maupun dari webhook, berupa link ke Ambil Media:

https://api-zate.azickri.com/media/68b3f0a2c1d4e5f6a7b8c9d0/-1001234567890/100/photo/Xk3d9QmPz0aB1cD2eF3gH4.jpg

Link itu bisa dibuka tanpa header, langsung dipasang di <img> atau <video>, dan di-stream sedikit-sedikit dari Telegram. Detailnya ada di Ambil Media.

Beda sama media, picture di sesi, grup, dan channel dikirim langsung sebagai data URI (data:image/jpeg;base64,...), jadi bisa langsung dipakai tanpa request lagi.

Format Response

Kalau berhasil, kamu dapet status 200 dengan objek JSON. Endpoint yang ngembaliin daftar selalu bungkus datanya di docs:

{
  "docs": [
    { "id": "-1001234567890", "name": "Komunitas Zate" }
  ]
}

Kalau gagal, bentuknya selalu sama:

{
  "statusCode": 400,
  "message": "invalid header"
}

Kalau ada beberapa kolom yang salah sekaligus, pesan-pesannya digabung pakai baris baru (\n) di message. Error yang datang langsung dari Telegram ikut diterusin dengan format kode: NAMA_ERROR (caused by ...). Daftar lengkap error dan cara ngatasinnya ada di Error & Solusi.

Batasan Lain yang Perlu Diingat

• Indikator mengetik dari Kirim Typing cuma tampil 5 detik.
• Ambil Pesan Channel ngambil 100 pesan per halaman.
• Ambil Member Group ngambil maksimal 10.000 anggota.
• created di grup dan channel itu tanggal akun kamu gabung, bukan tanggal grup atau channel-nya dibikin. Telegram cuma ngasih tanggal pembuatan ke yang bukan anggota.
• Deskripsi grup disimpan sementara selama 5 menit, jadi perubahan deskripsi bisa telat muncul.
• Akun Telegram gratis punya batas jumlah story per hari. Kalau udah kena, Telegram nolak story berikutnya.