Open in
telephony.incoming / web.incoming
ব্লকিং webhook যা রিয়েল টাইমে একটি ইনবাউন্ড কলের কনফিগারেশন নির্ধারণ করে।
কোনো ইনবাউন্ড ফোন কল নির্ধারিত এজেন্ট ছাড়া
কোনো নম্বরে পৌঁছালে (আপনার আউটবাউন্ড কলে ফিরে আসা কলারদের জন্য Callbacks দেখুন), অথবা কোনো প্রকাশযোগ্য কীতে
mode="webhook" সহ একটি ওয়েব উইজেট সেশন শুরু হলে, ThunderPhone আপনার
লিগ্যাসি webhook URL-এ একটি ব্লকিং
telephony.incoming / web.incoming অনুরোধ পাঠায়
এবং একটি কনফিগারেশন প্রতিক্রিয়ার জন্য অপেক্ষা করে: একটি ফোন কলের জন্য 13 সেকেন্ড পর্যন্ত,
একটি পুনঃচেষ্টা সহ, এবং একটি উইজেট সেশনের জন্য 10 সেকেন্ড পর্যন্ত (টাইমআউট ও পুনঃচেষ্টা দেখুন)। প্রতি কলে গতিশীলভাবে একটি prompt, ভয়েস এবং টুল বেছে নিতে এই
বিনিময় ব্যবহার করুন —
সম্পূর্ণ প্যাটার্নের জন্য ডায়নামিক কল কনফিগারেশন গাইড
দেখুন।
একটি নির্ধারিত এজেন্ট সহ নম্বরে সেই এজেন্ট কলের উত্তর দেয়। এজেন্টের নিজস্ব কল সেটআপ webhook থাকলে, একই ব্লকিং বিনিময় প্রথমে এজেন্টের URL-এ চলে, এজেন্টের ভেরিয়েবল এবং কলের প্রসঙ্গ পূরণ করতে।
সময়সীমা শেষ হওয়া ও পুনঃচেষ্টা
দ্রুত উত্তর দিন: আপনি সিদ্ধান্ত নেওয়ার সময় কলার লাইনে অপেক্ষা করছেন।
একটি ফোন কলের জন্য (telephony.incoming):
- প্রথম চেষ্টায় সর্বোচ্চ 10 সেকেন্ড সময় লাগতে পারে।
- সময়সীমা শেষ হলে, সংযোগ করা না গেলে, বা
5xx,408কিংবা429প্রতিক্রিয়া পেলে ThunderPhone আরও একবার চেষ্টা করে। সম্পূর্ণ আদান-প্রদানের 13-সেকেন্ডের বাজেটে যা অবশিষ্ট থাকে, পুনঃচেষ্টা ততটুকু সময় পায়: সময়সীমা শেষ হওয়া প্রথম চেষ্টার পর প্রায় 3 সেকেন্ড, দ্রুত ব্যর্থতার পর প্রায় পুরো 13 সেকেন্ড। 2 সেকেন্ডের কম সময় অবশিষ্ট থাকলে পুনঃচেষ্টা করা হয় না। - অন্য যেকোনো
4xxপ্রতিক্রিয়া, আকার সীমা-এর বেশি প্রতিক্রিয়া, বা এমন2xxযার body বৈধ configuration নয়, চূড়ান্ত বলে গণ্য হয় এবং পুনঃচেষ্টা করা হয় না। - উভয় চেষ্টাই একই body, একই
X-ThunderPhone-Signature, এবং একইX-ThunderPhone-Idempotency-Keyheader (telephony-incoming-<call_id>) পাঠায়, তাই পার্শ্বপ্রভাব আছে এমন handler পুনঃচেষ্টা শনাক্ত করতে পারে।
ব্যবহারযোগ্য কোনো কনফিগারেশন না এলে, কলারকে নীরব লাইনে রেখে দেওয়ার
পরিবর্তে কলটি সঙ্গে সঙ্গে শেষ করা হয়। এটি কল
ইতিহাসে end_reason
inbound_config_webhook_failed-সহ একটি ব্যর্থ, বিলবিহীন কল হিসেবে দেখা যায় এবং সাধারণ
telephony.complete ইভেন্ট পাঠানো হয়। ড্যাশবোর্ডে কলটির
পৃষ্ঠা এবং
GET /v1/calls/{call_id}-এ config_webhook_failure আপনার ওয়েবহুক
কী করেছে তা জানায়: {kind, attempts, http_status, host, source}; এখানে kind হলো http_error,
timeout, connection, dns, tls, response_too_large,
blocked_url, other, invalid_json, non_object_json অথবা
invalid_config, host হলো আপনার ওয়েবহুকের হোস্ট নাম, এবং source হলো
number (এই ওয়েবহুক) অথবা agent_setup (একটি এজেন্টের কল সেটআপ ওয়েবহুক)।
invalid_config-এর ক্ষেত্রে reason জানায় কেন উত্তরটি ব্যবহার করা যায়নি এবং
fields সংশ্লিষ্ট ফিল্ডগুলোর নাম দেয়: no_agent (agent_id বা
prompt কোনোটিই নেই; fields উপেক্ষা করা কীগুলোর তালিকা দেয়, যেমন ভুল বানানের
agentId), agent_not_found, agent_id_not_integer, unexpected_fields
(agent_id-এর পাশে variables, context, timezone এবং language ছাড়া অন্য
কী), invalid_variables, invalid_context, invalid_language,
unsupported_language, invalid_config_fields অথবা agent_settings_invalid।
অন্যথায় reason হলো null এবং fields খালি থাকে। একমাত্র
ব্যতিক্রম হলো, আদান-প্রদানটি নিজেই ব্যর্থ হলে কোনো কলার আপনার বহির্গামী কলগুলোর একটি ফেরত দিচ্ছে:
দেখুন Callbacks।
একটি widget session (web.incoming) সর্বোচ্চ 10 সেকেন্ডের একটি মাত্র চেষ্টা পায়।
এটি ব্যর্থ হলে, session request 502 বা 422 দিয়ে ব্যর্থ হয়।
অনুরোধ পেলোড
ফোন কলের জন্য (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| ফিল্ড | ধরন | বিবরণ |
|---|---|---|
call_id | integer | কল আইডি — এই কলের সব ইভেন্ট জুড়ে স্থিতিশীল |
from_number | string | E.164 কলার নম্বর |
to_number | string | E.164 গন্তব্য (আপনার ThunderPhone নম্বরগুলোর একটি) |
returning_call | object | গত 30 দিনের মধ্যে এই নম্বরটি কলারকে কল করে থাকলে তবেই উপস্থিত। কলব্যাক দেখুন |
sip_headers | object | X-* বা User-to-User SIP হেডারসহ ম্যানুয়াল SIP সংযোগে কল এলে তবেই উপস্থিত: ছোট হাতের হেডার নাম → মান। SIP হেডার দেখুন |
ওয়েব উইজেট সেশনের জন্য (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 | স্ট্রিং | ব্রাউজার যেভাবে পাঠিয়েছে, সেই অনুযায়ী উইজেট হোস্ট করা পৃষ্ঠার origin। নন-ব্রাউজার ক্লায়েন্ট যেকোনো মান পাঠাতে পারে, তাই অনুরোধটি কোথা থেকে এসেছে তার প্রমাণ হিসেবে এটিকে বিবেচনা করবেন না |
publishable_key_prefix | স্ট্রিং | সেশনটি খোলা পাবলিশেবল কী-এর প্রথম অক্ষরগুলো |
language, primary_language | স্ট্রিং | উইজেট সেশন ভাষা ওভাররাইডের অনুরোধ করলে উপস্থিত থাকে |
voice | স্ট্রিং | উইজেট সেশন ভয়েস ওভাররাইডের অনুরোধ করলে উপস্থিত থাকে |
website_context | স্ট্রিং | উইজেট সেশনভিত্তিক পৃষ্ঠা কনটেক্সট পাঠালে উপস্থিত থাকে |
ওভাররাইড ফিল্ডগুলো (language, voice, website_context, এবং যেকোনো
ব্রাউজার variables) শুধুমাত্র তখনই আসে, যখন পাবলিশেবল কী তার
ব্রাউজার ওভাররাইড-এ সেগুলো অনুমোদন করে। কী যে ফিল্ড অনুমোদন করে না, এমন কোনো ফিল্ড বহনকারী সেশন অনুরোধ এই webhook কল করার আগে প্রত্যাখ্যাত হয়।
প্রতিক্রিয়া স্কিমা
এই কলের জন্য এজেন্ট কনফিগারেশন বর্ণনা করে এমন একটি JSON অবজেক্ট ফেরত দিন।
prompt এবং voice প্রয়োজনীয়; বাকি সবকিছু ঐচ্ছিক।
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| ক্ষেত্র | ধরন | প্রয়োজনীয় | বিবরণ |
|---|---|---|---|
prompt | স্ট্রিং | হ্যাঁ | এজেন্ট পরিচালনাকারী সিস্টেম prompt |
voice | স্ট্রিং | হ্যাঁ | GET /v1/voices থেকে ভয়েস আইডি, যেমন john। voice_name একটি উপনাম হিসেবে গ্রহণ করা হয়। অজানা ভয়েস যাচাইয়ে ব্যর্থ হয় এবং কল প্রত্যাখ্যান করে |
product | স্ট্রিং | না | bolt পাঠান। ডিফল্ট spark, একটি পুরোনো মান যা এখনও 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 | না | শুধু সর্বশেষ টার্নের বদলে কলারের অডিওর শেষ কয়েকটি টার্ন অন্তর্ভুক্ত করুন, যাতে সামান্য বিলম্ব/খরচ বৃদ্ধির বিনিময়ে সংশোধন এবং বানান/সংখ্যা-নির্ভর ডেটা সংগ্রহ উন্নত হয়। ইনবাউন্ড সেশনের জন্য ডিফল্টভাবে চালু এবং আউটবাউন্ড ফোন কলের জন্য বন্ধ; null ডিফল্ট বজায় রাখে |
storm_feedback_mode | স্ট্রিং | না | none, acknowledgement (ডিফল্ট), অথবা tick: audio_tier plus বা max হলে ধীরগতির উত্তর প্রস্তুত করার সময় কলার যা শোনে |
language | স্ট্রিং | না | primary_language-এর সংক্ষিপ্ত রূপ। agent_id-এর পাশেও অনুমোদিত, যেখানে এটি সেই ভাষা যাতে এই কল শুরু হয় এবং যার জন্য এজেন্টের ভয়েসে কথা বলা হয়; দেখুন প্রতি কলে ভাষা সেট করুন |
primary_language | স্ট্রিং | না | স্বাভাবিকীকৃত ভাষা কোড (ডিফল্ট en)। সমাধান করা যায় না এমন কোড কল প্রত্যাখ্যান করে |
has_additional_languages | বুলিয়ান | না | ডিফল্ট false |
additional_languages | স্ট্রিংয়ের অ্যারে | না | এজেন্ট যেসব অতিরিক্ত ভাষায় পরিবর্তন করতে পারে |
native_voice_switching | বুলিয়ান | না | ডিফল্ট false। কল অন্য ভাষায় পরিবর্তিত হলে, কনফিগার করা ভয়েস বজায় রাখার বদলে সেই ভাষার স্থানীয় ভয়েসে পরিবর্তন করুন (লিঙ্গ অনুযায়ী মিলিয়ে) |
language_switching | স্ট্রিং | null | না | ask_first (ডিফল্ট) অথবা follow_caller; null ask_first-এর সমান। একটি বহুভাষী এজেন্ট তার অন্য কোনো ভাষায় অপর ব্যক্তি কথা বললে কীভাবে পরিচালনা করে। তারা ভাষাটির অনুরোধ করলে বা তাতে একটি সম্পূর্ণ বাক্য বললে ask_first সঙ্গে সঙ্গে পরিবর্তন করে, এবং "sí"-এর মতো সংক্ষিপ্ত কিছু বলার পরে তাতে চালিয়ে যাবেন কি না জিজ্ঞাসা করে। follow_caller তাদের বলা যেকোনো কনফিগার করা ভাষায় পরিবর্তন করে, এমনকি একটি শব্দ হলেও। শুধু additional_languages সেট থাকলে প্রযোজ্য |
audio_tier | স্ট্রিং | null | না | শুধু product: "bolt"। শোনা: এজেন্ট কত সতর্কতার সঙ্গে কলারকে শোনে। অধিকাংশ কলের জন্য standard (ডিফল্ট; "" এবং null একই অর্থে) উপযুক্ত (PHI প্রক্রিয়াকরণ করা কলগুলো শুধু BAA-আচ্ছাদিত প্রদানকারী ব্যবহার করে)। lite সবচেয়ে সস্তা এবং বেশি ভুল শোনে। plus কঠিন টার্নে আরও মনোযোগ দিয়ে শোনে, যেগুলোতে প্রায় 1–2 সেকেন্ড বেশি সময় লাগে। max সবচেয়ে কঠিন অডিও ও বিরল ভাষার জন্য; প্রতিটি উত্তরে 3–4 সেকেন্ড লাগে এবং কল pro ইন্টেলিজেন্স চালায় (intelligence উপেক্ষা করা হয়)। max সাধারণভাবে উপলভ্য নয়: যে সংস্থার জন্য এটি সক্রিয় করা হয়নি, তার ক্ষেত্রে কল plus এবং আপনার নির্ধারিত intelligence চালায় (এটি-সহ একটি আউটবাউন্ড কল অনুরোধ 400 দিয়ে প্রত্যাখ্যাত হয়)। পুরোনো মান lean (Lite), hearing (Plus) এবং deep_hearing (Max) এখনও গ্রহণ করা হয়। অন্যান্য প্রোডাক্ট এটি উপেক্ষা করে |
endpointing | স্ট্রিং | null | না | faster (200 ms), fast (300 ms), normal (500 ms, ডিফল্ট) অথবা patient (800 ms); null normal-এর সমান। কলার থামার পরে মডেলের কাছে উত্তর চাওয়ার আগে একটি Bolt v2 এজেন্ট কতক্ষণ অপেক্ষা করে। কম অপেক্ষায় দ্রুত উত্তর দেওয়া যায়, তবে কলারের পরবর্তী শব্দ যেসব অনুরোধ অপ্রাসঙ্গিক করে দিতে পারে সেরকম আরও অনুরোধ পাঠায়, যা মডেল খরচ বাড়ায়। অন্যান্য প্রোডাক্ট এটি উপেক্ষা করে |
eagerness | স্ট্রিং | null | না | অবচিত: October 19, 2026 পর্যন্ত endpointing-এর নাম, এখনও পড়া হয়। endpointing সেট থাকলে উপেক্ষা করা হয় |
intelligence | স্ট্রিং | null | না | core অথবা pro (ডিফল্ট); null pro-এর সমান। Bolt v2 পাইপলাইনে একটি bolt এজেন্ট কতটা নির্ভরযোগ্যভাবে তার নির্দেশনা অনুসরণ করে। core-এ প্রথম শব্দ পর্যন্ত প্রায় 700 ms, সবচেয়ে সস্তা এবং কিছুটা কম নির্ভরযোগ্য (PHI হিসেবে বিবেচিত কলে প্রায় 900 ms এবং কম নির্ভরযোগ্য); pro প্রায় 900 ms; যেসব Core উত্তরে শুধু একটি টুল কল করা হতো, সেগুলো Pro-তে পাঠানো হয়। পুরোনো মান lite (Core) এবং standard (Pro) এখনও গ্রহণ করা হয়, এবং অবসরপ্রাপ্ত plus ও max pro-তে চলে। audio_tier max হলে উপেক্ষা করা হয়। অন্যান্য প্রোডাক্ট এটি উপেক্ষা করে |
faster_replies | বুলিয়ান | null | না | গতি বৃদ্ধি। ডিফল্ট true। Bolt v2 পাইপলাইনে একটি bolt এজেন্টে, সামান্য বেশি খরচে উত্তর একটু দ্রুত শুরু হয়। false এটি বন্ধ করে। অন্যান্য প্রোডাক্ট এটি উপেক্ষা করে |
background_track | স্ট্রিং | null | না | পরিবেশগত অডিও আইডি অথবা null |
acknowledgement_prompt_mode | স্ট্রিং | না | auto (ডিফল্ট) অথবা manual (পুরোনো -with-ack প্রোডাক্ট মান) |
acknowledgement_prompt | স্ট্রিং | না | acknowledgement_prompt_mode="manual" হলে ব্যবহৃত হয় |
silence_interval_seconds | পূর্ণসংখ্যা | null | না | 5–120। চেক-ইনের আগে কলারের নীরবতার সেকেন্ড |
silence_max_checkins | পূর্ণসংখ্যা | null | না | 1–10 |
silence_checkins_enabled | বুলিয়ান | না | ডিফল্ট true |
silence_final_action | স্ট্রিং | না | শেষ চেক-ইনের পরে: hang_up (ডিফল্ট) অথবা silence_transfer_destination-এ transfer |
silence_transfer_destination | স্ট্রিং | না | এই কনফিগের transfer_destinations-এ একটি এন্ট্রির নাম; transfer-এর সঙ্গে প্রয়োজনীয়। transfer_destinations ছাড়া ট্রান্সফার করা যায় না এবং এজেন্ট কল কেটে দেয় |
silence_final_message | স্ট্রিং | না | ≤ 300 অক্ষর, যেভাবে লেখা আছে সেভাবেই পড়া হয়; "" (ডিফল্ট) ডিফল্ট লাইন ব্যবহার করে |
connect_tone_enabled | বুলিয়ান | না | ডিফল্ট false |
pronunciation_dicts | বুলিয়ান | null | না | ডিফল্ট false; null false-এর সমান। true হলে, যেখানে উপলভ্য, কলের Cartesia স্পিচ কলের ভাষার জন্য ThunderPhone-এর উচ্চারণ অভিধান ব্যবহার করে। ফোন ও উইজেট কলে কাজ করে। শুধু ThunderPhone-এর নিজস্ব Cartesia ভয়েসের ক্ষেত্রে প্রযোজ্য, আপনার নিজস্ব Cartesia API কী-এর ভয়েসের ক্ষেত্রে নয়। agent_id-এর সঙ্গে ব্যবহৃত হয় না, যেখানে সংরক্ষিত এজেন্টের সেটিংস প্রযোজ্য |
words | অ্যারে | null | না | এজেন্ট কীভাবে নির্দিষ্ট শব্দ বলে, support ছাড়া এজেন্টের words-এর মতো একই এন্ট্রি। language ছাড়া একটি এন্ট্রি এই কনফিগের ভাষা গ্রহণ করে। null এবং [] কোনোটিই নেই বোঝায়। agent_id-এর সঙ্গে ব্যবহৃত হয় না, যেখানে সংরক্ষিত এজেন্টের শব্দ প্রযোজ্য |
voicemail_action | স্ট্রিং | না | prompt (ডিফল্ট), hangup, অথবা message |
voicemail_message | স্ট্রিং | না | voicemail_action="message" হলে ব্যবহৃত হয় |
agent_name | স্ট্রিং | না | ড্যাশবোর্ড ও উইজেটে প্রদর্শিত নাম |
org_name | স্ট্রিং | না | এজেন্টের পারসোনার জন্য সংস্থার প্রদর্শিত নাম |
tools | অ্যারে | না | ইনলাইন ফাংশন-টুল স্কিমা (দেখুন ফাংশন টুল) |
transfer_destinations | অবজেক্টের অ্যারে | null | না | এই কল সর্বোচ্চ 50টি {name, number} এন্ট্রিতে ট্রান্সফার করতে পারে, যা এজেন্টের ট্রান্সফার নম্বর-এর মতো যাচাই করা হয়। এজেন্ট নাম অনুযায়ী এবং শুধু এগুলোতেই ট্রান্সফার করে; [] কোনো ট্রান্সফার নেই বোঝায়। এজেন্টকে তার পছন্দের নম্বরে ট্রান্সফার করতে দিতে এটি বাদ দিন বা null পাঠান |
timezone | স্ট্রিং | না | এই কলের জন্য IANA সময় অঞ্চল, যেমন America/Chicago। এজেন্ট তার নিজস্ব সময় অঞ্চলের পরিবর্তে এতে তারিখ ও সময় বলে। agent_id-এর পাশেও অনুমোদিত। IANA অঞ্চল নয় এমন মান উপেক্ষা করা হয়। দেখুন প্রতি কলে সময় অঞ্চল সেট করুন |
context | স্ট্রিং | null | না | এই কলের জন্য মুক্ত-রূপের টেক্সট, যেমন আপনার সিস্টেম সংগৃহীত নোট, সর্বোচ্চ 20,000 অক্ষর। একটি সীমাবদ্ধ ব্লকে prompt-এর পরে যোগ করা হয় এবং টেমপ্লেট হিসেবে রেন্ডার করা হয় না। agent_id-এর পাশেও অনুমোদিত। স্ট্রিং নয় এমন বা এর চেয়ে দীর্ঘ মান কল প্রত্যাখ্যান করে। দেখুন কল ভেরিয়েবল ও কনটেক্সট |
call_id | পূর্ণসংখ্যা | না | অনুরোধের কল আইডির ঐচ্ছিক প্রতিধ্বনি; উপেক্ষা করা হয় |
যেহেতু prompt এবং voice আবশ্যক, তাই {} ফেরত দিলে বা যাচাইকরণে ব্যর্থ হয় এমন কোনো প্রতিক্রিয়া ফেরত দিলে কল প্রত্যাখ্যাত হয়: টাইমআউট এবং পুনঃচেষ্টা-এ বর্ণিত অনুযায়ী একটি ফোন কল শেষ হয়ে যায় এবং একটি উইজেট সেশন অনুরোধ 422 সহ ব্যর্থ হয়। এটি পুনরায় কল করা কলারদের ক্ষেত্রেও প্রযোজ্য: আপনার webhook যে কোনো JSON অবজেক্ট ফেরত দেয় সেটিই তার উত্তর, এবং {} হলো একটি কল প্রত্যাখ্যান করার উপায়।
এজেন্ট কল সেটআপ ওয়েবহুক
একটি এজেন্টের নিজস্ব কল সেটআপ ওয়েবহুক থাকতে পারে: এর সেটিংসে থাকা কল সেটআপ ওয়েবহুক
ফিল্ড, অথবা API-তে call_setup_webhook_url।
এজেন্টটিকে একটি নম্বরে অ্যাসাইন করুন, এবং সেই নম্বরে এজেন্ট উত্তর দেওয়া প্রতিটি ইনবাউন্ড কলের
আগে ThunderPhone ওই কলের ভেরিয়েবল ও প্রসঙ্গের জন্য ওয়েবহুককে জিজ্ঞাসা করে। নম্বরটি তার
এজেন্ট বজায় রাখে, তাই ফোন নম্বর পৃষ্ঠা এবং এজেন্ট পৃষ্ঠা দেখায় কোন এজেন্ট সেটির উত্তর দেয়।
এটি এজেন্টের অন্যান্য সেটিংসের মতোই একটি সেটিং: খসড়া হিসেবে রাখা হয়, ডিপ্লয় করার সময় প্রকাশিত
হয় এবং সংস্করণ ইতিহাসে রাখা হয়। একটি নম্বর
পুরোনো সংস্করণে পিন করা থাকলে
সেই সংস্করণের URL-কে জিজ্ঞাসা করে। অনুরোধগুলো এজেন্টের নিজস্ব
call_setup_webhook_signing_secret দিয়ে সাইন করা হয় (প্রতিষ্ঠানের ওয়েবহুক
সিক্রেট দিয়ে নয়), এবং উপরে-এর মতো একই
X-ThunderPhone-Signature হেডার, টাইমআউট, পুনঃচেষ্টা ও idempotency key ব্যবহার করে। সিক্রেটটি
শুধু লেখার জন্য: আপনার endpoint যে সিক্রেটটি যাচাই করে সেটি সেট করুন (এজেন্টের সেটিংসে বা
PATCH /v1/agents/{id} দিয়ে); কোনো read এটি ফেরত দেয় না, এবং
call_setup_webhook_signing_secret_set বলে একটি সেট করা আছে কি না।
অনুরোধটি উপরের telephony.incoming payload-এর সঙ্গে যে এজেন্টের তথ্য এটি পূরণ করে তা যোগ করে:
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567",
"variables": null,
"agent": {
"id": 12,
"name": "Front desk",
"version": 7,
"version_pinned": false
}
}
}| ফিল্ড | ধরন | বিবরণ |
|---|---|---|
agent.id | পূর্ণসংখ্যা | নম্বরে অ্যাসাইন করা এজেন্ট |
agent.name | স্ট্রিং | এর নাম |
agent.version | পূর্ণসংখ্যা | null | যে সংস্করণটি উত্তর দেবে তার নম্বর: নম্বরটির পিন করা সংস্করণ, অথবা এজেন্টের সর্বশেষ প্রকাশিত সংস্করণ (null, যদি কোনোটি না থাকে) |
agent.version_pinned | বুলিয়ান | নম্বরটি সেই সংস্করণে পিন করা আছে কি না |
কলে যা প্রয়োজন, তা দিয়ে উত্তর দিন। এর যেকোনোটি নম্বরের সংস্করণে অ্যাসাইন করা এজেন্টকে পূরণ করে:
{"variables": {...}},{"context": "..."}, অথবা দুটিই- অ্যাসাইন করা এজেন্টের id-তে সেট করা
"agent_id"-সহ একইটি {}: কোনো তথ্য পূরণ না করেই এজেন্ট উত্তর দেয়
agent_id-এর পাশের মতো timezone এবং language-ও অনুমোদিত।
ভেরিয়েবল এজেন্টের {{placeholders}} পূরণ করে; prompt-এর পরে প্রসঙ্গ যোগ করা হয়।
অথবা কলের সিদ্ধান্ত নিজেই নিন। অন্য এজেন্টের একটি agent_id, অথবা একটি prompt-সহ
সম্পূর্ণ কনফিগারেশন, অ্যাসাইন করা এজেন্টের (এবং তার পিন করা সংস্করণের) পরিবর্তে এই একটি কলের
উত্তর দেয়। কলের বিবরণে প্রতিটি ক্ষেত্রকে call_setup_webhook-এ
assigned_agent, other_agent অথবা inline_config হিসেবে চিহ্নিত করা হয়। যে উত্তর ব্যবহার করা
যায় না (অজানা agent_id, variables-এর পাশে অন্য key, যাচাইকরণে ব্যর্থ কনফিগারেশন) তা একটি
নম্বরের ওয়েবহুকের মতোই কল শেষ করে।
ওয়েবহুককে কখন উত্তর দিতে হবে। কোনো এজেন্টের সেটিংসে ডিফল্ট ছাড়া একটি {{variable}}
ব্যবহৃত হলে এজেন্টটির ওয়েবহুক প্রয়োজন: এর prompt বা পুনর্ব্যবহারযোগ্য নির্দেশনা, ধাপের
নির্দেশনা বা লাইন, স্বীকৃতি prompt, ভয়েসমেইল বার্তা, সম্মতি ঘোষণা, অথবা একটি {{variable}}
ট্রান্সফার নম্বর। এজেন্টের call_setup_webhook_variables এগুলোর তালিকা দেয়।
- এটির ওয়েবহুক প্রয়োজন: ওয়েবহুকের টাইমআউট হলে, পৌঁছানো না গেলে, অথবা এটি ত্রুটি বা JSON
object নয় এমন body দিয়ে উত্তর দিলে, ওই ভেরিয়েবলগুলোর একটির জন্য কলে আগে থেকেই মান থাকলেও
কল শুরু হয় না। টাইমআউট ও পুনঃচেষ্টা-এ বর্ণিত অনুযায়ী ঠিক একইভাবে
এটি শেষ ও রেকর্ড করা হয় (
end_reasoninbound_config_webhook_failed, বিলযোগ্য নয়)। - এটির কিছুই প্রয়োজন নেই (কোনো ভেরিয়েবল নেই, অথবা প্রতিটির
{{first_name|there}}-এর মতো একটি ডিফল্ট আছে): ওয়েবহুক তবুও চলে, কিন্তু ব্যর্থ হলে এজেন্ট এটি ছাড়াই উত্তর দেয় এবং কলের বিবরণে কী ভুল হয়েছে তা-সহwebhook_failedদেখায়।
শুধু কল কনটেক্সট কখনোই ওয়েবহুককে আবশ্যক করে না: এজেন্টের সেটিংসে এমন কিছু নেই যা বলে যে তার কনটেক্সট দরকার। আপনার ওয়েবহুকের উত্তর ছাড়া কল শুরু করা না গেলে, ডিফল্ট ছাড়া একটি ভেরিয়েবল ব্যবহার করুন।
অ্যাসাইন ও মোতায়েন। যে এজেন্টের ওয়েবহুক প্রয়োজন, তাকে ওয়েবহুক ছাড়া
কোনো নম্বরে অ্যাসাইন করা যায় না: ভেরিয়েবলগুলোর নাম উল্লেখ করে একটি বার্তাসহ
অ্যাসাইনমেন্টটি প্রত্যাখ্যান করা হয়। কোনো নম্বরের সংস্করণ পরিবর্তিত হলে, পিন করা
নম্বর আবার সর্বশেষ সংস্করণে ফিরে গেলেও একই পরীক্ষা চলে। এজেন্ট তার
প্রকাশিত সেটিংস দিয়ে একটি নম্বরে উত্তর দেওয়ার সময়, ওয়েবহুক ছাড়া এমন একটি
ভেরিয়েবল যোগ করে এমন মোতায়েন
(বা ওয়েবহুক সরিয়ে দেয়) একইভাবে প্রত্যাখ্যান করা হয়। ড্রাফট সংরক্ষণ করা
সবসময় অনুমোদিত, এবং সমস্যাটি সমাধান না হওয়া পর্যন্ত এজেন্টের warnings-এ
call_setup_webhook_needed থাকে।
এজেন্টের ওয়েবহুক কেবল যে নম্বরগুলোতে এজেন্টটি অ্যাসাইন করা আছে, সেসব নম্বরে আসা ফোন কলের জন্য চলে। আউটবাউন্ড কল, ওয়েব উইজেট সেশন, SIP ঠিকানা, সিমুলেশন এবং ড্যাশবোর্ড টেস্ট কথোপকথন এটি কল করে না; আগের মতোই তারা রিকোয়েস্ট থেকে তাদের ভেরিয়েবল নেয়।
সংরক্ষিত নমুনা দিয়ে পরীক্ষা। কোনো নির্দিষ্ট উত্তরের ভিত্তিতে আপনার এজেন্ট কী করে পরীক্ষা করতে (ফিরে আসা কলার, কোনো রেকর্ড পাওয়া যায়নি, স্প্যানিশভাষী কলার), সেই উত্তরটি এজেন্টে নমুনা হিসেবে সংরক্ষণ করুন: এর variables, context এবং ঐচ্ছিকভাবে language, সরাসরি লিখে বা আগের কোনো কল থেকে কপি করে। ড্যাশবোর্ডে পরীক্ষা কথোপকথন, আপনার ফোনে পরীক্ষা কল, বা এজেন্টের বিপরীতে সিমুলেশন শুরু করার সময় এটি বেছে নিন, এবং কলটি এমনভাবে চলবে যেন আপনার webhook এটি দিয়ে উত্তর দিয়েছে। নমুনাগুলো এজেন্টের প্রতিটি সংস্করণে ভাগাভাগি করা হয়। একটি সম্পাদনা করলে এর আগের সংস্করণগুলো বজায় থাকে: এজেন্টের কোনো পরিবর্তনে এমন একটি variable প্রয়োজন হলে যা নমুনাটি সেট করে না, সেটি নমুনায় যোগ করুন, এবং এজেন্টের পুরোনো সংস্করণগুলো নমুনাটি আগের অবস্থাতেই ব্যবহার করতে থাকবে। ফোন নম্বরে ডায়াল করা সিমুলেশনগুলো পরিবর্তে আপনার প্রকৃত webhook চালায়।
কোনো এজেন্ট অ্যাসাইন করা নেই এমন নম্বরগুলো উপরে বর্ণিত অনুযায়ী নম্বরের বা প্রতিষ্ঠানের ওয়েবহুক ব্যবহার করতে থাকে।
কলব্যাক
লোকেরা প্রায়ই যে নম্বর থেকে কল পেয়েছেন সেই নম্বরে আবার কল করেন, যেমন আপনার এজেন্ট ভয়েসমেল রেখে যাওয়ার পরে। গত 30 দিনের মধ্যে একই নম্বরে কল করা কারও কাছ থেকে ফোন কল এলে, ThunderPhone এমন সর্বশেষ আউটবাউন্ড কলটি খুঁজে পায় (যেটি তাদের ফোনে রিং হয়েছিল) এবং এটি তিনভাবে ব্যবহার করে:
-
অনুরোধে
returning_call। উপরের ব্লকিং অনুরোধ এবং এন্ডপয়েন্ট বিজ্ঞপ্তি এটি বহন করে, যাতে আপনার হ্যান্ডলার কলারকে রাউট করতে পারে:{ "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567", "returning_call": { "call_id": 987650001, "agent_id": 13, "started_at": "2026-10-21T19:05:12.402Z", "outcome": "voicemail" } } }ক্ষেত্র ধরন বিবরণ call_idপূর্ণসংখ্যা আগের আউটবাউন্ড কল agent_idপূর্ণসংখ্যা | null যে এজেন্ট কলটি করেছিল; inline config দিয়ে করা কলের জন্য বা যার এজেন্ট মুছে ফেলা হয়েছে, তার জন্য nullstarted_atস্ট্রিং কখন এটি শুরু হয়েছিল (ISO 8601, UTC) outcomeস্ট্রিং no_answer(রিং শেষ হয়েছে, ব্যস্ত ছিল বা প্রত্যাখ্যাত হয়েছে),voicemail(ভয়েসমেল উত্তর দিয়েছে, অথবা কেউ এজেন্টের সঙ্গে কথা বলেনি),conversation(কেউ এজেন্টের সঙ্গে কথা বলেছে) অথবাanswered(কল গ্রহণ করা হয়েছে; কে গ্রহণ করেছে তা এখনো জানা নেই) -
এজেন্টের জন্য প্রেক্ষাপট। যে এজেন্ট উত্তর দেয়, তার prompt-এর শেষে একটি সংক্ষিপ্ত নোট পায়: আগের কলটি কখন করা হয়েছিল, কোন এজেন্ট করেছিল এবং তার ফলাফল। এজেন্টকে এটি জোরে পড়তে নিষেধ করা হয় এবং, কলার ID জাল করা যেতে পারে বলে, আগে নম্বরটিতে কল করা হয়েছিল—এর বেশি ওই কল সম্পর্কে কিছু শেয়ার না করতে বলা হয়।
-
একটি ফলব্যাক এজেন্ট। নম্বরটিতে কোনো ইনবাউন্ড এজেন্ট না থাকলে এবং কোনো webhook URL না থাকার কারণে বা আপনার webhook কোনো উত্তর না দেওয়ার কারণে কনফিগারেশন না এলে (এর সময়সীমা শেষ হয়েছে, এটিতে পৌঁছানো যায়নি, অথবা উভয় প্রচেষ্টায়
5xx,408বা429উত্তর দিয়েছে), কলটি শেষ হওয়ার পরিবর্তে আগের কলটি করা এজেন্টের কাছে যায়, যদি সেই এজেন্ট এখনো আপনার প্রতিষ্ঠানে থাকে। এটি ওই এজেন্টের মোতায়েনকৃত সেটিংস দিয়ে চলে। আপনার webhook যে কোনো উত্তর দিলেও সেটিই সিদ্ধান্ত নেয়: আরেকটি4xx, JSON object নয় এমন একটি বডি,{}, বা যাচাইকরণে ব্যর্থ কোনো config কলটিকে আগের মতো শেষ করে। নম্বরের একটি ইনবাউন্ড এজেন্ট সবসময় উত্তর দেয়।
আগের কলের বিবরণ শেয়ার করা। কলার ID জাল করা যেতে পারে, তাই ডিফল্টভাবে
আগের কলের কনটেন্ট থেকে নতুন কলে কিছুই পৌঁছায় না। প্রতিষ্ঠানের একজন প্রশাসক
Organization → General → Callbacks-এর অধীনে আগের কলের বিবরণ শেয়ার করুন
চালু করতে পারেন (অথবা
callback_context_details_enabled
সেট করতে পারেন)। এটি চালু থাকলে, এজেন্টের নোটে আগের কলের সারাংশও উদ্ধৃত হয়
এবং আগের কলটি করা এজেন্টের কাছে রাউট করা একটি কল ওই কলের variables (যেমন
কোনো পরিচিতির নাম) দিয়ে চলে। ওই নম্বর থেকে কল করা যে কারও সঙ্গে এই বিবরণ
শেয়ার করা নিরাপদ হলেই কেবল এটি চালু করুন। এটি চালু থাকলেও, যে কলে সুরক্ষিত
স্বাস্থ্য তথ্য থাকতে পারে সেটি কখনোই তার সারাংশ বা variables এমন কোনো কলে
পাঠায় না, যা PHI প্রক্রিয়াকরণের জন্য নির্ধারিত নয়।
কলের বিবরণে। আগের কোনো কলের সঙ্গে মিলে যাওয়া একটি ইনবাউন্ড কলে GET /v1/calls/{call_id}-এ একটি callback অবজেক্ট থাকে:
উপরের returning_call, routed_as_callback (ফলব্যাক এটি উত্তর দিয়েছিল কি না), এবং config_webhook_failure (আপনার webhook কোনো উত্তর না দিলে এবং ফলব্যাক কলটি নিলে {kind, attempts, http_status, host}, অন্যথায় null), ফলে কলের উত্তর দেওয়া হলেও webhook বিভ্রাট দৃশ্যমান থাকে।
প্রতিক্রিয়ার আকারসীমা
উদাহরণ হ্যান্ডলার
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 যাতে কথোপকথনের মাঝখানে আপনার API কল করতে পারে, সেজন্য টুল সংযুক্ত করুন:
{
"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"
}
}
}
]
}সেটিংসের সংক্ষিপ্ত নির্দেশিকা
product: "bolt" পাঠান এবং এই ফিল্ডগুলো দিয়ে কল টিউন করুন। পুরোনো
product মানগুলো (spark এবং storm-* মানগুলো) এখনও গ্রহণ করা হয়।
| ফিল্ড | মান | কী সমন্বয় করে |
|---|---|---|
intelligence | core, pro (ডিফল্ট) | Core সস্তা এবং দ্রুত উত্তর দিতে শুরু করে; Pro দীর্ঘ prompt আরও নির্ভরযোগ্যভাবে অনুসরণ করে |
audio_tier | lite, standard (ডিফল্ট), plus, max | উচ্চতর টিয়ারগুলো ভালো শোনে এবং বেশি খরচ হয়; কিছু টার্নে Plus 1–2 s যোগ করে, প্রতিটি Max উত্তরে 3–4 s লাগে (Max সাধারণভাবে উপলভ্য নয়) |
endpointing | faster, fast, normal (ডিফল্ট), patient | কম অপেক্ষার সময় দ্রুত উত্তর দেয় এবং বেশি খরচ হয় |
faster_replies | true (ডিফল্ট), false | গতি বৃদ্ধি: সামান্য বেশি খরচে উত্তর একটু দ্রুত দেয় |
সম্পর্কিত
কল শেষের নন-ব্লকিং ইভেন্ট।
tools[] এবং স্বাক্ষরিত এন্ডপয়েন্ট কনট্র্যাক্টের সম্পূর্ণ JSON স্কিমা।
একাধিক URL-কে telephony.incoming / web.incoming-এ সাবস্ক্রাইব করুন।
প্রতিটি কলারের জন্য prompt, টুল এবং A/B পরীক্ষার প্যাটার্ন।