ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Webhooks

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, 408 ili 429, 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 ili 2xx čije tijelo nije valjana konfiguracija konačan je i ne ponavlja se.
  • Oba pokušaja šalju isto tijelo, isti X-ThunderPhone-Signature i isto zaglavlje X-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"
  }
}
PoljeVrstaOpis
call_idcijeli brojID poziva — nepromjenjiv u svim događajima za ovaj poziv
from_numberniz znakovaE.164 broj pozivatelja
to_numberniz znakovaE.164 odredište (jedan od vaših ThunderPhone brojeva)
returning_callobjektPrisutan samo kada je ovaj broj nazvao pozivatelja u posljednjih 30 dana. Pogledajte Uzvratne pozive
sip_headersobjektPrisutan 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"
  }
}
PoljeVrstaOpis
call_idcijeli brojID poziva
origin_domainnizIzvor 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_prefixnizPrvi znakovi javnog ključa koji je otvorio sesiju
language, primary_languagenizPrisutan kada je sesija widgeta zatražila nadjačavanje jezika
voicenizPrisutan kada je sesija widgeta zatražila nadjačavanje glasa
website_contextnizPrisutan 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":   []
}
PoljeVrstaObaveznoOpis
promptniz znakovadaSustavni prompt koji upravlja agentom
voiceniz znakovadaID glasa iz GET /v1/voices, npr. john. voice_name prihvaća se kao pseudonim. Nepoznati glasovi ne prolaze provjeru i odbijaju poziv
productniz znakovanePoš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_levelniz znakovaneminimal, base (zadano) ili extra. Za starije vrijednosti proizvoda storm-*, storm-extra* prisiljava extra, a ostale vrijednosti storm-* prisiljavaju base
audio_context_modeniz znakovanefull (zadano) ili reduced
watchdog_enabledlogička vrijednostneOmogućite nadzor za ovaj poziv. Zadano je false
additional_audio_contextlogička vrijednost | nullneUključ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_modeniz znakovanenone, acknowledgement (zadano) ili tick: što pozivatelj čuje dok se priprema sporiji odgovor kada je audio_tier postavljen na plus ili max
languageniz znakovaneSkrać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_languageniz znakovaneJezični kôd, normaliziran (zadano en). Kôdovi koji se ne mogu razriješiti odbijaju poziv
has_additional_languageslogička vrijednostneZadano je false
additional_languagesniz nizova znakovaneDodatni jezici na koje se agent može prebaciti
native_voice_switchinglogička vrijednostneZadano 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_switchingniz znakova | nullneask_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_tierniz znakova | nullneSamo 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
endpointingniz znakova | nullnefaster (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
eagernessniz znakova | nullneZastarjelo: naziv za endpointing do 19. listopada 2026., koji se i dalje čita. Zanemaruje se kada je postavljen endpointing
intelligenceniz znakova | nullnecore 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_replieslogička vrijednost | nullneUbrzanje. 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_trackniz znakova | nullneID ambijentalnog zvuka ili null
acknowledgement_prompt_modeniz znakovaneauto (zadano) ili manual (starije vrijednosti proizvoda -with-ack)
acknowledgement_promptniz znakovaneKoristi se kada je acknowledgement_prompt_mode="manual"
silence_interval_secondscijeli broj | nullne5–120. Sekunde tišine pozivatelja prije provjere
silence_max_checkinscijeli broj | nullne1–10
silence_checkins_enabledlogička vrijednostneZadano je true
silence_final_actionniz znakovaneNakon posljednje provjere: hang_up (zadano) ili transfer na silence_transfer_destination
silence_transfer_destinationniz znakovaneNaziv 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_messageniz znakovane≤ 300 znakova, čita se kako je napisano; "" (zadano) koristi zadanu poruku
connect_tone_enabledlogička vrijednostneZadano je false
pronunciation_dictslogička vrijednost | nullneZadano 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
wordsniz | nullneKako 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_actionniz znakovaneprompt (zadano), hangup ili message
voicemail_messageniz znakovaneKoristi se kada je voicemail_action="message"
agent_nameniz znakovaneNaziv za prikaz koji se prijavljuje nadzornim pločama i widgetu
org_nameniz znakovaneNaziv organizacije za prikaz za personu agenta
toolsnizneUgrađene sheme funkcijskih alata (pogledajte Funkcijski alati)
transfer_destinationsniz objekata | nullneDo 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
timezoneniz znakovaneVremenska 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
contextniz znakova | nullneTekst 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_idcijeli brojneNeobavezni 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
    }
  }
}
PoljeVrstaOpis
agent.idintegerAgent dodijeljen broju
agent.namestringNjegov naziv
agent.versioninteger | nullBroj verzije koja će odgovoriti: verzija prikvačena na broj ili najnovija objavljena verzija agenta (null ako je nema)
agent.version_pinnedbooleanJe 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_reason inbound_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 prikazuju webhook_failed s 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:

  1. returning_call u 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"
        }
      }
    }
    PoljeVrstaOpis
    call_idintegerRaniji odlazni poziv
    agent_idinteger | nullAgent koji ga je uputio; null za poziv upućen s umetnutom konfiguracijom ili čiji je agent izbrisan
    started_atstringVrijeme početka (ISO 8601, UTC)
    outcomestringno_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) ili answered (na poziv je odgovoreno; još nije poznato tko je odgovorio)
  2. 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.

  3. 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, 408 ili 429), 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: drugi 4xx, 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

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({});
  },
);

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.

PoljeVrijednostiŠto se njime uravnotežuje
intelligencecore, pro (zadano)Core je jeftiniji i počinje odgovarati ranije; Pro pouzdanije slijedi duge upute
audio_tierlite, standard (zadano), plus, maxViš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)
endpointingfaster, fast, normal (zadano), patientKraća čekanja odgovaraju ranije i više koštaju
faster_repliestrue (zadano), falseUbrzanje: odgovori stižu malo ranije, uz malo veću cijenu

Povezano