Skip to content

Add WhatsApp adapter using Meta's WhatsApp Business Cloud#179

Closed
chitru wants to merge 1 commit intovercel:mainfrom
chitru:feat/add-whatsapp-adapter
Closed

Add WhatsApp adapter using Meta's WhatsApp Business Cloud#179
chitru wants to merge 1 commit intovercel:mainfrom
chitru:feat/add-whatsapp-adapter

Conversation

@chitru
Copy link

@chitru chitru commented Mar 4, 2026

Summary

Adds @chat-adapter/whatsapp — a WhatsApp adapter using Meta's official [WhatsApp Business Cloud API (https://developers.facebook.com/docs/whatsapp/cloud-api).
Serverless-compatible, zero external dependencies, follows the same patterns as the existing Telegram adapter.

Features

  • Webhook verification (GET handshake + X-Hub-Signature-256)
  • Send/receive text messages and media attachments
  • Interactive messages: reply buttons (≤3 actions) and list messages (>3 actions)
  • Add/remove emoji reactions
  • Cache-based message fetching with pagination
  • Error mapping to adapter-specific error types
  • Factory function with env var auto-detection

Limitations

  • No message editing (Cloud API limitation) — throws NotImplementedError
  • No message deletion (Cloud API limitation) — throws NotImplementedError
  • No typing indicator (Cloud API limitation) — no-op
  • No message history API — returns cached messages only

Environment Variables

Variable Required Description
WHATSAPP_ACCESS_TOKEN Yes Meta access token
WHATSAPP_PHONE_NUMBER_ID Yes Bot's phone number ID
WHATSAPP_VERIFY_TOKEN No Webhook verification secret
WHATSAPP_APP_SECRET No X-Hub-Signature-256 verification

Test plan

  • 24 unit tests pass (thread IDs, webhook verification, message parsing,
    posting, reactions, interactive messages, error mapping, pagination)
  • pnpm validate passes (knip, lint, typecheck, test, build)

   API                                                                         Adds @chat-adapter/whatsapp with support for:
   - Webhook verification (GET handshake + X-Hub-Signature-256)
   - Incoming text, media, reaction, and interactive messages
   - Outgoing text messages, reactions, and interactive messages
   (buttons/lists)
   - Thread ID format: whatsapp:{phoneNumberId}:{userPhoneNumber}
   - Cache-based message fetching (same pattern as Telegram adapter)
   - Error mapping to adapter-specific error types                             Limitations: edit/delete throw NotImplementedError, typing is a no-op.
@vercel
Copy link
Contributor

vercel bot commented Mar 4, 2026

@chitru is attempting to deploy a commit to the Vercel Labs Team on Vercel.

A member of the Team first needs to authorize it.

@haydenbleasel haydenbleasel self-requested a review March 6, 2026 23:39
@haydenbleasel
Copy link
Member

Hey @chitru amazing work - we have a PR open for this in #102 that's more comprehensive. You have some great things in here though like raw.voice vs raw.audio, configurable base url, etc. so I'm merging those into the other PR. Appreciate it!

haydenbleasel added a commit to ghellach/chat that referenced this pull request Mar 6, 2026
Bring over several enhancements from chitru's WhatsApp adapter PR (vercel#179):

- Voice message support (separate from audio)
- Legacy button response handling (template quick replies)
- Callback data encoding/decoding for interactive reply round-trips
- Message truncation at WhatsApp's 4096 char limit
- Example app integration (adapters, webhook route, package.json)
- GET webhook forwarding for WhatsApp verification challenges
- Package README and changeset
- Tests for all new functionality (68 total)

Co-Authored-By: Chitru Shrestha <chitra.shrestha@akuru.com.au>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cramforce pushed a commit to ghellach/chat that referenced this pull request Mar 8, 2026
Bring over several enhancements from chitru's WhatsApp adapter PR (vercel#179):

- Voice message support (separate from audio)
- Legacy button response handling (template quick replies)
- Callback data encoding/decoding for interactive reply round-trips
- Message truncation at WhatsApp's 4096 char limit
- Example app integration (adapters, webhook route, package.json)
- GET webhook forwarding for WhatsApp verification challenges
- Package README and changeset
- Tests for all new functionality (68 total)

Co-Authored-By: Chitru Shrestha <chitra.shrestha@akuru.com.au>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
cramforce pushed a commit to ghellach/chat that referenced this pull request Mar 8, 2026
Bring over several enhancements from chitru's WhatsApp adapter PR (vercel#179):

- Voice message support (separate from audio)
- Legacy button response handling (template quick replies)
- Callback data encoding/decoding for interactive reply round-trips
- Message truncation at WhatsApp's 4096 char limit
- Example app integration (adapters, webhook route, package.json)
- GET webhook forwarding for WhatsApp verification challenges
- Package README and changeset
- Tests for all new functionality (68 total)

Co-Authored-By: Chitru Shrestha <chitra.shrestha@akuru.com.au>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants