चैनल इनबाउंड API

चैनल प्राप्ति पथ एक ही प्रवाह का अनुसरण करते हैं:

प्लेटफ़ॉर्म इवेंट -> इनबाउंड तथ्य/संदर्भ -> एजेंट उत्तर -> संदेश डिलीवरी

इनबाउंड इवेंट सामान्यीकरण, फ़ॉर्मैटिंग, रूट्स और ऑर्केस्ट्रेशन के लिए openclaw/plugin-sdk/channel-inbound का उपयोग करें। नेटिव प्रेषण, रसीद, टिकाऊ डिलीवरी और लाइव पूर्वावलोकन व्यवहार के लिए openclaw/plugin-sdk/channel-outbound का उपयोग करें।

मुख्य सहायक

import {  buildChannelInboundEventContext,  runChannelInboundEvent,  dispatchChannelInboundReply,} from "openclaw/plugin-sdk/channel-inbound";

• buildChannelInboundEventContext(...): सामान्यीकृत चैनल तथ्यों को प्रॉम्प्ट/सत्र संदर्भ में प्रक्षेपित करता है। चैनल-स्वामित्व वाला प्रेषक/चैट मेटाडेटा channelContext के माध्यम से पास करें, जिसे Plugin हुक ctx.channelContext के रूप में देखते हैं। चैनल-विशिष्ट फ़ील्ड के लिए इस उपपथ से PluginHookChannelSenderContext या PluginHookChannelChatContext को विस्तारित करें।
• runChannelInboundEvent(...): एक इनबाउंड प्लेटफ़ॉर्म इवेंट के लिए अंतर्ग्रहण, वर्गीकरण, प्रीफ़्लाइट, समाधान, रिकॉर्डिंग, प्रेषण और अंतिमकरण चलाता है।
• dispatchChannelInboundReply(...): डिलीवरी अडैप्टर के साथ पहले से संयोजित इनबाउंड उत्तर को रिकॉर्ड और प्रेषित करता है।

केवल-मीडिया इनबाउंड इवेंट के लिए, संदेश का मुख्य भाग और कमांड टेक्स्ट खाली रखें तथा प्रत्येक नेटिव अटैचमेंट के लिए एक ChannelInboundMediaInput तथ्य पास करें। जब परिवेशी इतिहास पंक्ति या किसी अन्य केवल-टेक्स्ट वाहक में उन तथ्यों का वर्णन करना आवश्यक हो, तो formatMediaPlaceholderText(media) का उपयोग करें। यह प्रत्येक तथ्य को kind, MIME प्रकार, फिर पथ या URL एक्सटेंशन से वर्गीकृत करता है; डाउनलोड न किए गए नेटिव अटैचमेंट को भी प्रत्येक के लिए एक केवल-प्रकार तथ्य देना चाहिए। प्राथमिक इनबाउंड मुख्य भाग को संश्लेषित करने के लिए फ़ॉर्मैटर का उपयोग न करें।

Plugin-स्वामित्व वाले अटैचमेंट रिकॉर्ड को toInboundMediaFacts(...) से सामान्यीकृत करें, फिर परिणामी क्रमबद्ध ऐरे को संदर्भ के media फ़ील्ड के माध्यम से पास करें:

const media = toInboundMediaFacts([  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },]); const ctx = finalizeInboundContext({ Body: caption, media });

ऐरे की स्थिति अटैचमेंट की पहचान है। प्रत्येक तथ्य के transcribed, messageId और workspaceDir पुराने समानांतर इंडेक्स/वर्कस्पेस फ़ील्ड का स्थान लेते हैं। MediaPath, MediaPaths, MediaUrl, MediaUrls, MediaType, MediaTypes, MediaTranscribedIndexes, MediaWorkspaceDir और MediaStaged संदर्भ फ़ील्ड, साथ ही buildChannelInboundMediaPayload(...), केवल बहिष्कृत संगतता के रूप में उपलब्ध रहते हैं। नए Plugin को इन्हें बनाना या पढ़ना नहीं चाहिए।

बंडल किए गए/नेटिव चैनल जिन्हें पहले से इंजेक्ट किया गया Plugin रनटाइम ऑब्जेक्ट मिलता है, इस उपपथ को सीधे आयात करने के बजाय runtime.channel.inbound.* के अंतर्गत उन्हीं सहायकों को कॉल कर सकते हैं:

await runtime.channel.inbound.run({  channel: "demo",  accountId,  raw: platformEvent,  adapter: {    ingest: normalizePlatformEvent,    resolveTurn: resolveInboundReply,  },});

उन संगतता डिस्पैचर के लिए dispatchChannelInboundReply(...) इनपुट संयोजित करें जो प्लेटफ़ॉर्म डिलीवरी को डिलीवरी अडैप्टर में रखते हैं। नए प्रेषण पथों को इसके बजाय channel-outbound के संदेश अडैप्टर और टिकाऊ संदेश सहायकों का उपयोग करना चाहिए।

डिलीवरी निपटान अनुबंध

ChannelInboundTurnPlan.delivery प्रत्येक तार्किक उत्तर पेलोड के नेटिव प्रेषण का स्वामी है। कोर आउटबाउंड हुक क्रम और, जब अडैप्टर विकल्प चुनता है, टर्मिनल message_sent अवलोकन का स्वामी है। इन उत्तरदायित्वों को अलग रखें ताकि एक पेलोड डुप्लिकेट टर्मिनल इवेंट उत्पन्न न कर सके।

