> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scheduling & Timezone Management

> Guide for scheduling notifications with timezone support

## 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

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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:**

```json theme={null}
{
  "datetime_sending": "2024-12-25T14:30:00",
  "timezone": "America/Mexico_City"
}
```

**❌ Invalid datetime:**

```json theme={null}
{
  "datetime_sending": "12/25/2024 2:30 PM",  // Wrong format
  "timezone": "Europe/Madrid"
}
```

**❌ Invalid timezone:**

```json theme={null}
{
  "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

1. **Store user timezones**: Save preferred timezone per contact
2. **Local time display**: Show times in user's local timezone
3. **Business hour logic**: Calculate optimal sending times
4. **Daylight saving**: IANA codes handle DST automatically

### Scheduling Workflow

```mermaid theme={null}
graph TD
    A[User Input] --> B[Validate DateTime]
    B --> C[Validate Timezone]
    C --> D[Check Future Date]
    D --> E[Queue Notification]
    E --> F[Send at Scheduled Time]
```

***

## 📊 Response Examples

### Successful Scheduling

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

### Invalid Format Error

```json theme={null}
{
  "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

1. **Use near future**: Test with times 5-10 minutes ahead
2. **Timezone testing**: Test different timezone scenarios
3. **Edge cases**: Test daylight saving transitions
4. **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](https://www.iana.org/time-zones)
* **Online converter**: Use tools to verify timezone codes
* **Documentation**: Keep timezone reference for developers