Scheduled Messages System
The scheduled messaging system consists of three related tools that enable proactive customer communication through WhatsApp. Messages can be scheduled up to 24 hours in advance with flexible cancellation options.Overview
The system provides:- Future message scheduling with precise timing
- Automatic cancellation when customers interact
- Message management with listing and cancellation
- Two scheduling modes for different use cases
Tools in the System
schedule_message
Schedules a WhatsApp message for future delivery.list_scheduled_messages
Shows all pending scheduled messages for a conversation.cancel_scheduled_message
Cancels a previously scheduled message by ID.schedule_message Tool
Parameters
Required
message: Content to send to customerscheduled_for: ISO 8601 datetime when to send
Optional
type: Scheduling behavior (default: “until_next_message”)
Scheduling Types
until_next_message (Default)
Message is automatically cancelled if customer sends ANY message before scheduled time:- Order confirmations (“Click to confirm your order”)
- Pickup reminders
- Status updates that become irrelevant if customer messages
permanent
Message will ALWAYS be sent at scheduled time, even if customer messages:- Follow-up surveys
- Important notifications that must be delivered
- Marketing messages with timing requirements
Time Format Requirements
Always callget_current_time first to ensure accurate scheduling:
- ✅ Correct:
2024-01-15T19:30:00+01:00 - ✅ Correct:
2024-01-15T18:30:00Z - ❌ Wrong:
2024-01-15T19:30:00(missing timezone)
Response Handling
Success Response
Validation Errors
list_scheduled_messages Tool
Usage
No parameters required - lists all pending messages for the conversation:Response
cancel_scheduled_message Tool
Parameters
scheduled_message_id: ID returned fromschedule_message
Usage
Response
Common Usage Patterns
Order Confirmation Reminder
Pickup Notification
Follow-up Survey
Delivery Status Update
Best Practices
When to Use Scheduled Messages
✅ Good Use Cases
- Order confirmation reminders (10-15 minutes)
- Pickup notifications when order is ready
- Follow-up surveys after meal completion
- Delivery status updates during preparation
- Gentle nudges for incomplete orders
❌ Avoid Overuse
- Don’t schedule messages for every interaction
- Avoid messages that may become irrelevant quickly
- Don’t spam customers with too many scheduled messages
- Avoid scheduling during likely sleep hours
Timing Considerations
- Immediate reminders: 5-15 minutes
- Pickup notifications: When actually ready
- Follow-ups: 30-60 minutes after completion
- Surveys: 1-2 hours after delivery
- Check business hours: Avoid scheduling outside operating hours
Message Content Guidelines
- Be specific: “Your pizza will be ready in 10 minutes”
- Include context: Reference the specific order
- Actionable: Tell customer what to do next
- Polite: Use friendly, non-demanding language
- Brief: Keep messages concise and clear
Advanced Scenarios
Conditional Scheduling
Multiple Reminders
Message Cancellation Scenarios
Error Handling
Validation Errors
Handle time format and constraint errors:Scheduling Failures
Cancellation Failures
Performance Notes
- Message scheduling is near-instantaneous
- Validation happens immediately
- Actual delivery depends on WhatsApp infrastructure
- No limit on number of scheduled messages per conversation
- Messages are stored until sent or cancelled
Integration Points
- WhatsApp Business API: Message delivery platform
- get_current_time tool: Essential for accurate scheduling
- Order management: Trigger messages based on order status
- Customer preferences: Respect communication preferences