telephony.incoming / web.incoming

Webhook bloqueante que configura una llamada entrante en tiempo real.

Cuando una llamada telefónica entrante llega a un número sin un agente asignado, o una sesión de widget web comienza con una clave publicable en mode="webhook", ThunderPhone envía una solicitud bloqueante de telephony.incoming / web.incoming a tu URL de webhook heredada y espera una respuesta de configuración: hasta 13 segundos para una llamada telefónica, incluido un reintento, y hasta 10 segundos para una sesión de widget (consulta Tiempos de espera y reintentos). Usa este intercambio para elegir dinámicamente un prompt, una voz y herramientas para cada llamada; consulta la guía de configuración dinámica de llamadas para conocer el patrón integral.

Tiempos de espera y reintentos#

Responde rápido: la persona que llama está esperando en la línea mientras decides.

Para una llamada telefónica (telephony.incoming):

• El primer intento puede tardar hasta 10 segundos.
• Si se agota el tiempo de espera, no se puede conectar o recibe una respuesta 5xx, 408 o 429, ThunderPhone lo intenta una vez más. El reintento recibe lo que quede de un presupuesto de 13 segundos para toda la interacción: aproximadamente 3 segundos después de un primer intento que agotó el tiempo de espera, y casi los 13 después de una falla rápida. No hay reintento cuando quedarían menos de 2 segundos.
• Cualquier otra respuesta 4xx, una respuesta que supere el límite de tamaño, o una respuesta 2xx cuyo cuerpo no sea una configuración válida es definitiva y no se reintenta.
• Ambos intentos envían el mismo cuerpo, la misma cabecera X-ThunderPhone-Signature, y la misma cabecera X-ThunderPhone-Idempotency-Key (telephony-incoming-<call_id>), por lo que un controlador con efectos secundarios puede reconocer el reintento.

No hay un agente de respaldo. Si no llega una configuración utilizable, la llamada finaliza de inmediato en lugar de dejar a la persona que llama en una línea silenciosa. Aparece en el historial de llamadas como una llamada fallida sin facturar con end_reason inbound_config_webhook_failed, y se envía el evento habitual telephony.complete.

Una sesión de widget (web.incoming) recibe un solo intento de hasta 10 segundos. Si falla, la solicitud de sesión falla con 502 o 422.

Carga útil de la solicitud#

Para llamadas telefónicas (telephony.incoming):

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

Para sesiones del widget web (web.incoming), data identifica la página de inserción en lugar de números telefónicos:

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

Los campos de anulación (language, voice, website_context y cualquier variables del navegador) llegan solo cuando la clave publicable los permite en sus anulaciones del navegador. Una solicitud de sesión que incluya una anulación que la clave no permita se rechaza antes de que se llame a este webhook.

Esquema de respuesta#

Devuelve un objeto JSON que describa la configuración del agente para esta llamada. prompt y voice son obligatorios; todo lo demás es opcional.

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

Como prompt y voice son obligatorios, devolver {} o cualquier respuesta que no pase la validación rechaza la llamada: una llamada telefónica finaliza como se describe en Tiempos de espera y reintentos, y una solicitud de sesión del widget falla con 422. No hay alternativa de agente estático en esta ruta (un número o clave en modo webhook no tiene un agente asignado).

Límite de tamaño de respuesta#

Controlador de ejemplo#

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

Respuesta con herramientas de función#

Adjunta herramientas para que la IA pueda llamar a tus API durante la conversación:

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

Guía rápida de niveles de producto#

Relacionado#