> ## 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 Lovi, позволяющими создавать стандартизированные и персонализированные сообщения для коммуникаций WhatsApp. Это руководство охватывает все операции, связанные с управлением шаблонами.

## 📋 Получение Доступных Шаблонов

Получить все шаблоны, доступные для вашей компании и номера телефона.

### Конечная Точка

```
GET https://cloud.lovi.ai/functions/v1/notify/templates?access_key={YOUR_ACCESS_KEY}&phone_number={PHONE_NUMBER}
```

### Параметры Запроса

| Параметр       | Обязательно | Описание                                          |
| -------------- | ----------- | ------------------------------------------------- |
| `access_key`   | Да          | Ваш уникальный ключ доступа API.                  |
| `phone_number` | Да          | Номер телефона для фильтрации шаблонов (без '+'). |

**Пример запроса:**

```
GET https://cloud.lovi.ai/functions/v1/notify/templates?access_key=your-api-key&phone_number=34666033135
```

### Ответ

API возвращает **массив** объектов шаблонов (не обернутый в объект).

```json theme={null}
[
  {
    "id": "696796403510039",
    "name": "welcome_message",
    "status": "APPROVED",
    "category": "MARKETING",
    "language": "en",
    "components": [
      {
        "text": "Welcome! This is a test message.",
        "type": "BODY"
      }
    ],
    "parameter_format": "POSITIONAL"
  }
]
```

**Важные примечания:**

* Шаблоны фильтруются по номеру телефона
* Возвращаются только утвержденные шаблоны
* Ответ - прямой массив без ключа-обертки

## 📝 Создание Шаблонов

### Структура Шаблона

**Базовый шаблон:**

```json theme={null}
{
  "name": "welcome_user",
  "language": "ru_RU",
  "content": "Привет {{name}}! Добро пожаловать в {{company}}. Как мы можем вам помочь?",
  "variables": ["name", "company"],
  "category": "UTILITY"
}
```

**Шаблон с изображением:**

```json theme={null}
{
  "name": "promo_with_image",
  "language": "ru_RU",
  "content": "Посмотрите наше специальное предложение!",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": ["https://example.com/image.jpg"]
      }
    },
    {
      "text": "Спасибо, что выбираете нас!",
      "type": "FOOTER"
    }
  ],
  "category": "MARKETING"
}
```

### Процесс Утверждения

**Статусы шаблона:**

| Статус     | Описание             | Доступные действия                      |
| ---------- | -------------------- | --------------------------------------- |
| `draft`    | Шаблон в черновике   | Редактировать, отправить на утверждение |
| `pending`  | Ожидает утверждения  | Редактировать, проверить статус         |
| `approved` | Утвержден и доступен | Использовать в уведомлениях             |
| `rejected` | Отклонен             | Редактировать и повторно отправить      |

### Валидация Переменных

**Проверить переменные:**

```javascript theme={null}
function validateTemplateVariables(content, providedVariables) {
  const requiredVars = extractVariables(content); // Извлечь {{var}} из контента
  const providedVars = Object.keys(providedVariables);

  const missing = requiredVars.filter(v => !providedVars.includes(v));
  const extra = providedVars.filter(v => !requiredVars.includes(v));

  if (missing.length > 0) {
    throw new Error(`Отсутствующие переменные: ${missing.join(', ')}`);
  }

  if (extra.length > 0) {
    console.warn(`Предоставлены дополнительные переменные: ${extra.join(', ')}`);
  }
}
```

## 🎯 Использование Шаблонов

### Отправка Простого Уведомления

**С утвержденным шаблоном:**

```javascript theme={null}
await loviService.sendNotification({
  contact: { number: "34666033135" },
  template: "welcome_user",
  variables: {
    name: "Иван",
    company: "TechCorp"
  }
});
```

### Планирование Уведомлений

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

```javascript theme={null}
await loviService.sendNotification({
  contact: { number: "34666033135" },
  template: "reminder_meeting",
  variables: {
    name: "Иван",
    date: "25 декабря",
    time: "10:00"
  },
  datetime_sending: "2024-12-24T20:00:00Z" // Накануне вечером
});
```

### Категории Шаблонов

**Поддерживаемые категории:**

* **MARKETING**: Реклама, объявления, специальные предложения
* **UTILITY**: Подтверждения, обновления, квитанции
* **AUTHENTICATION**: Коды подтверждения, безопасность

### Многоязычная Поддержка

**Шаблон на русском:**

```javascript theme={null}
await loviService.createTemplate({
  name: "welcome_user",
  language: "ru_RU",
  content": "Привет {{name}}! Добро пожаловать в {{company}}."
});
```

**Шаблон на английском:**

```javascript theme={null}
await loviService.createTemplate({
  name: "welcome_user",
  language: "en_US",
  content": "Hello {{name}}! Welcome to {{company}}."
});
```

## 📊 Аналитика Шаблонов

### Метрики Производительности

**Статистика использования:**

```javascript theme={null}
const stats = await loviService.getTemplateStats("welcome_user");
// Возвращает: доставки, открытия, клики и т.д.
```

**Отчеты по периоду:**

```javascript theme={null}
const report = await loviService.getTemplateReport({
  template: "welcome_user",
  start_date: "2024-01-01",
  end_date: "2024-01-31"
});
```

## ⚠️ Ограничения и Соображения

### Ограничения Шаблонов

* **Длина контента**: Макс 1024 символа
* **Переменные**: Макс 20 на шаблон
* **Шаблоны на аккаунт**: 100 активных одновременно
* **Скорость создания**: 10 шаблонов в день

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

**Имена шаблонов:**

```javascript theme={null}
// ✅ Хорошие имена
"welcome_user"
"order_confirmation"
"meeting_reminder"

// ❌ Имена, которых следует избегать
"template1"
"new_template_2024"
"test"
```

**Содержимое шаблона:**

```javascript theme={null}
// ✅ Ясно и кратко
"Привет {{name}}, ваша встреча подтверждена на {{date}} в {{time}}."

// ❌ Слишком длинно или запутанно
"Уважаемый клиент {{name}}, мы рады сообщить, что ваша запись на наш объект для запрошенного обслуживания была правильно зарегистрирована в нашей системе на дату {{date}} с запланированным временем {{time}} часов. Просим прибыть за 15 минут до указанного времени."
```

### Безопасность

**Очистка входных данных:**

```javascript theme={null}
function sanitizeVariables(variables) {
  const sanitized = {};
  for (const [key, value] of Object.entries(variables)) {
    // Удалить потенциально опасные символы
    sanitized[key] = String(value).replace(/[<>]/g, '');
  }
  return sanitized;
}
```

Шаблоны жизненно важны для эффективной коммуникации WhatsApp. Следуйте этим рекомендациям, чтобы максимизировать влияние ваших кампаний коммуникации.