---
title: "Provádění odchozích hovorů (API)"
description: "Spusťte ze svého vlastního kódu odchozí hovor řízený umělou inteligencí – pro průzkumy, následné kontaktování nebo potvrzovací postupy."
---

Odchozí volání vám umožňuje předat ThunderPhone cílové číslo a
konfiguraci agenta a nechat AI uskutečnit hovor vaším
jménem. Typické případy použití:

- Potvrzení schůzek
- Zpětná volání v rámci průzkumů
- Následná volání na druhý pokus po zmeškaném hovoru
- Oznámení ve stylu dispečinku

<Note>
  Voláte celému seznamu? Funkce
  [**Kampaně**](/cs/guides/outbound-campaigns) na ovládacím panelu
  (`/dashboard/campaigns`) přijme CSV kontaktů a postará se za vás
  o časová okna volání zohledňující časová pásma, souběžnost a zásady
  opakování pokusů. Tento průvodce se věnuje jednotlivým programovým voláním.
</Note>

## Předpoklady

<Steps>
  <Step title="Vyberte číslo povolené pro odchozí volání">
    Použijte číslo, které vlastníte prostřednictvím
    [připojení VoIP](/api-reference/voip-connections), nebo požádejte o povolení
    používat svá čísla ThunderPhone pro odchozí volání na stránce Telefonní čísla.
    Čísla ThunderPhone jsou zpočátku pouze pro příchozí volání. ThunderPhone každou
    žádost posuzuje ručně; po schválení mohou tato čísla uskutečňovat hovory až do
    schváleného denního limitu (který se resetuje ve 00:00 UTC) a spouštět kampaně.
    Můžete také požádat o vyšší limit. Zákaznická čísla VoIP nemají denní limit, proto je
    doporučujeme pro odchozí volání. Viz
    [Použití vlastních čísel](/cs/guides/bring-your-own-numbers).
  </Step>
  <Step title="Vytvořte agenta">
    Prompt pro odchozí volání obvykle začíná tím, že se agent představí
    a uvede svůj účel — „Dobrý den, volá Acme, abychom potvrdili
    vaši schůzku na zítřek v 15:00…“ Nastavte
    `outbound_speak_order` na `agent_first` (výchozí hodnota).
  </Step>
  <Step title="Udržujte kladný zůstatek">
    Odchozí hovory vrátí `402 Payment Required`, pokud je zůstatek ≤
    `$0.00`. Doplňte zůstatek nebo povolte automatické dobíjení v části
    **Organizace → Nastavení fakturace** na ovládacím panelu. Váš klíč `sk_live_`
    může zkontrolovat zůstatek pomocí
    [`GET /v1/billing`](/api-reference/billing#get-billing-account), ale
    nemůže doplnit zůstatek ani změnit automatické dobíjení.
  </Step>
</Steps>

## Uskutečněte hovor s uloženým agentem

Nejjednodušší způsob — odkažte na agenta podle 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":   "+14155552671",
    "agent_id":    12
  }'
