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

# Lakukan panggilan keluar (API)

> Picu panggilan keluar berbasis AI dari kode Anda sendiri — untuk alur survei, tindak lanjut, atau konfirmasi.

Panggilan keluar memungkinkan Anda menyerahkan nomor tujuan dan konfigurasi agen
kepada ThunderPhone agar AI melakukan panggilan atas nama Anda. Kasus penggunaan umum:

* Konfirmasi janji temu
* Panggilan balik survei
* Tindak lanjut "percobaan kedua" setelah panggilan terlewat
* Notifikasi bergaya dispatch

<Note>
  Menelepon seluruh daftar? Fitur
  [**Campaigns**](/id/guides/outbound-campaigns) di dashboard
  (`/dashboard/campaigns`) menerima CSV kontak dan menangani
  jendela panggilan yang mempertimbangkan zona waktu, konkurensi, dan kebijakan percobaan ulang
  untuk Anda. Panduan ini membahas panggilan programatis tunggal.
</Note>

## Prasyarat

<Steps>
  <Step title="Sediakan nomor VoIP">
    Panggilan keluar mengharuskan Anda memiliki `from_number` melalui
    [koneksi VoIP](/api-reference/voip-connections). Nomor demo
    hanya untuk panggilan masuk. Lihat
    [Gunakan nomor Anda sendiri](/id/guides/bring-your-own-numbers).
  </Step>

  <Step title="Buat agen">
    Prompt bernuansa panggilan keluar biasanya dimulai dengan agen
    memperkenalkan diri dan tujuannya — "Halo, ini Acme yang menelepon untuk
    mengonfirmasi janji temu Anda besok pukul 15.00…" Atur
    `outbound_speak_order` ke `agent_first` (default).
  </Step>

  <Step title="Pertahankan saldo positif">
    Panggilan keluar mengembalikan `402 Payment Required` jika saldo ≤
    `$0.00`. Isi saldo melalui
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    atau aktifkan [isi ulang otomatis](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Lakukan panggilan dengan agen tersimpan

Cara paling sederhana — referensikan agen berdasarkan id:

```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
  }'
```

Respons:

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

<Warning>
  `status: "initiated"` hanya berarti permintaan diterima — panggilan
  **belum terhubung**. Polling
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  untuk status langsung (`in_progress` → `completed` / `failed`).
</Warning>

## Lakukan panggilan dengan konfigurasi inline

Jika Anda menginginkan Prompt sekali pakai yang tidak perlu disimpan sebagai agen,
gunakan `config`. Bentuknya sesuai dengan skema respons dari
[webhook `call.incoming`](/id/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"
    }
  }'
```

## Pantau panggilan

Secara paralel, berlangganan ke
[webhook `telephony.complete`](/id/webhooks/events) —
cara tercepat untuk mengetahui panggilan telah selesai. Jika Anda tidak dapat menerima
webhook masuk, lakukan polling `GET /v1/calls/{call_id}` setiap beberapa detik; rekaman
mencakup `end_reason`, `duration_seconds`, dan URL rekaman setelah panggilan berakhir.

## Mode kegagalan yang perlu ditangani

| Error                                                     | Perbaikan                                                                                                       |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                    | Isi saldo atau aktifkan isi ulang otomatis                                                                      |
| `403` panggilan keluar diblokir (nomor demo)              | Gunakan nomor VoIP sebagai gantinya                                                                             |
| `403` panggilan keluar diblokir (VoIP belum diverifikasi) | Jalankan [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization`  | Pastikan `from_number` sesuai dengan nomor telepon yang Anda miliki                                             |
| `502 Bad Gateway`                                         | Kegagalan SIP / LiveKit sementara; aman untuk mencoba lagi                                                      |

## Mengontrol waktu tunggu

Panggilan keluar yang berlangsung lama karena pihak yang dihubungi lambat merespons
(pohon IVR, antrean) dapat dibatasi dengan `max_hold_seconds`:

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

Agen mengakhiri panggilan jika tidak ada audio manusia yang diterima dalam
N detik terakhir. Defaultnya adalah 900 (15 menit).

***

## Langkah berikutnya

<CardGroup cols={2}>
  <Card title="Referensi panggilan keluar" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Setiap kolom permintaan dan kode error.
  </Card>

  <Card title="Menerima call.complete" icon="bolt" href="/id/webhooks/call-complete">
    Alirkan panggilan keluar yang selesai ke sistem Anda.
  </Card>

  <Card title="Penagihan" icon="credit-card" href="/api-reference/billing">
    Isi ulang otomatis agar panggilan keluar tidak pernah gagal karena saldo.
  </Card>

  <Card title="Menguji agen panggilan keluar" icon="flask" href="/id/guides/test-agents">
    Lakukan dry run agen panggilan keluar Anda sebelum produksi.
  </Card>
</CardGroup>