Bejövő hívások kezelése (API)

Teljes folyamat: konfiguráljon egy ügynököt, rendeljen hozzá egy telefonszámot, fogadjon hívást, és tekintse át az átiratot.

A kanonikus „AI-val válaszoljon meg egy telefont” folyamat a terminálból. A következőket fogja tenni:

1. Létrehoz egy ügynököt prompttal és hanggal.
2. Igényel (vagy hoz) egy telefonszámot, és az ügynököt a bejövő hívások kezelőjeként rendeli hozzá.
3. Felhívja a számot. Megtekinti a hívásnaplót, az átiratot és a felvételt.

API-hívások száma összesen: négy. Teljes idő: kevesebb mint öt perc.

1. Ügynök létrehozása#

Egy AI-ügynök egyesíti a hívást működtető promptot, hangot és termékszintet. Az AI-ügynökön híváskorlátokat is beállíthat, például a max_call_duration_seconds és a ring_duration_seconds értékét. Az AI-ügynökök az intro_clip és az intro_ring_count beállításokat is támogatják, így előre felvett bevezetőt és legfeljebb két kicsengést játszhat le, mielőtt az AI-ügynök megszólal. Az új AI-ügynökök esetében időzónát is meg kell adnia. Az összes konfigurációs mezőt lásd itt: Ügynökök; a minimálisan szükséges beállítás:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "spark"
  }'

Mentse el a visszaadott id értéket — a 2. lépésben szüksége lesz rá.

2. Telefonszám beszerzése#

Ha csak egy hívható számra van szüksége, igényeljen ThunderPhone-számot a ThunderPhone készletéből:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

A válasz E.164 formátumban tartalmaz egy id és egy number értéket. A ThunderPhone-számok kezdetben status="provisioning" állapotúak, majd néhány másodpercen belül active állapotba kerülnek — ha fontos Önnek, lekérdezheti a folyamatot a GET /v1/phone-numbers/{id} végponttal.

3. Az ügynök hozzárendelése#

Rendelje az 1. lépésben létrehozott ügynököt a szám bejövő hívási irányához:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Ennyi — a szám aktív. Miután szervezete számára jóváhagyták a kimenő hívásokat, ugyanebben a PATCH kérésben az outbound_agent_id értékét is beállíthatja. Addig az API 400 hibával elutasítja ezt a hozzárendelést.

Ha a bejövő hívásokat rögzített inbound_agent_id helyett konfigurációs webhookon keresztül irányítja, az a webhook mostantól hívásonkénti timezone értéket is visszaadhat az agent_id és a variables mellett.

4. Hívás fogadása#

Hívja fel a számot a telefonjáról. Az ügynök felveszi, a promptja szerint bemutatkozik, és megkezdődik a beszélgetés.

Amíg a hívás folyamatban van, a GET /v1/calls végponton status="in_progress" állapottal jelenik meg. Amikor véget ér, a rekord frissül az end_reason, duration_seconds, billable_minutes értékekkel, valamint később egy felvételi URL-lel és AI-értékeléssel.

A bejövő hívások beleszámítanak szervezete egyidejűhívás-korlátjába (alapértelmezés szerint 20 folyamatban lévő hívás, amelyet a kimenő, webes és teszthívásokkal közösen használnak). A korlát elérésekor beérkező hívást az AI-ügynök válaszadása előtt elutasítják és bontják, nem számlázzák ki, és sikertelen hívásként rögzítik concurrent_call_limit_reached befejezési okkal. Ha magasabb korlátra van szüksége, írjon a support@thunderphone.com címre.

5. Az eredmények ellenőrzése#

Kérje le a legutóbbi hívások listáját:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Kérje le az átiratot:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

És a felvétel URL-jét (rövid élettartamú, aláírt):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Ha feliratkozott a telephony.complete webhookra, ugyanezeket az adatokat POST-kérésként kapja meg a szerverén — lásd: call.complete.

Ha az ügynökéhez kinyerési mezők vannak konfigurálva, a befejezett hívás hasznos terhe strukturáltan kinyert adatokat is tartalmazhat.

Következő lépések#