Anlık Kampanyaları API ile Tetikleme

Anlık bir kampanya, sizin belirttiğiniz kişileri, sizin belirttiğiniz anda arar. Bir form, bir CRM ya da başka bir sistem SESTEK AgenticCX dış API'sine arama isteği gönderir, kişi kampanyaya katılır ve kampanyanın yapay zeka ajanı onu arar. Tipik örnekler: "müşteri formu az önce doldurdu, hemen arayın" ya da "sipariş iptal edildi, bilgilendirme araması yapın".

Bu makale, Anlık bir kampanyanın API ile baştan sona nasıl tetikleneceğini anlatır: nelere ihtiyacınız olduğunu, nasıl belirteç (token) alacağınızı, isteklerin nasıl gönderileceğini, yanıtların nasıl okunacağını ve her aramanın sonradan nasıl izleneceğini. Kampanyanın kendisini oluşturmak için Kampanya Oluşturma ve Düzenleme ve Yapay Zeka Ajanı Kampanyaları ve Anlık Tetikleme makalelerine bakın.

Başlamadan önce

Bir client yalnızca tek bir kiracıya aittir ve yalnızca o kiracının kampanyalarını görür. İsteklerde kiracı bilgisi göndermezsiniz: kiracı belirteçten okunur.

Kampanya adının yanındaki Kampanya Kimliği, entegrasyonunuzun kullanacağı numaradır. Kampanyayı yeniden adlandırsanız bile değişmez, bu yüzden adı değil kimliği saklayın. Bir entegrasyonun hâlâ kullandığı Anlık kampanyayı tamamlamayın: tamamlama geri alınamaz ve kimlik çalışmaz hale gelir. Ara vermek için Duraklat'ı kullanın.

cURL komutlarını ekrandan alın

İstekleri sıfırdan yazmak zorunda değilsiniz. Kampanya Kimliği'nin yanındaki </> simgesini seçerek cURL olarak kopyala (ext-api) penceresini açın. Pencere beş kampanya ucunu listeler. Birini seçtiğinizde Kampanya Kimliğiniz yerleştirilmiş cURL komutu panonuza kopyalanır. Erişim belirteci her zaman bir yer tutucudur (<YOUR_ACCESS_TOKEN>): gerçek bir belirteç hiçbir zaman gösterilmez ya da kopyalanmaz. Komutu çalıştırmadan önce açılı parantez içindeki tüm yer tutucuları değiştirin.

Adım 1: Erişim belirteci alın

API, OAuth client credentials akışını kullanır.

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

grant_type=client_credentials
&client_id=<YOUR_CLIENT_ID>
&client_secret=<YOUR_CLIENT_SECRET>
&scope=AgenticCXExternal

Dönen belirteci her istekte Authorization: Bearer <YOUR_ACCESS_TOKEN> olarak gönderin ve süresi dolana kadar yeniden kullanın.

scope parametresi zorunludur. Verilmezse belirteç hedef kitle (audience) olmadan üretilir, belirteç isteği başarılı görünür ve sonraki her API çağrısı 401 ve The audience 'empty' is invalid mesajıyla başarısız olur.

Adım 2: Arama istekleri gönderin

POST /ext-api/v1/campaign/96/call-requests
Authorization: Bearer <YOUR_ACCESS_TOKEN>
Content-Type: application/json

{
  "items": [
    {
      "clientReferenceId": "ORDER-2026-0001",
      "contact": {
        "phoneNumber": "+905770000123",
        "name": "Elif Yıldız",
        "email": "elif.yildiz@example.com"
      },
      "locale": "tr-TR",
      "parameters": [
        { "key": "orderId", "value": "A-1001" },
        { "key": "amount", "value": "249.90" }
      ]
    }
  ]
}

Her öğe aranacak bir kişidir.

