Voice-Benachrichtigungs-API - Lovi AI Documentation

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

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)

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

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

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

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

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:

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

{
  "name": "appointment_reminder_voice",
  "language": "de-DE",
  "content": "Terminerinnerung. <break time=\"500ms\"/> Hallo {{name}}. <break time=\"300ms\"/> Ihr Termin bei {{doctor}} ist für {{date}} um {{time}} geplant. <break time=\"500ms\"/> Wir erwarten Sie bei {{clinic}}.",
  "voice": "de-DE-Wavenet-A",
  "variables": ["name", "doctor", "date", "time", "clinic"]
}

Voice-Templates verwenden

Mit Template senden:

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:

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:

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:

const callStatus = await loviService.getVoiceCallStatus(callId);
// Ergebnis: { status: "completed", duration: 25, cost: 0.05 }

Anrufberichte:

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:

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:

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:

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:

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:

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:

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:

// 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:

// ✅ 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:

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.

​Einführung

​📞 Voice-Benachrichtigung senden

​Endpunkt

​Abfrageparameter

​Header

​Anfragetext

​Struktur mit verschachtelten Objekten (unflatten=false oder weggelassen)

​Struktur mit flachen Variablen (unflatten=true)

​Erforderliche Parameter

​Optionale Parameter

​API-Antwort

​Erfolgreiche Antwort

​Fehlerantwort

​🎵 Voice-Konfiguration

​Verfügbare Stimmen

​Erweiterte Voice-Konfigurationen

​📋 Voice-Templates

​Voice-Template erstellen

​Voice-Templates verwenden

​⏰ Voice-Benachrichtigungen planen

​Sofortige Sendung

​Geplante Sendung

​📞 Anrufverwaltung

​Anrufstatus

​Anruf-Monitoring

​🎯 Anwendungsfälle

​Gesundheitswesen

​E-Commerce

​⚙️ Erweiterte Konfigurationen

​Interaktivität

​Callback und Webhook

​📊 Analyse und Optimierung

​Voice-Metriken

​Qualitätsoptimierung

​🚨 Einschränkungen und Sicherheit

​Technische Einschränkungen

​Sicherheitsüberlegungen

​Best Practices