Skip to main content

How to Manage Multiple WhatsApp Sessions

Advancedadvanced10 minutes9 min read

Run multiple WhatsApp numbers from a single MoltFlow dashboard. Learn session creation, health monitoring, and strategies for multi-number automation.

What You'll Need

Before managing multiple WhatsApp sessions, ensure you have:

  • MoltFlow Pro or Business plan — Starter plan is limited to 1 session. Pro supports up to 3 sessions, Business supports up to 10 sessions.
  • Multiple WhatsApp numbers — Each session requires a separate phone number with WhatsApp installed. You cannot connect the same phone number to multiple sessions.
  • Separate devices or WAHA instances — Each WhatsApp number must be registered on a separate phone or emulated device (via WAHA).

Multi-session management is essential for businesses that operate multiple WhatsApp numbers for different departments, regions, or brands. This guide covers setup, monitoring, and best practices.

Step 1: Plan Your Multi-Session Strategy

Before creating sessions, plan your multi-session architecture. Common patterns include:

Pattern 1: Department-based sessions

  • Sales: +1-555-0100
  • Support: +1-555-0200
  • Marketing: +1-555-0300

Each department gets its own WhatsApp number. Benefits: clear separation of concerns, team members only access relevant sessions, easier to track department-specific metrics.

Pattern 2: Region-based sessions

  • US: +1-555-0100
  • EU: +44-20-1234-5678
  • APAC: +65-6123-4567

Each region gets its own WhatsApp number with a local country code. Benefits: better customer experience (local numbers inspire trust), easier to comply with regional regulations (GDPR, CCPA), time-zone-aligned response times.

Pattern 3: Brand-based sessions

  • Brand A: +1-555-0100
  • Brand B: +1-555-0200
  • Agency Client 1: +1-555-0300

If you manage multiple brands or clients, each gets its own WhatsApp number. Benefits: keeps customer communications separate, prevents cross-brand confusion, easier to hand off clients to other teams.

Pattern 4: Personal + Business

  • Personal: +1-555-0100
  • Business: +1-555-0200

Entrepreneurs often separate personal WhatsApp from business WhatsApp. Benefits: maintain work-life balance, professional image on business number, avoid accidental message sends.

Key considerations:

  • Session limits: Check your plan tier. Pro = 3 sessions, Business = 10 sessions. Contact sales if you need more.
  • Independence: Each session is completely independent — separate message queues, separate labels, separate contacts, separate AI configurations.
  • Phone requirements: Each WhatsApp number must be registered on a separate phone. You can use physical phones or WAHA's multi-device emulation.

Step 2: Create and Connect Multiple Sessions

To create additional WhatsApp sessions:

  1. Navigate to Sessions in the MoltFlow dashboard
  2. Click "Create Session" in the top-right corner
  3. Enter a descriptive name (e.g., "Sales - US", "Support - EU", "Brand A")
  4. Click "Create"

The session is now created with status STOPPED. To connect it:

  1. Click the session name to open session details
  2. Click "Start Session"
  3. Status transitions: STOPPED → STARTING → SCAN_QR_CODE
  4. When status shows SCAN_QR_CODE, a QR code appears on screen
  5. Open WhatsApp on the target phone (the one you want to connect)
  6. Go to Settings > Linked Devices > Link a Device
  7. Scan the QR code displayed in MoltFlow
  8. Status transitions to WORKING once connected

Repeat this process for each WhatsApp number you want to connect. Each session gets its own QR code, and each QR code must be scanned on the corresponding phone.

Session naming best practices:

  • Use descriptive names that indicate purpose: "Sales - US", not "Session 1"
  • Include region or department if applicable
  • Keep names under 30 characters for dashboard display
  • Avoid special characters (use hyphens or underscores, not slashes or brackets)

Status meanings:

  • STOPPED (gray) — Session not running, no WhatsApp connection
  • STARTING (amber) — Session initialization in progress (usually 10-30 seconds)
  • SCAN_QR_CODE (blue) — Waiting for you to scan the QR code on your phone
  • WORKING (green) — Session connected and operational
  • FAILED (red) — Connection error, requires restart or troubleshooting

Step 3: Monitor Session Health from the Dashboard

The Sessions page shows real-time status for all your sessions. MoltFlow uses Server-Sent Events (SSE) to deliver status updates instantly — no polling needed.

Dashboard view:

  • Session name and ID
  • Status badge (color-coded: green = working, red = failed, blue = qr_code, etc.)
  • Last activity timestamp (when the session last sent or received a message)
  • Phone number (the WhatsApp number connected to this session)
  • Actions: Restart, Stop, Delete

Real-time updates: MoltFlow uses Redis PubSub to broadcast session status changes to your browser in real time. When a session status changes (e.g., from WORKING to FAILED), you see the update within 1-2 seconds — without refreshing the page.

Technical details: The frontend subscribes to SSE at GET /sessions/{id}/events?token=.... The backend publishes WAHA events to Redis, and the SSE endpoint streams them to connected clients. WAHA events are deduplicated via Redis leader election to prevent duplicate notifications.

Health monitoring checklist:

  • Daily: Check that all sessions show WORKING status
  • Weekly: Review "Last Activity" timestamps (sessions with no activity may indicate a disconnected phone)
  • Monthly: Audit session usage metrics (Messages sent/received per session)

