Scheduling & Timezone Management - Lovi AI Documentation

Introduction

All Lovi notification endpoints support scheduling for future delivery. This feature allows you to send notifications at optimal times considering recipient timezones and business hours.

📅 Scheduling Parameters

Both WhatsApp and Voice notifications support the following scheduling parameters:

Parameters

Parameter	Type	Required	Description	Example
`datetime_sending`	DateTime	No	Scheduled date/time in ISO 8601 format	`"2024-12-25T10:30:00"`
`timezone`	String	No	Timezone for the scheduled time	`"Europe/Madrid"`

Default Behavior: If datetime_sending is not provided, the notification is sent immediately.

🕐 Datetime Format

Supported ISO 8601 Formats

{
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Madrid"
}

Alternative formats:

"2024-12-25T10:30:00"
"2024-12-25T10:30:00.000"
"2024-12-25T10:30:00Z"
"2024-12-25T10:30:00+01:00"

Important Notes

Future Date Required: The datetime must be in the future
ISO 8601 Strict: Use standard ISO 8601 format
Timezone Recommended: Always specify timezone for scheduled messages
UTC Default: If timezone is omitted, UTC is used

🌍 Supported Timezones

Common Business Timezones

Region/Country	Timezone Code	Description
Spain	`Europe/Madrid`	Central European Time
Mexico	`America/Mexico_City`	Central Standard Time
Argentina	`America/Argentina/Buenos_Aires`	Argentina Time
Colombia	`America/Bogota`	Colombia Time
Chile	`America/Santiago`	Chile Standard Time
Peru	`America/Lima`	Peru Time
Ecuador	`America/Guayaquil`	Ecuador Time
Venezuela	`America/Caracas`	Venezuela Time
United States	`America/New_York`	Eastern Standard Time
United States	`America/Chicago`	Central Standard Time
United States	`America/Denver`	Mountain Standard Time
United States	`America/Los_Angeles`	Pacific Standard Time
UTC	`UTC`	Coordinated Universal

European Timezones

Country	Timezone Code	Description
United Kingdom	`Europe/London`	Greenwich Mean Time
France	`Europe/Paris`	Central European Time
Germany	`Europe/Berlin`	Central European Time
Italy	`Europe/Rome`	Central European Time
Netherlands	`Europe/Amsterdam`	Central European Time
Portugal	`Europe/Lisbon`	Western European Time

📋 Examples

WhatsApp Scheduled Notification

Immediate sending (no scheduling):

{
  "contact": {
    "number": "34666033135",
    "name": "Ana García"
  },
  "language_template": "es_ES",
  "name_template": "promocion_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Christmas Campaign"
}

Scheduled for specific time:

{
  "contact": {
    "number": "34666033135",
    "name": "Ana García"
  },
  "language_template": "es_ES",
  "name_template": "promocion_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Christmas Campaign",
  "datetime_sending": "2024-12-24T09:00:00",
  "timezone": "Europe/Madrid"
}

Voice Scheduled Notification

