Why This Guide Exists

The API is the backbone of everything in MoltFlow.

Whether you're building a chatbot, integrating with your CRM, orchestrating AI agents, or just trying to send a WhatsApp message programmatically — it all flows through the REST API. This guide covers every endpoint you'll actually use, with working code examples and real response data.

No hand-waving. No "left as an exercise for the reader." Just complete, tested examples you can copy and run.

By the end, you'll know how to authenticate, manage sessions, send messages, monitor groups, set up webhooks, and leverage AI features. Let's dive in.

Authentication: Two Ways In

Before you can call any endpoint, you need to authenticate. MoltFlow supports two methods: JWT bearer tokens and API keys.

Method 1: JWT Bearer Token (For User Sessions)

JWT tokens are best when you're building a user-facing application where people log in with email/password.

Login request:

bash

curl -X POST https://apiv2.waiflow.app/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-secure-password"
  }'

Response:

json

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "token_type": "bearer",
  "expires_in": 3600
}

Now use that access_token in all subsequent requests:

bash

curl https://apiv2.waiflow.app/api/v2/sessions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token refresh: Tokens expire after 1 hour. Before they expire, refresh them:

bash

curl -X POST https://apiv2.waiflow.app/api/v2/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
  }'

You'll get a fresh access_token. Keep refreshing before expiry to maintain continuous authentication.

Method 2: API Key (For Server-to-Server)

API keys are better for backend services, automation scripts, and CI/CD pipelines. They don't expire (until you revoke them), and they're simpler to manage.

Generate an API key:

Go to your MoltFlow dashboard → Settings → API Keys → Create New Key. Select the scopes your integration needs (e.g., messages:send, sessions:read) — API keys require explicit permissions, so only grant what you actually use. Copy the key immediately — it's only shown once.

Usage:

bash

curl https://apiv2.waiflow.app/api/v2/sessions \
  -H "X-API-Key: molt_sk_1234567890abcdef"

That's it. No login flow, no token refresh, no expiry. Just add the X-API-Key header to every request.

Security note: Store API keys in environment variables or a secrets manager. Never commit them to git. Rotate them every 90 days.

Sessions: Your WhatsApp Connection

A session represents a WhatsApp connection. Think of it like logging into WhatsApp Web, but programmatically controlled via the API.

List All Sessions

bash

curl https://apiv2.waiflow.app/api/v2/sessions \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

[
  {
    "id": 42,
    "name": "support-team",
    "status": "working",
    "created_at": "2026-01-20T10:00:00Z",
    "updated_at": "2026-01-25T14:30:00Z"
  },
  {
    "id": 43,
    "name": "sales-bot",
    "status": "qr_code",
    "created_at": "2026-01-25T09:00:00Z",
    "updated_at": "2026-01-25T09:01:00Z"
  }
]

Create a Session

bash

curl -X POST https://apiv2.waiflow.app/api/v2/sessions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-new-session",
    "status": "starting"
  }'

Response:

json

{
  "id": 44,
  "name": "my-new-session",
  "status": "starting",
  "created_at": "2026-01-25T15:00:00Z"
}

The session will transition through: starting → qr_code → working. Watch the status via the next endpoint.

Get Session by Name

bash

curl https://apiv2.waiflow.app/api/v2/sessions/my-new-session \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "id": 44,
  "name": "my-new-session",
  "status": "qr_code",
  "created_at": "2026-01-25T15:00:00Z",
  "updated_at": "2026-01-25T15:00:15Z"
}

Delete a Session

When you're done with a session, clean it up:

bash

curl -X DELETE https://apiv2.waiflow.app/api/v2/sessions/my-new-session \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "message": "Session deleted successfully"
}

Real-Time Events (SSE)

Want to watch session events in real-time? Use Server-Sent Events:

bash

curl -N https://apiv2.waiflow.app/api/v2/sessions/my-new-session/events?token=YOUR_TOKEN

This keeps the connection open and streams events as they happen:

text

event: status
data: {"status": "qr_code"}

event: qr
data: {"qr": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."}

event: status
data: {"status": "working"}

Perfect for building dashboards or monitoring tools.

Messages: Send and Receive

This is why you're here. Sending and receiving WhatsApp messages programmatically.

Send a Text Message

bash

curl -X POST https://apiv2.waiflow.app/api/v2/sessions/support-team/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "[email protected]",
    "text": "Hello! Your order has shipped. Track it here: https://track.example.com/12345"
  }'

