---
name: bijection-convex-whatsapp
description: "Evaluate and integrate the WhatsApp Cloud API component with Bijection."
---

# WhatsApp Cloud API

Drop-in Convex component for the WhatsApp Cloud API — send & receive messages, track delivery, and manage conversations reactively

This is an upstream package. It has not been adapted or qualified for Bijection.

- Package: convex-whatsapp
- Source: https://github.com/david-potgieter/convex-whatsapp
- npm: https://www.npmjs.com/package/convex-whatsapp
- Directory: https://bijection.com/components/convex-whatsapp

Read the upstream README for setup, license, and compatibility before using it.

## Integration workflow

1. Read the source README and package manifest at the recorded revision.
2. Confirm the required SDK, dependency availability, and runtime compatibility.
3. Follow the component's documented setup and configuration. Never invent an npm install command from a catalog package name.
4. Keep credentials in the project's existing secret store.
5. Follow the project's execution rules for verification and report what was actually checked.

## Original upstream skill

The following guidance describes convex-whatsapp. Its installation commands and APIs refer to the upstream package. Evaluate compatibility with the Bijection source separately.


# WhatsApp

## Instructions

Use WhatsApp to drop-in convex component for whatsapp cloud api that handles message sending, receiving, delivery tracking, and conversation threading with reactive queries. This Convex component integrates directly with your backend.

### Installation

```bash
npm install convex-whatsapp
```

### Capabilities

- Send and receive WhatsApp messages with automatic delivery status tracking from Meta webhooks
- Store all conversations in Convex tables with reactive queries and unread count management
- Handle inbound messages with signature verification and automatic callback scheduling
- Sync and manage WhatsApp message templates with real-time status updates

## Examples

### how to send WhatsApp messages from Convex backend

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.

### WhatsApp webhook integration with Convex

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.

### track WhatsApp message delivery status in real time

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.

### manage WhatsApp conversations with unread counts

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.

## When NOT to use

- When a simpler built-in solution exists for your specific use case
- If you are not using Convex as your backend
- When the functionality provided by WhatsApp is not needed

## Troubleshooting

**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.

## Resources

- [npm package](https://www.npmjs.com/package/convex-whatsapp)
- [GitHub repository](https://github.com/david-potgieter/convex-whatsapp)
- [Live demo](https://github.com/david-potgieter/convex-whatsapp/tree/main/example)
- [Convex Components Directory](https://www.convex.dev/components/convex-whatsapp)
- [Convex documentation](https://docs.convex.dev)