API Голосовых Уведомлений

Введение

Голосовые уведомления позволяют достигать клиентов через автоматизированные телефонные звонки, когда WhatsApp недоступен или предпочтителен. Эта конечная точка позволяет отправлять голосовые звонки с AI-агентами на ваши контакты, предоставляя персонализированный голосовой опыт.

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

Чтобы отправить голосовое уведомление через API Lovi, отправьте POST-запрос на конечную точку voice с необходимыми параметрами и аутентификацией.

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

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

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

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

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

Пример URL:

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

Заголовки

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

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

Тело Запроса

Тело запроса содержит детали голосового уведомления.

Структура с вложенными объектами (unflatten=false или опущено)

{
  "contact": {
    "number": "34666033135",
    "first_name": "Иван",
    "last_name": "Петров",
    "email": "ivan@email.com",
    "specialty": "Медсестра",
    "client_source": "Главный сайт"
  },
  "recipient_id": "34911670470",
  "agent_id": "uuid-голосовой-агент",
  "notification_type": "marketing",
  "campaign_name": "Звонок Информационный Q4",
  "name_event": "info-курс-медсестер",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Moscow"
}

Структура с плоскими переменными (unflatten=true)

{
  "contact.number": "34666033135",
  "contact.first_name": "Иван",
  "contact.last_name": "Петров",
  "contact.email": "ivan@email.com",
  "contact.specialty": "Медсестра",
  "client_source": "Главный сайт",
  "recipient_id": "34911670470",
  "agent_id": "uuid-голосовой-агент",
  "notification_type": "marketing",
  "campaign_name": "Звонок Информационный Q4",
  "name_event": "info-курс-медсестер",
  "datetime_sending": "2024-12-25T09:00:00",
  "timezone": "Europe/Moscow"
}

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

Параметр	Тип	Описание	Пример
`contact.number`	String	Номер телефона получателя (только цифры)	`"34666033135"`
`recipient_id`	String	ID или номер телефона получателя	`"34911670470"`
`agent_id`	String	Уникальный идентификатор голосового агента	`"uuid-голосовой-агент"`
`notification_type`	String	Тип для аналитики	`"marketing"`, `"transactional"`
`campaign_name`	String	Идентификатор названия кампании	`"Голосовая кампания Q4"`

Опциональные Параметры

### API-Ответ

#### Успешный Ответ

