MoltFlow -- WhatsApp Business automation for teams. Connect, monitor, and automate WhatsApp at scale. Due to high demand and a recent registration issue, we're offering our top-tier Business plan with unlimited quotas for just $19.90/month on yearly billing — for a limited time only. Claim the deal Free tier available. Sign up

MoltFlow Core API

Manage WhatsApp sessions, send messages, monitor groups, organize with labels, and receive real-time events via webhooks.

Real-World Scenarios

Dental clinic — "Send an appointment confirmation to each patient after they book, and a reminder 24 hours before their visit."

Property manager — "Monitor my tenant WhatsApp groups for maintenance keywords like 'leak', 'broken', and 'urgent', and flag them instantly."

E-commerce store — "When a customer messages my support number, auto-label them as 'New Inquiry' and route the chat to the right team."

Logistics company — "Set up a webhook so my dispatch system gets notified the moment a driver sends a delivery confirmation photo."

When to Use

• "Connect WhatsApp" or "create a session"
• "Send a WhatsApp message" or "send text to contact"
• "Monitor a WhatsApp group" or "list groups"
• "Label contacts" or "sync labels from WhatsApp"
• "Set up a webhook" or "listen for WhatsApp events"
• "Get QR code" or "start session"
• "List chats" or "get conversations"

Prerequisites

1. MOLTFLOW_API_KEY -- Generate from the MoltFlow Dashboard under Settings > API Keys
2. All requests require authentication via

   Authorization: Bearer <token>

   or

   X-API-Key: <key>

3. Base URL:

   https://apiv2.waiflow.app/api/v2

Required API Key Scopes

sessions

read/manage

messages

read/send

groups

read/manage

labels

read/manage

webhooks

read/manage

Authentication

Every request must include one of:

Authorization: Bearer <jwt_token>

or

X-API-Key: <your_api_key>

Sessions

Manage WhatsApp connections. Each session represents one WhatsApp account linked via QR code.

/sessions

/sessions

/sessions/{id}

/sessions/{id}

/sessions/{id}/start

/sessions/{id}/stop

/sessions/{id}/restart

/sessions/{id}/logout

/sessions/{id}/qr

/sessions/{id}/events

Session Status Values

Sessions progress through these states:

stopped

starting

qr_code

working

failed

Create Session

POST

/sessions

{
  "name": "My WhatsApp"
}

Response

201 Created

{
  "id": "a1b2c3d4-...",
  "name": "My WhatsApp",
  "status": "stopped",
  "phone_number": null,
  "is_business": false,
  "created_at": "2026-02-11T10:00:00Z"
}

Start Session and Get QR

After creating a session, start it and retrieve the QR code:

1. POST /sessions/{id}/start

   -- begins the WAHA engine
2. Wait for status to become

   qr_code

   (use SSE events or poll)

3. GET /sessions/{id}/qr

   -- returns the QR code image

SSE Events

GET /sessions/{id}/events?token=<jwt>

Session Settings

PATCH

/sessions/{id}/settings

Configure per-session behavior. Settings are stored in the session's

config

// Request
{
  "auto_transcribe": true
}

// Response
{
  "status": "ok",
  "config": {
    "auto_transcribe": true
  }
}

auto_transcribe

Messages

Send and retrieve WhatsApp messages through connected sessions.

/messages/send

/messages/send/poll

/messages/send/sticker

/messages/send/gif

/messages/chats/{session_id}

/messages/chat/{session_id}/{chat_id}

/messages/{message_id}

Send Text Message

POST

/messages/send

{
  "session_id": "a1b2c3d4-...",
  "chat_id": "5511999999999@c.us",
  "message": "Hello from MoltFlow!"
}

Response

201 Created

{
  "id": "msg-uuid-...",
  "chat_id": "chat-uuid-...",
  "wa_message_id": "ABCD1234",
  "direction": "outbound",
  "message_type": "text",
  "content_preview": "Hello from MoltFlow!",
  "status": "sent",
  "sent_at": "2026-02-11T10:05:00Z",
  "created_at": "2026-02-11T10:05:00Z"
}

Chat ID Format

• Individual contacts:

  <phone>@c.us

  (e.g.,

  5511999999999@c.us

  )
• Groups:

  <group_id>@g.us

  (e.g.,

  120363012345678901@g.us

  )

Send Poll

POST

/messages/send/poll

{
  "session_id": "a1b2c3d4-...",
  "chat_id": "5511999999999@c.us",
  "title": "Preferred meeting time?",
  "options": ["Morning", "Afternoon", "Evening"],
  "allow_multiple": false
}

Groups

Monitor WhatsApp groups for keywords, messages, and activity.

/groups

/groups/available/{session_id}

/groups

/groups/{id}

/groups/{id}

/groups/{id}

/groups/create

/groups/{wa_group_id}/participants/add

/groups/{wa_group_id}/participants/remove

/groups/{wa_group_id}/admin/promote

/groups/{wa_group_id}/admin/demote

Add Group to Monitoring

POST

/groups

{
  "session_id": "a1b2c3d4-...",
  "wa_group_id": "120363012345678901@g.us",
  "monitor_mode": "keywords",
  "monitor_keywords": ["urgent", "support", "help"]
}

Monitor Modes

• all

  -- Capture every message in the group

• keywords

  -- Only capture messages matching specified keywords

• mentions

  -- Only when your account is mentioned

• first_message

  -- Only first messages from new users (default for new groups)

• ai_analysis

  -- AI-powered intent classification and lead scoring (Pro+ only)

Group Messages (AI Intelligence)

GET

/groups/{group_id}/messages

Retrieve paginated messages from a monitored group, including AI analysis results.

Query parameters:

limit

offset

Requires scope:

groups:read

