telephony.incoming / web.incoming

Webhook bloquant qui façonne la configuration d’un appel entrant en temps réel.

Lorsqu’un appel téléphonique entrant atteint un numéro sans agent attribué, ou qu’une session de widget web démarre sur une clé publiable en mode="webhook", ThunderPhone envoie une requête bloquante telephony.incoming / web.incoming à votre URL de webhook héritée et attend une réponse de configuration : jusqu’à 13 secondes pour un appel téléphonique, avec une nouvelle tentative incluse, et jusqu’à 10 secondes pour une session de widget (voir Délais d’expiration et nouvelles tentatives). Utilisez cet échange pour choisir dynamiquement un prompt, une voix et des outils pour chaque appel — consultez le guide de configuration dynamique des appels pour le modèle de bout en bout.

Délais d’attente et nouvelles tentatives#

Répondez rapidement : l’appelant attend en ligne pendant que vous décidez.

Pour un appel téléphonique (telephony.incoming) :

• La première tentative peut prendre jusqu’à 10 secondes.
• En cas de délai d’attente, d’impossibilité de se connecter, ou de réponse 5xx, 408 ou 429, ThunderPhone effectue une nouvelle tentative. La nouvelle tentative reçoit ce qui reste d’un budget de 13 secondes pour l’ensemble de l’échange : environ 3 secondes après une première tentative ayant expiré, et presque la totalité des 13 secondes après un échec rapide. Aucune nouvelle tentative n’est effectuée s’il reste moins de 2 secondes.
• Toute autre réponse 4xx, une réponse dépassant la limite de taille, ou une réponse 2xx dont le corps ne contient pas une configuration valide est définitive et ne fait pas l’objet d’une nouvelle tentative.
• Les deux tentatives envoient le même corps, le même en-tête X-ThunderPhone-Signature, et le même en-tête X-ThunderPhone-Idempotency-Key (telephony-incoming-<call_id>), afin qu’un gestionnaire ayant des effets de bord puisse reconnaître la nouvelle tentative.

Il n’existe aucun agent de secours. Si aucune configuration utilisable n’arrive, l’appel est terminé immédiatement plutôt que de laisser l’appelant sur une ligne silencieuse. Il apparaît dans l’historique des appels comme un appel échoué, non facturé, avec end_reason inbound_config_webhook_failed, et l’événement habituel telephony.complete est envoyé.

Une session de widget (web.incoming) dispose d’une seule tentative pouvant durer jusqu’à 10 secondes. En cas d’échec, la requête de session échoue avec 502 ou 422.

Corps de la requête#

Pour les appels téléphoniques (telephony.incoming) :

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

Pour les sessions de widget web (web.incoming), data identifie la page d'intégration au lieu des numéros de téléphone :

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

Les champs de surcharge (language, voice, website_context et toutes les variables du navigateur) arrivent uniquement lorsque la clé publiable les autorise dans ses surcharges du navigateur. Une requête de session contenant une surcharge non autorisée par la clé est rejetée avant l’appel de ce webhook.

Schéma de réponse#

Renvoyez un objet JSON décrivant la configuration de l’agent pour cet appel. prompt et voice sont obligatoires ; tous les autres champs sont facultatifs.

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

Comme prompt et voice sont obligatoires, renvoyer {} ou toute réponse qui échoue à la validation rejette l’appel : un appel téléphonique est terminé comme décrit dans Délais d’attente et nouvelles tentatives, et une demande de session de widget échoue avec 422. Il n’existe pas de solution de repli vers un agent statique sur ce chemin (un numéro ou une clé en mode webhook n’a aucun agent attribué).

Limite de taille de réponse#

Exemple de gestionnaire#

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

Réponse avec des outils de fonction#

Ajoutez des outils afin que l'IA puisse appeler vos API pendant la 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"
        }
      }
    }
  ]
}

Aide-mémoire des niveaux de produit#

Associé#