Organize Contacts with WhatsApp Labels

Sending the same message to everyone is lazy marketing. Hot leads need personalized follow-ups. Support tickets need urgency. VIP customers need special treatment. WhatsApp labels let you segment contacts—the difference between 5% and 25% conversion rates.

MoltFlow syncs labels bidirectionally with WhatsApp and lets you automate actions per label—something manual WhatsApp Business can't do. This guide shows you how to organize WhatsApp contacts, automate label assignment, and build targeted campaigns that convert.

What You'll Need

Before starting, make sure you have:

• A MoltFlow account with a connected WhatsApp session — Labels require an active session with status "working". See the "Connect Your WhatsApp Account" guide if you haven't set this up yet.
• A WhatsApp Business account — CRITICAL: Labels are only supported on WhatsApp Business accounts. Regular WhatsApp accounts cannot create or use custom labels. If you're using regular WhatsApp, you'll need to migrate to WhatsApp Business first.

You can check your account type in the MoltFlow dashboard under Sessions—look for the "Business" badge next to your session name.

Label automation (Growth+) — Auto-assign labels based on keywords and behavior. Starter plans support manual labels only; upgrade for smart segmentation.

Step 1: Understand WhatsApp Label Basics

WhatsApp Business allows you to create up to 20 custom labels per account. Each label has:

• Name — Up to 100 characters (e.g., "High Priority", "New Leads", "Support Tickets")
• Color — One of 20 predefined colors from WhatsApp's fixed palette (you can't use custom hex colors—WhatsApp enforces its palette)
• Description — Optional internal note (not visible in WhatsApp, only in MoltFlow)

How Labels Work

Labels apply to entire chats, not individual messages. When you label a contact, every message in that conversation is associated with the label until you remove it.

Key characteristics:

• Multiple labels per chat — You can assign multiple labels to a single contact (e.g., "New Lead" + "High Priority")
• Bidirectional sync — Labels created in WhatsApp appear in MoltFlow, and vice versa
• Per-session scope — Each connected WhatsApp number has its own set of labels (if you connect 3 business accounts, each has 20 label slots)
• No label hierarchy — WhatsApp doesn't support nested labels or categories (all labels are flat)

Common Use Cases

Here are practical ways to use labels for automation:

• Lead Segmentation — Tag contacts as "Hot Lead", "Warm Lead", "Cold Lead" based on engagement
• Campaign Tracking — Label contacts by campaign source ("Instagram Ad", "Referral", "Google Ad")
• Support Prioritization — Mark conversations as "Urgent", "Waiting for Customer", "Resolved"
• Bulk Messaging — Filter by label to send targeted messages (e.g., send a promotion only to "VIP Customers")
• Workflow Stages — Track progress through a sales funnel ("Qualified", "Demo Scheduled", "Proposal Sent", "Closed")

MoltFlow lets you automate label assignment based on keywords or first message triggers (covered in Step 3).

Step 2: Create Labels from the Dashboard

To create a new WhatsApp label:

1. Log in to your MoltFlow dashboard at molt.waiflow.app
2. Click Labels in the left sidebar
3. Click "Create Label" in the top-right corner

A modal appears asking for:

• Name — Choose something descriptive and actionable (e.g., "Follow-up Needed" not "Red Label")
• Color — Select from the 20 WhatsApp colors (the dropdown shows the exact palette)
• Description (optional) — Internal note for your team (e.g., "Contacts who requested a callback")
• Session — If you have multiple WhatsApp accounts connected, select which one this label belongs to

Click Create and the label syncs to WhatsApp within 2-3 seconds.

The 20-Label Limit

WhatsApp Business enforces a strict 20-label maximum per account. If you try to create a 21st label, MoltFlow returns an error:

Plan limit reached: maximum 20 labels per session

To create a new label when you're at the limit, you must first delete an unused label. Best practice: regularly audit your labels and remove ones that haven't been used in 30+ days.

Using the API to Create Labels

If you prefer automation, create labels via the API:

curl -X POST https://apiv2.waiflow.app/api/v2/labels \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Lead",
    "color": "#ff9485",
    "description": "Contacts from landing page form",
    "session_id": "YOUR_SESSION_ID"
  }'

The color field must be one of the 20 hex codes from WhatsApp's palette (see the Labels endpoint documentation for the full list). If you provide an invalid color, the API defaults to the first color (#ff9485, a light coral).

Step 3: Assign Labels to Contacts

Once you've created labels, you can assign them to contacts in three ways:

Method 1: From the Dashboard

1. Navigate to Messages or Chats in the sidebar
2. Click on a conversation to open the chat detail view
3. Look for the label icon (usually a tag icon) in the top-right
4. Click it to see all available labels
5. Select one or more labels to assign them
6. Click Save or click outside the dropdown to apply

The labels sync to WhatsApp immediately—if you open WhatsApp on your phone, you'll see the same labels applied.

Method 2: From WhatsApp Directly

Because labels sync bidirectionally, you can also assign labels in WhatsApp:

1. Open WhatsApp Business on your phone
2. Long-press a conversation
3. Tap the label icon at the top
4. Select labels from your list
5. Tap Done

Within a few seconds, MoltFlow's dashboard reflects the change. This two-way sync ensures you can work in whichever interface is most convenient.

Method 3: Via API (for Automation)

For programmatic label assignment (e.g., auto-labeling leads from a webhook):

