Developer cookbook

Soita lähteviä puheluita (API)

Käynnistä tekoälypohjainen lähtevä puhelu omasta koodistasi – kysely-, seuranta- tai vahvistustyönkulkuja varten.

Lähtevissä puheluissa voit antaa ThunderPhonelle kohdenumeron ja agentin määrityksen, jolloin tekoäly soittaa puhelun puolestasi. Tyypillisiä käyttötapauksia:

• Ajanvarausten vahvistukset
• Kyselyjen takaisinsoitot
• "Toinen yritys" -seurannat vastaamattoman puhelun jälkeen
• Välitystyyliset ilmoitukset

Vaatimukset#

1. Ota käyttöön VoIP-numero

   Lähtevät puhelut edellyttävät, että omistat from_number-numeron VoIP-yhteyden kautta. Demonumerot ovat vain saapuvia puheluita varten. Katso Käytä omia numeroitasi.

2. Luo agentti

   Lähteviin puheluihin suunnattu kehote alkaa yleensä siten, että agentti esittelee itsensä ja tarkoituksensa — "Hei, tässä Acme. Soitan vahvistaakseni huomisen klo 15 ajanvarauksesi…" Aseta outbound_speak_order arvoon agent_first (oletus).

3. Pidä saldo positiivisena

   Lähtevät puhelut palauttavat virheen 402 Payment Required, jos saldo on ≤ $0.00. Lataa saldoa käyttämällä POST /v1/billing/top-up tai ota käyttöön automaattinen saldon täydennys.

Soita puhelu tallennetulla agentilla#

Yksinkertaisin tapa on viitata agenttiin sen tunnuksella:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "agent_id":    12
  }'

Vastaus:

{ "call_id": 987654321, "status": "initiated" }

Soita puhelu sisäisellä määrityksellä#

Jos haluat kertaluonteisen kehotteen, jota ei kannata tallentaa agentiksi, välitä sen sijaan config. Sen rakenne vastaa call.incoming-webhookin vastausskeemaa:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Seuraa puhelua#

Tilaa samanaikaisesti telephony.complete-webhook — se on nopein tapa saada tieto puhelun päättymisestä. Jos et voi vastaanottaa saapuvia webhookeja, kysy GET /v1/calls/{call_id} muutaman sekunnin välein; tietue sisältää puhelun päätyttyä end_reason-, duration_seconds- ja tallenteen URL-osoitteen.

Käsittelyn arvoiset virhetilanteet#

Puhelun pidossaoloajan hallinta#

Lähtevät puhelut, jotka kestävät pitkään, koska vastaanottaja reagoi hitaasti (IVR-valikot, jonot), voidaan rajoittaa max_hold_seconds-asetuksella:

{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Agentti katkaisee puhelun, jos ihmisen ääntä ei ole vastaanotettu viimeisten N sekunnin aikana. Oletusarvo on 900 (15 minuuttia).

Seuraavat vaiheet#