वॉइस सीक्वेंस में एप्लिकेशन डेटा का उपयोग करें

जब आपके एप्लिकेशन के पास ऐसा डेटा हो जिसकी कॉल को ज़रूरत है, जैसे ऑर्डर की स्थिति, कोई टीम या अपॉइंटमेंट की पुष्टि, तब voice.webhook का उपयोग करें। यह चरण वह डेटा success पर लौटाता है, और बाद का Branch चरण उसी के आधार पर पथ चुनता है।

प्रतिक्रिया परिभाषित करें

लौटाए जाने वाले डेटा के लिए config.output_schema को एक ऑब्जेक्ट स्कीमा पर सेट करें। इस चरण के दो आउटपुट हैं: success उस स्कीमा के अनुसार डेटा ले जाता है और failure तकनीकी समस्याओं को संभालता है। कॉन्फ़िगरेशन न देने पर आउटपुट एक खाली ऑब्जेक्ट होता है।

इनपुट में एक स्थिर HTTPS url और वैकल्पिक ऑब्जेक्ट data होता है। डेटा के रूप में शाब्दिक ऑब्जेक्ट, $literal या पूरे ऑब्जेक्ट वाला $expr दिया जा सकता है। डायनामिक URL, स्वयं लिखे गए हेडर और क्रेडेंशियल समर्थित नहीं हैं।

अनुरोध सत्यापित करें

Bird हर अनुरोध पर, निरंतरता अनुरोधों सहित, आपके वर्कस्पेस के कॉलबैक सीक्रेट से Standard Webhooks हेडर webhook-id, webhook-timestamp और webhook-signature के साथ हस्ताक्षर करता है। हस्ताक्षर में ID, टाइमस्टैम्प और सटीक बॉडी शामिल होते हैं। सीक्रेट बदलने के बाद के 24 घंटों के दौरान webhook-signature में हर सक्रिय सीक्रेट के लिए एक v1, प्रविष्टि होती है, इसलिए दोनों में से कोई भी सीक्रेट सत्यापन कर सकता है। कॉल को नए सीक्रेट से हस्ताक्षर शुरू करने में लगभग एक मिनट लग सकता है, इसलिए यह अवधि समाप्त होने तक पिछला सीक्रेट भी स्वीकार करते रहें। आपकी प्रतिक्रिया पर हस्ताक्षर नहीं होता: Bird आपके रिसीवर के TLS प्रमाणपत्र की जाँच करता है, और HTTPS कनेक्शन उसकी लौटाई गई सामग्री को प्रमाणित करता है।

पार्स करने से पहले, कच्ची बॉडी पर किसी Standard Webhooks लाइब्रेरी के verify कॉल से हेडर सत्यापित करें। SDK का webhooks.unwrap प्लेटफ़ॉर्म इवेंट पार्स करता है और इन अनुरोधों के लिए नहीं है। सबसे पहले Webhooks → Direct callbacks में सीक्रेट बदलें, क्योंकि शुरुआती सीक्रेट कभी दिखाया नहीं जाता। हस्ताक्षर यह दिखाता है कि अनुरोध पर ऐसे किसी पक्ष ने हस्ताक्षर किया है जिसके पास आपके वर्कस्पेस का सीक्रेट है। आपके SMS कॉलबैक रिसीवर के पास भी यही सीक्रेट होता है और वे भी हस्ताक्षर कर सकते हैं, इसलिए इसे केवल उन्हीं रिसीवर पर रखें जिन पर आप भरोसा करते हैं। वर्कस्पेस के सीक्वेंस संपादित कर सकने वाला कोई भी व्यक्ति URL और data चुनता है। Bird द्वारा किसी दूसरे रिसीवर के लिए हस्ताक्षरित अनुरोध को अस्वीकार करने के लिए जाँचें कि target_url आपका अपना URL है, और व्यावसायिक कार्रवाइयों की अनुमति अपने रिसीवर में तय करें। ग्राहक का प्राधिकरण कभी आगे नहीं भेजा जाता।

सीक्वेंस वेबहुक अनुरोध क्लाइंट प्रमाणपत्र प्रस्तुत नहीं करते, तब भी जब आपका वर्कस्पेस mTLS लागू करता है। रिसीवर को क्लाइंट प्रमाणपत्र के बिना कनेक्शन स्वीकार करने के लिए कॉन्फ़िगर करें और उसके बजाय हस्ताक्षरित अनुरोध को प्रमाणित करें।

हस्ताक्षरित webhook-timestamp, जो सेकंड में Unix टाइमस्टैम्प है, को सिंक्रनाइज़ की गई सर्वर घड़ी से मिलाएँ। पाँच मिनट से अधिक पुराने या भविष्य के अनुरोध अस्वीकार करें। कोई भी साइड इफ़ेक्ट करने से पहले webhook-id के आधार पर दोहराव हटाएँ। जहाँ संभव हो, ID और परिणाम को कार्रवाई के साथ एक ही परमाणु ऑपरेशन में सहेजें, और दोहराए गए अनुरोध पर सहेजा गया परिणाम लौटाएँ। हर निरंतरता की अपनी ID होती है। यदि अलग-अलग अनुरोधों को एक ही कार्रवाई दोहरानी नहीं चाहिए, तो अलग व्यावसायिक आइडेम्पोटेंसी कुंजी का उपयोग करें।

डेटा लौटाएँ

रिसीवर यह बंद प्रतिक्रिया संरचना लौटाता है:

{
  "schema_version": 1,
  "type": "outcome",
  "output": { "status": "confirmed", "message": "Your appointment is confirmed." }
}

