Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(plugins): say what an ingress reply does to message:sending

Yudhi Armyndharis65c950096042
diff --git a/docs/25-integration-fabric.md b/docs/25-integration-fabric.md
index 3c714e3d8..2aac572f2 100644
--- a/docs/25-integration-fabric.md
+++ b/docs/25-integration-fabric.md
@@ -222,8 +222,11 @@ Four tables live on the data connection, each created by a hand-authored dual-di
- **Egress.** The only sanctioned outbound path remains the SSRF-guarded `ctx.net.fetch`, scoped to the
manifest's allowed hosts; a direct Node socket opened by the worker is not covered (see [30 - Plugin
Sandboxing](./30-plugin-sandboxing.md)).
-- **Re-entrancy.** A reply issued _inside_ an ingress handler seeds the in-flight hook set, so an adapter's
- own outbound message hook cannot echo-loop the reply back out to the external system.
+- **Re-entrancy.** A send issued from inside a hook handler is short-circuited for the event that handler
+ is running, so a hook cannot re-fire itself. A reply issued from an ingress handler carries no hook
+ context: it runs every plugin's `message:sending` hooks, the adapter's own included, so an adapter that
+ mirrors outbound messages to its provider must recognise and skip the replies it sent itself, for example
+ by the message id the send returned.
## 25.7 Scale and durability
diff --git a/src/core/plugins/conversation-send-facade.ts b/src/core/plugins/conversation-send-facade.ts
index bc2fe0211..ff2a08b28 100644
--- a/src/core/plugins/conversation-send-facade.ts
+++ b/src/core/plugins/conversation-send-facade.ts
@@ -13,10 +13,12 @@ export interface ConversationSendDeps {
assertSessionActive: (sessionId: string) => void;
// Resolve the WA chat id from conversation_mappings when the envelope omits chatId.
resolveChatId: (env: ConversationSendEnvelope) => Promise<string>;
- // Seed the hook in-flight set so an adapter's own outbound message:sending hook cannot echo-loop
- // back into this same send. Only 'message:sending' is reachable this way — MessageService fires it
- // synchronously inside sendText/reply. 'message:sent' is emitted later by SessionEngineLifecycle's
- // engine callback (onMessageCreate), outside this call's async scope, so seeding it here would be a no-op.
+ // Run the send inside the hook context the caller is already in, when it is in one: a send from a hook
+ // handler then cannot re-fire that handler's own message:sending event. A send from an ingress handler
+ // is in no hook context and runs the full chain. Only 'message:sending' is reachable this way,
+ // because MessageService fires it synchronously inside sendText/reply. 'message:sent' is emitted later
+ // by SessionEngineLifecycle's engine callback (onMessageCreate), outside this call's async scope, so
+ // seeding it here would be a no-op.
runGuarded: <T>(events: string[], run: () => Promise<T>) => Promise<T>;
sendText: (sessionId: string, opts: { chatId: string; text: string; linkPreview?: boolean }) => Promise<unknown>;
reply: (sessionId: string, opts: { chatId: string; quotedMessageId: string; text: string }) => Promise<unknown>;
diff --git a/src/core/plugins/plugin-capability-context.ts b/src/core/plugins/plugin-capability-context.ts
index 2b1ab8226..3a38d49c5 100644
--- a/src/core/plugins/plugin-capability-context.ts
+++ b/src/core/plugins/plugin-capability-context.ts
@@ -419,11 +419,12 @@ export class PluginCapabilityContext {
}
return mapping.chatId;
},
- // Re-establish the in-flight hook context around the downstream send so an adapter that calls
- // conversation.send from within its own ingress handling can't echo-loop back into itself via
- // its own outbound message:sending hook. Gate on an ALREADY-in-flight event (mirrors the
- // worker-cap wrap's `inFlight.length > 0` check): a plain top-level send must NOT suppress
- // message:sending for unrelated observers (audit/moderation) — only genuine re-entrancy does.
+ // Re-establish the in-flight hook context around the downstream send, so a conversation.send made
+ // from a hook handler cannot re-fire that handler's own event (an echo loop through
+ // message:sending). Gate on an ALREADY-in-flight event (mirrors the worker-cap wrap's
+ // `inFlight.length > 0` check): a send from an ingress handler or any other top-level context
+ // carries none, and must NOT suppress message:sending for observers (audit/moderation, or the
+ // adapter's own mirror hook), which then see the reply.
runGuarded: (events, run) =>
(events as HookEvent[]).some(e => this.hookManager.isInFlight(e))
? this.hookManager.runInFlight(events as HookEvent[], run)