> ## 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. # API уведомлений WhatsApp > Официальная документация по использованию API Lovi с WhatsApp через Postman ## Введение Этот раздел содержит официальную документацию по использованию API Lovi с WhatsApp через Postman. Он включает подробные инструкции по настройке и тестированию API-запросов для интеграции с WhatsApp, обеспечивая бесперебойную коммуникацию через платформу. Аутентификация выполняется с помощью токенов, обеспечивающих базовую аутентификацию для сервисов API. Подробнее об аутентификации см. на странице [Аутентификация](./authentication). 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`, когда хотите отправить уведомление **одному получателю**. **Структура**: ```json theme={null} { "contact": { "number": "34666033135", "name": "John", "email": "john@example.com" } } ``` * `contact` — это **объект** (не список) * Обязательное поле: `number` * Необязательные поля: `name`, `email` и любые пользовательские поля *** ### Использование `contacts` — массовая отправка Используйте `contacts`, когда хотите отправить одно уведомление **нескольким получателям** одновременно. **Структура**: ```json theme={null} { "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` или без указания используйте вложенные объекты: ```json theme={null} { "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` все вложенные объекты должны быть сведены через точечную нотацию: ```json theme={null} { "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 возвращает только те компоненты, которые нужно предоставить: ```json theme={null} { "status": "OK", "components": ["header_image", "body_text_0", "body_text_1"] } ``` 3. Отправьте ТОЛЬКО эти компоненты в запросе уведомления ### Типы компонентов по позиции #### Компоненты заголовка (Только медиа) **ВАЖНО**: Только ОДИН компонент заголовка на шаблон. Текст заголовка СТАТИЧЕСКИЙ. | Тип | Имя компонента | Описание | Пример | Спецификации | | ---------- | ----------------- | ------------------------- | --------------------------------- | ----------------------------------- | | `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-кнопок с переменными | **Примечание**: Кнопки быстрого ответа всегда статические и не могут быть изменены. *** ## 📚 Связанная документация * **[Аутентификация](./authentication)** — Как получить токены доступа и API-ключи * **[Голосовые уведомления](./voice_notifications)** — Отправка автоматизированных голосовых звонков * **[Управление шаблонами](./template_management)** — Создание и управление шаблонами WhatsApp * **[Планирование](./scheduling)** — Расширенное планирование и управление часовыми поясами * **[Обработка ошибок](./error_handling)** — Полные коды ошибок и стратегии обработки * **[Лучшие практики](./best_practices)** — Рекомендации по безопасности и производительности