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

Введение

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

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

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

Параметры

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

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

🕐 Формат DateTime

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

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

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

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

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

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

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

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

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

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

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 единиц"
  }
});

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

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

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

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 для будущего обращения

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

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

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

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

const schedule = await loviService.getScheduledNotification(notificationId);

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

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

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

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

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

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

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

await loviService.cancelScheduledNotification(notificationId);

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

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

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

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

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

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

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

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

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

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": [...]
// }

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

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

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
// }

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

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

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

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

Архивация

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

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

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

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

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

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

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

// ✅ Хорошие времена
"2024-12-25T09:00:00Z" // Рабочее время
"2024-12-25T19:00:00Z" // Вечер

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

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

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. Используйте его стратегически, чтобы максимизировать влияние ваших сообщений.

​Введение

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

​Параметры

​🕐 Формат DateTime

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

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

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

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

​📋 Примеры

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

​Архивация

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

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

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