TeleSapa API
Developer documentation

Bangun aplikasi di atas TeleSapa

Referensi endpoint untuk autentikasi, percakapan, lampiran, status, panggilan, dan administrasi. API menggunakan JSON kecuali upload file, yang menggunakan multipart/form-data.

BASE URLhttps://api.telesapa.com/api/v1

Quick start

Untuk menerima atau mengirim pesan atas nama satu pengguna, pengguna masuk ke TeleSapa lalu membuat key sendiri di API & Integrasi. Key ini menjadi [REDACTED:bearer-auth:12] dan terikat ke akun pembuatnya. Tidak perlu membagikan client key global kepada setiap pengguna.

Perlakukan API key pengguna seperti password. Simpan di secret storage server/aplikasi, jangan di source code publik atau JavaScript browser. Key hanya dapat dilihat saat dibuat dan dapat dicabut pemiliknya.
curl 'https://api.telesapa.com/api/v1/rooms' \\ -H 'Authorization: [REDACTED:bearer-auth:28]' \\ -H 'Accept: application/json'

Client key global tetap tersedia untuk aplikasi native yang memerlukan alur daftar/masuk. Endpoint daftar dan login menggunakan X-TeleSapa-App-Key karena belum ada API key pengguna sebelum pengguna masuk.

Header & autentikasi

Gunakan header berikut untuk API key pengguna. Akses dibatasi oleh scope saat key dibuat dan keanggotaan ruang milik akun tersebut.

Accept: application/json Content-Type: application/json Authorization: [REDACTED:bearer-auth:28]

Alur client key global: kirim X-TeleSapa-App-Key pada endpoint daftar/masuk, lalu gunakan Authorization: [REDACTED:bearer-auth:24]. Jangan menukar user token dengan client key.

API key pengguna: izin per akunClient key: identitas aplikasi daftar/masukHTTPS

Alur integrasi kirim/terima pesan

  1. Pengguna membuat key di API & Integrasi dan memilih izin baca/tulis.
  2. Panggil GET /rooms untuk daftar ruang yang diizinkan.
  3. Kirim pesan dengan POST /rooms/{room}/messages.
  4. Terima pesan baru dengan polling GET /updates?after_id={cursor}; simpan next_after_id untuk permintaan selanjutnya.
  5. Ambil riwayat dengan GET /rooms/{room}/messages?before_id={id}, lalu tandai sudah dibaca dengan POST /rooms/{room}/read.
// Kirim pesan fetch('https://api.telesapa.com/api/v1/rooms/ROOM_ID/messages', { method: 'POST', headers: { 'Authorization': '[REDACTED:bearer-auth:28]', 'Content-Type': 'application/json', 'Accept': 'application/json' }, body: JSON.stringify({ body: 'Halo dari aplikasi saya' }) }); // Terima pesan baru (lakukan polling berkala) fetch('https://api.telesapa.com/api/v1/updates?after_id=LAST_MESSAGE_ID', { headers: { 'Authorization': '[REDACTED:bearer-auth:28]', 'Accept': 'application/json' } });

API key per pengguna

Pemilik akun membuka halaman API & Integrasi untuk membuat koneksi bernama, memilih scope, dan menentukan masa berlaku. Maksimal 10 key aktif per akun; default berlaku 90 hari, pilihan sampai 365 hari. Scope calls:manage terpisah dari izin baca pesan. Key lengkap hanya ditampilkan satu kali.

ScopeIzinContoh endpoint
messages:readMenerima pesan dan membaca ruang, kontak, status, lampiran, serta riwayatGET /rooms, GET /updates
messages:writeMengirim atau mengelola pesan dan lampiranPOST /rooms/{room}/messages
calls:manageMelihat panggilan, mulai/akhiri, dan bergabung ke panggilanGET /calls, POST /calls/{call}/token
reports:readMelihat agregat akun serta pesan terkirim per koneksi (Web, client app, API key)GET /reports/overview, GET /reports/messages, GET /reports/connections

Key dikelola lewat sesi akun: GET /user-api-keys untuk daftar, POST /user-api-keys untuk membuat (body berisi name, scopes, dan opsional expires_in_days), serta DELETE /user-api-keys/{id} untuk mencabut key milik sendiri.

Key read-only tidak dapat mengirim pesan. Statistik per koneksi mulai tercatat setelah fitur ini dipasang; pesan lama tetap muncul di total akun, tetapi tidak punya label koneksi. Endpoint pengelolaan API key tetap memerlukan sesi masuk TeleSapa.

Content-Type: application/json X-TeleSapa-App-Key: YOUR_APP_KEY Authorization: [REDACTED:bearer-auth:24]
App key: semua request native[REDACTED:bearer-auth:12]: endpoint privatHTTPS

Akun & OTP

Gunakan format nomor internasional E.164, misalnya +628123456789. OTP dapat diatur dari panel admin. Bila OTP dimatikan, field otp tidak perlu dikirim.

GET/register/optionsStatus registrasi dan OTP

Publik untuk aplikasi. Respons: {"registration_enabled":true,"otp_enabled":true}.

POST/register/otpKirim OTP ke nomor

