Zpracování příchozích hovorů (API)

Kompletní postup: nakonfigurujte agenta, přiřaďte ho k telefonnímu číslu, přijměte hovor a zkontrolujte přepis.

Základní postup „odpovědět na telefon pomocí AI“ z vašeho terminálu. Budete:

1. Vytvoříte agenta s promptem a hlasem.
2. Zřídíte (nebo přenesete) telefonní číslo a přiřadíte agenta jako jeho obsluhu příchozích hovorů.
3. Zavoláte na číslo. Zkontrolujete protokol hovoru, přepis a nahrávku.

Celkový počet volání API: čtyři. Celkový čas: méně než pět minut.

1. Vytvořte agenta#

Agent sdružuje prompt, hlas a produktovou úroveň, které budou řídit hovor. U agenta můžete také nastavit limity hovoru, například max_call_duration_seconds a ring_duration_seconds. Agenti podporují také intro_clip a intro_ring_count pro přehrání předem nahrané úvodní zprávy a až dvou zazvonění předtím, než agent promluví. Noví agenti také vyžadují časové pásmo. Všechna konfigurační pole najdete v části Agenti; minimum 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": "spark"
  }'

Uložte vrácené id — budete ho potřebovat v kroku 2.

2. Získejte telefonní číslo#

Pokud potřebujete pouze číslo, na které lze volat, získejte čí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"}'

Odpověď obsahuje id a number ve formátu E.164. Čísla ThunderPhone začínají se stavem status="provisioning" a během několika sekund se stanou active — pokud vás to zajímá, sledujte změnu pomocí GET /v1/phone-numbers/{id}.

3. Přiřaďte agenta#

Přiřaďte agenta z kroku 1 ke směru příchozích hovorů daného čí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še — číslo je aktivní. Po schválení odchozího volání pro vaši organizaci můžete ve stejném PATCH nastavit také outbound_agent_id. Do té doby API toto přiřazení odmítne s kódem 400.

Pokud příchozí hovory směrujete prostřednictvím konfiguračního webhooku namísto pevně nastaveného inbound_agent_id, může tento webhook nyní pro každý hovor vrátit timezone spolu s agent_id a variables.

4. Přijměte hovor#

Zavolejte na číslo ze svého telefonu. Agent hovor přijme, představí se podle vašeho promptu a konverzace začne.

Během probíhajícího hovoru se zobrazí v GET /v1/calls se stavem status="in_progress". Po skončení se záznam aktualizuje o end_reason, duration_seconds, billable_minutes a (nakonec) adresu URL nahrávky a hodnocení AI.

Příchozí hovory se započítávají do limitu vaší organizace pro souběžné hovory (ve výchozím nastavení 20 probíhajících hovorů, sdílených s odchozími, webovými a testovacími hovory). Hovor, který dorazí při dosažení limitu, je odmítnut předtím, než jej agent přijme, a je ukončen, není účtován a je zaznamenán jako neúspěšný hovor s důvodem ukončení concurrent_call_limit_reached. Pokud potřebujete vyšší limit, napište na support@thunderphone.com.

5. Zkontrolujte výsledky#

Načtěte seznam posledních hovorů:

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

Získejte přepis:

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

A adresu URL nahrávky (krátkodobě platnou, podepsanou):

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

Pokud jste se přihlásili k odběru webhooku telephony.complete, obdržíte stejná data jako požadavek POST na váš server — viz call.complete.

Pokud má váš agent nakonfigurovaná pole pro extrakci, může datová část dokončeného hovoru obsahovat také strukturovaná extrahovaná data.

Další kroky#