Alerting (available on Business plan):

  • Configure webhook notifications for session status changes
  • Receive alerts when a session transitions to FAILED or STOPPED
  • Example webhook payload: {"event": "session.status", "session_id": "abc123", "status": "FAILED"}

Step 4: Route Messages to the Right Session

When sending messages via API or dashboard, you must specify which session to use. Each session has a unique session_id.

Sending via dashboard:

  1. Navigate to Messages or Bulk Send
  2. Select the active session from the session dropdown (top-right corner)
  3. Compose and send your message

The selected session determines which WhatsApp number the message is sent from.

Sending via API: Include the session_id parameter in your API request:

bash
curl -X POST https://apiv2.waiflow.app/messages/send \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "abc123",
    "to": "15551234567",
    "message": "Hello from our Sales team!"
  }'

The session_id tells MoltFlow which WhatsApp number to send from. If you omit session_id, the API returns a 400 error.

Finding session IDs:

  • Dashboard: Click on a session to see its ID in the URL (/sessions/abc123)
  • API: GET /sessions returns a list of all sessions with their IDs
bash
curl -X GET https://apiv2.waiflow.app/sessions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

json
[
  {
    "id": "abc123",
    "name": "Sales - US",
    "status": "WORKING",
    "phone_number": "+15551234567"
  },
  {
    "id": "def456",
    "name": "Support - EU",
    "status": "WORKING",
    "phone_number": "+442012345678"
  }
]

Bulk sends: When sending to a custom group or bulk list, specify the session_id in the bulk send request. All recipients will receive the message from that WhatsApp number.

Incoming messages: MoltFlow automatically associates incoming messages with the correct session based on which WhatsApp number received the message. You don't need to route inbound messages — it's handled automatically.

Step 5: Handle Session Failures and Recovery

Sessions can fail for several reasons:

Common failure causes:

  • Phone disconnected: The phone running WhatsApp lost internet connection
  • WhatsApp update: WhatsApp released an update that broke the WAHA integration (rare, but happens)
  • QR expired: The QR code scan failed or took too long, requiring re-scan
  • Network issues: Transient network errors between WAHA and WhatsApp servers
  • Account ban: WhatsApp banned the number for violating terms of service (spamming, etc.)

Recovery steps:

1. Automatic restart (transient failures): MoltFlow automatically retries failed sessions for up to 3 attempts. If the failure is transient (e.g., network hiccup), the session recovers automatically within 1-2 minutes.

2. Manual restart (persistent failures): If status shows FAILED for more than 5 minutes:

  1. Click the session name to open details
  2. Click "Restart"
  3. Wait 30 seconds for status to update
  4. If status changes to WORKING, recovery succeeded
  5. If status changes to SCAN_QR_CODE, you need to re-scan the QR code

3. QR re-scan (connection lost): If restart shows SCAN_QR_CODE:

  1. Open WhatsApp on the phone
  2. Go to Settings > Linked Devices
  3. Check if MoltFlow is still listed
  4. If listed: Click "MoltFlow" → Click "Unlink" → Rescan QR code in dashboard
  5. If not listed: Scan the new QR code directly

4. Account recovery (WhatsApp ban): If you suspect the account was banned:

  1. Try logging into WhatsApp on the phone directly
  2. If you see a ban message, appeal to WhatsApp (Settings > Help > Contact Us)
  3. MoltFlow cannot bypass WhatsApp bans — you must resolve with WhatsApp support
  4. Once unbanned, restart the session and re-scan QR code

Preventing failures:

  • Keep phones charged and connected: Ensure the phone running WhatsApp has reliable power and internet
  • Avoid spamming: Follow WhatsApp's terms of service (no unsolicited bulk messages)
  • Monitor proactively: Check session health daily, address issues before they escalate
  • Use anti-spam rules: Configure MoltFlow's anti-spam rules to prevent accidental violation of WhatsApp policies

When to delete and recreate: If a session has been FAILED for more than 24 hours despite multiple restart attempts, it may be corrupted. In this case:

  1. Stop the session
  2. Delete the session
  3. Create a new session with the same name
  4. Connect the same WhatsApp number via QR scan

This gives you a fresh session with clean state. Your historical messages are preserved (they're stored separately from the session state).

Troubleshooting

Session stuck in "starting":

  • Wait 30 seconds — session initialization takes time
  • If still stuck after 1 minute, click Restart
  • If restart doesn't help, check WAHA container logs (Business plan customers can request logs from support)

QR code expired:

  • QR codes expire after 60 seconds
  • Click "Refresh QR Code" to generate a new one
  • Scan within 60 seconds to avoid re-expiration

Can't create more sessions:

  • Check your plan limit: Starter = 1, Pro = 3, Business = 10
  • Upgrade your plan if you need more sessions
  • Delete unused sessions to free up slots

Messages going to wrong session:

  • Verify session_id in API calls (check request payload)
  • In dashboard, check which session is selected in the dropdown
  • If session ID is correct but still wrong, contact support (may be a routing bug)

Session shows "WORKING" but messages aren't sending:

  • Check the phone — is WhatsApp open and connected?
  • Check message queue (Messages > Queue) — are messages stuck?
  • Try sending a test message from WhatsApp directly on the phone
  • If phone sends but MoltFlow doesn't, restart the session

What's Next?

Now that you're managing multiple sessions, explore these related guides:

Need help? Contact support at [email protected] or visit our documentation.

Ready to automate your WhatsApp?

Start for free — set up in under 2 minutes.

Get Started Freeor explore more guides →