Body: {"phone":"+628123456789"}. Kode enam digit berlaku 5 menit; maksimal lima percobaan verifikasi. Pengiriman memerlukan gateway SMS yang diatur superadmin.

POST/registerDaftar akun baru

Body wajib: phone, name, password (minimal 12 karakter), accept_workplace_notice:true. Sertakan otp enam digit jika OTP aktif. Respons sukses 201 berisi access_token, token_type, expires_in, dan ringkasan akun.

POST/loginMasuk

Body: {"phone":"+628123456789","password":"…"}. Respons sukses memberikan [REDACTED:bearer-auth:12] berlaku 30 hari. Login dibatasi percobaan per IP.

GET/meProfil akun saat ini

Memerlukan autentikasi. Mengembalikan id, nomor telepon, nama, tipe akun, dan avatar_url jika foto profil tersedia.

PUT/me/avatarGanti foto profil

Gunakan multipart/form-data dengan field avatar. JPG, PNG, atau WebP; maksimal 5 MB.

DELETE/me/avatarHapus foto profil

Menghapus foto profil akun aktif dan kembali memakai inisial.

GET/accounts/{account}/avatarFoto profil akun

Memerlukan akses baca. Akun dapat mengambil foto sendiri atau foto anggota yang berbagi ruang percakapan.

POST/logoutCabut sesi saat ini

Memerlukan [REDACTED:bearer-auth:13]

Chat & pesan

Semua endpoint di bagian ini memerlukan [REDACTED:bearer-auth:12] dan anggota ruang yang sesuai.

GET/roomsDaftar ruang dan unread count

Respons berisi data ruang milik akun, ringkasan pesan, dan jumlah belum dibaca.

GET/rooms/{room}/messages?before_id={id} atau ?after_id={id}Riwayat pesan, 50 per halaman

Gunakan before_id untuk mengambil hingga 50 pesan lebih lama, atau after_id untuk mengambil hingga 50 pesan baru. Jangan kirim keduanya sekaligus. Hasil disajikan berurutan dari lama ke baru dan mengembalikan cursor berikutnya. Body pesan mencakup pengirim, jenis, reply, detail polling/acara, dan delivery_state untuk pesan Anda sendiri: sent (menunggu perangkat penerima), delivered (sudah diterima semua anggota lain), atau read (sudah dibaca semua anggota lain).

POST/rooms/{room}/messagesKirim pesan teks

Body: {"body":"Halo"}; maksimal 10.000 karakter. Kata yang masuk daftar blokir ditolak.

GET/updates?after_id={id}Ambil pembaruan pesan

Gunakan polling berkala dengan next_after_id sebagai cursor. Respons berisi hingga 100 pesan lengkap: id, room_id, sender_account_id, sender_name, sender_type, body, message_type, reply_to_id, edited_at, created_at, delivery_state, serta detail polling/acara bila tersedia. Untuk pesan milik akun sendiri, delivery_state bernilai sent, delivered, atau read sesuai penerimaan perangkat dan status baca anggota ruang. Gunakan next_after_id sebagai cursor; ulangi sampai cursor tidak berubah untuk mengambil seluruh backlog.

POST/rooms/{room}/readTandai ruang sudah dibaca

Body JSON kosong: {}.

GET/ai/accessCek izin Oki AI

Respons: {"enabled":true}. Ikuti visibilitas yang diatur superadmin; bila tidak tersedia, pembuatan ruang dan pengiriman pesan ditolak.

POST/ai/roomsBuat atau buka ruang Oki AI

Body JSON kosong: {}. Memerlukan izin messages:write dan akses Oki AI yang aktif bagi akun.

POST/ai/rooms/{room}/messagesKirim pesan ke Oki AI

Body: {"body":"Pertanyaan"}. Memerlukan izin messages:write dan akses Oki AI yang aktif bagi akun.

POST/directMulai chat pribadi

Buat ruang percakapan langsung dengan akun lain. Lihat validasi data anggota yang berlaku di versi server.

POST/groupsBuat grup

Grup mendukung anggota hingga batas yang diberlakukan server; organization_id opsional untuk grup organisasi.

GET/messages/search?q={query}Cari pesan

Pencarian hanya mencakup ruang yang dapat diakses akun.

PATCH/messages/{message}Edit pesan teks sendiri

Body: {"body":"Teks yang diperbarui"}. Batas edit 15 menit sejak pesan dibuat.

DELETE/messages/{message}Hapus pesan sendiri

Pesan dihapus secara logis dan isi pesan dikosongkan.

Lampiran

POST/rooms/{room}/attachmentsUpload file · multipart/form-data

Field multipart: file wajib, display_mode opsional dengan nilai document, media, atau audio. Maksimum 20 MB. Jenis yang didukung antara lain gambar, PDF, dokumen Office, ZIP, video, dan audio.

GET/attachments/{uuid}/downloadUnduh lampiran

Memerlukan akses anggota ke ruang asal lampiran. Respons berupa stream file.

Pesan interaktif

POST/rooms/{room}/interactive-messagesKontak, polling, acara, stiker

