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

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

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

{
  "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"
}

{
  "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"
}

### 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"
}

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"
});

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: { /* те же переменные */ }
    });
  }
}

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" }
      }
    }
  ]
});

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"
});

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

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

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

// ✅ Эффективный скрипт
"Привет Иван. Ваша встреча подтверждена на завтра в 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);
  }
}