Developer cookbook

प्रति-कॉल वेरिएबल्स

डिप्लॉय किए गए प्रॉम्प्ट, टूल्स या सेटिंग्स बदले बिना हर कॉल के लिए सेव किए गए एजेंट को पर्सनलाइज़ करें।

अपने सहेजे गए एजेंट के प्रॉम्प्ट में प्लेसहोल्डर डालें, फिर कॉल शुरू करते समय 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|Friend}}, name अनुपस्थित होने या null होने पर Friend का उपयोग करता है; खाली स्ट्रिंग स्पष्ट रूप से दी गई वैल्यू होती है। डिफ़ॉल्ट के बिना अनुपस्थित वैल्यू खाली स्ट्रिंग बन जाती हैं और उनके नाम unresolved_variables में दिखाई देते हैं। डबल ब्रेसेस के बीच का टेक्स्ट, जो मान्य प्लेसहोल्डर नहीं है, हटा दिया जाता है। प्रत्येक दी गई वैल्यू के भीतर का डबल-ब्रेस्ड टेक्स्ट स्वतंत्र रूप से हटा दिया जाता है; कोई वैल्यू आसपास के प्रॉम्प्ट टेक्स्ट या किसी अन्य वैल्यू को हटा नहीं सकती। बेमेल डबल-ब्रेस डिलिमिटर भी हटा दिए जाते हैं। प्रॉम्प्ट में JSON उदाहरणों को {{ का उपयोग नहीं करना चाहिए। वैल्यू सादा टेक्स्ट होती हैं, इन्हें कभी कोड के रूप में मूल्यांकित नहीं किया जाता या टेम्पलेट के रूप में रिकर्सिव रूप से विस्तारित नहीं किया जाता।

वेरिएबल स्वीकारोक्ति प्रॉम्प्ट, आउटबाउंड वॉइसमेल मैसेज और फ़ोन कॉल के लिए वह फ़ील्ड भेजे जाने पर सहमति घोषणा टेक्स्ट में भी दिखाई दे सकते हैं। एजेंट के पास अलग first_message फ़ील्ड नहीं है: उसके शुरुआती निर्देश प्रॉम्प्ट में रखें। मौजूदा वॉइसमेल {agent_name} और {org_name} प्लेसहोल्डर काम करते रहते हैं।

वैल्यू स्ट्रिंग, नंबर, बूलियन या null हो सकती हैं; बूलियन true और false के रूप में रेंडर होते हैं। न्यूलाइन (\n), टैब (\t), और कैरिज रिटर्न (\r) को छोड़कर यूनिकोड कंट्रोल (Cc) कैरेक्टर, सभी फ़ॉर्मैट (Cf) कैरेक्टर और सरोगेट (Cs) कोड पॉइंट हटा दिए जाते हैं; \r\n को \n में नॉर्मलाइज़ किया जाता है। रेंडर होने पर प्रत्येक वैल्यू 2,000 कैरेक्टर तक सीमित होती है। दी गई स्ट्रिंग को स्टोरेज से पहले भी साफ़ किया जाता है और ट्रंकेट किया जाता है। मूल ऑब्जेक्ट 32 KB of 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 के साथ भी काम करता है। अलग variables के साथ idempotency key का दोबारा उपयोग नहीं किया जा सकता।

कैंपेन CSV#

गैर-फ़ोन CSV कॉलम पहले से कॉन्टैक्ट variables के रूप में स्टोर होते हैं। हर डायल अब उनका अपने-आप उपयोग करता है। अपने placeholders से मिलान करने के लिए name, account_id, और appointment_slot जैसे हेडर का उपयोग करें। मौजूदा नाम मैपिंग पहले और अंतिम नाम के कॉलम को name variable में जोड़ सकती है।

डायनामिक कॉन्फ़िगरेशन webhook#

ब्लॉकिंग कॉन्फ़िगरेशन webhook पथ पर, अपने संगठन में एक सेव किया गया एजेंट और प्रत्येक कॉल के मान लौटाएँ:

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

रिस्पॉन्स की keys रिक्वेस्ट-लेवल variables को ओवरराइट करती हैं, जबकि अन्य रिक्वेस्ट keys बनी रहती हैं। null का रिस्पॉन्स मान placeholder का डिफ़ॉल्ट चुनता है। मर्ज किया गया ऑब्जेक्ट भी 32 KB में होना चाहिए। सेव किए गए एजेंट के रिस्पॉन्स केवल agent_id और variables स्वीकार करते हैं; जब आपको prompt या सेटिंग्स बदलनी हों, तो इनलाइन कॉन्फ़िगरेशन लौटाएँ। prompt वाला रिस्पॉन्स हमेशा इनलाइन कॉन्फ़िगरेशन का उपयोग करता है: उस रिस्पॉन्स में कोई भी agent_id अनदेखा किया जाता है, जिसमें null या non-integer मेटाडेटा भी शामिल है। इनलाइन prompt को फिर भी सामान्य वेलिडेशन पास करना होगा। इनलाइन webhook रिस्पॉन्स में variables भी शामिल हो सकते हैं। सेव किए गए एजेंट के webhook रिस्पॉन्स फ़ोन और widget, दोनों कॉल पर एजेंट के डिप्लॉय किए गए A/B split का उपयोग करते हैं; वेरिएंट चुने जाने के बाद variables रेंडर होते हैं। इनबाउंड फ़ोन कॉल पर, ऐसा नंबर उपयोग करें जिसे कोई इनबाउंड एजेंट असाइन न हो और उसका फ़ोन-नंबर या संगठन webhook कॉन्फ़िगर करें; widget keys mode="webhook" का उपयोग करती हैं। endpoint-system की इनकमिंग सूचनाएँ ब्लॉकिंग कॉन्फ़िगरेशन रिस्पॉन्स उपलब्ध नहीं करातीं।

Widget और Realtime session APIs#

POST /v1/widget/session टॉप-लेवल variables ऑब्जेक्ट स्वीकार करता है। इसकी publishable key सेव किए गए एजेंट को चुनती है। webhook-mode keys इन मानों को कॉन्फ़िगरेशन webhook पर फ़ॉरवर्ड करती हैं और ऊपर बताए अनुसार रिस्पॉन्स को मर्ज करती हैं। ब्राउज़र से दिए गए widget/realtime variables क्लाइंट-नियंत्रित होते हैं, ऊपर बताए गए वेलिडेशन और स्ट्रिंग क्लीनअप के बाद web.incoming में बिना बदलाव के फ़ॉरवर्ड किए जाते हैं, और completion webhooks तथा कॉल हिस्ट्री में दोहराए जाते हैं। इन्हें विश्वसनीय पहचान या ऑथराइज़ेशन डेटा न मानें।

POST /v1/realtime/sessions agent_id (या इनलाइन config) के साथ variables स्वीकार करता है। ये session-create API फ़ील्ड हैं। Realtime WebSocket bridge variables विकल्प को फ़ॉरवर्ड नहीं करता; इसे सीधे session-create API में दें। Widget क्लाइंट को पोस्ट किए गए session payload में variables शामिल करने होंगे; SDK फ़ॉरवर्डिंग इस API बदलाव का हिस्सा नहीं है। Builder mic और सिम्युलेटेड टेस्ट कॉल डिफ़ॉल्ट और अनुपलब्ध placeholders को रिज़ॉल्व करती हैं, लेकिन इनमें प्रत्येक कॉल के लिए variables इनपुट नहीं होता।

कॉल के बाद लौटाए गए मान#

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete, और web.complete में अंतिम मर्ज किए गए variables और unresolved_variables शामिल होते हैं। वे legacy completion payloads जिनमें data.history शामिल होता है, उनमें भी ये शामिल होते हैं:

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

पूर्ण हुई कॉल को उसके स्रोत रिकॉर्ड से जोड़ने के लिए अपने CRM या task identifier को variables ऑब्जेक्ट में स्टोर करें। ये फ़ील्ड कॉल रिकॉर्ड के साथ रखे जाते हैं; केवल वही जानकारी भेजें जो कॉल हिस्ट्री और webhooks में रखने के लिए उपयुक्त हो।

मौजूदा प्रॉम्प्ट संगतता#

रेंडरिंग मौजूदा सेव्ड-एजेंट और A/B वैरिएंट प्रॉम्प्ट्स, इनलाइन आउटबाउंड और रियलटाइम कॉन्फ़िगरेशन, और कॉन्फ़िगरेशन वेबहुक्स से लौटाए गए प्रॉम्प्ट्स पर भी लागू होती है। अज्ञात {{name}} प्लेसहोल्डर खाली टेक्स्ट बन जाते हैं, भले ही कोई variables न दिए गए हों। रोलआउट से पहले मौजूदा प्रॉम्प्ट्स की जाँच करें, जिनमें बाहरी रूप से दिए गए इनलाइन/वेबहुक प्रॉम्प्ट्स भी शामिल हैं, जिन्हें ThunderPhone इन्वेंटरी में शामिल नहीं कर सकता। Builder माइक और सिमुलेशन कॉल्स पर वही डिफ़ॉल्ट/खाली व्यवहार लागू होता है।