Developer cookbook

Giden aramalar yapın (API)

Kendi kodunuzdan yapay zeka destekli bir giden aramayı tetikleyin — anket, takip veya onay akışları için.

Giden arama, ThunderPhone'a bir hedef numara ve ajan yapılandırması vermenizi ve yapay zeka ajanının sizin adınıza arama yapmasını sağlar. Yaygın kullanım alanları:

• Randevu onayları
• Anket geri aramaları
• Cevapsız aramadan sonra "ikinci deneme" takipleri
• Sevkiyat tarzı bildirimler

Ön koşullar#

1. Bir VoIP numarası sağlayın

   Giden aramalar için from_number numarasının size ait olması ve bunun bir VoIP bağlantısı üzerinden sağlanması gerekir. Demo numaralar yalnızca gelen aramalar içindir. Bkz. Kendi numaralarınızı getirin.

2. Bir ajan oluşturun

   Giden aramalara yönelik bir istem genellikle ajanın kendini ve amacını tanıtmasıyla başlar — "Merhaba, Acme'den arıyorum; yarın saat 15.00'teki randevunuzu onaylamak için aradım…" outbound_speak_order değerini agent_first olarak ayarlayın (varsayılan değer budur).

3. Pozitif bakiye bulundurun

   Bakiye ≤ $0.00 olduğunda giden aramalar 402 Payment Required döndürür. Bakiye yüklemek için POST /v1/billing/top-up kullanın veya otomatik bakiye yüklemeyi etkinleştirin.

Kaydedilmiş bir ajanla arama yapın#

En basit yöntem — bir ajana kimliğiyle başvurun:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

Yanıt:

{ "call_id": 987654321, "status": "initiated" }

Satır içi yapılandırmayla arama yapın#

Ajan olarak kaydetmeye değmeyecek tek seferlik bir istem istiyorsanız, bunun yerine config iletin. Yapı, şu uç noktanın yanıt şemasıyla eşleşir: call.incoming webhook:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Aramayı takip edin#

Paralel olarak telephony.complete webhook olayına abone olun — bir aramanın bittiğini öğrenmenin en hızlı yolu budur. Gelen webhook'ları kabul edemiyorsanız GET /v1/calls/{call_id} çağrısını birkaç saniyede bir sorgulayın; arama sona erdiğinde kayıt end_reason, duration_seconds ve kayıt URL'sini içerir.

Ele alınması gereken hata durumları#

Bekletme süresini kontrol etme#

Aranan kişinin yanıt vermekte yavaş kalması nedeniyle uzayan giden aramalar (IVR menüleri, kuyruklar) max_hold_seconds ile sınırlandırılabilir:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Son N saniye içinde insan sesi alınmadığında ajan aramayı sonlandırır. Varsayılan değer 900'dür (15 dakika).

Sonraki adımlar#