Sesli Asistan
Çağrı Başlat

Çağrı Başlat

POST/api/app/voice-agent/start-call
Sesli asistan çağrısı başlatır. Token sahibinin tenant'ına ait bir voice agent oturumu açar ve aramayı başlatır.

Request Body

{
  "assistantId": "1a96b945-d104-4b64-b96e-3153d8f54c85",
  "customerNumbers": ["+905xxxxxxxxx"],
  "metadata": {
    "ref_id": "q_6876"
  }
}

Parametreler

AlanTipZorunluAçıklama
assistantIdstring (GUID)EvetKullanılacak voice agent asistanının ID'si. Asistanın tipi ("İş Akışı Asistanı" veya "Hazır Asistan") bu ID üzerinden sunucu tarafında çözülür; istekte ayrıca belirtilmez.
customerNumberstringHayırGeriye dönük uyumluluk içindir. Tekil müşteri numarası. Yeni entegrasyonlarda customerNumbers kullanılmalıdır.
customerNumbersarrayHayırAranacak müşteri numaraları listesi. customerNumber ile birleştirilir; boş değerler elenir, tekrarlar kaldırılır. En az bir numara (customerNumber veya customerNumbers üzerinden) zorunludur, toplamda en fazla 100 numara gönderilebilir.
metadataobject (string → string)HayırSerbest key-value veriler (yalnızca string değerler). Sağlayıcıya olduğu gibi iletilir ve çağrı tamamlandığında Webhook payload'ının metadata alanında aynen geri döner. Örn: ref_id.

assistantType alanı artık istekte gönderilmez — asistanın tipi assistantId üzerinden sunucu tarafında otomatik çözülür. İki asistan tipi vardır: İş Akışı Asistanı ve Hazır Asistan.

⚠️

Yalnızca Hazır Asistan + tek müşteri numarası kombinasyonu senkron çalışır: sağlayıcıya senkron istek atılır ve yanıt data.call_id içinde döner. Diğer tüm durumlar — İş Akışı Asistanı (tek veya çoklu numara) ya da Hazır Asistan + birden fazla numara — asenkron dispatch edilir: yanıt hemen döner, aramalar arka planda başlatılır ve sonuç, çağrı analizi tamamlandığında Webhook ile bildirilir.

  • İş Akışı Asistanı + tek numara: iş listesi (work list) oluşturulmadan doğrudan dispatch edilir, yanıt data: null döner.
  • İş Akışı Asistanı + çoklu numara veya Hazır Asistan + çoklu numara: bir iş listesi (work list) oluşturulur ve tenant eşzamanlılık limitine göre sırayla aranır, yanıt data.workListId döner.

Responses

200Başarılı — Hazır Asistan, tek numara (senkron)
{
  "success": true,
  "message": null,
  "data": {
    "success": true,
    "message": null,
    "call_id": "019e925a-5f79-7778-b0be-a45a146cf828"
  }
}
200Başarılı — İş Akışı Asistanı, tek numara (asenkron, fire-and-forget)
{
    "success": true,
    "message": null,
    "data": null
}
200Başarılı — çoklu numara (asenkron, iş listesi)
{
    "success": true,
    "message": null,
    "data": {
      "workListId": "6f1a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8"
    }
}

Asenkron akışlarda ( data: null veya data.workListId dönen tüm durumlar) sağlayıcının ürettiği call_id yanıtta bulunmaz; çağrı sonucu ve gönderdiğiniz metadata, analiz tamamlandığında Webhook payload'ı ile iletilir.

403Validasyon veya iş kuralı hatası
{
  "error": {
    "code": null,
    "message": "At least one CustomerNumber is required.",
    "details": null,
    "validationErrors": null
  }
}
MesajAçıklama
AssistantId is required.assistantId gönderilmedi.
AssistantId is invalid.assistantId geçerli bir GUID değil.
Asistan bulunamadı.assistantId geçerli bir GUID ama sistemde eşleşen bir asistan yok.
At least one CustomerNumber is required.customerNumber/customerNumbers üzerinden geçerli hiçbir numara bulunamadı.
CustomerNumbers cannot exceed 100.Toplam numara sayısı 100'ü aşıyor.
Geçerli en az bir telefon numarası gereklidir.Normalize edildikten sonra geçerli numara kalmadı.
Arama başlatılamadı.İş listesi (work list) dispatch işlemi başarısız oldu (çoklu numaralı çağrı).
⚠️

Hata durumunda HTTP status 403 döner ve gövde standart ABP hata formatındadır. Detaylar için Hata Kodları sayfasına bakınız.

Çağrı KayıtlarıÇağrı Kayıtları