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

# Planung und Zeitzonen-Verwaltung

> Anleitung zum Planen von Benachrichtigungen mit Zeitzonen-Unterstützung

## Einführung

Alle Lovi-Benachrichtigungs-Endpunkte unterstützen Planung für zukünftige Zustellung. Diese Funktion ermöglicht es Ihnen, Benachrichtigungen zu optimalen Zeiten zu senden, wobei die Zeitzonen der Empfänger und Geschäftszeiten berücksichtigt werden.

## 📅 Planungsparameter

Sowohl WhatsApp als auch Voice-Benachrichtigungen unterstützen die folgenden Planungsparameter:

### Parameter

| Parameter          | Typ      | Erforderlich | Beschreibung                            | Beispiel                |
| ------------------ | -------- | ------------ | --------------------------------------- | ----------------------- |
| `datetime_sending` | DateTime | Nein         | Geplantes Datum/Zeit im ISO 8601-Format | `"2024-12-25T10:30:00"` |
| `timezone`         | String   | Nein         | Zeitzone für die geplante Zeit          | `"Europe/Berlin"`       |

**Standardverhalten**: Wenn `datetime_sending` nicht bereitgestellt wird, wird die Benachrichtigung sofort gesendet.

***

## 🕐 Datetime-Format

### Unterstützte ISO 8601-Formate

```json theme={null}
{
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Berlin"
}
```

**Alternative Formate:**

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

### Wichtige Hinweise

* **Zukünftiges Datum erforderlich**: Datum/Zeit müssen in der Zukunft liegen
* **Strenges ISO 8601**: Verwenden Sie das Standard-ISO 8601-Format
* **Zeitzone empfohlen**: Immer Zeitzone für geplante Nachrichten angeben
* **UTC-Standard**: Wenn Zeitzone weggelassen wird, wird UTC verwendet

***

## 🌍 Unterstützte Zeitzonen

### Häufige Geschäftliche Zeitzonen

| Region/Land                | Zeitzonen-Code        | Beschreibung           |
| -------------------------- | --------------------- | ---------------------- |
| **Deutschland**            | `Europe/Berlin`       | Mitteleuropäische Zeit |
| **Österreich**             | `Europe/Vienna`       | Mitteleuropäische Zeit |
| **Schweiz**                | `Europe/Zurich`       | Mitteleuropäische Zeit |
| **USA**                    | `America/New_York`    | Eastern Standard Time  |
| **USA**                    | `America/Chicago`     | Central Standard Time  |
| **USA**                    | `America/Denver`      | Mountain Standard Time |
| **USA**                    | `America/Los_Angeles` | Pacific Standard Time  |
| **Vereinigtes Königreich** | `Europe/London`       | Greenwich Mean Time    |
| **Frankreich**             | `Europe/Paris`        | Mitteleuropäische Zeit |
| **Italien**                | `Europe/Rome`         | Mitteleuropäische Zeit |
| **UTC**                    | `UTC`                 | Koordinierte Weltzeit  |

***

## 📋 Beispiele

### WhatsApp geplante Benachrichtigung

**Sofortige Sendung (keine Planung):**

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "name": "Hans Müller"
  },
  "language_template": "de_DE",
  "name_template": "weihnachten_promo",
  "recipient_id": "34666033135",
  "notification_type": "marketing"
}
```

**Geplante Sendung:**

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "name": "Hans Müller"
  },
  "language_template": "de_DE",
  "name_template": "weihnachten_promo",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Berlin"
}
```

### Voice-Benachrichtigung

**Einfache Planung:**

```javascript theme={null}
await loviService.scheduleVoiceNotification({
  contact: { number: "34666033135" },
  message: "Erinnerung: Termin morgen um 9:00",
  datetime_sending: "2024-12-24T20:00:00Z", // Am Vorabend
  voice: "de-DE-Standard-A"
});
```

**Wiederkehrende Planung:**

```javascript theme={null}
await loviService.scheduleVoiceNotification({
  contact: { number: "34666033135" },
  template: "daily_medication_reminder",
  schedule: {
    type: "recurring",
    frequency: "daily",
    start_date: "2024-01-01T08:00:00Z",
    end_date: "2024-01-31T08:00:00Z",
    days_of_week: [1,2,3,4,5] // Mo-Fr
  },
  variables: {
    name: "Hans",
    medication: "insulin",
    dosage: "10 Einheiten"
  }
});
```

## 📊 Planungsverwaltung

### Planungen erstellen

**Einfache Planung:**

```javascript theme={null}
const result = await loviService.scheduleNotification({
  contact: { number: "34666033135" },
  template: "termin_bestaetigung",
  datetime_sending: "2024-12-25T09:00:00Z",
  variables: {
    name: "Hans",
    date: "25 Dezember",
    time: "10:00"
  }
});

console.log(result.notification_id); // ID für zukünftige Referenz
```

