Planung und Zeitzonen-Verwaltung - Lovi AI Documentation

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

{
  "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):

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

Geplante Sendung:

{
  "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:

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:

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:

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:

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

Planung nach ID:

const schedule = await loviService.getScheduledNotification(notificationId);

Planungen aktualisieren

Zeit ändern:

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

Inhalt ändern:

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

Planungen stornieren

Einzelne stornieren:

await loviService.cancelScheduledNotification(notificationId);

Mehrere stornieren:

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

📈 Monitoring und Analyse

Planungsmetriken

Versandstatistiken:

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:

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:

await loviService.cleanupExpiredSchedules({
  older_than_days: 30,
  status: "sent"
});

Archivierung

Alte Planungen archivieren:

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:

// ✅ 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:

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.

​Einführung

​📅 Planungsparameter

​Parameter

​🕐 Datetime-Format

​Unterstützte ISO 8601-Formate

​Wichtige Hinweise

​🌍 Unterstützte Zeitzonen

​Häufige Geschäftliche Zeitzonen

​📋 Beispiele

​WhatsApp geplante Benachrichtigung

​Voice-Benachrichtigung

​📊 Planungsverwaltung

​Planungen erstellen

​Planungen abrufen

​Planungen aktualisieren

​Planungen stornieren

​⏰ Status und Lebenszyklus

​Planungsstatus

​Statusübergänge

​📈 Monitoring und Analyse

​Planungsmetriken

​Zustellberichte

​🔧 Planungswartung

​Abgelaufene Planungen bereinigen

​Archivierung

​🚨 Einschränkungen und Überlegungen

​Planungseinschränkungen

​Best Practices