ThunderPhone v3 jau veikia.Viską atlikite savarankiškai – nuo 2 ct/min.Skaityti pranešimą

Developer cookbook

Vykdykite išeinančius skambučius (API)

Iš savo kodo inicijuokite DI valdomą išeinantį skambutį – apklausos, tolesnio susisiekimo ar patvirtinimo scenarijams.

Skambinimas į išorę leidžia perduoti paskirties numerį ir agento konfigūraciją ThunderPhone, kad DI atliktų skambutį jūsų vardu. Įprasti naudojimo atvejai:

  • Vizitų patvirtinimai
  • Pakartotiniai skambučiai apklausoms
  • Pakartotiniai bandymai po praleisto skambučio
  • Pranešimai pagal dispečerinį modelį

Būtinosios sąlygos

  1. Pasirinkite numerį, įgalintą skambučiams į išorę

    Naudokite numerį, kurį turite per VoIP ryšį, arba paprašykite leidimo naudoti savo ThunderPhone numerius skambučiams į išorę puslapyje Phone Numbers. ThunderPhone numeriai iš pradžių skirti tik įeinantiems skambučiams. ThunderPhone kiekvieną užklausą peržiūri rankiniu būdu; ją patvirtinus, šiais numeriais galima skambinti iki patvirtinto dienos limito (jis atnaujinamas 00:00 UTC) ir vykdyti kampanijas, o jūs galite prašyti didesnio limito. Klientų VoIP numeriams dienos limitas netaikomas, todėl rekomenduojame juos naudoti skambučiams į išorę. Žr. Naudokite savo numerius.

  2. Sukurkite agentą

    Skambučiams į išorę pritaikytas raginimas paprastai prasideda tuo, kad agentas prisistato ir nurodo savo paskirtį — „Sveiki, čia Acme, skambiname patvirtinti jūsų rytdienos susitikimą 15 val.…“ Nustatykite outbound_speak_order į agent_first (numatytoji reikšmė).

  3. Palaikykite teigiamą balansą

    Skambinant į išorę grąžinamas 402 Payment Required, jei balansas yra ≤ $0.00. Papildykite balansą arba įjunkite automatinį papildymą skydelio Organizacija → Atsiskaitymo nustatymai skiltyje. Jūsų sk_live_ raktas gali patikrinti balansą naudodamas GET /v1/billing, tačiau negali papildyti balanso ar keisti automatinio papildymo nustatymų.

Atlikite skambutį naudodami išsaugotą agentą

Paprasčiausias būdas — nurodyti agentą pagal id:

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

Atsakymas:

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

Atlikite skambutį su įterptine konfigūracija

Jei norite vienkartinio raginimo, kurio neverta išsaugoti kaip agento, vietoje to perduokite config. Struktūra atitinka call.incoming saityno kablio atsakymo schemą:

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

Valdykite, kas vyksta po paskutinio tylos patikrinimo

Taip pat galite perduoti tuos pačius tylos galutinio veiksmo nustatymus tiesioginiame config, kurį naudoja išsaugoti agentai:

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

Naudokite silence_final_action, kad pasirinktumėte, kas vyks po paskutinio tylos patikrinimo. Taip pat galite perduoti silence_final_message, o kai galutinis veiksmas yra peradresavimas – silence_transfer_destination.

Pridėkite žodžių sąrašą prie tiesioginio config

Tiesioginiuose išeinančiuose skambučiuose gali būti tas pats words sąrašas kaip ir išsaugotuose agentuose. Naudokite tai, kai norite, kad skambutyje būtų laikomasi pasirinktinių tarimo ar atpažinimo taisyklių, prieš tai neišsaugant agento.

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

Sekite skambutį

Atsakymas su queued_at laiku reiškia, kad ThunderPhone siunčiamų skambučių pajėgumas yra naudojamas: skambutis surenkamas, kai atsiranda vietos, per 10 minučių, ir baigiasi su end_reason outbound_queue_timeout, jei vietos neatsiranda. Jums nereikia bandyti dar kartą. Žr. skambučiai eilėje.

Tuo pat metu užsiprenumeruokite telephony.complete žiniatinklio kablį — tai greičiausias būdas sužinoti, kada skambutis baigtas. Taip pat galite užsiprenumeruoti call.status_changed, kad gautumėte tiesioginius eigos atnaujinimus, pvz., rinkimo, atsiliepimo, balso pašto ir sulaikymo būsenų pakeitimus. Jei negalite priimti įeinančių žiniatinklio kablių, kas kelias sekundes tikrinkite GET /v1/calls/{call_id}; įraše pateikiami end_reason, duration_seconds ir įrašo URL, kai skambutis baigiasi.

Jei jūsų agentas nustatytas išskirti struktūrinius duomenis po skambučio, šie duomenys pateikiami atskirai, kai užbaigimas baigiamas.

