WhatsApp Benachrichtigungen API - Lovi AI Documentation

Einführung

Dieser Abschnitt enthält die offizielle Dokumentation zur Nutzung der Lovi API mit WhatsApp über Postman. Er enthält detaillierte Anweisungen zum Einrichten und Testen von API-Anfragen für die WhatsApp-Integration, um eine reibungslose Kommunikation über die Plattform zu gewährleisten. Die Authentifizierung erfolgt über Tokens, die eine Basisauthentifizierung für die API-Dienste ermöglichen. Weitere Informationen zur Authentifizierung finden Sie auf der Seite Authentifizierung. Die Lovi API unterstützt WhatsApp-Benachrichtigungen mit Multimedia-Inhalten, dynamischen Platzhaltern, geplanter Zustellung und Integration von Konversationsabläufen.

Hauptfunktionen:

WhatsApp-Benachrichtigungen mit Multimedia-Unterstützung
Dynamische Inhaltspersonalisierung mit Platzhaltern
Geplante Nachrichtenzustellung mit Zeitzonen-Unterstützung
Integration von Konversationsabläufen
Zwei Datenstrukturformate (verschachtelt und flach)

📣 WhatsApp-Benachrichtigung senden

Um eine Benachrichtigung über die Lovi API zu senden, führen Sie eine POST-Anfrage an den Endpoint mit den erforderlichen Parametern und der Authentifizierung durch.

Methode: POST Format: JSON

Endpoint

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

Query-Parameter

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

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

Schlüssel	Wert	Erforderlich	Beschreibung
Content-Type	application/json	Ja	Gibt an, dass der Anfragebody im JSON-Format vorliegt.

Hinweis: Die Authentifizierung erfolgt über den Parameter access_key in der URL, nicht über Header.

📋 Anfrageparameter

Die API unterstützt zwei Datenstrukturformate, gesteuert durch den Parameter unflatten.

Erforderliche Parameter

Parameter	Typ	Beschreibung	Beispiel
`contact` ODER `contacts`	Object ODER Array	Wählen Sie eines: Einzelner Kontakt (Objekt) ODER Mehrere Kontakte (Array, max. 100)	Siehe unten
`language_template`	String	Sprachcode für das Template	`"es_ES"`, `"en_US"`
`name_template`	String	Name des genehmigten Templates	`"welcome_user"`
`recipient_id`	String	ID oder Telefonnummer des Empfängers	`"34666033135"`
`notification_type`	String	Typ für Analysen	`"marketing"`, `"transactional"`, `"utility"`
`campaign_name`	String	Kampagnenbezeichnung	`"Black Friday 2024"`

Wichtig: Sie müssen entweder contact (für einen einzelnen Empfänger) ODER contacts (für mehrere Empfänger) verwenden, aber NICHT beides.

Optionale Parameter

Parameter	Typ	Beschreibung	Verwendung	Beispiel
`contact.name`	String	Name des Kontakts zur Personalisierung	Für personalisierte Nachrichten	`"Juan Pérez"`
`contact.email`	String	E-Mail des Kontakts	Für zusätzliche Kontaktdaten	`"juan@email.com"`
`name_event`	String	Event zum Auslösen von Konversationsabläufen	Wenn Sie einen bestimmten Konversationsablauf starten möchten	`"intent-general-push"`
`datetime_sending`	DateTime	Geplante Zustellzeit (ISO 8601)	Wenn Sie die Nachricht für später planen möchten	`"2024-12-25T10:30:00"`
`timezone`	String	Zeitzone für geplante Zustellung	Bei Verwendung von `datetime_sending`	`"Europe/Madrid"`
`components_push.*`	Mixed	Template-Komponenten (Text, Medien)	Wenn das Template dynamische Inhalte erfordert	Siehe Komponentenabschnitt

👥 Einzelner vs. Mehrere Empfänger

Verwendung von `contact` - An eine Person senden

Verwenden Sie contact, wenn Sie eine Benachrichtigung an einen Empfänger senden möchten. Struktur:

{
  "contact": {
    "number": "34666033135",
    "name": "John",
    "email": "john@example.com"
  }
}

contact ist ein Objekt (keine Liste)
Erforderliches Feld: number
Optionale Felder: name, email und beliebige benutzerdefinierte Felder

Verwendung von `contacts` - An mehrere Personen senden (Massenversand)

Verwenden Sie contacts, wenn Sie dieselbe Benachrichtigung an mehrere Empfänger gleichzeitig senden möchten. Struktur:

{
  "contacts": [
    {
      "number": "34666033135",
      "name": "John"
    },
    {
      "number": "34777044246",
      "name": "Sarah"
    },
    {
      "number": "34888055357",
      "name": "Michael"
    }
  ]
}

contacts ist eine Liste/Array (kein einzelnes Objekt)
Maximum: 100 Kontakte pro Anfrage
Jeder Kontakt in der Liste muss eine number haben
Optionale Felder: name, email und beliebige benutzerdefinierte Felder

Wichtige Einschränkungen:

⚠️ unflatten=true kann nicht mit contacts verwendet werden - Massenversand funktioniert nur mit verschachtelter Struktur
⚠️ contact und contacts können nicht gleichzeitig verwendet werden - wählen Sie eines
⚠️ Die contacts-Liste darf nicht leer sein - muss mindestens 1 Kontakt enthalten

🔄 Datenstrukturformate

