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

Webhooks

telephony.incoming / web.incoming

Blokuojanti žiniatinklio užklausa, realiuoju laiku nustatanti įeinančio skambučio konfigūraciją.

Kai įeinantis telefono skambutis pasiekia numerį be priskirto agento (skambinantiesiems, perskambinantiems į jūsų išeinančius skambučius, žr. Atgaliniai skambučiai), arba žiniatinklio valdiklio sesija pradedama naudojant viešinimo raktą mode="webhook" režimu, ThunderPhone siunčia blokuojančią telephony.incoming / web.incoming užklausą į jūsų senąjį webhook URL ir laukia konfigūracijos atsakymo: telefono skambučiui – iki 13 sekundžių, įskaitant vieną pakartotinį bandymą, o valdiklio sesijai – iki 10 sekundžių (žr. Laiko limitai ir pakartotiniai bandymai). Naudokite šį apsikeitimą, kad dinamiškai pasirinktumėte raginimą, balsą ir įrankius kiekvienam skambučiui – visą procesą žr. dinaminės skambučio konfigūracijos vadove.

Numeris, kuriam priskirtas agentas, atsiliepia naudodamas tą agentą. Kai agentas turi savo skambučio nustatymo žiniatinklio kablį, tas pats blokuojantis apsikeitimas pirmiausia vykdomas agento URL adresu, kad būtų užpildyti agento kintamieji ir skambučio kontekstas.

Laiko limitai ir pakartotiniai bandymai

Atsakykite greitai: skambinantysis laukia linijoje, kol priimate sprendimą.

Telefono skambučiui (telephony.incoming):

  • Pirmasis bandymas gali trukti iki 10 sekundžių.
  • Jei viršijamas laiko limitas, nepavyksta prisijungti arba gaunamas 5xx, 408 ar 429 atsakymas, ThunderPhone bando dar kartą. Pakartotiniam bandymui skiriama tai, kas lieka iš 13 sekundžių biudžeto visam apsikeitimui: apie 3 sekundes po pirmojo bandymo, kuriam baigėsi laikas, ir beveik visos 13 sekundžių po greitos nesėkmės. Pakartotinis bandymas neatliekamas, jei liktų mažiau nei 2 sekundės.
  • Bet kuris kitas 4xx atsakymas, atsakymas, viršijantis dydžio limitą, arba 2xx, kurio turinys nėra tinkama konfigūracija, yra galutinis ir nebandomas pakartotinai.
  • Abu bandymai siunčia tą patį turinį, tą pačią X-ThunderPhone-Signature ir tą pačią X-ThunderPhone-Idempotency-Key antraštę (telephony-incoming-<call_id>), todėl apdorojimo programa, sukelianti šalutinį poveikį, gali atpažinti pakartotinį bandymą.

Jei negaunama tinkama naudoti konfigūracija, skambutis iš karto nutraukiamas, užuot palikus skambintoją tyloje. Skambučių istorijoje jis rodomas kaip nepavykęs, neapmokestinamas skambutis su end_reason inbound_config_webhook_failed, taip pat išsiunčiamas įprastas telephony.complete įvykis. Skambučio puslapyje valdymo skydelyje ir config_webhook_failure lauke GET /v1/calls/{call_id} nurodoma, kaip veikė jūsų žiniatinklio kabliukas: {kind, attempts, http_status, host, source}, kur kind yra http_error, timeout, connection, dns, tls, response_too_large, blocked_url, other, invalid_json, non_object_json arba invalid_config, host yra jūsų žiniatinklio kabliuko pagrindinio kompiuterio pavadinimas, o source yra number (šis žiniatinklio kabliukas) arba agent_setup (balso agento skambučio nustatymo žiniatinklio kabliukas). Kai naudojama invalid_config, reason nurodo, kodėl atsakymo nepavyko naudoti, o fields nurodo susijusius laukus: no_agent (nėra nei agent_id, nei prompt; fields išvardija ignoruotus raktus, pavyzdžiui, neteisingai parašytą agentId), agent_not_found, agent_id_not_integer, unexpected_fields (raktai, esantys šalia agent_id ir nesantys variables, context, timezone ar language), invalid_variables, invalid_context, invalid_language, unsupported_language, invalid_config_fields arba agent_settings_invalid. Kitu atveju reason yra null, o fields yra tuščias. Vienintelė išimtis yra skambintojas, perskambinantis į vieną iš jūsų išeinančių skambučių, kai nepavyko pats apsikeitimas: žr. Atgaliniai skambučiai.

