Open in
Dinamička konfiguracija za svaki poziv
Odaberite agenta koji odgovara — ili izmijenite njegov upit i postavke — zasebno za svaki dolazni poziv, na temelju prilagođene logike u webhooku koji sami kontrolirate.
Prema zadanim postavkama svakom telefonskom broju i objavljivom ključu dodijeljen je statični agent. Kada trebate prilagodbu po pozivatelju ili po posjetitelju — VIP usmjeravanje, kontekst prijavljenog korisnika, A/B testove uputa — prijeđite na način webhooka i prepustite odluku svom poslužitelju.
Kako funkcionira
- Pretplatite se na događaj
telephony.incoming(telefon) iliweb.incoming(widget). Oba su blokirajuća webhooka: ThunderPhone čeka vaš odgovor prije nastavka poziva, najviše 13 sekundi za telefonski poziv (uključen je jedan ponovni pokušaj) i 10 sekundi za sesiju widgeta. - ThunderPhone vam šalje
{call_id, from_number, to_number}(sesije widgeta umjesto brojeva sadrže polja specifična za widget — pogledajte shemu zahtjeva). - Vaš poslužitelj odgovara konfiguracijom agenta (upit, glas, proizvod, alati, riječi). ThunderPhone tu konfiguraciju koristi za poziv.
- Ne postoji zamjenski agent. Ako vratite
{}ili nevažeću konfiguraciju ili zahtjev i dalje ne uspije nakon ponovnog pokušaja, telefonski se poziv odmah prekida i bilježi send_reasoninbound_config_webhook_failed; zahtjev za sesiju widgeta ne uspijeva.
1. Konfigurirajte odredište webhooka
Za telefonske brojeve pretplatite svoju krajnju točku na telephony.incoming:
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Prod call-incoming",
"url": "https://example.com/thunderphone/incoming",
"events": ["telephony.incoming"]
}'Odgovor uključuje jednokratni secret — spremite ga; upotrijebit ćete ga
za provjeru potpisa.
Za sesije widgeta izradite objavljivi ključ u mode="webhook"
s ugrađenim URL-om vaše krajnje točke:
curl -X POST https://api.thunderphone.com/v1/publishable-key \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Dynamic widget",
"mode": "webhook",
"webhook_url": "https://example.com/thunderphone/widget-incoming",
"allowed_domains": ["example.com"]
}'Widget će poslati POST zahtjev na ovaj URL pri svakom pokretanju sesije.
2. Implementirajte rukovatelj
Tri praktična pravila:
- Provjerite potpis pri svakom zahtjevu (pogledajte Provjera potpisa webhookova). Nemojte ovo preskočiti u razvojnom okruženju — ispravno ga postavite jednom i ponovno upotrebljavajte.
- Odgovorite brzo. Prvi pokušaj telefonskog poziva prekida se nakon 10 sekundi, a cijela razmjena nakon 13, pri čemu je svaka sekunda tišina za pozivatelja. Po potrebi izvršite dohvaćanja iz baze podataka, ali nemojte sinkrono pozivati nizvodne LLM-ove — ako želite dinamičko generiranje upita, unaprijed ih izračunajte i predmemorirajte.
- Ispravno primijenite rezervnu opciju. Za svako neočekivano stanje odgovorite zadanim
promptivoicevrijednostima (ili spremljenimagent_id). Vraćanje{}ili statusa pogreške prekida poziv.
import hashlib
import hmac
import json
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
def verify(body: bytes, sig: str) -> bool:
expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, sig or "")
@app.post("/thunderphone/incoming")
async def incoming(request: Request):
body = await request.body()
if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
raise HTTPException(401)
event = json.loads(body)
if event["type"] not in ("telephony.incoming", "web.incoming"):
return {} # fall back to default
caller = event["data"]["from_number"]
# Cheap DB lookup: is this a known VIP?
customer = lookup_customer(caller)
if customer and customer.tier == "vip":
return {
"prompt": f"You are a VIP concierge for {customer.name}. Be proactive…",
"voice": "john",
"product": "storm-base",
}
return {} # default agent handles non-VIPs
def lookup_customer(phone: str):
# ... your CRM integration ...
passimport crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
function verify(body, sig) {
const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex");
return sig &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}
app.post(
"/thunderphone/incoming",
express.raw({ type: "application/json" }),
async (req, res) => {
if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
const IMPORTANT_TYPES = new Set([
"telephony.incoming",
"web.incoming",
]);
if (!IMPORTANT_TYPES.has(event.type)) return res.json({});
const customer = await lookupCustomer(event.data.from_number);
if (customer?.tier === "vip") {
return res.json({
prompt: `You are a VIP concierge for ${customer.name}. Be proactive…`,
voice: "john",
product: "storm-base",
});
}
res.json({}); // fall back to default agent
},
);3. Shema odgovora
Tijelo odgovora točno odgovara shemi odgovora za dolazni poziv. Često korištena polja:
| Polje | Vrsta | Opis |
|---|---|---|
prompt | niz znakova (obavezno) | Sustavna uputa za agenta |
voice | niz znakova (obavezno) | ID glasa iz GET /v1/voices |
product | niz znakova | Pošaljite bolt. Zadana je vrijednost spark, starija vrijednost koja se i dalje prihvaća. |
background_track | niz znakova | null | ID ambijentalnog zvuka |
acknowledgement_prompt_mode | niz znakova | auto ili manual (samo starije vrijednosti proizvoda -with-ack) |
acknowledgement_prompt | niz znakova | Obavezno kada je način rada manual |
language_switching | niz znakova | Za višejezične agente, ask_first ili follow_caller |
tools | niz | Ugrađene sheme funkcijskih alata — pogledajte Funkcijski alati |
Zadržite spremljenog agenta i navedite varijable ili kontekst
Vratite {"agent_id": 12, "variables": {"name": "Ada"}} da biste koristili
spremljenog agenta te organizacije s podacima po pozivu. Njegov prompt može sadržavati {{name}} ili
{{name|Friend}}. Varijable webhooka spajaju se preko varijabli na razini zahtjeva; vrijednost null
koristi zadanu vrijednost rezerviranog mjesta ili prazan tekst ako nije naveden. Konačne
vrijednosti i nerazriješena imena prikazuju se u pojedinostima poziva i webhookovima dovršetka.
Dodajte context, niz slobodnog formata s najviše 20.000 znakova, kako biste agentu dali
kratke upute za ovaj poziv (bilješke iz vašeg CRM-a, razlog zbog kojeg očekujete poziv);
dodaje se nakon prompta u razgraničenom bloku.
Odgovori spremljenog agenta prihvaćaju samo agent_id, variables, context, timezone i language. Ako je prisutan prompt,
odgovor koristi umetnutu konfiguraciju i zanemaruje agent_id; umetnuti prompt i dalje mora biti valjan. Ako je vaš webhook vlastiti webhook dodijeljenog agenta za postavljanje poziva, možete izostaviti i agent_id te vratiti samo variables, context, timezone ili language kako biste za poziv zadržali tog dodijeljenog agenta (uključujući svako fiksiranje verzije). Odgovori umetnute
konfiguracije mogu također uključivati variables i context. Odgovori spremljenog agenta koriste
objavljenu A/B raspodjelu agenta za telefonske pozive i pozive widgeta, a zatim prikazuju varijable. Pogledajte varijable poziva
za ograničenja i podršku za API sesije. Blokirajuća konfiguracija dolazi iz naslijeđenog
URL-a telefonskog broja/organizacije ili ključa widgeta u načinu webhooka; dolazni događaji sustava krajnjih točaka samo su obavijesti.
Postavite vremensku zonu za svaki poziv
Jedan agent može odgovarati kontaktima u različitim vremenskim zonama. Dodajte timezone, IANA naziv, u odgovor spremljenog agenta ili umetnuti odgovor, a agent će za taj poziv navesti datum i vrijeme te ponuditi termine u toj zoni, ispred vlastite vremenske zone agenta:
{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}Pošaljite zonu umjesto vremenske oznake u variables: sat agenta nastavlja raditi tijekom poziva, a vrijeme koje proslijedite zastarijeva. Vrijednost koja nije IANA zona zanemaruje se, a poziv se povezuje u zoni agenta.
Postavite jezik za svaki poziv
Jedan agent može odgovarati na svakom od svojih jezika. Dodajte language, podržani
jezični kôd kao što je es (es-MX se čita kao es), uz agent_id i
poziv započinje na tom jeziku:
{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}Agent ga govori glasom za taj jezik: unosom
language_voices; u protivnom, ako je
uključen native_voice_switching, izvornim glasom na koji bi agent prešao za
taj jezik; u protivnom vlastitim glasom, ako taj glas govori taj jezik. U
nebilježenim pozivima ThunderPhone također reproducira obavijest o obradi uživo
na jeziku poziva. Ostali jezici agenta i njegov primarni jezik zatim ostaju
dostupni za prebacivanje. Ako nijedan od njih ne može govoriti taj jezik, poziv
ipak započinje na tom jeziku, uz zadani glas tog jezika (agent s prilagođenim
glasom zadržava ga) i bez drugih jezika. Ako se poziv kasnije tijekom poziva
prebaci na drugi jezik agenta, koristi i unos language_voices za taj jezik
kada su oba glasa kataloški glasovi; u protivnom vrijede uobičajena pravila
prebacivanja. Agenti s punim dupleksom razlikuju se: na bilo kojem podržanom
jeziku poziv zadržava vlastiti glas agenta, a language_voices i prebacivanje
na izvorni glas ne primjenjuju se. Odbija se samo kôd koji nije podržani jezik.
Widget i sesije u stvarnom vremenu koriste isto polje language.
Obrasci
Kontekst prijavljenog korisnika
U widgetima u načinu rada webhooka stranica posjetitelja već zna tko su
oni. Pozovite svoj webhook s parametrom niza upita koji SDK widgeta
prosljeđuje (?customer_id=123) i potražite kupca na poslužitelju.
A/B uvođenje upute
Prije nego što ovo ručno implementirate, imajte na umu da ThunderPhone ima ugrađenu
značajku Eksperimenti
(/dashboard/experiments i karticu A/B u alatu za izradu agenata) koja
definira varijante, raspodjeljuje promet i uspoređuje ishode po varijanti —
webhook nije potreban.
Ako vam je ipak potrebna kontrola na strani webhooka: raspršite call_id → spremnik;
poslužite uputu A za 0..49 i uputu B za 50..99. Zabilježite koji ste
spremnik odabrali u vlastitoj bazi podataka i kasnije ga povežite s ocjenom
dovršenog poziva.
Usmjeravanje prema vremenu
Radno vrijeme → agent za „podršku uživo”; izvan radnog vremena → agent za „primanje poruke”.
Jednostavno prebacivanje na temelju new Date().getUTCHours() u vašem rukovatelju.
Sljedeći koraci
Točne sheme zahtjeva i odgovora, uključujući svaki konfiguracijski ključ.
Jednom ispravno postavite HMAC; ponovno ga upotrebljavajte posvuda.
Kombinirajte dinamičko usmjeravanje s alatima po agentu.
Ponovni pokušaji, redoslijed, vremenska ograničenja.