PR #54183: WhatsApp: add configurable send retry for transient network errors

• Repository: openclaw/openclaw
• Author: hassansys2
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/54183

Description (problem / solution / changelog)

Closes #54103

Summary

Adds configurable outbound send retry with exponential backoff for the WhatsApp channel, applied to all three send paths (text, media, poll). The retry is active by default with no config change needed.

What changed:

• src/config/types.whatsapp.ts — added retry?: OutboundRetryConfig to WhatsAppSharedConfig, inherited by both WhatsAppConfig and WhatsAppAccountConfig
• src/config/zod-schema.providers-whatsapp.ts — added retry: RetryConfigSchema to WhatsAppSharedSchema
• extensions/whatsapp/src/outbound-retry.ts (new) — shared retry helpers: withWhatsAppSendRetry, resolveWhatsAppRetryConfig, and defaults; isolated here so both the production plugin and the test adapter import from one place
• extensions/whatsapp/src/channel.ts — wraps the injected sendMessageWhatsApp and sendPollWhatsApp calls with retry before passing them to createWhatsAppOutboundBase; this is the actual production outbound path used by the plugin
• extensions/whatsapp/src/outbound-adapter.ts — also wraps its three send sites with retry (used in tests); imports from outbound-retry.ts instead of duplicating helpers
• src/config/bundled-channel-config-metadata.generated.ts — regenerated to include the new retry property in the WhatsApp channel schema
• docs/.generated/config-baseline.json / .jsonl — regenerated to document the 10 new channels.whatsapp[.accounts.*].retry.* config paths

Key design decisions:

• Only clearly transient errors are retried (/timeout|connect|reset|closed|unavailable|temporarily/i) to avoid duplicate message delivery on non-idempotent sends
• Account-level config takes precedence over channel-level; default account ID is resolved via resolveDefaultWhatsAppAccountId so channels.whatsapp.accounts.<default-id>.retry is honored even without an explicit accountId
• Account key lookup uses resolveAccountEntry (case-insensitive) to match the pattern used throughout WhatsApp account resolution
• Reuses existing RetryConfig / retryAsync / resolveRetryConfig infrastructure already used by Telegram

Config example

Channel-level (applies to all accounts):

{
  "channels": {
    "whatsapp": {
      "retry": {
        "attempts": 5,
        "minDelayMs": 3000,
        "maxDelayMs": 60000,
        "jitter": 0.1
      }
    }
  }
}

Per-account override (account-level takes precedence):

{
  "channels": {
    "whatsapp": {
      "retry": {
        "attempts": 3,
        "minDelayMs": 1000,
        "maxDelayMs": 30000
      },
      "accounts": {
        "my-account": {
          "retry": {
            "attempts": 2,
            "minDelayMs": 500,
            "maxDelayMs": 10000
          }
        }
      }
    }
  }
}

To disable retries for a specific account:

{
  "channels": {
    "whatsapp": {
      "accounts": {
        "my-account": {
          "retry": { "attempts": 1 }
        }
      }
    }
  }
}

Defaults (no config needed): 3 attempts, 1s–30s exponential backoff, 10% jitter.

Test plan

• pnpm test:extension whatsapp — 85 tests, all pass
• pnpm test:contracts:channels — all pass
• pnpm build — passes, no [INEFFECTIVE_DYNAMIC_IMPORT] warnings
• pnpm check — 0 warnings, 0 errors
• pnpm config:channels:check + pnpm config:docs:check — both pass
• New tests: retry on transient error succeeds on second attempt; non-transient errors not retried; attempts config limit respected
• Fully tested locally (see test plan above)
• Follows existing Telegram retry pattern (OutboundRetryConfig, retryAsync, resolveRetryConfig)
• Understands what the code does

Changed files

• docs/.generated/config-baseline.json (modified, +160/-74)
• docs/.generated/config-baseline.jsonl (modified, +31/-18)
• docs/plugins/architecture.md (modified, +3/-3)
• extensions/whatsapp/src/channel.test.ts (modified, +35/-0)
• extensions/whatsapp/src/channel.ts (modified, +13/-0)
• extensions/whatsapp/src/outbound-adapter.poll.test.ts (modified, +25/-0)
• extensions/whatsapp/src/outbound-adapter.sendpayload.test.ts (modified, +149/-0)
• extensions/whatsapp/src/outbound-adapter.ts (modified, +36/-20)
• extensions/whatsapp/src/outbound-retry.ts (added, +92/-0)
• extensions/whatsapp/src/send.test.ts (modified, +114/-0)
• extensions/whatsapp/src/send.ts (modified, +45/-7)
• src/channels/plugins/whatsapp-shared.ts (modified, +66/-22)
• src/config/bundled-channel-config-metadata.generated.ts (modified, +77/-128)
• src/config/types.whatsapp.ts (modified, +3/-0)
• src/config/zod-schema.providers-whatsapp.ts (modified, +2/-0)
• src/infra/retry-policy.test.ts (modified, +117/-1)
• src/infra/retry-policy.ts (modified, +64/-40)