ThunderPhone v3 आता लाइव्ह आहे.स्वतःच सुरू करा—2¢/मिनिटपासून.घोषणा वाचा

Developer cookbook

प्रत्येक कॉलसाठी व्हेरिएबल्स आणि संदर्भ

एजंटमध्ये बदल न करता, प्रत्येक कॉलला prompt साठी नामांकित व्हेरिएबल्स किंवा मुक्त-स्वरूप संक्षिप्त माहिती म्हणून स्वतःचे तपशील द्या.

प्रत्येक कॉलमध्ये कॉलनुसार दोन प्रकारचे इनपुट असू शकतात. यांपैकी एक किंवा दोन्ही एकत्र वापरा:

  • variables: prompt मधील {{placeholders}} भरणारी नामांकित मूल्ये. कॉलरचे नाव, खाते क्रमांक किंवा अपॉइंटमेंटची वेळ यांसारख्या, prompt ज्या फील्डचा नावाने उल्लेख करतो त्यासाठी यांचा वापर करा.
  • context: prompt नंतर जोडला जाणारा मुक्त-स्वरूपातील मजकूर. या कॉलसाठीच्या कार्याचे वर्णन किंवा आधी गोळा केलेल्या नोंदी यांसारख्या, टेम्पलेटमध्ये न बसणाऱ्या संक्षिप्त माहितीसाठी याचा वापर करा.

खाली वर्णन केलेल्या कॉल सुरू करण्याच्या प्रत्येक पद्धतीमध्ये, हे दोन्ही जतन केलेल्या एजंटसह आणि इनलाइन कॉन्फिगरेशनसह कार्य करतात. यांपैकी कोणतेही जतन केलेला एजंट, त्याचा आवृत्ती इतिहास किंवा त्याच्या इतर सेटिंग्ज बदलत नाही.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}

चल

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

फोन कॉलसाठी ते फील्ड पाठवले असल्यास, व्हेरिएबल्स स्वीकारोक्ती prompt, आउटबाउंड व्हॉइसमेल संदेश आणि संमती घोषणेच्या मजकुरातही दिसू शकतात. एजंटकडे स्वतंत्र first_message फील्ड नाही: त्याच्या सुरुवातीच्या सूचना prompt मध्ये ठेवा. विद्यमान व्हॉइसमेल {agent_name} आणि {org_name} प्लेसहोल्डर कार्यरत राहतात.

मूल्ये आणि मर्यादा

मूल्ये स्ट्रिंग्ज, संख्या, बुलियन्स किंवा null असू शकतात; बुलियन्स true आणि false म्हणून रेंडर होतात. न्यूलाइन (\n), टॅब (\t), आणि कॅरेज रिटर्न (\r) वगळता Unicode कंट्रोल (Cc) वर्ण, शून्य-रुंदी नॉन-जॉइनर आणि जॉइनर (U+200C, U+200D, जे भारतीय आणि अरबी-लिपीतील भाषांमध्ये शब्दांची रचना करतात) वगळता फॉरमॅट (Cf) वर्ण, आणि सरोगेट (Cs) कोड पॉइंट्स काढले जातात; \r\n चे \n मध्ये सामान्यीकरण केले जाते. प्रत्येक मूल्य रेंडर केल्यावर 2,000 वर्णांपुरते मर्यादित असते. दिलेल्या स्ट्रिंग्ज स्टोरेजपूर्वी स्वच्छ केल्या जातात आणि छाटल्या जातात. मूळ ऑब्जेक्ट 32 KB च्या UTF-8 JSON मध्ये बसला पाहिजे; मोठ्या ऑब्जेक्ट्सना कॉल/सेशन विनंत्यांवर 400 मिळते, तर मोहिम आयातीमध्ये अवैध पंक्ती स्वतंत्रपणे नोंदवल्या जातात. अॅरे आणि नेस्टेड ऑब्जेक्ट्स मूल्ये म्हणून स्वीकारले जात नाहीत. न जुळणाऱ्या मेटाडेटा की (उदाहरणार्थ स्पेस असलेला CSV हेडर) राखून ठेवल्या जातात आणि परत पाठवल्या जातात, पण प्लेसहोल्डरद्वारे संदर्भित करता येत नाहीत.

संदर्भ

context ही कमाल 20,000 वर्णांची स्ट्रिंग आहे. ThunderPhone ती प्रॉम्प्टनंतर, प्रॉम्प्टमधील व्हेरिएबल्स भरल्यानंतर, सीमांकित ब्लॉक म्हणून जोडते:

<your prompt, with its variables filled in>
 
Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>

