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

# Uskutečňování odchozích hovorů (API)

> Spusťte ze svého vlastního kódu odchozí hovor řízený AI – pro průzkumy, následné kontaktování nebo potvrzovací procesy.

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

* Potvrzení termínů
* Zpětná volání k průzkumům
* Následná volání na druhý pokus po zmeškaném hovoru
* Oznámení ve stylu dispečinku

<Note>
  Voláte na celý seznam? Funkce
  [**Kampaně**](/cs/guides/outbound-campaigns) v dashboardu
  (`/dashboard/campaigns`) přijímá CSV kontaktů a za vás zajišťuje
  časová okna volání s ohledem na časová pásma, souběžnost a zásady
  opakování. Tento průvodce popisuje jednotlivá programová volání.
</Note>

## Předpoklady

<Steps>
  <Step title="Přidejte VoIP číslo">
    Pro odchozí volání musíte vlastnit `from_number` prostřednictvím
    [VoIP připojení](/api-reference/voip-connections). Ukázková čísla
    jsou pouze pro příchozí hovory. Viz
    [Použijte vlastní čísla](/cs/guides/bring-your-own-numbers).
  </Step>

  <Step title="Vytvořte agenta">
    Prompt určený pro odchozí hovory obvykle začíná tím, že se agent
    představí a uvede svůj účel — „Dobrý den, zde Acme, voláme kvůli
    potvrzení vašeho zítřejšího termínu v 15:00…“ Nastavte
    `outbound_speak_order` na `agent_first` (výchozí nastavení).
  </Step>

  <Step title="Udržujte kladný zůstatek">
    Odchozí volání vrací `402 Payment Required`, pokud je zůstatek ≤
    `$0.00`. Doplňte kredit pomocí
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    nebo povolte [automatické dobíjení](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

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

Nejjednodušší postup — odkažte na agenta podle 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
  }'
```

Odpověď:

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

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

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

Pokud potřebujete jednorázový prompt, který nemá smysl ukládat jako agenta,
předejte místo toho `config`. Struktura odpovídá schématu odpovědi webhooku
[`call.incoming`](/cs/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"
    }
  }'
```

## Sledujte hovor

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

## Chybové stavy, které se vyplatí ošetřit

| Chyba                                                    | Řešení                                                                                                         |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                   | Doplňte zůstatek nebo povolte automatické dobíjení                                                             |
| `403` odchozí volání blokováno (ukázkové číslo)          | Místo toho přidejte VoIP číslo                                                                                 |
| `403` odchozí volání blokováno (neověřené VoIP)          | Spusťte [`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` | Ověřte, že `from_number` odpovídá telefonnímu číslu, které vlastníte                                           |
| `502 Bad Gateway`                                        | Dočasné selhání SIP / LiveKit; opakování je bezpečné                                                           |

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

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

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

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

***

## Další kroky

<CardGroup cols={2}>
  <Card title="Referenční dokumentace odchozích hovorů" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Každé pole požadavku a chybový kód.
  </Card>

  <Card title="Přijímání 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 do produkce nasucho otestujte svého odchozího agenta.
  </Card>
</CardGroup>