telephony.incoming / web.incoming

Blockerande webhook som formar konfigurationen för ett inkommande samtal i realtid.

När ett inkommande telefonsamtal når ett nummer utan en tilldelad röstagent, eller när en webbwidgets-session startar med en publicerbar nyckel i mode="webhook", skickar ThunderPhone en blockerande telephony.incoming / web.incoming-begäran till din äldre webhook-URL och väntar på ett konfigurationssvar: upp till 13 sekunder för ett telefonsamtal, inklusive ett återförsök, och upp till 10 sekunder för en widgetsession (se Timeouter och återförsök). Använd detta utbyte för att dynamiskt välja en prompt, röst och verktyg per samtal — se guiden för dynamisk samtalskonfiguration för flödet från början till slut.

Tidsgränser och återförsök#

Svara snabbt: uppringaren väntar kvar i samtalet medan du bestämmer dig.

För ett telefonsamtal (telephony.incoming):

• Det första försöket kan ta upp till 10 sekunder.
• Om det får en timeout, inte kan ansluta eller får ett svar med 5xx, 408 eller 429 försöker ThunderPhone en gång till. Återförsöket får det som återstår av en budget på 13 sekunder för hela utbytet: cirka 3 sekunder efter ett första försök som fick timeout, nästan alla 13 efter ett snabbt fel. Inget återförsök görs när mindre än 2 sekunder skulle återstå.
• Alla andra 4xx-svar, ett svar över storleksgränsen eller ett 2xx vars brödtext inte är en giltig konfiguration är slutgiltiga och försöks inte igen.
• Båda försöken skickar samma brödtext, samma X-ThunderPhone-Signature och samma X-ThunderPhone-Idempotency-Key-header (telephony-incoming-<call_id>), så att en hanterare med sidoeffekter kan känna igen återförsöket.

Det finns ingen reservröstagent. Om ingen användbar konfiguration kommer fram avslutas samtalet direkt i stället för att låta uppringaren vänta i en tyst linje. Det visas i samtalshistoriken som ett misslyckat, ej debiterat samtal med end_reason inbound_config_webhook_failed, och det vanliga telephony.complete-eventet skickas.

En widgetsessions (web.incoming) får ett enda försök på upp till 10 sekunder. Om det misslyckas misslyckas sessionsbegäran med 502 eller 422.

Begärans nyttolast#

För telefonsamtal (telephony.incoming):

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

För webbsessioner i webbwidgeten (web.incoming) identifierar data inbäddningssidan i stället för telefonnummer:

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

Överstyrningsfälten (language, voice, website_context och eventuella variables från webbläsaren) skickas endast när den publicerbara nyckeln tillåter dem i sina webbläsaröverstyrningar. En sessionsbegäran som innehåller en överstyrning som nyckeln inte tillåter avvisas innan denna webhook anropas.

Svarsschema#

Returnera ett JSON-objekt som beskriver agentkonfigurationen för det här samtalet. prompt och voice krävs; allt annat är valfritt.

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

Eftersom prompt och voice krävs avvisas samtalet om du returnerar {} eller ett svar som inte klarar valideringen: ett telefonsamtal avslutas enligt beskrivningen i Timeouts och återförsök, och en begäran om en widgetsession misslyckas med 422. Det finns ingen reservlösning med statisk agent på den här vägen (ett nummer eller en nyckel i webhook-läge har ingen tilldelad agent).

Begränsning av svarsstorlek#

Exempel på hanterare#

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

Svar med funktionsverktyg#

Koppla verktyg så att AI:n kan anropa dina API:er mitt i samtalet:

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

Snabbguide till produktnivåer#

Relaterat#