ThunderPhone 2.0 اب لائیو ہے۔سیلف سرو، قیمت 2¢ فی منٹ سے شروع۔اعلان پڑھیں

Webhooks

telephony.incoming / web.incoming

بلاکنگ webhook جو آنے والی کال کی کنفیگریشن کو حقیقی وقت میں تشکیل دیتا ہے۔

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

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

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

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

{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567"
  }
}
فیلڈقسموضاحت
call_idعدد صحیحکال آئی ڈی — اس کال کے تمام ایونٹس میں مستقل
from_numberاسٹرنگE.164 کالر نمبر
to_numberاسٹرنگE.164 منزل (آپ کے ThunderPhone نمبروں میں سے ایک)

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

{
  "type": "web.incoming",
  "data": {
    "call_id": 987654322,
    "origin_domain": "https://example.com",
    "publishable_key_prefix": "pk_live_a1b2"
  }
}
فیلڈقسموضاحت
call_idعدد صحیحکال آئی ڈی
origin_domainاسٹرنگویجٹ کی میزبانی کرنے والے صفحے کا اصل ماخذ
publishable_key_prefixاسٹرنگسیشن کھولنے والی قابلِ اشاعت کلید کے ابتدائی حروف
language, primary_languageاسٹرنگویجٹ سیشن میں زبان تبدیل کرنے کی درخواست ہونے پر موجود
voiceاسٹرنگویجٹ سیشن میں آواز تبدیل کرنے کی درخواست ہونے پر موجود
website_contextاسٹرنگویجٹ کے ذریعے ہر سیشن کے لیے صفحے کا سیاق بھیجے جانے پر موجود

جواب کا اسکیما

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

{
  "prompt":  "You are a helpful booking assistant for Acme Restaurant.",
  "voice":   "john",
  "product": "spark",
  "background_track": null,
  "tools":   []
}
فیلڈقسملازمیوضاحت
promptاسٹرنگہاںایجنٹ کو چلانے والا سسٹم پرامپٹ
voiceاسٹرنگہاںGET /v1/voices سے وائس آئی ڈی، مثلاً john۔ voice_name کو متبادل نام کے طور پر قبول کیا جاتا ہے۔ نامعلوم وائسز ویلیڈیشن میں ناکام ہوتی ہیں اور کال مسترد ہو جاتی ہے
productاسٹرنگنہیںڈیفالٹ spark ہے۔ قابل اجازت: spark، bolt، storm-base، storm-base-with-ack، storm-extra، storm-extra-with-ack
thinking_levelاسٹرنگنہیںminimal، base (ڈیفالٹ)، یا extra۔ Storm پروڈکٹس کے لیے اووررائیڈ ہوتا ہے: storm-extra*، extra نافذ کرتا ہے، دیگر storm-*، base نافذ کرتے ہیں
audio_context_modeاسٹرنگنہیںfull (ڈیفالٹ) یا reduced
watchdog_enabledبولیننہیںاس کال کے لیے نگرانی فعال کریں۔ ڈیفالٹ false
additional_audio_contextبولین | نلنہیںصرف تازہ ترین ٹرن کے بجائے کالر آڈیو کے آخری چند ٹرنز شامل کریں، جس سے معمولی تاخیر اور لاگت کے اضافے کے ساتھ تصحیحات اور ہجے یا نمبر پر مبنی ڈیٹا اکٹھا کرنا بہتر ہوتا ہے۔ اِن باؤنڈ سیشنز کے لیے بطور ڈیفالٹ فعال اور آؤٹ باؤنڈ فون کالز کے لیے غیر فعال ہوتا ہے؛ null ڈیفالٹ برقرار رکھتا ہے
storm_feedback_modeاسٹرنگنہیںnone، acknowledgement (ڈیفالٹ)، یا tick
languageاسٹرنگنہیںprimary_language کے لیے مختصر نام
primary_languageاسٹرنگنہیںزبان کا کوڈ، نارملائزڈ (ڈیفالٹ en)۔ ناقابل حل کوڈز کال مسترد کر دیتے ہیں
has_additional_languagesبولیننہیںڈیفالٹ false
additional_languagesاسٹرنگ کی ارےنہیںاضافی زبانیں جن پر ایجنٹ سوئچ کر سکتا ہے
native_voice_switchingبولیننہیںڈیفالٹ false۔ جب کال کسی دوسری زبان پر سوئچ ہو، تو کنفیگر کردہ وائس برقرار رکھنے کے بجائے اس زبان کی مقامی وائس استعمال کریں (جنس کے مطابق)
background_trackاسٹرنگ | نلنہیںمحیطی آڈیو آئی ڈی یا null
acknowledgement_prompt_modeاسٹرنگنہیںauto (ڈیفالٹ) یا manual (Storm-with-ack پروڈکٹس)
acknowledgement_promptاسٹرنگنہیںجب acknowledgement_prompt_mode="manual" ہو تو استعمال ہوتا ہے
silence_interval_secondsانٹیجر | نلنہیں5–120۔ چیک اِن سے پہلے کالر کی خاموشی کے سیکنڈز
silence_max_checkinsانٹیجر | نلنہیں1–10
silence_checkins_enabledبولیننہیںڈیفالٹ true
connect_tone_enabledبولیننہیںڈیفالٹ false
voicemail_actionاسٹرنگنہیںprompt (ڈیفالٹ)، hangup، یا message
voicemail_messageاسٹرنگنہیںجب voicemail_action="message" ہو تو استعمال ہوتا ہے
agent_nameاسٹرنگنہیںڈیش بورڈز اور ویجیٹ کو رپورٹ کیا جانے والا ڈسپلے نام
org_nameاسٹرنگنہیںایجنٹ کی شخصیت کے لیے تنظیم کا ڈسپلے نام
toolsارےنہیںاِن لائن فنکشن ٹول اسکیماز (Function Tools دیکھیں)
call_idانٹیجرنہیںدرخواست کی کال آئی ڈی کا اختیاری ایکو؛ نظر انداز کیا جاتا ہے

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


جواب کے سائز کی حد


مثال ہینڈلر

Python (FastAPI)
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 {}
Node.js (Express)
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"
        }
      }
    }
  ]
}

پروڈکٹ درجوں کی فوری رہنما

پروڈکٹتاخیراستدلالتصدیق
sparkسب سے کمبنیادی
boltکمبہتر
storm-baseدرمیانیمضبوط
storm-base-with-ackدرمیانیمضبوطسوچنے کے دوران خودکار وقفہ پُر کرنے والا متن
storm-extraزیادہگہرا
storm-extra-with-ackزیادہگہراسوچنے کے دوران خودکار وقفہ پُر کرنے والا متن

متعلقہ