API уведомлений WhatsApp - Lovi AI Documentation

Введение

Этот раздел содержит официальную документацию по использованию API Lovi с WhatsApp через Postman. Он включает подробные инструкции по настройке и тестированию API-запросов для интеграции с WhatsApp, обеспечивая бесперебойную коммуникацию через платформу. Аутентификация выполняется с помощью токенов, обеспечивающих базовую аутентификацию для сервисов API. Подробнее об аутентификации см. на странице Аутентификация. API Lovi поддерживает уведомления WhatsApp с мультимедийным контентом, динамическими плейсхолдерами, запланированной доставкой и интеграцией с потоками разговоров.

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

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

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

Для отправки уведомления через API Lovi выполните POST-запрос к эндпоинту с необходимыми параметрами и аутентификацией.

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

Эндпоинт

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

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

Параметр	Обязательный	Описание
`access_key`	Да	Ваш уникальный API-ключ доступа.
`unflatten`	Нет	Если `true`, тело должно содержать плоские переменные (без вложенных объектов). Если `false` или не указан, тело может содержать вложенные объекты.

Примеры URL:

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

Заголовки

Ключ	Значение	Обязательный	Описание
Content-Type	application/json	Да	Указывает, что тело запроса в формате JSON.

Примечание: Аутентификация выполняется через параметр access_key в URL, а не через заголовки.

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

API поддерживает два формата структуры данных, управляемых параметром unflatten.

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

Параметр	Тип	Описание	Пример
`contact` ИЛИ `contacts`	Object ИЛИ Array	Выберите один: Один контакт (объект) ИЛИ несколько контактов (массив, макс. 100)	См. ниже
`language_template`	String	Код языка шаблона	`"es_ES"`, `"en_US"`
`name_template`	String	Название одобренного шаблона	`"welcome_user"`
`recipient_id`	String	ID или номер телефона получателя	`"34666033135"`
`notification_type`	String	Тип для аналитики	`"marketing"`, `"transactional"`, `"utility"`
`campaign_name`	String	Идентификатор кампании	`"Black Friday 2024"`

Важно: Необходимо использовать либо contact (для одного получателя), ЛИБО contacts (для нескольких), но НЕ оба.

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

Параметр	Тип	Описание	Когда использовать	Пример
`contact.name`	String	Имя контакта для персонализации	Для персонализированных сообщений	`"Juan Pérez"`
`contact.email`	String	Email контакта	Для дополнительных данных контакта	`"juan@email.com"`
`name_event`	String	Событие для запуска потоков разговоров	Когда нужно начать конкретный поток	`"intent-general-push"`
`datetime_sending`	DateTime	Время запланированной доставки (ISO 8601)	Когда нужно запланировать сообщение	`"2024-12-25T10:30:00"`
`timezone`	String	Часовой пояс для запланированной доставки	При использовании `datetime_sending`	`"Europe/Madrid"`
`components_push.*`	Mixed	Компоненты шаблона (текст, медиа)	Когда шаблон требует динамического контента	См. раздел компонентов

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

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

Используйте contact, когда хотите отправить уведомление одному получателю. Структура:

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

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

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

Используйте 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 контакт

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

API поддерживает два формата на основе параметра unflatten:

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

При 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)

При 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}"})
Подпись и кнопки: СТАТИЧЕСКИЕ в определении шаблона и НЕ МОГУТ быть отправлены динамически

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

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

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

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

ВАЖНО: Только ОДИН компонент заголовка на шаблон. Текст заголовка СТАТИЧЕСКИЙ.

Тип	Имя компонента	Описание	Пример	Спецификации
`image`	`header_image`	URL изображения заголовка	`"https://example.com/image.jpg"`	JPG, PNG, GIF - Макс. 5 МБ
`video`	`header_video`	URL видео заголовка	`"https://example.com/video.mp4"`	MP4, AVI, MOV - Макс. 16 МБ, 30 сек
`document`	`header_document`	URL документа заголовка	`"https://example.com/doc.pdf"`	PDF, DOC, XLS, PPT - Макс. 100 МБ

Примечание: header_text НЕ является динамическим компонентом. Текст заголовка определяется в шаблоне и не может быть изменён.

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

Текст тела с плейсхолдерами требует переменные по порядку: {"{1}"}, {"{2}"}, {"{3}"} и т.д.

Имя компонента	Описание	Соответствие плейсхолдеру
`body_text_0`	Первая переменная тела	`{"{1}"}`
`body_text_1`	Вторая переменная тела	`{"{2}"}`
`body_text_2`	Третья переменная тела	`{"{3}"}`
`body_text_N`	N-я переменная тела	`{"{N}"}`

Пример шаблона: “Привет {"{1}"}, ваш курс {"{2}"} готов”

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

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

⚠️ Подпись СТАТИЧЕСКАЯ — определяется в шаблоне и не может быть изменена для каждого сообщения.

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

ВАЖНО: Большинство кнопок СТАТИЧЕСКИЕ. Однако URL-кнопки с переменными МОГУТ быть динамическими.

Имя компонента	Описание	Когда появляется
`buttons_url_0`	URL первой кнопки с переменной `{"{1}"}`	Когда шаблон имеет URL-кнопку с плейсхолдером `{"{1}"}`
`buttons_url_1`	URL второй кнопки с переменной `{"{2}"}`	Когда шаблон имеет несколько URL-кнопок с переменными

Примечание: Кнопки быстрого ответа всегда статические и не могут быть изменены.

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

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

​Введение

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

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

​Эндпоинт

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

​Заголовки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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