telephony.incoming / web.incoming

Blokkerende webhook die de configuratie van een inkomende oproep in realtime vormgeeft.

Wanneer een inkomend telefoongesprek een nummer bereikt zonder toegewezen spraakagent, of wanneer een websidgetsessie start op een publiceerbare sleutel in mode="webhook", stuurt ThunderPhone een blokkerend telephony.incoming / web.incoming-verzoek naar je verouderde webhook-URL en wacht op een configuratieantwoord: maximaal 13 seconden voor een telefoongesprek, inclusief één nieuwe poging, en maximaal 10 seconden voor een widgetsessie (zie Time-outs en nieuwe pogingen). Gebruik deze uitwisseling om per gesprek dynamisch een prompt, stem en tools te kiezen — zie de gids voor dynamische oproepconfiguratie voor het volledige patroon.

Time-outs en nieuwe pogingen#

Reageer snel: de beller wacht aan de lijn terwijl je beslist.

Voor een telefoongesprek (telephony.incoming):

• De eerste poging kan maximaal 10 seconden duren.
• Als deze een time-out krijgt, geen verbinding kan maken of een 5xx-, 408- of 429-antwoord ontvangt, probeert ThunderPhone het nog één keer. De nieuwe poging krijgt wat er over is van een budget van 13 seconden voor de volledige uitwisseling: ongeveer 3 seconden na een eerste poging met een time-out, bijna alle 13 seconden na een snelle fout. Er wordt niet opnieuw geprobeerd als er minder dan 2 seconden over zouden zijn.
• Elk ander 4xx-antwoord, een antwoord boven de groottelimiet, of een 2xx waarvan de body geen geldige configuratie is, is definitief en wordt niet opnieuw geprobeerd.
• Beide pogingen verzenden dezelfde body, dezelfde header X-ThunderPhone-Signature en dezelfde header X-ThunderPhone-Idempotency-Key (telephony-incoming-<call_id>), zodat een handler met neveneffecten de nieuwe poging kan herkennen.

Er is geen fallback-spraakagent. Als er geen bruikbare configuratie binnenkomt, wordt de oproep direct beëindigd in plaats van de beller op een stille lijn te laten wachten. De oproep verschijnt in de Oproepgeschiedenis als een mislukte, niet-gefactureerde oproep met end_reason inbound_config_webhook_failed, en de gebruikelijke gebeurtenis telephony.complete wordt verzonden.

Een widgetsessie (web.incoming) krijgt één poging van maximaal 10 seconden. Als deze mislukt, mislukt het sessieverzoek met 502 of 422.

Verzoekpayload#

Voor telefoongesprekken (telephony.incoming):

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

Voor webwidgetsessies (web.incoming) identificeert data de insluitende pagina in plaats van telefoonnummers:

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

De overschrijvingsvelden (language, voice, website_context en eventuele browser-variables) worden alleen verzonden wanneer de publiceerbare sleutel deze toestaat in de bijbehorende browseroverschrijvingen. Een sessieverzoek met een overschrijving die de sleutel niet toestaat, wordt afgewezen voordat deze webhook wordt aangeroepen.

Antwoordschema#

Geef een JSON-object terug dat de configuratie van de spraakagent voor dit gesprek beschrijft. prompt en voice zijn vereist; al het andere is optioneel.

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

Omdat prompt en voice vereist zijn, weigert het retourneren van {} of een andere respons die de validatie niet doorstaat de oproep: een telefoongesprek wordt beëindigd zoals beschreven in Time-outs en nieuwe pogingen, en een widgetsessieverzoek mislukt met 422. Er is geen terugval op een statische agent via dit pad (een nummer of sleutel in webhookmodus heeft geen toegewezen agent).

Limiet voor responsgrootte#

Voorbeeldhandler#

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

Respons met functietools#

Koppel tools zodat de AI tijdens het gesprek je API's kan aanroepen:

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

Spiekbriefje productpakketten#

Gerelateerd#