Menggunakan Call

API dan Webhook Call untuk Pembangun: Kunci, Skop, Acara

Lawatan praktikal API REST Call: kunci API dan skop, had kadar, pengendalian ralat, webhook bertandatangan dan halaman Pembangun untuk mengurus titik akhir.

Pasukan editorial Call · Diterbitkan · Bacaan 5 min

Lambat-laun, sistem telefon perlu berhubung dengan sistem lain: CRM yang patut memaparkan panggilan sebaik ia tamat, alat bil yang mahu tahu siapa yang menelefon, skrip yang membuat panggilan apabila borang dihantar. Call mempunyai API REST dan webhook keluar untuk tujuan ini. Panduan ini menerangkan bagaimana bahagian-bahagiannya berpadanan, apa yang perlu diminta sebelum menulis kod, dan kesilapan yang paling kerap membazirkan masa pembangun selama sepetang.

Seorang pembangun menyemak integrasi pada komputer riba di sebelah telefon meja
Imej ilustrasi

Jika matlamat anda hanyalah memindahkan kenalan secara pukal, baca Mengimport Kenalan ke dalam CRM Pasukan Telefon dahulu; import selalunya lebih mudah daripada integrasi.

Di mana bermula: rujukan dan halaman Pembangun

Ada dua tempat yang perlu diketahui. Rujukan API terletak di bawah Tetapan, dan juga dalam menu Sumber di halaman utama. Ia boleh dibaca tanpa log masuk, yang berguna apabila anda menganggar skop kerja untuk pelanggan. Halaman Pembangun, juga di bawah Tetapan, adalah untuk ruang kerja anda sendiri: ia memaparkan pengecam organisasi dan ejen anda, titik akhir webhook anda dan senarai baca sahaja kunci anda.

Apa yang diberikan setiap tempat

  • Mula di siniURL asas dan konvensyen, pengesahan dengan jadual skop, dan ralat dengan kod status.
  • Titik akhirSetiap kad titik akhir menyenaraikan skop, parameter, badan permintaan, respons dan ralatnya, dengan permintaan sedia untuk disalin dalam curl, JavaScript dan Python.
  • CarianTekan / untuk terus ke Cari titik akhir dan tapis mengikut kaedah, laluan, skop atau ringkasan.
  • OpenAPI JSONMemuat turun keseluruhan spesifikasi sebagai satu fail untuk alat anda sendiri.
  • ID Ejen / APIID dan slug organisasi anda, mod API (Sandbox atau Live) dan ID ejen AI yang anda pilih, masing-masing dengan butang Salin.
  • WebhookTitik akhir anda, acara yang diterima setiap satu, status HTTP terakhir dan sebarang penghantaran yang gagal.

Baca bahagian tentang had kadar dan webhook keluar sebelum anda melancarkan, bukan selepas. Ia menerangkan tingkah laku yang mudah terlepas pandang dalam ujian pantas.

Kunci API dan skop

Setiap permintaan membawa kunci dalam pengepala Authorization sebagai token bearer. Kunci tidak dicipta dalam aplikasi: pengendali ruang kerja anda mengeluarkannya dan memberitahu skop yang dibawanya. Kunci penuh dipaparkan sekali pada saat ia dikeluarkan, dan selepas itu hanya aksara pertamanya kelihatan, jadi simpan dalam stor rahsia anda sendiri dengan segera.

SkopApa yang dibenarkan
readMembaca kenalan, panggilan, baris gilir, ahli pasukan, laporan dan senarai jangan hubungi.
writeMencipta dan mengemas kini kenalan, merekod hasil panggilan, menambah nombor ke senarai jangan hubungi.
callsMembuat dan menamatkan panggilan.
adminMengurus webhook; juga boleh memanggil setiap titik akhir lain.

Minta set terkecil yang mencukupi untuk tugas itu. Skrip laporan hanya memerlukan read; butang klik-untuk-panggil memerlukan calls. Jika permintaan mengembalikan 403 dengan kod insufficient_scope, kunci itu tidak mempunyai skop yang tertera pada kad titik akhir tersebut.

