Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zapthinker.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Scheduler feature allows you to schedule WhatsApp messages for future delivery, enabling automated campaigns, reminders, and time-based communications. Schedule messages to individual contacts or entire contact lists with support for media, timezone handling, and flexible execution options.

​
Key Features

  • Future Scheduling: Schedule messages for any future date and time
  • Contact Lists: Send to entire contact lists with one schedule
  • Individual Targeting: Schedule messages to specific contacts
  • Media Support: Schedule text, images, documents, and videos
  • Timezone Support: Respect different timezones for global audiences
  • Manual Execution: Run scheduled messages immediately when needed
  • Unsubscribe: Allow recipients to opt-out of scheduled messages
  • Status Management: Pause, resume, or cancel scheduled messages
  • Recurring Messages: (Coming soon) Set up repeating schedules

​
How It Works

  1. Create Schedule: Define message content, recipients, and delivery time
  2. System Queues: Message is queued for future delivery
  3. Automatic Execution: System sends message at scheduled time
  4. Delivery Tracking: Monitor delivery status and failures
  5. Unsubscribe Handling: Respect opt-out requests automatically

​
Message Types

​
Text Messages

Simple text-based scheduled messages: 
{
  "name": "Weekly Newsletter",
  "targets": ["5511999999999@s.whatsapp.net"],
  "content": {
    "text": "Hello! Here's your weekly update..."
  },
  "runAt": "2024-03-15T10:00:00Z",
  "timezone": "America/Sao_Paulo"
}

​
Media Messages

Schedule messages with images, videos, or documents: 
{
  "name": "Product Launch",
  "contactListId": "list-123",
  "content": {
    "caption": "Check out our new product!"
  },
  "mediaUrl": "https://example.com/product.jpg",
  "mediaType": "image",
  "runAt": "2024-03-20T14:00:00Z"
}

​
Targeting Options

​
Individual Contacts

Send to specific phone numbers: 
{
  "targets": [
    "5511999999999@s.whatsapp.net",
    "5511888888888@s.whatsapp.net"
  ]
}

​
Contact Lists

Send to entire contact lists: 
{
  "contactListId": "list-123"
}

​
Combined Approach

Use both individual targets and contact lists in the same schedule.

​
Timezone Handling

Specify timezone to ensure messages are sent at the correct local time:
  • America/Sao_Paulo: Brazilian timezone
  • America/New_York: US Eastern
  • Europe/London: UK timezone
  • Asia/Tokyo: Japan timezone
  • UTC: Coordinated Universal Time

​
Example

Schedule message for 9 AM local time in São Paulo: 
{
  "runAt": "2024-03-15T09:00:00",
  "timezone": "America/Sao_Paulo"
}

​
Status Management

​
Schedule Status

  • Active: Will execute at scheduled time
  • Paused: Temporarily disabled, won’t execute
  • Completed: Already executed
  • Cancelled: Permanently cancelled

​
Updating Status

Change status to pause or resume schedules: 
{
  "status": "paused"
}

​
Manual Execution

Run scheduled messages immediately without waiting:
  1. Useful for testing
  2. Emergency communications
  3. Time-sensitive updates
  4. Correcting scheduling errors
The schedule will be marked as completed after manual execution.

​
Unsubscribe Management

Allow recipients to opt-out of scheduled messages:

​
How It Works

  1. Recipient sends unsubscribe request
  2. System removes them from schedule targets
  3. Future messages to that recipient are blocked
  4. Unsubscribe is logged for compliance

​
API Endpoint

POST /scheduler/unsubscribe/:scheduledMessageId/{instance}
{
  "remoteJid": "5511999999999@s.whatsapp.net"
}

​
Use Cases

​
Marketing Campaigns

Schedule promotional messages for product launches, sales, or events.

​
Appointment Reminders

Send automated reminders before appointments or meetings.

​
Follow-Up Messages

Schedule follow-up messages after customer interactions.

​
Birthday Greetings

Send automated birthday wishes to customers.

​
Payment Reminders

Schedule payment due date reminders.

​
Newsletter Distribution

Send regular newsletters at consistent times.

​
Event Notifications

Remind attendees about upcoming events.

​
Onboarding Sequences

Schedule a series of onboarding messages for new users.

​
Best Practices

  1. Test First: Test with small groups before large campaigns
  2. Timing: Consider recipient timezones and optimal send times
  3. Content Quality: Proofread messages before scheduling
  4. Compliance: Include unsubscribe options for marketing messages
  5. Frequency: Avoid over-messaging to prevent unsubscribes
  6. Segmentation: Use contact lists to target specific audiences
  7. Monitoring: Check delivery status after execution
  8. Backup: Keep copies of important scheduled content

​
Delivery Tracking

Monitor scheduled message performance:
  • Total Recipients: Number of targets
  • Delivered: Successfully delivered messages
  • Failed: Failed deliveries with reasons
  • Pending: Messages still in queue
  • Unsubscribed: Recipients who opted out

​
Advanced Features

​
Batch Processing

System processes large contact lists in batches to:
  • Avoid rate limits
  • Ensure reliable delivery
  • Maintain WhatsApp compliance
  • Prevent account restrictions

​
Failure Handling

Automatic retry logic for failed deliveries:
  • Network errors: Retry automatically
  • Invalid numbers: Skip and log
  • Rate limits: Queue for later delivery
  • Blocked contacts: Skip and log

​
Delivery Reports

Detailed reports on message delivery:
  • Delivery timestamps
  • Failure reasons
  • Recipient responses
  • Unsubscribe events

​
Compliance & Best Practices

​
WhatsApp Policies

  • Only message users who opted in
  • Respect unsubscribe requests immediately
  • Avoid spam or excessive messaging
  • Follow WhatsApp Business Policy
  • GDPR: Respect data privacy rights
  • CAN-SPAM: Include unsubscribe options
  • TCPA: Obtain proper consent
  • Local regulations: Follow country-specific rules

​
Limitations

  • Maximum Recipients: Depends on WhatsApp limits
  • Scheduling Window: Up to 1 year in advance
  • Media Size: Follow WhatsApp media size limits
  • Rate Limits: Subject to WhatsApp rate limiting
  • Timezone Support: Limited to standard timezone identifiers

​
Getting Started

  1. Create a contact list (optional)
  2. Prepare message content
  3. Choose delivery time and timezone
  4. Create scheduled message
  5. Monitor status before execution
  6. Review delivery results after execution
  7. Handle unsubscribe requests
  8. Analyze performance metrics

​
Example Workflow

​
Weekly Newsletter

// 1. Create contact list
POST /contact-list/create/{instance}
{
  "name": "Newsletter Subscribers",
  "contacts": [...]
}

// 2. Schedule message
POST /scheduler/create/{instance}
{
  "name": "Weekly Newsletter - March 15",
  "contactListId": "list-123",
  "content": {
    "text": "Your weekly update..."
  },
  "runAt": "2024-03-15T09:00:00",
  "timezone": "America/Sao_Paulo"
}

// 3. Monitor status
GET /scheduler/find/:scheduledMessageId/{instance}

// 4. Handle unsubscribes
POST /scheduler/unsubscribe/:scheduledMessageId/{instance}
For detailed API documentation, see the API Reference section.