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#

Agent zahŕňa prompt, hlas a produktovú úroveň, ktoré budú riadiť hovor. V agentovi môžete nastaviť aj limity hovoru, napríklad max_call_duration_seconds a ring_duration_seconds. Agenti podporujú aj intro_clip a intro_ring_count na prehratie vopred nahranej úvodnej správy a až dvoch zazvonení predtým, než agent prehovorí. Noví agenti tiež potrebujú časové pásmo. Všetky konfiguračné polia nájdete v časti Agenti; minimálne je potrebné:

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

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ť hodnotu timezone spolu s agent_id a variables.

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 na extrakciu, údaje dokončeného hovoru môžu obsahovať aj štruktúrované extrahované údaje.

Ďalšie kroky#