Die API unterstützt zwei Formate basierend auf dem Parameter unflatten:

Verschachtelte Struktur (unflatten=false oder weggelassen)

Wenn unflatten=false oder nicht angegeben, verwenden Sie verschachtelte Objekte:

{
  "contact": {
    "number": "34666033135",
    "name": "Juan Pérez",
    "email": "juan@email.com"
  },
  "components_push": {
    "header_text_0": "Welcome Message",
    "body_text_0": "Hello {{name}}",
    "body_text_1": "Your order is ready!",
    "footer_text_0": "Support Team"
  },
  "language_template": "es_ES",
  "name_template": "order_ready",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Order Notifications"
}

Flache Struktur (unflatten=true)

Wenn unflatten=true, müssen alle verschachtelten Objekte mit Punktnotation abgeflacht werden:

{
  "contact.number": "34666033135",
  "contact.name": "Juan Pérez",
  "contact.email": "juan@email.com",
  "components_push.header_text_0": "Welcome Message",
  "components_push.body_text_0": "Hello {{name}}",
  "components_push.body_text_1": "Your order is ready!",
  "components_push.footer_text_0": "Support Team",
  "language_template": "es_ES",
  "name_template": "order_ready",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Order Notifications"
}

Wann welches Format verwenden

Verschachtelte Struktur (unflatten=false): Empfohlen für bessere Lesbarkeit und wenn Ihr System verschachtelte Objekte unterstützt
Flache Struktur (unflatten=true): Verwenden, wenn Ihr System keine verschachtelten Objekte unterstützt oder eine flache Datenstruktur erfordert

🎨 Komponenten & Multimedia

WICHTIG: Komponenten, die Sie dynamisch senden können, sind NUR diejenigen, die vom Template-Komponenten-Endpoint zurückgegeben werden. Die Struktur variiert je nachdem, ob das Template Variablen oder Medien hat.

Regeln für Komponentennamen

Header-Medien: header_image, header_video, header_document (KEINE Suffixnummer)
Body-Variablen: body_text_0, body_text_1, body_text_2, etc. (mit Indexnummer für jeden {"{1}"}, {"{2}"}, {"{3}"} Platzhalter)
Footer und Buttons: Sind STATISCH in der Template-Definition und KÖNNEN NICHT dynamisch gesendet werden

So erfahren Sie, welche Komponenten zu senden sind

Rufen Sie zuerst den Template-Komponenten-Endpoint auf:

GET /notify/template/components?access_key={key}&template={template_id}

Die API gibt nur die Komponenten zurück, die Sie bereitstellen müssen:

{
  "status": "OK",
  "components": ["header_image", "body_text_0", "body_text_1"]
}

Senden Sie NUR diese Komponenten in Ihrer Benachrichtigungsanfrage

Komponententypen nach Position

Header-Komponenten (nur Medien)

WICHTIG: Nur EINE Header-Komponente pro Template. Header-Text ist STATISCH im Template.

Typ	Komponentenname	Beschreibung	Beispielwert	Spezifikationen
`image`	`header_image`	Header-Bild-URL	`"https://example.com/image.jpg"`	JPG, PNG, GIF - Max. 5MB
`video`	`header_video`	Header-Video-URL	`"https://example.com/video.mp4"`	MP4, AVI, MOV - Max. 16MB, 30s
`document`	`header_document`	Header-Dokument-URL	`"https://example.com/doc.pdf"`	PDF, DOC, XLS, PPT - Max. 100MB

Hinweis: header_text ist KEINE dynamische Komponente. Header-Text wird im Template definiert und kann nicht geändert werden.

Body-Komponenten (nur Variablen)

Body-Text mit Platzhaltern erfordert Variablen in der Reihenfolge: {"{1}"}, {"{2}"}, {"{3}"}, etc.

Komponentenname	Beschreibung	Entspricht Template-Platzhalter
`body_text_0`	Erste Variable im Body	`{"{1}"}`
`body_text_1`	Zweite Variable im Body	`{"{2}"}`
`body_text_2`	Dritte Variable im Body	`{"{3}"}`
`body_text_N`	N-te Variable im Body	`{"{N}"}`

Beispiel-Template: “Hallo {"{1}"}, Ihr Kurs {"{2}"} ist bereit”

body_text_0: Wert für {"{1}"} (z.B. “Maria”)
body_text_1: Wert für {"{2}"} (z.B. “JavaScript”)

⚠️ Footer ist STATISCH - wird im Template definiert und kann nicht pro Nachricht geändert werden.

Button-Komponenten

WICHTIG: Die meisten Buttons sind STATISCH im Template. URL-Buttons mit Variablen KÖNNEN jedoch dynamisch sein.

Komponentenname	Beschreibung	Wann sie erscheint
`buttons_url_0`	URL für ersten URL-Button mit Variable `{"{1}"}`	Wenn das Template einen URL-Button mit `{"{1}"}` Platzhalter hat
`buttons_url_1`	URL für zweiten URL-Button mit Variable `{"{2}"}`	Wenn das Template mehrere URL-Buttons mit Variablen hat

Beispiel-Template-Button: "url": "https://example.com/{"{1}"}"

Das Template definiert das URL-Muster mit Platzhalter
Sie geben den Wert für {"{1}"} über buttons_url_0 an

Hinweis: Schnellantwort-Buttons sind immer statisch und können nicht pro Nachricht geändert werden.

