WhatsApp REST API Quick Start - MoltFlow Developer Guide

MoltFlow's REST API gives you programmatic control over WhatsApp messaging for 2 billion users. Here's what developers are building: CRM integrations, support ticket automation, order status bots, lead capture pipelines, and scheduled campaigns.

Full REST API access on every plan. No API-gated pricing tiers like competitors. The WhatsApp REST API lets you programmatically control WhatsApp messaging API automation — send messages, manage sessions, configure AI, handle webhooks, and more. If you're building integrations, scripts, or custom workflows, the messaging API is your starting point.

This guide gets you from zero to your first API automation call in under 5 minutes.

What You'll Need

Before starting, make sure you have:

• A MoltFlow account — Any plan works. Sign up here if you haven't already.
• A terminal or API client — We'll use curl for examples, but you can use Postman, Insomnia, or any HTTP client.
• 5 minutes — That's genuinely all it takes.

No backend server required for testing — you can make API calls directly from your terminal.

API Overview

Here's what you need to know about the WhatsApp REST API:

• Base URL: https://apiv2.waiflow.app/api/v2
• Format: JSON requests and responses
• Authentication: API key (via X-API-Key header) or JWT token (via Authorization: Bearer header) for the messaging API
• Rate limits: Vary by plan (Free: 100 requests/hour, Growth: 1000/hour, Business: 10,000/hour)
• Documentation: Full interactive docs at https://apiv2.waiflow.app/docs (FastAPI auto-generated Swagger UI)

All WhatsApp REST API endpoints return JSON. Errors follow a consistent format with HTTP status codes (400 = bad request, 401 = unauthorized, 404 = not found, 422 = validation error).

Step 1: Create an API Key

API keys let you authenticate without needing to log in or manage JWT tokens. Perfect for scripts, integrations, and API automation.

Generate the Key

1. Log in to your MoltFlow dashboard
2. Go to Settings (left sidebar)
3. Click API Keys
4. Click "Create Key"
5. Enter a descriptive label:
   • "n8n Integration" if you're connecting to n8n
   • "Python Script" if you're writing a script
   • "Mobile App" if you're building an app
6. Select scopes — choose only the permissions this key needs (e.g., messages:send, sessions:read). Use a preset like "Messaging" or "Outreach", or pick individual scopes under "Custom"
7. Click Create

MoltFlow will show you the API key once. It looks like:

mf_1234567890abcdefghijklmnopqrstuvwxyz

Copy it immediately and store it securely:

• Environment variable: MOLTFLOW_API_KEY=mf_...
• Secrets manager (AWS Secrets Manager, 1Password, etc.)
• NEVER commit it to Git — add .env to .gitignore

If you lose the key, you'll need to delete it and create a new one. There's no way to view it again after creation.

Security Note

Treat API keys like passwords. Anyone with your key can:

• Send WhatsApp messages from your account
• Access your contact lists and messages
• Configure webhooks and automation

If a key is compromised, delete it immediately in the dashboard. All requests using that key will fail with 401 errors.

Step 2: Make Your First Request

Let's verify your API key works by making a simple authenticated request.

Test Authentication

Open a terminal and run:

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

Replace YOUR_API_KEY with the key you just created.

Expected response:

[
  {
    "id": "abc123",
    "name": "My WhatsApp Session",
    "status": "working",
    "phone_number": "1234567890",
    "created_at": "2026-02-10T08:00:00Z"
  }
]

If you see this, authentication is working! You just made your first API call.

Common Errors

401 Unauthorized

{
  "detail": "Invalid API key"
}

Cause: API key is wrong, has extra whitespace, or was deleted.

Solution: Copy the key again carefully. Check for trailing spaces. Make sure it starts with mf_.

404 Not Found

{
  "detail": "Not Found"
}

Cause: URL is wrong (typo, missing /api/v2 prefix).

Solution: Verify the full URL: https://apiv2.waiflow.app/api/v2/sessions

Step 3: List Your WhatsApp Sessions

Sessions are your connected WhatsApp accounts. Each session represents one WhatsApp number linked to MoltFlow.

Get All Sessions

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

Response fields:

