Giden aramalar yapın (API)

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

Giden arama, bir hedef numarayı ve ajan yapılandırmasını ThunderPhone'a iletmenizi 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
• Sevk tarzı bildirimler

Ön koşullar#

1. Giden aramalar için etkinleştirilmiş bir numara seçin

   Sahip olduğunuz bir numarayı VoIP bağlantısı aracılığıyla kullanın veya Telefon Numaraları sayfasından ThunderPhone numaralarınızı giden aramalarda kullanmak için izin isteyin. ThunderPhone numaraları başlangıçta yalnızca gelen aramalara açıktır. ThunderPhone her isteği manuel olarak inceler; onaylandıktan sonra bu numaralar onaylanan günlük sınıra kadar arama yapabilir (00:00 UTC'de sıfırlanır) ve kampanyalar yürütebilir; ayrıca daha yüksek bir limit talep edebilirsiniz. Müşteri VoIP numaralarında günlük limit yoktur; bu nedenle giden aramalar için bunları öneririz. Bkz. Kendi numaralarınızı getirin.

2. Bir ajan oluşturun

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

3. Bakiyenizi pozitif tutun

   Bakiye ≤ $0.00 olduğunda giden aramalar 402 Payment Required döndürür. Bakiyenize para yükleyin veya kontrol panelinde Kuruluş → Faturalandırma Ayarları bölümünden otomatik yüklemeyi etkinleştirin. sk_live_ anahtarınız bakiyeyi GET /v1/billing ile kontrol edebilir, ancak bakiye yükleyemez veya otomatik yüklemeyi değiştiremez.

Kaydedilmiş bir ajanla arama yapın#

En basit yol — 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":   "+14155552671",
    "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ı, call.incoming webhook'unun yanıt şemasıyla eşleşir:

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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Aramayı takip edin#

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

Ajanınız aramadan sonra yapılandırılmış veri çıkarmak üzere ayarlanmışsa, bu veriler sonlandırma tamamlandıktan sonra ayrı olarak teslim edilir.

Kaydedilmiş bir ajana arama başına değişken geçirin#

Kaydedilmiş ajanlar, istem metninde {{name}} veya {{name|there}} gibi yer tutucular kullanabilir. agent_id ile giden arama başlattığınızda, o aramanın değerlerini içeren variables alanını iletin:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Yer tutucu adıyla anahtarlanmış dize değerleri kullanın. Bu değişkenler kaydedilmiş ajanlar için geçerlidir; bu kılavuzdaki satır içi config örneği bunları kullanmaz.

Ele alınması gereken hata durumları#

Eksiksiz kararlı uygunluk kodu listesi ve her iki 409 yanıt biçimi için giden aramalar referansına bakın. Etkin bir numara, istek kabul edildikten sonra ancak arama başlatılmadan önce uygunsuz hâle gelirse, son kontrol yeniden denenemeyen 409 yükünü döndürür.

Bekletme süresini kontrol etme#

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

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

Son N saniye içinde insan sesi alınmadıysa ajan aramayı sonlandırır. Varsayılan süre 900 saniyedir (15 dakika).

Sonraki adımlar#