Komponentenbeispiele

Beispiel 1: Template mit Bild-Header (Verschachtelte Struktur)

{
  "components_push": {
    "header_image": "https://cdn.example.com/promo.jpg"
  }
}

Beispiel 2: Template mit Body-Variablen (Verschachtelte Struktur)

{
  "components_push": {
    "body_text_0": "María",
    "body_text_1": "JavaScript Advanced Course"
  }
}

Beispiel 3: Template mit Bild und Variablen (Flache Struktur)

{
  "components_push.header_image": "https://cdn.example.com/promo.jpg",
  "components_push.body_text_0": "María",
  "components_push.body_text_1": "JavaScript Advanced Course"
}

🧩 Template-Variablen (Body-Text)

KRITISCH: Variablen in WhatsApp-Templates verwenden positionelle Platzhalter wie {"{1}"}, {"{2}"}, {"{3}"}, NICHT benannte Variablen wie {"{name}"}.

Wie Template-Variablen funktionieren

WhatsApp-Templates definieren Variablen als nummerierte Platzhalter im Template-Body-Text:

Template-Text: “Hallo {"{1}"}, Ihr Kurs {"{2}"} ist bereit”
{"{1}"} entspricht body_text_0
{"{2}"} entspricht body_text_1

Variablenzuweisung

Sie geben die Werte für diese nummerierten Platzhalter im components_push-Objekt an:

{
  "components_push": {
    "body_text_0": "María",
    "body_text_1": "JavaScript Advanced Course"
  }
}

Ergebnis: “Hallo María, Ihr Kurs JavaScript Advanced Course ist bereit”

Wichtige Regeln

Positionsreihenfolge wichtig: body_text_0 = {"{1}"}, body_text_1 = {"{2}"}, etc.
Direkte Werte: Geben Sie den tatsächlichen Wert an, nicht die {"{variable}"}-Syntax
Alle Variablen erforderlich: Müssen Werte für alle {"{N}"}-Platzhalter im Template angeben
Kein Mischen: Kann Variablen nicht mit statischem Text in components_push kombinieren

✅ Gültige Beispiele

Template: “Hallo {"{1}"}, Ihre Bestellung {"{2}"} ist bereit”

{
  "contact": {
    "name": "María",
    "order_id": "ORD-12345"
  },
  "components_push": {
    "body_text_0": "María",
    "body_text_1": "ORD-12345"
  }
}

Sie können auch Kontaktfelder direkt verwenden:

{
  "contact": {
    "name": "María",
    "order_id": "ORD-12345"
  },
  "components_push": {
    "body_text_0": "{{name}}",
    "body_text_1": "{{order_id}}"
  }
}

❌ Ungültige Beispiele

{
  "components_push": {
    "body_text_0": "Hello María", // ❌ Fügen Sie keinen Template-Text hinzu, nur den Wert
    "body_text_1": "{1}" // ❌ Verwenden Sie nicht {1}, geben Sie den tatsächlichen Wert an
  }
}

Variablenauflösung

Das System löst {"{variable}"}-Referenzen in components_push auf, indem es sucht:

Zuerst im contact-Objekt
Dann in Parametern auf Root-Ebene

{
  "contact": {
    "name": "María",
    "email": "maria@example.com"
  },
  "order_id": "ORD-12345",
  "components_push": {
    "body_text_0": "{{name}}", // Aufgelöst aus contact.name → "María"
    "body_text_1": "{{order_id}}" // Aufgelöst aus Root order_id → "ORD-12345"
  }
}

⏰ Planung & Konversationsabläufe

Sofortige Zustellung (Standard)

Wenn datetime_sending nicht angegeben ist, wird die Nachricht sofort gesendet:

{
  "contact": { "number": "34666033135" },
  "language_template": "es_ES",
  "name_template": "welcome_user",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Welcome Campaign"
}

Geplante Zustellung

Verwenden Sie datetime_sending und timezone, um Nachrichten zu planen: Verschachtelte Struktur:

{
  "contact": { "number": "34666033135" },
  "language_template": "es_ES",
  "name_template": "welcome_user",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Welcome Campaign",
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Madrid"
}

Flache Struktur:

{
  "contact.number": "34666033135",
  "language_template": "es_ES",
  "name_template": "welcome_user",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Welcome Campaign",
  "datetime_sending": "2024-12-25T10:30:00",
  "timezone": "Europe/Madrid"
}

Integration von Konversationsabläufen

Verwenden Sie name_event, um bestimmte Konversationsabläufe auszulösen:

{
  "contact": { "number": "34666033135" },
  "language_template": "es_ES",
  "name_template": "course_info",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Course Enrollment",
  "name_event": "info-course-nursing"
}

📋 Vollständige Beispiele

Beispiel 1: Einzelner Empfänger mit Body-Variablen

Senden an EINE Person mit contact Template: “Hallo {"{1}"}, vielen Dank für Ihr Interesse an {"{2}"}!” Anfrage:

{
  "contact": {
    "number": "34666033135",
    "customer_name": "Sarah"
  },
  "components_push": {
    "body_text_0": "{{customer_name}}",
    "body_text_1": "our Premium Membership"
  },
  "language_template": "en",
  "name_template": "interest_confirmation",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Membership Campaign 2024"
}

Antwort:

{
  "success": true,
  "message": "Registration successful",
  "notification_id": "uuid-notification-123"
}

