Kimenő hívások indítása (API)

A kimenő hívásokkal megadhat egy céltelefonszámot és egy ügynök- konfigurációt a ThunderPhone számára, hogy az AI-ügynök az Ön nevében kezdeményezze a hívást. Tipikus felhasználási esetek:

Időpont-visszaigazolások
Visszahívások felmérésekhez
„Második próbálkozásos” utánkövetések nem fogadott hívás után
Diszpécserjellegű értesítések

Teljes listát hív? A vezérlőpult Kampányok funkciója (/dashboard/campaigns) fogadja a kapcsolatok CSV-fájlját, és kezeli az időzóna szerinti hívási időablakokat, a párhuzamosságot és az újrapróbálási szabályzatot. Ez az útmutató az egyedi, programozott hívásokat ismerteti.

Előfeltételek

Hozzon saját VoIP-számot

A kimenő hívásokhoz Önnek kell birtokolnia a from_number számot egy VoIP-kapcsolaton keresztül. A demószámok csak bejövő hívásokhoz használhatók. Lásd: Saját telefonszámok használata.

Hozzon létre egy ügynököt

A kimenő hívásokhoz készült promptok általában azzal kezdődnek, hogy az ügynök bemutatkozik és ismerteti a célját — „Üdvözlöm, az Acme-től 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).

Tartson fenn pozitív egyenleget

A kimenő hívások 402 Payment Required választ adnak vissza, ha az egyenleg ≤ $0.00. Töltsön fel egyenleget a következővel: POST /v1/billing/top-up, vagy engedélyezze az automatikus feltöltést.

Hívás indítása mentett ügynökkel

A legegyszerűbb megoldás — hivatkozzon egy ügynökre azonosító alapján:

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

Válasz:

{ "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 nincs kapcsolva. Kérdezze le rendszeresen a GET /v1/calls/{call_id} végpontot az aktuális állapotért (in_progress → completed / failed).

Hívás indítása beágyazott konfigurációval

Ha egyszeri promptot szeretne használni, amelyet nem érdemes ügynökként menteni, adja meg helyette a config értéket. A szerkezete megegyezik a call.incoming webhook válaszsémájával:

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

A hívás követése

Ezzel párhuzamosan iratkozzon fel a telephony.complete webhookra — ez a leggyorsabb módja annak, hogy megtudja, mikor fejeződött be egy hívás. Ha nem tud bejövő webhookokat fogadni, kérdezze le a GET /v1/calls/{call_id} végpontot néhány másodpercenként; a rekord a hívás befejezése után tartalmazza az end_reason, a duration_seconds és a felvétel URL-jét.

Kezelendő hibamódok

Hiba	Javítás
`402 Payment Required`	Töltse fel az egyenleget, vagy engedélyezze az automatikus feltöltést
`403` kimenő hívások blokkolva (demószám)	Használjon inkább VoIP-számot
`403` kimenő hívások blokkolva (nem hitelesített VoIP)	Futtassa a következőt: `POST /v1/phone-numbers/{id}/verify-voip`
`404 from_number is not registered to this organization`	Ellenőrizze, hogy a `from_number` az Ön tulajdonában lévő telefonszámnak felel meg
`502 Bad Gateway`	Átmeneti SIP- / LiveKit-hiba; biztonságosan újrapróbálható

Várakoztatási idő szabályozása

Az olyan kimenő hívások, amelyek elhúzódnak, 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:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "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 (15 perc).

Következő lépések

Kimenő hívások referenciája

Minden kérésmező és hibakód.

A call.complete fogadása

Továbbítsa a befejezett kimenő hívásokat a rendszerébe.

Számlázás

Automatikus feltöltés, hogy a kimenő hívások soha ne hiúsuljanak meg az egyenleg miatt.

Kimenő ügynökök tesztelése

Élesítés előtt futtasson próbahívást a kimenő ügynökével.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Kimenő hívások indítása (API)

Előfeltételek

Hívás indítása mentett ügynökkel

Hívás indítása beágyazott konfigurációval

A hívás követése

Kezelendő hibamódok

Várakoztatási idő szabályozása

Következő lépések

Kimenő hívások referenciája

A call.complete fogadása

Számlázás

Kimenő ügynökök tesztelése

​Előfeltételek

​Hívás indítása mentett ügynökkel

​Hívás indítása beágyazott konfigurációval

​A hívás követése

​Kezelendő hibamódok

​Várakoztatási idő szabályozása

​Következő lépések

Kimenő hívások referenciája

A call.complete fogadása

Számlázás

Kimenő ügynökök tesztelése

Előfeltételek

Hívás indítása mentett ügynökkel

Hívás indítása beágyazott konfigurációval

A hívás követése

Kezelendő hibamódok

Várakoztatási idő szabályozása

Következő lépések