telephony.incoming / web.incoming

Blocking webhook that shapes an inbound call

When an inbound phone call reaches a number without an assigned agent, or a web widget session starts on a publishable key in mode="webhook", ThunderPhone sends a blocking telephony.incoming / web.incoming request to your legacy webhook URL and waits for a configuration response: up to 13 seconds for a phone call, one retry included, and up to 10 seconds for a widget session (see Timeouts and retries). Use this exchange to dynamically choose a prompt, voice, and tools per call — see the dynamic call configuration guide for the end-to-end pattern.

Timeouts and retries#

Answer fast: the caller is waiting on the line while you decide.

For a phone call (telephony.incoming):

• The first attempt may take up to 10 seconds.
• If it times out, cannot connect, or gets a 5xx, 408 or 429 response, ThunderPhone tries once more. The retry gets whatever is left of a 13-second budget for the whole exchange: about 3 seconds after a first attempt that timed out, nearly all 13 after a fast failure. There is no retry when less than 2 seconds would be left.
• Any other 4xx response, a response over the size limit, or a 2xx whose body is not a valid configuration is final and is not retried.
• Both attempts send the same body, the same X-ThunderPhone-Signature, and the same X-ThunderPhone-Idempotency-Key header (telephony-incoming-<call_id>), so a handler that has side effects can recognize the retry.

There is no fallback agent. If no usable configuration arrives, the call is ended right away instead of leaving the caller on a silent line. It appears in call history as a failed, unbilled call with end_reason inbound_config_webhook_failed, and the usual telephony.complete event is sent.

A widget session (web.incoming) gets a single attempt of up to 10 seconds. If it fails, the session request fails with 502 or 422.

Request payload#

For phone calls (telephony.incoming):

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

For web widget sessions (web.incoming) the data identifies the embedding page instead of phone numbers:

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

The override fields (language, voice, website_context, and any browser variables) arrive only when the publishable key allows them in its browser overrides. A session request carrying one the key does not allow is rejected before this webhook is called.

Response schema#

Return a JSON object describing the agent configuration for this call. prompt and voice are required; everything else is optional.

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

Because prompt and voice are required, returning {} or any response that fails validation rejects the call: a phone call is ended as described in Timeouts and retries, and a widget session request fails with 422. There is no static-agent fallback on this path (a number or key in webhook mode has no assigned agent).

Response size limit#

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

Response with function tools#

Attach tools so the AI can call your APIs mid-conversation:

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

Product tier cheat sheet#

Related#