Beispiel 1B: Mehrere Empfänger (Massenversand)

Senden an MEHRERE Personen mit contacts Template: “Hallo {"{1}"}, vielen Dank für Ihr Interesse an {"{2}"}!” Anfrage:

{
  "contacts": [
    {
      "number": "34666033135",
      "customer_name": "Sarah"
    },
    {
      "number": "34777044246",
      "customer_name": "John"
    },
    {
      "number": "34888055357",
      "customer_name": "Michael"
    }
  ],
  "components_push": {
    "body_text_0": "{{customer_name}}",
    "body_text_1": "our Premium Membership"
  },
  "language_template": "en",
  "name_template": "interest_confirmation",
  "recipient_id": "bulk_campaign",
  "notification_type": "marketing",
  "campaign_name": "Membership Campaign 2024"
}

Antwort:

{
  "success": true,
  "message": "Processing completed",
  "total": 3,
  "processed": 3,
  "failed": 0,
  "errors": []
}

Wenn einige Kontakte fehlschlagen:

{
  "success": true,
  "message": "Processing completed",
  "total": 3,
  "processed": 2,
  "failed": 1,
  "errors": [
    {
      "contact": { "number": "34888055357", "customer_name": "Michael" },
      "reason": "Invalid phone number format"
    }
  ]
}

Beispiel 2: Template mit Bild-Header

Template-Komponenten: ["header_image"] URL:

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

Verschachtelte Struktur:

{
  "contact": {
    "number": "34666033135",
    "customer_name": "Robert",
    "email": "robert@example.com"
  },
  "components_push": {
    "header_image": "https://cdn.example.com/seasonal-promotion.jpg"
  },
  "language_template": "en",
  "name_template": "seasonal_offer",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Holiday Sale 2024",
  "datetime_sending": "2024-12-24T09:00:00",
  "timezone": "Europe/Madrid"
}

Hinweis: Body, Footer und Buttons sind im Template statisch und können nicht geändert werden.

Beispiel 3: Template mit PDF-Dokument

Template-Komponenten: ["header_document"] URL:

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

Flache Struktur:

{
  "contact.number": "34666033135",
  "contact.customer_name": "Jennifer",
  "contact.email": "jennifer@example.com",
  "components_push.header_document": "https://files.example.com/statement-2024.pdf",
  "language_template": "en",
  "name_template": "document_delivery",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Monthly Statements"
}

Beispiel 4: Auslösung eines Konversationsablaufs

Verschachtelte Struktur:

{
  "contact": {
    "number": "34666033135",
    "first_name": "Laura",
    "last_name": "Martínez",
    "course_interest": "Web Development"
  },
  "language_template": "en_US",
  "name_template": "course_inquiry",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Course Enrollment Q1",
  "name_event": "course-web-development-info",
  "datetime_sending": "2024-12-26T10:00:00",
  "timezone": "Europe/Madrid"
}

📊 Antwortcodes

Erfolgreiche Antwort (200 OK)

Sofortiger Versand:

{
  "success": true,
  "message": "Notification queued successfully",
  "notification_id": "uuid-notification-123"
}

Geplanter Versand:

{
  "success": true,
  "message": "Notification scheduled successfully",
  "notification_id": "uuid-notification-456",
  "scheduled_time": "2024-12-25T10:30:00Z"
}

Fehlerantworten

400 Bad Request - Ungültige Parameter

{
  "error": "validation_failed",
  "message": "Required field missing",
  "details": {
    "field": "contact.number",
    "reason": "This field is required"
  }
}

401 Unauthorized - Ungültiger Zugriffsschlüssel

{
  "error": "unauthorized",
  "message": "Invalid or expired access key"
}

404 Not Found - Template nicht gefunden

{
  "error": "template_not_found",
  "message": "Template 'welcome_user' not found or not approved"
}

422 Unprocessable Entity - Geschäftslogikfehler

{
  "error": "template_not_approved",
  "message": "Template is not in approved status",
  "details": {
    "template_name": "pending_template",
    "current_status": "pending"
  }
}

429 Too Many Requests - Anfragelimit

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again in 60 seconds",
  "retry_after": 60
}

🔧 Bewährte Praktiken

Datenstruktur

Bevorzugen Sie die verschachtelte Struktur (unflatten=false) für bessere Lesbarkeit
Verwenden Sie die flache Struktur (unflatten=true) nur wenn Ihr System es erfordert
Validieren Sie die Struktur vor dem Senden von Anfragen

Medienrichtlinien

Verwenden Sie HTTPS-URLs für alle Mediendateien
Optimieren Sie Dateigrößen für schnellere Zustellung
Verwenden Sie öffentliche URLs ohne Authentifizierungsanforderungen
Testen Sie Medien-URLs vor dem Versand, um die Erreichbarkeit sicherzustellen

Planung

Geben Sie die Zeitzone an bei Verwendung von datetime_sending
Validieren Sie zukünftige Daten vor der Planung
Berücksichtigen Sie Geschäftszeiten für besseres Engagement
Testen Sie die Planung in der Entwicklungsumgebung

Platzhalter

Verwenden Sie aussagekräftige Variablennamen, die zu Ihren Daten passen
Testen Sie die Variablenersetzung vor der Produktion
Halten Sie eine Variable pro Feld ein, um Fehler zu vermeiden
Stellen Sie Fallback-Werte in Ihrer Anwendungslogik bereit

