Skip to main content

Send WhatsApp Messages via API (5-Minute Guide)

Corebeginner5 minutes8 min read

Send 1,000 messages in 10 minutes vs. 20 hours manual. API + dashboard methods. Typing delays, media, delivery tracking included.

Manual WhatsApp messaging doesn't scale. Send 1,000 personalized messages in 10 minutes vs. 20 hours of copy-pasting. WhatsApp API automation transforms customer support, sales outreach, and lead nurturing from labor-intensive tasks into one-click operations. This guide covers both dashboard and REST API methods so you can send messages manually today and automate them completely tomorrow.

What You'll Need

Before starting, make sure you have:

  • A connected WhatsApp session — If you haven't connected yet, follow the WhatsApp connection guide first. It takes 2 minutes.
  • Recipient phone number — In international format (country code + number, no plus sign or spaces). Example: 1234567890 for +1 (234) 567-0890.
  • API key (for API method) — Available in your dashboard under Settings → API Keys. The free plan includes API access.

Step 1: Ensure Your WhatsApp Session Is Connected

Before sending any messages, verify your WhatsApp session is active:

  1. Navigate to Sessions in the left sidebar
  2. Check that your session status shows "WORKING" with a green badge
  3. If the status is "STOPPED", "FAILED", or "SCAN_QR_CODE", you'll need to restart and reconnect the session

Why this matters: MoltFlow can only send messages through active sessions. If your session is disconnected, messages will fail immediately.

New to MoltFlow? Follow our 2-minute WhatsApp connection guide to get started with the official WAHA integration.

Step 2: Send a Message from the Dashboard

The dashboard UI is perfect for one-off messages or testing before you automate.

Using the Messages Interface

  1. Click Messages in the left sidebar
  2. In the top bar, select your WhatsApp session from the dropdown
  3. Click the "Send Message" button
  4. Fill in the form:
    • Recipient phone: Enter the phone number in international format (e.g., 1234567890)
    • Message: Type your message text (up to 4096 characters)
    • Typing delay (optional): Add 2-5 seconds to make delivery look natural
  5. Click Send

The message will appear in your chat list within seconds, showing the delivery status (sent, delivered, or read).

Dashboard Tips

  • Test with your own number first — Send a message to yourself to verify everything works
  • Save frequent contacts — The interface remembers recent recipients for quick access
  • Watch the status indicator — Single gray check (sent), double gray checks (delivered), double blue checks (read)

Step 3: Send a Message via the REST API

The WhatsApp automation API is how you'll scale to hundreds or thousands of messages. Here's the basic request:

bash
curl -X POST https://apiv2.waiflow.app/api/v2/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "YOUR_SESSION_ID",
    "phone": "1234567890",
    "message": "Hello from MoltFlow!"
  }'

Replace these values:

  • YOUR_API_TOKEN — Your JWT token from the dashboard (copy from Settings → API Keys)
  • YOUR_SESSION_ID — Your session ID (visible in the Sessions list)
  • 1234567890 — The recipient's phone number in international format

Understanding the Response

A successful request returns:

json
{
  "status": "success",
  "result": {
    "key": {
      "id": "3EB0ABC123DEF456",
      "remoteJid": "[email protected]"
    }
  }
}

The result.key.id value is the WhatsApp message ID. Save this if you want to track delivery status later.

Common API Errors

  • 401 Unauthorized — Your API token is invalid or expired. Generate a new one in the dashboard.
  • 404 Session not found — The session_id is wrong or the session was deleted.
  • 400 Invalid phone number — Phone format is incorrect. Use country code + number with no spaces or special characters.
  • 500 Session not connected — The session status isn't "WORKING". Reconnect it first.

Step 4: Add Typing Delays for Natural Delivery

Rapid-fire messages look bot-like and can trigger spam filters. Typing delays make your messages appear human-written.

How Typing Delays Work

When you add a typing delay, WhatsApp shows the "typing..." indicator to the recipient for the specified duration before the message appears. This mimics natural human behavior.

Adding a Typing Delay via API

Include the typing_delay parameter (in seconds):

bash
curl -X POST https://apiv2.waiflow.app/api/v2/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "YOUR_SESSION_ID",
    "phone": "1234567890",
    "message": "Hello! Thanks for reaching out. Let me check that for you.",
    "typing_delay": 3
  }'

