Kunci API dan cakupan akses

REST API Ringhum memungkinkan sistem Anda sendiri bekerja dengan workspace Anda: menampilkan daftar panggilan dan transkrip, membuat asisten, memesan janji temu, mengelola kontak, melakukan panggilan keluar, dan banyak lagi. Setiap permintaan diautentikasi dengan kunci API yang dimiliki satu workspace. Artikel ini membahas cara membuat kunci dan konvensi yang berlaku di semua endpoint. Referensi endpoint lengkap ada di /docs.

Siapa yang dapat mengelola kunci

API tersedia di semua paket. Yang dapat dilakukan oleh sebuah kunci tetap dibatasi oleh paket Anda: misalnya, membuat asisten melebihi batas paket Anda akan mengembalikan error.

Membuat kunci API

1. Buka Developer di sidebar.
2. Di kartu Kunci API, klik Buat kunci.
3. Masukkan Nama kunci yang menunjukkan di mana kunci ini digunakan, misalnya "Server produksi".
4. Di bagian Cakupan, centang read, write, atau keduanya.
5. Klik Buat kunci.
6. Salin kunci dari kotak hijau dan simpan di tempat yang aman, misalnya penyimpanan rahasia (secret store) server Anda. Klik Selesai.

Penting: Kunci hanya ditampilkan satu kali. Ringhum hanya menyimpan sidik jari (fingerprint) kunci tersebut, sehingga tidak dapat ditampilkan lagi. Jika Anda kehilangannya, buat kunci baru dan cabut kunci yang lama.

Kunci diawali dengan ck_live_. Tabel Kunci API menampilkan nama setiap kunci, karakter awal kunci, cakupannya, kapan terakhir digunakan, dan apakah statusnya Aktif atau Dicabut.

Cakupan

Setiap kunci dapat memanggil endpoint yang hanya membaca. Endpoint yang membuat, mengubah, atau menghapus sesuatu memerlukan cakupan write. Contohnya adalah melakukan panggilan, mengirim pesan, memesan janji temu, atau memperbarui asisten. Referensi di /docs menandai endpoint-endpoint ini. Kunci tanpa write akan menerima error 403 pada endpoint tersebut.

Berikan setiap sistem akses seminimal yang dibutuhkannya. Dasbor pelaporan hanya memerlukan read.

Mencabut kunci

1. Di Developer, temukan kunci di tabel Kunci API.
2. Klik Cabut dan konfirmasi.

Permintaan yang menggunakan kunci tersebut akan langsung gagal dengan error 401. Kunci yang dicabut tetap ada di daftar, ditandai Dicabut, sehingga Anda dapat melihat riwayatnya. Kunci tidak dapat diedit: untuk mengubah cakupannya, buat kunci baru dan cabut kunci yang lama.

Melakukan permintaan

• URL dasar: https://ringhum.com/api/v1
• Autentikasi: kirim kunci sebagai Bearer token: Authorization: Bearer ck_live_…
• Format: JSON untuk masuk dan keluar. Kirim Content-Type: application/json dengan body.
• Waktu menggunakan format ISO 8601 dalam UTC. Nomor telepon menggunakan format E.164, misalnya +14155550132. Id berupa bilangan bulat.
• Pembaruan menggunakan PATCH hanya dengan field yang ingin Anda ubah.
• Setiap respons membawa header X-Request-Id. Sertakan header ini saat menghubungi dukungan.

curl "https://ringhum.com/api/v1/calls?per_page=10" \
  -H "Authorization: Bearer ck_live_…"

Untuk memeriksa workspace mana yang dimiliki sebuah kunci, panggil GET /me.

Respons dan paginasi

Objek tunggal dikembalikan sebagai {"data": {…}}. Daftar yang dipaginasi dikembalikan dengan objek meta:

{
  "data": [ … ],
  "meta": {
    "current_page": 1,
    "last_page": 4,
    "per_page": 25,
    "total": 87,
    "next_page_url": "https://ringhum.com/api/v1/calls?page=2",
    "prev_page_url": null
  }
}

Gunakan page dan per_page untuk berpindah antar hasil. per_page defaultnya adalah 25 dan maksimal 100.

Error

Setiap kegagalan memiliki bentuk yang sama, dengan type yang stabil dan dapat Anda periksa dalam kode Anda:

{
  "error": {
    "type": "validation_error",
    "message": "The to field format is invalid.",
    "errors": { "to": ["Use E.164 format, e.g. +15551234567."] }
  }
}

Batas laju permintaan

Anda dapat melakukan 120 permintaan per menit. Respons menyertakan header X-RateLimit-Limit dan X-RateLimit-Remaining. Jika Anda melebihi batas, Anda akan menerima 429 dengan header Retry-After yang menunjukkan berapa detik harus menunggu.

Tip: Jangan melakukan polling untuk hasil panggilan. Tambahkan webhook untuk call.ended dan Ringhum akan mengirimkan ringkasan dan transkrip kepada Anda saat panggilan selesai. Lihat Webhook.

Pertanyaan umum

Apakah ada spesifikasi yang dapat dibaca mesin? Ya. Deskripsi OpenAPI 3.1 ada di /api/v1/openapi.json dan tidak memerlukan kunci. Anda dapat membuat client darinya.

Apakah kunci berhenti berfungsi jika orang yang membuatnya keluar? Tidak. Kunci dimiliki oleh workspace dan tetap berfungsi hingga dicabut. Cabut kunci yang tidak lagi Anda percayai, terutama saat seseorang yang memiliki akses keluar.

Bisakah saya menggunakan API dari halaman web? Tidak. Siapa pun yang membuka halaman tersebut dapat membaca kunci. Panggil API dari server Anda.