Leistung

Bündeln Sie mehrere Benachrichtigungen wenn möglich
Cachen Sie Template-Informationen, um API-Aufrufe zu reduzieren
Überwachen Sie Anfragelimits und implementieren Sie Backoff-Strategien
Verwenden Sie Connection-Pooling für bessere Leistung

🚨 Häufige Fehler & Lösungen

Kontakt-/Kontakte-Validierungsfehler

Fehler: Fehlende Kontaktinformationen

Problem: Anfrage enthält weder contact noch contacts

{
  "error": "validation_failed",
  "message": "Missing required field: 'contact' or 'contacts'"
}

Lösung: Sie müssen entweder contact (für eine Person) ODER contacts (für mehrere Personen) angeben

Fehler: Gleichzeitige Verwendung von Contact und Contacts

Problem: Anfrage enthält sowohl contact als auch contacts gleichzeitig

{
  "error": "validation_failed",
  "message": "Cannot use both 'contact' and 'contacts' simultaneously"
}

Lösung: Wählen Sie nur eines - verwenden Sie contact für einzelne Empfänger oder contacts für mehrere Empfänger

Fehler: Contact ist eine Liste statt eines Objekts

Problem: contact als Liste [...] statt als Objekt {...} gesendet

{
  "error": "validation_failed",
  "message": "'contact' must be an object, not an array"
}

Lösung: Für einen einzelnen Empfänger verwenden Sie contact als Objekt:

{
  "contact": {
    "number": "34666033135",
    "name": "John"
  }
}

Fehler: Contacts ist keine Liste

Problem: contacts als Objekt {...} statt als Liste [...] gesendet

{
  "error": "validation_failed",
  "message": "'contacts' must be an array, not an object"
}

Lösung: Für mehrere Empfänger verwenden Sie contacts als Liste:

{
  "contacts": [
    { "number": "34666033135", "name": "John" },
    { "number": "34777044246", "name": "Sarah" }
  ]
}

Fehler: Leere Kontaktliste

Problem: contacts als leere Liste [] gesendet

{
  "error": "validation_failed",
  "message": "'contacts' array cannot be empty"
}

Lösung: Fügen Sie mindestens einen Kontakt in die Liste ein

Fehler: Zu viele Kontakte

Problem: Mehr als 100 Kontakte in der contacts-Liste gesendet

{
  "error": "validation_failed",
  "message": "Maximum 100 contacts allowed per request. Received: 150"
}

Lösung: Teilen Sie Ihre Kontakte in mehrere Anfragen mit maximal 100 Kontakten auf

Fehler: Unflatten mit Contacts

Problem: unflatten=true mit contacts (Massenversand) verwendet

{
  "error": "validation_failed",
  "message": "Parameter 'unflatten' is incompatible with 'contacts' array"
}

Lösung: Massenversand mit contacts funktioniert nur mit verschachtelter Struktur. Entfernen Sie unflatten=true oder verwenden Sie unflatten=false

Strukturkonflikt

Problem: Vermischung von verschachtelten und flachen Strukturen Lösung: Wählen Sie ein Format konsistent basierend auf dem unflatten-Parameter

Template nicht gefunden

Problem: Verwendung eines nicht existierenden oder nicht genehmigten Templates Lösung: Überprüfen Sie den Template-Namen und den Genehmigungsstatus mithilfe der Template-Management-Endpoints

Ungültiges Telefonnummernformat

Problem: ’+’ oder Leerzeichen in der Telefonnummer enthalten Lösung: Verwenden Sie das saubere internationale Format ohne Symbole (z.B. 34666033135)

Fehler bei Komponentennamen

Problem: Verwendung falscher Komponentennamen wie header_image_0 statt header_image Lösung: Überprüfen Sie immer zuerst die Template-Komponenten mit dem /notify/template/components Endpoint

Fehler bei Variablenpositionen

Problem: Falsche Zuordnung zwischen Template-Platzhaltern und body_text-Komponenten Lösung: Denken Sie daran: {"{1}"} = body_text_0, {"{2}"} = body_text_1, etc.

Änderung statischer Komponenten

Problem: Versuch, Footer, Buttons oder Header-Text dynamisch zu senden Lösung: Diese Komponenten sind im Template statisch. Senden Sie nur Komponenten, die vom Template-Komponenten-Endpoint zurückgegeben werden

Planungsfehler

Problem: Vergangene Daten oder ungültige Zeitzone Lösung: Verwenden Sie zukünftige Daten im ISO 8601-Format mit gültigen IANA-Zeitzonencodes

🔬 Template-Beispiele

Diese Beispiele zeigen verschiedene Arten von Template-Strukturen.

Beispiel 1: Einfaches Nur-Text-Template

Von der API zurückgegebene Komponenten: [] (leer - keine dynamischen Komponenten)

{
  "contact": {
    "number": "34666033135"
  },
  "language_template": "en",
  "name_template": "welcome_message",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Welcome Campaign"
}

Hinweis: Kein components_push erforderlich, da das Template keine dynamischen Komponenten hat.

Beispiel 2: Template mit Body-Variablen

Template-Body: “Hallo {"{1}"}, Ihr {"{2}"} ist bereit!” Von der API zurückgegebene Komponenten: ["body_text_0", "body_text_1"]