```

Odpověď:

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

<Warning>
  `status: "initiated"` znamená pouze, že byl požadavek přijat — hovor
  **ještě není spojen**. Zjišťujte
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  pro aktuální stav (`in_progress` → `completed` / `failed`).
</Warning>

## Uskutečněte hovor s vloženou konfigurací

Pokud chcete jednorázový prompt, který nestojí za uložení jako agent,
předejte místo toho `config`. Struktura odpovídá schématu odpovědi webhooku
[`call.incoming`](/cs/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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## Sledujte hovor

Souběžně se přihlaste k odběru
[webhooku `telephony.complete`](/cs/webhooks/events) —
nejrychlejšího způsobu, jak zjistit, že hovor skončil. Pokud nemůžete přijímat příchozí
webhooky, dotazujte se každých několik sekund na `GET /v1/calls/{call_id}`; záznam
po skončení hovoru obsahuje `end_reason`, `duration_seconds` a adresu URL nahrávky.

Pokud je váš agent nastavený na extrakci strukturovaných dat po hovoru,
tato data jsou doručena samostatně po dokončení finalizace.

### Předání proměnných pro jednotlivý hovor uloženému agentovi

Uložení agenti mohou v textu promptu používat zástupné symboly jako `{{name}}` nebo `{{name|there}}`.
Při uskutečnění odchozího hovoru s `agent_id` předejte
`variables` s hodnotami pro daný hovor:

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

Použijte řetězcové hodnoty s klíči odpovídajícími názvům zástupných symbolů. Tyto proměnné platí pro
uložené agenty; příklad vloženého `config` v této příručce je nepoužívá.

## Stavy selhání, které je vhodné ošetřit

| Chyba | Řešení |
|-------|-----|
| `402 Payment Required` | Doplňte zůstatek nebo povolte automatické dobíjení |
| `400` s `code: destination_not_allowed` | ThunderPhone na toto číslo nevolá: neplatná čísla, tísňová čísla, čísla se zvýšenou sazbou, zkrácená čísla nebo země pod sankcemi. Z čísel ThunderPhone lze volat pouze na běžná čísla v USA a Kanadě (nikoli na čísla se zvýšenou sazbou). `reason` uvádí které; viz [blokované destinace](/api-reference/outbound-calls#blocked-destinations) |
| `409` s `retryable: false` pro číslo ThunderPhone | Postupujte podle `code`: požádejte o odchozí volání na stránce Telefonní čísla, vyčkejte na probíhající kontrolu nebo použijte jiné způsobilé číslo |
| `429` s `code: platform_outbound_daily_limit_reached` | Organizace již využila dnešní odchozí volání z čísel ThunderPhone. Počkejte na `resets_at` (00:00 UTC), požádejte o vyšší limit na stránce Telefonní čísla nebo volejte z čísla ve vlastním připojení VoIP |
| `429` s `code: concurrent_call_limit_reached` | Organizace má právě tolik probíhajících hovorů, kolik činí její [limit souběžných hovorů](/api-reference/introduction#call-limits) (ve výchozím nastavení 20; započítávají se příchozí, odchozí, webové a testovací hovory). Opakujte pokus po uplynutí počtu sekund z hlavičky `Retry-After` nebo po ukončení hovoru; pro zvýšení limitu napište na support@thunderphone.com |
| `429` s `code: same_number_too_soon` | Na stejné `to_number` jste volali před méně než 10 sekundami. Opakujte pokus po uplynutí počtu sekund z hlavičky `Retry-After` |
| `409` s `retryable: false` pro zákaznické číslo VoIP | Opravte stav uvedený v `code`; při selhání ověření spusťte [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| Konflikt idempotence `409` | Klíč znovu použijte pouze s původním normalizovaným požadavkem, nebo odešlete nový klíč |
| `404 from_number is not registered to this organization` | Ověřte, že `from_number` odpovídá aktivnímu telefonnímu číslu ve vaší organizaci. Tuto odpověď vrátí také číslo, které se již zřizuje, selhalo, uvolňuje se nebo bylo uvolněno |
| `500` pouze s polem `detail` | Není nakonfigurován žádný odchozí trunk. Kontaktujte podporu; nejde o problém se stavem čísla, který můžete opravit |
| `502 Bad Gateway` | Přechodné selhání SIP / LiveKit; pokus lze bezpečně opakovat |

Úplný stabilní seznam kódů způsobilosti a oba tvary odpovědi `409` najdete v
[referenci odchozích hovorů](/api-reference/outbound-calls#error-responses).
Pokud se aktivní číslo stane nezpůsobilým po přijetí požadavku, ale před
uskutečněním hovoru, závěrečná kontrola vrátí datovou část `409`, kterou nelze opakovat.

## Řízení doby čekání

Odchozí hovory, které trvají dlouho, protože volaný reaguje pomalu
(stromy IVR, fronty), lze omezit pomocí `max_hold_seconds`:

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

Agent hovor ukončí, pokud během posledních N sekund nepřijal žádný lidský zvukový projev. Výchozí hodnota je 900 sekund (15 minut).

---

## Další kroky

<CardGroup cols={2}>
  <Card title="Reference odchozích hovorů" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Každé pole požadavku a každý chybový kód.
  </Card>
  <Card title="Přijímejte call.complete" icon="bolt" href="/cs/webhooks/call-complete">
    Odesílejte dokončené odchozí hovory do svého systému.
  </Card>
  <Card title="Fakturace" icon="credit-card" href="/api-reference/billing">
    Automatické dobíjení, aby odchozí hovory nikdy neselhaly kvůli zůstatku.
  </Card>
  <Card title="Testování odchozích agentů" icon="flask" href="/cs/guides/test-agents">
    Před nasazením proveďte zkušební běh odchozího agenta.
  </Card>
</CardGroup>