### Planungen abrufen

**Planungen auflisten:**

```javascript theme={null}
const schedules = await loviService.getScheduledNotifications({
  status: "pending", // pending, sent, cancelled
  limit: 50,
  offset: 0
});
```

**Planung nach ID:**

```javascript theme={null}
const schedule = await loviService.getScheduledNotification(notificationId);
```

### Planungen aktualisieren

**Zeit ändern:**

```javascript theme={null}
await loviService.updateScheduledNotification(notificationId, {
  datetime_sending: "2024-12-25T10:00:00Z" // Zeit ändern
});
```

**Inhalt ändern:**

```javascript theme={null}
await loviService.updateScheduledNotification(notificationId, {
  variables: {
    name: "Hans Müller", // Neuer Name
    date: "26 Dezember"  // Neues Datum
  }
});
```

### Planungen stornieren

**Einzelne stornieren:**

```javascript theme={null}
await loviService.cancelScheduledNotification(notificationId);
```

**Mehrere stornieren:**

```javascript theme={null}
await loviService.cancelScheduledNotifications({
  contact_number: "34666033135",
  template: "termin_erinnerung"
});
```

## ⏰ Status und Lebenszyklus

### Planungsstatus

| Status       | Beschreibung                   |
| ------------ | ------------------------------ |
| `scheduled`  | Geplant und wartet auf Sendung |
| `processing` | Wird für Sendung verarbeitet   |
| `sent`       | Erfolgreich gesendet           |
| `failed`     | Sendung fehlgeschlagen         |
| `cancelled`  | Vom Benutzer storniert         |

### Statusübergänge

```mermaid theme={null}
graph TD
    A[scheduled] --> B[processing]
    B --> C[sent]
    B --> D[failed]
    A --> E[cancelled]
    D --> F[retry_scheduled]
    F --> B
```

## 📈 Monitoring und Analyse

### Planungsmetriken

**Versandstatistiken:**

```javascript theme={null}
const stats = await loviService.getSchedulingStats({
  start_date: "2024-12-01",
  end_date: "2024-12-31",
  group_by: "day" // hour, day, week, month
});

// Ergebnis:
// {
//   "total_scheduled": 1250,
//   "total_sent": 1245,
//   "total_failed": 5,
//   "average_delay": 0.2, // Minuten
//   "by_day": [...]
// }
```

### Zustellberichte

**Zustellanalyse:**

```javascript theme={null}
const deliveryReport = await loviService.getDeliveryReport(notificationId);

// Ergebnis:
// {
//   "notification_id": "uuid-123",
//   "status": "sent",
//   "sent_at": "2024-12-25T09:00:15Z",
//   "delivered_at": "2024-12-25T09:00:20Z",
//   "read_at": "2024-12-25T09:05:30Z",
//   "delivery_status": "delivered",
//   "failure_reason": null
// }
```

## 🔧 Planungswartung

### Abgelaufene Planungen bereinigen

**Abgelaufene Planungen entfernen:**

```javascript theme={null}
await loviService.cleanupExpiredSchedules({
  older_than_days: 30,
  status: "sent"
});
```

### Archivierung

**Alte Planungen archivieren:**

```javascript theme={null}
await loviService.archiveSchedules({
  date_before: "2024-01-01",
  status: ["sent", "failed"]
});
```

## 🚨 Einschränkungen und Überlegungen

### Planungseinschränkungen

* **Maximales zukünftiges Zeit**: 90 Tage
* **Minimales zukünftiges Zeit**: 5 Minuten
* **Aktive Planungen pro Konto**: 100.000
* **Erstellungsrate**: 1000 Planungen pro Minute

### Best Practices

**Zeiten optimieren:**

```javascript theme={null}
// ✅ Gute Zeiten
"2024-12-25T09:00:00Z" // Geschäftszeit
"2024-12-25T19:00:00Z" // Abend

// ❌ Zu vermeidende Zeiten
"2024-12-25T03:00:00Z" // Tief in der Nacht
"2024-12-25T12:00:00Z" // Mittagspause
```

**Fehlerbehandlung:**

```javascript theme={null}
try {
  await loviService.scheduleNotification(notificationData);
} catch (error) {
  if (error.code === 'INVALID_SCHEDULE_TIME') {
    // Neue Zeit vorschlagen
    const suggestedTime = suggestValidTime(notificationData.datetime_sending);
    await loviService.scheduleNotification({
      ...notificationData,
      datetime_sending: suggestedTime
    });
  }
}
```

Planung ist ein leistungsstarkes Tool zur Optimierung der WhatsApp-Kommunikation. Verwenden Sie es strategisch, um die Wirkung Ihrer Nachrichten zu maximieren.