ThunderPhone 2.0 on nüüd saadaval.Iseteenindusena alates 2 senti/min.Loe uudist

Webhooks

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äliTüüpKirjeldus
call_idintegerKõne ID — püsib sama selle kõne kõigi sündmuste korral
from_numberstringHelistaja E.164-number
to_numberstringE.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äliTüüpKirjeldus
call_idintegerKõne ID
origin_domainstringVidinat majutava lehe päritolu
publishable_key_prefixstringSeansi avanud avaldatava võtme esimesed märgid
language, primary_languagestringEsineb, kui vidina seansis taotleti keele ülekirjutamist
voicestringEsineb, kui vidina seansis taotleti hääle ülekirjutamist
website_contextstringEsineb, 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äliTüüpKohustuslikKirjeldus
promptstringjahHäälagenti juhtiv süsteemiviip
voicestringjahHää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
productstringeiVaikeväärtus on spark. Lubatud: spark, bolt, storm-base, storm-base-with-ack, storm-extra, storm-extra-with-ack
thinking_levelstringeiminimal, base (vaikimisi) või extra. Stormi toodete puhul kirjutatakse üle: storm-extra* sunnib kasutama extra, muud storm-* sunnivad kasutama base
audio_context_modestringeifull (vaikimisi) või reduced
watchdog_enabledbooleaneiLuba selle kõne järelevalve. Vaikeväärtus false
additional_audio_contextboolean | nulleiKaasa 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_modestringeinone, acknowledgement (vaikimisi) või tick
languagestringeiLühivorm primary_language jaoks
primary_languagestringeiKeelekood, normaliseeritud (vaikimisi en). Lahendamatud koodid lükkavad kõne tagasi
has_additional_languagesbooleaneiVaikeväärtus false
additional_languagesstringide massiiveiLisakeeled, millele häälagent võib üle minna
native_voice_switchingbooleaneiVaikevää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_trackstring | nulleiTaustaheli ID või null
acknowledgement_prompt_modestringeiauto (vaikimisi) või manual (Storm-with-ack toodete puhul)
acknowledgement_promptstringeiKasutatakse, kui acknowledgement_prompt_mode="manual"
silence_interval_secondsinteger | nullei5–120. Helistaja vaikuse sekundite arv enne kontrollpäringut
silence_max_checkinsinteger | nullei1–10
silence_checkins_enabledbooleaneiVaikeväärtus true
connect_tone_enabledbooleaneiVaikeväärtus false
voicemail_actionstringeiprompt (vaikimisi), hangup või message
voicemail_messagestringeiKasutatakse, kui voicemail_action="message"
agent_namestringeiKuvanimi, millest teavitatakse juhtpaneele ja vidinat
org_namestringeiOrganisatsiooni kuvanimi häälagendi persooni jaoks
toolsmassiiveiReasisesed funktsioonitööriistade skeemid (vt Funktsioonitööriistad)
call_idintegereiTaotluse 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

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

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

ToodeLatentsusArutlusvõimeKinnitus
sparkMadalaimPõhiline
boltMadalTäiustatud
storm-baseKeskmineTugev
storm-base-with-ackKeskmineTugevAutomaatne täitesõnum mõtlemise ajal
storm-extraKõrgemSügav
storm-extra-with-ackKõrgemSügavAutomaatne täitesõnum mõtlemise ajal

Seotud