> ## 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.

# WhatsApp Benachrichtigungen API

> Offizielle Dokumentation zur Nutzung der Lovi API mit WhatsApp über Postman

## 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](./authentication).

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
```

### Header

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

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

1. Rufen Sie zuerst den Template-Komponenten-Endpoint auf:

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

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

   ```json theme={null}
   {
     "status": "OK",
     "components": ["header_image", "body_text_0", "body_text_1"]
   }
   ```

3. 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-Komponenten

⚠️ **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)

```json theme={null}
{
  "components_push": {
    "header_image": "https://cdn.example.com/promo.jpg"
  }
}
```

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

```json theme={null}
{
  "components_push": {
    "body_text_0": "María",
    "body_text_1": "JavaScript Advanced Course"
  }
}
```

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

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

### ✅ Gültige Beispiele

**Template**: "Hallo `{"{1}"}`, Ihre Bestellung `{"{2}"}` ist bereit"

```json theme={null}
{
  "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**:

```json theme={null}
{
  "contact": {
    "name": "María",
    "order_id": "ORD-12345"
  },
  "components_push": {
    "body_text_0": "{{name}}",
    "body_text_1": "{{order_id}}"
  }
}
```

### ❌ Ungültige Beispiele

```json theme={null}
{
  "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:

1. Zuerst im `contact`-Objekt
2. Dann in Parametern auf Root-Ebene

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "success": true,
  "message": "Processing completed",
  "total": 3,
  "processed": 3,
  "failed": 0,
  "errors": []
}
```

**Wenn einige Kontakte fehlschlagen:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "success": true,
  "message": "Notification queued successfully",
  "notification_id": "uuid-notification-123"
}
```

**Geplanter Versand:**

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "validation_failed",
  "message": "Required field missing",
  "details": {
    "field": "contact.number",
    "reason": "This field is required"
  }
}
```

#### 401 Unauthorized - Ungültiger Zugriffsschlüssel

```json theme={null}
{
  "error": "unauthorized",
  "message": "Invalid or expired access key"
}
```

#### 404 Not Found - Template nicht gefunden

```json theme={null}
{
  "error": "template_not_found",
  "message": "Template 'welcome_user' not found or not approved"
}
```

#### 422 Unprocessable Entity - Geschäftslogikfehler

```json theme={null}
{
  "error": "template_not_approved",
  "message": "Template is not in approved status",
  "details": {
    "template_name": "pending_template",
    "current_status": "pending"
  }
}
```

#### 429 Too Many Requests - Anfragelimit

```json theme={null}
{
  "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`

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```json theme={null}
{
  "contact": {
    "number": "34666033135",
    "name": "John"
  }
}
```

***

#### Fehler: Contacts ist keine Liste

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

```json theme={null}
{
  "error": "validation_failed",
  "message": "'contacts' must be an array, not an object"
}
```

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

```json theme={null}
{
  "contacts": [
    { "number": "34666033135", "name": "John" },
    { "number": "34777044246", "name": "Sarah" }
  ]
}
```

***

#### Fehler: Leere Kontaktliste

**Problem**: `contacts` als leere Liste `[]` gesendet

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "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"]`

```json theme={null}
{
  "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"]`

```json theme={null}
{
  "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"]`

```json theme={null}
{
  "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"]`

```json theme={null}
{
  "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"]`

```json theme={null}
{
  "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"]`

```json theme={null}
{
  "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.

***

## 📚 Verwandte Dokumentation

* **[Authentifizierung](./authentication)** - Wie Sie Zugriffstokens und API-Schlüssel erhalten
* **[Sprachbenachrichtigungen](./voice_notifications)** - Automatisierte Sprachanrufe senden
* **[Template-Verwaltung](./template_management)** - WhatsApp-Templates erstellen und verwalten
* **[Planung](./scheduling)** - Erweiterte Planung und Zeitzonenverwaltung
* **[Fehlerbehandlung](./error_handling)** - Vollständige Fehlercodes und Behandlungsstrategien
* **[Bewährte Praktiken](./best_practices)** - Sicherheits- und Leistungsrichtlinien