Valdiklio seansui (web.incoming) atliekamas vienas bandymas, trunkantis iki 10 sekundžių. Jei jis nepavyksta, seanso užklausa nepavyksta su 502 arba 422.

Užklausos duomenys

Telefono skambučiams (telephony.incoming):

{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567"
  }
}
LaukasTipasAprašymas
call_idsveikasis skaičiusSkambučio ID — nekinta visuose šio skambučio įvykiuose
from_numbereilutėSkambintojo E.164 numeris
to_numbereilutėE.164 paskirties numeris (vienas iš jūsų ThunderPhone numerių)
returning_callobjektasPateikiamas tik tada, kai šis numeris per pastarąsias 30 dienų skambino skambintojui. Žr. Atgaliniai skambučiai
sip_headersobjektasPateikiamas tik tada, kai skambutis gautas per rankiniu būdu sukurtą SIP ryšį su X-* arba User-to-User SIP antraštėmis: antraštės pavadinimas mažosiomis raidėmis → reikšmė. Žr. SIP antraštės

Žiniatinklio valdiklio sesijoms (web.incoming) data identifikuoja įterpimo puslapį, o ne telefono numerius:

{
  "type": "web.incoming",
  "data": {
    "call_id": 987654322,
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2"
  }
}
FieldTypeDescription
call_idintegerSkambučio ID
origin_domainstringPuslapio, kuriame talpinamas valdiklis, kilmė, kurią pateikė naršyklė. Ne naršyklės klientas gali siųsti bet kokią reikšmę, todėl nelaikykite jos įrodymu, iš kur atkeliavo užklausa
publishable_key_prefixstringPirmieji viešinamo rakto, kuriuo atidaryta sesija, simboliai
language, primary_languagestringYra, kai valdiklio sesija paprašė pakeisti kalbą
voicestringYra, kai valdiklio sesija paprašė pakeisti balsą
website_contextstringYra, kai valdiklis perdavė konkrečios sesijos puslapio kontekstą

Pakeitimo laukai (language, voice, website_context ir bet kokie naršyklės variables) pateikiami tik tada, kai viešinamasis raktas leidžia juos naudoti savo naršyklės pakeitimuose. Sesijos užklausa, kurioje pateiktas raktui neleidžiamas laukas, atmetama prieš iškviečiant šį webhook.


Atsakymo schema

Grąžinkite JSON objektą, aprašantį šio skambučio agento konfigūraciją. prompt ir voice yra privalomi; visa kita yra pasirinktinė.

