Drop-in Convex component for WhatsApp Cloud API that handles message sending, receiving, delivery tracking, and conversation threading with reactive queries.
npm install convex-whatsappA Convex component that wraps the WhatsApp Cloud API to enable messaging functionality within your Convex application. It provides reactive message handling, delivery tracking, and conversation management through Convex functions and database integration. The component eliminates the need to manually handle WhatsApp webhook integrations and API authentication.
The convex-whatsapp component provides a send() action that calls the WhatsApp Cloud API directly from your Convex functions. It supports text, template, media, and interactive button messages with automatic phone number normalization and error handling.
This component automatically handles WhatsApp webhook verification and ingestion, storing all inbound messages in Convex tables. You can register callback functions that get scheduled whenever new messages arrive, with full Meta signature verification built-in.
The component automatically updates message status from queued to sent, delivered, read, or failed based on Meta webhook notifications. All status changes are stored in Convex tables and can be queried reactively in your UI.
Messages are automatically threaded into conversations by phone number with unread counts and last-message previews. The component provides queries to list conversations, get message history, and mark conversations as read.
The convex-whatsapp component intentionally does not include retry logic. Failed messages are stored with status 'failed' and the component throws typed errors with Meta's error codes. For retries, the docs recommend using @convex-dev/workflow to build durable retry workflows with proper backoff handling.
The convex-whatsapp component supports text messages, template messages (HSM), media messages (image, document, audio, video), and interactive messages (buttons and lists). All message types work through the same send() action with type-safe parameters.
Register an inbound message handler using registerInboundHandler() with a Convex function handle. The convex-whatsapp component will automatically schedule your function whenever new messages arrive, passing the stored message ID for processing.
Yes, the convex-whatsapp component integrates with the WhatsApp Cloud API from Meta (formerly Facebook). It requires a WhatsApp Business Account, phone number ID, and access token from Meta Business Manager to send and receive messages.