Управление Шаблонами

Введение

Шаблоны являются важными компонентами 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 возвращает массив объектов шаблонов (не обернутый в объект).

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

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

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

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

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

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

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

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

{
  "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`	Отклонен	Редактировать и повторно отправить

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

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

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(', ')}`);
  }
}

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

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

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

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

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

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

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: Коды подтверждения, безопасность

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// ✅ Хорошие имена
"welcome_user"
"order_confirmation"
"meeting_reminder"

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

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

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

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

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

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

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

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

​Введение

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

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

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

​Ответ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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