Geliştiriciler İçin Call API ve Webhook'lar: Anahtar, Kapsam, Olay
Call REST API'sine pratik bakış: API anahtarları ve kapsamlar, hız sınırları, hata yönetimi, imzalı webhook'lar ve uç noktaları yönettiğiniz Geliştiriciler sayfası.
Er ya da geç bir telefon sistemi başka bir şeyle konuşmak zorunda kalır: bir arama biter bitmez onu göstermesi gereken bir CRM, kimin aradığını bilmek isteyen bir faturalama aracı, bir form gönderildiğinde arama başlatan bir betik. Call'un tam da bunun için bir REST API'si ve giden webhook'ları vardır. Bu rehber parçaların nasıl bir araya geldiğini, kod yazmadan önce neler istemeniz gerektiğini ve bir geliştiriciye en sık bir öğleden sonraya mal olan hataları açıklıyor.

Amacınız yalnızca kişileri toplu olarak taşımaksa önce Telefon Ekibi CRM'ine Kişi İçe Aktarma yazısını okuyun; içe aktarma çoğu zaman bir entegrasyondan daha kolaydır.
Nereden başlamalı: başvuru ve Geliştiriciler sayfası
Bilmeniz gereken iki yer var. API başvurusu Ayarlar altında ve ana sayfanın Kaynaklar menüsünde bulunur. Giriş yapmadan okunabilir; bu, bir müşteri için işin kapsamını belirlerken kullanışlıdır. Yine Ayarlar altındaki Geliştiriciler sayfası ise kendi çalışma alanınız içindir: kuruluş ve temsilci kimliklerinizi, webhook uç noktalarınızı ve anahtarlarınızın salt okunur bir listesini gösterir.
Her yerin size sundukları
- Buradan başlayınTemel URL ve kurallar, kapsam tablosuyla kimlik doğrulama ve durum kodlarıyla hatalar.
- Uç noktalarHer uç nokta kartı kapsamını, parametrelerini, istek gövdesini, yanıtını ve hatalarını; curl, JavaScript ve Python'da kopyalanmaya hazır isteklerle listeler.
- AramaUç nokta aramasına atlamak için / tuşuna basın ve yönteme, yola, kapsama veya özete göre filtreleyin.
- OpenAPI JSONKendi araçlarınız için tüm spesifikasyonu tek bir dosya olarak indirir.
- Agent ID / APIKuruluş kimliğiniz ve kısa adınız, API modu (Sandbox veya Live) ve seçtiğiniz yapay zekâ temsilcisinin kimliği; her biri bir Kopyala düğmesiyle.
- Webhook'larUç noktalarınız, her birinin aldığı olaylar, son HTTP durumu ve başarısız teslimatlar.
Hız sınırları ve giden webhook'larla ilgili bölümleri canlıya geçtikten sonra değil, önce okuyun. Hızlı bir testte gözden kaçması kolay davranışları anlatırlar.
API anahtarları ve kapsamlar
Her istek, Authorization başlığında bearer token olarak bir anahtar taşır. Anahtarlar uygulamada oluşturulmaz: çalışma alanınızın operatörü bunları verir ve hangi kapsamları taşıdıklarını size söyler. Anahtarın tamamı verildiği anda bir kez gösterilir, sonrasında yalnızca ilk karakterleri görünür; bu yüzden onu hemen kendi gizli bilgi deponuzda saklayın.
| Kapsam | Neye izin verir |
|---|---|
| read | Kişileri, aramaları, kuyrukları, ekip üyelerini, raporları ve aranmayacaklar listesini okumak. |
| write | Kişi oluşturmak ve güncellemek, arama sonuçlarını kaydetmek, aranmayacaklar listesine numara eklemek. |
| calls | Arama başlatmak ve sonlandırmak. |
| admin | Webhook'ları yönetmek; diğer tüm uç noktaları da çağırabilir. |
İşi gören en küçük seti isteyin. Bir raporlama betiğinin yalnızca read'e ihtiyacı vardır; tıkla-ara düğmesinin calls'a ihtiyacı vardır. Bir istek insufficient_scope koduyla 403 döndürürse anahtarda o uç noktanın kartında gösterilen kapsam eksiktir.
Sandbox ve canlı
Anahtarlar, simülatör kullanan ve gerçek arama yapmayan bir sandbox için veya canlı kullanım için verilebilir. Bir anahtarın önekini yalnızca bir etiket olarak görün: test etiketli bir anahtar canlı anahtarla aynı veriler ve aynı telefon bağlantısı üzerinde çalışır; bu yüzden deneyleri gerçek müşterilerden uzak tutmak için öneke güvenmeyin. Nerede durduğunuzu bilmek için Geliştiriciler sayfasında gösterilen API modunu kullanın.
API üzerinden arama başlatmak
Herkese açık uç noktalar temelleri kapsar: durum kontrolü, aramaları listeleme, tek bir aramayı okuma, arama başlatma, kapatma, webhook'ları yönetme ve bir yapay zekâ temsilcisiyle sohbet. API üzerinden başlatılan giden bir arama, masadan başlatılan bir aramayla aynı uyumluluk kontrolünden geçer; dolayısıyla aranmayacaklar listesindeki veya izin verilen arama saatleri dışındaki bir numara, tıpkı bir temsilci için olacağı gibi reddedilir. Kodunuzu bu reddi bir hata olarak değil, normal bir sonuç olarak ele alacak şekilde yazın.
Bu tasarım açısından önemlidir. Reddedilen bir aramayı başarılı olana kadar yeniden deneyen bir döngü yazmayın. Nedeni okuyun, kaydedin ve devam edin. Bu retlerin arkasındaki kurallar için Call'da Arama Saatleri Koruması ve Call'da Aranmayacaklar Listesi yazılarına bakın.
Hız sınırları ve hatalar
Her anahtarın, anahtar verilirken belirlenen kendi dakika başına istek sınırı vardır; varsayılan 120'dir. Bir anahtar o dakikanın hakkını doldurduğunda API rate_limited koduyla 429 yanıtı verir ve X-RateLimit-Reset başlığında ne kadar beklemeniz gerektiğini söyler. O kadar bekleyin, sonra devam edin. Nazik bir istemci duvara çarpmadan önce kendini yavaşlatır.
- 429 rate_limited: sıfırlama başlığındaki süre kadar geri çekilin ve toplu işleri zamana yayın.
- 403 insufficient_scope: anahtarda o uç noktanın kartındaki kapsam eksiktir; bu kapsama sahip bir anahtar isteyin.
- Diğer hatalar: mesaja değil, hata koduna göre hareket edin. Kodlar değişmez; ifadeler değişebilir.
Başarısız bir isteği ele almak
- Durumu okuyunDüzeltebileceğiniz bir istemci hatası mı, yoksa yeniden denemeye değer bir sunucu hatası mı?
- Kodu okuyunMesaj metnine göre değil, her zaman koda göre dallanın.
- Geri çekilin429 için sıfırlama başlığını bekleyin; sunucu hataları için artan gecikmelerle birkaç kez yeniden deneyin.
- Ayrıntıyı kaydedinDestek ekibi izini sürebilsin diye uç noktayı, kodu ve zamanı saklayın.
- Retlerde durunUyumluluk reddi bir aksaklık değil, bir karardır; üzerinde döngüye girmeyin.
Webhook'lar: olayları almak
API'ye bir şeyin olup olmadığını tekrar tekrar sormak yerine bunu Call'un size söylemesine izin verin. Geliştiriciler sayfasında Uç nokta ekle'ye basın, herkese açık bir https adresi girin ve istediğiniz olayları işaretleyin; hiçbirini işaretlememek tüm olaylar anlamına gelir. İmzalama sırrı, uç nokta eklendiğinde bir kez gösterilir. O anda kopyalayın. Kaybolursa yenisini almak için uç noktayı silip yeniden ekleyin.
Her teslimat imzalıdır. İmza başlığı, zaman damgası ile gövdenin bir noktayla birleştirilmesinin imzalama sırrınızla hesaplanmış HMAC-SHA256 değerini taşır; ayrı bir başlık da zaman damgasını taşır. Yükse güvenmeden önce bunu kendi tarafınızda yeniden hesaplayıp karşılaştırın. API başvurusu bunun için Node.js ve Python'da örnek kod içerir; eski zaman damgalarını reddetmek de sizi yeniden oynatılan isteklere karşı korur.
İyi ve zayıf bir webhook alıcısı
| İyi | Zayıf | |
|---|---|---|
| İmza | Her istekte doğrulanır | Kontrol edilmeden güvenilir |
| Yanıt | Saniyeler içinde 2xx, iş sonrası için kuyruğa alınır | Yanıt vermeden önce yavaş işleme |
| Mükerrer olaylar | Aynı olayı iki kez almak güvenlidir | İki kayıt oluşturur |
| Başarısızlıklar | Teslimatlar başarısız olduğunda uyarır | Biri fark edene kadar sessiz |
Uç noktanız 10 saniye içinde 2xx durum koduyla yanıt vermelidir. Başarısız bir teslimat toplam altı denemeye kadar yeniden denenir ve art arda 50 kez başarısız olan bir uç nokta kapatılır. Geliştiriciler sayfasındaki her satır son HTTP durumunu ve kaç teslimatın başarısız olduğunu gösterir; Test gönder ise sunucunuzun ne yanıt verdiğini görebilmeniz için imzalı bir test olayı gönderir.
Canlıya geçiş kontrol listesi
Bir entegrasyonu açmadan önce
- Anahtarın hangi kapsamlara sahip olduğunu biliyorsunuz ve gerekenden fazlası yok
- Anahtar kaynak kodda değil, bir gizli bilgi deposunda saklanıyor
- Webhook imzaları doğrulanıyor ve eski zaman damgaları reddediliyor
- Alıcı hızlı yanıt veriyor ve mükerrer olayları ele alıyor
- Hız sınırı ve ret yanıtları sıkı yeniden deneme döngüleri olmadan ele alınıyor
- Sandbox modunda test ettiniz ve uç noktada Test gönder'e bastınız
- Teslimatlar başarısız olmaya başlarsa uyarı alacak kişi belirlendi
Call'da yapmak
Call'da uç noktaları incelemek için Ayarlar'ı, ardından API başvurusu'nu; kuruluş kimliğinizi kopyalamak, anahtarlarınızı kontrol etmek ve bir webhook eklemek için Ayarlar'ı, ardından Geliştiriciler'i açın. Sahipler, yöneticiler ve müdürler uç nokta ekleyebilir, test edebilir ve silebilir; diğer herkes listeyi görür. Yapay zekâ temsilcisi özelliklerini de kullanıyorsanız aynı sayfadaki temsilci kimliği sohbet uç noktasında kullanılır. Ürünün ses tarafı için Call'da Yapay Zekâ Temsilcisi Kurma yazısına bakın.
Sık sorulan sorular
Bir API anahtarını nasıl alırım?
Anahtarları çalışma alanınızın operatörü verir; uygulamada oluşturulamazlar. Bir tane isteyin ve hangi kapsamlara ihtiyaç duyduğunu belirtin. Anahtarın tamamı verildiğinde bir kez gösterilir.
429 yanıtı ne anlama gelir?
Anahtar mevcut dakika için istek hakkını doldurmuştur. X-RateLimit-Reset başlığındaki saniye kadar bekleyin, sonra yeniden deneyin ve toplu işleri daha uzun bir süreye yayın.
Bir webhook'un gerçekten Call'dan geldiğini nasıl kontrol ederim?
Zaman damgası ve gövdenin imzalama sırrınızla HMAC-SHA256 değerini hesaplayın ve imza başlığıyla karşılaştırın. API başvurusu Node.js ve Python'da örnekler gösterir.
Webhook'ları yerel bir geliştirme sunucusuna gönderebilir miyim?
Doğrudan değil. Uç noktalar herkese açık https adresleri olmalıdır; bu yüzden yerel sunucunuzu böyle bir adreste yayınlayan bir tünel aracı kullanın.
API üzerinden arama başlatma isteğim neden reddedildi?
API üzerinden başlatılan aramalar, masadan yapılan aramalarla aynı uyumluluk kontrolünden geçer. Aranmayacaklar listesindeki veya arama saatleri dışındaki bir numara reddedilir.
Webhook'ları kim görebilir ve değiştirebilir?
Herkes listeyi okuyabilir, ancak uç nokta eklemeyi, test etmeyi veya silmeyi yalnızca sahipler, yöneticiler ve müdürler yapabilir.