telephony.incoming / web.incoming

Kai įeinantis telefono skambutis pasiekia numerį be priskirto agento arba žiniatinklio valdiklio sesija pradedama naudojant viešinį raktą su mode="webhook", ThunderPhone siunčia blokuojančią telephony.incoming / web.incoming užklausą į jūsų senąjį žiniatinklio kablio URL ir laukia iki 10 sekundžių konfigūracijos atsakymo. Naudokite šį apsikeitimą, kad kiekvienam skambučiui dinamiškai parinktumėte raginimą, balsą ir įrankius — visą procesą rasite dinaminio skambučio konfigūravimo vadove.

Blokuojantis apsikeitimas neturi atsarginio varianto: jei jūsų apdorotojas grąžina ne 2xx būseną, baigiasi jo laikas arba jis grąžina konfigūraciją, kuri nepraeina tikrinimo, skambutis atmetamas (telefono skambutis neprisijungia; valdiklio sesijos užklausa nepavyksta su 502/422). Atsakykite greitai — kol sprendžiate, skambintojas girdi skambučio signalą.

Užklausos duomenys

Telefono skambučiams (telephony.incoming):

{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567"
  }
}

Žiniatinklio valdiklio sesijoms (web.incoming) data identifikuoja įterpimo puslapį, o ne telefono numerius:

{
  "type": "web.incoming",
  "data": {
    "call_id": 987654322,
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2"
  }
}

Atsako schema

Grąžinkite JSON objektą, aprašantį šio skambučio agento konfigūraciją. prompt ir voice yra privalomi; visa kita neprivaloma.

{
  "prompt":  "You are a helpful booking assistant for Acme Restaurant.",
  "voice":   "john",
  "product": "spark",
  "background_track": null,
  "tools":   []
}

Kadangi prompt ir voice yra privalomi, grąžinus {} arba bet kokį validavimo neatitinkantį atsaką, skambutis atmetamas su 422 — šiame kelyje nėra statinio agento atsarginio varianto (numeriui arba raktui žiniatinklio kablio režimu nėra priskirtas agentas).

Atsako dydžio riba

Pavyzdinė apdorojimo funkcija

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

Atsakymas su funkcijų įrankiais

Pridėkite įrankius, kad DI galėtų iškviesti jūsų API pokalbio metu:

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

Produktų lygių atmintinė

Susiję