> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Note>
  Tüm bir listeyi mi arıyorsunuz? Kontrol panelindeki
  [**Kampanyalar**](/tr/guides/outbound-campaigns) ö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.
</Note>

## Ön koşullar

<Steps>
  <Step title="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ı](/api-reference/voip-connections) üzerinden sağlanması gerekir. Demo numaralar
    yalnızca gelen aramalar içindir. Bkz.
    [Kendi numaralarınızı getirin](/tr/guides/bring-your-own-numbers).
  </Step>

  <Step title="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).
  </Step>

  <Step title="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`](/api-reference/billing#top-up-balance) kullanın
    veya [otomatik bakiye yüklemeyi](/api-reference/billing#update-auto-reload) etkinleştirin.
  </Step>
</Steps>

## Kaydedilmiş bir ajanla arama yapın

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

```bash theme={null}
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:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `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}`](/api-reference/calls#retrieve-a-call) çağrısını
  sorgulayın (`in_progress` → `completed` / `failed`).
</Warning>

## 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](/tr/webhooks/call-incoming):

```bash theme={null}
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](/tr/webhooks/events) 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`](/api-reference/phone-numbers#verify-a-voip-sourced-number) ç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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Giden aramalar referansı" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Tüm istek alanları ve hata kodları.
  </Card>

  <Card title="call.complete alma" icon="bolt" href="/tr/webhooks/call-complete">
    Tamamlanan giden aramaları sisteminize aktarın.
  </Card>

  <Card title="Faturalandırma" icon="credit-card" href="/api-reference/billing">
    Giden aramaların bakiye nedeniyle başarısız olmaması için otomatik yükleme.
  </Card>

  <Card title="Giden ajanları test etme" icon="flask" href="/tr/guides/test-agents">
    Giden ajanınızı üretime almadan önce deneme çalıştırması yapın.
  </Card>
</CardGroup>