{
  "contact": {
    "number": "34666033135",
    "customer_name": "John",
    "product_name": "Premium Package"
  },
  "components_push": {
    "body_text_0": "{{customer_name}}",
    "body_text_1": "{{product_name}}"
  },
  "language_template": "en",
  "name_template": "order_ready",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Order Notifications"
}

Ergebnis: “Hallo John, Ihr Premium Package ist bereit!”

Beispiel 3: Template mit Bild-Header

Von der API zurückgegebene Komponenten: ["header_image"]

{
  "contact": {
    "number": "34666033135"
  },
  "components_push": {
    "header_image": "https://example.com/promotional-banner.jpg"
  },
  "language_template": "en",
  "name_template": "promo_with_image",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Holiday Sale"
}

Hinweis: Body, Footer und Buttons sind im Template statisch.

Beispiel 4: Template mit Video-Header

Von der API zurückgegebene Komponenten: ["header_video"]

{
  "contact": {
    "number": "34666033135"
  },
  "components_push": {
    "header_video": "https://example.com/product-demo.mp4"
  },
  "language_template": "en",
  "name_template": "video_announcement",
  "recipient_id": "34666033135",
  "notification_type": "marketing",
  "campaign_name": "Product Launch"
}

Beispiel 5: Template mit PDF-Dokument

Von der API zurückgegebene Komponenten: ["header_document"]

{
  "contact": {
    "number": "34666033135",
    "customer_name": "Jane Smith"
  },
  "components_push": {
    "header_document": "https://example.com/invoice-12345.pdf"
  },
  "language_template": "en",
  "name_template": "invoice_delivery",
  "recipient_id": "34666033135",
  "notification_type": "transactional",
  "campaign_name": "Monthly Invoices"
}

Beispiel 6: Template mit Header-Text und Body-Variable

Header: “Wichtiger Hinweis” (statischer Text im Template) Body: “Hallo {"{1}"}, willkommen auf unserer Plattform!” Von der API zurückgegebene Komponenten: ["body_text_0"]

{
  "contact": {
    "number": "34666033135",
    "first_name": "Michael"
  },
  "components_push": {
    "body_text_0": "{{first_name}}"
  },
  "language_template": "en",
  "name_template": "welcome_with_header",
  "recipient_id": "34666033135",
  "notification_type": "utility",
  "campaign_name": "User Onboarding"
}

Ergebnis:

Header: “Wichtiger Hinweis”
Body: “Hallo Michael, willkommen auf unserer Plattform!”

Beispiel 7: Template mit dynamischem URL-Button

Body: Statischer Text Buttons:

URL-Button mit Variable: "url": "https://example.com/{"{1}"}" (dynamisch)
Schnellantwort-Button: “Support kontaktieren” (statisch) Von der API zurückgegebene Komponenten: ["buttons_url_0"]

{
  "contact": {
    "number": "34666033135",
    "customer_id": "12345"
  },
  "components_push": {
    "buttons_url_0": "https://example.com/profile/{{customer_id}}"
  },
  "language_template": "en",
  "name_template": "account_notification",
  "recipient_id": "34666033135",
  "notification_type": "utility",
  "campaign_name": "Account Updates"
}

Ergebnis: Der URL-Button verlinkt zu https://example.com/profile/12345 Hinweis: Die Variable in buttons_url_0 kann Kontaktfelder mit der {"{variable}"}-Syntax referenzieren, und das System löst sie vor dem Versand auf.

Kampagnenstatus abfragen

Nach dem Erstellen den Fortschritt per GET abfragen, per ID oder per Name. Derselbe Endpoint gilt für WhatsApp und Voice (POST /notify/voice). Es gibt kein notification_id. Status braucht keine Extra-Permission; jeder gültige Key der Firma. Create braucht whatsapp_notifications am Key. Status braucht keine Extra-Permission. Max. 100 Kontakte. Kein HTTP-Rate-Limit, keine Pagination. Bei contacts ist message "Processing completed" plus Zähler. Host: https://cloud.lovi.ai/functions/v1/…. app.lovi.ai/functions ist nicht diese API.

GET https://cloud.lovi.ai/functions/v1/notify/status?access_key={YOUR_ACCESS_KEY}&campaign_id={CAMPAIGN_ID}
GET https://cloud.lovi.ai/functions/v1/notify/status?access_key={YOUR_ACCESS_KEY}&campaign_name={CAMPAIGN_NAME}

Parameter	Pflicht	Beschreibung
`access_key`	Ja	Gültiger Key. Nur Kampagnen derselben Firma.
`campaign_id`	Eins von beiden	UUID = `inquiry_set_id`. Nur dieser Batch.
`campaign_name`	Eins von beiden	Exakter Name. Mehrere Kampagnen mit gleichem Namen werden summiert. Bei beiden gewinnt `campaign_id`.
`failed_limit`	Nein	> 0 fügt `failed_list` hinzu (Fehlschläge einzeln). Max. 500 pro Seite.
`failed_offset`	Nein	Offset für `failed_list` (`100`, `200`…).

Große Versände werden oft in Batches mit gleichem Namen erstellt (z. B. 4 × F001): per Name kommen die Summen, campaigns listet jeden Batch. Wird ein Name an verschiedenen Tagen wiederverwendet, wird ebenfalls summiert — dann per campaign_id abfragen.

