WhatsApp Cloud API
Drop-in Convex component for the WhatsApp Cloud API — send & receive messages, track delivery, and manage conversations reactively
git clone https://github.com/david-potgieter/convex-whatsapp.git
cd convex-whatsappThis upstream package has not been adapted or qualified for Bijection. Read the original documentation before adopting it.
Description
Drop-in Convex component for the WhatsApp Cloud API — send & receive messages, track delivery, and manage conversations reactively
Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.
Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.
Getting started
- Get the source at the revision above and read its package documentation.
- Check the required Bijection SDK version, dependencies, and external service credentials.
- Follow the package setup instructions and the guide to using components.
- Exercise the component in your deployment according to your project’s verification rules.
Open source
Maintained source: david-potgieter/convex-whatsapp. License: See repository. Consult the repository for license terms, notices, and contributor attribution.
From the upstream publisher
Convex component for the WhatsApp Cloud API — send & receive messages, track delivery, and manage conversations reactively.
Explore the demo ↗Upstream overview
From the upstream package documentation.
A 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.
Use cases
From the upstream package documentation.
- Build customer support chat systems with automated responses and human handoff workflows
- Create notification systems that send order updates, appointment reminders, or shipping alerts via WhatsApp
- Implement two-way messaging for booking confirmations, survey collection, or feedback gathering
- Add WhatsApp integration to existing Convex apps without managing webhook infrastructure
- Track message delivery status and conversation state reactively in your database
How it works
From the upstream package documentation.
The component integrates with WhatsApp Cloud API through Convex actions that handle outbound messaging and webhook processing for inbound messages. It stores conversation data and message history in your Convex database, making all WhatsApp interactions queryable through standard Convex queries.
Incoming messages trigger Convex functions that can process content, update conversation state, and trigger automated responses. The reactive nature of Convex ensures your UI stays synchronized with message status changes and new incoming messages without additional polling or websocket management.
Setup involves configuring your WhatsApp Business API credentials and webhook endpoints through the component's configuration system. The component handles API authentication, rate limiting, and error handling while exposing clean Convex function interfaces for sending messages and querying conversation data.
Upstream package FAQ
Does convex-whatsapp handle message retry logic?
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.
What WhatsApp message types are supported?
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.
How do I handle inbound WhatsApp messages?
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.
Does this component work with WhatsApp Business API?
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.
Use with agents and CLI
Give your coding agent the component’s source identity and setup guidance.
Help me integrate WhatsApp Cloud API with Bijection.
Read: https://bijection.com/components/convex-whatsapp/SKILL.md
Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.Read upstream package documentation ↗