Open in
telephony.incoming / web.incoming
Blokirni spletni klic, ki v realnem času oblikuje konfiguracijo dohodnega klica.
Ko dohodni telefonski klic doseže številko brez dodeljenega
agenta (za klicatelje, ki vračajo vaše odhodne klice, glejte Povratni klici), ali se seja spletnega gradnika začne z objavljivim ključem v
mode="webhook", ThunderPhone pošlje blokirno
zahtevo telephony.incoming / web.incoming na vaš
starejši URL webhooka
in čaka na odgovor s konfiguracijo: do 13 sekund za
telefonski klic, vključno z enim ponovnim poskusom, in do 10 sekund za sejo
gradnika (glejte Časovne omejitve in ponovni poskusi). S to
izmenjavo dinamično izberite poziv, glas in orodja za vsak klic —
za celoten vzorec glejte vodnik za dinamično konfiguracijo klicev.
Številka z dodeljenim agentom sprejme klic s tem agentom. Ko ima agent svoj spletni kavelj za nastavitev klica, se ista blokirajoča izmenjava najprej izvede na URL-ju agenta, da se izpolnijo spremenljivke agenta in kontekst klica.
Časovne omejitve in ponovni poskusi
Odgovorite hitro: klicatelj čaka na liniji, medtem ko se odločate.
Za telefonski klic (telephony.incoming):
- Prvi poskus lahko traja do 10 sekund.
- Če poteče časovna omejitev, povezave ni mogoče vzpostaviti ali prejme odgovor
5xx,408ali429, ThunderPhone poskusi še enkrat. Ponovni poskus dobi preostanek 13-sekundnega časovnega proračuna za celotno izmenjavo: približno 3 sekunde po prvem poskusu, pri katerem je potekla časovna omejitev, in skoraj vseh 13 sekund po hitri napaki. Ponovnega poskusa ni, kadar bi ostali manj kot 2 sekundi. - Vsak drug odgovor
4xx, odgovor, ki presega omejitev velikosti, ali odgovor2xx, katerega telo ni veljavna konfiguracija, je dokončen in se ne ponovi. - Oba poskusa pošljeta isto telo, isti glavi
X-ThunderPhone-SignatureinX-ThunderPhone-Idempotency-Key(telephony-incoming-<call_id>), zato lahko obdelovalnik s stranskimi učinki prepozna ponovni poskus.
Če ne prispe uporabna konfiguracija, se klic takoj konča,
namesto da bi klicatelj ostal na tihi liniji. V zgodovini klicev se prikaže
kot neuspešen, nezaračunan klic z end_reason
inbound_config_webhook_failed, pošlje pa se tudi običajni dogodek
telephony.complete. Stran klica na nadzorni
plošči in config_webhook_failure v
GET /v1/calls/{call_id} navajata, kaj je vaš webhook
storil: {kind, attempts, http_status, host, source}, kjer je kind lahko http_error,
timeout, connection, dns, tls, response_too_large,
blocked_url, other, invalid_json, non_object_json ali
invalid_config, host je ime gostitelja vašega webhooka, source pa je
number (ta webhook) ali agent_setup (webhook za nastavitev klica agenta).
Za invalid_config reason pojasni, zakaj odgovora ni bilo mogoče uporabiti,
fields pa navede zadevna polja: no_agent (niti agent_id niti
prompt; fields navede ključe, ki so bili prezrti, na primer napačno črkovan
agentId), agent_not_found, agent_id_not_integer, unexpected_fields
(ključi poleg agent_id, ki niso variables, context, timezone in
language), invalid_variables, invalid_context, invalid_language,
unsupported_language, invalid_config_fields ali agent_settings_invalid.
V nasprotnem primeru je reason null, fields pa je prazen. Edina
izjema je, kadar klicatelj povratno pokliče na enega od vaših odhodnih klicev,
medtem ko sama izmenjava ni uspela: glejte Povratni klici.
Seja pripomočka (web.incoming) ima en poskus, ki lahko traja do 10
sekund. Če ne uspe, zahteva seje ne uspe s kodo 502 ali 422.
Telo zahteve
Za telefonske klice (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| Polje | Vrsta | Opis |
|---|---|---|
call_id | celo število | ID klica — nespremenljiv v vseh dogodkih za ta klic |
from_number | niz | Številka klicatelja v formatu E.164 |
to_number | niz | Ciljna številka E.164 (ena od vaših številk ThunderPhone) |
returning_call | objekt | Prisotno samo, ko je ta številka klicatelja poklicala v zadnjih 30 dneh. Glejte Povratni klici |
sip_headers | objekt | Prisotno samo, ko je klic prispel prek ročne povezave SIP z glavami SIP X-* ali User-to-User: ime glave z malimi črkami → vrednost. Glejte Glave SIP |
Za seje spletnega gradnika (web.incoming) data namesto telefonskih
številk določa stran, v katero je gradnik vdelan:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| Polje | Vrsta | Opis |
|---|---|---|
call_id | celo število | ID klica |
origin_domain | niz | Izvor strani, na kateri gostuje gradnik, kot ga je poslal brskalnik. Odjemalec, ki ni brskalnik, lahko pošlje katero koli vrednost, zato tega ne obravnavajte kot dokaz, od kod je zahteva prišla |
publishable_key_prefix | niz | Prvi znaki objavljivega ključa, ki je odprl sejo |
language, primary_language | niz | Prisotno, ko je seja gradnika zahtevala preglasitev jezika |
voice | niz | Prisotno, ko je seja gradnika zahtevala preglasitev glasu |
website_context | niz | Prisotno, ko je gradnik posredoval kontekst strani za posamezno sejo |
Polja za preglasitev (language, voice, website_context in vse
brskalniške variables) prispejo samo, ko jih objavljivi ključ dovoljuje v
svojih preglasitvah brskalnika. Zahteva za sejo, ki vsebuje preglasitev, ki je ključ ne dovoljuje, je zavrnjena, preden je ta webhook poklican.
Shema odgovora
Vrnite objekt JSON, ki opisuje konfiguracijo agenta za ta klic.
prompt in voice sta obvezna; vse drugo je izbirno.
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| Polje | Vrsta | Obvezno | Opis |
|---|---|---|---|
prompt | niz | da | Sistemski poziv, ki usmerja agenta |
voice | niz | da | ID glasu iz GET /v1/voices, npr. john. voice_name je sprejet kot vzdevek. Neznani glasovi ne prestanejo preverjanja in zavrnejo klic |
product | niz | ne | Pošljite bolt. Privzeta vrednost je spark, starejša vrednost, ki je še vedno sprejeta skupaj z storm-base, storm-base-with-ack, storm-extra in storm-extra-with-ack |
thinking_level | niz | ne | minimal, base (privzeto) ali extra. Pri starejših vrednostih izdelka storm-* storm-extra* vsili extra, drugi storm-* pa vsilijo base |
audio_context_mode | niz | ne | full (privzeto) ali reduced |
watchdog_enabled | logična vrednost | ne | Omogočite nadzor za ta klic. Privzeta vrednost je false |
additional_audio_context | logična vrednost | null | ne | Vključite zadnjih nekaj obratov zvoka klicatelja namesto le najnovejšega obrata, kar izboljša popravke ter zbiranje podatkov z veliko črkovanja in številk ob majhnem dodatku zakasnitve oziroma stroškov. Privzeto je vklopljeno za dohodne seje in izklopljeno za odhodne telefonske klice; null ohrani privzeto nastavitev |
storm_feedback_mode | niz | ne | none, acknowledgement (privzeto) ali tick: kaj klicatelj sliši, medtem ko se pripravlja počasnejši odgovor, kadar je audio_tier plus ali max |
language | niz | ne | Okrajšava za primary_language. Dovoljeno je tudi ob agent_id, kjer določa jezik, v katerem se ta klic začne in ki ga agent govori z glasom, določenim zanj; glejte Nastavite jezik za posamezen klic |
primary_language | niz | ne | Jezikovna koda, normalizirana (privzeto en). Kod, ki jih ni mogoče razrešiti, klic zavrne |
has_additional_languages | logična vrednost | ne | Privzeta vrednost je false |
additional_languages | polje nizov | ne | Dodatni jeziki, na katere lahko agent preklopi |
native_voice_switching | logična vrednost | ne | Privzeta vrednost je false. Ko klic preklopi v drug jezik, zamenjajte glas z glasom, naravnim za ta jezik (ujemajočim se po spolu), namesto da ohranite konfigurirani glas |
language_switching | niz | null | ne | ask_first (privzeto) ali follow_caller; null pomeni enako kot ask_first. Določa, kako večjezični agent obravnava drugo osebo, ki govori drug njegov jezik. ask_first takoj preklopi, ko oseba zahteva jezik ali v njem pove celoten stavek, po nečem kratkem, kot je »sí«, pa vpraša, ali naj nadaljuje v tem jeziku. follow_caller preklopi v kateri koli konfigurirani jezik, ki ga oseba govori, tudi če gre le za eno besedo. Velja le, ko je nastavljeno additional_languages |
audio_tier | niz | null | ne | Samo za product: "bolt". Poslušanje: kako skrbno agent sliši klicatelja. standard (privzeto; "" in null pomenita enako) je primeren za večino klicev (klici, ki obdelujejo PHI, uporabljajo le ponudnike, zajete v BAA). lite je najcenejši in pogosteje napačno sliši. plus pozorneje posluša pri zahtevnih obratih, ki trajajo približno 1–2 sekundi dlje. max je za najzahtevnejši zvok in redke jezike; vsak odgovor traja 3–4 sekunde, klic pa uporablja inteligenco pro (intelligence se prezre). max ni splošno na voljo: za organizacijo, za katero ni omogočen, klic uporablja plus in navedeno intelligence (zahteva za odhodni klic z njim je zavrnjena s 400). Starejše vrednosti lean (Lite), hearing (Plus) in deep_hearing (Max) so še vedno sprejete. Drugi izdelki to prezrejo |
endpointing | niz | null | ne | faster (200 ms), fast (300 ms), normal (500 ms, privzeto) ali patient (800 ms); null pomeni enako kot normal. Določa, kako dolgo agent Bolt v2 po tem, ko klicatelj preneha govoriti, čaka, preden model zaprosi za odgovor. Krajše čakanje lahko odgovori prej, vendar pošlje več zahtev, ki jih naslednje besede klicatelja zastarajo, kar poveča strošek modela. Drugi izdelki to prezrejo |
eagerness | niz | null | ne | Zastarelo: ime za endpointing do 19. oktobra 2026, ki se še vedno bere. Prezre se, kadar je nastavljeno endpointing |
intelligence | niz | null | ne | core ali pro (privzeto); null pomeni enako kot pro. Določa, kako zanesljivo agent bolt v cevovodu Bolt v2 sledi navodilom. core potrebuje približno 700 ms do prve besede, je najcenejši in nekoliko manj zanesljiv (pri klicih, obravnavanih kot PHI, približno 900 ms in je manj zanesljiv); pro potrebuje približno 900 ms; odgovori Core, ki bi zgolj poklicali orodje, se predajo Pro. Starejši vrednosti lite (Core) in standard (Pro) sta še vedno sprejeti, opuščeni plus in max pa se izvajata v pro. Prezre se, kadar je audio_tier max. Drugi izdelki to prezrejo |
faster_replies | logična vrednost | null | ne | Pospešitev. Privzeta vrednost je true. Pri agentu bolt v cevovodu Bolt v2 se odgovori začnejo nekoliko prej, za nekoliko višjo ceno. false to izklopi. Drugi izdelki to prezrejo |
background_track | niz | null | ne | ID ambientalnega zvoka ali null |
acknowledgement_prompt_mode | niz | ne | auto (privzeto) ali manual (starejše vrednosti izdelka -with-ack) |
acknowledgement_prompt | niz | ne | Uporabi se, kadar je acknowledgement_prompt_mode="manual" |
silence_interval_seconds | celo število | null | ne | 5–120. Sekunde tišine klicatelja pred preverjanjem |
silence_max_checkins | celo število | null | ne | 1–10 |
silence_checkins_enabled | logična vrednost | ne | Privzeta vrednost je true |
silence_final_action | niz | ne | Po zadnjem preverjanju: hang_up (privzeto) ali transfer v silence_transfer_destination |
silence_transfer_destination | niz | ne | Ime vnosa v transfer_destinations te konfiguracije; obvezno pri transfer. Brez transfer_destinations prenosa ni mogoče izvesti in agent prekine klic |
silence_final_message | niz | ne | ≤ 300 znakov, prebere se, kot je zapisano; "" (privzeto) uporabi privzeto vrstico |
connect_tone_enabled | logična vrednost | ne | Privzeta vrednost je false |
pronunciation_dicts | logična vrednost | null | ne | Privzeta vrednost je false; null pomeni enako kot false. Kadar je true, govor Cartesia v klicu uporablja slovar izgovorjave ThunderPhone za jezik klica, kjer ta obstaja. Deluje za telefonske klice in klice iz gradnika. Velja le za lastne glasove Cartesia družbe ThunderPhone, ne za glasove z vašim lastnim ključem API Cartesia. Ne uporablja se z agent_id, kjer veljajo nastavitve shranjenega agenta |
words | polje | null | ne | Določa, kako agent izgovarja določene besede; vnosi so enaki kot pri words agenta, brez support. Vnos brez language prevzame jezik te konfiguracije. null in [] pomenita nobenih vnosov. Ne uporablja se z agent_id, kjer veljajo besede shranjenega agenta |
voicemail_action | niz | ne | prompt (privzeto), hangup ali message |
voicemail_message | niz | ne | Uporabi se, kadar je voicemail_action="message" |
agent_name | niz | ne | Prikazno ime, prikazano na nadzornih ploščah in v gradniku |
org_name | niz | ne | Prikazno ime organizacije za osebnost agenta |
tools | polje | ne | Vrstične sheme funkcijskih orodij (glejte Funkcijska orodja) |
transfer_destinations | polje objektov | null | ne | Do 50 vnosov {name, number}, na katere se lahko ta klic preusmeri, preverjenih kot številke za prenos agenta. Agent prenaša po imenu in le na te vnose; [] pomeni brez prenosov. Izpustite ga ali pošljite null, da lahko agent prenese klic na številko, ki jo izbere sam |
timezone | niz | ne | Časovni pas IANA za ta klic, kot je America/Chicago. Agent navede datum in čas v njem pred lastnim časovnim pasom agenta. Dovoljeno je tudi ob agent_id. Vrednosti, ki niso časovni pasovi IANA, se prezrejo. Glejte Nastavite časovni pas za posamezen klic |
context | niz | null | ne | Besedilo proste oblike za ta klic, na primer opombe, ki jih je zbral vaš sistem, do 20.000 znakov. Doda se za pozivom v razmejenem bloku in se ne upodobi kot predloga. Dovoljeno je tudi ob agent_id. Vrednost, ki ni niz ali je daljša, klic zavrne. Glejte spremenljivke klica in kontekst |
call_id | celo število | ne | Izbirni odmev ID-ja klica zahteve; prezre se |
Ker sta prompt in voice obvezna, vrnitev {} ali katerega koli odgovora, ki ne prestane preverjanja veljavnosti, zavrne klic: telefonski klic se konča, kot je opisano v Časovne omejitve in ponovni poskusi, zahteva za sejo gradnika pa ne uspe s kodo 422. To velja tudi za povratne klicatelje: vsak predmet JSON, ki ga vrne vaš webhook, je njegov odgovor, {} pa je način za zavrnitev klica.
Webhook agenta za nastavitev klica
Agent ima lahko svoj webhook za nastavitev klica: polje Webhook za nastavitev klica
v njegovih nastavitvah ali call_setup_webhook_url
v API-ju. Agenta dodelite številki in pred vsakim dohodnim klicem
na to številko, na katerega agent odgovori, ThunderPhone webhook vpraša po
spremenljivkah in kontekstu tega klica. Številka ohrani svojega agenta, zato stran s telefonskimi
številkami in stran agenta prikazujeta, kateri agent nanjo odgovarja.
To je nastavitev kot druge nastavitve agenta: pripravljena kot osnutek, objavljena ob
uvedbi in shranjena v zgodovini različic. Številka,
pripeta na starejšo različico,
zahteva URL te različice. Zahteve so podpisane z lastnim agentovim
call_setup_webhook_signing_secret (ne s skrivnostjo webhooka organizacije),
z isto glavo X-ThunderPhone-Signature, časovnimi omejitvami,
ponovnimi poskusi in ključem idempotentnosti kot zgoraj. Skrivnost je
samo za zapisovanje: nastavite takšno, ki jo vaša končna točka preverja (v nastavitvah agenta ali z
PATCH /v1/agents/{id}); nobeno branje je ne vrne, vrednost
call_setup_webhook_signing_secret_set pa pove, ali je nastavljena.
Zahteva vsebuje zgornji payload telephony.incoming ter agenta, ki ga
dopolnjuje:
{
"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
}
}
}| Polje | Vrsta | Opis |
|---|---|---|
agent.id | celo število | Agent, dodeljen številki |
agent.name | niz | Njegovo ime |
agent.version | celo število | null | Številka različice, ki bo odgovorila: pripeta različica številke, sicer najnovejša objavljena različica agenta (null, če je nima) |
agent.version_pinned | logična vrednost | Ali je številka pripeta na to različico |
Odgovorite s tem, kar klic potrebuje. Kateri koli od teh odgovorov dopolni dodeljenega agenta v različici številke:
{"variables": {...}},{"context": "..."}ali oboje- enako z
"agent_id", nastavljenim na ID dodeljenega agenta {}: agent odgovori brez dopolnjenih podatkov
Dovoljena sta tudi timezone in language, kot ob
agent_id. Spremenljivke izpolnijo agentove
{{placeholders}}; kontekst se doda za pozivom.
Lahko pa o klicu odločite sami. agent_id drugega agenta ali
celotna konfiguracija s prompt odgovori na ta posamezni klic namesto
dodeljenega agenta (in njegove pripete različice). Podrobnosti klica vsak primer označijo v
call_setup_webhook: assigned_agent,
other_agent ali inline_config. Odgovor, ki ga ni mogoče uporabiti (neznan
agent_id, drugi ključi poleg variables, konfiguracija, ki ne prestane
preverjanja veljavnosti), konča klic enako kot webhook številke.
Kdaj mora webhook odgovoriti. Agent potrebuje svoj webhook, kadar njegove
nastavitve uporabljajo {{variable}} brez privzete vrednosti: v pozivu ali navodilih za večkratno uporabo,
navodilih ali vrsticah koraka, pozivu za potrditev,
sporočilu glasovne pošte, obvestilu o privolitvi ali številki za preusmeritev {{variable}}.
Agentov call_setup_webhook_variables jih navede.
- Webhook potrebuje: kadar webhooku poteče časovna omejitev, ga ni mogoče
doseči ali odgovori z napako oziroma telesom, ki ni predmet JSON,
se klic ne začne, tudi če klic že vsebuje vrednost ene od teh
spremenljivk. Konča se in zabeleži točno tako, kot je opisano v
Časovne omejitve in ponovni poskusi (
end_reasoninbound_config_webhook_failed, brez zaračunavanja). - Ne potrebuje ničesar (nima spremenljivk ali pa ima vsaka privzeto vrednost, kot je
{{first_name|there}}): webhook se še vedno zažene, vendar agent ob njegovi napaki odgovori brez njega, podrobnosti klica pa prikažejowebhook_failedz opisom težave.
Sam kontekst klica nikoli ne pomeni, da je webhook obvezen: nič v nastavitvah agenta ne določa, da potrebuje kontekst. Uporabite spremenljivko brez privzete vrednosti, če se klic ne sme začeti brez odgovora vašega webhooka.
Dodeljevanje in objavljanje. Agenta, ki potrebuje svoj webhook, ni mogoče
dodeliti številki brez njega: dodelitev je zavrnjena s sporočilom, ki navaja
spremenljivke. Enako preverjanje se izvede, ko se spremeni različica številke,
vključno s pripeto številko, ki se vrne na Najnovejšo. Medtem ko agent odgovarja na številko s
svojimi objavljenimi nastavitvami, je objava, ki doda takšno spremenljivko brez webhooka
(ali odstrani webhook), enako zavrnjena. Shranjevanje osnutka je vedno dovoljeno,
opozorila agenta warnings pa vsebujejo
call_setup_webhook_needed, dokler težava ni odpravljena.
Webhook agenta se izvaja samo za dohodne telefonske klice na številkah, ki so mu dodeljene. Odhodni klici, seje spletnega gradnika, naslovi SIP, simulacije in preskusni pogovori na nadzorni plošči ga ne kličejo; spremenljivke še naprej pridobivajo iz zahteve kot prej.
Preizkušanje s shranjenimi vzorci. Če želite preizkusiti, kaj vaš agent naredi z
danim odgovorom (klicatelj, ki se vrača, ni najdenega zapisa, govorec španščine),
ta odgovor shranite pri agentu kot vzorec: njegove variables, context
in po želji language, vnesene ali kopirane iz preteklega klica. Izberite ga,
ko začnete preizkusni pogovor na nadzorni plošči, preizkusni klic na svoj telefon
ali simulacijo z agentom, klic pa se izvede, kot da bi vaš spletni kavelj odgovoril
z njim. Vzorci so skupni vsem različicam agenta. Z urejanjem vzorca ohranite
njegove prejšnje različice: ko sprememba agenta zahteva spremenljivko, ki je vzorec
ne nastavi, jo dodajte vzorcu, starejše različice agenta pa še naprej uporabljajo
vzorec v prejšnji obliki. Simulacije, ki pokličejo telefonsko številko, namesto tega
zaženejo vaš dejanski spletni kavelj.
Številke brez dodeljenega agenta še naprej uporabljajo webhook številke ali organizacije natanko tako kot zgoraj.
Povratni klici
Ljudje pogosto pokličejo nazaj številko, ki jih je poklicala, na primer po tem, ko je vaš agent pustil glasovno sporočilo. Ko prejmete telefonski klic od osebe, ki jo je ista številka poklicala v zadnjih 30 dneh, ThunderPhone poišče najnovejši tak odhodni klic (tak, pri katerem je njen telefon zvonil) in ga uporabi na tri načine:
-
returning_callv zahtevi. Zgornja blokirajoča zahteva in obvestilo končne točke ga vsebujeta, zato lahko vaš obdelovalnik usmeri klicatelja:{ "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" } } }Polje Vrsta Opis call_idcelo število Prejšnji odhodni klic agent_idcelo število | null Agent, ki je opravil klic; nullza klic, opravljen z vrstično konfiguracijo, ali če je bil njegov agent izbrisanstarted_atniz Kdaj se je začel (ISO 8601, UTC) outcomeniz no_answer(telefon je zvonil do konca, bil zaseden ali je bil klic zavrnjen),voicemail(odzvala se je glasovna pošta ali nihče ni govoril z agentom),conversation(nekdo je govoril z agentom) alianswered(klic je bil prevzet; še ni znano, kdo ga je prevzel) -
Kontekst za agenta. Kateri koli agent odgovori, na koncu svojega poziva prejme kratko opombo: kdaj je bil opravljen prejšnji klic, kateri agent ga je opravil in kakšen je bil njegov izid. Agentu je naročeno, naj je ne prebere na glas in naj zaradi možnosti ponarejanja identitete klicatelja ne deli ničesar o tem klicu, razen da je bila številka prej poklicana.
-
Nadomestni agent. Kadar številka nima dohodnega agenta in ne prispe nobena konfiguracija, ker ni URL-ja webhooka ali vaš webhook ni podal odgovora (potekel je čas, ni bil dosegljiv ali je v obeh poskusih vrnil
5xx,408ali429), se klic namesto zaključka preusmeri k agentu, ki je opravil prejšnji klic, če ta agent še vedno obstaja v vaši organizaciji. Izvaja se z uvedenimi nastavitvami tega agenta. Vsak odgovor vašega webhooka še vedno odloča: drug4xx, telo, ki ni predmet JSON,{}ali konfiguracija, ki ne uspe pri preverjanju veljavnosti, zaključi klic kot prej. Dohodni agent na številki vedno odgovori.
Deljenje podrobnosti prejšnjega klica. Identiteto klicatelja je mogoče ponarediti, zato
privzeto nobena vsebina prejšnjega klica ne doseže novega klica.
Skrbnik organizacije lahko v možnosti Organizacija → Splošno → Povratni klici vklopi
Deli podrobnosti prejšnjega klica (ali nastavi
callback_context_details_enabled).
Ko je možnost vklopljena, opomba za agenta vključuje tudi povzetek prejšnjega klica,
klic, usmerjen k agentu, ki je opravil prejšnji klic, pa se izvaja s spremenljivkami
variables tega klica (na primer z imenom stika). Vklopite jo le, če je te podrobnosti
varno deliti z vsakomer, ki kliče s te številke. Tudi ko je možnost vklopljena, klic,
ki lahko vsebuje zaščitene zdravstvene informacije, nikoli ne posreduje svojega povzetka
ali spremenljivk klicu, ki ni določen za obdelavo PHI.
V podrobnostih klica. Dohodni klic, ki se je ujemal s prejšnjim klicem, ima
objekt callback v GET /v1/calls/{call_id}:
zgornji returning_call, routed_as_callback (ali je nadomestni agent
odgovoril nanj) in config_webhook_failure ({kind, attempts, http_status, host} kadar vaš webhook ni odgovoril in je nadomestni agent prevzel
klic, sicer null), tako da izpad webhoka ostane viden, tudi če je bil
klic sprejet.
Omejitev velikosti odziva
Primer obdelovalnika
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({});
},
);Odziv s funkcijskimi orodji
Priložite orodja, da lahko umetna inteligenca med pogovorom pokliče vaše API-je:
{
"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"
}
}
}
]
}Pregled nastavitev
Pošljite product: "bolt" in klic prilagodite s temi polji. Starejše
vrednosti product (spark in vrednosti storm-*) so še vedno podprte.
| Polje | Vrednosti | Kaj uravnava |
|---|---|---|
intelligence | core, pro (privzeto) | Core je cenejši in začne odgovarjati prej; Pro zanesljiveje sledi dolgim pozivom |
audio_tier | lite, standard (privzeto), plus, max | Višje ravni bolje slišijo in stanejo več; Plus pri nekaterih potezah doda 1–2 s, vsak odgovor Max traja 3–4 s (Max ni splošno na voljo) |
endpointing | faster, fast, normal (privzeto), patient | Krajše čakanje odgovori prej in stane več |
faster_replies | true (privzeto), false | Pospešitev hitrosti: odgovori nekoliko prej, za nekoliko višjo ceno |
Povezano
Neblokirajoč dogodek ob koncu klica.
Celotna shema JSON za tools[] in pogodba podpisane končne točke.
Naročite več naslovov URL na telephony.incoming / web.incoming.
Vzorci za pozive, orodja in A/B-teste za posamezne klicatelje.