डिलीवरी परिणाम फ़ील्ड के ये अर्थ हैं:

जब कोर को इस अडैप्टर के गैर-टिकाऊ प्रेषण के लिए प्रामाणिक Plugin और आंतरिक message_sent इवेंट उत्सर्जित करने चाहिए, तब डिलीवरी अडैप्टर के observeMessageSent विकल्प को true पर सेट करें। इस विकल्प को deliver से वापस न करें और Plugin में भी उन इवेंट को उत्सर्जित न करें। टिकाऊ प्रेषण पहले से साझा आउटबाउंड स्वामी के माध्यम से उत्सर्जित होते हैं और डुप्लिकेट नहीं किए जाते।

प्रत्येक तार्किक पेलोड के लिए एक परिणाम लौटाएँ। finalization दूसरा प्रेषण नहीं है और इसे reply_payload_sending या message_sending को दोबारा नहीं चलाना चाहिए। जैसे ही deliver लौटता है, कोर अंतिमकरण प्रॉमिस की अस्वीकृति का अवलोकन करता है ताकि वह अनहैंडल्ड न हो सके; उत्तर प्रेषण का निपटान होने के बाद भी कोर मूल प्रॉमिस की प्रतीक्षा करता है। इसके बाद यह अंतिमकृत सामग्री और प्रदाता आईडी के साथ प्रत्येक पेलोड पर अधिकतम एक टर्मिनल अवलोकन उत्सर्जित करता है। onDelivered, जब मौजूद हो, उस अवलोकन के बाद निपटाया गया परिणाम प्राप्त करता है।

नेटिव डिलीवरी विफल होने पर deliver या finalization को अस्वीकार करें। यदि कोई प्रदाता प्रेषण करने का प्रयास नहीं किया गया, तो openclaw/plugin-sdk/error-runtime से PlatformMessageNotDispatchedError थ्रो करें; कोर झूठे message_sent इवेंट को दबा देता है। यदि किसी बाद की कार्रवाई के विफल होने से पहले नेटिव प्रेषण दृश्यमान हो गया था, तो त्रुटि पर दृश्यमान उपसमुच्चय बनाए रखें:

import { createChannelPartialDeliveryError } from "openclaw/plugin-sdk/channel-inbound"; throw createChannelPartialDeliveryError(cause, {  visibleReplySent: true,  content: finalizedVisibleText,  receipt,});

कोर उस प्रदाता-दृश्यमान सामग्री और पहचान के साथ विफल टर्मिनल अवलोकन उत्सर्जित करता है, फिर डिलीवरी को विफल ही रखता है ताकि कॉलर आंशिक सफलता को त्रुटिरहित प्रेषण न समझें। किसी पूर्वावलोकन, ड्राफ़्ट, अटैचमेंट या अंतिम संदेश के दृश्यमान होने के बाद visibleReplySent: false की रिपोर्ट न करें।

जब reply_payload_sending या message_sending पंजीकृत हो, तब प्रदाता को दृश्यमान कुछ भी बनाने से पहले उन हुक का निपटान होना आवश्यक है, क्योंकि दोनों में से कोई भी हुक तार्किक पेलोड को फिर से लिख या रद्द कर सकता है। जल्दबाज़ी में बनाया गया नेटिव पूर्वावलोकन पुनर्लेखन-पूर्व सामग्री को उजागर कर देगा या रद्द किया गया ड्राफ़्ट पीछे छोड़ देगा। स्वीकृत पेलोड के deliver तक पहुँचने तक पूर्वावलोकन सामग्री को बफ़र करें; जो संगतता डिस्पैचर पूर्वावलोकन पहले शुरू करते हैं, उन्हें किसी भी हुक के पंजीकृत होने पर उस जल्दबाज़ी वाले पूर्वावलोकन को दबाना होगा। नए पूर्वावलोकन पथों के लिए चैनल आउटबाउंड API के अंतिमकरण योग्य लाइव-पूर्वावलोकन सहायकों का उपयोग करें।

माइग्रेशन

runtime.channel.turn.* रनटाइम उपनाम हटा दिए गए। उपयोग करें:

• runtime.channel.inbound.run(...) कच्चे इनबाउंड इवेंट के लिए।
• runtime.channel.inbound.dispatchReply(...) संयोजित उत्तर संदर्भों के लिए।
• runtime.channel.inbound.buildContext(...) इनबाउंड संदर्भ पेलोड के लिए।
• runtime.channel.inbound.runPreparedReply(...), बहिष्कृत, केवल उन चैनल-स्वामित्व वाले तैयार प्रेषण पथों के लिए जो पहले से अपना प्रेषण क्लोज़र संयोजित करते हैं।

नए Plugin कोड में turn-नामित चैनल API प्रस्तुत नहीं होने चाहिए। मॉडल या एजेंट टर्न शब्दावली को एजेंट/प्रदाता कोड के भीतर रखें; चैनल Plugin इनबाउंड, संदेश, डिलीवरी और उत्तर शब्दों का उपयोग करते हैं।