ThunderPhone v3 đã chính thức ra mắt.Tự đăng ký và sử dụng, chỉ từ 2¢/phút.Xem thông báo ra mắt

Developer cookbook

Cấu hình động cho từng cuộc gọi

Chọn tác nhân AI trả lời — hoặc viết lại prompt và cài đặt của tác nhân — riêng cho từng cuộc gọi đến, dựa trên logic tùy chỉnh trong webhook do bạn kiểm soát.

Theo mặc định, mọi số điện thoại và khóa có thể công khai đều được gán một tác nhân AI tĩnh. Khi bạn cần tùy chỉnh theo từng người gọi hoặc theo từng khách truy cập — định tuyến VIP, ngữ cảnh người dùng đã đăng nhập, kiểm thử prompt A/B — hãy chuyển sang chế độ webhook và để máy chủ của bạn quyết định.

Cách hoạt động

  1. Bạn đăng ký sự kiện telephony.incoming (điện thoại) hoặc web.incoming (widget). Cả hai đều là webhook chặn: ThunderPhone chờ phản hồi của bạn trước khi tiếp tục cuộc gọi, tối đa 13 giây đối với cuộc gọi điện thoại (bao gồm một lần thử lại) và 10 giây đối với phiên widget.
  2. ThunderPhone gửi cho bạn {call_id, from_number, to_number} (phiên widget chứa các trường dành riêng cho widget thay vì số điện thoại — xem schema yêu cầu).
  3. Máy chủ của bạn phản hồi bằng cấu hình tác nhân AI (prompt, giọng nói, sản phẩm, công cụ, từ ngữ). ThunderPhone sử dụng cấu hình đó cho cuộc gọi.
  4. Không có tác nhân AI dự phòng. Nếu bạn trả về {} hoặc một cấu hình không hợp lệ, hoặc yêu cầu vẫn thất bại sau lần thử lại, cuộc gọi điện thoại sẽ kết thúc ngay và được ghi nhận với end_reason inbound_config_webhook_failed; yêu cầu phiên widget sẽ thất bại.

1. Cấu hình đích webhook

Đối với số điện thoại, đăng ký điểm cuối của bạn với telephony.incoming:

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Prod call-incoming",
    "url":    "https://example.com/thunderphone/incoming",
    "events": ["telephony.incoming"]
  }'

Phản hồi bao gồm secret dùng một lần — hãy lưu lại; bạn sẽ dùng nó để xác minh chữ ký.

Đối với phiên widget, tạo khóa có thể công khai ở mode="webhook" với URL điểm cuối của bạn được nhúng sẵn:

curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Dynamic widget",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-incoming",
    "allowed_domains": ["example.com"]
  }'

Widget sẽ POST đến URL này mỗi khi bắt đầu phiên.

2. Triển khai handler

Ba quy tắc thực hành:

  • Xác minh chữ ký trên mọi yêu cầu (xem Xác minh chữ ký webhook). Đừng bỏ qua bước này trong môi trường dev — thực hiện đúng một lần rồi tái sử dụng.
  • Phản hồi nhanh. Lần thử đầu tiên của một cuộc gọi sẽ bị ngắt sau 10 giây và toàn bộ trao đổi sau 13 giây, và mỗi giây đều là khoảng lặng với người gọi. Hãy tra cứu cơ sở dữ liệu nếu cần, nhưng đừng gọi đồng bộ các LLM ở hạ nguồn — nếu muốn tạo prompt động, hãy tính trước và lưu vào bộ nhớ đệm.
  • Dự phòng gọn gàng. Với mọi trạng thái không mong đợi, hãy phản hồi bằng prompt và voice mặc định (hoặc agent_id đã lưu). Trả về {} hoặc trạng thái lỗi sẽ kết thúc cuộc gọi.
FastAPI
import hashlib
import hmac
import json
import os
 
from fastapi import FastAPI, HTTPException, Request
 
app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
 
def verify(body: bytes, sig: str) -> bool:
    expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig or "")
 