{
  "campaign_id": "d891b9b4-2f79-45a0-bc99-9a2922d4f713",
  "campaign_ids": [
    "d891b9b4-2f79-45a0-bc99-9a2922d4f713",
    "5c1e7a20-8b3f-4d6e-9a12-3f4b5c6d7e8f"
  ],
  "name": "F001",
  "status": "completed",
  "general_failure": false,
  "created_at": "2026-10-27T17:34:25.943296",
  "campaigns": [
    {
      "campaign_id": "d891b9b4-2f79-45a0-bc99-9a2922d4f713",
      "status": "completed",
      "count_total": 3000,
      "alert_message": null,
      "created_at": "2026-10-27T17:34:25.943296"
    },
    {
      "campaign_id": "5c1e7a20-8b3f-4d6e-9a12-3f4b5c6d7e8f",
      "status": "completed",
      "count_total": 1143,
      "alert_message": null,
      "created_at": "2026-10-27T17:41:02.118734"
    }
  ],
  "total_recipients": 4143,
  "sent": 3010,
  "failed": 1130,
  "pending": 3,
  "responded": 21,
  "by_status": {
    "read": 1400,
    "delivered": 1100,
    "sent": 510,
    "failed": 1130,
    "processed": 3
  },
  "failed_reasons": [
    { "status": "failed", "code": "131026", "title": "Message undeliverable", "count": 520 },
    { "status": "failed", "code": "131049", "title": "This message was not delivered to maintain healthy ecosystem engagement.", "count": 480 },
    { "status": "failed", "code": "131050", "title": "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business", "count": 95 },
    { "status": "failed", "code": "duplicate", "title": "duplicate", "count": 35 }
  ]
}

Feld	Bedeutung
`campaign_ids`	IDs aller Batches, nach Erstellung.
`status`	`pending`, `processing`, `ready`, `completed`, `failed`; per Name `mixed`, wenn Batches abweichen.
`general_failure`	`true`, wenn ein Batch `failed` ist.
`campaigns`	Pro Batch: `campaign_id`, `status`, `count_total`, `alert_message`, `created_at`.
`sent`	Empfänger in `delivered`, `read`, `sent`, `completed` oder `done`.
`failed`	`failed`, `warning`, `busy`, `no-answer` oder `voicemail`.
`pending`	Alle anderen.
`responded`	Personen (distincte Chats), die geantwortet haben.
`by_status`	Zählung nach Originalstatus.
`failed_reasons`	Fehlschläge nach Grund (`status`, `code`, `title`, `count`). `code`: Meta-Fehlercode (z. B. `131026`, `131049`, `131050`), SIP-Code bei Voice oder Verwerfungsgrund vor dem Versand (`duplicate`, `invalid_number`, `invalid_format`).

GET https://cloud.lovi.ai/functions/v1/notify/status?access_key={YOUR_ACCESS_KEY}&campaign_name={CAMPAIGN_NAME}&failed_limit=100&failed_offset=0

Mit failed_limit kommen zusätzlich failed_list und failed_offset. Nächste Seite: failed_offset um failed_limit erhöhen; leere Liste = Ende.

{
  "failed_list": [
    {
      "inquiry_id": "0b6f3c2e-1d4a-4f8b-9c7e-2a5d6e7f8a9b",
      "campaign_id": "d891b9b4-2f79-45a0-bc99-9a2922d4f713",
      "number": "34600000000",
      "status": "failed",
      "code": "131026",
      "title": "Message undeliverable",
      "sent_at": "2026-10-27T17:35:10.412000"
    }
  ],
  "failed_offset": 0
}

Fehlerkörper: { "success": false, "message": "…" }. 400 fehlende Parameter oder campaign_id keine UUID. 404 ungültiger Key (nicht 401) oder fremde/unbekannte Kampagne. 500 intern.

📚 Verwandte Dokumentation

Authentifizierung - Wie Sie Zugriffstokens und API-Schlüssel erhalten
Sprachbenachrichtigungen - Automatisierte Sprachanrufe senden
Template-Verwaltung - WhatsApp-Templates erstellen und verwalten
Planung - Erweiterte Planung und Zeitzonenverwaltung
Fehlerbehandlung - Vollständige Fehlercodes und Behandlungsstrategien
Bewährte Praktiken - Sicherheits- und Leistungsrichtlinien

​Einführung

​Hauptfunktionen:

​📣 WhatsApp-Benachrichtigung senden

​Endpoint

​Query-Parameter

​Header

​📋 Anfrageparameter

​Erforderliche Parameter

​Optionale Parameter

​👥 Einzelner vs. Mehrere Empfänger

​Verwendung von contact - An eine Person senden

​Verwendung von contacts - An mehrere Personen senden (Massenversand)

​🔄 Datenstrukturformate

​Verschachtelte Struktur (unflatten=false oder weggelassen)

​Flache Struktur (unflatten=true)

​Wann welches Format verwenden

​🎨 Komponenten & Multimedia

​Regeln für Komponentennamen

​So erfahren Sie, welche Komponenten zu senden sind

​Komponententypen nach Position

​Header-Komponenten (nur Medien)

​Body-Komponenten (nur Variablen)

​Footer-Komponenten

​Button-Komponenten

​Komponentenbeispiele

​Beispiel 1: Template mit Bild-Header (Verschachtelte Struktur)

​Beispiel 2: Template mit Body-Variablen (Verschachtelte Struktur)

​Beispiel 3: Template mit Bild und Variablen (Flache Struktur)

​🧩 Template-Variablen (Body-Text)

