Giden aramalar yapın (API)

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

Tüm bir listeyi mi arıyorsunuz? Kontrol panelindeki Kampanyalar özelliği (/dashboard/campaigns), kişi listesini içeren bir CSV dosyasını alır ve saat dilimine duyarlı arama zamanlarını, eşzamanlılığı ve yeniden deneme politikasını sizin için yönetir. Bu rehber, tekil programatik aramaları kapsar.

Ön koşullar

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.

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).

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" }

status: "initiated", yalnızca isteğin kabul edildiği anlamına gelir — arama henüz bağlanmadı. Canlı durum için GET /v1/calls/{call_id} çağrısını sorgulayın (in_progress → completed / failed).

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ı

Hata	Çözüm
`402 Payment Required`	Bakiye yükleyin veya otomatik bakiye yüklemeyi etkinleştirin
`403` giden arama engellendi (demo numarası)	Bunun yerine bir VoIP numarası sağlayın
`403` giden arama engellendi (doğrulanmamış VoIP)	`POST /v1/phone-numbers/{id}/verify-voip` çağrısını çalıştırın
`404 from_number is not registered to this organization`	`from_number` değerinin size ait bir telefon numarasıyla eşleştiğini doğrulayın
`502 Bad Gateway`	Geçici SIP / LiveKit hatası; yeniden denemek güvenlidir

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

Giden aramalar referansı

Tüm istek alanları ve hata kodları.

call.complete alma

Tamamlanan giden aramaları sisteminize aktarın.

Faturalandırma

Giden aramaların bakiye nedeniyle başarısız olmaması için otomatik yükleme.

Giden ajanları test etme

Giden ajanınızı üretime almadan önce deneme çalıştırması yapın.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Giden aramalar yapın (API)

Ön koşullar

Kaydedilmiş bir ajanla arama yapın

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

Aramayı takip edin

Ele alınması gereken hata durumları

Bekletme süresini kontrol etme

Sonraki adımlar

Giden aramalar referansı

call.complete alma

Faturalandırma

Giden ajanları test etme

​Ön koşullar

​Kaydedilmiş bir ajanla arama yapın

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

​Aramayı takip edin

​Ele alınması gereken hata durumları

​Bekletme süresini kontrol etme

​Sonraki adımlar

Giden aramalar referansı

call.complete alma

Faturalandırma

Giden ajanları test etme

Ön koşullar

Kaydedilmiş bir ajanla arama yapın

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

Aramayı takip edin

Ele alınması gereken hata durumları

Bekletme süresini kontrol etme

Sonraki adımlar