Перейти к основному содержанию

Введение

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

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

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

Параметры

ПараметрТипОбязательноОписаниеПример
datetime_sendingDateTimeНетДата/время отправки в формате ISO 8601"2024-12-25T10:30:00"
timezoneStringНетЧасовой пояс для времени отправки"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Алматинское время
UTCUTCКоординированное универсальное время

📋 Примеры

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