External API

Anlık Tetikleme API'si, harici bir sistemin AgenticCX'ten, çalışan bir giden kampanya kapsamında belirli bir kişiyi şu anda aramasını istemesini sağlar. Planlı bir kampanyada kimin aranacağına segment karar verir; Anlık bir kampanyada ise kararı siz verirsiniz: gönderdiğiniz her istek, o kampanyanın arama havuzuna bir kişi ekler.

Ne Yapar

Bir isteği kabul etmek, aramayı başlatmak demek değildir. Uç nokta kişiyi kuyruğa alır ve Queued döndürür; aramanın kendisini kampanya motorunun kendi zamanlayıcısı, genellikle yaklaşık 15 saniye içinde yapar. Bu bilinçli bir tasarımdır: arama üretimi tek bir yerde kalır, böylece arama pencereleri, yeniden deneme sınırları ve eşzamanlılık sınırları, kişi havuza nasıl girmiş olursa olsun aynı şekilde uygulanır.

Tipik kullanım: olay odaklı senaryolar, örneğin "bir müşteri form doldurdu, hemen arayın" veya "bir sipariş iptal edildi, bilgilendirme araması yapın".

Adım adım bir anlatım için bkz. Anlık Kampanyaları API ile Tetikleme.

Kimlik Doğrulama

client_credentials OAuth akışı, audience AgenticCXExternal, rol Customer.

POST /connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=<istemci kimliğiniz>
&client_secret=<gizli anahtarınız>
&scope=AgenticCXExternal

Dönen belirteci her istekte Authorization: Bearer <token> olarak gönderin. scope parametresi zorunludur; atlanırsa belirteç audience olmadan verilir ve her çağrı 401 ile başarısız olur. Kiracınız belirteçten çözülür; gönderilecek bir kiracı başlığı veya sorgu parametresi yoktur.

Uç Noktalar

Temel yol: ext-api/v1

campaignId, kampanya detay ekranında Kampanya Kimliği olarak gösterilen numaradır. Kampanyanın adı değişse bile değişmez; entegrasyonu adı değil bu numarayı kullanarak yapın. O ekrandaki kopyala düğmesinin yanındaki </> düğmesi, bu uç noktaların hepsini çalıştırmaya hazır bir curl komutuyla listeleyen bir pencere açar (belirteç yer tutucu olarak görünür, gerçek bir kimlik bilgisi asla görünmez).

İstek Gönderme

POST campaign/{campaignId}/call-requests, bir items dizisi kabul eder (çağrı başına 1 ila 100 öğe). Her öğe için bir clientReferenceId (kendi anahtarınız, en fazla 128 karakter) ile contact.phoneNumber ve contact.name gerekir; contact.email, locale ve en fazla 20 parameters anahtar/değer çifti isteğe bağlıdır. Yanıt her zaman 200'dür. Öğeler birbirinden bağımsızdır ve her biri kendi sonucunu taşır: Queued (kabul edildi, arama geliyor), Deferred (kabul edildi ama arama penceresi dışında), Merged (bu kişi için zaten bir arama bekliyordu, iki istek birleştirildi) veya Rejected (bir nedenle birlikte).

clientReferenceId, sizin idempotency (tekrar güvenliği) anahtarınızdır. Aynı anahtarı iki kez göndermek hiçbir zaman ikinci bir arama üretmez; ilk isteğin sonucunu aynen geri alırsınız. Bu, bağlantı koptuktan sonra bir toplu isteği, kendiniz bir şey eşleştirmeden güvenle yeniden göndermenizi sağlar.

Takip ve Listeleme

GET call-requests/{clientReferenceId}, tek bir isteğin tüm resmini döndürür: ne gönderdiğinizi, AgenticCX'in ne karar verdiğini ve aramanın kendisinin ne yaptığını (durum, her deneme, sonucu). GET call-requests, bir kampanyanın istek geçmişini imleç (cursor) tabanlı sayfalamayla listeler; tarih aralığına veya arama durumuna göre filtrelenebilir. GET call-requests-summary aynı filtrelemeyi sayılar olarak döndürür; tek tek kayıtlar arasında gezmeden pano tarzı bir görünüm içindir.

Entegrasyondan Önce Okunması Gereken Davranışlar

Kampanya düzeyinde bir ret (kampanya bulunamadı, Anlık Tetikleme kampanyası değil, aktif değil veya tarih aralığı dışında), tek tek öğeler değerlendirilmeden önce, istek gövdesinin tamamı için 422 döndürür. Bir 422 hiçbir zaman yeni bir clientReferenceId ile yeniden denenmemelidir; mükerrer arama üretebilecek tek senaryo budur. Sorun (örneğin duraklatılmış bir kampanya) çözüldüğünde aynı anahtarla bir kez yeniden gönderin.