telephony.incoming / web.incoming

Webhook chặn định hình cấu hình cuộc gọi đến theo thời gian thực.

Khi một cuộc gọi điện thoại đến một số chưa được gán tác nhân AI, hoặc một phiên widget web bắt đầu trên khóa có thể công khai ở mode="webhook", ThunderPhone gửi một yêu cầu chặn telephony.incoming / web.incoming đến URL webhook cũ của bạn và chờ phản hồi cấu hình: tối đa 13 giây cho một cuộc gọi điện thoại, bao gồm một lần thử lại, và tối đa 10 giây cho một phiên widget (xem Thời gian chờ và thử lại). Dùng trao đổi này để chọn động prompt, giọng nói và công cụ cho từng cuộc gọi — xem hướng dẫn cấu hình cuộc gọi động để biết quy trình toàn diện.

Hết thời gian chờ và thử lại#

Phản hồi nhanh: người gọi đang chờ trên đường dây trong khi bạn quyết định.

Đối với cuộc gọi điện thoại (telephony.incoming):

• Lần thử đầu tiên có thể mất tối đa 10 giây.
• Nếu hết thời gian chờ, không thể kết nối hoặc nhận được phản hồi 5xx, 408 hay 429, ThunderPhone sẽ thử lại một lần nữa. Lần thử lại nhận phần còn lại của ngân sách 13 giây cho toàn bộ quá trình trao đổi: khoảng 3 giây sau lần thử đầu tiên hết thời gian chờ, hoặc gần như toàn bộ 13 giây sau một lỗi xảy ra nhanh. Sẽ không thử lại nếu còn chưa đến 2 giây.
• Bất kỳ phản hồi 4xx nào khác, phản hồi vượt quá giới hạn kích thước, hoặc phản hồi 2xx có phần thân không phải là cấu hình hợp lệ đều là cuối cùng và không được thử lại.
• Cả hai lần thử đều gửi cùng phần thân, cùng tiêu đề X-ThunderPhone-Signature, và cùng tiêu đề X-ThunderPhone-Idempotency-Key (telephony-incoming-<call_id>), vì vậy trình xử lý có tác dụng phụ có thể nhận biết lần thử lại.

Không có tác nhân dự phòng. Nếu không nhận được cấu hình có thể sử dụng, cuộc gọi sẽ được kết thúc ngay thay vì để người gọi chờ trên đường dây im lặng. Cuộc gọi xuất hiện trong lịch sử cuộc gọi là cuộc gọi thất bại, không tính phí với end_reason là inbound_config_webhook_failed, và sự kiện telephony.complete thông thường sẽ được gửi.

Một phiên widget (web.incoming) chỉ có một lần thử tối đa 10 giây. Nếu thất bại, yêu cầu phiên sẽ thất bại với 502 hoặc 422.

Payload yêu cầu#

Đối với cuộc gọi điện thoại (telephony.incoming):

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

Đối với phiên widget web (web.incoming), data xác định trang nhúng thay vì số điện thoại:

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

Các trường ghi đè (language, voice, website_context và mọi variables của trình duyệt) chỉ được gửi khi publishable key cho phép chúng trong các ghi đè của trình duyệt. Yêu cầu phiên chứa một trường mà key không cho phép sẽ bị từ chối trước khi webhook này được gọi.

Lược đồ phản hồi#

Trả về một đối tượng JSON mô tả cấu hình tác nhân AI cho cuộc gọi này. prompt và voice là bắt buộc; mọi trường khác là tùy chọn.

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

Vì prompt và voice là bắt buộc, việc trả về {} hoặc bất kỳ phản hồi nào không vượt qua bước xác thực sẽ từ chối cuộc gọi: cuộc gọi điện thoại sẽ kết thúc như mô tả trong Hết thời gian chờ và thử lại, và yêu cầu phiên widget sẽ thất bại với mã 422. Không có phương án dự phòng bằng tác nhân tĩnh trên luồng này (một số điện thoại hoặc khóa ở chế độ webhook không có tác nhân được gán).

Giới hạn kích thước phản hồi#

Ví dụ về trình xử lý#

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

Phản hồi kèm công cụ hàm#

Đính kèm công cụ để tác nhân AI có thể gọi API của bạn trong khi trò chuyệ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"
        }
      }
    }
  ]
}

Bảng tham chiếu nhanh về các gói sản phẩm#

Liên quan#