Open in
Dinamična konfiguracija za posamezen klic
Za vsak dohodni klic posebej izberite odgovarjajočega agenta ali prepišite njegov poziv in nastavitve na podlagi logike po meri v spletnem kavlju, ki ga upravljate vi.
Vsaki telefonski številki in ključu za objavo je privzeto dodeljen statični agent. Ko potrebujete prilagoditev za posameznega klicatelja ali za posameznega obiskovalca — usmerjanje VIP, kontekst prijavljenega uporabnika, A/B-preizkuse pozivov — preklopite v način webhook in prepustite odločitev strežniku.
Kako deluje
- Naročite se na dogodek
telephony.incoming(telefon) aliweb.incoming(pripomoček). Oba sta blokirajoča spletna kavlja: ThunderPhone pred nadaljevanjem klica čaka na vaš odgovor, do 13 sekund za telefonski klic (vključen je en ponovni poskus) in 10 sekund za sejo pripomočka. - ThunderPhone vam pošlje
{call_id, from_number, to_number}(seje pripomočka namesto številk vsebujejo polja, značilna za pripomoček — glejte shemo zahteve). - Vaš strežnik odgovori s konfiguracijo agenta (poziv, glas, izdelek, orodja, besede). ThunderPhone to konfiguracijo uporabi za klic.
- Nadomestni agent ne obstaja. Če vrnete
{}ali neveljavno konfiguracijo oziroma zahteva tudi po ponovnem poskusu še vedno ne uspe, se telefonski klic takoj konča in zabeleži zend_reasoninbound_config_webhook_failed; zahteva za sejo pripomočka ne uspe.
1. Konfigurirajte cilj webhooka
Za telefonske številke naročite svojo končno točko 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 vključuje enkratni secret — shranite ga; uporabili ga boste
za preverjanje podpisa.
Za seje gradnika ustvarite ključ za objavo v mode="webhook"
z vdelanim URL-jem vaše končne 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"]
}'Gradnik bo ob vsakem začetku seje na ta URL poslal zahtevo POST.
2. Implementirajte obdelovalnik
Tri osnovna pravila:
- Preverite podpis pri vsaki zahtevi (glejte Preverjanje podpisov spletnih kavljev). Tega ne preskočite v razvojnem okolju — enkrat uredite pravilno in znova uporabite.
- Odgovorite hitro. Prvi poskus telefonskega klica se prekine po 10 sekundah, celotna izmenjava pa po 13 sekundah, vsaka sekunda pa je za klicatelja tišina. Po potrebi izvedite poizvedbe v zbirki podatkov, vendar podrejenih LLM-jev ne kličite sinhrono — če želite dinamično ustvarjanje poziva, ga vnaprej izračunajte in shranite v predpomnilnik.
- Ustrezno uporabite nadomestno možnost. Za vsako nepričakovano stanje odgovorite s
privzetima
promptinvoice(ali shranjenimagent_id). Vrnitev{}ali statusa napake prekine klic.
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
Telo odgovora se natančno ujema s shemo odgovora za dohodni klic. Pogosto uporabljena polja:
| Polje | Vrsta | Opis |
|---|---|---|
prompt | niz (obvezno) | Sistemski poziv za agenta |
voice | niz (obvezno) | ID glasu iz GET /v1/voices |
product | niz | Pošljite bolt. Privzeta vrednost je spark, starejša vrednost, ki je še vedno podprta. |
background_track | niz | null | ID ambientalnega zvoka |
acknowledgement_prompt_mode | niz | auto ali manual (samo pri starejših vrednostih izdelka -with-ack) |
acknowledgement_prompt | niz | Obvezno, kadar je način manual |
language_switching | niz | Za večjezične agente: ask_first ali follow_caller |
tools | polje | Vdelane sheme funkcijskih orodij — glejte Funkcijska orodja |
Obdržite shranjenega agenta in posredujte spremenljivke ali kontekst
Vrnite {"agent_id": 12, "variables": {"name": "Ada"}}, da uporabite shranjenega agenta te organizacije s podatki za posamezen klic. Njegov poziv lahko vsebuje {{name}} ali
{{name|Friend}}. Spremenljivke webhooka se združijo s spremenljivkami na ravni zahteve; vrednost null
uporabi privzeto vrednost nadomestnega mesta oziroma prazno besedilo, če ni navedena nobena. Končne
vrednosti in nerazrešena imena so prikazani v podrobnostih klica in webhookih ob zaključku.
Dodajte context, niz poljubne oblike z do 20.000 znaki, da agentu zagotovite
kratek opis za ta klic (opombe iz vašega CRM-ja, razlog, zakaj klic pričakujete);
dodan je za pozivom v razmejenem bloku.
Odgovori shranjenega agenta sprejemajo samo agent_id, variables, context, timezone in language. Če je prisoten prompt,
odgovor uporabi vdelano konfiguracijo in prezre agent_id; vdelani poziv mora biti še vedno veljaven. Če je vaš webhook lastni webhook za nastavitev klica dodeljenega agenta, lahko izpustite tudi agent_id in vrnete samo variables, context, timezone ali language, da za klic ohranite tega dodeljenega agenta (vključno z morebitno pripeto različico). Odgovori vdelane
konfiguracije lahko vključujejo tudi variables in context. Odgovori shranjenega agenta uporabijo
razporeditev A/B, uvedeno za agenta, pri telefonskih klicih in klicih iz gradnika, nato pa prikažejo spremenljivke. Za omejitve in podporo API-ja sej glejte spremenljivke klica.
Blokirna konfiguracija prihaja iz podedovanega URL-ja telefonske številke/organizacije ali ključa gradnika v načinu webhooka; dohodni dogodki sistema končnih točk so zgolj obvestila.
Nastavite časovni pas za posamezen klic
En agent lahko odgovarja stikom v različnih časovnih pasovih. Shranjenemu agentu ali vdelanemu odgovoru dodajte timezone, ime IANA, in agent za ta klic navede datum in čas ter ponudi termine v tem pasu, ne glede na agentov lastni časovni pas:
{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}Namesto časovnega žiga v variables pošljite pas: ura agenta med klicem teče naprej, zato čas, ki ga posredujete, zastara. Vrednost, ki ni časovni pas IANA, se prezre, klic pa se poveže v časovnem pasu agenta.
Nastavite jezik za posamezen klic
En agent lahko odgovarja v vsakem od svojih jezikov. Dodajte language, podprto
jezikovno kodo, kot je es (es-MX se prebere kot es), ob agent_id in
klic se začne v tem jeziku:
{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}Agent ga govori z glasom za ta jezik: z vnosom
language_voices; sicer, če je vklopljena možnost
native_voice_switching, z izvornim glasom, na katerega bi agent preklopil za
ta jezik; sicer z lastnim glasom, kadar ta glas govori jezik. Pri nesnemanih
klicih ThunderPhone predvaja tudi obvestilo o obdelavi v živo v jeziku klica.
Nato ostanejo za preklapljanje na voljo drugi jeziki agenta in njegov primarni
jezik. Če nobeden od njih ne more govoriti tega jezika, se klic vseeno začne v tem
jeziku s privzetim glasom za ta jezik (agent z glasom po meri ga ohrani) in brez
drugih jezikov. Če klic pozneje med klicem preklopi na drug jezik agenta, uporabi
tudi vnos language_voices za ta jezik, kadar sta oba glasova kataloška glasova;
sicer veljajo običajna pravila preklapljanja. Agenti s polnim dupleksom so drugačni:
v katerem koli podprtem jeziku klic ohrani lastni glas agenta, language_voices
in preklapljanje na izvorni glas pa ne veljata. Zavrnjena je samo koda, ki ne
predstavlja podprtega jezika. Seja gradnika in seja v realnem času uporabljata isto
polje language.
Vzorci
Kontekst prijavljenega uporabnika
V gradnikih v načinu webhooka stran obiskovalca že ve, kdo je
obiskovalec. Pokličite svoj webhook s parametrom poizvedbenega niza, ki ga SDK
gradnika posreduje naprej (?customer_id=123), in stranko poiščite na strežniški
strani.
Uvajanje pozivov A/B
Preden to sami implementirate, upoštevajte, da ima ThunderPhone vgrajeno
funkcijo Poskusi
(/dashboard/experiments in zavihek A/B v gradniku agenta), ki
določa različice, razdeli promet in primerja rezultate za posamezno različico —
webhook ni potreben.
Če vseeno potrebujete nadzor na strani webhooka: zgostite call_id → segment;
za 0..49 uporabite poziv A, za 50..99 pa poziv B. Izbrani segment
zabeležite v lastni zbirki podatkov in ga pozneje povežite z oceno
zaključenega klica.
Usmerjanje glede na čas
Delovni čas → agent za »podporo v živo«; zunaj delovnega časa → agent za
»sprejem sporočil«. V obdelovalniku preprosto preklopite glede na
new Date().getUTCHours().
Naslednji koraki
Natančne sheme zahtev in odgovorov, vključno z vsakim konfiguracijskim ključem.
Enkrat pravilno nastavite HMAC; uporabite ga povsod.
Združite dinamično usmerjanje z orodji za posamezne agente.
Ponovni poskusi, vrstni red, časovne omejitve.