एजंट हे त्याच्या सूचनांसह वाचतो, म्हणून कॉलपूर्वी तुम्ही सहकाऱ्याला जसे ब्रीफ कराल तसे ते लिहा. संदर्भ हा टेम्पलेट नाही: त्यातील {{name}} जसे लिहिले आहे तसेच राहते. मजकुराला मूल्य आवश्यक असल्यास, पाठवण्यापूर्वी ते तुम्ही स्वतः भरा.

  • null, रिकामी स्ट्रिंग किंवा फक्त रिकामी जागा असल्यास कोणताही संदर्भ नसतो.
  • स्ट्रिंग नसलेले किंवा 20,000 वर्णांपेक्षा मोठे मूल्य कॉल आणि सत्र विनंत्यांमध्ये 400 सह नाकारले जाते; कॉन्फिगरेशन वेबहुकमधून ते अवैध variables प्रमाणे एक्सचेंज अयशस्वी करते (खाली पहा).
  • सुरुवातीची आणि शेवटची रिकामी जागा काढून टाकली जाते आणि व्हेरिएबल मूल्यांप्रमाणेच नियंत्रण व स्वरूप वर्ण काढले जातात.
  • संदर्भ हा कॉलच्या prompt चा भाग असतो, त्यामुळे तो कॉलच्या prompt आकारात मोजला जातो.

स्टेप्स एजंटवर, संदर्भ कॉलमधील प्रत्येक एजंटच्या प्रॉम्प्टनंतर येतो, प्रत्येक स्टेपच्या सूचनांनंतर नाही.

मूल्ये कुठून येतात

आउटबाउंड API

POST /v1/call वर variables आणि context पाठवा:

{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}

हे दोन्ही फोन नंबरच्या डीफॉल्ट आउटबाउंड एजंटसह किंवा इनलाइन config.prompt सह देखील कार्य करतात. इनलाइन कॉन्फिगसह, context हे config मध्येही असू शकते, जे कॉन्फिगरेशन webhook परत करते तेच फील्ड; तुम्ही दोन्ही पाठवल्यास, त्यांचा मजकूर समान असणे आवश्यक आहे. वेगवेगळ्या variables किंवा वेगळ्या context सह idempotency key पुन्हा वापरता येत नाही.

मोहिम CSV

फोन नसलेले CSV स्तंभ आधीच संपर्क चल म्हणून संग्रहित केलेले आहेत. प्रत्येक डायल आता त्यांचा आपोआप वापर करते. तुमच्या प्लेसहोल्डरशी जुळवण्यासाठी name, account_id, आणि appointment_slot यांसारखे हेडर वापरा. विद्यमान नाव मॅपिंग प्रथम आणि आडनावाचे स्तंभ एकत्र करून name या चलात समाविष्ट करू शकते. कॅम्पेन संपर्कांकडे प्रति-संपर्क संदर्भ नसतो.

डायनॅमिक कॉन्फिगरेशन वेबहुक

ब्लॉकिंग कॉन्फिगरेशन वेबहुक मार्गावर, तुमच्या संस्थेतील जतन केलेला एजंट आणि प्रति-कॉल मूल्ये परत करा. Full duplex एजंटसाठी, कॉल दुसऱ्या समर्थित भाषेत सुरू झाला तरी कॉल एजंटचा आवाज कायम ठेवतो: प्रत्येक भाषेसाठीचे आवाज मॅपिंग आणि मूळ आवाज स्विचिंग त्या कॉलला लागू होत नाही.

{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}

