telephony.incoming / web.incoming

Webhook pemblokiran yang membentuk konfigurasi panggilan masuk secara real time.

Saat panggilan telepon masuk mencapai nomor tanpa agen yang ditetapkan, atau sesi widget web dimulai pada kunci yang dapat dipublikasikan dalam mode="webhook", ThunderPhone mengirimkan permintaan yang memblokir telephony.incoming / web.incoming ke URL webhook lama Anda dan menunggu respons konfigurasi: hingga 13 detik untuk panggilan telepon, termasuk satu percobaan ulang, dan hingga 10 detik untuk sesi widget (lihat Batas waktu dan percobaan ulang). Gunakan pertukaran ini untuk memilih Prompt, suara, dan alat secara dinamis per panggilan — lihat panduan konfigurasi panggilan dinamis untuk pola menyeluruh.

Batas waktu dan percobaan ulang#

Jawablah dengan cepat: penelepon menunggu di saluran saat Anda memutuskan.

Untuk panggilan telepon (telephony.incoming):

• Upaya pertama dapat memakan waktu hingga 10 detik.
• Jika mengalami batas waktu habis, tidak dapat terhubung, atau menerima respons 5xx, 408, atau 429, ThunderPhone mencoba sekali lagi. Percobaan ulang mendapatkan sisa dari batas waktu 13 detik untuk seluruh pertukaran: sekitar 3 detik setelah upaya pertama yang mengalami batas waktu habis, hampir seluruh 13 detik setelah kegagalan cepat. Tidak ada percobaan ulang jika sisa waktunya kurang dari 2 detik.
• Respons 4xx lainnya, respons yang melebihi batas ukuran, atau 2xx yang isi responsnya bukan konfigurasi valid bersifat final dan tidak dicoba ulang.
• Kedua upaya mengirim isi respons yang sama, header X-ThunderPhone-Signature yang sama, dan header X-ThunderPhone-Idempotency-Key yang sama (telephony-incoming-<call_id>), sehingga handler yang memiliki efek samping dapat mengenali percobaan ulang.

Tidak ada agen cadangan. Jika tidak ada konfigurasi yang dapat digunakan, panggilan langsung diakhiri alih-alih membiarkan penelepon berada di saluran hening. Panggilan tersebut muncul dalam riwayat panggilan sebagai panggilan gagal yang tidak ditagihkan dengan end_reason inbound_config_webhook_failed, dan peristiwa telephony.complete biasa dikirim.

Sesi widget (web.incoming) mendapatkan satu upaya hingga 10 detik. Jika gagal, permintaan sesi gagal dengan 502 atau 422.

Payload permintaan#

Untuk panggilan telepon (telephony.incoming):

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

Untuk sesi widget web (web.incoming), data mengidentifikasi halaman yang menyematkan widget, bukan nomor telepon:

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

Bidang override (language, voice, website_context, dan variables peramban) hanya tiba saat kunci yang dapat dipublikasikan mengizinkannya di override peramban. Permintaan sesi yang menyertakan override yang tidak diizinkan oleh kunci tersebut ditolak sebelum webhook ini dipanggil.

Skema respons#

Kembalikan objek JSON yang menjelaskan konfigurasi agen untuk panggilan ini. prompt dan voice wajib diisi; semua yang lain bersifat opsional.

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

Karena prompt dan voice wajib, mengembalikan {} atau respons apa pun yang gagal validasi akan menolak panggilan: panggilan telepon diakhiri seperti dijelaskan dalam Batas waktu dan percobaan ulang, dan permintaan sesi widget gagal dengan 422. Tidak ada fallback agen statis pada jalur ini (nomor atau kunci dalam mode webhook tidak memiliki agen yang ditetapkan).

Batas ukuran respons#

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

Respons dengan function tool#

Tambahkan tool agar AI dapat memanggil API Anda di tengah percakapan:

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

Lembar ringkas tingkatan produk#

Terkait#