- Move INTERACTIVE_MESSAGES.md to docs/ folder
- Remove all third-party name references from code comments
- Temporarily remove docs from .gitignore to allow tracking
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Previously the same `text` field was used for both header.title and body.text,
causing duplicate content to appear. Now `title` controls the header (defaults
to a space like Pastorini) and `text` controls the body independently.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove messageContextInfo (deviceListMetadata) from viewOnceMessage wrapper
in generateButtonMessage and remove empty subtitle from header. This fixes
CTA mixed buttons (url, copy, call) not being delivered to iOS devices -
same pattern that fixed carousel messages.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Flatten image validation nesting to max 4 levels (eslint max-depth)
- Collapse multi-line ternary to single line (prettier)
- Add missing blank line before statement
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Lint fixes:
- Replace `any` types with proper proto interfaces (IInteractiveMessage)
- Fix missing blank lines before statements (eslint padding-line-between-statements)
- Fix unused variable and indentation in protocol dump
- Remove pre-existing `any` casts in createParticipantNodes
Review feedback (Copilot/Codex):
- Gate protobuf roundtrip test and protocol dump behind debug level
(avoids CPU overhead and sensitive data exposure in production)
- Add empty array validation for nativeButtons (fixes [].every() edge case)
- Support headerTitle in quick_reply buttonsMessage (HeaderType.TEXT)
- Fix stale comment that said "wrap viewOnceMessage" when code sends direct
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Carousel (interactiveMessage):
- Remove messageContextInfo from carousel (breaks iOS delivery)
- Remove empty subtitle field from card headers
- Add jpegThumbnail/dimensions validation for card images
- Return direct interactiveMessage at root (no viewOnceMessage wrapper)
- Skip DSM (deviceSentMessage) for own devices (causes error 479)
- Skip bot node injection for carousel messages
Quick Reply Buttons (buttonsMessage):
- Separate quick_reply buttons from CTA buttons in generateWAMessageContent
- quick_reply (reply only) uses legacy buttonsMessage format (works on Android + iOS + Web)
- CTA buttons (url, copy, call) use nativeFlowMessage with viewOnceMessage wrapper
Stanza construction (messages-send.ts):
- Defer biz/bot nodes to be appended LAST (after device-identity, tctoken)
- Fix button name extraction for carousel (flatMap from cards)
- Add protobuf roundtrip test and protocol dump for debugging
Tested: Carousel renders on Android + iOS. Quick reply buttons render on Android + iOS + Web.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Applied yarn lint --fix to auto-correct:
- Import spacing and sorting across multiple files
- Trailing commas
- Arrow function formatting
- Object literal formatting
- Indentation consistency
- Removed unused imports (BaileysEventType, jest from tests)
This commit addresses the linting errors reported in GitHub Actions:
- Fixed import ordering in libsignal.ts
- Fixed trailing commas in Defaults/index.ts
- Cleaned up formatting across 63 files
- Reduced line count by ~220 lines through formatting optimization
Note: Some lint errors remain (75 errors, 239 warnings) mainly:
- @typescript-eslint/no-unused-vars (variables assigned but not used)
- @typescript-eslint/no-explicit-any (type safety warnings)
These remaining issues are non-blocking and can be addressed incrementally.
https://claude.ai/code/session_015R3U3kiprQiNTTNNt31Sg6
Fixes:
- chats.ts: revert encodeResult/initial to ! (guaranteed by callback assignment)
- groups.ts: fix operator precedence with ?? (wrap +attrs in parens), fix groupId type
- messages-recv.ts: extract messageKey.id to local const with fallback
- socket.ts: revert onClose! (guaranteed by synchronous callback assignment)
- event-buffer.ts: add 'notify' fallback for MessageUpsertType
- messages.ts: add filePath const after null guard, fix contextInfo type assertion
- noise-handler.ts: restore array index ! (guaranteed by length check)
Build now compiles with zero new errors.
https://claude.ai/code/session_01E2cfX1N3sJgCJBTvzGazSG
Pastorini's carousel renders on WhatsApp Web. Key differences found
by comparing logs and screenshot:
1. Direct interactiveMessage at root (NO viewOnceMessage wrapper)
- messageKeys: ['interactiveMessage'] in Pastorini logs
- Previous attempts with viewOnce V1/V2 all failed on Web
2. Root header WITH title + hasMediaAttachment: false (restored)
3. messageVersion: 1 in carouselMessage (restored)
4. tctoken included in stanza (was being skipped for carousel)
- Pastorini stanza: ['participants','device-identity','tctoken','biz']
5. messageContextInfo at message root level (kept)
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
Compare with ckptw's working carousel implementation:
1. Remove root header from interactiveMessage - ckptw does NOT set
a header on the root, only on individual cards. The root header
was incorrectly believed to prevent error 479.
2. Remove messageVersion from carouselMessage - ckptw doesn't set it.
Structure now matches ckptw exactly:
viewOnceMessage > message > {
messageContextInfo,
interactiveMessage: {
body, footer,
carouselMessage: { cards } // no messageVersion
// no header at root level
}
}
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
1. Switch wrapper from viewOnceMessageV2 (field 55) to viewOnceMessage V1
(field 37). V2 renders on mobile but NOT on WhatsApp Web/Desktop.
V1 is what ckptw, Vkazee, and most working Baileys forks use.
Previous error 479 with V1 was caused by missing root header and
fromObject() corruption - both now fixed.
2. Stop skipping own linked devices for carousel messages. This was
preventing the sender's WhatsApp Web from receiving the carousel.
3. Allow DSM (deviceSentMessage) wrapper for carousel - no longer
skip it for own devices or retry paths.
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
1. Suppress verbose "Closing session: SessionEntry {...}" logs from
libsignal that dump cryptographic keys/ratchets to console.log
2. Add warning when carousel cards don't have media attachments -
WhatsApp Web requires every card to have hasMediaAttachment:true
with actual image/video (per ckptw reference implementation)
3. Add carousel structure summary log for debugging card composition
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
The messageContextInfo with deviceListMetadata was only inside the V2 wrapper.
relayMessage copies message.messageContextInfo to meMsg for sender's own
devices (DSM), so it needs to be at the outer level too.
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
Switch carousel from direct interactiveMessage to viewOnceMessageV2
wrapper (field 55), confirmed by Z-API as the stable approach for
WhatsApp Web rendering from non-Cloud API accounts.
Key changes:
- Wrap carousel in viewOnceMessageV2 > message > interactiveMessage
(V1 caused error 479, direct interactiveMessage didn't render on Web)
- Add messageContextInfo with deviceListMetadata and version 2 for
multi-device rendering compatibility
- Update all helper functions (getButtonType, isCarouselMessage,
isCatalogMessage, isListNativeFlow, getButtonArgs) to check V2 path
- Update per-device and biz node debug logging for V2 detection
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
Pastorini's working implementation confirms carousels must be sent as
direct interactiveMessage at the message root level, NOT wrapped in
viewOnceMessage. The viewOnce wrapper prevented rendering on WhatsApp
Web and delivery to Apple/iOS users.
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
Three changes matching Pastorini's working implementation:
1. Always set root header in generateCarouselMessage - the root
interactiveMessage header must always be present with title and
hasMediaAttachment:false. Previously it was undefined when no text
was provided, which violates WhatsApp MD protocol requirements.
2. Return plain JS object from generateWAMessageContent for carousel -
skip WAProto.Message.fromObject() which can corrupt nested carousel
structures by incorrectly handling oneOf fields in deeply nested
InteractiveMessage cards. protobuf encode() handles plain objects
correctly during serialization.
3. Pass plain JS object directly to relayMessage in sendMessage - call
relayMessage(jid, msgContent) with the plain object instead of
going through proto.WebMessageInfo.fromObject() first. This matches
Pastorini's approach of relayMessage(jid, plainObject, opts).
https://claude.ai/code/session_018DkDxsjWzM131jy3ivWjZp
- Remove hasSubtitle (field 10) from Header proto definition, index.js
and index.d.ts - this field was adding extra bytes to encoded protobuf
that working implementations don't send, potentially causing rejection
- Remove hasSubtitle from carousel card headers and root header
- Add [CAROUSEL DEBUG] logging in relayMessage to dump:
- Encoded message bytes as base64 (for binary comparison)
- Message structure as JSON
- Per-device encoded bytes with DSM flag
- This enables byte-level comparison with working implementations
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Implementação completa baseada na análise ponto-a-ponto de 5 diferenças:
1. hasSubtitle adicionado ao proto schema (field 10, bool em Header)
- Adicionado ao WAProto.proto, index.js (encode/decode/fromObject/toObject)
- Adicionado ao index.d.ts (IHeader, Header class)
- Usado no root header e em cada card do carousel
2. relayMessage direto para carousel em sendMessage
- Detecta nativeCarousel no content e bypassa generateWAMessage inteiro
- Chama generateWAMessageContent (que usa fromObject) diretamente
- Depois relayMessage sem passar por generateWAMessageFromContent
- Elimina: segundo WAProto.Message.create(), contextInfo.expiration, etc.
3. Pipeline final do carousel agora:
sendMessage → generateWAMessageContent(fromObject) → relayMessage
Sem: generateWAMessageFromContent, WAProto.Message.create, ephemeral
Commits anteriores já incluem:
- viewOnceMessage wrapper
- fromObject no generateWAMessageContent
- Skip tctoken no stanza
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Três correções para eliminar erro 479 em dispositivos vinculados:
1. Skip WAProto.Message.create() em generateWAMessageFromContent para carousel
- O carousel já foi processado com fromObject() (conversão profunda)
- O segundo create() faz cópia rasa que pode perder tipos protobuf nested
- Preserva a estrutura deep: cards > headers > imageMessage > nativeFlowMessage
2. Skip tctoken no stanza para carousel
- Implementações que funcionam não incluem tctoken para carousel
- Pode causar rejeição 479 em dispositivos vinculados (Web/Desktop)
3. Skip contextInfo.expiration (ephemeral) para carousel
- Se mensagens temporárias estão ativadas, contextInfo.expiration era
adicionado ao interactiveMessage, o que pode causar 479
- Implementações que funcionam não passam por generateWAMessageFromContent
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Mudanças críticas para renderização do carousel em dispositivos vinculados:
1. Wrap carousel em viewOnceMessage para compatibilidade multi-device (MD)
2. Usar WAProto.Message.fromObject() ao invés de create() para conversão
profunda das estruturas nested (header, cards, nativeFlowMessage)
3. Adicionar root header com título no interactiveMessage
4. Retorno antecipado do carousel (sem messageContextInfo/reportingToken)
A diferença entre fromObject e create:
- fromObject: converte recursivamente objetos JS para tipos protobuf
- create: cópia rasa que pode não codificar corretamente estruturas deep
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
sendMessage adiciona messageContextInfo.messageSecret ao proto da
mensagem (para reporting token). Isso nao existe quando relayMessage
e chamado diretamente. O messageContextInfo ao lado de
interactiveMessage.carouselMessage causa erro 479 nos dispositivos
vinculados (Web/Desktop).
Agora o carousel pula a adicao de messageContextInfo, resultando em
um proto limpo: { interactiveMessage: { carouselMessage: {...} } }
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Ajuste na estrutura do carrossel para renderizar na Web:
1. Removido viewOnceMessage wrapper - carrossel usa interactiveMessage direto
2. Biz node habilitado com native_flow v=9 name=mixed
3. Removido subtitle vazio e header vazio do nível raiz
4. Sem bot node (já estava correto)
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Mudanças baseadas na comparação com Pastorini:
1. Adicionado viewOnceMessage wrapper MÍNIMO (sem messageContextInfo)
- viewOnceMessage é obrigatório para Web/Desktop renderizar carousel
- messageContextInfo pode ter causado o erro 479 anterior
2. Removido campos extras que Pastorini não usa:
- Removido messageParamsJson dos cards
- Removido messageVersion dos cards
- Removido carouselCardType (Pastorini não define)
- Removido header vazio no nível raiz (Pastorini não envia)
3. Estrutura final:
viewOnceMessage.message.interactiveMessage.carouselMessage
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Two changes to fix carousel rendering on WhatsApp Web/Desktop:
1. Added carouselCardType: 1 (HSCROLL_CARDS) to carouselMessage - this
proto field tells the client how to render carousel cards. Without it,
Web/Desktop doesn't know to render horizontal scrollable cards.
2. Removed viewOnceMessage wrapper - confirmed it causes error 479
rejection from linked devices (Web/Desktop). Carousel works as
direct interactiveMessage on phone; carouselCardType should fix Web.
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
WhatsApp Web/Desktop requires interactiveMessage to be wrapped inside
viewOnceMessage.message to render carousels fully. Without the wrapper,
only the header/body text is shown. The previous error 479 was caused by
missing messageVersion and empty messageParamsJson in cards, not by the
viewOnceMessage wrapper itself. Those card fixes are preserved.
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Each carousel card's nativeFlowMessage was missing messageVersion and
had empty string '' for messageParamsJson instead of '{}'. This caused
error 479 on linked devices (Web/Desktop) while phone rendered OK.
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Carousels wrapped in viewOnceMessage cause error 479 rejection.
Pastorini sends carousel as direct interactiveMessage which works
on all platforms including WhatsApp Web/Desktop.
https://claude.ai/code/session_01EK9NpViRCtda1WAvFd8ptR
Validates sections, rows, and string lengths before sending:
- Max 10 sections, 10 rows/section, 30 total rows
- Section title max 24 chars, row title max 24 chars
- Row description max 72 chars, row ID max 200 chars
- buttonText max 20 chars
- At least 1 section and 1 row per section required
Applied to all 3 list message paths: generateListMessage,
generateListMessageLegacy, and inline sections handler.
https://claude.ai/code/session_01SJdSHiUxtwzV8bb5dedodb
When title is not provided, the text was used as fallback for both
title and description, causing the header to appear twice. Now title
only uses an explicit title field, description uses text.
https://claude.ai/code/session_01SJdSHiUxtwzV8bb5dedodb
PRODUCT_LIST type requires WhatsApp Business catalog data and causes
error 479 for regular menu lists. SINGLE_SELECT is the correct type
for interactive menu lists with sections/rows.
https://claude.ai/code/session_01SJdSHiUxtwzV8bb5dedodb
Error 479 was still occurring even with legacy listMessage format.
The issue is that listType must be PRODUCT_LIST (not SINGLE_SELECT)
to match the biz node type="product_list" v="2" that we're injecting.
This matches pastorini's working implementation exactly:
- listMessage with listType: PRODUCT_LIST
- biz node with type="product_list" v="2"
https://claude.ai/code/session_01Vgu4xrsj8aUVCHWb4pmQPF
The modern interactiveMessage format was causing error 479 (message rejection).
Switched to legacy listMessage format that matches pastorini's working implementation.
Changes:
1. **messages.ts**: Changed nativeList to use generateListMessageLegacy()
- Creates listMessage directly (not viewOnceMessage wrapper)
- Uses SINGLE_SELECT type (standard list)
2. **messages-send.ts**: Inject correct biz node for listMessage
- For buttonType === 'list': <biz><list type="product_list" v="2">
- Matches pastorini's working structure
- Removed checks that skipped biz node for listMessage
Why this works:
- Legacy listMessage + product_list biz node = accepted by WhatsApp
- Modern interactiveMessage + native_flow biz node = error 479
- This matches the pastorini implementation that works on Web/iOS/Android
https://claude.ai/code/session_01Vgu4xrsj8aUVCHWb4pmQPF
- Fix ProductCarouselMessageOptions import indentation
- Fix productList comment indentation to align with else-if chain
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Replace catalogId with businessOwnerJid (required for catalog reference)
- Fix cards structure to use proper IInteractiveMessage[] format
- Each card now uses collectionMessage with bizJid and id
- Fix body reading from productCarousel.body (was reading from message.body)
- Remove 'as any' type casting by using correct proto types
- Update examples in types and function documentation
Addresses:
- Schema mismatch in carousel cards
- Body text being silently ignored when nested in productCarousel
- Improper type casting masking validation errors
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes based on code review:
1. Fix sections vs productSections mismatch
- Changed `productMsg.productList.sections` to `productMsg.productList.productSections`
- Ensures consistency with ProductListMessageOptions type
2. Add section title validation
- Each section must have a non-empty title string
3. Add productId validation for each product
- Each product in a section must have a non-empty productId string
4. Add headerImage.productId validation
- When headerImage is provided, productId must be a non-empty string
5. Remove fallback values (|| '')
- Removed fallbacks for title and description
- Let generateProductListMessage handle validation consistently
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add generateProductListMessage function for sending multiple products
from the WhatsApp Business catalog in a single message.
Features:
- ProductListMessageOptions type with full validation
- Support for product sections (categories)
- Optional header image from catalog
- Integration with sendMessage via 'productList' property
- Maximum 30 products limit per WhatsApp specs
Usage:
```typescript
const msg = generateProductListMessage({
title: 'Our Best Sellers',
description: 'Check out our products!',
buttonText: 'View Products',
businessOwnerJid: '5511999999999@s.whatsapp.net',
productSections: [
{ title: 'Electronics', products: [{ productId: 'prod_001' }] }
]
})
await sock.sendMessage(jid, msg)
```
Note: Requires WhatsApp Business account with catalog configured.
Does NOT require Meta Business Manager integration.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Fixes all 9 issues identified in PR #49 review:
## 1. Input Validation (formatNativeFlowButton)
- Added validateNonEmptyString helper function
- Validates required fields: text, url, copyText, id, phoneNumber
- Throws Boom error with descriptive message for empty/whitespace values
## 2-3. Async Media Processing (generateButtonMessage)
- Function is now async, returns Promise<WAMessageContent>
- Accepts optional MessageContentGenerationOptions parameter
- Calls prepareWAMessageMedia() for headerImage/headerVideo
- Throws error if media provided without mediaOptions
## 4-7. Async Media Processing (generateCarouselMessage)
- Function is now async, returns Promise<WAMessageContent>
- Uses Promise.all to process all card media in parallel
- Properly converts WAMediaUpload to IImageMessage/IVideoMessage
## 5. Mutual Exclusivity Validation
- generateButtonMessage: Throws if both headerImage AND headerVideo provided
- generateCarouselMessage: Throws if card has both image AND video
## 6. Empty Button Array Validation
- Each carousel card must have at least one button
- Throws descriptive error with card index
## 8. Updated Async Calls
- generateWAMessageContent now awaits generateButtonMessage
- generateWAMessageContent now awaits generateCarouselMessage
- Both pass MessageContentGenerationOptions for media processing
## 9. Type Support
- Functions accept MessageContentGenerationOptions as optional param
- Enables access to upload, mediaCache, logger options
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Extends the Native Flow implementation with additional features:
## New Button Type
- `CallButton` - `cta_call` type for initiating phone calls
```typescript
{ type: 'call', text: 'Call Us', phoneNumber: '+5511999999999' }
```
## New List Message Support
- `generateListMessage()` - Creates interactive list with single_select
- `nativeList` type for sendMessage integration
```typescript
await sock.sendMessage(jid, {
text: 'Choose:',
nativeList: {
buttonText: 'View Options',
sections: [{ title: 'Section', rows: [...] }]
}
})
```
## Legacy Functions (for backward compatibility)
- `generateButtonMessageLegacy()` - Old buttonsMessage format
- `generateListMessageLegacy()` - Old listMessage format
⚠️ These are deprecated and may not work on all devices
## Other Improvements
- Added `merchantUrl` support for URL buttons
- Added `messageVersion` parameter (default: 2)
- Added `messageParamsJson` to nativeFlowMessage
- Created `NativeListSection` type to avoid conflict with legacy `ListSection`
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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>
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>
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>
Renato Alcara