Sandbox dan live

Kunci boleh dikeluarkan untuk sandbox, yang menggunakan simulator dan tidak membuat panggilan sebenar, atau untuk penggunaan live. Anggap awalan kunci sebagai label sahaja: kunci berlabel ujian berfungsi pada data dan sambungan telefon yang sama dengan kunci live, jadi jangan bergantung pada awalan untuk menjauhkan eksperimen daripada pelanggan sebenar. Gunakan mod API yang dipaparkan di halaman Pembangun untuk mengetahui kedudukan anda.

Membuat panggilan melalui API

Titik akhir awam meliputi perkara asas: semakan kesihatan, menyenaraikan panggilan, membaca satu panggilan, membuat panggilan, meletak panggilan, mengurus webhook dan bersembang dengan ejen AI. Panggilan keluar yang dibuat melalui API melalui semakan pematuhan yang sama seperti panggilan dari meja, jadi nombor dalam senarai jangan hubungi atau di luar waktu panggilan yang dibenarkan akan ditolak, sama seperti bagi ejen. Bina kod anda untuk mengendalikan penolakan itu sebagai hasil biasa, bukan pepijat.

Ini penting untuk reka bentuk. Jangan tulis gelung yang mencuba semula panggilan yang ditolak sehingga ia berjaya. Baca sebabnya, log, dan teruskan. Untuk peraturan di sebalik penolakan itu, lihat Kawalan Waktu Panggilan dalam Call dan Senarai Jangan Hubungi dalam Call.

Had kadar dan ralat

Setiap kunci mempunyai had permintaan seminitnya sendiri, ditetapkan semasa kunci dikeluarkan; lalainya ialah 120. Apabila kunci menghabiskan had seminit itu, API menjawab 429 dengan kod rate_limited dan memberitahu berapa lama perlu menunggu dalam pengepala X-RateLimit-Reset. Tunggu selama itu, kemudian teruskan. Klien yang sopan memperlahankan dirinya sebelum mencapai had.

Mengendalikan permintaan yang gagal

  1. Baca statusAdakah ia ralat klien yang boleh anda betulkan, atau ralat pelayan yang berbaloi dicuba semula?
  2. Baca kodBercabang berdasarkan kod, jangan sekali-kali berdasarkan teks mesej.
  3. BerundurUntuk 429, tunggu pengepala reset; untuk ralat pelayan, cuba semula beberapa kali dengan selang yang semakin panjang.
  4. Log butirannyaSimpan titik akhir, kod dan masa supaya pasukan sokongan boleh mengesannya.
  5. Berhenti pada penolakanPenolakan pematuhan ialah keputusan, bukan gangguan; jangan buat gelung padanya.

Webhook: menerima acara

Daripada bertanya kepada API berulang kali sama ada sesuatu telah berlaku, biarkan Call memberitahu anda. Di halaman Pembangun, tekan Tambah titik akhir, masukkan alamat https awam, dan tandakan acara yang anda mahu; tidak menanda apa-apa bermakna semua acara. Rahsia tandatangan dipaparkan sekali, semasa titik akhir ditambah. Salin pada ketika itu. Jika ia hilang, padam titik akhir dan tambah semula untuk mendapatkan rahsia baharu.

Setiap penghantaran ditandatangani. Pengepala tandatangan mengandungi HMAC-SHA256 bagi cap masa dan badan yang dicantumkan dengan noktah, dikira menggunakan rahsia tandatangan anda, dan pengepala berasingan membawa cap masa. Kira semula di pihak anda dan bandingkan sebelum mempercayai muatannya. Rujukan API menyertakan contoh kod untuk ini dalam Node.js dan Python, dan menolak cap masa lama melindungi anda daripada permintaan yang dimainkan semula.

Penerima webhook yang baik dan lemah

