API voor inkomende kanaalberichten

Ontvangstpaden van kanalen volgen één flow:

platformgebeurtenis -> inkomende feiten/context -> agentantwoord -> berichtbezorging

Gebruik openclaw/plugin-sdk/channel-inbound voor normalisatie van inkomende gebeurtenissen, opmaak, roots en orkestratie. Gebruik openclaw/plugin-sdk/channel-outbound voor systeemeigen verzending, ontvangstbewijs, duurzame bezorging en livevoorbeeldgedrag.

Kernhelpers

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

• buildChannelInboundEventContext(...): projecteert genormaliseerde kanaalfeiten in de prompt-/sessiecontext. Geef door het kanaal beheerde metadata van afzender/chat door via channelContext, die Plugin-hooks zien als ctx.channelContext. Breid PluginHookChannelSenderContext of PluginHookChannelChatContext vanuit dit subpad uit met kanaalspecifieke velden.
• runChannelInboundEvent(...): voert opname, classificatie, preflight, oplossing, registratie, verzending en afronding uit voor één inkomende platformgebeurtenis.
• dispatchChannelInboundReply(...): registreert en verzendt een reeds samengesteld inkomend antwoord met een bezorgingsadapter.

Houd voor inkomende gebeurtenissen die alleen media bevatten de berichttekst en opdrachttekst leeg en geef per systeemeigen bijlage één ChannelInboundMediaInput-feit door. Wanneer een omgevingsgebonden geschiedenisregel of een andere uitsluitend tekstuele drager die feiten moet beschrijven, gebruik je formatMediaPlaceholderText(media). Deze classificeert elk feit op basis van kind, het MIME- type en vervolgens de extensie van het pad of de URL; nog niet gedownloade systeemeigen bijlagen moeten elk nog steeds één feit met alleen een type opleveren. Gebruik de formatter niet om de primaire inkomende berichttekst te genereren.

Normaliseer door de Plugin beheerde bijlagerecords met toInboundMediaFacts(...) en geef daarna de resulterende geordende array door via het veld media van de context:

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

De arraypositie is de identiteit van de bijlage. transcribed, messageId en workspaceDir per feit vervangen de verouderde parallelle index-/werkruimtevelden. De contextvelden MediaPath, MediaPaths, MediaUrl, MediaUrls, MediaType, MediaTypes, MediaTranscribedIndexes, MediaWorkspaceDir en MediaStaged, plus buildChannelInboundMediaPayload(...), blijven alleen beschikbaar als verouderde compatibiliteitsvoorziening. Nieuwe plugins mogen ze niet aanmaken of uitlezen.

Gebundelde/systeemeigen kanalen die het geïnjecteerde Plugin-runtimeobject al ontvangen, kunnen dezelfde helpers aanroepen onder runtime.channel.inbound.* in plaats van dit subpad rechtstreeks te importeren:

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

Stel invoer voor dispatchChannelInboundReply(...) samen voor compatibiliteitsdispatchers die platformbezorging in de bezorgingsadapter houden. Nieuwe verzendpaden moeten in plaats daarvan berichtadapters en duurzame berichthelpers uit channel-outbound gebruiken.

Contract voor afhandeling van bezorging

ChannelInboundTurnPlan.delivery beheert de systeemeigen verzending voor elke logische antwoordpayload. Core beheert de volgorde van uitgaande hooks en, wanneer de adapter zich hiervoor aanmeldt, de uiteindelijke observatie van message_sent. Houd deze verantwoordelijkheden gescheiden, zodat één payload geen dubbele eindgebeurtenissen kan produceren.

De velden van het bezorgingsresultaat hebben de volgende betekenis:

Stel de optie observeMessageSent van de bezorgingsadapter in op true wanneer core de canonieke Plugin- en interne message_sent-gebeurtenissen moet genereren voor de niet-duurzame verzendingen van deze adapter. Retourneer deze optie niet vanuit deliver en genereer die gebeurtenissen ook niet in de Plugin. Duurzame verzendingen worden al gegenereerd via de gedeelde eigenaar van uitgaande berichten en worden niet gedupliceerd.

Retourneer één resultaat per logische payload. finalization is geen tweede verzending en mag reply_payload_sending of message_sending niet opnieuw uitvoeren. Zodra deliver retourneert, observeert core de afwijzing van de afrondingspromise, zodat deze niet onafgehandeld kan blijven; core wacht nog steeds op de oorspronkelijke promise nadat de verzending van het antwoord is afgehandeld. Vervolgens genereert core maximaal één uiteindelijke observatie per payload met de afgeronde inhoud en provider-id. onDelivered, indien aanwezig, ontvangt het afgehandelde resultaat na die observatie.

Wijs deliver of finalization af wanneer systeemeigen bezorging mislukt. Als geen providerverzending is geprobeerd, werp je PlatformMessageNotDispatchedError vanuit openclaw/plugin-sdk/error-runtime; core onderdrukt dan een onterechte message_sent- gebeurtenis. Als een systeemeigen verzending zichtbaar werd voordat een latere bewerking mislukte, behoud je de zichtbare subset in de fout:

 throw createChannelPartialDeliveryError(cause, {  visibleReplySent: true,  content: finalizedVisibleText,  receipt,});

Core genereert een mislukte uiteindelijke observatie met die voor de provider zichtbare inhoud en identiteit en houdt de bezorging vervolgens op mislukt, zodat aanroepers gedeeltelijk succes niet aanzien voor een foutloze verzending. Rapporteer visibleReplySent: false niet nadat een voorbeeld, concept, bijlage of definitief bericht zichtbaar is geworden.

Wanneer reply_payload_sending of message_sending is geregistreerd, moeten die hooks zijn afgehandeld voordat iets voor de provider zichtbaars wordt aangemaakt, omdat elke hook de logische payload kan herschrijven of annuleren. Een voortijdig systeemeigen voorbeeld zou inhoud van vóór de herschrijving lekken of een geannuleerd concept achterlaten. Buffer voorbeeldinhoud totdat de geaccepteerde payload deliver bereikt; compatibiliteitsdispatchers die voorbeelden eerder starten, moeten dat voortijdige voorbeeld onderdrukken zolang een van beide hooks is geregistreerd. Gebruik voor nieuwe voorbeeldpaden de afrondbare livevoorbeeldhelpers uit API voor uitgaande kanalen.

Migratie

Runtime-aliassen van runtime.channel.turn.* zijn verwijderd. Gebruik:

• runtime.channel.inbound.run(...) voor onbewerkte inkomende gebeurtenissen.
• runtime.channel.inbound.dispatchReply(...) voor samengestelde antwoordcontexten.
• runtime.channel.inbound.buildContext(...) voor payloads van inkomende contexten.
• runtime.channel.inbound.runPreparedReply(...), verouderd, alleen voor door kanalen beheerde voorbereide verzendpaden die hun eigen verzendclosure al samenstellen.

Nieuwe Plugincode mag geen kanaal-API's met de naam turn introduceren. Houd terminologie voor model- of agentbeurten binnen agent-/providercode; kanaalplugins gebruiken termen voor inkomend verkeer, berichten, bezorging en antwoorden.