---
title: "Uskutočňujte odchádzajúce hovory (API)"
description: "Spustite odchádzajúci hovor riadený AI z vlastného kódu — pre prieskumy, následné kontaktovanie alebo potvrdzovacie postupy."
---

Odchádzajúce volania umožňujú odovzdať ThunderPhone cieľové číslo a konfiguráciu
agenta, aby AI uskutočnila hovor vo vašom mene. Bežné prípady použitia:

- Potvrdenia termínov
- Spätné volania pri prieskumoch
- Následné kontaktovanie na druhý pokus po zmeškanom hovore
- Oznámenia v štýle dispečingu

<Note>
  Voláte celý zoznam? Funkcia
  [**Kampane**](/sk/guides/outbound-campaigns) na ovládacom paneli
  (`/dashboard/campaigns`) prijíma CSV kontaktov a zaistí
  časové okná volania so zohľadnením časových pásiem, súbežnosť a pravidlá
  opakovania. Táto príručka sa venuje jednotlivým programovým volaniam.
</Note>

## Požiadavky

<Steps>
  <Step title="Použite číslo VoIP">
    Odchádzajúce volania vyžadujú, aby ste vlastnili `from_number` prostredníctvom
    [pripojenia VoIP](/api-reference/voip-connections). Čísla ThunderPhone
    sú určené iba pre prichádzajúce hovory. Pozrite si
    [Použitie vlastných čísel](/sk/guides/bring-your-own-numbers).
  </Step>
  <Step title="Vytvorte agenta">
    Výzva určená pre odchádzajúce hovory zvyčajne začína tým, že sa hlasový agent
    predstaví a uvedie svoj účel — „Dobrý deň, tu je Acme, voláme, aby sme
    potvrdili váš zajtrajší termín o 15:00…“ Nastavte
    `outbound_speak_order` na `agent_first` (predvolené nastavenie).
  </Step>
  <Step title="Udržujte kladný zostatok">
    Odchádzajúce hovory vrátia `402 Payment Required`, ak je zostatok ≤
    `$0.00`. Dobite kredit cez
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    alebo povoľte [automatické dobíjanie](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Uskutočnite hovor s uloženým agentom

Najjednoduchší spôsob — odkážte na agenta podľa id:

```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":   "+14155550199",
    "agent_id":    12
  }'
```

Odpoveď:

```json
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` znamená iba to, že požiadavka bola prijatá — hovor
  **ešte nie je spojený**. Aktuálny stav zisťujte pomocou
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  (`in_progress` → `completed` / `failed`).
</Warning>

## Uskutočnite hovor s vloženou konfiguráciou

Ak chcete jednorazovú výzvu, ktorú sa neoplatí ukladať ako agenta,
namiesto toho odošlite `config`. Štruktúra zodpovedá schéme odpovede
webhooku [`call.incoming`](/sk/webhooks/call-incoming):

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

## Sledujte hovor

Súbežne sa prihláste na odber webhooku
[`telephony.complete`](/sk/webhooks/events) —
je to najrýchlejší spôsob, ako zistiť, že hovor skončil. Ak nemôžete prijímať
prichádzajúce webhooky, každých niekoľko sekúnd zisťujte stav cez `GET /v1/calls/{call_id}`; záznam
po skončení hovoru obsahuje `end_reason`, `duration_seconds` a URL záznamu.

## Stavy zlyhania, ktoré sa oplatí spracovať

| Chyba | Riešenie |
|-------|-----|
| `402 Payment Required` | Dobite kredit alebo povoľte automatické dobíjanie |
| `403` odchádzajúce volania sú blokované (číslo ThunderPhone) | Použite namiesto toho číslo VoIP |
| `403` odchádzajúce volania sú blokované (neoverené VoIP) | Spustite [`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` | Overte, že `from_number` zodpovedá telefónnemu číslu, ktoré vlastníte |
| `502 Bad Gateway` | Dočasné zlyhanie SIP / LiveKit; opakovanie je bezpečné |

## Riadenie času čakania

Odchádzajúce hovory, ktoré trvajú dlho, pretože volaný reaguje pomaly
(stromy IVR, fronty), možno obmedziť pomocou `max_hold_seconds`:

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

Agent ukončí hovor, ak za posledných N sekúnd neprijal žiadny zvuk od človeka. Predvolená hodnota je 900 (15 minút).

---

## Ďalšie kroky

<CardGroup cols={2}>
  <Card title="Referenčná dokumentácia odchádzajúcich hovorov" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Každé pole požiadavky a chybový kód.
  </Card>
  <Card title="Prijatie call.complete" icon="bolt" href="/sk/webhooks/call-complete">
    Streamujte dokončené odchádzajúce hovory do svojho systému.
  </Card>
  <Card title="Fakturácia" icon="credit-card" href="/api-reference/billing">
    Automatické dobitie, aby odchádzajúce hovory nikdy nezlyhali pre nedostatočný zostatok.
  </Card>
  <Card title="Testovanie odchádzajúcich agentov" icon="flask" href="/sk/guides/test-agents">
    Pred nasadením otestujte svojho odchádzajúceho agenta nasucho.
  </Card>
</CardGroup>