Adds backward compatibility alias:
- isJidUser -> isPersonJid
This allows zpro.io and other consumers that depend on the old
isJidUser function name to continue working without changes.
1. Add logger to writeCacheFile (version-cache.ts)
- Now logs warnings when file write fails
- Helps debugging in production environments
2. Sanitize logging in parseGroupResult (communities.ts)
- Changed from info to debug level
- Removed full node/groupNode dumps (sensitive data)
- Now only logs nodeTag and groupId
3. Add input validation in parseNewsletterCreateResponse (newsletter.ts)
- Validates response structure before destructuring
- Adds fallback values for parseInt (prevents NaN)
- Adds null checks for optional fields
4. Add health-status.ts module
- getHealthStatus(): Full health check with circuit breakers, cache, memory
- isHealthy(): Simple boolean for liveness probes
- getSimpleHealthStatus(): Returns 'ok', 'degraded', or 'error'
- Useful for k8s probes and monitoring dashboards
Fixes 3 issues identified in code review:
1. ENV VAR PRECEDENCE: Changed DEFAULT_CONNECTION_CONFIG to use
undefined for enableUnifiedSession, allowing env var
BAILEYS_UNIFIED_SESSION_ENABLED to take precedence.
Priority is now: explicit config > env var > default (true)
2. SINGLE INITIALIZATION: UnifiedSessionManager is now created
only once, after sendNode is defined. This avoids:
- Duplicate circuit breaker instances
- State reinitialization
- Unnecessary overhead and logs
3. CONTINUOUS TIME SYNC: serverTimeOffset is now updated on
every received frame that contains a 't' attribute, not just
on CB:success. This keeps the offset accurate even during
long-running connections.
Implements WhatsApp's unified_session telemetry feature to reduce
detection of unofficial clients. This is an enterprise-grade implementation
inspired by whatsmeow PR #1057 and Baileys PR #2294.
Features:
- UnifiedSessionManager class with circuit breaker protection
- Server time synchronization for accurate session IDs
- Rate limiting to prevent spam (1 minute between sends)
- Prometheus metrics integration (unified_session_sent, errors)
- Structured logging for debugging
- Configurable via SocketConfig.enableUnifiedSession
- Environment variable support (BAILEYS_UNIFIED_SESSION_ENABLED)
Trigger points (matching official WhatsApp Web):
- After successful login (CB:success)
- After successful pairing (CB:iq,,pair-success)
- When sending 'available' presence
Implementation details:
- Session ID algorithm: (now + serverOffset + 3days) % 7days
- Time constants exported from Defaults/index.ts
- Full test coverage (31 tests)
References:
- https://github.com/tulir/whatsmeow/pull/1057
- https://github.com/WhiskeySockets/Baileys/pull/2294
- https://github.com/tulir/whatsmeow/issues/810
Fix TS2345 errors where array element access (medias[i]) was inferred as
`AlbumMediaItem | undefined` instead of `AlbumMediaItem`.
Changes:
- Add non-null assertion (!) after array access in for loops
- Add explicit cast to AnyMessageContent for hasNonNullishProperty calls
The non-null assertion is safe here because we iterate with `i < medias.length`,
guaranteeing the index is valid.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Addresses additional PR review suggestions:
1. **Consistent media type validation**
- Changed from `'image' in m` to `hasNonNullishProperty(m, 'image')`
- Aligns with validation in generateWAMessageContent
- Prevents counting items with undefined image/video properties
2. **Explicit interrupted send indication**
- Added `attemptedItems: number` - how many items were actually tried
- Added `stoppedEarly: boolean` - true if interrupted by continueOnFailure=false
- Updated `success` to be false if stoppedEarly (even if no failures in attempted items)
- Helps automated integrations understand partial sends
Example result when interrupted:
```json
{
"totalItems": 5,
"attemptedItems": 3,
"successCount": 2,
"failedCount": 1,
"stoppedEarly": true,
"success": false
}
```
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes all issues identified in PR #44 review:
1. **Album root message now relayed to server** (Critical)
- Before: Only generated root message, never sent it
- After: Calls relayMessage() on albumRootMsg before sending media items
- Also emits own event if emitOwnEvents is enabled
2. **Fixed messageId collision**
- Before: Spread ...options could pass same messageId to all items
- After: Explicitly pass only safe options (timestamp, quoted, etc.)
- Each media item now gets a fresh ID from generateWAMessage
3. **Fixed proto structure for album association**
- Before: Used non-existent messageContextInfo.messageAddOnType
- After: Uses correct messageContextInfo.messageAssociation with:
- associationType: proto.MessageAssociation.AssociationType.MEDIA_ALBUM
- parentMessageKey: albumKey
4. **Added runtime error for sendMessage misuse**
- sendMessage() now throws clear error if called with { album: ... }
- Forces users to use sendAlbumMessage() for proper behavior
5. **Fixed documentation**
- delay: Changed "based on media size" to "based on media type"
- retryAttempts: Clarified it's "total attempts" not just retries
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Implements WhatsApp album messages (grouped media) with the following features:
- Send 2-10 images/videos grouped as a single album message
- Adaptive delay between sends based on media type (videos get 2x delay)
- Intelligent retry with exponential backoff for failed items
- parentMessageKey reference to album root (as suggested by maintainer)
- Complete result structure with success/failure tracking per item
- Validation for min (2) and max (10) media items
Types added:
- AlbumMediaItem: Single image/video with caption, mentions, dimensions
- AlbumMessageOptions: Configuration for delay, retry, continueOnFailure
- AlbumMediaResult: Per-item result with latency and retry attempts
- AlbumSendResult: Complete result with albumKey and statistics
Based on PR #2058 from WhiskeySockets/Baileys with improvements.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Update outdated file reference in comment (process-message.ts:399-421
-> PDO response handler in src/Utils/process-message.ts)
- Add missing else branch in fallback path for duplicate request logging
to maintain observability parity with scheduled path
- Clarify log message in fallback path to reflect direct request flow
('Message received before direct resend request completed')
https://claude.ai/code/session_011WM4Nb6tE1S5nLjHen8Xsi
Aligns CTWA recovery with upstream philosophy by using messageRetryManager
instead of direct requestPlaceholderResend calls.
Benefits:
- Uses 3-second delay from manager (avoids request spam)
- Enables automatic cancellation if message arrives before request
- Centralizes phone request logic in messageRetryManager
- Adds fallback for when manager is not available
Changes:
- Wrap requestPlaceholderResend in messageRetryManager.schedulePhoneRequest()
- Add new metric status 'scheduled' for tracking scheduled requests
- Add metric status 'sent' when request is actually sent after delay
- Keep direct call as fallback when messageRetryManager is null
https://claude.ai/code/session_011WM4Nb6tE1S5nLjHen8Xsi
Critical bug fix: Interactive message blocks were never being executed because
they were placed AFTER the normal text message processing block. Messages with
text+buttons were processed as plain text, ignoring the interactive features.
Changes:
- Move all interactive message processing (buttons, lists, templates, carousel)
to BEFORE the normal text processing block
- Remove duplicate interactive message blocks that were unreachable
- Ensure correct execution order: check for interactive features first, then
fallback to normal text processing
This fixes the runtime error where interactive message functions were not
being called properly when sending messages with buttons/lists.
Structure now:
1. Check text + buttons → buttonsMessage
2. Check text + templateButtons → templateMessage
3. Check sections → listMessage
4. Check carousel → interactiveMessage
5. Check text (normal) → extendedTextMessage
6. Other message types...
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Fixes type incompatibility error when processing buttons with media:
- Extract only media properties before passing to prepareWAMessageMedia
- Remove problematic interactiveMessage type from AnyRegularMessageContent
- Move Carouselable to text message type as Partial
This resolves the compilation error:
error TS2345: Argument of type '...' is not assignable to parameter
of type 'AnyMediaMessageContent'
Changes:
- src/Utils/messages.ts: Extract media content explicitly for type safety
- src/Types/Message.ts: Simplify type definitions, add Carouselable to text messages
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
⚠️ EXPERIMENTAL FEATURE - Use only for testing with disposable accounts
Implements full support for WhatsApp interactive messages including:
- Simple text buttons (up to 3 buttons)
- Buttons with images/videos
- List messages (up to 10 items in sections)
- Template buttons (quick reply, URL, call actions)
- Carousel messages (up to 10 scrollable cards)
Features:
- Feature flag 'enableInteractiveMessages' (default: true for dev/testing)
- Prometheus metrics for tracking sends, successes, failures, and latency
- Comprehensive TypeScript types for all interactive message formats
- Extensive logging with warnings about potential account bans
- Automatic 'biz' node injection when feature is enabled
CRITICAL WARNINGS:
- These features may NOT work on non-business WhatsApp accounts
- Can cause temporary or permanent account BANS
- WhatsApp actively blocks this functionality since April 2022
- Messages may be rejected or fail silently
- Use ONLY in dev environment with test accounts
Architecture:
- Added ButtonInfo, Templatable, Listable, Carouselable types to Message.ts
- Extended AnyMediaMessageContent and AnyRegularMessageContent
- Implemented message generation in messages.ts
- Added getButtonType() and getButtonArgs() helpers in messages-send.ts
- Injected 'biz' node in stanza construction with metrics tracking
- Added 4 new Prometheus metrics: interactiveMessagesSent, Success, Failures, Latency
Documentation:
- Complete usage guide in INTERACTIVE_MESSAGES.md
- Examples for all interactive message types
- Metrics monitoring queries
- Troubleshooting guide
- Migration path to WhatsApp Business API
Related issues:
- https://github.com/WhiskeySockets/Baileys/issues/56
- https://github.com/WhiskeySockets/Baileys/issues/25
- https://github.com/WhiskeySockets/Baileys/pull/2291
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
The property was declared twice in SocketConfig type:
- Line 134 as required boolean
- Line 211 as optional boolean
This caused TypeScript compilation errors:
- TS2300: Duplicate identifier
- TS2687: Mismatched modifiers
- TS2717: Type mismatch between required and optional
Removed the duplicate declaration, keeping the first one which is
already properly documented and has the correct type.
Prevents unnecessary placeholder resend requests for messages older than 7 days,
improving resource efficiency and aligning with upstream best practices. Adds
metrics tracking for rejected old messages and includes message age in logs.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
- Add explicit Buffer type annotations to salt, encKey, decKey variables
- Add Promise<[Buffer, Buffer]> return type to localHKDF function
- Add Buffer type casts for subarray return values
- Remove unnecessary non-null assertion operators (!)
Fixes TS2322 type mismatch errors when building with TypeScript 5.9.3+
and Node.js v24+. No runtime behavior changes.
Based on upstream PR #2284.
Merge upstream/master using 'ours' strategy to mark the following
commits as integrated (already cherry-picked with customizations):
- chat-utils,sync-action-utils: provide alternatives for the contact name
- example: revamp logging for example
- defaults, index: change shouldSyncHistoryMessage behavior
- history: fortify contact data
- history: add proper logging support in history
- example: cleanup
- socket: no sync warning!!!!!
- Fix connection showing "Online" but disconnected (#2132)
- fix: skip retry for expired status messages over 24 hours old
- fix: optimize getLIDsForPNs and add getPNsForLIDs (#2274)
- fix: extract LID-PN mappings from conversation objects in history sync
Our customizations are preserved. This zeros the "behind" counter.
Refactor example.ts to use pino logger with structured data:
- Replace all console.log with logger.debug/fatal
- Use objects for data instead of string concatenation
- Add contacts.upsert event handler
- Improves log filtering and searchability
Remove the override that was forcing full history sync when
syncFullHistory was true. Now uses the default from Defaults/index.ts
which skips FULL sync type for better performance and stability.
Benefits:
- Faster connection time (2-10s vs 30s-5min)
- Lower bandwidth usage (1-10MB vs 50-500MB+)
- More stable connections (no timeouts)
- INITIAL_BOOTSTRAP + RECENT provide sufficient data
Users can still customize via shouldSyncHistoryMessage if needed.
- Add fallback chain for contact name: displayName || name || username
- Add fallback for LID: lidJid || accountLid
- Add TODO marker for WAJIDHASH support in picture updates
These fallbacks improve robustness when WhatsApp returns contact
data in different fields depending on account type (business, personal).
- Add optional ILogger parameter to processHistoryMessage and
downloadAndProcessHistorySyncNotification functions
- Add trace-level logging with syncType and progress for debugging
- Preserve all existing imports and LID-PN extraction functionality
- Enhanced JSDoc documentation with detailed parameter descriptions
This enables trace-level visibility into history sync processing,
helping debug issues with message synchronization and LID mappings.
Fixes 4 issues identified in PR #35 code review:
## 1. Self-Primary Identity Check (Copilot #1)
- BEFORE: `ctx.meId && (areJidsSameUser(...) || (ctx.meLid && ...))`
- AFTER: Check meId and meLid independently with OR
- FIX: Now correctly detects when only meLid exists
## 2. Debounce Cache Placement (Copilot #3, #4)
- BEFORE: Cache set immediately after debounce check
- AFTER: Cache set only before actual assertSessions call
- FIX: Prevents incorrect debouncing when exiting early (offline, etc.)
## 3. Session Regression (ChatGPT Codex P2)
- BEFORE: Returned 'skipped_no_session' when no session exists
- AFTER: Always call assertSessions - identity change IS the signal to rebuild
- FIX: Critical for key reset and device restore scenarios
## 4. Result Type Enhancement
- Added `hadExistingSession: boolean` to 'session_refreshed' result
- Removed 'skipped_no_session' action (no longer applicable)
- Enables better monitoring of session creation vs refresh
## Test Updates
- Added test for meLid-only self-primary detection
- Updated session creation test (no longer skips)
- Added test verifying debounce not set on offline skip
- Added Result Types test suite for type safety
Cherry-pick from upstream PR #2280 (commit 92d4198)
- Add STATUS_EXPIRY_SECONDS constant (24h = 86400s)
- Skip retry attempts for status broadcast messages older than 24h
- Saves resources by not retrying messages that are already expired
Co-authored-by: João Lucas de Oliveira Lopes <55464917+jlucaso1@users.noreply.github.com>
Add extractPnFromMessages() function to extract phone numbers from
userReceipt fields when pnJid is missing in LID conversations.
This is a cherry-pick of the functionality from upstream PR #2282
(commit f829b6d7a) integrated with our existing LID-PN extraction logic.
Closes: WhiskeySockets/Baileys#2282
Metrics with labels only appear in Prometheus output after being
incremented at least once. This fix pre-initializes all labeled metrics
with zero values so they appear in Grafana dashboards immediately,
including buffer_destroyed_total which was showing "No data".
Added metrics tracking for:
- message_retries_total: Incremented when message retry is attempted
- message_failures_total: Incremented when max retries reached or encryption fails
Note: messages_queued metric is not applicable as this implementation
sends messages directly without an explicit queue system.
Added metrics tracking for:
- circuit_breaker_trips_total: Incremented when circuit opens
- adaptive_health_status: 1 if healthy (not in aggressive mode), 0 otherwise
- adaptive_event_rate: Current events per second
Added methods to AdaptiveTimeoutCalculator:
- getEventRate(): Returns current event rate in events/second
- isHealthy(): Returns true if not in aggressive mode
Metrics are updated on each buffer flush when adaptive timeout is enabled.
Added recordBufferDestroyed() and recordBufferFinalFlush() functions
and integrated into destroy() function in event-buffer.ts.
Tracks:
- Buffer destruction with reason and whether there was pending flush
- Final flushes that occur during buffer destruction
Claude