Open in
প্রতিটি কলের জন্য ডায়নামিক কনফিগারেশন
আপনার নিয়ন্ত্রিত একটি webhook-এ কাস্টম লজিকের ভিত্তিতে প্রতিটি ইনকামিং কলের জন্য আলাদাভাবে উত্তরদাতা এজেন্ট বেছে নিন — অথবা এর prompt ও সেটিংস পুনর্লিখুন।
ডিফল্টভাবে প্রতিটি ফোন নম্বর এবং publishable key-এর সঙ্গে একটি স্থির এজেন্ট নির্ধারিত থাকে। যখন আপনার প্রতি-কলার বা প্রতি-ভিজিটর কাস্টমাইজেশন প্রয়োজন — VIP রাউটিং, লগ-ইন করা ব্যবহারকারীর প্রেক্ষিত, A/B prompt পরীক্ষা — তখন webhook মোডে স্যুইচ করুন এবং আপনার সার্ভারকে সিদ্ধান্ত নিতে দিন।
এটি কীভাবে কাজ করে
- আপনি
telephony.incoming(ফোন) অথবাweb.incoming(উইজেট) ইভেন্টে সাবস্ক্রাইব করেন। উভয়ই ব্লকিং webhook: কল চালিয়ে যাওয়ার আগে ThunderPhone আপনার প্রতিক্রিয়ার জন্য অপেক্ষা করে—ফোন কলে 13 সেকেন্ড পর্যন্ত (একটি পুনঃচেষ্টাসহ) এবং উইজেট সেশনে 10 সেকেন্ড পর্যন্ত। - ThunderPhone আপনাকে
{call_id, from_number, to_number}পাঠায় (উইজেট সেশনে নম্বরের পরিবর্তে উইজেট-নির্দিষ্ট ফিল্ড থাকে—দেখুন অনুরোধের স্কিমা)। - আপনার সার্ভার একটি এজেন্ট কনফিগারেশন (prompt, ভয়েস, পণ্য, টুল, শব্দ) দিয়ে প্রতিক্রিয়া জানায়। ThunderPhone কলে সেই কনফিগারেশন ব্যবহার করে।
- কোনো ফলব্যাক এজেন্ট নেই। আপনি
{}অথবা একটি অবৈধ কনফিগারেশন ফেরত দিলে, অথবা অনুরোধটি তার পুনঃচেষ্টা-এর পরেও ব্যর্থ হলে, ফোন কলটি সঙ্গে সঙ্গে শেষ করা হয় এবংend_reasoninbound_config_webhook_failedদিয়ে রেকর্ড করা হয়; উইজেট সেশনের অনুরোধ ব্যর্থ হয়।
1. webhook গন্তব্য কনফিগার করুন
ফোন নম্বরের জন্য, আপনার endpoint-কে 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 অন্তর্ভুক্ত থাকে — এটি সংরক্ষণ করুন; স্বাক্ষর যাচাইয়ের জন্য
আপনার এটি লাগবে।
উইজেট সেশনের জন্য, আপনার endpoint URL অন্তর্ভুক্ত করে mode="webhook"-এ একটি publishable key তৈরি করুন:
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. হ্যান্ডলার বাস্তবায়ন করুন
তিনটি সাধারণ নিয়ম:
- প্রতিটি অনুরোধে সিগনেচার যাচাই করুন (দেখুন ওয়েবহুক সিগনেচার যাচাই করুন)। ডেভেলপমেন্টে এটি এড়িয়ে যাবেন না — একবার সঠিকভাবে করুন এবং পুনঃব্যবহার করুন।
- দ্রুত প্রতিক্রিয়া দিন। একটি ফোন কলের প্রথম প্রচেষ্টা 10 সেকেন্ডে এবং পুরো আদান-প্রদান 13 সেকেন্ডে কেটে যায়, আর প্রতিটি সেকেন্ড কলারের জন্য নীরবতা। প্রয়োজন হলে ডেটাবেস লুকআপ করুন, তবে ডাউনস্ট্রিম LLM-কে সিঙ্ক্রোনাসভাবে কল করবেন না — ডায়নামিক 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 থেকে ভয়েস আইডি |
product | স্ট্রিং | bolt পাঠান। ডিফল্ট হলো spark, একটি পুরোনো মান যা এখনও গ্রহণ করা হয়। |
background_track | স্ট্রিং | null | পরিবেশগত অডিও আইডি |
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()-এর ওপর সরাসরি সুইচ করুন।