@app.post("/thunderphone/incoming")
async def incoming(request: Request):
    body = await request.body()
    if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
        raise HTTPException(401)
 
    event = json.loads(body)
    if event["type"] not in ("telephony.incoming", "web.incoming"):
        return {}  # fall back to default
 
    caller = event["data"]["from_number"]
    # Cheap DB lookup: is this a known VIP?
    customer = lookup_customer(caller)
    if customer and customer.tier == "vip":
        return {
            "prompt":  f"You are a VIP concierge for {customer.name}. Be proactive…",
            "voice":   "john",
            "product": "storm-base",
        }
    return {}  # default agent handles non-VIPs
 
def lookup_customer(phone: str):
    # ... your CRM integration ...
    pass
Express
import crypto from "node:crypto";
import express from "express";
 
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
 
function verify(body, sig) {
  const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex");
  return sig &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}
 
app.post(
  "/thunderphone/incoming",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
      return res.sendStatus(401);
    }
    const event = JSON.parse(req.body.toString("utf8"));
 
    const IMPORTANT_TYPES = new Set([
      "telephony.incoming",
      "web.incoming",
    ]);
    if (!IMPORTANT_TYPES.has(event.type)) return res.json({});
 
    const customer = await lookupCustomer(event.data.from_number);
    if (customer?.tier === "vip") {
      return res.json({
        prompt:  `You are a VIP concierge for ${customer.name}. Be proactive…`,
        voice:   "john",
        product: "storm-base",
      });
    }
    res.json({}); // fall back to default agent
  },
);

3. Lược đồ phản hồi

Nội dung phản hồi khớp chính xác với lược đồ phản hồi cuộc gọi đến. Các trường thường dùng:

TrườngLoạiMô tả
promptchuỗi (bắt buộc)System prompt cho tác nhân AI
voicechuỗi (bắt buộc)ID giọng nói từ GET /v1/voices
productchuỗiGửi bolt. Mặc định là spark, một giá trị cũ vẫn được chấp nhận.
background_trackchuỗi | nullID âm thanh nền
acknowledgement_prompt_modechuỗiauto hoặc manual (chỉ dành cho các giá trị product -with-ack cũ)
acknowledgement_promptchuỗiBắt buộc khi chế độ là manual
language_switchingchuỗiĐối với tác nhân AI đa ngôn ngữ, ask_first hoặc follow_caller
toolsmảngSchema công cụ hàm nội tuyến — xem Công cụ hàm

Giữ một tác nhân đã lưu và cung cấp biến hoặc ngữ cảnh

Trả về {"agent_id": 12, "variables": {"name": "Ada"}} để sử dụng tác nhân AI đã lưu của tổ chức đó với dữ liệu theo từng cuộc gọi. Prompt của tác nhân có thể chứa {{name}} hoặc {{name|Friend}}. Biến webhook được hợp nhất lên trên biến cấp yêu cầu; null sử dụng giá trị mặc định của phần giữ chỗ hoặc văn bản trống nếu không được cung cấp. Giá trị cuối cùng và tên chưa được phân giải xuất hiện trong chi tiết cuộc gọi và webhook hoàn tất. Thêm context, một chuỗi dạng tự do dài tối đa 20.000 ký tự, để cung cấp cho tác nhân AI bản hướng dẫn ngắn cho cuộc gọi này (ghi chú từ CRM của bạn, lý do bạn dự kiến có cuộc gọi); nó được thêm sau prompt trong một khối có dấu phân cách. Phản hồi của tác nhân AI đã lưu chỉ chấp nhận agent_id, variables, context, timezone và language. Nếu prompt có mặt, phản hồi sẽ sử dụng cấu hình nội tuyến và bỏ qua agent_id; prompt nội tuyến vẫn phải hợp lệ. Nếu webhook của bạn là webhook thiết lập cuộc gọi của chính tác nhân được chỉ định, bạn cũng có thể bỏ qua agent_id và chỉ trả về variables, context, timezone hoặc language để giữ tác nhân được chỉ định đó (bao gồm mọi ghim phiên bản) cho cuộc gọi. Phản hồi cấu hình nội tuyến cũng có thể bao gồm variables và context. Phản hồi của tác nhân AI đã lưu sử dụng phân chia A/B đã triển khai của tác nhân trên cả cuộc gọi điện thoại và cuộc gọi widget, sau đó kết xuất biến. Xem biến cuộc gọi để biết giới hạn và hỗ trợ API phiên. Cấu hình chặn đến từ URL số điện thoại/tổ chức cũ hoặc khóa widget ở chế độ webhook; các sự kiện đến của hệ thống endpoint chỉ là thông báo.