Kirim kind bernilai contact, poll, event, atau sticker bersama field khusus jenis tersebut. Poll: question, options, allow_multiple. Event: title, starts_at, serta description/location opsional.

POST/messages/{message}/poll-votePilih opsi polling

Body: {"option_ids":[1]}.

POST/messages/{message}/event-rsvpRespons acara

Body: {"status":"yes"}; pilihan yes, maybe, atau no.

Kontak & workspace

GET/contactsKontak tersimpan

Daftar kontak yang sudah tersinkron.

POST/contacts/matchCocokkan nomor telepon

Gunakan daftar nomor dalam format internasional. Hanya kecocokan akun yang dikembalikan.

POST/contacts/syncSimpan hasil sinkron kontak

Memerlukan kontak yang cocok dari endpoint pencocokan.

GET/workspacesDaftar workspace

Daftar organisasi/workspace yang dapat diakses akun.

GET/organizations/{organization}/membersDirektori anggota organisasi

Hanya untuk anggota aktif organisasi terkait.

POST/organizations/{organization}/groupsBuat grup organisasi

Anggota grup harus menjadi anggota aktif organisasi tersebut.

Status

GET/statusesFeed status yang terlihat

Cursor opsional: before_id. Status kedaluwarsa setelah 24 jam.

POST/statusesBuat status

JSON untuk teks: kind=text, text, dan visibility=contacts|private. Untuk media gunakan multipart kind=image|video, field file, dan teks opsional.

GET/statuses/{status}Lihat status

Akses dicatat sebagai view saat status milik pengguna lain.

GET/statuses/{status}/mediaStream media status

Memerlukan hak melihat status.

GET/statuses/{status}/viewersDaftar penonton milik sendiri

Hanya pemilik status yang dapat melihat daftar penonton.

POST/statuses/{status}/replyBalas status ke chat pribadi

Body: {"body":"Balasan"}.

DELETE/statuses/{status}Hapus status sendiri

Menghapus status dan data view/reply terkait.

Panggilan & media

GET/rtc/statusStatus layanan panggilan

Menunjukkan status konfigurasi LiveKit; detail server hanya ditampilkan kepada superadmin.

GET/callsRiwayat panggilan

Gunakan before_id untuk halaman sebelumnya.

GET/calls/incomingPanggilan masuk

Daftar panggilan yang menunggu akun untuk bergabung.

GET/rooms/{room}/calls/activePanggilan aktif di ruang
POST/rooms/{room}/callsMulai panggilan

Body: {"type":"audio"} atau {"type":"video"}.

POST/calls/{call}/tokenAmbil token ruang LiveKit

Token dibuat untuk anggota ruang yang berhak bergabung.

POST/calls/{call}/endAkhiri panggilan

Memerlukan akses ke panggilan.

API administrasi

Endpoint admin memerlukan [REDACTED:bearer-auth:12] akun yang memiliki peran. API key penuh hanya dikelola superadmin melalui panel.

MethodEndpointAksesFungsi
GET/admin/overviewAdminRingkasan akun dan konfigurasi
GET/admin/users?q=&page=AdminCari dan daftar akun
PATCH/admin/users/{account}Admin{"status":"banned","reason":"…"} atau status active
GET/POST/admin/banned-wordsAdminDaftar/tambah kata; input term, match_mode=whole|contains
DELETE/admin/banned-words/{word}AdminHapus aturan kata
GET/PATCH/admin/settingsAdmin / superadminToggle OTP, pendaftaran, dan visibilitas Oki AI; kredensial SMS serta akses Oki AI superadmin
GET/admin/audit-eventsAdminRiwayat perubahan admin
GET/PUT/admin/admins, /admin/admins/{account}SuperadminDaftar admin dan grant/revoke; PUT body {"enabled":true}
GET/POST/app-keysSuperadminList/buat client key; respons create menampilkan key lengkap satu kali
DELETE/app-keys/{key}SuperadminCabut client key
PUT/rtc/settingsSuperadminAtur LiveKit di Konfigurasi panel superadmin

Error, akses, dan batas

HTTPArtiYang dilakukan klien
400/422Validasi atau aturan tidak terpenuhiTampilkan pesan validasi dari JSON message/errors.
401Token tidak ada, kedaluwarsa, dicabut, atau akun nonaktifMinta pengguna masuk kembali.
403Tidak punya peran, bukan anggota ruang, atau fitur sedang dinonaktifkanJangan ulangi tanpa perubahan akses.
404Resource tidak ditemukan atau tidak dapat diaksesPerbarui daftar resource.
429Rate limit tercapaiGunakan jeda/backoff sebelum mencoba kembali.
502/503Gateway SMS atau layanan terkait belum siapTampilkan error yang ramah dan coba lagi nanti.
Panggilan memakai LiveKit dan memerlukan konfigurasi RTC aktif. Upload file maksimal 20 MB. Semua akses data privat dibatasi oleh keanggotaan ruang atau organisasi.

Dokumentasi ini mengikuti endpoint TeleSapa API v1 yang aktif. Field request tertentu dapat berkembang; periksa pesan validasi dari server saat integrasi.