Open in
telephony.incoming / web.incoming
Blokeeriv veebikonks, mis kujundab sissetuleva kõne konfiguratsiooni reaalajas.
Kui sissetulev telefonikõne jõuab numbrini ilma määratud
agendita või veebividina seanss algab avaldatava võtmega
mode="webhook", saadab ThunderPhone sinu
pärandveebihaagi URL-ile
blokeeriva telephony.incoming / web.incoming päringu ja ootab
konfiguratsioonivastust kuni 10 sekundit. Kasuta seda
andmevahetust, et valida iga kõne jaoks dünaamiliselt viip, hääl ja
tööriistad — täielikku mustrit vaata
dünaamilise kõnekonfiguratsiooni juhendist.
Blokeerival andmevahetusel puudub varuvariant: kui sinu töötleja tagastab
muu olekukoodi kui 2xx, aegub või tagastab valideerimisel ebaõnnestuva
konfiguratsiooni, lükatakse kõne tagasi (telefonikõne ei ühendata;
vidina seansipäring nurjub koodiga 502/422). Vasta kiiresti — kuni
otsustad, kuuleb helistaja kutsungit.
Päringu sisu
Telefonikõnede jaoks (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| Väli | Tüüp | Kirjeldus |
|---|---|---|
call_id | integer | Kõne ID — püsib sama selle kõne kõigi sündmuste korral |
from_number | string | Helistaja E.164-number |
to_number | string | E.164 sihtnumber (üks sinu ThunderPhone'i numbritest) |
Veebividina seansside puhul (web.incoming) tuvastab data
telefoninumbrite asemel manustatud lehe:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| Väli | Tüüp | Kirjeldus |
|---|---|---|
call_id | integer | Kõne ID |
origin_domain | string | Vidinat majutava lehe päritolu |
publishable_key_prefix | string | Seansi avanud avaldatava võtme esimesed märgid |
language, primary_language | string | Esineb, kui vidina seansis taotleti keele ülekirjutamist |
voice | string | Esineb, kui vidina seansis taotleti hääle ülekirjutamist |
website_context | string | Esineb, kui vidin edastas seansipõhise lehekonteksti |
Vastuse skeem
Tagasta JSON-objekt, mis kirjeldab selle kõne häälagendi konfiguratsiooni.
prompt ja voice on kohustuslikud; kõik muu on valikuline.
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| Väli | Tüüp | Kohustuslik | Kirjeldus |
|---|---|---|---|
prompt | string | jah | Häälagenti juhtiv süsteemiviip |
voice | string | jah | Hääle ID asukohast GET /v1/voices, nt john. Aliaseks aktsepteeritakse voice_name. Tundmatud hääled ei läbi valideerimist ja kõne lükatakse tagasi |
product | string | ei | Vaikeväärtus on spark. Lubatud: spark, bolt, storm-base, storm-base-with-ack, storm-extra, storm-extra-with-ack |
thinking_level | string | ei | minimal, base (vaikimisi) või extra. Stormi toodete puhul kirjutatakse üle: storm-extra* sunnib kasutama extra, muud storm-* sunnivad kasutama base |
audio_context_mode | string | ei | full (vaikimisi) või reduced |
watchdog_enabled | boolean | ei | Luba selle kõne järelevalve. Vaikeväärtus false |
additional_audio_context | boolean | null | ei | Kaasa helistaja heli viimased mõned voorud, mitte ainult kõige hiljutisem voor; see parandab paranduste ning õigekirja- või numbrimahuka andmekogumise täpsust väikese latentsuse- ja kululisaga. Sissetulevate seansside puhul on vaikimisi sisse lülitatud ning väljaminevate telefonikõnede puhul välja lülitatud; null säilitab vaikeväärtuse |
storm_feedback_mode | string | ei | none, acknowledgement (vaikimisi) või tick |
language | string | ei | Lühivorm primary_language jaoks |
primary_language | string | ei | Keelekood, normaliseeritud (vaikimisi en). Lahendamatud koodid lükkavad kõne tagasi |
has_additional_languages | boolean | ei | Vaikeväärtus false |
additional_languages | stringide massiiv | ei | Lisakeeled, millele häälagent võib üle minna |
native_voice_switching | boolean | ei | Vaikeväärtus false. Kui kõne läheb üle teisele keelele, vaheta sellele keelele omase hääle vastu (sobitatud soo järgi), selle asemel et säilitada konfigureeritud hääl |
background_track | string | null | ei | Taustaheli ID või null |
acknowledgement_prompt_mode | string | ei | auto (vaikimisi) või manual (Storm-with-ack toodete puhul) |
acknowledgement_prompt | string | ei | Kasutatakse, kui acknowledgement_prompt_mode="manual" |
silence_interval_seconds | integer | null | ei | 5–120. Helistaja vaikuse sekundite arv enne kontrollpäringut |
silence_max_checkins | integer | null | ei | 1–10 |
silence_checkins_enabled | boolean | ei | Vaikeväärtus true |
connect_tone_enabled | boolean | ei | Vaikeväärtus false |
voicemail_action | string | ei | prompt (vaikimisi), hangup või message |
voicemail_message | string | ei | Kasutatakse, kui voicemail_action="message" |
agent_name | string | ei | Kuvanimi, millest teavitatakse juhtpaneele ja vidinat |
org_name | string | ei | Organisatsiooni kuvanimi häälagendi persooni jaoks |
tools | massiiv | ei | Reasisesed funktsioonitööriistade skeemid (vt Funktsioonitööriistad) |
call_id | integer | ei | Taotluse kõne ID valikuline kajastus; ignoreeritakse |
Kuna prompt ja voice on kohustuslikud, lükkab {} või mis tahes
valideerimist mitte läbiv vastus kõne tagasi koodiga 422 — sellel
teel puudub staatilise häälagendi varuvariant (veebikonksu režiimis
olevale numbrile või võtmele ei ole häälagenti määratud).
Vastuse suuruse piirang
Näidistöötleja
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 {}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({});
},
);Vastus funktsioonitööriistadega
Lisa tööriistad, et tehisintellekt saaks vestluse ajal sinu API-sid kasutada:
{
"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"
}
}
}
]
}Toote tasemete kiirülevaade
| Toode | Latentsus | Arutlusvõime | Kinnitus |
|---|---|---|---|
spark | Madalaim | Põhiline | — |
bolt | Madal | Täiustatud | — |
storm-base | Keskmine | Tugev | — |
storm-base-with-ack | Keskmine | Tugev | Automaatne täitesõnum mõtlemise ajal |
storm-extra | Kõrgem | Sügav | — |
storm-extra-with-ack | Kõrgem | Sügav | Automaatne täitesõnum mõtlemise ajal |
Seotud
Mitteblokeeriv kõne lõppemise sündmus.
Täielik JSON-skeem tools[] jaoks ja allkirjastatud lõpp-punkti leping.
Telli mitu URL-i sündmustele telephony.incoming / web.incoming.
Mustrid helistajapõhiste viipade, tööriistade ja A/B-testide jaoks.