Developer cookbook

Käsittele saapuvia puheluita (API)

Alusta loppuun: määritä agentti, liitä se puhelinnumeroon, vastaanota puhelu ja tarkista litterointi.

Tavanomainen ”vastaa puhelimeen tekoälyn avulla” -työnkulku päätelaitteeltasi. Sinä:

1. Luo agentti, jolla on kehote ja ääni.
2. Hanki (tai tuo) puhelinnumero ja määritä agentti sen saapuvien puhelujen käsittelijäksi.
3. Soita numeroon. Tarkastele puhelulokia, litterointia ja tallennetta.

API-kutsuja yhteensä: neljä. Kokonaisaika: alle viisi minuuttia.

1. Luo agentti#

Agentti yhdistää kehotteen, äänen ja tuotetason, jotka ohjaavat puhelua. Katso kaikki määrityskentät kohdasta Agentit; vähimmäismääritys on:

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

Tallenna palautettu id — tarvitset sitä vaiheessa 2.

2. Hanki puhelinnumero#

Jos tarvitset vain numeron, johon soittaa, hanki demonumero ThunderPhonen numerovarannosta:

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

Vastaus sisältää id:n ja number:n E.164-muodossa. Demonumerot alkavat tilassa status="provisioning" ja muuttuvat tilaan active muutamassa sekunnissa — voit seurata tilan vaihtumista kyselemällä GET /v1/phone-numbers/{id}, jos tarvitset sitä.

3. Määritä agentti#

Määritä vaiheessa 1 luotu agentti numeron saapuvien puhelujen käsittelijäksi:

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

Siinä kaikki — numero on käytössä. Voit myös määrittää outbound_agent_id:n samassa PATCH-pyynnössä, jolloin numero on valmis myös lähteviin puheluihin.

4. Vastaa puheluun#

Soita numeroon puhelimellasi. Agentti vastaa, esittelee itsensä kehotteesi mukaisesti, ja keskustelu alkaa.

Puhelun ollessa käynnissä se näkyy kohteessa GET /v1/calls tilalla status="in_progress". Kun puhelu päättyy, tietue päivittyy kentillä end_reason, duration_seconds, billable_minutes sekä (myöhemmin) tallenteen URL-osoitteella ja tekoälyarviolla.

5. Tarkista tulokset#

Hae viimeisimpien puheluiden luettelo:

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

Hae litterointi:

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

Ja tallenteen URL-osoite (lyhytkestoinen, allekirjoitettu):

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

Jos tilasit telephony.complete-webhookin, saat samat tiedot POST-pyyntönä palvelimellesi — katso call.complete.

Seuraavat vaiheet#