Soita lähteviä puheluita (API)

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

Lähtevien puheluiden avulla voit antaa kohdenumeron ja agentin määrityksen ThunderPhonelle ja antaa tekoälyn soittaa puhelun puolestasi. Tyypillisiä käyttötapauksia:

• Tapaamisvahvistukset
• Kyselyjen takaisinsoitot
• Toisen yrityksen seurannat vastaamattoman puhelun jälkeen
• Lähetysluonteiset ilmoitukset

Vaatimukset#

1. Valitse ulospäin soittamiseen sallittu numero

   Käytä numeroa, jonka omistat VoIP-yhteyden kautta, tai pyydä lupaa käyttää ThunderPhone-numeroitasi ulospäin soittamiseen Phone Numbers -sivulla. ThunderPhone-numerot ovat aluksi vain saapuvia puheluita varten. ThunderPhone tarkistaa jokaisen pyynnön manuaalisesti; hyväksynnän jälkeen näillä numeroilla voi soittaa puheluita hyväksyttyyn päivittäiseen enimmäismäärään asti (nollautuu klo 00:00 UTC) ja suorittaa kampanjoita, ja voit pyytää suurempaa rajaa. Asiakkaan VoIP-numeroilla ei ole päivittäistä rajaa, joten suosittelemme niitä ulospäin soittamiseen. Katso Käytä omia numeroitasi.

2. Luo agentti

   Ulospäin soittamiseen suunnattu kehote alkaa yleensä siten, että agentti kertoo, kuka se on ja mikä on puhelun tarkoitus — "Hei, täällä Acme. Soitan vahvistaakseni huomisen tapaamisesi klo 15…" Aseta outbound_speak_order arvoon agent_first (oletusarvo).

3. Pidä saldo positiivisena

   Ulospäin soitetut puhelut palauttavat virheen 402 Payment Required, jos saldo on ≤ $0.00. Lisää saldoa tai ota automaattinen saldon lisäys käyttöön hallintapaneelin kohdassa Organisaatio → Laskutusasetukset. sk_live_-avaimesi voi tarkistaa saldon pyynnöllä GET /v1/billing, mutta sillä ei voi lisätä saldoa tai muuttaa automaattista saldon lisäystä.

Soita puhelu tallennetulla agentilla#

Yksinkertaisin tapa on viitata agenttiin 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":   "+14155552671",
    "agent_id":    12
  }'

Vastaus:

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

Soita puhelu upotetulla 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":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Seuraa puhelua#

Tilaa samanaikaisesti telephony.complete-webhook — nopein tapa tietää, että puhelu on päättynyt. Jos et voi vastaanottaa saapuvia webhookeja, kyselyllä GET /v1/calls/{call_id} muutaman sekunnin välein; tietue sisältää end_reason-, duration_seconds- ja tallenne-URL:n, kun puhelu päättyy.

Jos agenttisi on määritetty poimimaan jäsenneltyä dataa puhelun jälkeen, data toimitetaan erikseen viimeistelyn valmistuttua.

Välitä puhelukohtaisia muuttujia tallennetulle agentille#

Tallennetut agentit voivat käyttää kehotetekstissä paikkamerkkejä, kuten {{name}} tai {{name|there}}. Kun soitat lähtevän puhelun käyttäen agent_id:tä, välitä variables, joissa ovat kyseisen puhelun arvot:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Käytä merkkijonoarvoja, joiden avaimena on paikkamerkin nimi. Nämä muuttujat koskevat tallennettuja agentteja; tämän oppaan upotettu config-esimerkki ei käytä niitä.

Käsittelyn arvoiset virhetilat#

Katso lähtevien puhelujen viite täydellisestä pysyvien kelpoisuuskoodien luettelosta ja molemmista 409-vastausmuodoista. Jos aktiivinen numero muuttuu kelpaamattomaksi pyynnön hyväksymisen jälkeen mutta ennen puhelun soittamista, lopullinen tarkistus palauttaa uudelleenyritykseen kelpaamattoman 409-vastauksen.

Pitoajan hallinta#

Lähtevien puhelujen kestoa voidaan rajoittaa, jos vastaanottaja vastaa hitaasti (IVR-valikot, jonot), käyttämällä max_hold_seconds-asetusta:

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

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

Seuraavat vaiheet#