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

# Планирование и Управление Часовыми Поясами

> Руководство по планированию уведомлений с поддержкой часовых поясов

## Введение

Все конечные точки уведомлений Lovi поддерживают планирование для доставки в будущем. Эта функция позволяет отправлять уведомления в оптимальное время, учитывая часовые пояса получателей и рабочие часы.

## 📅 Параметры Планирования

И WhatsApp, и голосовые уведомления поддерживают следующие параметры планирования:

### Параметры

| Параметр           | Тип      | Обязательно | Описание                               | Пример                  |
| ------------------ | -------- | ----------- | -------------------------------------- | ----------------------- |
| `datetime_sending` | DateTime | Нет         | Дата/время отправки в формате ISO 8601 | `"2024-12-25T10:30:00"` |
| `timezone`         | String   | Нет         | Часовой пояс для времени отправки      | `"Europe/Moscow"`       |

**Поведение по умолчанию**: Если `datetime_sending` не предоставлен, уведомление отправляется немедленно.

***

## 🕐 Формат DateTime

### Поддерживаемые Форматы ISO 8601

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

**Альтернативные форматы:**

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

### Важные Примечания

* **Требуется Будущее Время**: Дата/время должны быть в будущем
* **Строго ISO 8601**: Использовать стандартный формат ISO 8601
* **Рекомендуется Часовой Пояс**: Всегда указывать часовой пояс для запланированных сообщений
* **UTC по умолчанию**: Если часовой пояс опущен, используется UTC

***

## 🌍 Поддерживаемые Часовые Пояса

### Распространенные Бизнес-Часовые Пояса

| Регион/Страна      | Код Часового Пояса | Описание                             |
| ------------------ | ------------------ | ------------------------------------ |
| **Россия**         | `Europe/Moscow`    | Московское время                     |
| **США**            | `America/New_York` | Восточное стандартное время          |
| **Великобритания** | `Europe/London`    | Среднее время по Гринвичу            |
| **Германия**       | `Europe/Berlin`    | Центральноевропейское время          |
| **Франция**        | `Europe/Paris`     | Центральноевропейское время          |
| **Италия**         | `Europe/Rome`      | Центральноевропейское время          |
| **Испания**        | `Europe/Madrid`    | Центральноевропейское время          |
| **Украина**        | `Europe/Kiev`      | Восточноевропейское время            |
| **Казахстан**      | `Asia/Almaty`      | Алматинское время                    |
| **UTC**            | `UTC`              | Координированное универсальное время |

***

## 📋 Примеры

### Запланированное Уведомление WhatsApp

**Немедленная отправка (без планирования):**

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "name": "Иван Петров"
  },
  "language_template": "ru_RU",
  "name_template": "рождественская_акция",
  "recipient_id": "34666033135",
  "notification_type": "marketing"
}
```

**Запланированная отправка:**

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "name": "Иван Петров"
  },
  "language_template": "ru_RU",
  "name_template": "рождественская_акция",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Moscow"
}
```

### Голосовое Уведомление

**Простое планирование:**

```javascript theme={null}
await loviService.scheduleVoiceNotification({
  contact: { number: "34666033135" },
  message: "Напоминание: встреча завтра в 9:00",
  datetime_sending: "2024-12-24T20:00:00Z", // Накануне вечером
  voice: "ru-RU-Standard-A"
});
```

**Повторяющееся планирование:**

```javascript theme={null}
await loviService.scheduleVoiceNotification({
  contact: { number: "34666033135" },
  template: "ежедневное_напоминание_о_лекарствах",
  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] // Пн-Пт
  },
  variables: {
    name: "Иван",
    medication: "инсулин",
    dosage: "10 единиц"
  }
});
```

## 📊 Управление Планированием

### Создание Планирований

**Простое планирование:**

```javascript theme={null}
const result = await loviService.scheduleNotification({
  contact: { number: "34666033135" },
  template: "подтверждение_встречи",
  datetime_sending: "2024-12-25T09:00:00Z",
  variables: {
    name: "Иван",
    date: "25 декабря",
    time: "10:00"
  }
});

console.log(result.notification_id); // ID для будущего обращения
```

### Получение Планирований

**Список планирований:**

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

**Планирование по ID:**

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

### Обновление Планирований

**Изменить время:**

```javascript theme={null}
await loviService.updateScheduledNotification(notificationId, {
  datetime_sending: "2024-12-25T10:00:00Z" // Изменить время
});
```

**Изменить содержимое:**

```javascript theme={null}
await loviService.updateScheduledNotification(notificationId, {
  variables: {
    name: "Иван Петров", // Новое имя
    date: "26 декабря"  // Новая дата
  }
});
```

### Отмена Планирований

**Отменить одно:**

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

**Отменить несколько:**

```javascript theme={null}
await loviService.cancelScheduledNotifications({
  contact_number: "34666033135",
  template: "напоминание_о_встрече"
});
```

## ⏰ Статусы и Жизненный Цикл

### Статусы Планирования

| Статус       | Описание                         |
| ------------ | -------------------------------- |
| `scheduled`  | Запланировано и ожидает отправки |
| `processing` | Обрабатывается для отправки      |
| `sent`       | Отправлено успешно               |
| `failed`     | Отправка не удалась              |
| `cancelled`  | Отменено пользователем           |

### Переходы Статусов

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

## 📈 Мониторинг и Анализ

### Метрики Планирования

**Статистика отправки:**

```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
});

// Результат:
// {
//   "total_scheduled": 1250,
//   "total_sent": 1245,
//   "total_failed": 5,
//   "average_delay": 0.2, // минуты
//   "by_day": [...]
// }
```

### Отчеты о Доставке

**Анализ доставки:**

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

// Результат:
// {
//   "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
// }
```

## 🔧 Обслуживание Планирований

### Очистка Истекших Планирований

**Удалить истекшие планирования:**

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

### Архивация

**Архивировать старые планирования:**

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

## 🚨 Ограничения и Соображения

### Ограничения Планирования

* **Максимальное будущее время**: 90 дней
* **Минимальное будущее время**: 5 минут
* **Активные планирования на аккаунт**: 100.000
* **Скорость создания**: 1000 планирований в минуту

### Лучшие Практики

**Оптимизация времен:**

```javascript theme={null}
// ✅ Хорошие времена
"2024-12-25T09:00:00Z" // Рабочее время
"2024-12-25T19:00:00Z" // Вечер

// ❌ Времена, которых следует избегать
"2024-12-25T03:00:00Z" // Глубокая ночь
"2024-12-25T12:00:00Z" // Обеденное время
```

**Обработка ошибок:**

```javascript theme={null}
try {
  await loviService.scheduleNotification(notificationData);
} catch (error) {
  if (error.code === 'INVALID_SCHEDULE_TIME') {
    // Предложить новое время
    const suggestedTime = suggestValidTime(notificationData.datetime_sending);
    await loviService.scheduleNotification({
      ...notificationData,
      datetime_sending: suggestedTime
    });
  }
}
```

Планирование - это мощный инструмент для оптимизации коммуникаций WhatsApp. Используйте его стратегически, чтобы максимизировать влияние ваших сообщений.