{
  "prompt":  "You are a helpful booking assistant for Acme Restaurant.",
  "voice":   "john",
  "product": "spark",
  "background_track": null,
  "tools":   []
}
LaukasTipasPrivalomasAprašas
prompteilutėtaipSistemos raginimas, kuriuo vadovaujasi agentas
voiceeilutėtaipBalso ID iš GET /v1/voices, pvz., john. voice_name priimamas kaip alternatyvus pavadinimas. Nežinomi balsai nepraeina tikrinimo ir užklausa atmetama
producteilutėneSiųskite bolt. Numatytoji reikšmė yra spark – senesnė reikšmė, kuri vis dar priimama kartu su storm-base, storm-base-with-ack, storm-extra ir storm-extra-with-ack
thinking_leveleilutėneminimal, base (numatytoji reikšmė) arba extra. Naudojant senesnes storm-* produkto reikšmes, storm-extra* priverstinai nustato extra, o kitos storm-* nustato base
audio_context_modeeilutėnefull (numatytoji reikšmė) arba reduced
watchdog_enabledloginė reikšmėneĮjunkite šio skambučio priežiūrą. Numatytoji reikšmė – false
additional_audio_contextloginė reikšmė | nullneĮtraukite kelis paskutinius skambinančiojo garso posūkius, o ne tik naujausią posūkį – taip pagerinami pataisymai ir duomenų, kuriuose daug raidžių ar skaičių, rinkimas, šiek tiek padidinant delsą ir kainą. Numatytoji reikšmė įjungta įeinamosioms sesijoms ir išjungta išeinamiems telefono skambučiams; null išlaiko numatytąją reikšmę
storm_feedback_modeeilutėnenone, acknowledgement (numatytoji reikšmė) arba tick: ką skambinantysis girdi, kol rengiama lėtesnė atsakymo versija, kai audio_tier yra plus arba max
languageeilutėneTrumpinys, skirtas primary_language. Taip pat leidžiama šalia agent_id; tuomet tai yra kalba, kuria pradedamas šis skambutis ir kuria kalba tam skirtas agento balsas; žr. Nustatykite kalbą kiekvienam skambučiui
primary_languageeilutėneKalbos kodas, normalizuotas (numatytoji reikšmė – en). Neišsprendžiami kodai atmeta skambutį
has_additional_languagesloginė reikšmėneNumatytoji reikšmė – false
additional_languageseilučių masyvasnePapildomos kalbos, į kurias agentas gali persijungti
native_voice_switchingloginė reikšmėneNumatytoji reikšmė – false. Skambučiui persijungus į kitą kalbą, vietoje sukonfigūruoto balso naudojamas tai kalbai gimtakalbis balsas, suderintas pagal lytį
language_switchingeilutė | nullneask_first (numatytoji reikšmė) arba follow_caller; null yra tas pats, kas ask_first. Nurodo, kaip daugiakalbis agentas reaguoja, kai kitas asmuo kalba kita jo kalba. ask_first iš karto persijungia, kai asmuo paprašo kalbos arba ja pasako visą sakinį, o po trumpo pasakymo, pavyzdžiui, „sí“, paklausia, ar tęsti ta kalba. follow_caller persijungia į bet kurią sukonfigūruotą kalbą, kuria asmuo kalba, net jei ištariamas tik vienas žodis. Taikoma tik nustačius additional_languages
audio_tiereilutė | nullneTik product: "bolt". Klausymas: kaip atidžiai agentas girdi skambinantįjį. standard (numatytoji reikšmė; "" ir null reiškia tą patį) tinka daugumai skambučių (skambučiuose, kuriuose tvarkomi PHI, naudojami tik BAA aprėpti teikėjai). lite yra pigiausias ir dažniau neteisingai išgirsta. plus atidžiau klausosi sudėtingų posūkių, kurie užtrunka maždaug 1–2 sekundėmis ilgiau. max skirtas sudėtingiausiam garsui ir retoms kalboms; kiekvienas atsakymas užtrunka 3–4 sekundes, o skambutyje naudojamas pro intelektas (intelligence ignoruojamas). max paprastai nepasiekiamas: organizacijai, kuriai jis neįjungtas, skambutyje naudojamas plus ir jūsų nurodytas intelligence (išeinančio skambučio užklausa su juo atmetama grąžinant 400). Senesnės reikšmės lean (Lite), hearing (Plus) ir deep_hearing (Max) vis dar priimamos. Kiti produktai tai ignoruoja
endpointingeilutė | nullnefaster (200 ms), fast (300 ms), normal (500 ms, numatytoji reikšmė) arba patient (800 ms); null yra tas pats, kas normal. Nurodo, kiek laiko Bolt v2 agentas laukia skambinančiajam nutilus, prieš prašydamas modelio atsakymo. Trumpesnis laukimas gali leisti atsakyti greičiau, tačiau siunčia daugiau užklausų, kurias vėlesni skambinančiojo žodžiai padaro nebeaktualias, todėl padidėja modelio kaina. Kiti produktai tai ignoruoja
eagernesseilutė | nullneNebenaudojama: iki 2026 m. spalio 19 d. naudotas endpointing pavadinimas, vis dar nuskaitomas. Ignoruojamas, kai nustatytas endpointing
intelligenceeilutė | nullnecore arba pro (numatytoji reikšmė); null yra tas pats, kas pro. Nurodo, kaip patikimai bolt agentas Bolt v2 sistemoje laikosi instrukcijų. core iki pirmojo žodžio užtrunka apie 700 ms, yra pigiausias ir šiek tiek mažiau patikimas (skambučiuose, laikomuose PHI, apie 900 ms ir mažiau patikimas); pro užtrunka apie 900 ms; Core atsakymai, kurie tik iškviestų įrankį, perduodami Pro. Senesnės reikšmės lite (Core) ir standard (Pro) vis dar priimamos, o nebevartojamos plus ir max veikia su pro. Ignoruojamas, kai audio_tier yra max. Kiti produktai tai ignoruoja
faster_repliesloginė reikšmė | nullneGreičio padidinimas. Numatytoji reikšmė – true. Bolt v2 sistemoje veikiančiam bolt agentui atsakymai pradedami šiek tiek greičiau, už šiek tiek didesnę kainą. false tai išjungia. Kiti produktai tai ignoruoja
background_trackeilutė | nullneAplinkos garso ID arba null
acknowledgement_prompt_modeeilutėneauto (numatytoji reikšmė) arba manual (senesnėms -with-ack produkto reikšmėms)
acknowledgement_prompteilutėneNaudojama, kai acknowledgement_prompt_mode="manual"
silence_interval_secondssveikasis skaičius | nullne5–120. Skambinančiojo tylos sekundės prieš patikrinimą
silence_max_checkinssveikasis skaičius | nullne1–10
silence_checkins_enabledloginė reikšmėneNumatytoji reikšmė – true
silence_final_actioneilutėnePo paskutinio patikrinimo: hang_up (numatytoji reikšmė) arba transfer į silence_transfer_destination
silence_transfer_destinationeilutėneŠios konfigūracijos transfer_destinations įrašo pavadinimas; būtinas naudojant transfer. Be transfer_destinations perdavimas negali būti atliktas ir agentas nutraukia skambutį
silence_final_messageeilutėne≤ 300 simbolių, perskaitoma taip, kaip parašyta; "" (numatytoji reikšmė) naudoja numatytąją frazę
connect_tone_enabledloginė reikšmėneNumatytoji reikšmė – false
pronunciation_dictsloginė reikšmė | nullneNumatytoji reikšmė – false; null yra tas pats, kas false. Kai nustatyta true, skambučio Cartesia kalba naudoja ThunderPhone tarimo žodyną skambučio kalbai, jei jis yra. Veikia telefono ir valdiklio skambučiams. Taikoma tik ThunderPhone nuosaviems Cartesia balsams, o ne balsams, naudojantiems jūsų Cartesia API raktą. Nenaudojama su agent_id, kuriam taikomi išsaugoto agento nustatymai
wordsmasyvas | nullneKaip agentas taria konkrečius žodžius – tie patys įrašai kaip agento words, tik be support. Įrašas be language naudoja šios konfigūracijos kalbą. null ir [] reiškia, kad jų nėra. Nenaudojama su agent_id, kuriam taikomi išsaugoto agento žodžiai
voicemail_actioneilutėneprompt (numatytoji reikšmė), hangup arba message
voicemail_messageeilutėneNaudojama, kai voicemail_action="message"
agent_nameeilutėneRodomas pavadinimas, pateikiamas valdymo skydeliuose ir valdiklyje
org_nameeilutėneOrganizacijos rodomas pavadinimas agento personai
toolsmasyvasneĮterptos funkcijų įrankių schemos (žr. Funkcijų įrankiai)
transfer_destinationsobjektų masyvas | nullneIki 50 {name, number} įrašų, į kuriuos šis skambutis gali būti perduotas; jie tikrinami kaip agento perdavimo numeriai. Agentas perduoda pagal pavadinimą ir tik į šiuos įrašus; [] reiškia, kad perdavimų nėra. Praleiskite šį lauką arba siųskite null, kad agentas galėtų perduoti į savo pasirinktą numerį
timezoneeilutėneŠio skambučio IANA laiko juosta, pvz., America/Chicago. Agentas joje nurodo datą ir laiką, pirmenybę teikdamas jai, o ne savo laiko juostai. Taip pat leidžiama šalia agent_id. Reikšmės, kurios nėra IANA zonos, ignoruojamos. Žr. Nustatykite laiko juostą kiekvienam skambučiui
contexteilutė | nullneLaisvos formos tekstas šiam skambučiui, pvz., jūsų sistemos surinktos pastabos, iki 20 000 simbolių. Pridedamas po raginimo atskirtame bloke ir neatvaizduojamas kaip šablonas. Taip pat leidžiama šalia agent_id. Reikšmė, kuri nėra eilutė arba yra ilgesnė, atmeta skambutį. Žr. skambučio kintamieji ir kontekstas
call_idsveikasis skaičiusnePasirinktinis užklausos skambučio ID pakartojimas; ignoruojamas

