Dünaamiline kõnepõhine seadistamine

Vali vastav häälagent või kirjuta selle juhis ja seaded ümber iga sissetuleva kõne jaoks eraldi, lähtudes sinu hallatavas veebikonksus olevast kohandatud loogikast.

Vaikimisi on igale telefoninumbrile ja avaldatavale võtmele määratud staatiline agent. Kui vajad helistajapõhist või külastajapõhist kohandamist — VIP-marsruutimist, sisselogitud kasutaja konteksti, A/B-viibetestimist — lülitu webhooki režiimi ja lase oma serveril otsustada.

Kuidas see toimib#

1. Telli sündmus telephony.incoming (telefon) või web.incoming (vidin). Mõlemad on blokeerivad webhookid: ThunderPhone ootab enne kõnega jätkamist sinu vastust kuni 10 sekundit.
2. ThunderPhone saadab sulle {call_id, from_number, to_number} (vidina seansid sisaldavad numbrite asemel vidinapõhiseid välju — vaata päringuskeemi).
3. Sinu server vastab agendi konfiguratsiooniga (viip, hääl, toode, tööriistad). ThunderPhone kasutab seda konfiguratsiooni kõne jaoks.
4. Kui tagastad {}, vastamine aegub või tekib viga, kasutatakse varuna staatiliselt määratud agenti. Turvaline vaikeseade.

1. Seadista webhooki sihtkoht#

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"]
  }'

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"]
  }'

2. Rakenda töötleja#

Kolm rusikareeglit:

• Kontrolli signatuuri igal päringul (vt Veebikonksu signatuuride kontrollimine). Ära jäta seda arenduses vahele — tee see üks kord õigesti ja kasuta uuesti.
• Vasta kiiresti. Kümme sekundit on kindel ülempiir ning iga sekund on helistaja jaoks vaikus. Vajaduse korral tee andmebaasipäringuid, kuid ära kutsu allavoolu LLM-e sünkroonselt — kui soovid dünaamilist viibageneratsiooni, arvuta see eelnevalt ja salvesta vahemällu.
• Kasuta puhast varuvarianti. Iga ootamatu olek peab tagastama {}, et staatiliselt määratud häälagent kõne käsitleks.

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 ...
    pass

import 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. Vastuse skeem#

Vastuse sisu vastab täpselt sissetuleva kõne vastuse skeemile. Levinud väljad:

Hoia salvestatud agenti ja edasta muutujaid#

Tagasta {"agent_id": 12, "variables": {"name": "Ada"}}, et kasutada selle organisatsiooni salvestatud agenti koos kõnepõhiste andmetega. Selle juhis võib sisaldada {{name}} või {{name|Friend}}. Veebikonksu muutujad liidetakse päringutaseme muutujate peale; null kasutab kohatäite vaikeväärtust või tühja teksti, kui vaikeväärtust pole määratud. Lõplikud väärtused ja lahendamata nimed kuvatakse kõne üksikasjades ning lõpetamise veebikonksudes. Salvestatud agendi vastused aktsepteerivad ainult agent_id ja variables. Kui prompt on olemas, kasutab vastus tekstisisest konfiguratsiooni ja ignoreerib agent_id-d (sealhulgas null- või mittetäisarvulisi metaandmeid); tekstisisene juhis peab siiski olema kehtiv. Tekstisisese konfiguratsiooni vastused võivad samuti sisaldada variables. Salvestatud agendi vastused kasutavad agendi avaldatud A/B-jaotust nii telefoni- kui ka vidinakõnedes ning seejärel renderdavad muutujad. Piirangute ja seansi API toe kohta vaata kõnemuutujaid. Blokeeriv konfiguratsioon pärineb pärandtelefoninumbri/organisatsiooni URL-ist või veebikonksurežiimis vidina võtmest; lõpp-punkti süsteemi sissetulevad sündmused on ainult teavitused.

Mustrite näited#

Sisselogitud kasutaja kontekst#

Veebikonksurežiimis vidinates teab külastaja leht juba, kes ta on. Kutsu oma veebikonks välja päringustringi parameetriga, mille vidina SDK edastab (?customer_id=123), ja otsi klient serveripoolel üles.

A/B-juhise kasutuselevõtt#

Enne kui selle ise käsitsi lahendad, pane tähele, et ThunderPhone'il on sisseehitatud eksperimentide funktsioon (/dashboard/experiments ja agendiehitaja A/B vahekaart), mis määratleb variandid, jagab liikluse ja võrdleb tulemusi variantide kaupa — veebikonksu pole vaja.

Kui vajad siiski veebikonksupoolset juhtimist: räsi call_id → ämber; serveeri juhist A väärtustele 0..49 ja juhist B väärtustele 50..99. Salvesta, millise ämbri valisid, oma andmebaasi ning korreleeri see hiljem lõpetatud kõne hindega.

Ajapõhine suunamine#

Tööajal → „otseabi” agent; väljaspool tööaega → „võta sõnum” agent. Puhtalt lüliti new Date().getUTCHours() põhjal sinu töötlejas.

Järgmised sammud#