telephony.incoming / web.incoming

Bloķējošs tīmekļa aizķeres punkts, kas reāllaikā konfigurē ienākošo zvanu.

Kad ienākošs tālruņa zvans sasniedz numuru bez piešķirta balss aģenta vai tīmekļa logrīka sesija tiek sākta ar publicējamu atslēgu režīmā mode="webhook", ThunderPhone nosūta bloķējošu telephony.incoming / web.incoming pieprasījumu uz jūsu veco tīmekļa aizķeres URL un gaida konfigurācijas atbildi: līdz 13 sekundēm tālruņa zvanam, ieskaitot vienu atkārtotu mēģinājumu, un līdz 10 sekundēm logrīka sesijai (skatiet Noildzes un atkārtoti mēģinājumi). Izmantojiet šo apmaiņu, lai katram zvanam dinamiski izvēlētos uzvedni, balsi un rīkus — skatiet dinamiskās zvanu konfigurācijas ceļvedi, lai iepazītos ar pilnu procesu.

Noildzes un atkārtoti mēģinājumi#

Atbildiet ātri: zvanītājs gaida līnijā, kamēr pieņemat lēmumu.

Tālruņa zvanam (telephony.incoming):

• Pirmais mēģinājums var ilgt līdz 10 sekundēm.
• Ja tas pārsniedz noildzi, nevar izveidot savienojumu vai saņem 5xx, 408 vai 429 atbildi, ThunderPhone mēģina vēlreiz. Atkārtotajam mēģinājumam tiek piešķirts viss, kas atlicis no 13 sekunžu budžeta visai apmaiņai: aptuveni 3 sekundes pēc pirmā mēģinājuma, kam iestājās noildze, un gandrīz visas 13 sekundes pēc ātras kļūmes. Atkārtots mēģinājums netiek veikts, ja atliktu mazāk par 2 sekundēm.
• Jebkura cita 4xx atbilde, atbilde, kas pārsniedz izmēra ierobežojumu, vai 2xx atbilde, kuras pamatteksts nav derīga konfigurācija, ir galīga un netiek atkārtota.
• Abi mēģinājumi nosūta vienādu pamattekstu, vienādu X-ThunderPhone-Signature un vienādu X-ThunderPhone-Idempotency-Key galveni (telephony-incoming-<call_id>), tādēļ apstrādātājs ar blakusietekmēm var atpazīt atkārtoto mēģinājumu.

Nav rezerves balss aģenta. Ja netiek saņemta izmantojama konfigurācija, zvans tiek nekavējoties pārtraukts, nevis zvanītājs tiek atstāts klusā līnijā. Zvanu vēsturē tas tiek rādīts kā neveiksmīgs zvans, par kuru netiek iekasēta maksa, ar end_reason inbound_config_webhook_failed, un tiek nosūtīts parastais telephony.complete notikums.

Logrīka sesijai (web.incoming) ir viens mēģinājums, kas var ilgt līdz 10 sekundēm. Ja tas neizdodas, sesijas pieprasījums neizdodas ar 502 vai 422.

Pieprasījuma dati#

Tālruņa zvaniem (telephony.incoming):

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

Tīmekļa logrīka sesijām (web.incoming) data tālruņa numuru vietā identificē iegulšanas lapu:

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

Pārrakstīšanas lauki (language, voice, website_context un jebkuri pārlūka variables) tiek saņemti tikai tad, ja publicējamā atslēga tos atļauj savos pārlūka pārrakstījumos. Sesijas pieprasījums, kas ietver kādu vērtību, kuru atslēga neatļauj, tiek noraidīts, pirms tiek izsaukts šis tīmekļa aizķeres punkts.

Atbildes shēma#

Atgrieziet JSON objektu, kas apraksta balss aģenta konfigurāciju šim zvanam. prompt un voice ir obligāti; viss pārējais nav obligāts.

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

Tā kā prompt un voice ir obligāti, {} vai jebkura atbilde, kas neiztur validāciju, noraida zvanu: tālruņa zvans tiek beigts, kā aprakstīts sadaļā Noildzes un atkārtoti mēģinājumi, un logrīka sesijas pieprasījums neizdodas ar 422. Šajā ceļā nav rezerves statiskā balss aģenta (numuram vai atslēgai tīmekļa aizķeres režīmā nav piešķirta balss aģenta).

Atbildes lieluma ierobežojums#

Apstrādātāja piemērs#

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

Atbilde ar funkciju rīkiem#

Pievienojiet rīkus, lai AI varētu izsaukt jūsu API sarunas laikā:

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

Produkta līmeņu īsā atsauce#

Saistītie materiāli#