Kadangi prompt ir voice yra privalomi, grąžinus {} arba bet kokį atsakymą, kuris nepraeina tikrinimo, skambutis atmetamas: telefono skambutis nutraukiamas, kaip aprašyta Laiko limitai ir pakartotiniai bandymai, o valdiklio sesijos užklausa nepavyksta su 422. Tai taikoma ir grįžtantiems skambintojams: bet koks JSON objektas, kurį grąžina jūsų webhook, yra jo atsakymas, o {} yra būdas atmesti skambutį.


Agento skambučio nustatymo žiniatinklio kabliukas

Agentas gali turėti savo skambučio nustatymo žiniatinklio kabliuką: jo nustatymų lauke Skambučio nustatymo žiniatinklio kabliukas arba call_setup_webhook_url API. Priskirkite agentą numeriui, ir prieš kiekvieną įeinantį skambutį tuo numeriu, į kurį atsiliepia agentas, ThunderPhone paprašo žiniatinklio kabliuko to skambučio kintamųjų ir konteksto. Numeris išlaiko savo agentą, todėl telefono numerių puslapyje ir agento puslapyje rodoma, kuris agentas į jį atsiliepia.

Tai nustatymas, kaip ir kiti agento nustatymai: išsaugomas kaip juodraštis, paskelbiamas diegimo metu, saugomas versijų istorijoje. Numeris, priskirtas senesnei versijai, kreipiasi į tos versijos URL. Užklausos pasirašomos naudojant paties agento call_setup_webhook_signing_secret (ne organizacijos žiniatinklio kabliuko paslaptį), su ta pačia X-ThunderPhone-Signature antrašte, laukimo laikais, pakartotiniais bandymais ir idempotentiškumo raktu, kaip nurodyta aukščiau. Paslaptis skirta tik rašyti: nustatykite tokią, kurią tikrina jūsų galinis taškas (agento nustatymuose arba naudodami PATCH /v1/agents/{id}); jokia skaitymo užklausa jos negrąžina, o call_setup_webhook_signing_secret_set nurodo, ar ji nustatyta.

