Developer cookbook

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

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

Standardní postup „zvednout telefon pomocí AI“ přímo z vašeho terminálu. Budete:

1. Vytvořte agenta s promptem a hlasem.
2. Zřiďte (nebo přidejte vlastní) telefonní číslo a přiřaďte agenta jako jeho obsluhu příchozích hovorů.
3. Zavolejte na číslo. Zkontrolujte protokol hovoru, přepis a nahrávku.

Celkem 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. Všechny konfigurační parametry 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řiďte si ukázkové číslo 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. Ukázková čísla začínají se stavem status="provisioning" a během několika sekund se stanou active — pokud vás to zajímá, sledujte přechod dotazováním GET /v1/phone-numbers/{id}.

3. Přiřaďte agenta#

Přidružte agenta z kroku 1 k příchozímu směru čí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í. Ve stejném PATCH můžete také nastavit outbound_agent_id, aby bylo číslo připravené i pro odchozí hovory.

4. Přijměte hovor#

Vytočte čí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.

5. Zkontrolujte výsledky#

Načtěte seznam nedávný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átkodobou, 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 POST na váš server — viz call.complete.

Další kroky#