{
  "contact": {
    "number": "34666033135",
    "first_name": "María",
    "last_name": "González"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-agente-voz",
  "notification_type": "marketing",
  "campaign_name": "Voice Campaign",
  "datetime_sending": "2024-12-26T10:00:00",
  "timezone": "Europe/Madrid"
}

Flat Structure with Scheduling (unflatten=true)

{
  "contact.number": "34666033135",
  "contact.name": "Ana García",
  "language_template": "es_ES",
  "name_template": "promocion_navidad",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Christmas Campaign",
  "datetime_sending": "2024-12-24T09:00:00",
  "timezone": "Europe/Madrid"
}

⚙️ Validation Rules

Date Validation

✅ Future dates only: Must be later than current time
✅ Maximum advance: Up to 1 year in advance
✅ Format strict: Must follow ISO 8601
❌ Past dates: Will be rejected
❌ Invalid format: Non-ISO dates rejected

Timezone Validation

✅ Valid IANA codes: Use standard timezone database
✅ Case sensitive: Exact format required
❌ Abbreviations: Don’t use CET, EST, etc.
❌ Invalid codes: Unknown timezones rejected

Examples of Valid/Invalid

✅ Valid:

{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "America/Mexico_City"
}

❌ Invalid datetime:

{
  "datetime_sending": "12/25/2024 2:30 PM",  // Wrong format
  "timezone": "Europe/Madrid"
}

❌ Invalid timezone:

{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "CET"  // Use Europe/Madrid instead
}

🚀 Best Practices

Optimal Timing

WhatsApp Messages:

Business hours: 9:00 AM - 6:00 PM local time
Avoid early/late: Not before 8:00 AM or after 9:00 PM
Weekend consideration: Adjust for weekend preferences
Holiday awareness: Check local holidays

Voice Calls:

Business hours only: 9:00 AM - 5:00 PM local time
Workdays preferred: Monday through Friday
Lunch hours: Avoid 12:00 PM - 2:00 PM
Cultural sensitivity: Respect local customs

Timezone Strategy

Store user timezones: Save preferred timezone per contact
Local time display: Show times in user’s local timezone
Business hour logic: Calculate optimal sending times
Daylight saving: IANA codes handle DST automatically

Scheduling Workflow

📊 Response Examples

Successful Scheduling

{
  "success": true,
  "message": "Notification scheduled successfully",
  "notification_id": "uuid-notification-123",
  "scheduled_time": "2024-12-25T10:30:00Z",
  "local_time": "2024-12-25T11:30:00+01:00",
  "timezone": "Europe/Madrid"
}

Immediate Sending

{
  "success": true,
  "message": "Notification queued for immediate sending",
  "notification_id": "uuid-notification-456",
  "queued_at": "2024-12-20T15:45:30Z"
}

⚠️ Common Errors

Past Date Error

{
  "error": "validation_failed",
  "message": "Scheduled time must be in the future",
  "details": {
    "field": "datetime_sending",
    "provided": "2024-12-20T10:00:00",
    "current_time": "2024-12-20T15:30:00Z"
  }
}

Invalid Timezone Error

{
  "error": "validation_failed",
  "message": "Invalid timezone specified",
  "details": {
    "field": "timezone",
    "provided": "CET",
    "suggestion": "Use IANA timezone codes like 'Europe/Madrid'"
  }
}

Invalid Format Error

{
  "error": "validation_failed",
  "message": "Invalid datetime format",
  "details": {
    "field": "datetime_sending",
    "provided": "25-12-2024 10:30",
    "expected_format": "ISO 8601 (YYYY-MM-DDTHH:MM:SS)"
  }
}

🛠️ Development Tips

Testing Scheduling

Use near future: Test with times 5-10 minutes ahead
Timezone testing: Test different timezone scenarios
Edge cases: Test daylight saving transitions
Error handling: Test with invalid dates/timezones

Production Considerations

Buffer time: Add 2-3 minutes buffer for processing
Monitoring: Monitor scheduled vs actual send times
Retry logic: Handle temporary failures gracefully
Logs: Log scheduling details for debugging

Timezone Resources

IANA Database: Official timezone database
Online converter: Use tools to verify timezone codes
Documentation: Keep timezone reference for developers

API Documentation

​Introduction

​📅 Scheduling Parameters

​Parameters

​🕐 Datetime Format

​Supported ISO 8601 Formats

​Important Notes

​🌍 Supported Timezones

​Common Business Timezones

​European Timezones

​📋 Examples

​WhatsApp Scheduled Notification

​Voice Scheduled Notification

​Flat Structure with Scheduling (unflatten=true)

​⚙️ Validation Rules

​Date Validation

​Timezone Validation

​Examples of Valid/Invalid

​🚀 Best Practices

​Optimal Timing

​Timezone Strategy

​Scheduling Workflow

​📊 Response Examples

​Successful Scheduling

​Immediate Sending

​⚠️ Common Errors

​Past Date Error

​Invalid Timezone Error

​Invalid Format Error

​🛠️ Development Tips

​Testing Scheduling

​Production Considerations

​Timezone Resources