API v1

REST dan JSON. Aplikasi Onix sendiri memakai API yang sama, jadi data yang kamu lihat di aplikasi datang lewat endpoint ini.

Base URL: https://onix.sassly.ai/api/v1. Semua path di halaman ini relatif terhadap base URL. Body request berformat JSON (Content-Type: application/json). Spesifikasi lengkap OpenAPI 3.1: /docs/openapi.yaml — bisa diimpor ke Postman, Insomnia, atau generator SDK.

Autentikasi

Membuat API key

1. Buka Pengaturan → API (butuh akses Kelola API key; khusus Pro).
2. Klik Buat key, beri nama (mis. "Integrasi CRM"), lalu pilih scope: read (hanya membaca) atau write (membaca dan mengubah data).
3. Key berawalan onx_live_ dan hanya ditampilkan sekali. Simpan di secret manager; jangan taruh di kode frontend atau repositori.
4. Maksimal 10 key aktif per workspace. Request dengan key yang sudah dicabut dibalas 401.

export ONIX_API_KEY="onx_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

API key bertindak atas nama workspace dan tidak dibatasi role, jadi perlakukan seperti password. Endpoint pengelolaan (anggota, role, pengaturan, API key, tagihan) hanya bisa dari aplikasi. API tidak mendukung CORS: panggil dari server, bukan dari JavaScript di browser.

Format respons

Respons sukses selalu berbentuk {"data": …, "meta": {…}}; meta hanya ada bila relevan. Respons error selalu berbentuk:

{
  "error": {
    "code": "validation_error",
    "message": "Nama workspace 2–120 karakter.",
    "fields": {"name": "Nama workspace 2–120 karakter."}
  }
}

• code tetap dan aman dipakai di logika program; message adalah teks untuk manusia yang mengikuti bahasa (header X-Locale: en|id).
• fields hanya ada pada error input, berisi pesan per kolom.
• Waktu selalu UTC dalam ISO 8601, mis. 2026-10-08T02:30:00Z. Ubah ke zona waktumu sendiri saat menampilkan; aplikasi Onix memakai zona pribadi pengguna atau zona workspace.
• Daftar berhalaman menerima page (mulai 1) dan per_page (maks. 100, bawaan 25 kecuali disebut lain), lalu mengembalikan meta.page, meta.per_page, meta.total, dan meta.pages.

Batas request

• 120 request per menit per API key.
• Respons memuat header X-RateLimit-Limit dan X-RateLimit-Remaining.
• Lewat batas dibalas 429 rate_limited dengan header Retry-After (detik sampai menit berikutnya).

Kode error

Endpoint

Kolom Permission menunjukkan hak akses yang dibutuhkan pengguna aplikasi (diatur lewat role); "—" berarti semua anggota workspace. API key dianggap punya semua permission workspace dan melihat semua data.

Batas data (tim): permission mengatur menu & aksi, sedangkan data percakapan & tiket yang terlihat mengikuti tim. Percakapan yang belum di-assign terlihat semua yang punya interactions.view; yang di-assign ke tim Frontline hanya terlihat anggota tim itu; yang di-assign ke orang hanya terlihat orang itu. Tiket tanpa penanggung jawab terlihat anggota tim Back Office-nya; tiket dengan penanggung jawab hanya terlihat peserta (penanggung jawab, pembuat, yang di-@mention). Artikel knowledge base khusus tim hanya terlihat anggota tim yang dipilih (tanpa tim = semua tim). Lead pipeline tanpa PJ terlihat anggota tim lead-nya; lead ber-PJ hanya terlihat PJ-nya. Owner, role admin, dan anggota "Bisa lihat semua data" melihat semuanya (akses channel tetap berlaku). Data yang tidak boleh dilihat dibalas 404.

Bisa dipanggil dengan API key

Khusus aplikasi Onix

Endpoint berikut hanya menerima sesi aplikasi (cookie + X-CSRF-Token). Dengan API key dibalas 403 forbidden.

Publik

Widget livechat (publik)

Dipanggil widget livechat (pemuat livechat.js & iframe Onix) tanpa login. {key} = kunci publik channel. Selain config dan logo, semua memakai token pengunjung di Authorization: Bearer. Penjelasan lengkap: Livechat.

Channel API (kunci channel)

Untuk sistem Anda yang mengirim pesan pelanggan ke Onix lewat channel API, dengan kunci channel onx_ch_… di Authorization: Bearer (bukan API key workspace). Balasan agen dikirim ke webhook Anda. Panduan, contoh payload, dan verifikasi tanda tangan: Channel API.

Contoh

Siapa pemilik key ini

curl -s "https://onix.sassly.ai/api/v1/me" \
  -H "Authorization: Bearer $ONIX_API_KEY"

