telephony.incoming / web.incoming

Blokerende webhook, der former konfigurationen for et indgående opkald i realtid.

Når et indgående telefonopkald når et nummer uden en tilknyttet agent, eller en webwidgetsession starter på en publicerbar nøgle i mode="webhook", sender ThunderPhone en blokerende telephony.incoming / web.incoming-anmodning til din ældre webhook-URL og venter på et konfigurationssvar: op til 13 sekunder for et telefonopkald, inklusive ét genforsøg, og op til 10 sekunder for en widgetsession (se Timeouts and retries). Brug denne udveksling til dynamisk at vælge en prompt, stemme og værktøjer pr. opkald — se vejledningen til dynamisk opkaldskonfiguration for det fulde mønster.

Tidsgrænser og genforsøg#

Svar hurtigt: Personen, der ringer, venter på linjen, mens du beslutter dig.

For et telefonopkald (telephony.incoming):

• Det første forsøg kan tage op til 10 sekunder.
• Hvis det får timeout, ikke kan oprette forbindelse eller modtager et 5xx-, 408- eller 429-svar, prøver ThunderPhone én gang til. Genforsøget får den resterende tid af et budget på 13 sekunder for hele udvekslingen: omkring 3 sekunder efter et første forsøg med timeout, næsten alle 13 efter en hurtig fejl. Der foretages ikke noget genforsøg, hvis der ville være mindre end 2 sekunder tilbage.
• Ethvert andet 4xx-svar, et svar over størrelsesgrænsen eller et 2xx-svar, hvis brødtekst ikke er en gyldig konfiguration, er endeligt og prøves ikke igen.
• Begge forsøg sender den samme brødtekst, den samme X-ThunderPhone-Signature og den samme X-ThunderPhone-Idempotency-Key-header (telephony-incoming-<call_id>), så en handler med bivirkninger kan genkende genforsøget.

Der er ingen fallback-agent. Hvis der ikke modtages en brugbar konfiguration, afsluttes opkaldet straks i stedet for at lade personen, der ringer, vente på en stille linje. Det vises i opkaldshistorikken som et mislykket, ikke-faktureret opkald med end_reason inbound_config_webhook_failed, og det sædvanlige telephony.complete-event sendes.

En widgetsession (web.incoming) får ét forsøg på op til 10 sekunder. Hvis det mislykkes, mislykkes sessionsanmodningen med 502 eller 422.

Anmodningspayload#

For telefonopkald (telephony.incoming):

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

For webwidgetsessioner (web.incoming) identificerer data indlejringssiden i stedet for telefonnumre:

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

Tilsidesættelsesfelterne (language, voice, website_context og eventuelle browser-variables) ankommer kun, når den publicerbare nøgle tillader dem i sine browsertilsidesættelser. En sessionsanmodning med en tilsidesættelse, som nøglen ikke tillader, afvises, før denne webhook kaldes.

Svarskema#

Returner et JSON-objekt, der beskriver agentkonfigurationen for dette opkald. prompt og voice er påkrævede; alt andet er valgfrit.

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

Da prompt og voice er påkrævet, afviser returnering af {} eller et svar, der fejler valideringen, opkaldet: Et telefonopkald afsluttes som beskrevet i Timeouts og genforsøg, og en widget-sessionsforespørgsel fejler med 422. Der er ingen fallback til en statisk agent på denne sti (et nummer eller en nøgle i webhook-tilstand har ingen tildelt agent).

Grænse for svarstørrelse#

Eksempel på handler#

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 funktionsværktøjer#

Tilknyt værktøjer, så AI'en kan kalde dine API'er midt i samtalen:

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

Produktniveauer – hurtig oversigt#

Relateret#