Campaign Management - Mindhunters API Documentation

What are Campaigns?

Campaigns allow you to orchestrate multi-channel communication at scale. Whether you’re conducting surveys, sending reminders, or reaching out to leads, campaigns help you organize and automate your outreach.

Campaign Types

Voice Campaigns

Automated outbound calling with AI agents

WhatsApp Campaigns

Template-based WhatsApp broadcasts

Mixed Campaigns

Multi-channel campaigns with sequential touchpoints

Drip Campaigns

Automated sequences with timing rules

Creating a Campaign

Via Dashboard

Navigate to Campaigns

Go to Campaigns in your Mindhunters dashboard

Create New Campaign

Click “Create Campaign” button

Configure Basic Settings

Campaign name
Campaign type (Voice, WhatsApp, Mixed)
Description
Start and end dates

Select Agent/Template

For voice: Choose an AI agent
For WhatsApp: Select message template
For mixed: Configure both

Choose Contacts

Upload contact list
Select from existing contacts
Apply filters and segments

Set Schedule

Immediate or scheduled start
Time windows (e.g., 9 AM - 5 PM)
Timezone considerations
Pacing (calls per hour)

Launch Campaign

Review settings and click “Launch”

Via API

Create campaigns programmatically:

curl -X POST https://your-tenant.mindhunters.ai/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Survey Q1 2025",
    "type": "voice",
    "agentId": "agent-uuid-here",
    "contacts": [
      {"number": "+1234567890", "name": "John Doe"},
      {"number": "+0987654321", "name": "Jane Smith"}
    ],
    "schedule": {
      "startDate": "2025-01-20T09:00:00Z",
      "endDate": "2025-01-25T17:00:00Z",
      "timeWindows": [
        {"start": "09:00", "end": "17:00", "timezone": "America/New_York"}
      ]
    },
    "settings": {
      "maxCallsPerHour": 100,
      "retryFailed": true,
      "maxRetries": 2
    }
  }'

Campaign Settings

Scheduling Options

Start Date & Time

When the campaign should begin contacting people. Can be immediate or scheduled for a future date/time.

End Date & Time

When the campaign should stop. All pending contacts will be marked as “not contacted” after this time.

Time Windows

Specific hours when contacts can be reached (e.g., 9 AM - 5 PM). Respects recipient timezones.

Pacing

Control how many contacts are reached per hour to avoid overwhelming your team or systems.

Retry Logic

Automatically retry failed attempts with configurable retry count and delay.

Advanced Settings

Setting	Description	Default
Max Calls/Hour	Rate limit for outbound calls	100
Retry Failed	Retry failed attempts	true
Max Retries	Maximum retry attempts	2
Retry Delay	Hours between retries	2
Skip Duplicates	Skip duplicate phone numbers	true
Respect DNC	Honor Do Not Call lists	true

Contact Management

Adding Contacts

Manual Entry
CSV Upload
From Contacts Database
Via API

Add contacts one by one through the dashboard interface.

Contact Filters

Filter contacts based on:

Tags: Contact tags and labels
Custom Fields: Any custom field values
Previous Interactions: Past campaign participation
Status: Active, inactive, opted-out
Location: Country, state, city
Timezone: Specific timezones

Campaign Monitoring

Real-time Dashboard

Monitor campaign progress in real-time:

Total Contacts: Total contacts in campaign
Contacted: Successfully reached
Pending: Not yet contacted
Failed: Failed to reach
Success Rate: Percentage successfully contacted
Progress: Visual progress bar

Live Activity Feed

See contact-by-contact activity:

15 PM - Called +1234567890 (John Doe) - Success - Duration: 3:45
14 PM - Called +0987654321 (Jane Smith) - No Answer - Retry scheduled
13 PM - Called +1122334455 (Bob Wilson) - Success - Duration: 2:30

Webhooks for Campaign Events

Receive real-time updates via webhooks:

Example Webhook

{
  "event": "campaign.contact.completed",
  "timestamp": "2025-01-15T14:15:00Z",
  "data": {
    "campaignId": "campaign-uuid",
    "contactNumber": "+1234567890",
    "contactName": "John Doe",
    "status": "success",
    "duration": 225,
    "callId": "call-uuid"
  }
}

See Webhooks Guide for setup.

Campaign Analytics

Performance Metrics

Contact Rate: Percentage of contacts reached
Answer Rate: Percentage who answered (voice)
Completion Rate: Percentage who completed interaction
Average Duration: Mean interaction time
Intent Distribution: Common intents detected
Sentiment Analysis: Overall sentiment breakdown

Reports

Generate detailed reports:

Go to Campaigns → Select campaign
Click “Analytics” tab
Choose metrics and date range
Export as CSV or PDF

A/B Testing

Test different approaches:

Split Test: Divide contacts into groups
Agent Variations: Test different agent prompts
Template Variations: Test different messages
Timing: Test different time windows
Compare Results: Analyze which performs better