Response:

json

{
  "success": true,
  "result": {
    "key": {
      "id": "3EB0F2A4B5C6D7E8F9"
    },
    "timestamp": 1706195400
  }
}

Critical detail: The message ID is at result.key.id, not result.id. This trips people up constantly.

Understanding chatId Format

The chatId field determines where the message goes:

Type	Format	Example
Individual contact	`{phone}@c.us`	`[email protected]`
WhatsApp group	`{groupId}@g.us`	`[email protected]`

Phone number rules:

Must include country code
No spaces, dashes, or parentheses
US example: (650) 555-1234 becomes [email protected]

Send to a Group

Same endpoint, different chatId:

bash

curl -X POST https://apiv2.waiflow.app/api/v2/sessions/support-team/messages \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "[email protected]",
    "text": "Team update: We hit our Q1 target! Great work everyone."
  }'

You can get group IDs from the groups endpoint (covered next).

Code Examples: Python and Node.js

Python:

python

import requests

def send_whatsapp_message(session_name, chat_id, text, api_token):
    url = f"https://apiv2.waiflow.app/api/v2/sessions/{session_name}/messages"
    headers = {
        "Authorization": f"Bearer {api_token}",
        "Content-Type": "application/json"
    }
    payload = {
        "chatId": chat_id,
        "text": text
    }

    response = requests.post(url, json=payload, headers=headers)
    return response.json()

# Usage
result = send_whatsapp_message(
    session_name="support-team",
    chat_id="[email protected]",
    text="Hello from Python!",
    api_token="YOUR_TOKEN"
)
print(f"Message ID: {result['result']['key']['id']}")

Node.js:

javascript

const axios = require('axios');

async function sendWhatsAppMessage(sessionName, chatId, text, apiToken) {
  const url = `https://apiv2.waiflow.app/api/v2/sessions/${sessionName}/messages`;
  const headers = {
    'Authorization': `Bearer ${apiToken}`,
    'Content-Type': 'application/json'
  };
  const payload = { chatId, text };

  const response = await axios.post(url, payload, { headers });
  return response.data;
}

// Usage
(async () => {
  const result = await sendWhatsAppMessage(
    'support-team',
    '[email protected]',
    'Hello from Node.js!',
    'YOUR_TOKEN'
  );
  console.log(`Message ID: ${result.result.key.id}`);
})();

Groups: List and Monitor

Groups are powerful. You can list all groups your session has access to, and monitor specific groups for keywords.

List All Groups

bash

curl https://apiv2.waiflow.app/api/v2/sessions/support-team/groups \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

[
  {
    "id": "[email protected]",
    "name": "Customer Support Team",
    "participant_count": 12,
    "created_at": "2025-06-15T08:00:00Z"
  },
  {
    "id": "[email protected]",
    "name": "Sales Pipeline",
    "participant_count": 8,
    "created_at": "2025-11-20T14:30:00Z"
  }
]

These are all the WhatsApp groups the connected account is a member of.

Create a Monitored Group

Now here's where it gets interesting. You can configure MoltFlow to watch specific groups for keywords:

bash

curl -X POST https://apiv2.waiflow.app/api/v2/groups \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "wa_group_id": "[email protected]",
    "keywords": ["urgent", "help", "bug", "down"]
  }'

Response:

json

{
  "id": 5,
  "wa_group_id": "[email protected]",
  "keywords": ["urgent", "help", "bug", "down"],
  "created_at": "2026-01-25T15:30:00Z"
}

Now whenever someone says "urgent" or "help" in that group, MoltFlow will flag it. You'll receive these events via webhooks.

List Monitored Groups

bash

curl https://apiv2.waiflow.app/api/v2/groups \
  -H "Authorization: Bearer YOUR_TOKEN"

This returns all groups you're actively monitoring with keyword tracking.

The Difference: WhatsApp Groups vs Monitored Groups

WhatsApp groups (via /sessions/{name}/groups): All groups the account is a member of. Read-only list.
Monitored groups (via /groups): Groups you've configured MoltFlow to actively watch and analyze. You control these.

Webhooks: Get Notified About Events

Webhooks let MoltFlow push events to your server in real-time. No polling, no checking for updates — just instant notifications when things happen.

Create a Webhook

