Developer cookbook

প্রতি-কলে ভেরিয়েবল

ডিপ্লয় করা prompt, টুল বা সেটিংস পরিবর্তন না করে প্রতিটি কলের জন্য একটি সংরক্ষিত এজেন্টকে ব্যক্তিগতকৃত করুন।

আপনার সংরক্ষিত এজেন্টের prompt-এ প্লেসহোল্ডার রাখুন, তারপর কল শুরু করার সময় একটি variables অবজেক্ট দিন। সংরক্ষিত কনফিগারেশন এবং সংস্করণ ইতিহাস অপরিবর্তিত থাকে। ThunderPhone কল কনফিগারেশন ভয়েস রানটাইমে পাঠানোর আগে টেক্সট রেন্ডার করে।

কোনো মানের প্রয়োজন না হলে variables বাদ দিন, null পাঠাবেন না (400 দিয়ে প্রত্যাখ্যাত হবে)।

প্লেসহোল্ডার এবং ডিফল্ট#

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

নামগুলো কেস-সেনসিটিভ এবং [A-Za-z_][A-Za-z0-9_]* অনুসরণ করে। নামের চারপাশে হোয়াইটস্পেস অনুমোদিত; |-এর পরের হোয়াইটস্পেস ডিফল্টের অংশ এবং সংরক্ষিত থাকে। name অনুপস্থিত বা null হলে {{name|Friend}} Friend ব্যবহার করে; একটি খালি স্ট্রিং স্পষ্টভাবে দেওয়া মান হিসেবে বিবেচিত হয়। ডিফল্ট ছাড়া অনুপস্থিত মান খালি স্ট্রিং হয়ে যায় এবং তাদের নাম unresolved_variables-এ প্রদর্শিত হয়। ডাবল ব্রেসের মধ্যে থাকা টেক্সট বৈধ প্লেসহোল্ডার না হলে তা সরিয়ে ফেলা হয়। প্রতিটি সরবরাহ করা মানের ভেতরের ডাবল-ব্রেসযুক্ত টেক্সট আলাদাভাবে সরিয়ে ফেলা হয়; একটি মান আশপাশের prompt টেক্সট বা অন্য কোনো মান সরাতে পারে না। অমিল ডাবল-ব্রেস ডিলিমিটারও সরিয়ে ফেলা হয়। prompt-এ JSON উদাহরণে {{ ব্যবহার করা যাবে না। মানগুলো সাধারণ টেক্সট; এগুলোকে কখনো কোড হিসেবে মূল্যায়ন করা হয় না বা টেমপ্লেট হিসেবে পুনরাবৃত্তভাবে প্রসারিত করা হয় না।

স্বীকৃতি prompt, আউটবাউন্ড ভয়েসমেইল বার্তা এবং ফোন কলের জন্য সেই ফিল্ড পাঠানো হলে সম্মতি ঘোষণার টেক্সটেও ভেরিয়েবল থাকতে পারে। এজেন্টের আলাদা কোনো first_message ফিল্ড নেই: prompt-এ এর প্রাথমিক নির্দেশনা দিন। বিদ্যমান ভয়েসমেইল {agent_name} এবং {org_name} প্লেসহোল্ডার কাজ করতে থাকবে।

মান স্ট্রিং, সংখ্যা, বুলিয়ান বা null হতে পারে; বুলিয়ান true এবং false হিসেবে রেন্ডার হয়। নিউলাইন (\n), ট্যাব (\t), এবং ক্যারেজ রিটার্ন (\r) ছাড়া ইউনিকোড কন্ট্রোল (Cc) ক্যারেক্টার, সব ফরম্যাট (Cf) ক্যারেক্টার এবং সারোগেট (Cs) কোড পয়েন্ট সরিয়ে ফেলা হয়; \r\n-কে \n-এ স্বাভাবিক করা হয়। রেন্ডার করার সময় প্রতিটি মান 2,000 ক্যারেক্টারের মধ্যে সীমাবদ্ধ। সরবরাহ করা স্ট্রিং সংরক্ষণের আগেও পরিষ্কার করা এবং ছাঁটা হয়। মূল অবজেক্টটি 32 KB-এর UTF-8 JSON-এর মধ্যে হতে হবে; বড় অবজেক্ট কল/সেশন অনুরোধে 400 পায়, আর ক্যাম্পেইন ইমপোর্টে অবৈধ সারিগুলো আলাদাভাবে রিপোর্ট করা হয়। অ্যারে এবং নেস্টেড অবজেক্ট মান হিসেবে গ্রহণ করা হয় না। অমিল মেটাডেটা কী (উদাহরণস্বরূপ, স্পেসসহ একটি CSV হেডার) সংরক্ষিত থাকে এবং ফেরত পাঠানো হয়, তবে প্লেসহোল্ডার দিয়ে রেফারেন্স করা যায় না।

মানগুলো কোথা থেকে আসে#

আউটবাউন্ড API#

POST /v1/call-এ agent_id-এর সঙ্গে variables পাঠান:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

এটি ফোন নম্বরের ডিফল্ট আউটবাউন্ড এজেন্টের সঙ্গেও কাজ করে, অথবা ইনলাইন config.prompt-এর সঙ্গেও। ভিন্ন ভেরিয়েবলের সঙ্গে একটি আইডেমপোটেন্সি কী পুনরায় ব্যবহার করা যাবে না।

ক্যাম্পেইন CSV#

ফোন-বহির্ভূত CSV কলামগুলো ইতিমধ্যেই কনট্যাক্ট ভেরিয়েবল হিসেবে সংরক্ষিত থাকে। এখন প্রতিটি ডায়াল স্বয়ংক্রিয়ভাবে সেগুলো ব্যবহার করে। আপনার প্লেসহোল্ডারের সঙ্গে মিলাতে name, account_id, এবং appointment_slot-এর মতো হেডার ব্যবহার করুন। বিদ্যমান নাম ম্যাপিং প্রথম ও শেষ নামের কলাম একত্র করে name ভেরিয়েবলে রাখতে পারে।

ডায়নামিক কনফিগারেশন ওয়েবহুক#

ব্লকিং কনফিগারেশন ওয়েবহুক পাথে, আপনার প্রতিষ্ঠানের একটি সংরক্ষিত এজেন্ট এবং প্রতি-কলে প্রযোজ্য যেকোনো মান ফেরত দিন:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

রেসপন্সের কীগুলো রিকোয়েস্ট-স্তরের ভেরিয়েবল ওভাররাইট করে, অন্য রিকোয়েস্ট কীগুলো অপরিবর্তিত থাকে। null রেসপন্স মান প্লেসহোল্ডারের ডিফল্ট নির্বাচন করে। মার্জ করা অবজেক্টটি অবশ্যই 32 KB-এর মধ্যে হতে হবে। সংরক্ষিত-এজেন্ট রেসপন্স শুধু agent_id এবং variables গ্রহণ করে; prompt বা সেটিংস প্রতিস্থাপন করতে হলে ইনলাইন কনফিগারেশন ফেরত দিন। prompt-সম্বলিত রেসপন্স সবসময় ইনলাইন কনফিগারেশন ব্যবহার করে: সেই রেসপন্সে থাকা যেকোনো agent_id উপেক্ষা করা হয়, null বা পূর্ণসংখ্যা নয় এমন মেটাডেটাসহ। ইনলাইন prompt-কে তবুও স্বাভাবিক ভ্যালিডেশন পাস করতে হবে। ইনলাইন ওয়েবহুক রেসপন্সেও variables অন্তর্ভুক্ত থাকতে পারে। সংরক্ষিত-এজেন্ট ওয়েবহুক রেসপন্স ফোন ও উইজেট উভয় কলে এজেন্টের ডিপ্লয় করা A/B বিভাজন ব্যবহার করে; ভ্যারিয়েন্ট নির্বাচনের পরে ভেরিয়েবল রেন্ডার হয়। ইনবাউন্ড ফোন কলে, কোনো বরাদ্দকৃত ইনবাউন্ড এজেন্ট নেই এমন একটি নম্বর ব্যবহার করুন এবং তার ফোন-নম্বর বা প্রতিষ্ঠানের ওয়েবহুক কনফিগার করুন; উইজেট কী mode="webhook" ব্যবহার করে। এন্ডপয়েন্ট-সিস্টেমের ইনকামিং নোটিফিকেশন ব্লকিং কনফিগারেশন রেসপন্স সরবরাহ করে না।

উইজেট এবং রিয়েলটাইম সেশন API#

POST /v1/widget/session একটি শীর্ষ-স্তরের variables অবজেক্ট গ্রহণ করে। এর পাবলিশেবল কী সংরক্ষিত এজেন্ট নির্বাচন করে। ওয়েবহুক-মোড কী এই মানগুলো কনফিগারেশন ওয়েবহুকে ফরোয়ার্ড করে এবং উপরে বর্ণিতভাবে রেসপন্স মার্জ করে। ব্রাউজার-সরবরাহকৃত উইজেট/রিয়েলটাইম variables ক্লায়েন্ট-নিয়ন্ত্রিত, উপরে বর্ণিত ভ্যালিডেশন এবং স্ট্রিং পরিষ্কারের পরে হুবহু web.incoming-এ ফরোয়ার্ড হয়, এবং কমপ্লিশন ওয়েবহুক ও কল ইতিহাসে প্রতিধ্বনিত হয়। এগুলোকে বিশ্বস্ত পরিচয় বা অনুমোদন ডেটা হিসেবে বিবেচনা করবেন না।

POST /v1/realtime/sessions, agent_id-এর পাশাপাশি (অথবা ইনলাইন config) variables গ্রহণ করে। এগুলো সেশন-তৈরি API ফিল্ড। রিয়েলটাইম WebSocket ব্রিজ ভেরিয়েবল অপশন ফরোয়ার্ড করে না; এটি সরাসরি সেশন-তৈরি API-তে দিন। উইজেট ক্লায়েন্টকে পোস্ট করা সেশন পেলোডে variables অন্তর্ভুক্ত করতে হবে; SDK ফরোয়ার্ডিং এই API পরিবর্তনের অংশ নয়। Builder মাইক এবং সিমুলেটেড টেস্ট কল ডিফল্ট ও অনুপস্থিত প্লেসহোল্ডার সমাধান করে, কিন্তু প্রতি-কলে ভেরিয়েবলের ইনপুট নেই।

কলের পরে ফেরত পাওয়া মান#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete, এবং web.complete চূড়ান্ত মার্জ করা variables এবং unresolved_variables অন্তর্ভুক্ত করে। data.history অন্তর্ভুক্ত করা লিগ্যাসি কমপ্লিশন পেলোডেও এগুলো থাকে:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

সম্পন্ন কলটিকে তার উৎস রেকর্ডের সঙ্গে যুক্ত করতে ভেরিয়েবল অবজেক্টে আপনার CRM বা টাস্ক আইডেন্টিফায়ার সংরক্ষণ করুন। এই ফিল্ডগুলো কল রেকর্ডের সঙ্গে সংরক্ষিত থাকে; শুধু এমন তথ্য পাঠান যা কল ইতিহাস ও ওয়েবহুকে সংরক্ষণ করা উপযুক্ত।

বিদ্যমান prompt সামঞ্জস্যতা#

রেন্ডারিং বিদ্যমান সংরক্ষিত-এজেন্ট এবং A/B ভ্যারিয়েন্ট prompt, ইনলাইন আউটবাউন্ড ও রিয়েলটাইম কনফিগারেশন, এবং কনফিগারেশন ওয়েবহুক থেকে ফেরত আসা prompt-গুলিতেও প্রযোজ্য। অজানা {{name}} প্লেসহোল্ডার ফাঁকা টেক্সটে পরিণত হয়, এমনকি কোনো variables সরবরাহ না করা হলেও। রোলআউটের আগে বিদ্যমান prompt পরীক্ষা করুন, যার মধ্যে বাহ্যিকভাবে সরবরাহ করা ইনলাইন/ওয়েবহুক prompt অন্তর্ভুক্ত, যেগুলোর তালিকা ThunderPhone তৈরি করতে পারে না। Builder মাইক এবং সিমুলেশন কলেও একই ডিফল্ট/ফাঁকা আচরণ প্রযোজ্য।