Soita lähteviä puheluita (API)

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

Soitatko kokonaiselle listalle? Hallintapaneelin Kampanjat -toiminto (/dashboard/campaigns) vastaanottaa CSV-tiedoston yhteystiedoista ja hoitaa aikavyöhykkeet huomioivat soittoajat, samanaikaisuuden ja uudelleenyrityskäytännön puolestasi. Tämä opas käsittelee yksittäisiä ohjelmallisia puheluita.

Vaatimukset

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.

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).

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

status: "initiated" tarkoittaa vain, että pyyntö hyväksyttiin — puhelua ei ole vielä yhdistetty. Tarkista GET /v1/calls/{call_id} reaaliaikaisen tilan varalta (in_progress → completed / failed).

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

Virhe	Korjaus
`402 Payment Required`	Lataa saldoa tai ota automaattinen saldon täydennys käyttöön
`403` lähtevät puhelut estetty (demonumero)	Ota sen sijaan käyttöön VoIP-numero
`403` lähtevät puhelut estetty (vahvistamaton VoIP)	Suorita `POST /v1/phone-numbers/{id}/verify-voip`
`404 from_number is not registered to this organization`	Varmista, että `from_number` vastaa omistamaasi puhelinnumeroa
`502 Bad Gateway`	Tilapäinen SIP- / LiveKit-virhe; uudelleenyritys on turvallinen

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

Lähtevien puhelujen viite

Kaikki pyyntökentät ja virhekoodit.

Vastaanota call.complete

Välitä valmistuneet lähtevät puhelut järjestelmääsi.

Laskutus

Automaattinen saldojen lisäys, jotta lähtevät puhelut eivät epäonnistu saldon vuoksi.

Testaa lähteviä agentteja

Tee lähtevästä agentistasi kuivaharjoitus ennen tuotantoa.

Getting Started

Using the dashboard

Connect tools & data

Analyze & improve

Team & account

Developer cookbook

Operations

Soita lähteviä puheluita (API)

Vaatimukset

Soita puhelu tallennetulla agentilla

Soita puhelu sisäisellä määrityksellä

Seuraa puhelua

Käsittelyn arvoiset virhetilanteet

Puhelun pidossaoloajan hallinta

Seuraavat vaiheet

Lähtevien puhelujen viite

Vastaanota call.complete

Laskutus

Testaa lähteviä agentteja

​Vaatimukset

​Soita puhelu tallennetulla agentilla

​Soita puhelu sisäisellä määrityksellä

​Seuraa puhelua

​Käsittelyn arvoiset virhetilanteet

​Puhelun pidossaoloajan hallinta

​Seuraavat vaiheet

Lähtevien puhelujen viite

Vastaanota call.complete

Laskutus

Testaa lähteviä agentteja

Vaatimukset

Soita puhelu tallennetulla agentilla

Soita puhelu sisäisellä määrityksellä

Seuraa puhelua

Käsittelyn arvoiset virhetilanteet

Puhelun pidossaoloajan hallinta

Seuraavat vaiheet