Channel: WhatsApp Adapter (Baileys)

[ggondim]

Summary

Implement a custom WhatsApp channel adapter using Baileys (WhatsApp Web protocol library). This is the most complex adapter due to Baileys session management and WhatsApp's limited interactive message support.

Tasks

• Integrate Baileys library for WhatsApp Web protocol
• Inbound: messages (text, media), replies
• Outbound: text, buttons (WhatsApp interactive messages — max 3 buttons), lists
• Thread support: virtual threads via quoted replies
• A2H inline (method 1): limited — WhatsApp buttons for simple AUTHORIZE (max 3 options)
• A2H fallback: most COLLECT intents → method 3 (external form) due to platform limitations
• Response capture (method 2): quoted reply messages
• Session management: QR code auth flow, reconnection logic, session persistence
• Report capabilities: { threads: false, buttons: true (limited), selectMenus: false, replyMessages: true, dms: true, fileUpload: true }

Acceptance Criteria

• Adapter implements full ChannelAdapter interface
• QR code auth flow works for initial setup
• Session survives restarts (persistent auth state)
• Reconnection handles disconnects gracefully
• A2H AUTHORIZE with ≤3 options renders as WhatsApp buttons
• A2H COLLECT falls back to method 3 correctly
• Passes shared adapter conformance test suite

Dependencies

• Core: Data Model, Types & Interfaces #2 (Core: Data Model & Interfaces) — implements the ChannelAdapter interface

Known Risks

• Baileys is an unofficial library; WhatsApp may break compatibility
• WhatsApp business API is an alternative but requires Meta approval

References

• VISION.md — WhatsApp / Baileys
• PLAN.md — Phase 3.4

[claude]

@claude Implement this issue. Follow these steps precisely:

1. Checkout the base branch and create your working branch:
   git fetch origin meta/17 && git checkout meta/17 && git checkout -b claude/17-10-whatsapp-adapter
2. Implement all tasks listed in this issue
3. Commit and push your branch:
   git push -u origin claude/17-10-whatsapp-adapter
4. Create a PR targeting meta/17:
   gh pr create --base meta/17 --head claude/17-10-whatsapp-adapter --title "Channel: WhatsApp Adapter (Baileys)" --body "fixes Channel: WhatsApp Adapter (Baileys) #10"

[claude]

Claude finished @claude[bot]'s task in 11m 59s —— View job • claude/issue-10-20260410-2206 • Create PR ➔

---

Implementing WhatsApp Adapter (Baileys)

• Setup: explored codebase structure via VISION.md (no CLAUDE.md present)
• Create packages/channels/whatsapp/package.json
• Create packages/channels/whatsapp/tsconfig.json
• Create packages/channels/whatsapp/src/types.ts
• Create packages/channels/whatsapp/src/SessionManager.ts
• Create packages/channels/whatsapp/src/WhatsAppAdapter.ts
• Create packages/channels/whatsapp/src/index.ts
• Create packages/channels/whatsapp/src/__tests__/WhatsAppAdapter.test.ts
• Commit and push to claude/issue-10-20260410-2206
• PR creation link provided below (gh pr create requires approval in this environment)

---

What was implemented

All tasks from issue #10 are complete in branch claude/issue-10-20260410-2206.

packages/channels/whatsapp/ — new package with 5 source files + test suite:

File	Implements
src/types.ts	WhatsAppConfig, WhatsAppAdapterOptions, WHATSAPP_CAPABILITIES, PendingCapture
src/SessionManager.ts	QR-code auth via useMultiFileAuthState, exponential-backoff reconnection (default 10 retries), graceful shutdown
src/WhatsAppAdapter.ts	Full ChannelAdapter implementation — inbound parsing, outbound dispatch, A2H method 1/2/3
src/index.ts	Public exports + JSDoc quick-start
src/__tests__/WhatsAppAdapter.test.ts	20+ conformance tests using a mock Baileys socket

A2H method selection:

• AUTHORIZE ≤3 options → method 1 (WhatsApp interactive buttons)
• AUTHORIZE >3 options → method 3 (external form link)
• COLLECT any → method 3 (external form link)
• Quoted-reply capture (PendingCapture map) → method 2 for free-text responses

Capabilities reported:

{ "threads": false, "buttons": true, "selectMenus": false,
  "replyMessages": true, "dms": true, "fileUpload": true }

Note: buildQuotedOptions returns undefined pending a makeInMemoryStore integration in the core — this is the documented extension point for store-backed quoted replies.

· Branch

[claude]

@claude Implement this issue.

• Base branch: meta/17
• Target your PR to meta/17
• Include fixes #10 in the PR body

[claude]

Claude finished @claude[bot]'s task in 16m 16s —— View job • claude/17-issue-10-20260410-2220 • Create PR ➔

---

Implementing WhatsApp Adapter (Baileys)

• Gather context: read CLAUDE.md, explore repo structure, and understand existing interfaces
• Implement packages/channels/whatsapp/ package
  • package.json with @whiskeysockets/baileys dependency
  • tsconfig.json
  • src/types.ts — ChannelCapabilities, A2H intent types, envelopes, config, MockableSocket
  • src/SessionManager.ts — QR auth flow, exponential-backoff reconnection, session persistence
  • src/WhatsAppAdapter.ts — full adapter implementation
  • src/index.ts — public exports with JSDoc quick-start
  • src/__tests__/WhatsAppAdapter.test.ts — 30+ tests with injected mock socket
• Commit and push changes
• Create PR targeting meta/17

---

What was implemented

packages/channels/whatsapp/ — new monorepo package with 6 source files and a full test suite:

File	Implements
src/types.ts	WhatsAppAdapterConfig, WhatsAppAdapterDeps, WHATSAPP_CAPABILITIES, all A2H intent types, MockableSocket
src/SessionManager.ts	QR-code auth via useMultiFileAuthState, exponential-backoff reconnection (configurable retries), graceful shutdown
src/WhatsAppAdapter.ts	Full ChannelAdapter implementation — initialize, shutdown, onMessage, send, sendA2H
src/index.ts	Public exports with JSDoc quick-start example
src/__tests__/WhatsAppAdapter.test.ts	30+ conformance tests using an injected mock socket

A2H method selection:

Intent	Options	Method
AUTHORIZE	≤ 3	Method 1 — WhatsApp interactive buttons
AUTHORIZE	> 3	Method 3 — external form link
COLLECT	any	Method 3 — external form link + method 2 quoted-reply capture
INFORM	—	Fire-and-forget text

Capabilities reported:

{ "threads": false, "buttons": true, "selectMenus": false,
  "replyMessages": true, "dms": true, "fileUpload": true }

Virtual threads: WhatsApp has no native threads. The adapter creates virtual threads by using the root message ID from quoted reply chains as the threadId.

· Branch