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

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

Előfeltételek#

1. Válasszon kimenő hívásokra engedélyezett számot

   Használjon egy Ön tulajdonában lévő számot egy VoIP-kapcsolaton 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.

2. Hozzon létre egy ügynököt

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

3. Tartson fenn pozitív egyenleget

   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 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:

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:

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

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 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":   "+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 — 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:

{
  "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#

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

{
  "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#