API уведомлений WhatsApp

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.

​

Введение

​

Ключевые возможности:

• Уведомления WhatsApp с поддержкой мультимедиа
• Динамическая персонализация контента с помощью плейсхолдеров
• Запланированная доставка сообщений с поддержкой часовых поясов
• Интеграция с потоками разговоров
• Два формата структуры данных (вложенная и плоская)

​

📣 Отправка уведомления WhatsApp

Метод: POST Формат: JSON

​

Эндпоинт

POST https://cloud.lovi.ai/functions/v1/notify?access_key={YOUR_ACCESS_KEY}

​

Параметры запроса

POST https://cloud.lovi.ai/functions/v1/notify?access_key=your-api-key
POST https://cloud.lovi.ai/functions/v1/notify?access_key=your-api-key&unflatten=true

​

Заголовки

​

📋 Параметры запроса

​

Обязательные параметры

​

Необязательные параметры

​

👥 Один vs несколько получателей

​

Использование contact — отправка одному человеку

{
  "contact": {
    "number": "34666033135",
    "name": "John",
    "email": "john@example.com"
  }
}

• contact — это объект (не список)
• Обязательное поле: number
• Необязательные поля: name, email и любые пользовательские поля

​

Использование contacts — массовая отправка

{
  "contacts": [
    {
      "number": "34666033135",
      "name": "John"
    },
    {
      "number": "34777044246",
      "name": "Sarah"
    },
    {
      "number": "34888055357",
      "name": "Michael"
    }
  ]
}

• contacts — это список/массив (не единичный объект)
• Максимум: 100 контактов за запрос
• Каждый контакт должен иметь number
• Необязательные поля: name, email и любые пользовательские поля

• ⚠️ Нельзя использовать unflatten=true с contacts — массовая отправка работает только с вложенной структурой
• ⚠️ Нельзя использовать contact и contacts одновременно — выберите что-то одно
• ⚠️ Список contacts не может быть пустым — минимум 1 контакт

​

🔄 Форматы структуры данных

​

Вложенная структура (unflatten=false или не указан)

{
  "contact": {
    "number": "34666033135",
    "name": "Juan Pérez",
    "email": "juan@email.com"
  },
  "components_push": {
    "header_text_0": "Welcome Message",
    "body_text_0": "Hello {{name}}",
    "body_text_1": "Your order is ready!",
    "footer_text_0": "Support Team"
  },
  "language_template": "es_ES",
  "name_template": "order_ready",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Order Notifications"
}

​

Плоская структура (unflatten=true)

{
  "contact.number": "34666033135",
  "contact.name": "Juan Pérez",
  "contact.email": "juan@email.com",
  "components_push.header_text_0": "Welcome Message",
  "components_push.body_text_0": "Hello {{name}}",
  "components_push.body_text_1": "Your order is ready!",
  "components_push.footer_text_0": "Support Team",
  "language_template": "es_ES",
  "name_template": "order_ready",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Order Notifications"
}

​

Когда использовать каждый формат

• Вложенная структура (unflatten=false): Рекомендуется для лучшей читаемости и когда ваша система поддерживает вложенные объекты
• Плоская структура (unflatten=true): Используйте, когда ваша система не поддерживает вложенные объекты или требует плоскую структуру данных

​

🎨 Компоненты и мультимедиа

​

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

• Медиа заголовка: header_image, header_video, header_document (БЕЗ суффикса-номера)
• Переменные тела: body_text_0, body_text_1, body_text_2 и т.д. (с индексным номером для каждого плейсхолдера {"{1}"}, {"{2}"}, {"{3}"})
• Подпись и кнопки: СТАТИЧЕСКИЕ в определении шаблона и НЕ МОГУТ быть отправлены динамически

​

Как узнать, какие компоненты отправлять

1. Сначала вызовите эндпоинт компонентов шаблона:
   GET /notify/template/components?access_key={key}&template={template_id}
   
2. API возвращает только те компоненты, которые нужно предоставить:
   {
     "status": "OK",
     "components": ["header_image", "body_text_0", "body_text_1"]
   }
   
3. Отправьте ТОЛЬКО эти компоненты в запросе уведомления

​

Типы компонентов по позиции

​

Компоненты заголовка (Только медиа)

​

Компоненты тела (Только переменные)

• body_text_0: Значение для {"{1}"} (например, “Мария”)
• body_text_1: Значение для {"{2}"} (например, “JavaScript”)

​

Компоненты подписи

​

Компоненты кнопок

​

📚 Связанная документация

• Аутентификация — Как получить токены доступа и API-ключи
• Голосовые уведомления — Отправка автоматизированных голосовых звонков
• Управление шаблонами — Создание и управление шаблонами WhatsApp
• Планирование — Расширенное планирование и управление часовыми поясами
• Обработка ошибок — Полные коды ошибок и стратегии обработки
• Лучшие практики — Рекомендации по безопасности и производительности