Užklausa yra aukščiau pateiktas telephony.incoming turinys ir agentas, kurio konfigūracija papildoma:

{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567",
    "variables":   null,
    "agent": {
      "id": 12,
      "name": "Front desk",
      "version": 7,
      "version_pinned": false
    }
  }
}
LaukasTipasAprašas
agent.idsveikasis skaičiusAgentas, priskirtas numeriui
agent.nameeilutėJo pavadinimas
agent.versionsveikasis skaičius | nullVersijos, kuri atsilieps, numeris: numeriui priskirta versija arba naujausia paskelbta agento versija (null, jei jos nėra)
agent.version_pinnedloginė reikšmėAr numeris priskirtas tai versijai

Pateikite tai, ko reikia skambučiui. Bet kuris iš šių variantų papildo priskirto agento konfigūraciją pagal numerio versiją:

  • {"variables": {...}}, {"context": "..."} arba abu
  • tas pats, kai "agent_id" nustatytas į priskirto agento id
  • {}: agentas atsiliepia nieko nepapildžius

Taip pat leidžiami timezone ir language, kaip nurodyta prie agent_id. Kintamieji užpildo agento {{placeholders}}; kontekstas pridedamas po raginimo.

Arba nuspręskite dėl skambučio patys. Kito agento agent_id arba visa konfigūracija su prompt atsiliepia tik į šį vieną skambutį vietoje priskirto agento (ir jo priskirtos versijos). Skambučio išsamioje informacijoje kiekvienas atvejis pažymimas call_setup_webhook: assigned_agent, other_agent arba inline_config. Atsakymas, kurio negalima naudoti (nežinomas agent_id, kiti raktai šalia variables, konfigūracija, kurios tikrinimas nepavyksta), nutraukia skambutį taip pat, kaip numerio žiniatinklio kabliuko atveju.

