API voor uitgaande kanaalberichten

Channelplugins maken het gedrag voor uitgaande berichten beschikbaar vanuit openclaw/plugin-sdk/channel-outbound. Gebruik openclaw/plugin-sdk/channel-inbound voor de orkestratie van ontvangst/context/dispatch.

Core beheert wachtrijvorming, duurzaamheid, de duurzame ingangsmonitor en verwerking (createChannelIngressMonitor, createChannelIngressDrain en openChannelIngressDrain), generiek beleid voor nieuwe pogingen, de levenscyclus voor overname van beurten (turnAdoptionLifecycle / bindIngressLifecycleToReplyOptions), hooks, ontvangstbewijzen en de gedeelde tool message. De plugin beheert native aanroepen voor verzenden/bewerken/verwijderen, normalisatie van doelen, platformspecifieke threads, geselecteerde citaten, meldingsvlaggen, accountstatus, inspectie van binnenkomende gegevens en codering van payloads, baansleutels, predicaten voor niet-opnieuw-uitvoerbare fouten, optionele autorisatie voor vervanging en platformspecifieke neveneffecten.

Duurzame ingangsmonitors

Gebruik createChannelIngressMonitor(...) wanneer een kanaal geaccepteerde transportgebeurtenissen vóór dispatch duurzaam moet opslaan. Dit combineert een wachtrij en verwerking voor kanaalingang met de gedeelde levenscyclus voor toelating, polling, opschoning, levering en afsluiting. Gebruik het onderliggende createChannelIngressDrain(...) alleen wanneer het transport een wezenlijk ander contract voor toelating of verwerking beheert.

De vereiste opties zijn:

De monitor serialiseert toelatingen, zodat back-off bij toevoegen de volgorde binnen een baan niet kan omkeren. De standaard begrensde vertragingen voor toevoegen zijn 0, 100 en 300 ms; bij uitputting wordt de transportcallback geweigerd in plaats van een gebeurtenis te dispatchen die niet duurzaam is opgeslagen. Op het moment van claimen decodeert de monitor de payload met versie, voert inspect opnieuw uit en weigert deze een niet-overeenkomende id of baan vóór levering.

deliver ontvangt onAdopted, onDeferred, onAdoptionFinalizing, onAbandoned en abortSignal. Terugkeren zonder expliciete overdracht markeert een terminale gebeurtenis zonder dispatch als overgenomen. admission is altijd exclusive. Een uitgestelde overdracht houdt de claim vast, terwijl afsluiting of afbreking niet-overgenomen werk opnieuw uitvoerbaar laat. De monitor volgt levering onafhankelijk van de afhandeling van claims, omdat overname een rij als verwijderd kan markeren voordat de leveringsbelofte van het kanaal terugkeert.

Optionele instellingen omvatten aangepaste vertragingen voor toevoegen, een optieblok drain voor geavanceerde volgorde/concurrency/beleid voor nieuwe pogingen bij verwerking, een extern abortSignal, een klok, rapportage van verwerkingsfouten, een factory voor fouten bij gestopte toestand en toelatingsbeleid. De geretourneerde monitor maakt admit, start, pause, stop, waitForIdle, isRunning en isStopped beschikbaar. stop handelt eerst geaccepteerde toelatingen af, breekt daarna de verwerking af en verwijdert deze, wacht op de verwerking en actieve leveringen, en verwijdert deze opnieuw om de racecondition bij luie creatie af te sluiten.

Houd transportspecifieke redactie, validatie van onbewerkte enveloppen, classificatie als niet-opnieuw-uitvoerbaar en de opgeslagen payloadvorm in de plugin. Webhook-transporten mogen pas bevestigen nadat admit is voltooid; transporten zonder herhalingsmogelijkheid moeten uitputting bij duurzaam toevoegen melden in plaats van stilzwijgend te dispatchen.

Adapter

De meeste plugins definiëren één message-adapter:

   defineChannelMessageAdapter,  createMessageReceiptFromOutboundResults,} from "openclaw/plugin-sdk/channel-outbound"; export const demoMessageAdapter = defineChannelMessageAdapter({  id: "demo",  durableFinal: {    capabilities: {      text: true,      replyTo: true,      thread: true,      messageSendingHooks: true,    },  },  send: {    text: async ({ cfg, to, text, accountId, replyToId, threadId, signal }) => {      const sent = await sendDemoMessage({        cfg,        to,        text,        accountId: accountId ?? undefined,        replyToId: replyToId ?? undefined,        threadId: threadId == null ? undefined : String(threadId),        signal,      });       return {        receipt: createMessageReceiptFromOutboundResults({          results: [{ channel: "demo", messageId: sent.id, conversationId: to }],          kind: "text",          threadId: threadId == null ? undefined : String(threadId),          replyToId: replyToId ?? undefined,        }),      };    },  },});

Declareer alleen mogelijkheden die het native transport daadwerkelijk behoudt. Dek elke gedeclareerde mogelijkheid voor verzenden, ontvangstbewijzen, livevoorbeelden en ontvangstbevestigingen af met de contracthelpers die vanuit dit subpad worden geëxporteerd.

Onderdrukking van uitgaande echo's