curl -X PUT https://apiv2.waiflow.app/api/v2/labels/chat/{chat_id} \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label_ids": ["label_id_1", "label_id_2"]
  }'

Replace {chat_id} with the WhatsApp chat ID (format: [email protected] or phone@lid—more on this in Step 5) and label_id_1, label_id_2 with the actual label IDs from the /labels endpoint.

Important: Setting labels via API replaces all existing labels on the chat. To add a label without removing others, first fetch the current labels with GET /labels/chat/{chat_id}, append your new label ID to the array, then PUT the combined list.

Auto-Apply Labels Based on Keywords

MoltFlow supports automatic label assignment when messages contain specific keywords (planned feature—check dashboard for availability):

1. Edit a label in the Labels page
2. Add Auto-apply keywords (e.g., "urgent", "emergency", "asap")
3. Enable Auto-apply on first message if you want to label new contacts immediately

When an inbound message matches a keyword, MoltFlow applies the label automatically and logs the action in the AI audit trail.

Step 4: Filter Contacts by Label

The real power of labels is filtering and segmentation. Here's how to use labels to find specific contacts:

View All Contacts with a Label

1. Go to Labels in the sidebar
2. Click on a label name to see all assigned chats
3. The page shows a list of contacts with:
   • Contact name (if in your phone's contacts) or phone number
   • Last message timestamp
   • Verified business name (if applicable)
   • Whether the contact is saved in your phone (is_my_contact)

This view updates in real-time as you assign/remove labels.

Use WhatsApp Labels for Bulk Messaging

WhatsApp labels are perfect for targeted campaigns. To send a message to everyone with a specific label:

1. Navigate to Bulk Send in the sidebar
2. Choose "Custom Group" as the recipient type
3. Create a custom group and add contacts by label filter
4. Select the label (e.g., "VIP Customers")
5. Compose your message and click Send

MoltFlow queues the messages with random delays (3-8 seconds by default) to avoid WhatsApp's anti-spam detection.

API Endpoint for Label Filtering

To fetch all chats with a specific label programmatically:

curl -X GET https://apiv2.waiflow.app/api/v2/labels/{label_id}/chats \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

[
  {
    "id": "[email protected]",
    "name": "John Doe",
    "phone": "972501234567",
    "display": "John Doe",
    "is_my_contact": true,
    "is_business": false,
    "verified_name": null
  }
  // ... more contacts
]

This endpoint performs a full scan (see Step 5 for technical details) and returns all active and archived chats with the label applied.

Step 5: Understand the NOWEB LID Format

MoltFlow uses the NOWEB engine (powered by WAHA) to connect to WhatsApp. For most label operations, MoltFlow automatically handles the technical details—you don't need to know the internals.

Troubleshooting

Labels Not Syncing

Problem: You create a label in MoltFlow but it doesn't appear in WhatsApp (or vice versa).

Solution: Check these steps:

1. Verify session status — Labels only sync when the session is "working". If the status is "stopped" or "failed", restart the session.
2. Check account type — Labels require WhatsApp Business. If you're using regular WhatsApp, migration is required (see WhatsApp's migration guide).
3. Wait 5-10 seconds — Sync isn't instant. Refresh WhatsApp or MoltFlow after a few seconds.
4. Check the 20-label limit — If you're at 20 labels, new ones won't sync. Delete an unused label first.

"Label Not Found" Error

Problem: The API returns 404 Not Found when fetching a label.

Solution: Labels are scoped to sessions. If you have multiple WhatsApp accounts connected, ensure you're querying the correct session. Check the session_id field on the label—it must match the session you're working with.

Empty Results for Label Filter

Problem: GET /labels/{label_id}/chats returns an empty array even though you've assigned labels.

Solution: This usually means:

1. LID conversion failed — The session may not have synced LIDs yet. Restart the session to force a fresh LID fetch.
2. Cache is stale — Redis cache may be outdated. Wait 5 minutes for it to expire, or manually flush the cache (requires admin access).
3. Labels are local-only — Check if is_synced_to_whatsapp is false on the label. Local-only labels don't have WhatsApp chat associations.

Labels Show for Wrong Session

Problem: Labels from one WhatsApp account appear when viewing chats from another account.

Solution: Labels are per-session, but the dashboard dropdown may default to "All sessions". Use the session filter at the top of the Labels page to view only labels for a specific WhatsApp account.

What's Next?

Now that you've mastered WhatsApp labels, explore related features for advanced contact segmentation and automation:

• Create Custom Groups — Build reusable audience segments from label filters for bulk campaigns
• Monitor WhatsApp Groups — Combine labels with group monitoring to categorize leads by source
• Configure Keyword Auto-Reply Rules — Automatically label contacts based on message keywords
• Send Bulk WhatsApp Messages — Target specific labels for personalized bulk campaigns

Upgrade for Advanced Label Automation

Want to automate label assignment and build sophisticated contact workflows? Upgrade to Growth or Business plans for:

• Auto-apply labels based on keywords — "urgent" → "High Priority" label automatically
• Behavior-based labeling — Assign labels based on engagement, purchase history, or conversation stage
• Label webhooks — Trigger external workflows when labels change (CRM sync, Slack notifications)
• Unlimited labels per session — Go beyond the 20-label WhatsApp Business limit with virtual labels

View plans and pricing — Label automation is the key to 10x conversion rates.

Need help with label automation? Contact support via the dashboard chat or email us at [email protected]. We can help you design label workflows tailored to your use case (sales funnel, support triage, campaign segmentation, etc.).