```json
{
  "success": true,
  "message": "Voice notification queued successfully",
  "notification_id": "uuid-voice-notification-123",
  "estimated_duration": 25
}

Ответ с Ошибкой

{
  "error": "validation_failed",
  "message": "Invalid phone number format",
  "details": {
    "field": "contact.number",
    "provided": "34-666-033-135",
    "expected_format": "Numbers only, no + or spaces",
    "example": "34666033135"
  },
  "request_id": "req_123456789"
}

🎵 Конфигурация Голоса

Доступные Голоса

Русский:

ru-RU-Standard-A (Женский, стандарт)
ru-RU-Standard-B (Мужской, стандарт)
ru-RU-Wavenet-A (Женский, высокое качество)
ru-RU-Wavenet-B (Мужской, высокое качество)
ru-RU-Neural2-A (Женский, нейронный)
ru-RU-Neural2-B (Мужской, нейронный)

Расширенные Конфигурации Голоса

Персонализация голоса:

await loviService.sendVoiceNotification({
  contact: { number: "34666033135" },
  message: "Добро пожаловать в наш сервис поддержки клиентов",
  voice_config: {
    voice: "ru-RU-Wavenet-A",
    speaking_rate: 1.0,     // Скорость речи: 0.25 - 4.0
    pitch: 0.0,            // Высота тона: -20.0 - 20.0
    volume_gain_db: 0.0    // Громкость: -96.0 - 16.0
  }
});

📋 Голосовые Шаблоны

Создание Голосового Шаблона

Простой шаблон:

{
  "name": "order_ready_voice",
  "language": "ru-RU",
  "content": "Привет {{name}}, ваш заказ номер {{order_id}} готов к выдаче в {{store_location}}",
  "voice": "ru-RU-Standard-A",
  "variables": ["name", "order_id", "store_location"]
}

Шаблон с паузами и интонацией:

{
  "name": "appointment_reminder_voice",
  "language": "ru-RU",
  "content": "Напоминание о встрече. <break time=\"500ms\"/> Привет {{name}}. <break time=\"300ms\"/> Ваша встреча с {{doctor}} запланирована на {{date}} в {{time}}. <break time=\"500ms\"/> Ждем вас в {{clinic}}.",
  "voice": "ru-RU-Wavenet-A",
  "variables": ["name", "doctor", "date", "time", "clinic"]
}

Использование Голосовых Шаблонов

Отправка с шаблоном:

await loviService.sendVoiceNotification({
  contact: { number: "34666033135" },
  template: "appointment_reminder_voice",
  variables: {
    name: "Иван Петров",
    doctor: "Доктор Сидоров",
    date: "15 декабря",
    time: "10:30",
    clinic: "Центральная клиника"
  }
});

⏰ Планирование Голосовых Уведомлений

Немедленная Отправка

Базовый звонок:

await loviService.sendVoiceNotification({
  contact: { number: "34666033135" },
  message: "Привет Иван, ваша встреча подтверждена на завтра в 10:00",
  voice: "ru-RU-Standard-A",
  language: "ru-RU"
});

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

Простое планирование:

await loviService.scheduleVoiceNotification({
  contact: { number: "34666033135" },
  message: "Напоминание: встреча завтра в 9:00",
  datetime_sending: "2024-12-24T20:00:00Z", // Накануне вечером
  voice: "ru-RU-Standard-A"
});

📞 Управление Звонками

Статусы Звонков

Статус	Описание
`queued`	В очереди для отправки
`ringing`	Звонок идет
`answered`	Получатель ответил
`completed`	Звонок завершен успешно
`busy`	Линия занята
`no_answer`	Нет ответа
`failed`	Звонок не удался

Мониторинг Звонков

Статус звонка:

const callStatus = await loviService.getVoiceCallStatus(callId);
// Результат: { status: "completed", duration: 25, cost: 0.05 }

Отчеты о звонках:

const report = await loviService.getVoiceCallReport({
  start_date: "2024-12-01",
  end_date: "2024-12-31",
  status: "completed"
});
// Результат: статистика завершенных звонков

🎯 Примеры Использования

Здравоохранение

Напоминания о встречах:

async function scheduleMedicalReminders(appointments) {
  for (const appointment of appointments) {
    // Звонок за 24 часа
    await loviService.scheduleVoiceNotification({
      contact: { number: appointment.patient_phone },
      template: "medical_appointment_reminder",
      datetime_sending: calculateReminderTime(appointment.datetime, -24),
      variables: {
        name: appointment.patient_name,
        doctor: appointment.doctor_name,
        specialty: appointment.specialty,
        date: formatDate(appointment.datetime),
        time: formatTime(appointment.datetime),
        location: appointment.clinic_address
      }
    });

    // SMS-напоминание, если звонок не ответил
    await loviService.scheduleNotification({
      contact: { number: appointment.patient_phone },
      template: "appointment_reminder_sms",
      datetime_sending: calculateReminderTime(appointment.datetime, -2),
      variables: { /* те же переменные */ }
    });
  }
}

E-commerce

Подтверждения заказов:

async function sendOrderVoiceConfirmation(order) {
  await loviService.sendVoiceNotification({
    contact: { number: order.customer_phone },
    template: "order_voice_confirmation",
    variables: {
      name: order.customer_name,
      order_number: order.id,
      total: formatCurrency(order.total),
      delivery_date: formatDate(order.delivery_date),
      items: order.items.map(item => item.name).join(", ")
    }
  });
}

⚙️ Расширенные Конфигурации

Интерактивность

Интерактивные звонки:

await loviService.sendInteractiveVoiceNotification({
  contact: { number: "34666033135" },
  script: [
    {
      type: "speak",
      text": "Нажмите 1 для подтверждения, 2 для переноса, 3 для отмены"
    },
    {
      type: "gather",
      num_digits: 1,
      timeout: 10,
      on_gather: {
        "1": { action: "confirm_appointment" },
        "2": { action: "reschedule_appointment" },
        "3": { action: "cancel_appointment" }
      }
    }
  ]
});

Callback и Webhook

Конфигурация callback:

await loviService.sendVoiceNotification({
  contact: { number: "34666033135" },
  message: "Подтверждение встречи",
  webhook: {
    url: "https://api.myapp.com/voice-callback",
    events: ["answered", "completed", "failed"],
    method: "POST"
  }
});

📊 Анализ и Оптимизация

Метрики Голоса

Статистика производительности:

const voiceStats = await loviService.getVoiceStatistics({
  start_date: "2024-12-01",
  end_date: "2024-12-31"
});

// Результат:
// {
//   "total_calls": 1250,
//   "answered_calls": 980,
//   "average_duration": 24,
//   "answer_rate": 78.4,
//   "cost_per_call": 0.08
// }

Оптимизация Качества

Тест качества голоса:

const qualityTest = await loviService.testVoiceQuality({
  message: "Это тест качества голоса",
  voices: ["ru-RU-Standard-A", "ru-RU-Wavenet-A", "ru-RU-Neural2-A"],
  language: "ru-RU"
});

// Результат: сравнение качества и предпочтений

🚨 Ограничения и Безопасность

Технические Ограничения

Длина сообщения: Макс 5000 символов
Длительность звонка: Макс 10 минут
Скорость звонков: 10 одновременных звонков на аккаунт
Поддерживаемые номера: Только верифицированные номера

Соображения Безопасности

Конфиденциальность данных:

// Обеспечить шифрование голосовых данных
const encryptedMessage = encryptSensitiveData(message);

// Использовать HTTPS для вебхуков
const webhookConfig = {
  url: "https://secure-api.myapp.com/voice-webhook",
  headers: {
    "Authorization": `Bearer ${secureToken}`,
    "Content-Type": "application/json"
  }
};

Соответствие GDPR:

Получать явное согласие перед звонками
Предоставлять четкие опции opt-out
Записывать все голосовые взаимодействия
Удалять записи после периода хранения

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

Оптимизация голосовых скриптов:

// ✅ Эффективный скрипт
"Привет Иван. Ваша встреча подтверждена на завтра в 10:00 в Центральной клинике. Ждем вас. Спасибо."

// ❌ Скрипт, которого следует избегать
"Эм, эй, это автоматическое сообщение от Центральной клиники о том, что у вас встреча завтра в десять утра, так что если вы сможете прийти, было бы здорово, спасибо и до свидания."

Обработка ошибок:

try {
  await loviService.sendVoiceNotification(voiceData);
} catch (error) {
  if (error.code === 'INVALID_PHONE_NUMBER') {
    await logInvalidNumber(voiceData.contact.number);
  } else if (error.code === 'VOICE_SYNTHESIS_FAILED') {
    await fallbackToTextMessage(voiceData);
  }
}

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

API уведомлений WhatsApp Планирование и Управление Часовыми Поясами

​Введение

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

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

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

​Заголовки

​Тело Запроса

​Структура с вложенными объектами (unflatten=false или опущено)

​Структура с плоскими переменными (unflatten=true)

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

​Опциональные Параметры

​Ответ с Ошибкой

​🎵 Конфигурация Голоса

​Доступные Голоса

​Расширенные Конфигурации Голоса

​📋 Голосовые Шаблоны

​Создание Голосового Шаблона

​Использование Голосовых Шаблонов

​⏰ Планирование Голосовых Уведомлений

​Немедленная Отправка

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

​📞 Управление Звонками

​Статусы Звонков

​Мониторинг Звонков

​🎯 Примеры Использования

​Здравоохранение

​E-commerce

​⚙️ Расширенные Конфигурации

​Интерактивность

​Callback и Webhook

​📊 Анализ и Оптимизация

​Метрики Голоса

​Оптимизация Качества

​🚨 Ограничения и Безопасность

​Технические Ограничения

​Соображения Безопасности

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