Campaign Types in Detail

Voice Campaigns

Automated calling campaigns with AI agents: Best for:

Customer surveys
Appointment reminders
Lead qualification
Debt collection
Emergency notifications

Configuration:

Select AI agent
Set call windows
Define success criteria
Configure retry logic

WhatsApp Campaigns

Template-based messaging campaigns: Best for:

Order confirmations
Shipping updates
Appointment reminders
Marketing promotions
Customer notifications

Requirements:

Approved WhatsApp templates
Valid phone numbers
Opt-in consent

Drip Campaigns

Multi-touch sequences over time: Example Flow:

Day 1: Send WhatsApp message
Day 3: Make voice call if no response
Day 7: Send follow-up WhatsApp
Day 14: Final voice call attempt

Configuration:

Define sequence steps
Set delays between steps
Configure triggers and conditions
Handle responses

Best Practices

Segment Your Audience

Group contacts by relevant criteria
Personalize messaging for each segment
Test different approaches per segment
Track segment-specific performance

Optimize Timing

Call during business hours
Consider recipient timezones
Avoid holidays and weekends (unless appropriate)
Test different time windows

Monitor and Adjust

Watch real-time metrics
Pause if issues arise
Adjust pacing as needed
Iterate based on results

Respect Opt-Outs

Honor Do Not Call lists
Process opt-out requests immediately
Maintain unsubscribe lists
Comply with regulations

Test Before Launching

Test with small sample first
Verify agent/template works correctly
Check contact data quality
Confirm scheduling is correct

Managing Active Campaigns

Pausing a Campaign

curl -X PATCH https://your-tenant.mindhunters.ai/api/v1/campaigns/{id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "paused"}'

Resuming a Campaign

curl -X PATCH https://your-tenant.mindhunters.ai/api/v1/campaigns/{id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Stopping a Campaign

curl -X PATCH https://your-tenant.mindhunters.ai/api/v1/campaigns/{id} \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "stopped"}'

Compliance

Regulations

TCPA: Telephone Consumer Protection Act (US)
GDPR: General Data Protection Regulation (EU)
CASL: Canadian Anti-Spam Legislation
DNC Lists: Do Not Call registries

Best Practices

✅ Do:

Get explicit consent
Provide opt-out options
Honor opt-out requests
Respect calling hours
Maintain DNC lists

❌ Don’t:

Call without consent
Ignore opt-out requests
Call outside permitted hours
Use misleading caller ID
Harass contacts

Troubleshooting

Low Contact Rate

Possible causes:

Poor contact data quality
Calling outside business hours
Phone numbers invalid/disconnected
Agent issues

Solutions:

Validate contact data
Adjust time windows
Review agent configuration
Test with known-good numbers

High Failure Rate

Possible causes:

Technical issues
Rate limiting
Invalid agent configuration
Network problems

Solutions:

Check campaign logs
Reduce pacing
Verify agent settings
Contact support

Next Steps

Voice Agents

Create AI agents for campaigns

Set up WhatsApp messaging

Contacts

Manage your contact database

API Reference

View campaign API endpoints

Getting Started

Services

Developer Tools

​What are Campaigns?

​Campaign Types

Voice Campaigns

WhatsApp Campaigns

Mixed Campaigns

Drip Campaigns

​Creating a Campaign

​Via Dashboard

​Via API

​Campaign Settings

​Scheduling Options

​Advanced Settings

​Contact Management

​Adding Contacts

​Contact Filters

​Campaign Monitoring

​Real-time Dashboard

​Live Activity Feed

​Webhooks for Campaign Events

​Campaign Analytics

​Performance Metrics

​Reports

​A/B Testing

​Campaign Types in Detail

​Voice Campaigns

​WhatsApp Campaigns

​Drip Campaigns

​Best Practices

​Managing Active Campaigns

​Pausing a Campaign

​Resuming a Campaign

​Stopping a Campaign

​Compliance

​Regulations

​Best Practices

​Troubleshooting

​Low Contact Rate

​High Failure Rate

​Next Steps

Voice Agents

WhatsApp

Contacts

API Reference

What are Campaigns?

Campaign Types

Creating a Campaign

Via Dashboard

Via API

Campaign Settings

Scheduling Options

Advanced Settings

Contact Management

Adding Contacts

Contact Filters

Campaign Monitoring

Real-time Dashboard

Live Activity Feed

Webhooks for Campaign Events

Campaign Analytics

Performance Metrics

Reports

A/B Testing

Campaign Types in Detail

Voice Campaigns

WhatsApp Campaigns

Drip Campaigns

Best Practices

Managing Active Campaigns

Pausing a Campaign

Resuming a Campaign

Stopping a Campaign

Compliance

Regulations

Best Practices

Troubleshooting

Low Contact Rate

High Failure Rate

Next Steps