Wanneer een platform het eigen uitgaande bericht van de plugin opnieuw als inkomend bericht kan afleveren, roep je recordOutboundMessageIdentity(...) aan met het kanaal, account, gesprek en een stabiele platformbericht- of bronidentiteit. Het gedeelde pad voor inkomende beurten verwijdert overeenkomende identiteiten gedurende een begrensd venster van 30 seconden vóór sessieregistratie of dispatch naar de agent; een bronidentiteit kan vóór verzending worden gereserveerd of worden vernieuwd wanneer een kanaalroute wordt verwijderd om leveringsraceconditions af te sluiten. isRecentOutboundMessageIdentity(...) maakt dezelfde query beschikbaar voor kanaaldiagnostiek en tests. Onderhoud geen parallelle kanaallokale TTL-cache voor dezelfde stabiele identiteit.

Opschoning van platte tekst

Gebruik sanitizeForPlainText(...) wanneer een uitgaande adapter de ondersteunde HTML-opmaaktags moet omzetten in lichtgewicht tekstopmaak. Standaard blijven de bestaande chatmarkeringen voor vet en doorhalen behouden. Geef { style: "markdown" } alleen door wanneer het kanaal het resultaat opnieuw als Markdown verwerkt:

 const chatText = sanitizeForPlainText(text);const markdownText = sanitizeForPlainText(text, { style: "markdown" });

De Markdown-stijl gebruikt **bold** en ~~strikethrough~~; cursief en inline code behouden in beide stijlen _italic_ en backtickmarkeringen. Selecteer de stijl bij de kanaalgrens in plaats van markeringstekst na opschoning te herschrijven.

Leveringsbewijs

Een MessageReceipt registreert het resultaat dat een kanaaladapter retourneert. Concrete platformbericht-id's tonen aan dat het verzendpad van het platform het bericht heeft geaccepteerd; ze bewijzen niet dat het apparaat van een ontvanger het heeft weergegeven of gelezen. Ontvangstbewijzen zonder platformbericht-id's zijn uitsluitend lokale metagegevens voor ontvangstbewijzen. Kanalen met leesbevestigingen of informatie over levering aan apparaten moeten deze feiten via een afzonderlijk kanaalspecifiek pad bijhouden.

Als een kanaaladapter kan bewijzen dat het opnieuw proberen van een fout geen voor de ontvanger zichtbare verzending kan dupliceren en er geen aanroep met finalisatiemogelijkheid is begonnen, genereer dan new PlatformMessageNotDispatchedError("...", { cause: error }) vanuit openclaw/plugin-sdk/error-runtime. Core kan dan verouderd bewijs van verzendpogingen wissen en de intentie in de wachtrij veilig opnieuw uitvoeren. Alleen de adapter die de uiteindelijke dispatchgrens beheert, mag dit beweren. Gebruik de markering nooit nadat een finalisatie-/verzendaanroep begint of een dubbelzinnig resultaat retourneert; een onjuiste markering kan berichten dupliceren.

Bestaande uitgaande adapters

Als het kanaal al een compatibele outbound-adapter heeft, leid je de berichtadapter daarvan af in plaats van verzendcode te dupliceren:

 export const messageAdapter = createChannelMessageAdapterFromOutbound({  id: "demo",  outbound,  durableFinal: {    capabilities: {      text: true,      media: true,    },  },});

Duurzame verzendingen

Runtime-helpers voor verzending zijn ook beschikbaar op channel-outbound:

• sendDurableMessageBatch(...)
• withDurableMessageSendContext(...)
• deliverInboundReplyWithMessageSendContext(...)
• helpers voor conceptstreaming/voortgang, zoals resolveChannelDraftStreamingChunking(...)

sendDurableMessageBatch(...) retourneert één expliciete uitkomst:

Gebruik payloadOutcomes wanneer een batch verzonden, onderdrukte en mislukte payloads combineert. Leid annulering door hooks niet af uit een leeg verouderd resultaat voor directe levering.

Toelating voor uitgestelde levering

Gebruik message.durableFinal.admitDeferredDelivery(...) wanneer een herleid account door Core beheerde uitgaande of uitgestelde levering niet veilig kan accepteren. Core roept deze hook synchroon aan vóór actief uitgaand werk, inclusief paden die duurzame opslag in de wachtrij overslaan, en opnieuw voordat een herstelde intentie wordt afgespeeld. De context omvat cfg, channel, to, accountId en een phase van live of recovery.

Retourneer { status: "allowed" } om door te gaan. Retourneer { status: "permanent_rejection", reason } wanneer de levering niet duurzaam mag worden opgeslagen, rechtstreeks mag worden verzonden of opnieuw mag worden afgespeeld. Een actieve weigering mislukt vóór het aanmaken van de wachtrij, berichthooks of platformwerk. Een weigering tijdens herstel markeert de wachtrijregistratie als mislukt en slaat reconciliatie en opnieuw afspelen over. Als de hook ontbreekt, is dit toegestaan.

De hook is een synchrone toelatingsbeslissing, geen verzendpad. Lees alleen reeds geladen configuratie of runtimestatus; voer geen netwerk-, bestandssysteem- of andere asynchrone I/O uit. Contracttests moeten beide fasen en beide resultaatvarianten doorlopen via ChannelMessageDurableFinalAdapter vanuit openclaw/plugin-sdk/channel-outbound.

Compatibiliteitsdispatch

Stel de dispatch voor inkomende antwoorden samen via dispatchChannelInboundReply(...) vanuit channel-inbound. Houd platformlevering in de leveringsadapter; gebruik channel-outbound voor berichtadapters, duurzame verzendingen, ontvangstbevestigingen, live voorvertoning en opties voor de antwoordpijplijn.