API dan Webhook Call untuk Developer: Kunci, Scope, dan Event
Tur praktis REST API Call: kunci API dan scope, batas laju, penanganan error, webhook bertanda tangan, dan halaman Pengembang tempat Anda mengelola endpoint.
Cepat atau lambat, sistem telepon harus berkomunikasi dengan sistem lain: CRM yang perlu menampilkan panggilan saat berakhir, alat penagihan yang ingin tahu siapa yang menelepon, skrip yang melakukan panggilan saat formulir dikirim. Call memiliki REST API dan webhook keluar untuk keperluan ini. Panduan ini menjelaskan bagaimana bagian-bagiannya saling terkait, apa yang perlu diminta sebelum menulis kode, dan kesalahan yang paling sering menghabiskan satu sore seorang developer.

Jika tujuan Anda hanya memindahkan kontak dalam jumlah besar, baca dulu Mengimpor Kontak ke CRM Tim Telepon; impor sering kali lebih mudah daripada integrasi.
Titik awal: rujukan dan halaman Pengembang
Ada dua tempat yang perlu diketahui. Rujukan API berada di Pengaturan, dan juga di menu Sumber daya di halaman beranda. Rujukan ini dapat dibaca tanpa masuk, yang memudahkan saat Anda menyusun ruang lingkup pekerjaan untuk klien. Halaman Pengembang, juga di Pengaturan, adalah untuk ruang kerja Anda sendiri: menampilkan ID organisasi dan agen, endpoint webhook, dan daftar kunci yang hanya bisa dibaca.
Yang diberikan setiap tempat
- Mulai di siniBase URL dan konvensi, autentikasi dengan tabel scope, serta error beserta kode statusnya.
- EndpointSetiap kartu endpoint mencantumkan scope, parameter, body permintaan, respons, dan error, dengan contoh permintaan siap salin dalam curl, JavaScript, dan Python.
- PencarianTekan / untuk melompat ke Cari endpoint dan memfilter berdasarkan metode, path, scope, atau ringkasan.
- OpenAPI JSONMengunduh seluruh spesifikasi sebagai satu file untuk alat Anda sendiri.
- ID agen / APIID dan slug organisasi Anda, mode API (Sandbox atau Langsung), dan ID agen AI yang Anda pilih, masing-masing dengan tombol Salin.
- WebhookEndpoint Anda, event yang diterima masing-masing, status HTTP terakhir, dan pengiriman yang gagal.
Baca bagian tentang batas laju dan webhook keluar sebelum Anda go-live, bukan sesudahnya. Bagian itu menjelaskan perilaku yang mudah terlewat dalam pengujian singkat.
Kunci API dan scope
Setiap permintaan membawa kunci di header Authorization sebagai bearer token. Kunci tidak dibuat di aplikasi: operator ruang kerja Anda yang menerbitkannya dan memberi tahu scope yang dimilikinya. Kunci lengkap hanya ditampilkan sekali saat diterbitkan, dan setelah itu hanya beberapa karakter pertamanya yang terlihat, jadi segera simpan di penyimpanan rahasia Anda sendiri.
| Scope | Yang diizinkan |
|---|---|
| read | Membaca kontak, panggilan, antrean, anggota tim, laporan, dan daftar jangan-telepon. |
| write | Membuat dan memperbarui kontak, mencatat hasil panggilan, menambahkan nomor ke daftar jangan-telepon. |
| calls | Melakukan dan mengakhiri panggilan. |
| admin | Mengelola webhook; juga dapat memanggil semua endpoint lain. |
Mintalah set terkecil yang cukup untuk pekerjaannya. Skrip pelaporan hanya butuh read; tombol klik-untuk-menelepon butuh calls. Jika permintaan mengembalikan 403 dengan kode insufficient_scope, kunci itu tidak memiliki scope yang tercantum di kartu endpoint tersebut.
Sandbox dan live
Kunci dapat diterbitkan untuk sandbox, yang memakai simulator dan tidak melakukan panggilan sungguhan, atau untuk penggunaan live. Anggap prefiks kunci hanya sebagai label: kunci berlabel test bekerja pada data dan sambungan telepon yang sama dengan kunci live, jadi jangan mengandalkan prefiks untuk menjauhkan eksperimen dari pelanggan sungguhan. Gunakan mode API yang ditampilkan di halaman Pengembang untuk mengetahui posisi Anda.
Melakukan panggilan lewat API
Endpoint publik mencakup hal-hal dasar: pemeriksaan kesehatan, daftar panggilan, membaca satu panggilan, melakukan panggilan, menutup panggilan, mengelola webhook, dan chat dengan agen AI. Panggilan keluar yang dilakukan lewat API melewati pemeriksaan kepatuhan yang sama dengan panggilan dari meja agen, jadi nomor yang ada di daftar jangan-telepon atau di luar jam panggilan yang diizinkan akan ditolak, persis seperti untuk agen. Rancang kode Anda agar menangani penolakan itu sebagai hasil normal, bukan bug.
Ini penting untuk desain. Jangan menulis loop yang terus mengulang panggilan yang ditolak sampai berhasil. Baca alasannya, catat di log, lalu lanjutkan. Untuk aturan di balik penolakan tersebut, lihat Pengaman Jam Panggilan di Call dan Daftar Jangan-Telepon di Call.
Batas laju dan error
Setiap kunci memiliki batas permintaan per menitnya sendiri, yang ditetapkan saat kunci diterbitkan; nilai bawaannya 120. Saat kunci menghabiskan jatah satu menit, API menjawab 429 dengan kode rate_limited dan memberi tahu berapa lama harus menunggu di header X-RateLimit-Reset. Tunggu selama itu, lalu lanjutkan. Klien yang sopan memperlambat dirinya sebelum menabrak batas.
- 429 rate_limited: mundur selama periode di header reset, dan sebarkan pekerjaan massal dalam rentang waktu.
- 403 insufficient_scope: kunci tidak memiliki scope yang tercantum di kartu endpoint; minta kunci yang memilikinya.
- Error lain: bertindaklah berdasarkan kode error, bukan pesannya. Kode tidak berubah; kata-katanya bisa berubah.
Menangani permintaan yang gagal
- Baca statusnyaApakah ini error klien yang bisa Anda perbaiki, atau error server yang layak dicoba ulang?
- Baca kodenyaBuat percabangan berdasarkan kode, jangan pernah berdasarkan teks pesan.
- MundurUntuk 429, tunggu sesuai header reset; untuk error server, coba ulang beberapa kali dengan jeda yang makin panjang.
- Catat detailnyaSimpan endpoint, kode, dan waktunya agar tim dukungan bisa melacaknya.
- Berhenti saat ditolakPenolakan kepatuhan adalah keputusan, bukan gangguan; jangan diulang terus-menerus.
Webhook: menerima event
Alih-alih terus-menerus bertanya ke API apakah sesuatu sudah terjadi, biarkan Call yang memberi tahu Anda. Di halaman Pengembang, tekan Tambah endpoint, masukkan alamat https publik, dan centang event yang Anda inginkan; tidak mencentang apa pun berarti semua event. Signing secret ditampilkan sekali, saat endpoint ditambahkan. Salin saat itu juga. Jika hilang, hapus endpoint dan tambahkan lagi untuk mendapatkan yang baru.
Setiap pengiriman ditandatangani. Header tanda tangan berisi HMAC-SHA256 dari timestamp dan body yang digabung dengan tanda titik, dihitung dengan signing secret Anda, dan header terpisah membawa timestamp-nya. Hitung ulang di sisi Anda dan bandingkan sebelum memercayai payload. Rujukan API menyertakan contoh kode untuk ini dalam Node.js dan Python, dan menolak timestamp lama melindungi Anda dari permintaan yang diputar ulang.
Penerima webhook yang baik dan yang buruk
| Baik | Buruk | |
|---|---|---|
| Tanda tangan | Diverifikasi di setiap permintaan | Dipercaya tanpa diperiksa |
| Balasan | 2xx dalam hitungan detik, pekerjaan diantrekan untuk nanti | Pemrosesan lambat sebelum membalas |
| Duplikat | Aman menerima event yang sama dua kali | Membuat dua catatan |
| Kegagalan | Memberi peringatan saat pengiriman gagal | Diam sampai ada yang menyadari |
Endpoint Anda harus menjawab dengan status 2xx dalam 10 detik. Pengiriman yang gagal akan dicoba lagi, hingga enam kali percobaan secara keseluruhan, dan endpoint yang gagal 50 kali berturut-turut akan dinonaktifkan. Setiap baris di halaman Pengembang menampilkan status HTTP terakhir dan berapa banyak pengiriman yang gagal, dan Kirim uji coba mengirim satu event uji bertanda tangan agar Anda bisa melihat jawaban server Anda.
Daftar periksa go-live
Sebelum mengaktifkan integrasi
- Anda tahu scope apa yang dimiliki kunci, dan tidak lebih dari yang dibutuhkan
- Kunci disimpan di penyimpanan rahasia, bukan di kode sumber
- Tanda tangan webhook diverifikasi dan timestamp lama ditolak
- Penerima membalas dengan cepat dan menangani event duplikat
- Respons batas laju dan penolakan ditangani tanpa loop coba ulang yang rapat
- Anda sudah menguji di mode sandbox dan menekan Kirim uji coba pada endpoint
- Ada orang yang ditunjuk untuk menerima peringatan jika pengiriman mulai gagal
Melakukannya di Call
Di Call, buka Pengaturan, lalu Rujukan API untuk mempelajari endpoint, dan Pengaturan, lalu Pengembang untuk menyalin ID organisasi, memeriksa kunci, dan menambahkan webhook. Pemilik, admin, dan manajer dapat menambah, menguji, dan menghapus endpoint; yang lain hanya melihat daftarnya. Jika Anda juga memakai fitur agen AI, ID agen di halaman yang sama dipakai untuk endpoint chat. Untuk sisi suara produk, lihat Menyiapkan Agen AI di Call.
Pertanyaan yang sering diajukan
Bagaimana cara mendapatkan kunci API?
Kunci diterbitkan oleh operator ruang kerja Anda; kunci tidak dapat dibuat di aplikasi. Mintalah dan sebutkan scope yang dibutuhkan. Kunci lengkap ditampilkan sekali saat diterbitkan.
Apa arti respons 429?
Kunci sudah menghabiskan jatah permintaan untuk menit ini. Tunggu selama jumlah detik di header X-RateLimit-Reset, lalu coba lagi, dan sebarkan pekerjaan massal dalam periode yang lebih panjang.
Bagaimana cara memastikan webhook benar-benar berasal dari Call?
Hitung HMAC-SHA256 dari timestamp dan body dengan signing secret Anda, lalu bandingkan dengan header tanda tangan. Rujukan API menampilkan contohnya dalam Node.js dan Python.
Bisakah saya mengirim webhook ke server pengembangan lokal?
Tidak secara langsung. Endpoint harus berupa alamat https publik, jadi gunakan alat tunneling yang mengekspos server lokal Anda di alamat semacam itu.
Mengapa panggilan yang saya lakukan lewat API ditolak?
Panggilan lewat API melewati pemeriksaan kepatuhan yang sama dengan panggilan dari meja agen. Nomor yang ada di daftar jangan-telepon atau di luar jam panggilan akan ditolak.
Siapa yang dapat melihat dan mengubah webhook?
Semua orang dapat membaca daftarnya, tetapi hanya pemilik, admin, dan manajer yang dapat menambah, menguji, atau menghapus endpoint.