Excluded Numbers

Excluded Numbers is your account-wide do-not-contact list. Any phone number added here is completely skipped — by the AI chatbot, by flow bots, and by bulk campaigns — so people who've opted out stay opted out everywhere, automatically. You can add numbers individually with a reason and optional expiry date, bulk-import via CSV, or manage exclusions programmatically through the API. A daily background cleanup automatically re-enables numbers whose temporary exclusion has expired, and the dashboard shows real-time counts of active vs. expired exclusions so you always know the state of your blocklist.

How Exclusions Work

Customer

Incoming Message

Customer sends a message.

System

Skip Bot

If excluded, skip the bot and route to inbox.

System

Blocklist Check

System checks if sender is on the exclusion list.

Bot

Process Normally

If not excluded, process through Chatbot or Flows.

Customer

Incoming Message

Customer sends a message.

System

Blocklist Check

System checks if sender is on the exclusion list.

System

Skip Bot

If excluded, skip the bot and route to inbox.

Bot

Process Normally

If not excluded, process through Chatbot or Flows.

📊 Free Feature: Managing the excluded numbers list is included on all plans and does not consume any message limits or API quotas.

What you can do here

Maintain a global blocklist — add numbers to ensure they are completely skipped by automated chatbot replies and marketing campaigns.
Add single entries — manually add a valid phone number (10–20 characters), along with a reason (up to 255 chars) and an optional expiry date.
Bulk import via CSV — upload a list of phone numbers with a shared reason, or drag-and-drop a CSV file to add many exclusions at once.
Monitor analytics — view a real-time dashboard displaying counts of Active vs. Expired exclusions.
Export your list — download your complete blocklist as a CSV containing Phone Number, Reason, Excluded At, Expires At, and Status.
Manage via API — programmatically add, list, or delete exclusions using the dedicated JSON API endpoints.

Global Blocklist

Account-wide do-not-contact list

Single & Bulk Entry

Add manually or upload via CSV

Expiry Dates

Set temporary or permanent exclusions

Dashboard Analytics

Track active vs. expired counts

CSV Export

Download list for compliance audits

API Integration

Manage programmatically via endpoints

How to manage exclusions

Your Blocklist Workflow

Step 1

Add Numbers

Add a single number with a specific reason, or drag-and-drop a CSV to bulk-import a list of opted-out contacts.

Step 2

Set Expirations

Apply optional expiry dates for temporary pauses (e.g., snooze for 30 days), or leave blank for a permanent block.

Step 3

Audit & Export

Periodically review active vs. expired counts and download a CSV export for your compliance records.

Step 1

Add Numbers

Add a single number with a specific reason, or drag-and-drop a CSV to bulk-import a list of opted-out contacts.

Step 2

Set Expirations

Apply optional expiry dates for temporary pauses (e.g., snooze for 30 days), or leave blank for a permanent block.

Step 3

Audit & Export

Periodically review active vs. expired counts and download a CSV export for your compliance records.

Tip: The chatbot automatically checks this list before replying. If a number is on the active list, the bot will immediately skip it and route the message to the human inbox.

Technical Configuration Details

To manage your blocklist properly, keep these technical details in mind:

Phone Number Validation: Must be a valid numeric string between 10 and 20 characters in length, including the country code.
Reason Limit: The reason text can be up to 255 characters.
Daily Cleanup: A scheduled sweeper runs daily in the background to automatically identify and clean up expired exclusions.
Developer Endpoints:
- GET /api/exclusions — List all exclusions (supports pagination and search filters).
- POST /api/exclusions — Create a new exclusion.
- DELETE /api/exclusions/:phoneNumber — Remove a number from the blocklist.

Making the Most of Excluded Numbers

This list isn't just an administrative tool — it's your compliance safety net and a key protector of your WhatsApp number's health. WhatsApp monitors how often your messages are blocked or reported.

Complaint rate threshold before account restriction risks

35-40%

Reduction in failed COD deliveries by excluding canceled orders

100%

Compliance with opt-out requests instantly

How top teams stay compliant

Playbook: Blocklist Best Practices

Compliance

Immediate Opt-Outs

Under GDPR and TCPA, you must stop messaging immediately when a customer opts out. Use this list to automate compliance.

Automation

Temporary Pauses

If a customer asks to "pause promotions for 30 days," set an expiry date. They are automatically re-included when the timer ends.

Integration

CRM Sync

Integrate your CRM via API to automatically add customers who cancel their subscriptions to this list.

Real results

COD order management: An apparel brand used auto-exclusion for customers who cancelled cash-on-delivery orders before dispatch. This reduced failed deliveries by 35–40% within 30 days — saving significant logistics costs.
Compliance Protection: Repeatedly messaging opted-out contacts risks your number progressing from a warning status to a permanent ban. Proper exclusion management prevents small report spikes from hurting your quality rating.

Measured improvements with Exclusion Management

Failed COD Deliveries

Baseline-40%

Compliance Risk

High Manual ErrorAutomated

Quality Rating Protection

At RiskSecured

Industry case studies: apparel brand, CRM automations

Bot Settings — Enables "Human Takeover" settings to auto-add numbers to this blocklist when agents reply.
Contact Groups — The system cross-references this blocklist and automatically skips campaigns to excluded recipients.
API Management — Generate keys to access the /api/exclusions endpoints.

How Exclusions Work

Incoming Message

Skip Bot

Blocklist Check

Process Normally

Incoming Message

Blocklist Check

Skip Bot

Process Normally

Global Blocklist

Single & Bulk Entry

Expiry Dates

Dashboard Analytics

CSV Export

API Integration

Your Blocklist Workflow

Add Numbers

Set Expirations

Audit & Export

Add Numbers

Set Expirations

Audit & Export

Playbook: Blocklist Best Practices

Immediate Opt-Outs

Temporary Pauses

CRM Sync

Measured improvements with Exclusion Management

Continue Learning

API Management

Bot Escalations

Flow Builder

How Exclusions Work

Incoming Message

Skip Bot

Blocklist Check

Process Normally

Incoming Message

Blocklist Check

Skip Bot

Process Normally

Global Blocklist

Single & Bulk Entry

Expiry Dates

Dashboard Analytics

CSV Export

API Integration

Your Blocklist Workflow

Add Numbers

Set Expirations

Audit & Export

Add Numbers

Set Expirations

Audit & Export

Playbook: Blocklist Best Practices

Immediate Opt-Outs

Temporary Pauses

CRM Sync

Measured improvements with Exclusion Management