output को कॉन्फ़िगर किए गए स्कीमा से मेल खाना चाहिए। प्रतिक्रिया डेटा लौटाती है, कोई पोर्ट, नोड ID या नए कमांड नहीं। निरंतरता मूल URL के कैनोनिकल ओरिजिन पर {"schema_version":1,"type":"continue","url":"https://example.com/voice/next"} होती है।

डेटा के आधार पर रूट करने के लिए success को logic.branch चरण से जोड़ें, जिसमें steps.decision.output.status == 'confirmed' जैसे केस हों। स्कीमा में फ़ील्ड को स्ट्रिंग enum के रूप में घोषित करें, ताकि रिसीवर केवल वही मान लौटा सके।

अनुरोध में रन/सत्र/कॉल की पहचान, स्वीकृत सीक्वेंस और नोड की पहचान, आपका भरा हुआ data और results शामिल होते हैं। व्यावसायिक इनपुट data में रखें। किसी सीधे निजी Gather का परिणाम results में एक बार दिख सकता है, और पूरी हो चुकी रिकॉर्डिंग में उपलब्ध होने पर एक ID होती है। ये अवलोकन अपने आप एक्सप्रेशन फ़ील्ड नहीं बनते।

रिसीवर का अनुरोध पढ़ें

ड्राफ़्ट टेस्ट रन इस रूप का अनुरोध भेजता है। नीचे दी गई ID और टाइमस्टैम्प काल्पनिक हैं। वास्तविक अनुरोध स्वीकृत रन और नोड की वर्तमान घटना का उपयोग करता है:

{
  "schema_version": 1,
  "method": "POST",
  "target_url": "https://example.com/decision",
  "run_id": "vsr_01k5yb7p000000000000000000",
  "sequence": {
    "id": "vsq_01k5yb7p000000000000000000",
    "version_id": null,
    "draft_revision": 1,
    "entry_node_id": "start",
    "mode": "test"
  },
  "session_id": "vcs_01k5yb7p000000000000000000",
  "call": { "id": "vcl_01k5yb7p000000000000000000", "orig": null, "dest": null },
  "node": { "id": "decision", "occurrence_id": "00000000-0000-4000-8000-000000000001" },
  "data": { "appointment_id": "appointment_123" },
  "results": []
}

प्रकाशित रन के लिए version_id चुने गए संस्करण की पहचान करता है और draft_revision null होता है। जिस कॉल में इनलाइन परिभाषा चली हो, उसके लिए id, version_id और draft_revision तीनों null होते हैं। mode का मान test या production हो सकता है। मूल और गंतव्य ऐसे कॉल-पक्ष ऑब्जेक्ट का उपयोग करते हैं जो null हो सकते हैं। इन पहचान फ़ील्ड पर भरोसा करने से पहले हस्ताक्षर सत्यापित करें।

results में Gather अवलोकन में type: "gather", node_id, UUID command_id, digits और reason होते हैं। रिकॉर्डिंग अवलोकन में type: "recording", UUID command_id, state और उपलब्ध होने पर recording_id होता है। निजी अंकों का उपयोग केवल उसी अनुरोध के लिए करें जिसके लिए वे हैं। वे सहेजे जाने वाले एक्सप्रेशन आउटपुट नहीं बनते। निरंतरता अनुरोधों में नोड की वही घटना बनी रहती है, और पहले भेजे जा चुके अवलोकन results से हटा दिए जाते हैं।

विफलताओं को संभालें

तकनीकी नमूना {"code":"webhook_unavailable"} या {"code":"webhook_invalid_response"} के साथ failure पोर्ट का उपयोग करता है। जुड़ा हुआ होने पर विफलता रिकवरी पथ पर जाती है; न जुड़ा होने पर रन विफल हो जाता है। न जुड़ा success रन को सामान्य रूप से समाप्त करता है। लाइव वेबहुक अनुरोधों की समय-सीमा तीन सेकंड है, और उन्हें अपने आप फिर से प्रयास नहीं किया जाता। प्रीव्यू कोई अनुरोध नहीं भेजता।

तीन सेकंड की समय-सीमा में साइनिंग सीक्रेट पढ़ने का समय भी शामिल है। failure को रिकवरी पथ से जोड़ें, ताकि रिसीवर उपलब्ध न होने या अमान्य प्रतिक्रिया लौटाने पर भी कॉल जारी रह सके। टाइमआउट हुआ अनुरोध रिसीवर पर पहले ही कोई प्रभाव डाल चुका हो सकता है।

data, कॉल की पहचान और Gather अंकों को निजी मानें। रिसीवर और सीक्रेट तक पहुँच सीमित करें, बॉडी या सीक्रेट लॉग न करें, और कॉलर का इनपुट केवल तब तक रखें जब तक आपके एप्लिकेशन को उसकी ज़रूरत हो। URL में निजी डेटा या क्रेडेंशियल न डालें, क्योंकि कॉल ट्रेस क्वेरी सहित पूरा URL सहेजता है। लिखे गए URL और डेटा तथा सत्यापित आउटपुट रन इतिहास में सहेजे जाते हैं। अस्थायी Gather अंक दर्ज किए गए चरण इनपुट में शामिल नहीं होते। केवल वही डेटा लौटाएँ जिसकी सीक्वेंस को ज़रूरत है।

लौटाया गया डेटा steps.decision.output पर पढ़ें और तकनीकी त्रुटियाँ steps.decision.error.code पर पढ़ें। यदि दोनों पथ मिलते हैं, तो रैपर का उपयोग करने से पहले उसे has(steps.decision.output) या has(steps.decision.error) से जाँचें। आपके रिसीवर से मिला HTTP 200 तब तक मान्य परिणाम नहीं माना जाता, जब तक उसकी बॉडी अनुबंध की जाँच में पास न हो जाए।