Open in
Dinaminė konfigūracija kiekvienam skambučiui
Kiekvienam įeinančiam skambučiui atskirai pasirinkite atsiliepiantį agentą arba pakeiskite jo raginimą ir nustatymus, remdamiesi pasirinkta logika jūsų valdomame webhook.
Pagal numatytuosius nustatymus kiekvienam telefono numeriui ir viešajam raktui priskiriamas statinis agentas. Kai reikia tinkinti kiekvienam skambintojui arba kiekvienam lankytojui — nukreipti VIP klientus, įtraukti prisijungusio naudotojo kontekstą, atlikti A/B raginimų bandymus — perjunkite į žiniatinklio kabliuko režimą ir leiskite spręsti savo serveriui.
Kaip tai veikia
- Užsiprenumeruokite
telephony.incoming(telefono) arbaweb.incoming(valdiklio) įvykį. Abu yra blokuojamieji žiniatinklio kabliai: ThunderPhone laukia jūsų atsakymo prieš tęsdamas skambutį — iki 13 sekundžių telefono skambučiui (įskaičiuotas vienas pakartotinis bandymas) ir 10 sekundžių valdiklio seansui. - ThunderPhone siunčia jums
{call_id, from_number, to_number}(valdiklio seansuose vietoj numerių pateikiami valdikliui būdingi laukai — žr. užklausos schemą). - Jūsų serveris atsako agento konfigūracija (nurodymai, balsas, produktas, įrankiai, žodžiai). ThunderPhone naudoja šią konfigūraciją skambučiui.
- Atsarginio agento nėra. Jei grąžinate
{}arba netinkamą konfigūraciją arba užklausa vis tiek nepavyksta po pakartotinio bandymo, telefono skambutis nedelsiant nutraukiamas ir užregistruojamas suend_reasoninbound_config_webhook_failed; valdiklio seanso užklausa nepavyksta.
1. Sukonfigūruokite žiniatinklio kabliuko paskirties vietą
Telefono numeriams užsiprenumeruokite savo galinį tašką įvykiui 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"]
}'Atsakyme pateikiamas vienkartinis secret — išsaugokite jį; naudosite jį
parašo tikrinimui.
Valdiklio sesijoms sukurkite viešąjį raktą su mode="webhook",
kuriame įtraukta jūsų galinio taško URL:
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"]
}'Valdiklis siųs POST užklausą į šį URL kiekvienos sesijos pradžioje.
2. Įdiekite tvarkytuvę
Trys pagrindinės taisyklės:
- Patikrinkite parašą kiekvienoje užklausoje (žr. Tikrinkite žiniatinklio kablio parašus). Nepraleiskite šio veiksmo kūrimo aplinkoje — tinkamai įgyvendinkite vieną kartą ir naudokite pakartotinai.
- Atsakykite greitai. Pirmasis telefono skambučio bandymas nutraukiamas po 10 sekundžių, o visas apsikeitimas — po 13, todėl kiekviena sekundė skambinančiajam yra tyla. Jei reikia, atlikite duomenų bazės užklausas, tačiau nekvieskite paskesnių LLM sinchroniškai — jei norite dinamiškai generuoti raginimus, iš anksto juos apskaičiuokite ir išsaugokite talpykloje.
- Tvarkingai naudokite atsarginį variantą. Esant bet kokiai netikėtai būsenai, atsakykite
numatytaisiais
promptirvoice(arba išsaugotuagent_id). Grąžinus{}arba klaidos būseną, skambutis nutraukiamas.
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. Atsakymo schema
Atsakymo turinys tiksliai atitinka įeinančio skambučio atsakymo schemą. Dažniausiai naudojami laukai:
| Laukas | Tipas | Aprašymas |
|---|---|---|
prompt | eilutė (privaloma) | Sisteminė agento instrukcija |
voice | eilutė (privaloma) | Balso identifikatorius iš GET /v1/voices |
product | eilutė | Siųskite bolt. Numatytoji reikšmė yra spark – senesnė reikšmė, kuri vis dar priimama. |
background_track | eilutė | null | Aplinkos garso identifikatorius |
acknowledgement_prompt_mode | eilutė | auto arba manual (tik senesnėms -with-ack produkto reikšmėms) |
acknowledgement_prompt | eilutė | Privaloma, kai režimas yra manual |
language_switching | eilutė | Daugiakalbiams agentams: ask_first arba follow_caller |
tools | masyvas | Įterptinės funkcijų įrankių schemos – žr. Funkcijų įrankiai |
Išsaugokite agentą ir pateikite kintamuosius arba kontekstą
Grąžinkite {"agent_id": 12, "variables": {"name": "Ada"}}, kad naudotumėte tos organizacijos
išsaugotą agentą su kiekvieno skambučio duomenimis. Jo raginime gali būti {{name}} arba
{{name|Friend}}. Žiniatinklio kablio kintamieji sujungiami su užklausos lygio kintamaisiais; reikšmė null
naudoja vietaženklio numatytąją reikšmę arba tuščią tekstą, jei ji nepateikta. Galutinės
reikšmės ir neišspręsti pavadinimai rodomi skambučio išsamioje informacijoje ir užbaigimo žiniatinklio kabliuose.
Pridėkite context – laisvos formos eilutę, sudarytą ne daugiau kaip iš 20 000 simbolių, kad suteiktumėte agentui
informaciją apie šį skambutį (pastabas iš jūsų CRM, priežastį, dėl kurios tikitės skambučio);
ji pridedama po raginimo atskirtame bloke.
Išsaugoto agento atsakymai priima tik agent_id, variables, context, timezone ir language. Jei yra prompt,
atsakyme naudojama įterptinė konfigūracija ir nepaisoma agent_id; įterptinis raginimas vis tiek turi būti galiojantis. Jei jūsų žiniatinklio kablys yra priskirto agento skambučio nustatymo žiniatinklio kablys, taip pat galite nenurodyti agent_id ir grąžinti tik variables, context, timezone arba language, kad skambučiui išlaikytumėte tą priskirtą agentą (įskaitant bet kokį versijos fiksavimą). Įterptinės
konfigūracijos atsakymai taip pat gali apimti variables ir context. Išsaugoto agento atsakymuose naudojamas
diegto agento A/B paskirstymas tiek telefono, tiek valdiklio skambučiams, tada atvaizduojami kintamieji. Žr. skambučio kintamieji
apribojimams ir sesijos API palaikymui. Blokuojanti konfigūracija gaunama iš senstelėjusio
telefono numerio / organizacijos URL arba valdiklio režimo valdiklio rakto; galinių taškų sistemos
gaunami įvykiai yra tik pranešimai.
Nustatykite laiko juostą kiekvienam skambučiui
Vienas agentas gali atsiliepti kontaktams skirtingose laiko juostose. Pridėkite timezone – IANA pavadinimą – prie išsaugoto agento arba įterptinio atsakymo, ir šio skambučio metu agentas nurodys datą bei laiką ir pasiūlys laikus toje juostoje, o ne savo laiko juostoje:
{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}Siųskite juostą, o ne laiko žymą per variables: skambučio metu agento laikrodis veikia toliau, todėl jūsų perduotas laikas pasensta. Reikšmė, kuri nėra IANA laiko juosta, ignoruojama, o skambutis sujungiamas naudojant agento laiko juostą.
Nustatykite kalbą kiekvienam skambučiui
Vienas agentas gali atsakyti kiekviena savo kalba. Pridėkite language – palaikomos
kalbos kodą, pvz., es (es-MX skaitomas kaip es) – šalia agent_id, ir
skambutis pradedamas ta kalba:
{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}Agentas kalba šia kalba naudodamas tai kalbai skirtą balsą: savo
language_voices įrašą; kitu atveju, jei
įjungtas native_voice_switching, gimtąjį balsą, į kurį agentas persijungtų
tai kalbai; kitu atveju savo balsą, jei tas balsas kalba šia kalba. Neįrašomuose
skambučiuose ThunderPhone taip pat paleidžia tiesioginio apdorojimo pranešimą
skambučio kalba. Tada kitos agento kalbos ir jo pagrindinė kalba lieka
prieinamos perjungti. Jei nė viena iš jų negali kalbėti šia kalba, skambutis vis
tiek pradedamas šia kalba, naudojant numatytąjį tos kalbos balsą (agentas su
tinkintu balsu jį išlaiko) ir be kitų kalbų. Jei vėliau skambučio metu
persijungiama į kitą agento kalbą, taip pat naudojamas tos kalbos
language_voices įrašas, kai abu balsai yra katalogo balsai; kitu atveju
taikomos įprastos perjungimo taisyklės. Viso duplekso agentams taikoma kita
tvarka: bet kuria palaikoma kalba skambutis išlaiko paties agento balsą, o
language_voices ir gimtojo balso perjungimas netaikomi. Atmetamas tik kodas,
kuris nėra palaikomos kalbos kodas. Valdiklio ir realiojo laiko seansuose
naudojamas tas pats language laukas.
Modeliai
Prisijungusio naudotojo kontekstas
Žiniatinklio kablio režimo valdikliuose lankytojo puslapis jau žino, kas jis
yra. Iškvieskite savo žiniatinklio kablį su užklausos eilutės parametru, kurį
valdiklio SDK persiunčia (?customer_id=123), ir suraskite klientą serverio pusėje.
A/B raginimų diegimas
Prieš kurdami tai patys, atkreipkite dėmesį, kad ThunderPhone turi vietinę
eksperimentų funkciją
(/dashboard/experiments ir agento kūrimo priemonės A/B skirtuką), kuri
apibrėžia variantus, paskirsto srautą ir palygina kiekvieno varianto rezultatus —
žiniatinklio kablio nereikia.
Jei vis tiek reikia valdymo žiniatinklio kablio pusėje: maišykite call_id → segmentas;
pateikite raginimą A reikšmėms 0..49 ir raginimą B reikšmėms 50..99. Įrašykite pasirinktą
segmentą savo DB ir vėliau susiekite jį su užbaigto skambučio įvertinimu.
Maršrutizavimas pagal laiką
Darbo valandos → „tiesioginio palaikymo“ agentas; ne darbo valandomis → „priimti žinutę“
agentas. Tvarkyklėje tiesiog perjunkite pagal new Date().getUTCHours().
Tolesni veiksmai
Tikslios užklausų ir atsakymų schemos, įskaitant kiekvieną konfigūracijos raktą.
Vieną kartą teisingai nustatykite HMAC; naudokite visur.
Derinkite dinaminį maršrutizavimą su agentui skirtais įrankiais.
Pakartotiniai bandymai, tvarka, laiko limitai.