ThunderPhone v3 je tu.Začnite sami, už od 2 ¢/min.Prečítať oznámenie

Developer cookbook

Spracovanie prichádzajúcich hovorov (API)

Od začiatku do konca: nakonfigurujte agenta, priraďte ho k telefónnemu číslu, prijmite hovor a skontrolujte prepis.

Štandardný postup „odpovedať na telefón pomocou AI“ z vášho terminálu. Budete:

  1. Vytvorte agenta s promptom a hlasom.
  2. Zriaďte (alebo pridajte vlastné) telefónne číslo a priraďte agenta ako jeho obsluhu prichádzajúcich hovorov.
  3. Zavolajte na číslo. Skontrolujte denník hovorov, prepis a nahrávku.

Celkový počet volaní API: štyri. Celkový čas: menej ako päť minút.

1. Vytvorte agenta

Hlasový agent spája prompt, hlas a produktovú úroveň, ktoré budú riadiť hovor. Na hlasovom agentovi môžete nastaviť aj limity hovorov, napríklad max_call_duration_seconds a ring_duration_seconds. Pri odchádzajúcich hovoroch môžete nastaviť aj max_hold_seconds, aby ste obmedzili, ako dlho hlasový agent čaká v poradí pred ukončením hovoru. Hlasoví agenti Bolt podporujú aj audio_tier, endpointing a intelligence na riadenie spôsobu počúvania a odpovedania: intelligence je core alebo pro a audio_tier (Hearing) je lite, standard, plus alebo max (Max nie je všeobecne dostupný). Staršie hodnoty (lite a standard pre intelligence; lean, hearing a deep_hearing pre hearing) sú stále akceptované. Hlasoví agenti s plným duplexom zachovávajú rovnaký hlas vo všetkých podporovaných jazykoch, preto sa pri týchto hovoroch nepoužíva prepínanie hlasu podľa jazyka. Hlasoví agenti podporujú aj intro_clip a intro_ring_count na prehratie vopred nahranej úvodnej nahrávky a až dvoch zvonení predtým, než hlasový agent prehovorí. Noví hlasoví agenti potrebujú aj časové pásmo. Ak je váš hlasový agent viacjazyčný, môžete nastaviť language_switching na určenie, či sa má pred prepnutím jazykov opýtať, alebo sa má riadiť jazykom volajúceho. Na hlasovom agentovi môžete nastaviť aj words na riadenie toho, ako vyslovuje konkrétne výrazy a ktoré výrazy rozpoznáva. Všetky konfiguračné polia nájdete v časti Agenti; minimálne nastavenie je:

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

Uložte vrátené id — budete ho potrebovať v kroku 2.

2. Získajte telefónne číslo

Ak potrebujete iba číslo, na ktoré môžete volať, získajte číslo ThunderPhone z fondu ThunderPhone:

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

Odpoveď obsahuje id a number vo formáte E.164. Čísla ThunderPhone začínajú v stave status="provisioning" a do niekoľkých sekúnd sa stanú active — ak chcete sledovať zmenu, pravidelne volajte GET /v1/phone-numbers/{id}.

3. Priraďte agenta

Priraďte agenta z kroku 1 k prichádzajúcemu smeru čísla:

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

To je všetko — číslo je aktívne. Po schválení odchádzajúcich volaní pre vašu organizáciu môžete v rovnakom PATCH nastaviť aj outbound_agent_id. Dovtedy API toto priradenie odmietne s chybou 400.

Ak prichádzajúce hovory smerujete cez konfiguračný webhook namiesto pevne nastaveného inbound_agent_id, tento webhook teraz môže pre každý hovor vrátiť timezone spolu s agent_id a variables. Pri agentoch Bolt môžete pri zápisoch cez API na agentovi nastaviť aj audio_tier, endpointing a intelligence. API naďalej prijíma starší názov eagerness ako alias pre endpointing. Ak váš agent používa pripojenia API s trigger="call_start", ThunderPhone môže tieto nástroje spustiť raz na začiatku každého telefonického hovoru, pred pozdravom, s použitím ich uložených call_start_arguments.

Spätné volania na vaše odchádzajúce hovory

Keď niekto zavolá späť na číslo, ktoré mu volalo za posledných 30 dní, agent prijímajúci hovor dostane krátku kontextovú poznámku o danom hovore: kedy sa uskutočnil, ktorý agent ho vykonal a čo sa stalo (bez odpovede, hlasová schránka alebo konverzácia). Číslo bez agenta pre prichádzajúce hovory odošle rovnaké podrobnosti do vášho webhooku konfigurácie ako returning_call. Ak toto číslo nemá webhook alebo webhook vyprší, prípadne nie je dostupný, hovor sa namiesto ukončenia presmeruje na agenta, ktorý uskutočnil predchádzajúci hovor. ID volajúceho môže byť sfalšované, preto sa zhrnutie a premenné predchádzajúceho hovoru zdieľajú iba vtedy, ak správca zapne možnosť Zdieľať podrobnosti predchádzajúceho hovoru v časti Organizácia → Všeobecné → Spätné volania. Pozrite si Spätné volania.

4. Prijmite hovor

Zavolajte na číslo zo svojho telefónu. Agent hovor prijme, predstaví sa podľa vášho promptu a začne sa konverzácia.

Počas hovoru sa zobrazí v GET /v1/calls so stavom status="in_progress". Po skončení sa záznam aktualizuje o end_reason, duration_seconds, billable_minutes a (neskôr) adresu URL nahrávky a hodnotenie AI.

Prichádzajúce hovory sa započítavajú do limitu vašej organizácie pre súbežné hovory (predvolene 20 prebiehajúcich hovorov, zdieľaných s odchádzajúcimi, webovými a testovacími hovormi). Hovor, ktorý príde po dosiahnutí limitu, sa pred odpoveďou agenta odmietne a ukončí, neúčtuje sa a zaznamená sa ako neúspešný hovor s dôvodom ukončenia concurrent_call_limit_reached. Ak potrebujete vyšší limit, napíšte na support@thunderphone.com.

5. Skontrolujte výsledky

Načítajte zoznam nedávnych hovorov:

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

Získajte prepis:

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

A URL nahrávky (krátkodobo platné, podpísané):

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

Ak ste sa prihlásili na odber webhooku telephony.complete, dostanete rovnaké údaje prostredníctvom požiadavky POST na váš server — pozrite si call.complete.

Ak má váš agent nakonfigurované polia extrakcie, dátový obsah dokončeného hovoru môže obsahovať aj štruktúrované extrahované údaje. Súhrny hovorov sa zapisujú v jazyku, ktorý vaša organizácia používa v ThunderPhone, pokiaľ agent toto nastavenie neprepíše.


Ďalšie kroky