> ## 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. # Voice-Benachrichtigungs-API > Offizielle Dokumentation zur Verwendung der Lovi Voice-API zum Senden automatischer Sprachanrufe ## Einführung Voice-Benachrichtigungen ermöglichen es, Kunden über automatisierte Telefonanrufe zu erreichen, wenn WhatsApp nicht verfügbar ist oder bevorzugt wird. Dieser Endpunkt ermöglicht es Ihnen, Sprachanrufe mit KI-Agenten an Ihre Kontakte zu senden und bietet eine personalisierte Spracherfahrung. ## 📞 Voice-Benachrichtigung senden Um eine Voice-Benachrichtigung über die Lovi API zu senden, stellen Sie eine POST-Anfrage an den Voice-Endpunkt mit den erforderlichen Parametern und der Authentifizierung. > **Methode**: POST **Format**: JSON ### Endpunkt ``` POST https://cloud.lovi.ai/functions/v1/notify/voice?access_key={YOUR_ACCESS_KEY} ``` ### Abfrageparameter | Parameter | Erforderlich | Beschreibung | | ------------ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `access_key` | Ja | Ihr eindeutiger API-Zugriffsschlüssel. | | `unflatten` | Nein | Wenn auf `true` gesetzt, muss der Body flache Variablen enthalten (keine verschachtelten Objekte). Wenn auf `false` gesetzt oder weggelassen, kann der Body verschachtelte Objekte enthalten. | **Beispiel-URL:** ``` POST https://cloud.lovi.ai/functions/v1/notify/voice?access_key=your-api-key&unflatten=true ``` ### Header | Schlüssel | Wert | Erforderlich | Beschreibung | | ------------ | ---------------- | ------------ | ------------------------------------------------- | | Content-Type | application/json | Ja | Gibt an, dass der Anfragetext im JSON-Format ist. | **Hinweis**: Die Authentifizierung wird über den `access_key`-Parameter in der URL behandelt, nicht über Header. ### Anfragetext Der Anfragetext enthält die Voice-Benachrichtigungsdetails. #### Struktur mit verschachtelten Objekten (unflatten=false oder weggelassen) ```json theme={null} { "contact": { "number": "34666033135", "first_name": "Hans", "last_name": "Müller", "email": "hans@email.com", "specialty": "Krankenpflegeassistent", "client_source": "Hauptwebsite" }, "recipient_id": "34911670470", "agent_id": "uuid-sprach-agent", "notification_type": "marketing", "campaign_name": "Info-Call Q4", "name_event": "info-krankenpflege-kurs", "datetime_sending": "2024-12-25T09:00:00", "timezone": "Europe/Berlin" } ``` #### Struktur mit flachen Variablen (unflatten=true) ```json theme={null} { "contact.number": "34666033135", "contact.first_name": "Hans", "contact.last_name": "Müller", "contact.email": "hans@email.com", "contact.specialty": "Krankenpflegeassistent", "client_source": "Hauptwebsite", "recipient_id": "34911670470", "agent_id": "uuid-sprach-agent", "notification_type": "marketing", "campaign_name": "Info-Call Q4", "name_event": "info-krankenpflege-kurs", "datetime_sending": "2024-12-25T09:00:00", "timezone": "Europe/Berlin" } ``` ### Erforderliche Parameter | Parameter | Typ | Beschreibung | Beispiel | | ------------------- | ------ | ------------------------------------------ | -------------------------------- | | `contact.number` | String | Telefonnummer des Empfängers (nur Ziffern) | `"34666033135"` | | `recipient_id` | String | ID oder Telefonnummer des Empfängers | `"34911670470"` | | `agent_id` | String | Eindeutige Kennung des Sprachagenten | `"uuid-sprach-agent"` | | `notification_type` | String | Typ für Analytik | `"marketing"`, `"transactional"` | | `campaign_name` | String | Kampagnenname-Kennung | `"Voice Campaign Q4"` | ### Optionale Parameter | Parameter | Typ | Beschreibung | Beispiel | Standard | | -------------------- | -------- | ----------------------------------------- | ----------------------- | -------- | | `contact.first_name` | String | Vorname des Kontakts | `"Hans"` | null | | `contact.last_name` | String | Nachname des Kontakts | `"Müller"` | null | | `contact.email` | String | E-Mail des Kontakts | `"hans@email.com"` | null | | `datetime_sending` | DateTime | Datum/Zeit der Sendung im ISO 8601-Format | `"2024-12-25T09:00:00"` | Sofort | | `timezone` | String | Zeitzone | `"Europe/Berlin"` | UTC | | `name_event` | String | Ereignis-Kennung für Analytik | `"info-call-q4"` | null | ### API-Antwort #### Erfolgreiche Antwort ```json theme={null} { "success": true, "message": "Voice notification queued successfully", "notification_id": "uuid-voice-notification-123", "scheduled_time": "2024-12-25T09:00:00+01:00", "estimated_duration": 25 } ``` #### Fehlerantwort ```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" } ``` ## 🎵 Voice-Konfiguration ### Verfügbare Stimmen **Deutsch:** * `de-DE-Standard-A` (Weiblich, Standard) * `de-DE-Standard-B` (Männlich, Standard) * `de-DE-Wavenet-A` (Weiblich, hohe Qualität) * `de-DE-Wavenet-B` (Männlich, hohe Qualität) * `de-DE-Neural2-A` (Weiblich, neuronal) * `de-DE-Neural2-B` (Männlich, neuronal) ### Erweiterte Voice-Konfigurationen **Voice-Personalisierung:** ```javascript theme={null} await loviService.sendVoiceNotification({ contact: { number: "34666033135" }, message: "Willkommen bei unserem Kundenservice", voice_config: { voice: "de-DE-Wavenet-A", speaking_rate: 1.0, // Sprechgeschwindigkeit: 0.25 - 4.0 pitch: 0.0, // Tonhöhe: -20.0 - 20.0 volume_gain_db: 0.0 // Lautstärke: -96.0 - 16.0 } }); ``` ## 📋 Voice-Templates ### Voice-Template erstellen **Einfaches Template:** ```json theme={null} { "name": "order_ready_voice", "language": "de-DE", "content": "Hallo {{name}}, Ihre Bestellung Nummer {{order_id}} ist zur Abholung bereit bei {{store_location}}", "voice": "de-DE-Standard-A", "variables": ["name", "order_id", "store_location"] } ``` **Template mit Pausen und Intonation:** ```json theme={null} { "name": "appointment_reminder_voice", "language": "de-DE", "content": "Terminerinnerung. Hallo {{name}}. Ihr Termin bei {{doctor}} ist für {{date}} um {{time}} geplant. Wir erwarten Sie bei {{clinic}}.", "voice": "de-DE-Wavenet-A", "variables": ["name", "doctor", "date", "time", "clinic"] } ``` ### Voice-Templates verwenden **Mit Template senden:** ```javascript theme={null} await loviService.sendVoiceNotification({ contact: { number: "34666033135" }, template: "appointment_reminder_voice", variables: { name: "Hans Müller", doctor: "Dr. Schmidt", date: "15 Dezember", time: "10:30", clinic: "Zentralklinik" } }); ``` ## ⏰ Voice-Benachrichtigungen planen ### Sofortige Sendung **Basisanruf:** ```javascript theme={null} await loviService.sendVoiceNotification({ contact: { number: "34666033135" }, message: "Hallo Hans, Ihr Termin ist für morgen um 10:00 bestätigt", voice: "de-DE-Standard-A", language: "de-DE" }); ``` ### Geplante Sendung **Einfache Planung:** ```javascript theme={null} await loviService.scheduleVoiceNotification({ contact: { number: "34666033135" }, message: "Erinnerung: Termin morgen um 9:00", datetime_sending: "2024-12-24T20:00:00Z", // Am Vorabend voice: "de-DE-Standard-A" }); ``` ## 📞 Anrufverwaltung ### Anrufstatus | Status | Beschreibung | | ----------- | ------------------------------- | | `queued` | In Warteschlange für Sendung | | `ringing` | Klingelt | | `answered` | Vom Empfänger beantwortet | | `completed` | Anruf erfolgreich abgeschlossen | | `busy` | Leitung besetzt | | `no_answer` | Keine Antwort | | `failed` | Anruf fehlgeschlagen | ### Anruf-Monitoring **Anrufstatus:** ```javascript theme={null} const callStatus = await loviService.getVoiceCallStatus(callId); // Ergebnis: { status: "completed", duration: 25, cost: 0.05 } ``` **Anrufberichte:** ```javascript theme={null} const report = await loviService.getVoiceCallReport({ start_date: "2024-12-01", end_date: "2024-12-31", status: "completed" }); // Ergebnis: Statistiken über abgeschlossene Anrufe ``` ## 🎯 Anwendungsfälle ### Gesundheitswesen **Terminerinnerungen:** ```javascript theme={null} async function scheduleMedicalReminders(appointments) { for (const appointment of appointments) { // Anruf 24 Stunden vorher 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-Follow-up falls Anruf nicht beantwortet wird await loviService.scheduleNotification({ contact: { number: appointment.patient_phone }, template: "appointment_reminder_sms", datetime_sending: calculateReminderTime(appointment.datetime, -2), variables: { /* gleiche Variablen */ } }); } } ``` ### E-Commerce **Bestellbestätigungen:** ```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(", ") } }); } ``` ## ⚙️ Erweiterte Konfigurationen ### Interaktivität **Interaktive Anrufe:** ```javascript theme={null} await loviService.sendInteractiveVoiceNotification({ contact: { number: "34666033135" }, script: [ { type: "speak", text": "Drücken Sie 1 um zu bestätigen, 2 um zu verschieben, 3 um abzusagen" }, { type: "gather", num_digits: 1, timeout: 10, on_gather: { "1": { action: "confirm_appointment" }, "2": { action: "reschedule_appointment" }, "3": { action: "cancel_appointment" } } } ] }); ``` ### Callback und Webhook **Callback-Konfiguration:** ```javascript theme={null} await loviService.sendVoiceNotification({ contact: { number: "34666033135" }, message: "Terminbestätigung", webhook: { url: "https://api.myapp.com/voice-callback", events: ["answered", "completed", "failed"], method: "POST" } }); ``` ## 📊 Analyse und Optimierung ### Voice-Metriken **Leistungsstatistiken:** ```javascript theme={null} const voiceStats = await loviService.getVoiceStatistics({ start_date: "2024-12-01", end_date: "2024-12-31" }); // Ergebnis: // { // "total_calls": 1250, // "answered_calls": 980, // "average_duration": 24, // "answer_rate": 78.4, // "cost_per_call": 0.08 // } ``` ### Qualitätsoptimierung **Voice-Qualitätstest:** ```javascript theme={null} const qualityTest = await loviService.testVoiceQuality({ message: "Das ist ein Voice-Qualitätstest", voices: ["de-DE-Standard-A", "de-DE-Wavenet-A", "de-DE-Neural2-A"], language: "de-DE" }); // Ergebnis: Qualitätsvergleich und Präferenzen ``` ## 🚨 Einschränkungen und Sicherheit ### Technische Einschränkungen * **Nachrichtenlänge**: Max 5000 Zeichen * **Anrufdauer**: Max 10 Minuten * **Anrufgeschwindigkeit**: 10 gleichzeitige Anrufe pro Konto * **Unterstützte Nummern**: Nur verifizierte Nummern ### Sicherheitsüberlegungen **Datenschutz:** ```javascript theme={null} // Sicherstellen, dass Voice-Daten verschlüsselt sind const encryptedMessage = encryptSensitiveData(message); // HTTPS für Webhooks verwenden const webhookConfig = { url: "https://secure-api.myapp.com/voice-webhook", headers: { "Authorization": `Bearer ${secureToken}`, "Content-Type": "application/json" } }; ``` **DSGVO-Konformität:** * Vor Anrufen ausdrückliche Zustimmung einholen * Klare Opt-out-Optionen bereitstellen * Alle Voice-Interaktionen aufzeichnen * Aufzeichnungen nach Aufbewahrungszeitraum löschen ### Best Practices **Voice-Skript-Optimierung:** ```javascript theme={null} // ✅ Effektives Skript "Hallo Hans. Ihr Termin ist für morgen um 10:00 in der Zentralklinik bestätigt. Wir erwarten Sie. Vielen Dank." // ❌ Zu vermeidendes Skript "Äh, hallo, das ist eine automatische Nachricht von der Zentralklinik darüber, dass Sie einen Termin morgen um zehn Uhr haben, also wenn Sie kommen könnten, wäre das toll, danke und auf Wiederhören." ``` **Fehlerbehandlung:** ```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); } } ``` Voice-Benachrichtigungen bieten einen alternativen effektiven Kanal, wenn WhatsApp nicht ausreicht. Verwenden Sie sie strategisch, um die Kundenerfahrung und die Effektivität der Kommunikation zu verbessern.