parameters, yapay zeka ajanına aramanın bağlamını verir, örneğin bir sipariş numarası ya da randevu tarihi. İki sınır birlikte geçerlidir: 512 karakterlik değerlere sahip yirmi çift 4.000 baytı aşar ve isteğin tamamı 400 ile reddedilir.

Adım 3: Yanıtı okuyun

İstek geçerliyse yanıt her zaman 200 olur ve her öğe kendi sonucunu, gönderdiğiniz sırayla taşır. Sonuçları kayıtlarınızla clientReferenceId üzerinden eşleştirin. Reddedilen bir öğe diğerlerini etkilemez.

{
  "campaignId": 96,
  "groupId": "2f6a8e10-9b4c-4a3d-8e21-0a5b7c9d1e2f",
  "acceptedCount": 1,
  "rejectedCount": 0,
  "results": [
    {
      "id": "8f14e45f-ea8d-4b41-9a2c-7c2b0e1d5a63",
      "clientReferenceId": "ORDER-2026-0001",
      "accepted": true,
      "status": "Queued",
      "nextEligibleAtUtc": null,
      "mergedIntoId": null,
      "rejectionReason": null
    }
  ]
}

Bir isteğin kabul edilmesi tek başına aramayı başlatmaz. Kampanya motoru isteği, kampanyanın çağrı penceresine, maksimum deneme sayısına ve çağrılar arası bekleme süresine göre yürütür.

Referans kimlikleri ve yeniden denemeler

clientReferenceId sizin tekrar güvenliği (idempotency) anahtarınızdır. Aynı anahtarı yeniden göndermek hiçbir zaman ikinci bir arama oluşturmaz: aynı durumla ilk sonucu geri alırsınız. Bu sayede bağlantı koptuktan sonra tüm gövdeyi, ek bir uzlaştırma yapmadan güvenle yeniden gönderebilirsiniz.

• Anahtar büyük/küçük harfe duyarlıdır. ORDER-1 ve order-1 iki ayrı anahtardır ve iki arama yapılır. Anahtarları tek bir tutarlı biçimde üretin.
• /, \, %, ? veya # içeremez, kontrol karakteri içeremez, yalnızca . ya da .. olamaz. Boşluklar ve İngilizce olmayan harfler dahil geri kalan her şeye izin verilir.
• Anahtarı bir adrese koyarken yüzde işaretiyle kodlayın (percent-encode).
• Güvence, isteğin saklandığı süre boyunca geçerlidir. Tamamlanmış istekler bir saklama süresinden sonra silinir, bu süre varsayılan olarak 90 gündür. Sonrasında aynı anahtar yeni bir iş sayılır ve yeni bir arama yapabilir. Anahtarları yeniden kullanan bir sistemin, örneğin her yıl tekrarlanan sipariş numaralarının, bunu hesaba katması gerekir.
• Tekrarlanan isteği yalnızca bir hatadan kurtulmak için kullanın. Bir aramanın durumunu denetlemek için asla kullanmayın: her tekrar bir kayıt yazar. Bunun yerine aşağıdaki izleme uçlarını kullanın.

Tüm istek reddedildiğinde

API, hiçbir öğeyi okumadan önce kampanyayı denetler. Kampanya istek kabul edemiyorsa gövdenin tamamı 422 ile reddedilir.

422 sonrasında asla yeni bir clientReferenceId ile yeniden denemeyin. Aynı kişi için iki arama yapılabilecek tek durum budur. Kampanya çalışmaya başladıktan sonra aynı gövdeyi aynı anahtarlarla yeniden gönderin. Duraklatılmış bir kampanya, yalnızca daha önce kabul ettiği anahtarlardan oluşan bir gövdeyi yine yanıtlar, bu yüzden bağlantı koptuktan sonra tekrar göndermek güvenli kalır.

Adım 4: Bir aramayı izleyin

Bir isteğe ne olduğunu görmek için onu referans kimliğiyle sorgulayın.

GET /ext-api/v1/campaign/96/call-requests/ORDER-2026-0001
Authorization: Bearer <YOUR_ACCESS_TOKEN>