Recommended Delays

  • Short messages (1-2 sentences): 2-4 seconds
  • Medium messages (3-5 sentences): 5-8 seconds
  • Long messages (6+ sentences): 10-15 seconds

Don't go above 20 seconds — recipients might think you've stopped typing.

Dashboard Typing Delays

The dashboard Send Message form has a "Typing delay" field. Enter the number of seconds and MoltFlow will show the typing indicator before sending.

Step 5: Verify Message Delivery

After sending a message, you'll want to confirm it was delivered and (optionally) read.

Checking Status in the Dashboard

  1. Go to Messages in the sidebar
  2. Find your message in the chat list
  3. Look at the checkmark indicators:
    • ✓ (single gray) — Message sent to WhatsApp's servers
    • ✓✓ (double gray) — Message delivered to recipient's phone
    • ✓✓ (double blue) — Message read by recipient

Checking Status via API

Use the message ID from the send response:

bash
curl -X GET https://apiv2.waiflow.app/api/v2/messages/{message_id} \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The response includes:

  • status — "sent", "delivered", or "read"
  • timestamp — When the message was sent
  • ack_timestamp — When it was delivered/read (if applicable)

Why Messages Fail

If a message shows "failed" status, common causes are:

  • Recipient has blocked your number
  • Recipient's phone is offline for 30+ days (WhatsApp discards the message)
  • Invalid phone number
  • Session disconnected mid-send (check session status)

Sending Media Messages

Beyond text, you can send images, documents, audio, and video.

Media via API

Add a media_url parameter pointing to a publicly accessible file:

bash
curl -X POST https://apiv2.waiflow.app/api/v2/messages/send \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "YOUR_SESSION_ID",
    "phone": "1234567890",
    "message": "Here is the document you requested.",
    "media_url": "https://example.com/document.pdf"
  }'

Supported Media Types

  • Images: JPG, PNG, WebP (max 16MB)
  • Documents: PDF, DOC, DOCX, XLS, XLSX (max 100MB)
  • Audio: MP3, OGG, M4A (max 16MB)
  • Video: MP4, AVI, MOV (max 64MB)

The media_url must be publicly accessible (no authentication required). MoltFlow downloads the file and sends it through WhatsApp.

Media Tips

  • Use captions — The message field becomes the caption when media is attached
  • Host files reliably — If the URL is unreachable, the send will fail
  • Compress large files — Smaller files send faster and use less mobile data for recipients

Troubleshooting

"Session not found" Error

Problem: The API returns 404 with "Session not found".

Solution: Double-check your session ID. Copy it directly from the Sessions page in the dashboard. Session IDs are UUIDs (e.g., 550e8400-e29b-41d4-a716-446655440000).

"Invalid phone number" Error

Problem: The API returns 400 with "Invalid phone number format".

Solution: Phone numbers must be in international format: country code + number with no spaces, dashes, parentheses, or plus sign. Examples:

  • Correct: 1234567890 (US)
  • Correct: 447700900123 (UK)
  • Wrong: +1-234-567-0890
  • Wrong: (234) 567-0890

Message Stuck on "Sent" (Not Delivered)

Problem: Message shows one checkmark but never gets two (delivered).

Solution: This usually means the recipient's phone is offline. WhatsApp will retry delivery for up to 30 days. If the phone comes online, the message will be delivered automatically. If 30 days pass, WhatsApp discards the message.

Session Disconnects After Sending

Problem: Messages send successfully, but then the session status changes to "FAILED".

Solution: WhatsApp may have flagged your account for unusual activity (e.g., sending too many messages too fast). This is WhatsApp's spam protection. Solutions:

  • Add typing delays to all messages (2-5 seconds)
  • Spread out bulk sends over hours, not minutes
  • Avoid identical message content to many recipients
  • Reconnect the session and reduce send frequency

Pro tip: MoltFlow's bulk messaging feature includes built-in anti-spam throttling (included on all paid plans). It has saved customers thousands in lost accounts by preventing bans before they happen.

What's Next?

Now that you can send individual WhatsApp messages via API, you're ready to:

All of these features are available now in your MoltFlow dashboard. Check the sidebar to explore.

Ready to automate at scale? Join 500+ businesses using MoltFlow for WhatsApp automation. Start your 14-day Growth trial — no credit card required.

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

Ready to automate your WhatsApp?

Start for free — set up in under 2 minutes.

Get Started Freeor explore more guides →