> ## 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 Голосовых Уведомлений > Официальная документация по использованию Voice API Lovi для отправки автоматизированных голосовых вызовов ## Введение Голосовые уведомления позволяют достигать клиентов через автоматизированные телефонные звонки, когда 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 или опущено) ```json theme={null} { "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) ```json theme={null} { "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"` | ### Опциональные Параметры \| Параметр | Тип | Описание | Пример | По умолчанию | (Показаны первые 100 строк из 145. Используйте offset=101 для продолжения.) ```` ### API-Ответ #### Успешный Ответ ```json { "success": true, "message": "Voice notification queued successfully", "notification_id": "uuid-voice-notification-123", "estimated_duration": 25 } ```` #### Ответ с Ошибкой ```json theme={null} { "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` (Мужской, нейронный) ### Расширенные Конфигурации Голоса **Персонализация голоса:** ```javascript theme={null} 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 } }); ``` ## 📋 Голосовые Шаблоны ### Создание Голосового Шаблона **Простой шаблон:** ```json theme={null} { "name": "order_ready_voice", "language": "ru-RU", "content": "Привет {{name}}, ваш заказ номер {{order_id}} готов к выдаче в {{store_location}}", "voice": "ru-RU-Standard-A", "variables": ["name", "order_id", "store_location"] } ``` **Шаблон с паузами и интонацией:** ```json theme={null} { "name": "appointment_reminder_voice", "language": "ru-RU", "content": "Напоминание о встрече. Привет {{name}}. Ваша встреча с {{doctor}} запланирована на {{date}} в {{time}}. Ждем вас в {{clinic}}.", "voice": "ru-RU-Wavenet-A", "variables": ["name", "doctor", "date", "time", "clinic"] } ``` ### Использование Голосовых Шаблонов **Отправка с шаблоном:** ```javascript theme={null} await loviService.sendVoiceNotification({ contact: { number: "34666033135" }, template: "appointment_reminder_voice", variables: { name: "Иван Петров", doctor: "Доктор Сидоров", date: "15 декабря", time: "10:30", clinic: "Центральная клиника" } }); ``` ## ⏰ Планирование Голосовых Уведомлений ### Немедленная Отправка **Базовый звонок:** ```javascript theme={null} await loviService.sendVoiceNotification({ contact: { number: "34666033135" }, message: "Привет Иван, ваша встреча подтверждена на завтра в 10:00", voice: "ru-RU-Standard-A", language: "ru-RU" }); ``` ### Запланированная Отправка **Простое планирование:** ```javascript theme={null} 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` | Звонок не удался | ### Мониторинг Звонков **Статус звонка:** ```javascript theme={null} const callStatus = await loviService.getVoiceCallStatus(callId); // Результат: { status: "completed", duration: 25, cost: 0.05 } ``` **Отчеты о звонках:** ```javascript theme={null} const report = await loviService.getVoiceCallReport({ start_date: "2024-12-01", end_date: "2024-12-31", status: "completed" }); // Результат: статистика завершенных звонков ``` ## 🎯 Примеры Использования ### Здравоохранение **Напоминания о встречах:** ```javascript theme={null} 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 **Подтверждения заказов:** ```javascript theme={null} 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(", ") } }); } ``` ## ⚙️ Расширенные Конфигурации ### Интерактивность **Интерактивные звонки:** ```javascript theme={null} 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:** ```javascript theme={null} await loviService.sendVoiceNotification({ contact: { number: "34666033135" }, message: "Подтверждение встречи", webhook: { url: "https://api.myapp.com/voice-callback", events: ["answered", "completed", "failed"], method: "POST" } }); ``` ## 📊 Анализ и Оптимизация ### Метрики Голоса **Статистика производительности:** ```javascript theme={null} 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 // } ``` ### Оптимизация Качества **Тест качества голоса:** ```javascript theme={null} 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 одновременных звонков на аккаунт * **Поддерживаемые номера**: Только верифицированные номера ### Соображения Безопасности **Конфиденциальность данных:** ```javascript theme={null} // Обеспечить шифрование голосовых данных 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 * Записывать все голосовые взаимодействия * Удалять записи после периода хранения ### Лучшие Практики **Оптимизация голосовых скриптов:** ```javascript theme={null} // ✅ Эффективный скрипт "Привет Иван. Ваша встреча подтверждена на завтра в 10:00 в Центральной клинике. Ждем вас. Спасибо." // ❌ Скрипт, которого следует избегать "Эм, эй, это автоматическое сообщение от Центральной клиники о том, что у вас встреча завтра в десять утра, так что если вы сможете прийти, было бы здорово, спасибо и до свидания." ``` **Обработка ошибок:** ```javascript theme={null} 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 недостаточно. Используйте их стратегически, чтобы улучшить пользовательский опыт и эффективность коммуникаций.