bash

curl -X POST https://apiv2.waiflow.app/api/v2/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/moltflow",
    "events": ["message", "session_status", "group_join"]
  }'

Response:

json

{
  "id": 7,
  "url": "https://your-server.com/webhooks/moltflow",
  "events": ["message", "session_status", "group_join"],
  "created_at": "2026-01-25T16:00:00Z"
}

Available Events

Event	When it fires
`message`	New message received (inbound only)
`session_status`	Session status changes (starting, qr_code, working, failed)
`group_join`	Someone joined a monitored group

Example Webhook Payload

When a message arrives, MoltFlow will POST to your webhook URL:

json

{
  "event": "message",
  "session": "support-team",
  "timestamp": "2026-01-25T16:05:00Z",
  "data": {
    "id": "3EB0F2A4B5C6D7E8F9",
    "from": "[email protected]",
    "body": "Hi, I need help with my order",
    "timestamp": 1706197500
  }
}

Your server should respond with a 200 status code to acknowledge receipt. If we don't get a 200, we'll retry the webhook (with exponential backoff).

List All Webhooks

bash

curl https://apiv2.waiflow.app/api/v2/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN"

This returns all webhooks you've configured, along with their delivery stats (success count, failure count, last delivered timestamp).

AI Features: Auto-Reply and Learn Mode

MoltFlow includes built-in AI capabilities for automating responses and training custom models on your conversation data.

Configure AI Auto-Reply

bash

curl -X POST https://apiv2.waiflow.app/api/v2/ai/auto-reply/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "session_name": "support-team",
    "prompt": "You are a helpful customer support assistant. Answer questions about our products and services. If you don't know something, ask the customer to contact human support.",
    "model": "gpt-4o-mini"
  }'

Now any messages received by the support-team session will trigger an AI-generated response based on your prompt.

Train Learn Mode

Learn Mode analyzes your past conversations to train a custom style model:

bash

curl -X POST https://apiv2.waiflow.app/api/v2/ai/learn-mode/train \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_name": "support-team",
    "message_count": 500
  }'

This kicks off a background training job. MoltFlow will analyze the most recent 500 messages from that session and train a model to mimic your writing style.

Note: AI features require credits. Check your plan limits in the dashboard.

For a deeper dive into AI capabilities, see our dedicated AI guides (coming soon).

Error Handling: Status Codes and Responses

When things go wrong, MoltFlow returns standard HTTP status codes with descriptive error messages.

Common Status Codes

Code	Meaning	What to do
200	Success	All good
400	Bad request	Check your request format
401	Unauthorized	Invalid/expired token or API key
403	Forbidden	Plan limit reached or permission denied
404	Not found	Session, group, or resource doesn't exist
429	Too many requests	Slow down, you hit the rate limit
500	Server error	Contact support (rare)

Error Response Format

json

{
  "detail": "Session 'invalid-session' not found",
  "error_code": "SESSION_NOT_FOUND",
  "status": 404
}

Always check the error_code field for programmatic error handling. Don't parse the detail message — it's human-readable and may change.

Rate Limit Headers

When you hit a rate limit, check these headers:

text

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706199600
Retry-After: 3600

X-RateLimit-Limit: Your total limit
X-RateLimit-Remaining: How many requests you have left
X-RateLimit-Reset: Unix timestamp when the limit resets
Retry-After: Seconds until you can retry

What's Next?

You now have a complete reference for the MoltFlow API:

Authentication (JWT and API keys)
Session management (create, list, delete, monitor)
Messaging (send text to individuals and groups)
Group operations (list groups, monitor with keywords)
Webhooks (real-time event notifications)
AI features (auto-reply and Learn Mode)
Error handling (status codes and rate limits)

Where to go from here:

Quick start guides:

REST API Quick Start — 5-minute integration guide
Connect Your WhatsApp Account — Step-by-step session setup
Send Your First Message — Examples in Python, Node.js, cURL
Set Up Webhooks — Real-time event notifications

Advanced features:

Build a Knowledge Base AI — Add RAG to your bot
Connect MoltFlow to n8n — Visual workflow automation
AI Auto-Replies Setup — Configure intelligent responses
WhatsApp BSUID Migration Guide — Prepare for June 2026 changes

Ready to build? Start your free trial — 1,000 messages included, no credit card required. Official WAHA integration means enterprise reliability from day one.