Open in
telephony.incoming / web.incoming
Blokirajući webhook koji u stvarnom vremenu oblikuje konfiguraciju dolaznog poziva.
Kada dolazni telefonski poziv stigne na broj bez dodijeljenog
agenta (pogledajte Povratni pozivi za pozivatelje koji uzvraćaju vaše
odlazne pozive) ili kada sesija web-widgeta započne na ključu za objavu u
mode="webhook", ThunderPhone šalje blokirajući
zahtjev telephony.incoming / web.incoming na vaš
zastarjeli URL webhooka
i čeka odgovor s konfiguracijom: do 13 sekundi za telefonski
poziv, uključujući jedan ponovni pokušaj, te do 10 sekundi za sesiju
widgeta (pogledajte Vremenska ograničenja i ponovni pokušaji). Ovu razmjenu koristite za
dinamički odabir prompta, glasa i alata za svaki poziv —
pogledajte vodič za dinamičku konfiguraciju poziva
za cjeloviti obrazac.
Broj s dodijeljenim glasovnim agentom odgovara tim agentom. Kada agent ima vlastiti webhook za postavljanje poziva, ista se blokirajuća razmjena najprije izvršava na URL-u agenta kako bi se popunile varijable agenta i kontekst poziva.
Istek vremena i ponovni pokušaji
Odgovorite brzo: pozivatelj čeka na vezi dok odlučujete.
Za telefonski poziv (telephony.incoming):
- Prvi pokušaj može trajati do 10 sekundi.
- Ako istekne vrijeme, ne može se povezati ili primi odgovor
5xx,408ili429, ThunderPhone pokušava još jednom. Ponovni pokušaj dobiva preostali dio proračuna od 13 sekundi za cijelu razmjenu: oko 3 sekunde nakon prvog pokušaja kojem je isteklo vrijeme, a gotovo svih 13 nakon brzog neuspjeha. Nema ponovnog pokušaja ako bi preostalo manje od 2 sekunde. - Svaki drugi odgovor
4xx, odgovor koji premašuje ograničenje veličine ili2xxčije tijelo nije valjana konfiguracija konačan je i ne ponavlja se. - Oba pokušaja šalju isto tijelo, isti
X-ThunderPhone-Signaturei isto zaglavljeX-ThunderPhone-Idempotency-Key(telephony-incoming-<call_id>), tako da obrađivač s nuspojavama može prepoznati ponovni pokušaj.
Ako ne stigne upotrebljiva konfiguracija, poziv se odmah završava
umjesto da pozivatelj ostane na tihoj liniji. U povijesti poziva prikazuje se kao
neuspješan, nenaplaćen poziv s vrijednošću end_reason
inbound_config_webhook_failed, a šalje se uobičajeni događaj
telephony.complete. Stranica poziva na nadzornoj
ploči i config_webhook_failure u
GET /v1/calls/{call_id} navode što je vaš webhook
učinio: {kind, attempts, http_status, host, source}, gdje kind može biti
http_error, timeout, connection, dns, tls, response_too_large,
blocked_url, other, invalid_json, non_object_json ili
invalid_config, host je naziv glavnog računala vašeg webhooka, a source
je number (ovaj webhook) ili agent_setup (webhook za postavljanje poziva
agenta). Za invalid_config, reason navodi zašto se odgovor nije mogao
upotrijebiti, a fields imenuje polja na koja se to odnosi: no_agent (ni
agent_id ni prompt; fields navodi ključeve koji su zanemareni, kao što je
pogrešno napisani agentId), agent_not_found, agent_id_not_integer,
unexpected_fields (ključevi osim variables, context, timezone i
language uz agent_id), invalid_variables, invalid_context,
invalid_language, unsupported_language, invalid_config_fields ili
agent_settings_invalid. U suprotnom je reason null, a fields je prazan.
Jedina je iznimka pozivatelj koji uzvraća jedan od vaših odlaznih poziva kada
sama razmjena nije uspjela: pogledajte Povratni pozivi.
Sesija widgeta (web.incoming) dobiva jedan pokušaj u trajanju do 10
sekundi. Ako ne uspije, zahtjev sesije završava pogreškom 502 ili 422.
Sadržaj zahtjeva
Za telefonske pozive (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| Polje | Vrsta | Opis |
|---|---|---|
call_id | cijeli broj | ID poziva — nepromjenjiv u svim događajima za ovaj poziv |
from_number | niz znakova | E.164 broj pozivatelja |
to_number | niz znakova | E.164 odredište (jedan od vaših ThunderPhone brojeva) |
returning_call | objekt | Prisutan samo kada je ovaj broj nazvao pozivatelja u posljednjih 30 dana. Pogledajte Uzvratne pozive |
sip_headers | objekt | Prisutan samo kada je poziv stigao putem ručne SIP veze sa zaglavljima X-* ili User-to-User SIP: naziv zaglavlja malim slovima → vrijednost. Pogledajte SIP zaglavlja |
Za sesije web widgeta (web.incoming) data umjesto telefonskih
brojeva identificira stranicu na koju je widget ugrađen:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| Polje | Vrsta | Opis |
|---|---|---|
call_id | cijeli broj | ID poziva |
origin_domain | niz | Izvor stranice na kojoj se nalazi widget, kako ga je preglednik poslao. Klijent koji nije preglednik može poslati bilo koju vrijednost, stoga ga ne tretirajte kao dokaz o tome odakle je zahtjev došao |
publishable_key_prefix | niz | Prvi znakovi javnog ključa koji je otvorio sesiju |
language, primary_language | niz | Prisutan kada je sesija widgeta zatražila nadjačavanje jezika |
voice | niz | Prisutan kada je sesija widgeta zatražila nadjačavanje glasa |
website_context | niz | Prisutan kada je widget proslijedio kontekst stranice po sesiji |
Polja za nadjačavanje (language, voice, website_context i sve
varijable preglednika variables) stižu samo kada ih javni ključ dopušta u
svojim nadjačavanjima preglednika. Zahtjev sesije koji sadrži polje koje ključ ne dopušta odbija se prije pozivanja ovog webhooka.
Shema odgovora
Vratite JSON objekt koji opisuje konfiguraciju agenta za ovaj poziv.
prompt i voice su obavezni; sve ostalo nije obavezno.
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| Polje | Vrsta | Obavezno | Opis |
|---|---|---|---|
prompt | niz znakova | da | Sustavni prompt koji upravlja agentom |
voice | niz znakova | da | ID glasa iz GET /v1/voices, npr. john. voice_name prihvaća se kao pseudonim. Nepoznati glasovi ne prolaze provjeru i odbijaju poziv |
product | niz znakova | ne | Pošaljite bolt. Zadano je spark, starija vrijednost koja se i dalje prihvaća uz storm-base, storm-base-with-ack, storm-extra i storm-extra-with-ack |
thinking_level | niz znakova | ne | minimal, base (zadano) ili extra. Za starije vrijednosti proizvoda storm-*, storm-extra* prisiljava extra, a ostale vrijednosti storm-* prisiljavaju base |
audio_context_mode | niz znakova | ne | full (zadano) ili reduced |
watchdog_enabled | logička vrijednost | ne | Omogućite nadzor za ovaj poziv. Zadano je false |
additional_audio_context | logička vrijednost | null | ne | Uključite posljednjih nekoliko izmjena zvuka pozivatelja umjesto samo najnovije izmjene, čime se poboljšavaju ispravci i prikupljanje podataka s mnogo slova/brojeva uz mali dodatni trošak latencije i cijene. Zadano je uključeno za dolazne sesije, a isključeno za odlazne telefonske pozive; null zadržava zadanu vrijednost |
storm_feedback_mode | niz znakova | ne | none, acknowledgement (zadano) ili tick: što pozivatelj čuje dok se priprema sporiji odgovor kada je audio_tier postavljen na plus ili max |
language | niz znakova | ne | Skraćenica za primary_language. Dopušteno je i uz agent_id, gdje označava jezik na kojem ovaj poziv počinje, izgovoren glasom agenta za taj jezik; pogledajte Postavljanje jezika za svaki poziv |
primary_language | niz znakova | ne | Jezični kôd, normaliziran (zadano en). Kôdovi koji se ne mogu razriješiti odbijaju poziv |
has_additional_languages | logička vrijednost | ne | Zadano je false |
additional_languages | niz nizova znakova | ne | Dodatni jezici na koje se agent može prebaciti |
native_voice_switching | logička vrijednost | ne | Zadano je false. Kada se poziv prebaci na drugi jezik, zamijenite glas glasom izvornog govornika tog jezika (usklađenim prema spolu) umjesto zadržavanja konfiguriranog glasa |
language_switching | niz znakova | null | ne | ask_first (zadano) ili follow_caller; null je isto što i ask_first. Određuje kako višejezični agent postupa kada druga osoba govori neki drugi njegov jezik. ask_first odmah se prebacuje kada osoba zatraži jezik ili izgovori cijelu rečenicu na njemu te pita želi li nastaviti na tom jeziku nakon nečeg kratkog, poput „da”. follow_caller prebacuje se na bilo koji konfigurirani jezik koji osoba govori, čak i nakon jedne riječi. Primjenjuje se samo kada je postavljen additional_languages |
audio_tier | niz znakova | null | ne | Samo za product: "bolt". Slušanje: koliko pažljivo agent čuje pozivatelja. standard (zadano; "" i null znače isto) prikladan je za većinu poziva (pozivi koji obrađuju PHI koriste samo pružatelje obuhvaćene BAA-om). lite je najjeftiniji i češće pogrešno čuje. plus pažljivije sluša tijekom zahtjevnih izmjena, koje traju oko 1–2 sekunde dulje. max je za najzahtjevniji zvuk i rijetke jezike; svaki odgovor traje 3–4 sekunde, a poziv koristi inteligenciju pro (intelligence se zanemaruje). max nije općenito dostupan: za organizaciju za koju nije omogućen, poziv koristi plus i intelligence koji navedete (zahtjev za odlazni poziv s njime odbija se s 400). Starije vrijednosti lean (Lite), hearing (Plus) i deep_hearing (Max) i dalje se prihvaćaju. Ostali proizvodi to zanemaruju |
endpointing | niz znakova | null | ne | faster (200 ms), fast (300 ms), normal (500 ms, zadano) ili patient (800 ms); null je isto što i normal. Određuje koliko Bolt v2 agent čeka nakon što pozivatelj prestane govoriti prije nego što od modela zatraži odgovor. Kraće čekanje može odgovoriti ranije, ali šalje više zahtjeva koje sljedeće riječi pozivatelja mogu učiniti zastarjelima, što povećava trošak modela. Ostali proizvodi to zanemaruju |
eagerness | niz znakova | null | ne | Zastarjelo: naziv za endpointing do 19. listopada 2026., koji se i dalje čita. Zanemaruje se kada je postavljen endpointing |
intelligence | niz znakova | null | ne | core ili pro (zadano); null je isto što i pro. Određuje koliko pouzdano agent bolt na cjevovodu Bolt v2 slijedi svoje upute. core ima približno 700 ms do prve riječi, najjeftiniji je i nešto manje pouzdan (na pozivima koji se tretiraju kao PHI, približno 900 ms i manje je pouzdan); pro ima približno 900 ms; odgovori Core koji bi samo pozvali alat predaju se Prou. Starije vrijednosti lite (Core) i standard (Pro) i dalje se prihvaćaju, a umirovljene vrijednosti plus i max izvode se na pro. Zanemaruje se kada je audio_tier postavljen na max. Ostali proizvodi to zanemaruju |
faster_replies | logička vrijednost | null | ne | Ubrzanje. Zadano je true. Za agenta bolt na cjevovodu Bolt v2 odgovori počinju nešto ranije, uz nešto veću cijenu. false to isključuje. Ostali proizvodi to zanemaruju |
background_track | niz znakova | null | ne | ID ambijentalnog zvuka ili null |
acknowledgement_prompt_mode | niz znakova | ne | auto (zadano) ili manual (starije vrijednosti proizvoda -with-ack) |
acknowledgement_prompt | niz znakova | ne | Koristi se kada je acknowledgement_prompt_mode="manual" |
silence_interval_seconds | cijeli broj | null | ne | 5–120. Sekunde tišine pozivatelja prije provjere |
silence_max_checkins | cijeli broj | null | ne | 1–10 |
silence_checkins_enabled | logička vrijednost | ne | Zadano je true |
silence_final_action | niz znakova | ne | Nakon posljednje provjere: hang_up (zadano) ili transfer na silence_transfer_destination |
silence_transfer_destination | niz znakova | ne | Naziv unosa u transfer_destinations ove konfiguracije; obavezan uz transfer. Bez transfer_destinations prijenos se ne može izvršiti i agent prekida poziv |
silence_final_message | niz znakova | ne | ≤ 300 znakova, čita se kako je napisano; "" (zadano) koristi zadanu poruku |
connect_tone_enabled | logička vrijednost | ne | Zadano je false |
pronunciation_dicts | logička vrijednost | null | ne | Zadano je false; null je isto što i false. Kada je true, Cartesia govor poziva koristi ThunderPhoneov rječnik izgovora za jezik poziva, kada postoji. Radi za telefonske pozive i pozive putem widgeta. Primjenjuje se samo na ThunderPhoneove vlastite Cartesia glasove, a ne na glasove putem vašeg vlastitog Cartesia API ključa. Ne koristi se uz agent_id, gdje se primjenjuju postavke spremljenog agenta |
words | niz | null | ne | Kako agent izgovara određene riječi, isti unosi kao u agentovu words bez support. Unos bez language preuzima jezik ove konfiguracije. null i [] znače da nema unosa. Ne koristi se uz agent_id, gdje se primjenjuju riječi spremljenog agenta |
voicemail_action | niz znakova | ne | prompt (zadano), hangup ili message |
voicemail_message | niz znakova | ne | Koristi se kada je voicemail_action="message" |
agent_name | niz znakova | ne | Naziv za prikaz koji se prijavljuje nadzornim pločama i widgetu |
org_name | niz znakova | ne | Naziv organizacije za prikaz za personu agenta |
tools | niz | ne | Ugrađene sheme funkcijskih alata (pogledajte Funkcijski alati) |
transfer_destinations | niz objekata | null | ne | Do 50 unosa {name, number} na koje ovaj poziv može biti preusmjeren, provjerenih kao agentovi brojevi za prijenos. Agent preusmjerava prema nazivu i samo na njih; [] znači da nema prijenosa. Izostavite ga ili pošaljite null da biste agentu omogućili prijenos na broj koji odabere |
timezone | niz znakova | ne | Vremenska zona IANA za ovaj poziv, kao što je America/Chicago. Agent navodi datum i vrijeme u njoj, umjesto u vlastitoj vremenskoj zoni agenta. Dopušteno je i uz agent_id. Vrijednosti koje nisu zone IANA zanemaruju se. Pogledajte Postavljanje vremenske zone za svaki poziv |
context | niz znakova | null | ne | Tekst slobodnog oblika za ovaj poziv, kao što su bilješke koje je prikupio vaš sustav, do 20.000 znakova. Dodaje se nakon prompta u razgraničenom bloku i ne prikazuje se kao predložak. Dopušteno je i uz agent_id. Vrijednost koja nije niz znakova ili je dulja odbija poziv. Pogledajte varijable poziva i kontekst |
call_id | cijeli broj | ne | Neobavezni odjek ID-a poziva zahtjeva; zanemaruje se |
Budući da su prompt i voice obavezni, vraćanje {} ili bilo kojeg
odgovora koji ne prođe provjeru valjanosti odbija poziv: telefonski se poziv prekida
kako je opisano u Isteku vremena i ponovnim pokušajima, a zahtjev za sesiju
widgeta ne uspijeva s 422. To vrijedi i za pozivatelje koji se vraćaju: bilo koji JSON objekt koji vaš webhook vrati njegov je odgovor, a
{} je način za odbijanje poziva.
Webhook za postavljanje poziva agenta
Agent može imati vlastiti webhook za postavljanje poziva: polje Webhook za postavljanje poziva
u njegovim postavkama ili call_setup_webhook_url
u API-ju. Dodijelite agenta broju i prije svakog dolaznog poziva
na taj broj, na koji agent odgovara, ThunderPhone od webhooka traži varijable
i kontekst tog poziva. Broj zadržava svojeg agenta, pa stranica telefonskih
brojeva i stranica agenta prikazuju koji agent odgovara na njega.
To je postavka kao i ostale postavke agenta: sprema se kao skica, objavljuje pri
implementaciji i čuva u povijesti verzija. Broj
prikvačen na stariju verziju
traži URL te verzije. Zahtjevi su potpisani vlastitim ključem agenta
call_setup_webhook_signing_secret (a ne tajnom webhooka organizacije), s
istim zaglavljem X-ThunderPhone-Signature, vremenskim ograničenjima,
ponovnim pokušajima i ključem idempotentnosti kao gore. Tajna je
samo za upis: postavite onu koju Vaša krajnja točka provjerava (u postavkama
agenta ili s PATCH /v1/agents/{id}); nijedan zahtjev za čitanje je ne vraća, a
call_setup_webhook_signing_secret_set navodi je li postavljena.
Zahtjev je gornji sadržaj telephony.incoming uz agenta kojeg
konfigurira:
{
"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 | integer | Agent dodijeljen broju |
agent.name | string | Njegov naziv |
agent.version | integer | null | Broj verzije koja će odgovoriti: verzija prikvačena na broj ili najnovija objavljena verzija agenta (null ako je nema) |
agent.version_pinned | boolean | Je li broj prikvačen na tu verziju |
Odgovorite onime što poziv treba. Bilo što od navedenoga popunjava dodijeljenog agenta u verziji koju koristi broj:
{"variables": {...}},{"context": "..."}ili oboje- isto uz
"agent_id"postavljen na ID dodijeljenog agenta {}: agent odgovara bez popunjenih vrijednosti
Dopušteni su i timezone i language, kao uz
agent_id. Varijable popunjavaju agentove
{{placeholders}}; kontekst se dodaje nakon prompta.
Ili sami odlučite o pozivu. agent_id drugog agenta ili
potpuna konfiguracija koja sadrži prompt odgovara samo na ovaj poziv umjesto
dodijeljenog agenta (i njegove prikvačene verzije). Pojedinosti poziva označavaju svaki slučaj u
call_setup_webhook: assigned_agent,
other_agent ili inline_config. Odgovor koji se ne može upotrijebiti (nepoznat
agent_id, drugi ključevi uz variables, konfiguracija koja
ne prođe provjeru valjanosti) završava poziv kao i webhook broja.
Kada webhook mora odgovoriti. Agent treba svoj webhook kada njegove
postavke upotrebljavaju {{variable}} bez zadane vrijednosti: njegov prompt ili višekratno
upotrebljive upute, upute ili retke koraka, prompt za potvrdu,
poruku govorne pošte, obavijest o pristanku ili broj za preusmjeravanje
{{variable}}. Agentov call_setup_webhook_variables navodi ih.
- Treba webhook: kada webhook prekorači vremensko ograničenje, nije
dostupan ili odgovori pogreškom odnosno tijelom koje nije JSON objekt,
poziv se ne pokreće, čak i kada poziv već sadrži vrijednost za
jednu od tih varijabli. Završava se i bilježi točno kako je opisano
u Vremenskim ograničenjima i ponovnim pokušajima (
end_reasoninbound_config_webhook_failed, bez naplate). - Ne treba ništa (nema varijabli ili svaka ima zadanu vrijednost kao
{{first_name|there}}): webhook se i dalje pokreće, ali kada ne uspije, agent odgovara bez njega, a pojedinosti poziva prikazujuwebhook_faileds informacijom o tome što je pošlo po zlu.
Sam kontekst poziva nikada ne čini webhook obaveznim: ništa u postavkama glasovnog agenta ne navodi da mu je potreban kontekst. Upotrijebite varijablu bez zadane vrijednosti ako poziv ne smije započeti bez odgovora vašeg webhooka.
Dodjeljivanje i implementacija. Glasovni agent kojem je potreban webhook ne može se
dodijeliti broju bez webhooka: dodjeljivanje se odbija porukom koja navodi
varijable. Ista se provjera pokreće kada se promijeni verzija broja, uključujući kada se broj s
prikvačenom verzijom vrati na Najnoviju verziju. Dok s objavljenim postavkama odgovara na pozive na broj,
implementacija koja dodaje takvu varijablu bez webhooka
(ili uklanja webhook) odbija se na isti način. Spremanje skice uvijek je dopušteno, a
warnings glasovnog agenta sadrži
call_setup_webhook_needed dok se problem ne otkloni.
Webhook glasovnog agenta pokreće se samo za dolazne telefonske pozive na brojevima kojima je dodijeljen. Odlazni pozivi, sesije web-widgeta, SIP adrese, simulacije i testni razgovori na nadzornoj ploči ne pozivaju ga; svoje varijable i dalje preuzimaju iz zahtjeva kao i prije.
Testiranje sa spremljenim uzorcima. Da biste testirali što Vaš agent radi s danim odgovorom (pozivatelj koji ponovno zove, zapis nije pronađen, govornik španjolskog jezika), spremite taj odgovor na agentu kao uzorak: njegove variables, context i, prema potrebi, language, unesene ili kopirane iz prošlog poziva. Odaberite ga kada pokrenete testni razgovor na nadzornoj ploči, testni poziv na svoj telefon ili simulaciju s agentom, a poziv će se izvršiti kao da je Vaš webhook odgovorio tim podacima. Uzorci se dijele među svim verzijama agenta. Uređivanjem uzorka zadržavaju se njegove ranije verzije: kada promjena agenta zahtijeva varijablu koju uzorak ne postavlja, dodajte je uzorku, a starije verzije agenta nastavljaju koristiti uzorak kakav je bio. Simulacije koje biraju telefonski broj umjesto toga pokreću Vaš stvarni webhook.
Brojevi bez dodijeljenog glasovnog agenta i dalje koriste webhook broja ili organizacije točno kako je gore opisano.
Uzvratni pozivi
Ljudi često uzvrate poziv na broj koji ih je nazvao, primjerice nakon što je vaš agent ostavio govornu poruku. Kada telefonski poziv stigne od nekoga koga je isti broj nazvao u posljednjih 30 dana, ThunderPhone pronalazi najnoviji takav odlazni poziv (onaj koji je zazvonio na njihovu telefonu) i koristi ga na tri načina:
-
returning_callu zahtjevu. Prethodni blokirajući zahtjev i obavijest krajnje točke sadrže ga, pa vaš rukovatelj može usmjeriti pozivatelja:{ "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_idinteger Raniji odlazni poziv agent_idinteger | null Agent koji ga je uputio; nullza poziv upućen s umetnutom konfiguracijom ili čiji je agent izbrisanstarted_atstring Vrijeme početka (ISO 8601, UTC) outcomestring no_answer(zvonio je do isteka, bilo je zauzeto ili je odbijen),voicemail(odgovorila je govorna pošta ili nitko nije razgovarao s agentom),conversation(netko je razgovarao s agentom) ilianswered(na poziv je odgovoreno; još nije poznato tko je odgovorio) -
Kontekst za agenta. Koji god agent odgovori dobiva kratku bilješku na kraju svojeg upita: kada je raniji poziv upućen, koji ga je agent uputio i kakav je bio njegov ishod. Agentu je rečeno da je ne čita naglas i da, budući da se ID pozivatelja može krivotvoriti, ne dijeli ništa o tom pozivu osim činjenice da je broj ranije nazvan.
-
Rezervni agent. Kada broj nema dolaznog agenta i ne stigne konfiguracija zato što nema URL-a web-dojavnika ili vaš web-dojavnik nije odgovorio (isteklo mu je vrijeme, nije bio dostupan ili je na oba pokušaja odgovorio s
5xx,408ili429), poziv se, umjesto da završi, preusmjerava agentu koji je uputio raniji poziv, pod uvjetom da taj agent i dalje postoji u vašoj organizaciji. Izvršava se s objavljenim postavkama tog agenta. Svaki odgovor vašeg web-dojavnika i dalje odlučuje: drugi4xx, tijelo koje nije JSON objekt,{}ili konfiguracija koja ne prođe provjeru valjanosti završavaju poziv kao i prije. Dolazni agent na broju uvijek odgovara.
Dijeljenje pojedinosti ranijeg poziva. ID pozivatelja može se krivotvoriti, pa
prema zadanim postavkama ništa iz sadržaja ranijeg poziva ne prelazi u novi poziv.
Administrator organizacije može uključiti Dijeli pojedinosti ranijeg poziva
u odjeljku Organizacija → Općenito → Uzvratni pozivi (ili postaviti
callback_context_details_enabled).
Kada je uključeno, bilješka agenta također navodi sažetak ranijeg poziva,
a poziv usmjeren agentu koji je uputio raniji poziv izvršava se s variables
tog poziva (kao što je ime kontakta). Uključite ga samo ako je te pojedinosti
sigurno dijeliti sa svakim tko nazove s tog broja. Čak i kada je uključeno,
poziv koji može sadržavati zaštićene zdravstvene podatke nikada ne prosljeđuje
svoj sažetak ni varijable pozivu koji nije označen za obradu PHI-ja.
U pojedinostima poziva. Dolazni poziv koji se podudara s ranijim pozivom ima objekt callback u GET /v1/calls/{call_id}:
prethodno navedeni returning_call, routed_as_callback (je li se javio
rezervni agent) i config_webhook_failure ({kind, attempts, http_status, host} kada Vaš webhook nije odgovorio, a rezervni agent je preuzeo
poziv, inače null), tako da prekid rada webhooka ostaje vidljiv iako je
na poziv odgovoreno.
Ograničenje veličine odgovora
Primjer obrađivača
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({});
},
);Odgovor s funkcijskim alatima
Priložite alate kako bi AI mogao pozivati vaše API-je usred razgovora:
{
"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 postavki
Pošaljite product: "bolt" i prilagodite poziv ovim poljima. Starije
vrijednosti product (spark i vrijednosti storm-*) i dalje su prihvaćene.
| Polje | Vrijednosti | Što se njime uravnotežuje |
|---|---|---|
intelligence | core, pro (zadano) | Core je jeftiniji i počinje odgovarati ranije; Pro pouzdanije slijedi duge upute |
audio_tier | lite, standard (zadano), plus, max | Više razine bolje čuju i više koštaju; Plus dodaje 1–2 s u nekim izmjenama, svaki odgovor Maxa traje 3–4 s (Max nije općenito dostupan) |
endpointing | faster, fast, normal (zadano), patient | Kraća čekanja odgovaraju ranije i više koštaju |
faster_replies | true (zadano), false | Ubrzanje: odgovori stižu malo ranije, uz malo veću cijenu |
Povezano
Neblokirajući događaj završetka poziva.
Potpuna JSON shema za tools[] i ugovor potpisane krajnje točke.
Pretplatite više URL-ova na telephony.incoming / web.incoming.
Obrasci za upite, alate i A/B testove za svakog pozivatelja.