telephony.incoming / web.incoming

جب کسی آنے والی فون کال کا نمبر کسی مقرر کردہ ایجنٹ کے بغیر ہو، یا ویب ویجٹ سیشن mode="webhook" میں کسی پبلش ایبل کلید پر شروع ہو، تو ThunderPhone آپ کے لیگیسی webhook URL کو ایک روکنے والی telephony.incoming / web.incoming درخواست بھیجتا ہے اور کنفیگریشن کے جواب کے لیے 10 سیکنڈ تک انتظار کرتا ہے۔ ہر کال کے لیے prompt، آواز، اور ٹولز کو متحرک طور پر منتخب کرنے کے لیے اس تبادلے کو استعمال کریں — مکمل طریقۂ کار کے لیے متحرک کال کنفیگریشن گائیڈ دیکھیں۔

اس روکنے والے تبادلے کا کوئی متبادل نہیں: اگر آپ کا ہینڈلر غیر-2xx اسٹیٹس واپس کرے، وقت ختم ہو جائے، یا ایسی کنفیگ واپس کرے جو توثیق میں ناکام ہو، تو کال مسترد کر دی جاتی ہے (فون کال کنیکٹ نہیں ہوتی؛ ویجٹ سیشن کی درخواست 502/422 کے ساتھ ناکام ہو جاتی ہے)۔ فوری جواب دیں — جب آپ فیصلہ کر رہے ہوتے ہیں تو کالر رنگ بیک سن رہا ہوتا ہے۔

درخواست پے لوڈ

فون کالز کے لیے (telephony.incoming):

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

ویب ویجٹ سیشنز (web.incoming) کے لیے data فون نمبروں کے بجائے ایمبیڈنگ صفحے کی شناخت کرتا ہے:

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

جوابی اسکیما

اس کال کے لیے ایجنٹ کی کنفیگریشن بیان کرنے والا JSON آبجیکٹ واپس کریں۔ prompt اور voice لازمی ہیں؛ باقی سب اختیاری ہے۔

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

چونکہ prompt اور voice لازمی ہیں، اس لیے {} یا توثیق میں ناکام ہونے والا کوئی بھی جواب کال کو 422 کے ساتھ مسترد کر دیتا ہے — اس راستے پر جامد ایجنٹ کا کوئی متبادل نہیں ہے (ویب ہک موڈ میں کسی نمبر یا کلید کے ساتھ کوئی ایجنٹ مقرر نہیں ہوتا)۔

جوابی حجم کی حد

ہینڈلر کی مثال

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

فنکشن ٹولز کے ساتھ جواب

ٹولز منسلک کریں تاکہ AI گفتگو کے دوران آپ کی APIs کو کال کر سکے:

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

پروڈکٹ ٹئیر کا فوری حوالہ

متعلقہ