Open in
ہر کال کے لیے متحرک کنفیگریشن
اپنے کنٹرول والے webhook میں کسٹم منطق کی بنیاد پر، ہر آنے والی کال کے لیے جواب دینے والا ایجنٹ منتخب کریں — یا اس کا prompt اور ترتیبات الگ سے تبدیل کریں۔
بطور ڈیفالٹ ہر فون نمبر اور قابل اشاعت کلید کے ساتھ ایک جامد ایجنٹ منسلک ہوتا ہے۔ جب آپ کو ہر کالر کے لیے یا ہر وزیٹر کے لیے تخصیص درکار ہو — VIP روٹنگ، لاگ اِن صارف کا سیاق، A/B prompt ٹیسٹس — تو ویب ہک موڈ پر منتقل ہوں اور اپنے سرور کو فیصلہ کرنے دیں۔
یہ کیسے کام کرتا ہے
- آپ
telephony.incoming(فون) یاweb.incoming(ویجیٹ) ایونٹ کو سبسکرائب کرتے ہیں۔ دونوں بلاکنگ ویب ہکس ہیں: ThunderPhone کال جاری رکھنے سے پہلے آپ کے جواب کا انتظار کرتا ہے، فون کال کے لیے زیادہ سے زیادہ 13 سیکنڈ تک (ایک دوبارہ کوشش سمیت) اور ویجیٹ سیشن کے لیے 10 سیکنڈ تک۔ - ThunderPhone آپ کو
{call_id, from_number, to_number}بھیجتا ہے (ویجیٹ سیشنز میں نمبروں کے بجائے ویجیٹ سے مخصوص فیلڈز ہوتے ہیں — درخواست کا اسکیما دیکھیں)۔ - آپ کا سرور ایجنٹ کی کنفیگریشن (prompt، آواز، پروڈکٹ، ٹولز، الفاظ) کے ساتھ جواب دیتا ہے۔ ThunderPhone کال کے لیے اسی کنفیگریشن کو استعمال کرتا ہے۔
- کوئی متبادل ایجنٹ نہیں ہے۔ اگر آپ
{}یا غلط کنفیگریشن واپس کرتے ہیں، یا اس کی دوبارہ کوشش کے بعد بھی درخواست ناکام رہتی ہے، تو فون کال فوراً ختم کر دی جاتی ہے اورend_reasoninbound_config_webhook_failedکے ساتھ ریکارڈ کی جاتی ہے؛ ویجیٹ سیشن کی درخواست ناکام ہو جاتی ہے۔
1. ویب ہک منزل کنفیگر کریں
فون نمبروں کے لیے، اپنے اینڈپوائنٹ کو 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"]
}'جواب میں ایک بار استعمال ہونے والا secret شامل ہوتا ہے — اسے محفوظ کریں؛ آپ اسے
دستخط کی توثیق کے لیے استعمال کریں گے۔
ویجیٹ سیشنز کے لیے، اپنے اینڈپوائنٹ URL کے ساتھ شامل mode="webhook" میں قابل اشاعت کلید بنائیں:
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"]
}'ویجیٹ ہر سیشن شروع ہونے پر اس URL پر POST کرے گا۔
2. ہینڈلر نافذ کریں
تین بنیادی اصول:
- ہر درخواست پر دستخط کی تصدیق کریں (دیکھیں ویب ہک دستخطوں کی تصدیق کریں)۔ dev میں اسے نظرانداز نہ کریں — ایک بار درست کریں اور دوبارہ استعمال کریں۔
- فوری جواب دیں۔ فون کال کی پہلی کوشش 10 سیکنڈ پر اور پورا تبادلہ 13 سیکنڈ پر منقطع ہو جاتا ہے، اور ہر سیکنڈ کال کرنے والے کے لیے خاموشی ہے۔ ضرورت ہو تو ڈیٹابیس تلاش کریں، مگر ڈاؤن اسٹریم LLMs کو ہم وقت طریقے سے کال نہ کریں — اگر آپ کو متحرک prompt جنریشن چاہیے تو پہلے سے حساب کریں اور کیش کریں۔
- صاف طور پر متبادل پر جائیں۔ کسی بھی غیر متوقع حالت کے لیے،
ایک ڈیفالٹ
promptاورvoice(یا محفوظ شدہagent_id) کے ساتھ جواب دیں۔{}یا ایرر اسٹیٹس واپس کرنے سے کال ختم ہو جاتی ہے۔
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 ...
passimport 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. رسپانس اسکیما
رسپانس باڈی بالکل ان کمنگ کال رسپانس اسکیما سے مطابقت رکھتی ہے۔ عام طور پر استعمال ہونے والی فیلڈز:
| فیلڈ | قسم | وضاحت |
|---|---|---|
prompt | سٹرنگ (لازمی) | ایجنٹ کے لیے سسٹم prompt |
voice | سٹرنگ (لازمی) | GET /v1/voices سے وائس ID |
product | سٹرنگ | bolt بھیجیں۔ ڈیفالٹ spark ہے، جو ایک پرانی ویلیو ہے اور اب بھی قبول کی جاتی ہے۔ |
background_track | سٹرنگ | null | محیطی آڈیو ID |
acknowledgement_prompt_mode | سٹرنگ | auto یا manual (صرف پرانی -with-ack پروڈکٹ ویلیوز) |
acknowledgement_prompt | سٹرنگ | موڈ manual ہونے پر لازمی |
language_switching | سٹرنگ | کثیر لسانی ایجنٹس کے لیے، ask_first یا follow_caller |
tools | ارے | ان لائن فنکشن-ٹول اسکیماز — فنکشن ٹولز دیکھیں |
محفوظ شدہ ایجنٹ رکھیں اور متغیرات یا سیاق فراہم کریں
اس ادارے کے محفوظ کردہ ایجنٹ کو فی کال ڈیٹا کے ساتھ استعمال کرنے کے لیے {"agent_id": 12, "variables": {"name": "Ada"}} واپس کریں۔
اس کے prompt میں {{name}} یا {{name|Friend}} شامل ہو سکتا ہے۔ ویب ہک ویری ایبلز درخواست کی سطح کے ویری ایبلز پر ضم ہو جاتے ہیں؛ null پلیس ہولڈر کا ڈیفالٹ استعمال کرتا ہے، یا اگر کوئی فراہم نہ کیا گیا ہو تو خالی متن۔ حتمی
اقدار اور حل نہ ہونے والے نام کال کی تفصیلات اور تکمیلی ویب ہکس میں ظاہر ہوتے ہیں۔
ایجنٹ کو اس کال کے لیے مختصر بریف دینے کے لیے context شامل کریں، جو 20,000 حروف تک کی آزاد شکل کی اسٹرنگ ہے
(آپ کے CRM کے نوٹس، کال کی متوقع وجہ)؛
اسے prompt کے بعد ایک محدود بلاک میں شامل کیا جاتا ہے۔
محفوظ کردہ ایجنٹ کے جوابات صرف agent_id، variables، context، timezone اور language قبول کرتے ہیں۔ اگر prompt موجود ہو
تو جواب ان لائن کنفیگریشن استعمال کرتا ہے اور agent_id کو نظر انداز کرتا ہے؛ ان لائن prompt کا پھر بھی درست ہونا ضروری ہے۔ اگر آپ کا ویب ہک تفویض کردہ ایجنٹ کا اپنا کال سیٹ اپ ویب ہک ہے، تو آپ کال کے لیے اس تفویض کردہ ایجنٹ کو برقرار رکھنے کے لیے agent_id کو چھوڑ بھی سکتے ہیں اور صرف variables، context، timezone یا language واپس کر سکتے ہیں (کسی بھی ورژن پن سمیت)۔ ان لائن
کنفیگریشن کے جوابات میں variables اور context بھی شامل ہو سکتے ہیں۔ محفوظ کردہ ایجنٹ کے جوابات
فون اور ویجیٹ، دونوں کالز پر ایجنٹ کی تعینات کردہ A/B تقسیم استعمال کرتے ہیں، پھر ویری ایبلز رینڈر کرتے ہیں۔ حدود اور سیشن API سپورٹ کے لیے کال ویری ایبلز
دیکھیں۔ بلاکنگ کنفیگریشن لیگیسی فون نمبر/ادارے کے URL یا ویب ہک موڈ ویجیٹ کلید سے آتی ہے؛ اینڈ پوائنٹ سسٹم کے
آنے والے ایونٹس صرف اطلاعات ہوتے ہیں۔
ہر کال کے لیے ٹائم زون مقرر کریں
ایک ایجنٹ مختلف ٹائم زونز میں موجود رابطوں کو جواب دے سکتا ہے۔ محفوظ شدہ ایجنٹ یا اِن لائن جواب میں IANA نام timezone شامل کریں، اور ایجنٹ اس کال کے لیے تاریخ اور وقت بتائے گا اور اسی زون میں اوقات پیش کرے گا، جو ایجنٹ کے اپنے ٹائم زون سے مختلف ہوگا:
{"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}}variables میں ٹائم اسٹیمپ کے بجائے زون بھیجیں: کال کے دوران ایجنٹ کی گھڑی چلتی رہتی ہے، اور آپ کا بھیجا ہوا وقت پرانا ہو جاتا ہے۔ جو قدر IANA زون نہ ہو اسے نظر انداز کر دیا جاتا ہے اور کال ایجنٹ کے زون میں منسلک ہو جاتی ہے۔
ہر کال کے لیے زبان مقرر کریں
ایک ایجنٹ اپنی ہر زبان میں جواب دے سکتا ہے۔ agent_id کے ساتھ language شامل کریں، جو معاون زبان کا کوڈ ہو، مثلاً es (es-MX کو es کے طور پر پڑھا جاتا ہے)، اور کال اس زبان میں شروع ہو جاتی ہے:
{"agent_id": 12, "language": "es", "variables": {"name": "Ada"}}ایجنٹ اس زبان کے لیے اپنی مخصوص آواز میں بولتا ہے: اس کا
language_voices اندراج؛ بصورت دیگر، native_voice_switching فعال ہونے پر، وہ مقامی آواز جس پر ایجنٹ اس زبان کے لیے منتقل ہوتا؛ بصورت دیگر اپنی آواز میں، جب وہ آواز اس زبان میں بول سکتی ہو۔ غیر ریکارڈ شدہ کالز پر، ThunderPhone کال کی زبان میں براہِ راست پروسیسنگ کا نوٹس بھی چلاتا ہے۔ پھر ایجنٹ کی دیگر زبانیں اور اس کی بنیادی زبان تبدیل کرنے کے لیے دستیاب رہتی ہیں۔ اگر ان میں سے کوئی بھی اس زبان میں نہیں بول سکتی، تو کال پھر بھی اس زبان میں شروع ہوتی ہے، زبان کی طے شدہ آواز کے ساتھ (حسب ضرورت آواز والا ایجنٹ اپنی آواز برقرار رکھتا ہے) اور کوئی دوسری زبان دستیاب نہیں ہوتی۔ اگر کال بعد میں دورانِ کال ایجنٹ کی کسی دوسری زبان پر منتقل ہو، تو جب دونوں آوازیں کیٹلاگ آوازیں ہوں، وہ اس زبان کا language_voices اندراج بھی استعمال کرتی ہے؛ بصورت دیگر معمول کے تبدیلی کے قواعد لاگو ہوتے ہیں۔ فل ڈوپلیکس ایجنٹس مختلف ہوتے ہیں: کسی بھی معاون زبان میں، کال ایجنٹ کی اپنی آواز برقرار رکھتی ہے، اور language_voices اور مقامی آواز کی تبدیلی لاگو نہیں ہوتے۔ صرف وہ کوڈ مسترد کیا جاتا ہے جو معاون زبان نہ ہو۔ ویجیٹ اور ریئل ٹائم سیشنز بھی یہی language فیلڈ لیتے ہیں۔
پیٹرنز
لاگ اِن صارف کا سیاق
ویب ہک موڈ وجٹس میں، وزیٹر کا صفحہ پہلے ہی جانتا ہے کہ وہ کون ہیں۔
اپنے ویب ہک کو ایک کوئری اسٹرنگ پیرامیٹر کے ساتھ کال کریں جسے وجٹ SDK
آگے بھیجتا ہے (?customer_id=123) اور صارف کو سرور سائیڈ پر تلاش کریں۔
A/B prompt رول آؤٹ
اسے خود تیار کرنے سے پہلے، نوٹ کریں کہ ThunderPhone میں مقامی
ایکسپیریمنٹس فیچر
(/dashboard/experiments اور ایجنٹ بلڈر کا A/B ٹیب) موجود ہے جو
ویریئنٹس متعین کرتا ہے، ٹریفک تقسیم کرتا ہے، اور ہر ویریئنٹ کے نتائج کا موازنہ کرتا ہے —
کسی ویب ہک کی ضرورت نہیں۔
اگر آپ کو پھر بھی ویب ہک سائیڈ کنٹرول درکار ہو: call_id کو ہیش کر کے بکٹ بنائیں؛
0..49 کے لیے prompt A اور 50..99 کے لیے prompt B فراہم کریں۔ اپنے DB میں
منتخب کردہ بکٹ ریکارڈ کریں اور بعد میں اسے مکمل شدہ کال کے گریڈ سے مربوط کریں۔
وقت پر مبنی روٹنگ
کاروباری اوقات → "براہ راست سپورٹ" ایجنٹ؛ کاروباری اوقات کے بعد → "پیغام لیں"
ایجنٹ۔ اپنے ہینڈلر میں new Date().getUTCHours() پر سادہ سوئچ استعمال کریں۔