{
  "items": [
    {
      "id": "msg-uuid",
      "sender_phone": "+15550123456",
      "sender_name": "John D.",
      "content_preview": "I'm interested in the 3BR property",
      "wa_timestamp": "2026-02-20T14:30:00Z",
      "ai_analysis": {
        "intent": "buying_intent",
        "lead_score": 9,
        "confidence": 0.92,
        "reason": "Explicit interest in a specific property with buying signal"
      }
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

ai_analysis

MCP Tool: moltflow_get_group_messages

Retrieve messages from a monitored WhatsApp group via Claude or any MCP client.

Args:

• group_id

  (required): UUID of the monitored group

• limit

  (optional): Max messages 1-100 (default: 50)

• offset

  (optional): Skip count for pagination (default: 0)

• response_format

  (optional):

  "markdown"

  or

  "json"

Returns: Paginated list of messages with sender info, content preview, timestamp, and

ai_analysis

Requires scope:

groups:read

Labels

Organize contacts and chats with color-coded labels. Supports sync with WhatsApp Business native labels.

/labels

/labels

/labels/{id}

/labels/{id}

/labels/{id}

/labels/{id}/sync

/labels/sync-from-whatsapp

/labels/business-check

/labels/{id}/chats

/labels/chat/{chat_id}

/labels/chat/{chat_id}

Create Label

POST

/labels

{
  "name": "VIP Customer",
  "color": "#FF6B35",
  "description": "High-value accounts"
}

Response

201 Created

{
  "id": "label-uuid-...",
  "name": "VIP Customer",
  "color": "#FF6B35",
  "description": "High-value accounts",
  "chat_count": 0,
  "synced": false,
  "created_at": "2026-02-11T10:00:00Z"
}

Note: Syncing labels to WhatsApp requires a WhatsApp Business account. Use

GET /labels/business-check

to verify.

Webhooks

Receive real-time notifications when events occur in your WhatsApp sessions.

/webhooks

/webhooks

/webhooks/{id}

/webhooks/{id}

/webhooks/{id}

/webhooks/{id}/test

Supported Events

message.received

message.sent

session.connected

session.disconnected

lead.detected

ai_analysis

group.message

group.message.analyzed

Create Webhook

POST

/webhooks

Security: Webhook URLs are validated server-side — private IPs, cloud metadata endpoints, and non-HTTPS schemes are blocked. Only configure endpoints you control. Always set a

secret

for HMAC signature verification.

{
  "name": "CRM Integration",
  "url": "https://example.com/webhooks/moltflow",
  "events": ["message.received", "lead.detected"],
  "secret": "whsec_mysecretkey123"
}

Response

201 Created

{
  "id": "wh-uuid-...",
  "name": "CRM Integration",
  "url": "https://example.com/webhooks/moltflow",
  "events": ["message.received", "lead.detected"],
  "is_active": true,
  "created_at": "2026-02-11T10:00:00Z"
}

Webhook Payload

Deliveries include an HMAC-SHA256 signature in the

X-Webhook-Signature

{
  "event": "message.received",
  "timestamp": "2026-02-11T10:05:00Z",
  "data": {
    "session_id": "a1b2c3d4-...",
    "chat_id": "5511999999999@c.us",
    "message": "Hello!",
    "direction": "inbound"
  }
}

Examples

Full workflow: Create session and send first message

# 1. Create a session
curl -X POST https://apiv2.waiflow.app/api/v2/sessions \
  -H "X-API-Key: $MOLTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales Team"}'

# 2. Start the session (triggers QR)
curl -X POST https://apiv2.waiflow.app/api/v2/sessions/{session_id}/start \
  -H "X-API-Key: $MOLTFLOW_API_KEY"

# 3. Get QR code (scan with WhatsApp)
curl https://apiv2.waiflow.app/api/v2/sessions/{session_id}/qr \
  -H "X-API-Key: $MOLTFLOW_API_KEY"

# 4. Send a message (after session status is "working")
curl -X POST https://apiv2.waiflow.app/api/v2/messages/send \
  -H "X-API-Key: $MOLTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "{session_id}",
    "chat_id": "5511999999999@c.us",
    "message": "Hello from MoltFlow!"
  }'

Set up a webhook for incoming messages

curl -X POST https://apiv2.waiflow.app/api/v2/webhooks \
  -H "X-API-Key: $MOLTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Incoming Messages",
    "url": "https://myapp.com/webhooks/whatsapp",
    "events": ["message.received", "session.connected"],
    "secret": "whsec_my_secret"
  }'

Monitor a group for keywords

# List available groups from a connected session
curl https://apiv2.waiflow.app/api/v2/groups/available/{session_id} \
  -H "X-API-Key: $MOLTFLOW_API_KEY"

# Add a group to monitoring
curl -X POST https://apiv2.waiflow.app/api/v2/groups \
  -H "X-API-Key: $MOLTFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "{session_id}",
    "wa_group_id": "120363012345678901@g.us",
    "monitor_mode": "keywords",
    "monitor_keywords": ["urgent", "support"]
  }'

Error Responses

All endpoints return standard error responses:

{
  "detail": "Session not found"
}

Rate Limits

API requests are rate-limited per tenant. Limits vary by plan:

Rate limit headers are included in every response:

X-RateLimit-Remaining

X-RateLimit-Reset

Related Skills

• moltflow-outreach -- Bulk Send, Scheduled Messages, Custom Groups
• moltflow-leads -- Lead detection, pipeline tracking, bulk operations, CSV/JSON export
• moltflow-ai -- AI-powered auto-replies, voice transcription, RAG knowledge base, style profiles
• moltflow-a2a -- Agent-to-Agent protocol, encrypted messaging, content policy
• moltflow-reviews -- Review collection and testimonial management
• moltflow-admin -- Platform administration, user management, plan configuration