Perduokite kiekvieno skambučio kintamuosius išsaugotam agentui

Išsaugoti agentai raginimo tekste gali naudoti vietos rezervavimo ženklus, pvz., {{name}} arba {{name|there}}. Kai inicijuojate išeinantį skambutį su agent_id, perduokite variables su to skambučio reikšmėmis:

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

Naudokite eilutės reikšmes, kurių raktai atitinka vietos rezervavimo ženklo pavadinimą. Šie kintamieji taikomi išsaugotiems agentams; šio vadovo įterptiniame config pavyzdyje jie nenaudojami.

Klaidų scenarijai, kuriuos verta apdoroti

KlaidaSprendimas
402 Payment RequiredPapildykite balansą arba įjunkite automatinį papildymą
400 su code: destination_not_allowedThunderPhone neskambina šiuo numeriu: neteisingais numeriais, skubiosios pagalbos numeriais, padidinto tarifo numeriais, trumpaisiais kodais, sankcionuotomis šalimis arba JAV valstija, kuriai jūsų organizacija užblokavo išeinančius skambučius. Iš ThunderPhone numerių leidžiama skambinti į įprastus JAV ir Kanados numerius, taip pat į kai kurias tarptautines paskirties vietas, kurioms taikomas paskirties vietos tarifas. reason nurodo, kuris atvejis taikomas; žr. blokuojamos paskirties vietos
409 su retryable: false, skirtas ThunderPhone numeriuiVadovaukitės code nurodymu: Telefono numerių puslapyje pateikite prašymą dėl išeinančių skambučių, palaukite vykdomos peržiūros arba naudokite kitą tinkamą numerį
429 su code: platform_outbound_daily_limit_reachedOrganizacija išnaudojo šiandienos išeinančių skambučių iš ThunderPhone numerių limitą. Palaukite resets_at (00:00 UTC), Telefono numerių puslapyje paprašykite didesnio limito arba skambinkite iš numerio, prijungto prie jūsų VoIP ryšio
429 su code: concurrent_call_limit_reachedOrganizacijoje vyksta tiek skambučių, kiek leidžia jos vienalaikių skambučių limitas (pagal numatytuosius nustatymus 20, įskaitant įeinančius, išeinančius, žiniatinklio ir bandomuosius skambučius). Bandykite dar kartą praėjus Retry-After antraštėje nurodytam sekundžių skaičiui arba pasibaigus skambučiui; norėdami padidinti limitą, rašykite support@thunderphone.com
429 su code: outbound_queue_fullOrganizacijoje laukia 50 eilėje esančių skambučių. Bandykite dar kartą praėjus Retry-After antraštėje nurodytam sekundžių skaičiui
429 su code: same_number_too_soonĮ tą patį to_number skambinote mažiau nei prieš 10 sekundžių. Bandykite dar kartą praėjus Retry-After antraštėje nurodytam sekundžių skaičiui
409 su retryable: false, skirtas kliento VoIP numeriuiIštaisykite code nurodytą būseną; jei nepavyko patvirtinimas, vykdykite POST /v1/phone-numbers/{id}/verify-voip
409 idempotentiškumo konfliktasPakartotinai naudokite raktą tik su pradine normalizuota užklausa arba siųskite naują raktą
404 from_number is not registered to this organizationPatvirtinkite, kad from_number atitinka aktyvų telefono numerį jūsų organizacijoje. Šis atsakymas taip pat grąžinamas, jei numeris jau parengiamas, jo parengimas nepavyko, jis atlaisvinamas arba jau atlaisvintas
500 tik su detail laukuNesukonfigūruota išeinančių skambučių magistralė. Susisiekite su palaikymo komanda; tai nėra numerio būsenos problema, kurią galite ištaisyti
502 Bad GatewayLaikinas SIP / LiveKit sutrikimas; saugu bandyti dar kartą

Visą nekintantį tinkamumo kodų sąrašą ir abi 409 atsakymo formas rasite išeinančių skambučių nuorodoje. Jei aktyvus numeris tampa netinkamas po to, kai užklausa priimama, bet prieš inicijuojant skambutį, galutinis patikrinimas grąžina nekartotiną 409 naudingąjį krūvį.

Laukimo laiko valdymas

Ilgai trunkantys išeinantys skambučiai, kai skambinamas asmuo lėtai atsako (IVR medžiai, eilės), gali būti apriboti nustatant max_hold_seconds skambučiui arba išsaugotam agentui:

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

Agentas nutraukia skambutį, jei per pastarąsias N sekundžių nebuvo gauta žmogaus balso. Numatytoji reikšmė yra 900 sekundžių (15 minučių).

Jei max_hold_seconds nustatote ir išsaugotam agentui, ir išeinančio skambučio užklausoje, tam skambučiui naudojama vieno skambučio reikšmė.


Tolesni veiksmai