BaikLemah
TandatanganDisahkan pada setiap permintaanDipercayai tanpa semakan
Balasan2xx dalam beberapa saat, kerja dibaris gilirkan untuk kemudianPemprosesan perlahan sebelum membalas
PenduaSelamat menerima acara yang sama dua kaliMencipta dua rekod
KegagalanMemberi amaran apabila penghantaran gagalSenyap sehingga seseorang perasan

Titik akhir anda mesti menjawab dengan status 2xx dalam masa 10 saat. Penghantaran yang gagal dicuba semula, sehingga enam percubaan kesemuanya, dan titik akhir yang gagal 50 kali berturut-turut akan dimatikan. Setiap baris di halaman Pembangun memaparkan status HTTP terakhir dan bilangan penghantaran yang gagal, dan Hantar ujian menghantar satu acara ujian bertandatangan supaya anda boleh melihat jawapan pelayan anda.

Senarai semak sebelum pelancaran

Sebelum anda menghidupkan integrasi

  • Anda tahu skop yang dimiliki kunci, dan ia tidak lebih daripada yang diperlukan
  • Kunci disimpan dalam stor rahsia, bukan dalam kod sumber
  • Tandatangan webhook disahkan dan cap masa lama ditolak
  • Penerima menjawab dengan pantas dan mengendalikan acara pendua
  • Respons had kadar dan penolakan dikendalikan tanpa gelung cuba semula yang ketat
  • Anda telah menguji dalam mod sandbox dan menekan Hantar ujian pada titik akhir
  • Seseorang dinamakan untuk menerima amaran jika penghantaran mula gagal

Melakukannya dalam Call

Dalam Call, buka Tetapan, kemudian Rujukan API untuk mengkaji titik akhir, dan Tetapan, kemudian Pembangun untuk menyalin ID organisasi, menyemak kunci dan menambah webhook. Pemilik, pentadbir dan pengurus boleh menambah, menguji dan memadam titik akhir; orang lain hanya melihat senarai. Jika anda juga menggunakan ciri ejen AI, ID ejen pada halaman yang sama digunakan untuk titik akhir sembang. Untuk bahagian suara produk ini, lihat Menyediakan Ejen AI dalam Call.

Soalan lazim

Bagaimana saya mendapatkan kunci API?

Kunci dikeluarkan oleh pengendali ruang kerja anda; ia tidak boleh dicipta dalam aplikasi. Minta satu dan nyatakan skop yang diperlukan. Kunci penuh dipaparkan sekali semasa ia dikeluarkan.

Apa maksud respons 429?

Kunci telah menghabiskan permintaannya bagi minit semasa. Tunggu selama bilangan saat dalam pengepala X-RateLimit-Reset, kemudian cuba lagi, dan agihkan kerja pukal dalam tempoh yang lebih panjang.

Bagaimana saya menyemak bahawa webhook benar-benar datang daripada Call?

Kira HMAC-SHA256 bagi cap masa dan badan dengan rahsia tandatangan anda dan bandingkan dengan pengepala tandatangan. Rujukan API menunjukkan contoh dalam Node.js dan Python.

Bolehkah saya menghantar webhook ke pelayan pembangunan setempat?

Tidak secara terus. Titik akhir mesti alamat https awam, jadi gunakan alat terowong yang mendedahkan pelayan setempat anda pada alamat sedemikian.

Mengapa panggilan API saya untuk membuat panggilan ditolak?

Panggilan yang dibuat melalui API melalui semakan pematuhan yang sama seperti panggilan dari meja. Nombor dalam senarai jangan hubungi atau di luar waktu panggilan akan ditolak.

Siapa yang boleh melihat dan mengubah webhook?

Semua orang boleh membaca senarai, tetapi hanya pemilik, pentadbir dan pengurus boleh menambah, menguji atau memadam titik akhir.

Buka rujukan API Call dan tambah titik akhir webhook

Dalam konsol demo, anda boleh mencuba panggilan masuk secara simulasi.

Panduan berkaitan