Skip to content

WhatsApp

OMD Cleo supports WhatsApp via a Node.js Baileys bridge. The Python agent does not connect to Meta directly; instead it communicates with the bridge over HTTP. This allows using a personal or business WhatsApp account without the official Meta Cloud API.

Architecture

User (WhatsApp)
    ↓
WhatsApp servers
    ↓
Baileys bridge (Node.js)  ←—→  Cleo agent (Python)
                               POST /api/whatsapp/webhook  (incoming)
                               POST {bridge}/send           (outgoing)

Setup

Add whatsapp to ENABLED_CLIENTS:

ENABLED_CLIENTS=whatsapp

Required environment variables:

Variable Description
WHATSAPP_BRIDGE_URL Base URL of the Baileys bridge (e.g. http://localhost:3001)

Optional:

Variable Description
WHATSAPP_WEBHOOK_SECRET If set, the bridge must send this value in X-Webhook-Secret; otherwise the webhook returns 403

Running the Baileys bridge

The bridge is located in omd-agents/whatsapp-bridge/. It is a Node.js service that:

  1. Connects to WhatsApp using Baileys (QR-code or pairing-code authentication).
  2. On each inbound message, POSTs to {CLEO_API_URL}/api/whatsapp/webhook.
  3. Exposes HTTP endpoints for the agent to call:
  4. GET /health — bridge health and connection status.
  5. POST /send — send a text message to a JID or phone number.
  6. POST /send-media — send a media message (image, document, etc.).

Webhook payload

Each inbound event from the bridge contains:

Field Description
from Sender JID or phone number (conversation ID)
messageId WhatsApp message ID
text Text body (if present)
media Optional { url, mimetype, filename, size } for attachments
timestamp Unix time in milliseconds
senderId Sender ID (defaults to from)

For tool confirmations, the bridge can send events with a reaction field and reactsToMessageId; the agent will call the tool confirmation handler.

Known limitations

  • No native thread/reply support — conversations are 1:1.
  • Editing or replacing a previously sent message is not supported.
  • Message history from the bridge is not available on startup.
  • Typing indicators are a no-op unless the bridge exposes them.

Switching to the Meta Cloud API

To migrate to the official WhatsApp Business Cloud API in the future, implement a WhatsAppCloudClient and set WHATSAPP_BACKEND=cloud with the appropriate Cloud API credentials. The whatsapp channel and all handlers remain unchanged; only the backend implementation changes.