Đặt múi giờ cho từng cuộc gọi

Một tác nhân AI có thể trả lời cho liên hệ ở các múi giờ khác nhau. Thêm timezone, một tên IANA, vào phản hồi tác nhân đã lưu hoặc phản hồi nội tuyến và tác nhân sẽ nêu ngày và giờ cũng như đề xuất thời gian theo múi giờ đó cho cuộc gọi này, thay vì múi giờ của chính tác nhân:

{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}

Gửi múi giờ thay vì dấu thời gian trong variables: đồng hồ của tác nhân vẫn tiếp tục chạy trong cuộc gọi và thời gian bạn truyền vào sẽ trở nên lỗi thời. Giá trị không phải là múi giờ IANA sẽ bị bỏ qua và cuộc gọi kết nối theo múi giờ của tác nhân.

Đặt ngôn ngữ cho từng cuộc gọi

Một tác nhân có thể trả lời bằng từng ngôn ngữ của mình. Thêm language, một mã ngôn ngữ được hỗ trợ như es (es-MX được hiểu là es), bên cạnh agent_id và cuộc gọi sẽ bắt đầu bằng ngôn ngữ đó:

{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}

Tác nhân AI nói ngôn ngữ đó bằng giọng của ngôn ngữ đó: mục language_voices của tác nhân AI; nếu không, khi bật native_voice_switching, bằng giọng bản địa mà tác nhân AI sẽ chuyển sang cho ngôn ngữ đó; nếu không, bằng giọng riêng của tác nhân AI, khi giọng đó nói được ngôn ngữ này. Sau đó, các ngôn ngữ khác của tác nhân AI và ngôn ngữ chính vẫn khả dụng để chuyển đổi. Nếu không giọng nào trong số này có thể nói ngôn ngữ đó, cuộc gọi vẫn bắt đầu bằng ngôn ngữ đó, với giọng mặc định của ngôn ngữ (tác nhân AI có giọng tùy chỉnh vẫn giữ giọng đó) và không có ngôn ngữ nào khác. Nếu cuộc gọi chuyển giữa chừng sang một ngôn ngữ khác của tác nhân AI, cuộc gọi cũng sử dụng mục language_voices của ngôn ngữ đó khi cả hai giọng đều là giọng trong danh mục; nếu không, áp dụng quy tắc chuyển đổi thông thường. Tác nhân AI song công hoàn toàn hoạt động khác: với mọi ngôn ngữ được hỗ trợ, cuộc gọi giữ nguyên giọng riêng của tác nhân AI, và language_voices cùng việc chuyển đổi giọng bản địa không áp dụng. Chỉ mã không phải là ngôn ngữ được hỗ trợ mới bị từ chối. Widget và phiên realtime sử dụng cùng trường language.

Mẫu

Ngữ cảnh người dùng đã đăng nhập

Trong widget ở chế độ webhook, trang của khách truy cập đã biết họ là ai. Gọi webhook của bạn bằng tham số chuỗi truy vấn mà SDK widget chuyển tiếp (?customer_id=123) và tra cứu khách hàng ở phía máy chủ.

Triển khai prompt A/B

Trước khi tự xây dựng cách này, hãy lưu ý rằng ThunderPhone có tính năng Thử nghiệm gốc (/dashboard/experiments và tab A/B của trình tạo tác nhân AI) để xác định biến thể, phân chia lưu lượng và so sánh kết quả theo từng biến thể — không cần webhook.

Nếu bạn vẫn cần quyền kiểm soát ở phía webhook: băm call_id → nhóm; phục vụ prompt A cho 0..49 và prompt B cho 50..99. Ghi lại nhóm bạn đã chọn trong DB riêng và sau đó đối chiếu với điểm của cuộc gọi đã hoàn tất.

Định tuyến theo thời gian

Trong giờ làm việc → tác nhân AI "hỗ trợ trực tiếp"; ngoài giờ → tác nhân AI "nhận lời nhắn". Chỉ cần chuyển nhánh theo new Date().getUTCHours() trong trình xử lý của bạn.


Bước tiếp theo