{
  "data": {
    "user": {"id": 12, "name": "Budi Santoso", "email": "[email protected]", "avatar_url": null, "locale": "id", "timezone": null, "last_login_at": "2026-10-08T02:00:00Z"},
    "via": "key",
    "timezone": "Asia/Jakarta",
    "workspace": {
      "id": 3, "name": "Toko Budi", "slug": "toko-budi", "plan": "pro", "pro_until": "2026-11-08T03:15:00Z", "in_grace": false, "timezone": "Asia/Jakarta",
      "limits": {"channels": 4, "users": 10, "tickets_per_month": 200, "replies_per_day": 0, "ai_per_month": 2000, "ai": true, "api": true},
      "created_at": "2026-10-08T02:00:00Z"
    },
    "role": {"id": 1, "name": "Owner"},
    "is_owner": true,
    "is_platform_admin": false,
    "permissions": ["dashboard.view", "interactions.view", "interactions.reply", "interactions.assign", "templates.manage", "channels.manage", "settings.members", "settings.roles", "settings.billing", "settings.audit", "settings.workspace", "settings.api"],
    "channel_ids": null,
    "realtime": true
  }
}

Pada limits, nilai 0 berarti tanpa batas. channel_ids bernilai null berarti akses ke semua channel. timezone adalah zona efektif (zona pribadi pengguna, atau zona workspace).

Membalas pelanggan WhatsApp

Cari percakapan yang belum dibalas, lalu kirim balasan (butuh key ber-scope write). Pesan dikirim lewat nomor WhatsApp percakapan itu dan tercatat atas nama key.

curl -s "https://onix.sassly.ai/api/v1/interactions?tab=unreplied&per_page=5" \
  -H "Authorization: Bearer $ONIX_API_KEY"

curl -s -X POST "https://onix.sassly.ai/api/v1/interactions/42/messages" \
  -H "Authorization: Bearer $ONIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Halo kak, pesanan sudah kami kirim hari ini 🙏"}'

{
  "data": {
    "id": 981, "interaction_id": 42, "direction": "out", "type": "text", "body": "Halo kak, pesanan sudah kami kirim hari ini 🙏",
    "media": null, "reply_to": null, "sender": {"name": "API · CRM", "user_id": 12, "jid": null},
    "status": "sent", "error": null, "reactions": [], "sent_at": "2026-10-09T03:15:00Z", "created_at": "2026-10-09T03:15:00Z"
  },
  "meta": {"replies": {"used": 1, "limit": 0}}
}

Pesan yang ditolak WhatsApp tetap tersimpan dengan "status": "failed" dan alasan di error; kirim ulang lewat /retry. Maksimal 30 pesan per menit per nomor (429 bila lewat). Lampiran: kirim multipart/form-data dengan field file (maks. 16 MB).

Audit log anggota sejak awal bulan

curl -s "https://onix.sassly.ai/api/v1/audit-logs?category=anggota&from=2026-10-01&per_page=20" \
  -H "Authorization: Bearer $ONIX_API_KEY"

{
  "data": [
    {
      "id": 41, "action": "member.invited", "label": "Mengundang anggota", "category": "anggota", "icon": "user-plus",
      "target": "[email protected]", "details": "Role: Agent",
      "user": {"id": 12, "name": "Budi Santoso", "avatar_url": null},
      "ip": "203.0.113.10", "created_at": "2026-10-08T03:20:00Z"
    }
  ],
  "meta": {"page": 1, "per_page": 20, "total": 1, "pages": 1, "categories": [{"key": "anggota", "label": "Anggota & undangan"}, "…"], "users": [{"id": 12, "name": "Budi Santoso"}]}
}

Contoh JavaScript (Node 18+) dan PHP

const res = await fetch("https://onix.sassly.ai/api/v1/members", {
  headers: { Authorization: `Bearer ${process.env.ONIX_API_KEY}` },
});
const { data, error } = await res.json();
if (error) throw new Error(`${error.code}: ${error.message}`);

$ch = curl_init('https://onix.sassly.ai/api/v1/roles');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('ONIX_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);

Event real-time

Aplikasi menerima event lewat WebSocket (Centrifugo) di kanal ws:{workspace_id} dan user:{user_id}. Isi setiap event: {"event": "…", "data": {…}, "at": "…Z"}.

Kanal conv:{id} hanya diberikan bila pengguna boleh melihat percakapan itu (akses channel + aturan tim). Saat percakapan di-assign ke tim/orang lain, yang kehilangan akses otomatis dicabut dari kanalnya.

Kanal ticket:{id} hanya diberikan bila pengguna boleh membuka tiket itu (peserta, anggota tim untuk tiket tanpa penanggung jawab, atau melihat semua data).

Widget livechat memakai kanal terpisah visitor:{sesi} (token dari POST /livechat/{key}/realtime) dengan event message, queue, typing, dan read — lihat Livechat.