प्रतिसादातील variables विनंती-स्तरावरील variables अधिलिखित करतात, तर इतर विनंती keys तसेच राहतात. null प्रतिसाद मूल्य placeholder चे डीफॉल्ट निवडते. विलीन केलेला ऑब्जेक्ट 32 KB मध्येही बसला पाहिजे. जतन केलेल्या एजंटच्या प्रतिसादांमध्ये फक्त agent_id, variables, context, language आणि प्रति-कॉल timezone स्वीकारले जातात; तुम्हाला prompt किंवा इतर सेटिंग्ज बदलायच्या असल्यास inline configuration परत करा. जतन केलेल्या एजंटच्या webhook प्रतिसादांमध्ये फोन आणि widget दोन्ही कॉलवर एजंटचा तैनात केलेला A/B split वापरला जातो; variant निवडल्यानंतर variables रेंडर केले जातात. प्रतिसादाने Full duplex नसलेल्या एजंटसाठी language सेट केल्यास, त्या भाषेसाठी एजंटने आवाज सेट केला असल्यास कॉल त्या भाषेचा स्वतःचा आवाजही वापरतो. prompt असलेला प्रतिसाद नेहमी inline configuration वापरतो: त्या प्रतिसादातील कोणताही agent_id दुर्लक्षित केला जातो, ज्यामध्ये null किंवा पूर्णांक नसलेला metadata यांचाही समावेश आहे. inline prompt ला तरीही नेहमीची पडताळणी उत्तीर्ण करावी लागते. Inline webhook प्रतिसादांमध्ये variables आणि context देखील समाविष्ट असू शकतात. स्ट्रिंग नसलेला किंवा खूप लांब असलेला context एक्सचेंज अयशस्वी करतो: फोन कॉल नाकारला जातो आणि widget session विनंती 400 सह अयशस्वी होते. जतन केलेल्या एजंटच्या webhook प्रतिसादांमध्ये फोन आणि widget दोन्ही कॉलवर एजंटचा तैनात केलेला A/B split वापरला जातो; variant निवडल्यानंतर variables रेंडर केले जातात. येणाऱ्या फोन कॉलवर, नियुक्त inbound एजंट नसलेला नंबर वापरा आणि त्याचा फोन-नंबर किंवा organization webhook कॉन्फिगर करा; widget keys मध्ये mode="webhook" वापरले जाते. Endpoint-system येणाऱ्या सूचना blocking configuration प्रतिसाद पुरवत नाहीत.

एजंट कॉल सेटअप webhook

एखादा नंबर त्याच्या एजंटला नियुक्त ठेवण्यासाठी आणि फक्त कॉलची मूल्ये भरण्यासाठी, एजंटला कॉल सेटअप वेबहुक द्या. एजंट एखाद्या नंबरवर प्रत्येक इनबाउंड कॉलला उत्तर देण्यापूर्वी, वेबहुकला कॉल तसेच एजंटचा आयडी, नाव आणि आवृत्ती मिळते आणि agent_id ची गरज नसताना, वरीलप्रमाणेच variables, context, language आणि प्रत्येक कॉलचा timezone यांसह प्रतिसाद देते. ज्या एजंटच्या सेटिंग्जमध्ये डीफॉल्ट नसलेला प्लेसहोल्डर आहे, त्याला फोन नंबरवर उत्तर देण्यासाठी हा वेबहुक आवश्यक आहे: वेबहुक अयशस्वी झाल्यास कॉल सुरू होत नाही. {{name|there}} सारखे डीफॉल्ट असलेले प्लेसहोल्डर एजंटला त्याशिवाय उत्तर देऊ देतात.

SIP हेडर्स

SIP द्वारे एजंटपर्यंत पोहोचणारे कॉल (एक SIP पत्ता, किंवा मॅन्युअल SIP कनेक्शनवरील क्रमांक) X-* आणि User-to-User हेडर्समध्ये संदर्भ वाहून नेऊ शकतात. प्रत्येक हेडर {{sip_x_amzn_connectcontactid}} किंवा {{sip_uui}} सारखा sip_ व्हेरिएबल बनतो, आणि त्याची प्राधान्यता सर्वात कमी असते: API किंवा webhook मधून आलेले त्याच नावाचे मूल्य प्राधान्याने वापरले जाते. पहा SIP हेडर्समध्ये कॉल संदर्भ पास करा. हेडर मूल्ये प्रेषक सेट करतो, त्यामुळे ब्राउझरद्वारे पुरवलेल्या कोणत्याही मूल्याप्रमाणे त्यांना अविश्वसनीय माना.

विजेट सेशन API

POST /v1/widget/session उच्च-स्तरीय variables आणि language स्वीकारतो. त्याची पब्लिशेबल की जतन केलेला एजंट निवडते. वेबहूक-मोड की ही मूल्ये कॉन्फिगरेशन वेबहूककडे पाठवतात आणि वरील वर्णनानुसार प्रतिसाद विलीन करतात. ब्राउझरद्वारे पुरवलेले विजेट variables क्लायंट-नियंत्रित असतात, वरील वर्णन केलेल्या प्रमाणीकरण आणि स्ट्रिंग साफसफाईनंतर web.incoming मध्ये जसेच्या तसे पाठवले जातात आणि पूर्णता वेबहूक व कॉल इतिहासात प्रतिध्वनित केले जातात. त्यांना विश्वसनीय ओळख किंवा अधिकृतता डेटा म्हणून वापरू नका.

