---
title: "Kimenő hívások indítása (API)"
description: "Indítson AI által vezérelt kimenő hívást saját kódjából — felmérési, utánkövetési vagy megerősítési folyamatokhoz."
---
Kimenő hívással megadhat ThunderPhone számára egy céltelefonszámot és egy ügynökkonfigurációt, hogy az AI az Ön nevében kezdeményezze a hívást. Jellemző felhasználási esetek:
- Időpont-visszaigazolások
- Felmérésekkel kapcsolatos visszahívások
- „Második próbálkozásos” utánkövetések nem fogadott hívás után
- Diszpécser jellegű értesítések
Teljes listát hívna? Az irányítópult
[**Kampányok**](/hu/guides/outbound-campaigns) funkciója
(`/dashboard/campaigns`) fogadja a kapcsolatok CSV-fájlját, és kezeli Ön helyett
az időzónaérzékeny hívási időablakokat, a párhuzamosságot és az újrapróbálkozási
szabályzatot. Ez az útmutató egyedi, programozott hívásokat ismertet.
## Előfeltételek
Használjon egy Ön tulajdonában lévő számot egy
[VoIP-kapcsolaton](/api-reference/voip-connections) keresztül, vagy kérjen engedélyt
ThunderPhone-számainak kimenő hívásokhoz való használatára a Phone Numbers
oldalon. A ThunderPhone-számok kezdetben csak bejövő hívásokra használhatók. A ThunderPhone minden
kérelmet manuálisan ellenőriz; jóváhagyás után ezek a számok hívásokat kezdeményezhetnek a
jóváhagyott napi korlátig (amely 00:00 UTC-kor nullázódik), valamint kampányokat futtathatnak, és
magasabb korlátot is kérhet. Az ügyfél VoIP-számaira nem vonatkozik napi korlát, ezért
kimenő hívásokhoz ezeket javasoljuk. Lásd:
[Saját számok használata](/hu/guides/bring-your-own-numbers).
A kimenő hívásokhoz készült prompt jellemzően azzal kezdődik, hogy az ügynök
bemutatkozik és ismerteti a célját — „Üdvözlöm, az Acme nevében hívom, hogy
megerősítsem a holnap délután 3 órára szóló időpontját…” Állítsa az
`outbound_speak_order` értékét `agent_first` értékre (ez az alapértelmezett).
A kimenő hívások `402 Payment Required` választ adnak vissza, ha az egyenleg ≤
`$0.00`. Töltse fel az egyenleget, vagy engedélyezze az automatikus feltöltést a
vezérlőpult **Szervezet → Számlázási beállítások** menüpontjában. Az `sk_live_`
kulccsal ellenőrizheti az egyenleget a
[`GET /v1/billing`](/api-reference/billing#get-billing-account) használatával, de
nem töltheti fel az egyenleget, és nem módosíthatja az automatikus feltöltést.
## Hívás kezdeményezése mentett ügynökkel
A legegyszerűbb megoldás — hivatkozzon egy ügynökre azonosító alapján:
```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
}'
```
Válasz:
```json
{ "call_id": 987654321, "status": "initiated" }
```
A `status: "initiated"` csak azt jelenti, hogy a kérés elfogadásra került — a hívás
**még nem kapcsolódott**. Kérdezze le a
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
végpontot az élő állapotért (`in_progress` → `completed` / `failed`).
## Hívás kezdeményezése beágyazott konfigurációval
Ha egyszeri promptot szeretne használni, amelyet nem érdemes ügynökként menteni,
adja át helyette a `config` értéket. A formátuma megegyezik a
[`call.incoming` webhook](/hu/webhooks/call-incoming)
válaszsémájával:
```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"
}
}'
```
## Kövesse a hívást
Ezzel párhuzamosan iratkozzon fel a
[`telephony.complete` webhookra](/hu/webhooks/events) —
ez a leggyorsabb módja annak, hogy megtudja, mikor fejeződött be egy hívás. Ha nem tud
bejövő webhookokat fogadni, néhány másodpercenként kérdezze le a `GET /v1/calls/{call_id}` végpontot; a
rekord a hívás befejeződése után tartalmazza az `end_reason`, a `duration_seconds` és a felvétel
URL-jét.
Ha az ügynöke úgy van beállítva, hogy a hívás után strukturált adatokat nyerjen ki,
ezek az adatok a véglegesítés befejezése után külön érkeznek meg.
### Hívásonkénti változók átadása mentett ügynöknek
A mentett ügynökök olyan helyőrzőket használhatnak a prompt szövegében, mint a `{{name}}` vagy a `{{name|there}}`.
Ha `agent_id` használatával indít kimenő hívást, adja át az adott hívás értékeit a
`variables` mezőben:
```json
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}
```
Használjon karakterláncértékeket, amelyeknek a kulcsa a helyőrző neve. Ezek a változók a
mentett ügynökökre vonatkoznak; az útmutató beágyazott `config` példája nem használja őket.
## Kezelendő hibamódok
| Hiba | Javítás |
|-------|-----|
| `402 Payment Required` | Töltse fel az egyenleget, vagy engedélyezze az automatikus feltöltést |
| `400` ezzel: `code: destination_not_allowed` | ThunderPhone nem hívja ezt a számot: érvénytelen számok, segélyhívó számok, emelt díjas számok, rövid kódok vagy szankciókkal sújtott országok. ThunderPhone-számokról csak hagyományos amerikai és kanadai számok hívhatók (emelt díjas számok nem). A `reason` jelzi, melyikről van szó; lásd: [tiltott célállomások](/api-reference/outbound-calls#blocked-destinations) |
| `409` ezzel: `retryable: false`, ThunderPhone-szám esetén | Kövesse a `code` utasítását: kérjen kimenő hívási jogosultságot a Telefonos számok oldalon, várja meg a függőben lévő ellenőrzést, vagy használjon másik jogosult számot |
| `429` ezzel: `code: platform_outbound_daily_limit_reached` | A szervezet felhasználta a ThunderPhone-számokról indítható mai kimenő hívások keretét. Várjon a `resets_at` időpontig (00:00 UTC), kérjen magasabb korlátot a Telefonos számok oldalon, vagy hívjon saját VoIP-kapcsolatán lévő számról |
| `429` ezzel: `code: concurrent_call_limit_reached` | A szervezetnek annyi folyamatban lévő hívása van, amennyi a [párhuzamos hívási korlátja](/api-reference/introduction#call-limits) (alapértelmezés szerint 20, beleértve a bejövő, kimenő, webes és teszthívásokat). Próbálja újra a `Retry-After` fejlécben megadott másodpercek után, vagy amikor egy hívás befejeződik; a korlát emeléséhez írjon a support@thunderphone.com címre |
| `429` ezzel: `code: same_number_too_soon` | Kevesebb mint 10 másodperce hívta ugyanazt a `to_number` számot. Próbálja újra a `Retry-After` fejlécben megadott másodpercek után |
| `409` ezzel: `retryable: false`, ügyfél VoIP-száma esetén | Hozza helyre a `code` által jelzett állapotot; ellenőrzési hiba esetén futtassa a következőt: [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `409` idempotenciakonfliktus | A kulcsot csak az eredeti normalizált kéréssel használja újra, vagy küldjön új kulcsot |
| `404 from_number is not registered to this organization` | Ellenőrizze, hogy a `from_number` megegyezik-e a szervezet egyik aktív telefonszámával. A már kiépítés alatt álló, sikertelen, felszabadítás alatt álló vagy felszabadított szám is ezt a választ adja |
| `500` csak `detail` mezővel | Nincs konfigurálva kimenő trunk. Forduljon az ügyfélszolgálathoz; ez nem olyan számállapot-probléma, amelyet Ön javíthat |
| `502 Bad Gateway` | Átmeneti SIP- vagy LiveKit-hiba; biztonságosan újrapróbálható |
A teljes, stabil jogosultsági kódlistáért és mindkét `409` válaszformátumért
tekintse meg a [kimenő hívások referenciaanyagát](/api-reference/outbound-calls#error-responses).
Ha egy aktív szám a kérés elfogadása után, de a hívás indítása előtt válik jogosulatlanná,
a végső ellenőrzés a nem újrapróbálható `409` hasznos terhet adja vissza.
## Várakoztatási idő szabályozása
Azok a kimenő hívások, amelyek azért tartanak sokáig, mert a hívott fél lassan válaszol
(IVR-menük, várólisták), a `max_hold_seconds` értékkel korlátozhatók:
```json
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}
```
Az ügynök bontja a hívást, ha az elmúlt N másodpercben nem érkezett emberi hang. Az alapértelmezett érték 900 másodperc (15 perc).
---
## Következő lépések
Minden kérésmező és hibakód.
Továbbítsa a befejezett kimenő hívásokat a rendszerébe.
Automatikus feltöltés, hogy a kimenő hívások soha ne bukjanak el egyenleg miatt.
Éles használat előtt futtasson próbahívást a kimenő ügynökével.