Tee väljuvaid kõnesid (API)

Käivita oma koodist tehisintellektipõhine väljuv kõne — küsitluse, järeltegevuse või kinnituse töövood.

Väljaminevad kõned võimaldavad sul anda ThunderPhone'ile sihtnumbri ja agendi konfiguratsiooni ning lasta häälagendil sinu eest kõne teha. Tüüpilised kasutusjuhud:

• Kohtumiste kinnitused
• Küsitluste järelkõned
• „Teine katse” pärast vastamata kõnet
• Dispetšerilaadsed teavitused

Eeltingimused#

1. Vali väljaminevaid kõnesid toetav number

   Kasuta numbrit, mis kuulub sulle VoIP-ühenduse kaudu, või taotle luba kasutada oma ThunderPhone'i numbreid väljaminevateks kõnedeks lehel Phone Numbers. ThunderPhone'i numbrid on algselt ainult sissetulevate kõnede jaoks. ThunderPhone vaatab iga taotluse käsitsi üle; pärast heakskiitmist saavad need numbrid teha kõnesid kuni heakskiidetud päevase limiidini (lähtestatakse kell 00:00 UTC) ja käitada kampaaniaid ning saad taotleda suuremat limiiti. Kliendi VoIP-numbritel puudub päevane limiit, seega soovitame neid väljaminevateks kõnedeks. Vaata Kasuta oma numbreid.

2. Loo agent

   Väljaminevatele kõnedele kohandatud viip algab tavaliselt sellega, et agent tutvustab ennast ja oma eesmärki — „Tere, siin Acme, helistan, et kinnitada teie homset kohtumist kell 15…“ Määra outbound_speak_order väärtuseks agent_first (vaikeväärtus).

3. Hoia positiivset saldot

   Väljaminevad kõned tagastavad 402 Payment Required, kui saldo on ≤ $0.00. Lisa raha või luba automaatne saldo täiendamine juhtpaneelil jaotises Organisatsioon → Arvelduse seaded. Sinu sk_live_ võti saab kontrollida saldot päringuga GET /v1/billing, kuid ei saa saldot täiendada ega automaatset täiendamist muuta.

Tee kõne salvestatud agendiga#

Lihtsaim viis — viita agendile ID järgi:

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

Vastus:

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

Tee kõne sisseehitatud konfiguratsiooniga#

Kui soovid ühekordset viipa, mida ei tasu agendina salvestada, edasta selle asemel config. Selle struktuur vastab call.incoming veebikonksu vastuseskeemile:

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

Määra, mis juhtub pärast viimast vaikusekontrolli#

Saad edastada samad vaikuse lõpptegevuse seaded ka salvestatud agentide kasutatavas tekstisiseses config-is:

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

Kasuta silence_final_action, et valida, mis juhtub pärast viimast vaikusekontrolli. Saad edastada ka silence_final_message ning kui lõpptegevus on edastamine, siis silence_transfer_destination.

Lisa sõnaloend tekstisisesele config-ile#

Tekstisisesed väljaminevad kõned võivad sisaldada sama words-i loendit nagu salvestatud agendid. Kasuta seda, kui soovid, et kõne järgiks kohandatud hääldus- või kuulmisreegleid, ilma agenti eelnevalt salvestamata.

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

Jälgi kõnet#

Vastus, mis sisaldab aega queued_at, tähendab, et ThunderPhone'i väljaminevate kõnede maht on kasutusel: kõne valitakse, kui ruumi vabaneb, 10 minuti jooksul, ning kui ruumi ei teki, lõpeb see väärtusega end_reason outbound_queue_timeout. Sa ei pea uuesti proovima. Vaata järjekorras olevaid kõnesid.

Telli paralleelselt telephony.complete veebikonksu — see on kiireim viis teada saada, et kõne on lõppenud. Kui sa ei saa sissetulevaid veebikonkse vastu võtta, päri GET /v1/calls/{call_id} iga paari sekundi järel; kirje sisaldab pärast kõne lõppu väärtusi end_reason, duration_seconds ja salvestise URL-i.

Kui sinu agent on seadistatud pärast kõnet struktureeritud andmeid eraldama, edastatakse need andmed eraldi pärast lõplikku kinnitamist.

Edasta kõnepõhiseid muutujaid salvestatud agendile#

Salvestatud agendid saavad viibatekstis kasutada kohatäiteid nagu {{name}} või {{name|there}}. Kui teed agent_id abil väljuva kõne, edasta selle kõne väärtustega variables:

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

Kasuta kohatäite nimega seotud stringväärtusi. Need muutujad kehtivad salvestatud agentidele; selle juhendi tekstisisene config-i näide neid ei kasuta.

Tõrkerežiimid, mida tasub käsitleda#

Täieliku stabiilsete sobivuskoodide loendi ja mõlema 409 vastusekuju jaoks vaata väljuvate kõnede viidet. Kui aktiivne number muutub sobimatuks pärast päringu vastuvõtmist, kuid enne kõne tegemist, tagastab lõplik kontroll mitteuuesti proovitava 409-i vastusekoormuse.

Ooteaja juhtimine#

Väljuvaid kõnesid, mis venivad pikaks, kuna kõne vastuvõtja reageerib aeglaselt (IVR-i menüüpuud, järjekorrad), saab piirata kõne max_hold_seconds-i väärtusega või määrates selle salvestatud häälagendile:

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

Agent lõpetab kõne, kui viimase N sekundi jooksul pole inimese häält vastu võetud. Vaikeväärtus on 900 sekundit (15 minutit).

Kui määrad max_hold_seconds-i nii salvestatud häälagendil kui ka väljuva kõne päringus, kasutatakse selle kõne jaoks kõnepõhist väärtust.

Järgmised sammud#