Open in
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,408ar429atsakymas, 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
4xxatsakymas, atsakymas, viršijantis dydžio limitą, arba2xx, kurio turinys nėra tinkama konfigūracija, yra galutinis ir nebandomas pakartotinai. - Abu bandymai siunčia tą patį turinį, tą pačią
X-ThunderPhone-Signatureir tą pačiąX-ThunderPhone-Idempotency-Keyantraš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"
}
}| Laukas | Tipas | Aprašymas |
|---|---|---|
call_id | sveikasis skaičius | Skambučio ID — nekinta visuose šio skambučio įvykiuose |
from_number | eilutė | Skambintojo E.164 numeris |
to_number | eilutė | E.164 paskirties numeris (vienas iš jūsų ThunderPhone numerių) |
returning_call | objektas | Pateikiamas tik tada, kai šis numeris per pastarąsias 30 dienų skambino skambintojui. Žr. Atgaliniai skambučiai |
sip_headers | objektas | Pateikiamas 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"
}
}| Field | Type | Description |
|---|---|---|
call_id | integer | Skambučio ID |
origin_domain | string | Puslapio, 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_prefix | string | Pirmieji viešinamo rakto, kuriuo atidaryta sesija, simboliai |
language, primary_language | string | Yra, kai valdiklio sesija paprašė pakeisti kalbą |
voice | string | Yra, kai valdiklio sesija paprašė pakeisti balsą |
website_context | string | Yra, 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": []
}| Laukas | Tipas | Privalomas | Aprašas |
|---|---|---|---|
prompt | eilutė | taip | Sistemos raginimas, kuriuo vadovaujasi agentas |
voice | eilutė | taip | Balso ID iš GET /v1/voices, pvz., john. voice_name priimamas kaip alternatyvus pavadinimas. Nežinomi balsai nepraeina tikrinimo ir užklausa atmetama |
product | eilutė | ne | Sių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_level | eilutė | ne | minimal, base (numatytoji reikšmė) arba extra. Naudojant senesnes storm-* produkto reikšmes, storm-extra* priverstinai nustato extra, o kitos storm-* nustato base |
audio_context_mode | eilutė | ne | full (numatytoji reikšmė) arba reduced |
watchdog_enabled | loginė reikšmė | ne | Įjunkite šio skambučio priežiūrą. Numatytoji reikšmė – false |
additional_audio_context | loginė reikšmė | null | ne | Į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_mode | eilutė | ne | none, acknowledgement (numatytoji reikšmė) arba tick: ką skambinantysis girdi, kol rengiama lėtesnė atsakymo versija, kai audio_tier yra plus arba max |
language | eilutė | ne | Trumpinys, 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_language | eilutė | ne | Kalbos kodas, normalizuotas (numatytoji reikšmė – en). Neišsprendžiami kodai atmeta skambutį |
has_additional_languages | loginė reikšmė | ne | Numatytoji reikšmė – false |
additional_languages | eilučių masyvas | ne | Papildomos kalbos, į kurias agentas gali persijungti |
native_voice_switching | loginė reikšmė | ne | Numatytoji reikšmė – false. Skambučiui persijungus į kitą kalbą, vietoje sukonfigūruoto balso naudojamas tai kalbai gimtakalbis balsas, suderintas pagal lytį |
language_switching | eilutė | null | ne | ask_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_tier | eilutė | null | ne | Tik 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 |
endpointing | eilutė | null | ne | faster (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 |
eagerness | eilutė | null | ne | Nebenaudojama: iki 2026 m. spalio 19 d. naudotas endpointing pavadinimas, vis dar nuskaitomas. Ignoruojamas, kai nustatytas endpointing |
intelligence | eilutė | null | ne | core 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_replies | loginė reikšmė | null | ne | Greič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_track | eilutė | null | ne | Aplinkos garso ID arba null |
acknowledgement_prompt_mode | eilutė | ne | auto (numatytoji reikšmė) arba manual (senesnėms -with-ack produkto reikšmėms) |
acknowledgement_prompt | eilutė | ne | Naudojama, kai acknowledgement_prompt_mode="manual" |
silence_interval_seconds | sveikasis skaičius | null | ne | 5–120. Skambinančiojo tylos sekundės prieš patikrinimą |
silence_max_checkins | sveikasis skaičius | null | ne | 1–10 |
silence_checkins_enabled | loginė reikšmė | ne | Numatytoji reikšmė – true |
silence_final_action | eilutė | ne | Po paskutinio patikrinimo: hang_up (numatytoji reikšmė) arba transfer į silence_transfer_destination |
silence_transfer_destination | eilutė | 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_message | eilutė | ne | ≤ 300 simbolių, perskaitoma taip, kaip parašyta; "" (numatytoji reikšmė) naudoja numatytąją frazę |
connect_tone_enabled | loginė reikšmė | ne | Numatytoji reikšmė – false |
pronunciation_dicts | loginė reikšmė | null | ne | Numatytoji 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 |
words | masyvas | null | ne | Kaip 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_action | eilutė | ne | prompt (numatytoji reikšmė), hangup arba message |
voicemail_message | eilutė | ne | Naudojama, kai voicemail_action="message" |
agent_name | eilutė | ne | Rodomas pavadinimas, pateikiamas valdymo skydeliuose ir valdiklyje |
org_name | eilutė | ne | Organizacijos rodomas pavadinimas agento personai |
tools | masyvas | ne | Įterptos funkcijų įrankių schemos (žr. Funkcijų įrankiai) |
transfer_destinations | objektų masyvas | null | ne | Iki 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į |
timezone | eilutė | 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 |
context | eilutė | null | ne | Laisvos 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_id | sveikasis skaičius | ne | Pasirinktinis 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
}
}
}| Laukas | Tipas | Aprašas |
|---|---|---|
agent.id | sveikasis skaičius | Agentas, priskirtas numeriui |
agent.name | eilutė | Jo pavadinimas |
agent.version | sveikasis skaičius | null | Versijos, kuri atsilieps, numeris: numeriui priskirta versija arba naujausia paskelbta agento versija (null, jei jos nėra) |
agent.version_pinned | loginė 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_reasoninbound_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 rodomawebhook_failedir 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:
-
returning_calluž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" } } }Laukas Tipas Aprašas call_idsveikasis skaičius Ankstesnis išeinantis skambutis agent_idsveikasis skaičius | null Jį atlikęs agentas; null, jei skambinta naudojant įterptinę konfigūraciją arba agentas buvo ištrintasstarted_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) arbaanswered(atsiliepta; kas atsiliepė, dar nežinoma) -
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.
-
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,408ar429), 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ą: kitas4xx, 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
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 {}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.
| Laukas | Reikšmės | Ką tai keičia |
|---|---|---|
intelligence | core, pro (numatytoji) | Core yra pigesnis ir pradeda atsakyti greičiau; Pro patikimiau laikosi ilgų raginimų |
audio_tier | lite, standard (numatytoji), plus, max | Aukš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) |
endpointing | faster, fast, normal (numatytoji), patient | Trumpesnis laukimas leidžia atsakyti greičiau ir kainuoja daugiau |
faster_replies | true (numatytoji), false | Greičio padidinimas: atsakymai pateikiami šiek tiek greičiau už šiek tiek didesnę kainą |
Susiję
Neblokuojantis skambučio pabaigos įvykis.
Visa tools[] JSON schema ir pasirašyto galinio taško sutartis.
Prenumeruokite kelis URL adresus įvykiams telephony.incoming / web.incoming.
Šablonai raginimams, įrankiams ir A/B testams pagal skambinantįjį.