ThunderPhone v3 on julkaistu.Ota käyttöön itse – alkaen 2 ¢/min.Lue lisää julkistuksesta

Developer cookbook

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

Hallitse, mitä tapahtuu viimeisen hiljaisuuden tarkistuksen jälkeen

Voit välittää samat hiljaisuuden lopputoiminnon asetukset myös tallennettujen agenttien käyttämässä sisäisessä config-määrityksessä:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "silence_final_action": "hang_up"
  }
}

Valitse silence_final_action-asetuksella, mitä tapahtuu viimeisen hiljaisuuden tarkistuksen jälkeen. Voit välittää myös silence_final_message-asetuksen ja, kun lopputoiminto on siirto, silence_transfer_destination-asetuksen.

Lisää sanojen luettelo sisäiseen config-määritykseen

Sisäiset lähtevät puhelut voivat sisältää saman words-luettelon kuin tallennetut agentit. Käytä tätä, kun haluat puhelun noudattavan mukautettuja ääntämis- tai kuulemisen sääntöjä tallentamatta ensin agenttia.

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "prompt": "[REDACTED_LITERAL]",
    "voice": "john",
    "product": "spark",
    "words": []
  }
}

Seuraa puhelua

Vastaus, jossa on queued_at-aika, tarkoittaa, että ThunderPhonein lähtevien puhelujen kapasiteetti on käytössä: puhelu soitetaan, kun kapasiteettia vapautuu, 10 minuutin kuluessa, ja se päättyy end_reason-arvoon outbound_queue_timeout, jos kapasiteettia ei vapaudu. Sinun ei tarvitse yrittää uudelleen. Katso jonossa olevat puhelut.

Tilaa samanaikaisesti telephony.complete-webhook — se on nopein tapa saada tieto puhelun päättymisestä. Voit myös tilata call.status_changed-tapahtuman reaaliaikaisia tilapäivityksiä varten, kuten soitto, vastattu, vastaaja ja pidossa olon muutokset. Jos et voi vastaanottaa saapuvia webhookeja, kysely GET /v1/calls/{call_id} muutaman sekunnin välein; tietue sisältää end_reason-, duration_seconds- ja tallenteen URL-osoitteen puhelun päätyttyä.

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

VirheKorjaus
402 Payment RequiredTäydennä saldo tai ota automaattinen saldon lisäys käyttöön
400 with code: destination_not_allowedThunderPhone ei soita tähän numeroon: virheelliset numerot, hätänumerot, lisämaksulliset numerot, lyhytnumerot, pakotteiden alaiset maat tai Yhdysvaltain osavaltio, jonka organisaatiosi on estänyt lähteviltä puheluilta. ThunderPhone-numeroista voi soittaa vain tavallisiin yhdysvaltalaisiin ja kanadalaisiin numeroihin (ei lisämaksullisiin numeroihin). reason kertoo, mikä niistä on kyseessä; katso estetyt kohteet
409 with retryable: false for a ThunderPhone numberToimi code-arvon mukaan: pyydä lähtevien puheluiden käyttöoikeutta Puhelinnumerot-sivulla, odota keskeneräistä tarkistusta tai käytä toista kelpoista numeroa
429 with code: platform_outbound_daily_limit_reachedOrganisaatio on käyttänyt tämän päivän ThunderPhone-numeroista soitettavien lähtevien puheluiden kiintiön. Odota resets_at-aikaan (00:00 UTC), pyydä suurempaa rajaa Puhelinnumerot-sivulla tai soita oman VoIP-yhteytesi numerosta
429 with code: concurrent_call_limit_reachedOrganisaatiolla on käynnissä yhtä monta puhelua kuin sen samanaikaisten puheluiden raja sallii (oletusarvoisesti 20, mukaan lukien saapuvat, lähtevät, verkko- ja testipuhelut). Yritä uudelleen Retry-After-otsakkeen ilmoittaman sekuntimäärän kuluttua tai kun puhelu päättyy; lähetä sähköpostia osoitteeseen support@thunderphone.com rajan nostamiseksi
429 with code: outbound_queue_fullOrganisaatiolla on 50 jonossa olevaa puhelua odottamassa. Yritä uudelleen Retry-After-otsakkeen ilmoittaman sekuntimäärän kuluttua
429 with code: same_number_too_soonSoitit samaan to_number-numeroon alle 10 sekuntia sitten. Yritä uudelleen Retry-After-otsakkeen ilmoittaman sekuntimäärän kuluttua
409 with retryable: false for a customer VoIP numberKorjaa code-arvon nimeämä tila; suorita vahvistusvirheissä POST /v1/phone-numbers/{id}/verify-voip
409 idempotency conflictKäytä avainta uudelleen vain alkuperäisen normalisoidun pyynnön kanssa tai lähetä uusi avain
404 from_number is not registered to this organizationVarmista, että from_number vastaa organisaatiosi aktiivista puhelinnumeroa. Tämä vastaus palautuu myös, jos numero on jo käyttöönotossa, epäonnistunut, vapautettavana tai vapautettu
500 with only a detail fieldLähtevää trunk-yhteyttä ei ole määritetty. Ota yhteyttä tukeen; tämä ei ole numeron tilaan liittyvä ongelma, jonka voisit korjata
502 Bad GatewayTilapäinen SIP- / LiveKit-vika; uudelleenyritys on turvallinen

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

Pitkittyvät lähtevät puhelut, joissa vastaanottaja reagoi hitaasti (IVR-valikot, jonot), voidaan rajoittaa puhelukohtaisella max_hold_seconds-asetuksella tai määrittämällä se tallennetulle agentille:

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

Jos määrität max_hold_seconds-asetuksen sekä tallennetulle agentille että lähtevän puhelun pyynnölle, puhelukohtaista arvoa käytetään kyseisessä puhelussa.


Seuraavat vaiheet