Kada žiniatinklio kabliukas privalo atsakyti. Agentui reikia jo žiniatinklio kabliuko, kai jo nustatymuose naudojamas {{variable}} be numatytosios reikšmės: jo raginime ar pakartotinai naudojamose instrukcijose, veiksmo instrukcijose ar eilutėse, patvirtinimo raginime, balso pašto pranešime, sutikimo pranešime arba {{variable}} peradresavimo numeryje. Agento call_setup_webhook_variables juos išvardija.

  • Jam reikia žiniatinklio kabliuko: kai žiniatinklio kabliuko laukimo laikas baigiasi, jis nepasiekiamas arba atsako su klaida ar turiniu, kuris nėra JSON objektas, skambutis nepradedamas, net jei skambutyje jau perduota vieno iš tų kintamųjų reikšmė. Jis nutraukiamas ir užregistruojamas tiksliai taip, kaip aprašyta Laukimo laikai ir pakartotiniai bandymai (end_reason inbound_config_webhook_failed, neapmokestinamas).
  • Jam nieko nereikia (nėra kintamųjų arba kiekvienas turi numatytąją reikšmę, pvz., {{first_name|there}}): žiniatinklio kabliukas vis tiek vykdomas, tačiau jam nepavykus agentas atsiliepia be jo, o skambučio išsamioje informacijoje rodoma webhook_failed ir nurodoma klaidos priežastis.

Vien skambučio kontekstas niekada nepadaro žiniatinklio kabliuko privalomo: niekas agento nustatymuose nenurodo, kad jam reikia konteksto. Naudokite kintamąjį be numatytosios reikšmės, jei skambutis neturi prasidėti be jūsų žiniatinklio kabliuko atsakymo.

Priskyrimas ir diegimas. Agentas, kuriam reikia žiniatinklio kabliuko, negali būti priskirtas numeriui be jo: priskyrimas atmetamas pateikiant pranešimą, kuriame nurodomi kintamieji. Tas pats patikrinimas atliekamas, kai keičiasi numerio versija, įskaitant atvejį, kai prie versijos prisegtas numeris grąžinamas į Naujausią. Kol jis atsiliepia į numerio skambučius naudodamas paskelbtus nustatymus, diegimas, kuriuo pridedamas toks kintamasis be žiniatinklio kabliuko (arba pašalinamas žiniatinklio kabliukas), atmetamas taip pat. Juodraštį visada galima išsaugoti, o agento warnings turi call_setup_webhook_needed, kol problema neišsprendžiama.

Agento žiniatinklio kabliukas vykdomas tik įeinantiems telefono skambučiams numeriais, kuriems jis yra priskirtas. Išeinantys skambučiai, žiniatinklio valdiklio seansai, SIP adresai, simuliacijos ir valdymo skydelio bandomieji pokalbiai jo neiškviečia; jų kintamieji, kaip ir anksčiau, gaunami iš užklausos.

Testavimas su išsaugotais pavyzdžiais. Norėdami patikrinti, ką jūsų agentas daro gavęs tam tikrą atsakymą (grįžtantis skambintojas, įrašo nerasta, ispaniškai kalbantis asmuo), išsaugokite tą atsakymą agentui kaip pavyzdį: jo variables, context ir, pasirinktinai, language, įvestus arba nukopijuotus iš ankstesnio skambučio. Pasirinkite jį pradėdami valdymo skydelio bandomąjį pokalbį, bandomąjį skambutį į savo telefoną ar simuliaciją su agentu, ir skambutis vyks taip, tarsi jūsų žiniatinklio kabliukas būtų atsakęs šiuo atsakymu. Pavyzdžiai bendri visoms agento versijoms. Redaguojant vieną išsaugomos ankstesnės jo versijos: kai pakeitus agentą reikia kintamojo, kurio pavyzdys nenustato, pridėkite jį prie pavyzdžio, o senesnės agento versijos toliau naudos pavyzdį tokį, koks jis buvo. Simuliacijos, kurios skambina telefono numeriu, vietoj to vykdo jūsų tikrąjį žiniatinklio kabliuką.