विजेटचे स्वतःचे ब्राउझर context फील्ड वेगळे आहे: ते भेट देणारी व्यक्ती ज्या पेजवर आहे त्यावरील मजकूर वाहून नेते, ज्याला एजंट वेबसाइट सामग्री म्हणून हाताळतो (वेब विजेट एम्बेड करा पहा). विजेट कॉलचा प्रति-कॉल संदर्भ वर सांगितल्याप्रमाणे वेबहुक-मोड कीच्या कॉन्फिगरेशन वेबहुकमधून येतो. कॉलमध्ये दोन्ही असल्यास, प्रति-कॉल संदर्भ आधी येतो आणि त्यानंतर पेजची सामग्री येते.

रिअलटाइम सेशन API

POST /v1/realtime/sessions हे टॉप-लेव्हल variables, context आणि language स्वीकारते, तसेच agent_id किंवा इनलाइन config स्वीकारते:

{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}

context फक्त टॉप लेव्हलवर जाते; इनलाइन config ते अज्ञात फील्ड म्हणून नाकारते.

रिअलटाइम WebSocket

जतन केलेल्या एजंटसह, जतन केलेल्या एजंटचा डिप्लॉय केलेला prompt हाच त्याचा prompt राहतो. session.instructions कॉलचा संदर्भ बनतो, session.prompt.variables (किंवा session.config.variables) त्याचे व्हेरिएबल्स बनतात आणि session.language प्रति-कॉल भाषा बनते. पहिल्या session.update मध्ये session.prompt.id वापरून एजंट निवडा; हे अपडेट प्राप्त होताच सत्र सुरू होते:

{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}

कनेक्शन URL वरील ?agent_id=12 सॉकेट कनेक्ट होताच, कोणत्याही session.update च्या आधी एजंट सुरू करते, त्यामुळे त्यात प्रति-कॉल इनपुट नसते. पहिल्या session.update ची प्रतीक्षा करण्यासाठी &wait_for_session_update=1 जोडा आणि त्यातील सूचना व व्हेरिएबल्स वापरा.

इनलाइन सत्रात (जतन केलेला एजंट नसताना), पूर्वीप्रमाणे session.instructions हाच prompt असतो. बिल्डर माइक आणि सिम्युलेटेड चाचणी कॉल डीफॉल्ट व गहाळ प्लेसहोल्डरचे निराकरण करतात, परंतु त्यांच्याकडे प्रति-कॉल व्हेरिएबल्स किंवा संदर्भ इनपुट नसते.

कॉलनंतर

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"]
}

कॉलचा prompt_snapshot (GET /v1/calls/{call_id}) एजंटचा prompt दाखवतो, ज्यामध्ये त्याचे व्हेरिएबल्स भरलेले असतात आणि कॉन्टेक्स्ट ब्लॉक जोडलेला असतो.

पूर्ण झालेला कॉल त्याच्या स्रोत रेकॉर्डशी जोडण्यासाठी तुमचा CRM किंवा टास्क आयडेंटिफायर व्हेरिएबल्स ऑब्जेक्टमध्ये साठवा. व्हेरिएबल्स आणि कॉन्टेक्स्ट कॉल रेकॉर्डसह जतन केले जातात; कॉल इतिहास आणि वेबहुक्समध्ये जतन करणे योग्य असेल अशीच माहिती पाठवा.

व्हॅलिडेशन संचांमध्ये, रीप्ले रनमध्ये आणि तपासांमध्ये कॉलचे रीप्ले, चाचणीतील prompt सोबत त्या कॉलचे व्हेरिएबल्स आणि कॉन्टेक्स्ट वापरतात, त्यामुळे रीप्ले त्या कॉलवरील एजंटला काय सांगितले गेले असते याची चाचणी करतो.

विद्यमान prompt सुसंगतता

रेंडरिंग विद्यमान सेव्ह केलेल्या एजंट आणि A/B व्हेरिएंट prompt, इनलाइन आउटबाउंड आणि रिअलटाइम कॉन्फिगरेशन, तसेच कॉन्फिगरेशन वेबहुकद्वारे परत केलेल्या prompt वरही लागू होते. अज्ञात {{name}} प्लेसहोल्डर रिक्त मजकूर बनतात, जरी कोणतेही variables दिलेले नसले तरीही. रोलआउटपूर्वी विद्यमान prompt तपासा, ज्यामध्ये ThunderPhone सूचीबद्ध करू शकत नसलेल्या बाहेरून पुरवलेल्या इनलाइन/वेबहुक prompt चा समावेश आहे. बिल्डर मायक्रोफोन आणि सिम्युलेशन कॉलवरही तेच डीफॉल्ट/रिक्त वर्तन लागू होते.