---
title: "Giden aramalar yapın (API)"
description: "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
Tüm bir listeyi mi arıyorsunuz? Kontrol panelindeki
[**Kampanyalar**](/tr/guides/outbound-campaigns) özelliği
(`/dashboard/campaigns`) bir kişi CSV'si alır ve saat dilimine duyarlı
arama zaman aralıklarını, eşzamanlılığı ve yeniden deneme politikasını
sizin için yönetir. Bu kılavuz tekil programatik aramaları kapsar.
## Ön koşullar
Sahip olduğunuz bir numarayı
[VoIP bağlantısı](/api-reference/voip-connections) 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](/tr/guides/bring-your-own-numbers).
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).
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`](/api-reference/billing#get-billing-account) 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:
```bash
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:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` yalnızca isteğin kabul edildiği anlamına gelir — arama
**henüz bağlanmadı**. Canlı durumu (`in_progress` → `completed` / `failed`)
görmek için
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call) çağrısını yoklayın.
## 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](/tr/webhooks/call-incoming)
yanıt şemasıyla eşleşir:
```bash
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](/tr/webhooks/events) 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:
```json
{
"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ı
| Hata | Çözüm |
|-------|-----|
| `402 Payment Required` | Bakiyeyi yükleyin veya otomatik yüklemeyi etkinleştirin |
| `400` ve `code: destination_not_allowed` | ThunderPhone bu numarayı aramaz: geçersiz numaralar, acil durum numaraları, yüksek ücretli numaralar, kısa kodlar veya yaptırım uygulanan ülkeler. ThunderPhone numaralarından yalnızca normal ABD ve Kanada numaraları aranabilir (yüksek ücretli numaralar hariç). Hangisi olduğunu `reason` belirtir; bkz. [engellenen hedefler](/api-reference/outbound-calls#blocked-destinations) |
| ThunderPhone numarası için `retryable: false` içeren `409` | `code` yönergelerini izleyin: Telefon Numaraları sayfasından giden arama isteğinde bulunun, bekleyen incelemenin tamamlanmasını bekleyin veya uygun başka bir numara kullanın |
| `429` ve `code: platform_outbound_daily_limit_reached` | Kuruluş, ThunderPhone numaralarından bugünkü giden arama kotasını kullandı. `resets_at` (00:00 UTC) zamanını bekleyin, Telefon Numaraları sayfasından daha yüksek bir limit isteyin veya kendi VoIP bağlantınızdaki bir numaradan arayın |
| `429` ve `code: concurrent_call_limit_reached` | Kuruluşun devam eden arama sayısı, [eşzamanlı arama limiti](/api-reference/introduction#call-limits) kadardır (varsayılan olarak 20; gelen, giden, web ve test aramaları dahil). `Retry-After` başlığındaki saniye sayısı kadar bekledikten sonra veya bir arama sona erdiğinde yeniden deneyin; limiti artırmak için support@thunderphone.com adresine e-posta gönderin |
| `429` ve `code: same_number_too_soon` | Aynı `to_number` numarasını 10 saniyeden kısa süre önce aradınız. `Retry-After` başlığındaki saniye sayısı kadar bekledikten sonra yeniden deneyin |
| Müşteri VoIP numarası için `retryable: false` içeren `409` | `code` tarafından belirtilen durumu düzeltin; doğrulama hatalarında [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) isteğini çalıştırın |
| `409` idempotentlik çakışması | Anahtarı yalnızca özgün normalleştirilmiş istekle yeniden kullanın veya yeni bir anahtar gönderin |
| `404 from_number is not registered to this organization` | `from_number` değerinin kuruluşunuzdaki etkin bir telefon numarasıyla eşleştiğini doğrulayın. Sağlanmakta olan, başarısız olan, serbest bırakılmakta olan veya serbest bırakılmış bir numara da bu yanıtı döndürür |
| Yalnızca `detail` alanı içeren `500` | Giden trunk yapılandırılmamış. Destek ekibiyle iletişime geçin; bu, düzeltebileceğiniz bir numara durumu sorunu değildir |
| `502 Bad Gateway` | Geçici SIP / LiveKit hatası; yeniden denemek güvenlidir |
Eksiksiz kararlı uygunluk kodu listesi ve her iki `409` yanıt biçimi için
[giden aramalar referansına](/api-reference/outbound-calls#error-responses) 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:
```json
{
"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
Tüm istek alanları ve hata kodları.
Tamamlanmış giden aramaları sisteminize aktarın.
Giden aramaların bakiye nedeniyle başarısız olmaması için otomatik yükleme kullanın.
Giden arama yapan ajanınızı üretime geçmeden önce deneme çalıştırmasıyla test edin.