Numeriai be priskirto agento ir toliau naudoja numerio arba organizacijos žiniatinklio kabliuką lygiai taip pat, kaip nurodyta pirmiau.


Perskambinimai

Žmonės dažnai perskambina numeriu, iš kurio jiems buvo skambinta, pavyzdžiui, kai jūsų agentas paliko balso pranešimą. Kai sulaukiama telefono skambučio iš asmens, kuriam tuo pačiu numeriu buvo skambinta per pastarąsias 30 dienų, ThunderPhone randa naujausią tokį išeinantį skambutį (tokį, kuris skambino į jo telefoną) ir naudoja jį trimis būdais:

  1. returning_call užklausoje. Aukščiau pateikta blokuojanti užklausa ir galinio punkto pranešimas jį perduoda, todėl jūsų apdorojimo priemonė gali nukreipti skambintoją:

    {
      "type": "telephony.incoming",
      "data": {
        "call_id": 987654321,
        "from_number": "+14155550199",
        "to_number": "+15551234567",
        "returning_call": {
          "call_id": 987650001,
          "agent_id": 13,
          "started_at": "2026-10-21T19:05:12.402Z",
          "outcome": "voicemail"
        }
      }
    }
    LaukasTipasAprašas
    call_idsveikasis skaičiusAnkstesnis išeinantis skambutis
    agent_idsveikasis skaičius | nullJį atlikęs agentas; null, jei skambinta naudojant įterptinę konfigūraciją arba agentas buvo ištrintas
    started_ateilutėKada jis prasidėjo (ISO 8601, UTC)
    outcomeeilutėno_answer (neatsiliepta, numeris buvo užimtas arba skambutis atmestas), voicemail (atsiliepė balso paštas arba niekas nekalbėjo su agentu), conversation (kažkas kalbėjo su agentu) arba answered (atsiliepta; kas atsiliepė, dar nežinoma)
  2. Kontekstas agentui. Atsiliepiantis agentas savo raginimo pabaigoje gauna trumpą pastabą: kada buvo atliktas ankstesnis skambutis, kuris agentas jį atliko ir kokia buvo jo baigtis. Agentui nurodoma jos neskaityti garsiai ir, kadangi skambintojo ID gali būti suklastotas, nesidalinti niekuo apie tą skambutį, išskyrus tuo, kad į šį numerį buvo skambinta anksčiau.

  3. Atsarginis agentas. Kai numeriui nepriskirtas įeinančių skambučių agentas ir negaunama konfigūracija, nes nėra webhook URL arba jūsų webhook nepateikė atsakymo (baigėsi jo laikas, jo nepavyko pasiekti arba abiejų bandymų metu jis atsakė 5xx, 408 ar 429), skambutis, užuot buvęs nutrauktas, nukreipiamas agentui, atlikusiam ankstesnį skambutį, jei šis agentas vis dar yra jūsų organizacijoje. Jis veikia su to agento įdiegtomis nuostatomis. Bet koks jūsų webhook pateiktas atsakymas vis tiek lemia rezultatą: kitas 4xx, turinys, kuris nėra JSON objektas, {}, arba konfigūracija, nepraeinanti tikrinimo, nutraukia skambutį kaip ir anksčiau. Numeriui priskirtas įeinančių skambučių agentas visada atsiliepia.

Ankstesnio skambučio išsamios informacijos bendrinimas. Skambintojo ID gali būti suklastotas, todėl pagal numatytuosius nustatymus į naują skambutį nepatenka jokia ankstesnio skambučio turinio informacija. Organizacijos administratorius gali įjungti Bendrinti ankstesnio skambučio išsamią informaciją skiltyje Organizacija → Bendrieji → Perskambinimai (arba nustatyti callback_context_details_enabled). Jį įjungus, agento pastaboje taip pat pateikiama ankstesnio skambučio suvestinė, o skambutis, nukreiptas agentui, atlikusiam ankstesnį skambutį, vykdomas su to skambučio variables (pvz., kontakto vardu). Įjunkite tai tik jei šią informaciją saugu bendrinti su bet kuo, skambinančiu iš to numerio. Net ir įjungus šią parinktį, skambutis, kuriame gali būti saugoma sveikatos informacija, niekada neperduoda savo suvestinės ar kintamųjų skambučiui, kuris nėra nurodytas kaip tvarkantis PHI.