• id — Unique session identifier (use this in other API calls)
• name — Display name you gave it
• status — Current status: working (green), stopped (gray), failed (red), qr_code (orange)
• phone_number — WhatsApp phone number (if connected)
• created_at — When the session was created

Get a Specific Session

If you know the session ID, fetch details:

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

Replace abc123 with your session ID.

Why this matters: You need the session ID to send messages, configure AI, or manage contacts. Save it in your script or config file.

Step 4: Send a Message

Now let's send an actual WhatsApp message via the API.

Send a Text Message

curl -X POST https://apiv2.waiflow.app/api/v2/messages/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "abc123",
    "phone": "1234567890",
    "message": "Hello from the MoltFlow API! This is a test message."
  }'

Request fields:

• session_id — Your session ID (from Step 3)
• phone — Recipient's phone number (country code + number, no + or spaces)
  • Good: 15551234567 (US number)
  • Bad: +1 (555) 123-4567 (formatting not allowed)
• message — The text to send (max 4096 characters)

Response:

{
  "success": true,
  "result": {
    "key": {
      "id": "wamid.xyz789ABC",
      "remoteJid": "[email protected]"
    }
  }
}

The result.key.id is the WhatsApp message ID. Save it if you need to track delivery status or replies.

Check Your Phone

The message should arrive on the recipient's phone within 1-3 seconds. If it doesn't:

• Verify the phone number format (no +, no spaces, no parentheses)
• Check that the session status is working (not stopped or failed)
• Verify the session ID is correct

Send a Message with Media

You can also send images, documents, audio, and video:

curl -X POST https://apiv2.waiflow.app/api/v2/messages/send \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "abc123",
    "phone": "1234567890",
    "message": "Check out this image!",
    "media_url": "https://example.com/image.jpg"
  }'

Supported media types: JPG, PNG, GIF (images), PDF, DOCX (documents), MP3, M4A (audio), MP4 (video).

Step 5: Explore Core Endpoints

Here's a quick reference of the most useful API endpoints. For full details, visit the interactive docs at https://apiv2.waiflow.app/docs.

Sessions

Messages

Webhooks

Custom Groups (Contact Management)

Scheduled Messages

AI & Knowledge Base

Authentication Methods

MoltFlow supports two authentication methods:

1. API Key (Recommended for Scripts)

Use the X-API-Key header:

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

Pros:

• Simple — just one header
• No expiration (until you delete the key)
• Perfect for scripts, integrations, cron jobs

Cons:

• If compromised, attacker has full access (until you delete the key)

2. JWT Token (For Browser/App Sessions)

Use the Authorization: Bearer header:

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

Pros:

• Auto-expires after 15 minutes (more secure)
• Auto-refreshed by the frontend (no manual management)

Cons:

• More complex to manage in scripts (need to implement refresh flow)

When to use JWT: If you're building a web app or mobile app that already uses login sessions, use JWT. It's automatically managed by the MoltFlow frontend SDK.

When to use API keys: If you're writing a Python script, Node.js service, or n8n workflow, use API keys. Much simpler.

Error Handling

All API errors follow this structure:

{
  "detail": "Error message here"
}

Common HTTP Status Codes

Validation Errors (422)

When a request fails validation, you get detailed error info:

{
  "detail": [
    {
      "loc": ["body", "phone"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

This tells you exactly which field is missing or invalid. In this example, the phone field is required but wasn't provided.

Rate Limiting (429)

If you hit your plan's rate limit, you'll see:

{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}

Solution: Implement exponential backoff in your script. Wait 60 seconds and retry.

What's Next?

Now that you've made your first WhatsApp REST API calls, explore these advanced messaging API features:

• Send Your First Message — Get started with basic WhatsApp automation
• Send Bulk Messages — Send messages to thousands of contacts at scale via the messaging API
• Set Up Webhooks — Receive real-time events instead of polling the WhatsApp REST API
• Build AI Knowledge Base — Upload documents programmatically via the API automation

The full WhatsApp REST API reference is available at https://apiv2.waiflow.app/docs — interactive Swagger UI where you can test every messaging API endpoint directly in your browser.

Developers love MoltFlow's API. See the full reference docs.

Need help? Contact support via the dashboard chat or email us at [email protected]. We typically respond within 2-4 hours.