Yanıt dört bloktan oluşur.

Deneme outcome değeri Answered, NoAnswer, Failed, Cancelled, Dialing, Scheduled veya Unknown değerlerinden biridir. Başarısız bir deneme için errorCode nedeni verir: telefon sisteminin bildirdiği bir kapanma nedeni, örneğin NO_ANSWER veya USER_BUSY, ya da arama hiç yapılamadığında NoActiveOutboundNumber gibi bir yapılandırma nedeni. Yeni neden kodları ortaya çıkabilir, bu yüzden kesin değerlere göre dallanmayın. Bilinmeyen bir kodu başarısız deneme sayın ve metnini günlüğe yazın.

Merged bir isteğin call bloğu boştur, çünkü kendi başına bir arama oluşturmamıştır. Aramayı görmek için mergedIntoId içindeki isteği sorgulayın.

İstekleri listeleyin ve sayın

Çok sayıda isteği izlerken iki uç daha işinize yarar.

İkisi de şu filtreleri kabul eder.

Liste ayrıca arama durumuna göre süzmek için callState, maxResultCount (1 ile 500, varsayılan 50) ve sayfalama için cursor alır. Bir sayfanın nextCursor değerini bir sonrakinin cursor değeri olarak verin ve bunu opak bir değer sayın. nextCursor değerinin null olması son sayfa demektir. Özet; totalCount, acceptedCount, her durumun ve her arama durumunun sayısını ve iki toplamı döndürür: pendingCount (başlamamış, zamanlanmış veya aranıyor) ve finishedCount (tamamlanmış, başarısız veya iptal edilmiş).

Tipik bir entegrasyon

1. Bir belirteç alın ve süresi dolana kadar yeniden kullanın.
2. Kampanya detay sayfasındaki Kampanya Kimliğini yapılandırmanıza kopyalayın.
3. Olay gerçekleştiğinde en fazla 100 kişilik bir POST gönderin.
4. Her sonucu saklayın: id, status ve groupId.
5. Bağlantı koptuktan sonra aynı gövdeyi yeniden gönderin.
6. Tek bir kişiyi izlemek için isteği clientReferenceId ile okuyun. Bir toplu gönderimi izlemek için groupId ile call-requests-summary kullanın.

Bilmekte fayda var

• API'deki tüm zamanlar UTC'dir (Utc ile biten alanlar). Hiçbir değer kiracı saat dilimine çevrilmez.
• Merged bir istek parameters ve locale değerlerini kayıtta tutar, ancak yapay zeka ajanı katıldığı isteğin bağlamını kullanır. Aynı kişiye farklı bir bağlam vermek için ilk arama bitene kadar bekleyin, sonra yeni bir anahtar gönderin.
• Kişi telefon numarasına göre eşleştirilir. Bu numarada bir kişi zaten varsa o kullanılır ve gönderdiğiniz ad ile e-posta ona yazılmaz. Yalnızca yeni bir kişi oluşturulurken kullanılırlar. Mevcut bir kişiyi değiştirmek için Kişiler ekranlarını kullanın.
• Kabul edilmiş bir istek hiçbir zaman iptal edilmez ve süresi dolmaz: arama kendi penceresini bekler, deneme sınırında durur ve kampanya duraklatıldığında bekler.
• Aynı kişinin ne sıklıkla tetiklenebileceğine dair kişi başına bir sınır yoktur. Her seferinde yeni bir clientReferenceId gönderirseniz aynı numara kısa aralıklarla yeniden aranabilir, kampanyanın Çağrılar Arası Bekleme ayarı uygulanmaz ve deneme sayacı her yeni istekle yeniden başlar. Bu konuda uyum sorumlularıyla bir kural belirleyin.
• Bu makale kampanya uçlarını anlatır. Her alanı içeren tam sözleşme, Teknik Belgeler altındaki External API makalesindedir.