​Wie Template-Variablen funktionieren

​Variablenzuweisung

​Wichtige Regeln

​✅ Gültige Beispiele

​❌ Ungültige Beispiele

​Variablenauflösung

​⏰ Planung & Konversationsabläufe

​Sofortige Zustellung (Standard)

​Geplante Zustellung

​Integration von Konversationsabläufen

​📋 Vollständige Beispiele

​Beispiel 1: Einzelner Empfänger mit Body-Variablen

​Beispiel 1B: Mehrere Empfänger (Massenversand)

​Beispiel 2: Template mit Bild-Header

​Beispiel 3: Template mit PDF-Dokument

​Beispiel 4: Auslösung eines Konversationsablaufs

​📊 Antwortcodes

​Erfolgreiche Antwort (200 OK)

​Fehlerantworten

​400 Bad Request - Ungültige Parameter

​401 Unauthorized - Ungültiger Zugriffsschlüssel

​404 Not Found - Template nicht gefunden

​422 Unprocessable Entity - Geschäftslogikfehler

​429 Too Many Requests - Anfragelimit

​🔧 Bewährte Praktiken

​Datenstruktur

​Medienrichtlinien

​Planung

​Platzhalter

​Leistung

​🚨 Häufige Fehler & Lösungen

​Kontakt-/Kontakte-Validierungsfehler

​Fehler: Fehlende Kontaktinformationen

​Fehler: Gleichzeitige Verwendung von Contact und Contacts

​Fehler: Contact ist eine Liste statt eines Objekts

​Fehler: Contacts ist keine Liste

​Fehler: Leere Kontaktliste

​Fehler: Zu viele Kontakte

​Fehler: Unflatten mit Contacts

​Strukturkonflikt

​Template nicht gefunden

​Ungültiges Telefonnummernformat

​Fehler bei Komponentennamen

​Fehler bei Variablenpositionen

​Änderung statischer Komponenten

​Planungsfehler

​🔬 Template-Beispiele

​Beispiel 1: Einfaches Nur-Text-Template

​Beispiel 2: Template mit Body-Variablen

​Beispiel 3: Template mit Bild-Header

​Beispiel 4: Template mit Video-Header

Einführung

Hauptfunktionen:

📣 WhatsApp-Benachrichtigung senden

Endpoint

Query-Parameter

Header

📋 Anfrageparameter

Erforderliche Parameter

Optionale Parameter

👥 Einzelner vs. Mehrere Empfänger

Verwendung von `contact` - An eine Person senden

Verwendung von `contacts` - An mehrere Personen senden (Massenversand)

🔄 Datenstrukturformate

Verschachtelte Struktur (unflatten=false oder weggelassen)

Flache Struktur (unflatten=true)

Wann welches Format verwenden

🎨 Komponenten & Multimedia

Regeln für Komponentennamen

So erfahren Sie, welche Komponenten zu senden sind

Komponententypen nach Position

Header-Komponenten (nur Medien)

Body-Komponenten (nur Variablen)

Footer-Komponenten

Button-Komponenten

Komponentenbeispiele

Beispiel 1: Template mit Bild-Header (Verschachtelte Struktur)

Beispiel 2: Template mit Body-Variablen (Verschachtelte Struktur)

Beispiel 3: Template mit Bild und Variablen (Flache Struktur)

🧩 Template-Variablen (Body-Text)

Wie Template-Variablen funktionieren

Variablenzuweisung

Wichtige Regeln

✅ Gültige Beispiele

❌ Ungültige Beispiele

Variablenauflösung

⏰ Planung & Konversationsabläufe

Sofortige Zustellung (Standard)

Geplante Zustellung

Integration von Konversationsabläufen

📋 Vollständige Beispiele

Beispiel 1: Einzelner Empfänger mit Body-Variablen

Beispiel 1B: Mehrere Empfänger (Massenversand)

Beispiel 2: Template mit Bild-Header

Beispiel 3: Template mit PDF-Dokument

Beispiel 4: Auslösung eines Konversationsablaufs

📊 Antwortcodes

Erfolgreiche Antwort (200 OK)

Fehlerantworten

400 Bad Request - Ungültige Parameter

401 Unauthorized - Ungültiger Zugriffsschlüssel

404 Not Found - Template nicht gefunden

422 Unprocessable Entity - Geschäftslogikfehler

429 Too Many Requests - Anfragelimit

🔧 Bewährte Praktiken

Datenstruktur

Medienrichtlinien

Planung

Platzhalter

Leistung

🚨 Häufige Fehler & Lösungen

Kontakt-/Kontakte-Validierungsfehler

Fehler: Fehlende Kontaktinformationen

Fehler: Gleichzeitige Verwendung von Contact und Contacts

Fehler: Contact ist eine Liste statt eines Objekts

Fehler: Contacts ist keine Liste

Fehler: Leere Kontaktliste

Fehler: Zu viele Kontakte

Fehler: Unflatten mit Contacts

Strukturkonflikt

Template nicht gefunden

Ungültiges Telefonnummernformat

Fehler bei Komponentennamen

Fehler bei Variablenpositionen

Änderung statischer Komponenten

Planungsfehler

🔬 Template-Beispiele

Beispiel 1: Einfaches Nur-Text-Template

Beispiel 2: Template mit Body-Variablen

Beispiel 3: Template mit Bild-Header

Beispiel 4: Template mit Video-Header