WhatsApp Channel and Chat API

This MIT-licensed project is a self-hosted HTTP API for developers who need to send WhatsApp channel posts or private messages from their own server. It uses Baileys to connect a WhatsApp account and exposes routes for channel discovery, role checks, recipient resolution, text, and media.

The problem

A send request can be retried by a client or interrupted after delivery. Media may also arrive with the wrong file type, and a channel account may lose its publishing role between lookup and sending. The API handles those cases at the server boundary.

Key features

• Discover channels subscribed to by the connected account.
• Resolve a channel from a supported selector and check its current role.
• Publish text and media only after confirming channel publishing rights.
• Resolve private recipients and send text or uploaded media.
• Generate image thumbnails and audio or video metadata when applicable.
• Require an Idempotency-Key for sends and replay a completed result on retry.
• Queue outbound sends with a bounded depth and an interval between sends.
• Expose health routes that report the WhatsApp connection state.

Technical architecture

Express receives the HTTP request and applies API key authentication, rate limits, upload checks, and validation before reaching controllers. Baileys owns the WhatsApp socket. Node.js native SQLite stores authentication state and a separate idempotency ledger in WAL mode. A process-local queue serializes outbound delivery. Multer handles uploads; file-type checks their signatures. sharp and media utilities prepare previews. Channel media follows a custom upload and relay path that sets the required media attributes.

Engineering highlights

• SQLite transactions claim and complete idempotency keys. Concurrent duplicates share an in-flight result; an uncertain crash outcome returns a conflict for manual verification.
• Channel sends recheck admin or owner rights inside the queue, immediately before delivery.
• API key comparison hashes both values and uses timingSafeEqual.
• Upload handling checks actual media signatures and limits temporary file access.
• The API uploads channel media itself and adds the mediatype attribute required by WhatsApp newsletters, so images, video, and voice notes post to channels correctly.