ThunderPhone v3 je zdaj na voljo.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Webhooks

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, 408 ali 429, 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 odgovor 2xx, katerega telo ni veljavna konfiguracija, je dokončen in se ne ponovi.
  • Oba poskusa pošljeta isto telo, isti glavi X-ThunderPhone-Signature in X-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"
  }
}
PoljeVrstaOpis
call_idcelo številoID klica — nespremenljiv v vseh dogodkih za ta klic
from_numbernizŠtevilka klicatelja v formatu E.164
to_numbernizCiljna številka E.164 (ena od vaših številk ThunderPhone)
returning_callobjektPrisotno samo, ko je ta številka klicatelja poklicala v zadnjih 30 dneh. Glejte Povratni klici
sip_headersobjektPrisotno 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"
  }
}
PoljeVrstaOpis
call_idcelo številoID klica
origin_domainnizIzvor 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_prefixnizPrvi znaki objavljivega ključa, ki je odprl sejo
language, primary_languagenizPrisotno, ko je seja gradnika zahtevala preglasitev jezika
voicenizPrisotno, ko je seja gradnika zahtevala preglasitev glasu
website_contextnizPrisotno, 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":   []
}
PoljeVrstaObveznoOpis
promptnizdaSistemski poziv, ki usmerja agenta
voicenizdaID glasu iz GET /v1/voices, npr. john. voice_name je sprejet kot vzdevek. Neznani glasovi ne prestanejo preverjanja in zavrnejo klic
productniznePoš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_levelnizneminimal, base (privzeto) ali extra. Pri starejših vrednostih izdelka storm-* storm-extra* vsili extra, drugi storm-* pa vsilijo base
audio_context_modeniznefull (privzeto) ali reduced
watchdog_enabledlogična vrednostneOmogočite nadzor za ta klic. Privzeta vrednost je false
additional_audio_contextlogična vrednost | nullneVključ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_modeniznenone, acknowledgement (privzeto) ali tick: kaj klicatelj sliši, medtem ko se pripravlja počasnejši odgovor, kadar je audio_tier plus ali max
languagenizneOkrajš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_languagenizneJezikovna koda, normalizirana (privzeto en). Kod, ki jih ni mogoče razrešiti, klic zavrne
has_additional_languageslogična vrednostnePrivzeta vrednost je false
additional_languagespolje nizovneDodatni jeziki, na katere lahko agent preklopi
native_voice_switchinglogična vrednostnePrivzeta 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_switchingniz | nullneask_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_tierniz | nullneSamo 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
endpointingniz | nullnefaster (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
eagernessniz | nullneZastarelo: ime za endpointing do 19. oktobra 2026, ki se še vedno bere. Prezre se, kadar je nastavljeno endpointing
intelligenceniz | nullnecore 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_replieslogična vrednost | nullnePospeš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_trackniz | nullneID ambientalnega zvoka ali null
acknowledgement_prompt_modenizneauto (privzeto) ali manual (starejše vrednosti izdelka -with-ack)
acknowledgement_promptnizneUporabi se, kadar je acknowledgement_prompt_mode="manual"
silence_interval_secondscelo število | nullne5–120. Sekunde tišine klicatelja pred preverjanjem
silence_max_checkinscelo število | nullne1–10
silence_checkins_enabledlogična vrednostnePrivzeta vrednost je true
silence_final_actionniznePo zadnjem preverjanju: hang_up (privzeto) ali transfer v silence_transfer_destination
silence_transfer_destinationnizneIme vnosa v transfer_destinations te konfiguracije; obvezno pri transfer. Brez transfer_destinations prenosa ni mogoče izvesti in agent prekine klic
silence_final_messagenizne≤ 300 znakov, prebere se, kot je zapisano; "" (privzeto) uporabi privzeto vrstico
connect_tone_enabledlogična vrednostnePrivzeta vrednost je false
pronunciation_dictslogična vrednost | nullnePrivzeta 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
wordspolje | nullneDoloč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_actionnizneprompt (privzeto), hangup ali message
voicemail_messagenizneUporabi se, kadar je voicemail_action="message"
agent_nameniznePrikazno ime, prikazano na nadzornih ploščah in v gradniku
org_nameniznePrikazno ime organizacije za osebnost agenta
toolspoljeneVrstične sheme funkcijskih orodij (glejte Funkcijska orodja)
transfer_destinationspolje objektov | nullneDo 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
timezonenizneČ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
contextniz | nullneBesedilo 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_idcelo številoneIzbirni 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
    }
  }
}
PoljeVrstaOpis
agent.idcelo številoAgent, dodeljen številki
agent.namenizNjegovo ime
agent.versioncelo š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_pinnedlogična vrednostAli 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_reason inbound_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žejo webhook_failed z 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:

  1. returning_call v 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"
        }
      }
    }
    PoljeVrstaOpis
    call_idcelo številoPrejšnji odhodni klic
    agent_idcelo število | nullAgent, ki je opravil klic; null za klic, opravljen z vrstično konfiguracijo, ali če je bil njegov agent izbrisan
    started_atnizKdaj se je začel (ISO 8601, UTC)
    outcomenizno_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) ali answered (klic je bil prevzet; še ni znano, kdo ga je prevzel)
  2. 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.

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

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

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.

PoljeVrednostiKaj uravnava
intelligencecore, pro (privzeto)Core je cenejši in začne odgovarjati prej; Pro zanesljiveje sledi dolgim pozivom
audio_tierlite, standard (privzeto), plus, maxViš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)
endpointingfaster, fast, normal (privzeto), patientKrajše čakanje odgovori prej in stane več
faster_repliestrue (privzeto), falsePospešitev hitrosti: odgovori nekoliko prej, za nekoliko višjo ceno

Povezano