Skambučio išsamioje informacijoje. Įeinantis skambutis, sutapęs su ankstesniu skambučiu, turi callback objektą GET /v1/calls/{call_id}: anksčiau nurodytą returning_call, routed_as_callback (ar atsarginis agentas į jį atsiliepė) ir config_webhook_failure ({kind, attempts, http_status, host}, kai jūsų webhook nepateikė atsakymo ir atsarginis agentas perėmė skambutį, kitu atveju null), todėl webhook sutrikimas lieka matomas, net jei į skambutį buvo atsiliepta.


Atsakymo dydžio apribojimas


Apdorojimo programos pavyzdys

Python (FastAPI)
import hashlib
import hmac
import json
import os
 
from fastapi import FastAPI, HTTPException, Request
 
app = FastAPI()
WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
 
def verify(body: bytes, signature: str) -> bool:
    expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")
 
@app.post("/thunderphone-webhook")
async def webhook(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(status_code=401)
 
    event = json.loads(body)
    if event["type"] == "telephony.incoming":
        caller = event["data"]["from_number"]
        prompt = (
            "Greet the caller as a San Francisco local…"
            if caller.startswith("+1415")
            else "You are a friendly customer support agent…"
        )
        return {
            "prompt": prompt,
            "voice": "john",
            "product": "spark",
        }
    if event["type"] == "web.incoming":
        return {
            "prompt": "You are the website's helpful voice assistant…",
            "voice": "john",
            "product": "spark",
        }
    return {}
Node.js (Express)
import crypto from "node:crypto";
import express from "express";
 
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
 
function verify(body, signature) {
  const expected = crypto
    .createHmac("sha256", SECRET)
    .update(body)
    .digest("hex");
  return signature &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
 
app.post(
  "/thunderphone-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
 
    if (event.type === "telephony.incoming" || event.type === "web.incoming") {
      const caller = event.data.from_number || "web";
      const prompt = caller.startsWith("+1415")
        ? "Greet the caller as a San Francisco local…"
        : "You are a friendly customer support agent…";
      return res.json({
        prompt,
        voice: "john",
        product: "spark",
      });
    }
    res.json({});
  },
);

Atsakymas su funkcijų įrankiais

Pridėkite įrankius, kad dirbtinis intelektas pokalbio metu galėtų iškviesti jūsų API:

{
  "prompt":  "You are a booking assistant. Use the available tools to help customers schedule appointments.",
  "voice":   "john",
  "product": "spark",
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "search_appointments",
        "description": "Find available appointment slots",
        "parameters": {
          "type": "object",
          "properties": {
            "date": { "type": "string", "description": "YYYY-MM-DD" },
            "service": { "type": "string" }
          },
          "required": ["date"]
        }
      },
      "endpoint": {
        "url": "https://api.example.com/appointments/search",
        "method": "POST",
        "headers": {
          "X-Api-Key": "your-key"
        }
      }
    }
  ]
}

Nustatymų atmintinė

Siųskite product: "bolt" ir derinkite skambutį naudodami šiuos laukus. Senesnės product reikšmės (spark ir storm-* reikšmės) vis dar priimamos.

LaukasReikšmėsKą tai keičia
intelligencecore, pro (numatytoji)Core yra pigesnis ir pradeda atsakyti greičiau; Pro patikimiau laikosi ilgų raginimų
audio_tierlite, standard (numatytoji), plus, maxAukštesni lygiai geriau girdi ir kainuoja daugiau; Plus kai kuriuose ėjimuose prideda 1–2 s, kiekvienas Max atsakymas trunka 3–4 s (Max nėra visuotinai prieinamas)
endpointingfaster, fast, normal (numatytoji), patientTrumpesnis laukimas leidžia atsakyti greičiau ir kainuoja daugiau
faster_repliestrue (numatytoji), falseGreičio padidinimas: atsakymai pateikiami šiek tiek greičiau už šiek tiek didesnę kainą

Susiję